Consulta de anúncios destacados

Consulta de anúncios destacados

A URL usada para fazer a requisição do arquivo JSON é https://apps.olx.com.br/autoupload/bump/ads?ad_ids=[{ad_id},{ad_id}], método GET. Essa requisição deve conter uma lista de até 10 identificadores de anúncios (separados por vírgula) e o access_token de cada anunciante no header como: Authorization: Bearer <access_token>.

O campo access_token pode ser obtido seguindo a documentação Autenticação na API olx.com.br.

Parâmetro	Valores	Obrigatório	Descrição
ad_id	array[string]	sim	Lista de até 10 identificadores de anúncios. Obs: se for enviada uma lista com mais de 10 identificadores, o 11º em diante será ignorado.
access_token	string	sim	Chave de acesso do anunciante

Se o anunciante possui anúncios destacados, a requisição retorna um status code 200 e um JSON no corpo da resposta com a estrutura abaixo, podendo vir uma lista com até 10 itens:

Retorno de sucesso esperado

Parâmetro	Valores	Obrigatório	Descrição
id	string	sim	Identificador do anúncio.
last_bumps	arrayOf[string (ISO Datetime)]	não	Últimas datas que o anúncio foi ao topo.
next_bumps	arrayOf[string (ISO Datetime)]	não	Próximas datas agendadas para a volta do anúncio ao topo (ou seja, para a reaplicação do destaque).
reason	string	não	Motivo do erro que ocorreu ao obter dados do anúncio específico.
message	string	não	Mensagem de erro que ocorreu ao obter dados do anúncio específico.

A quantidade de datas retornadas nos campos last_bumps e next_bumps, dependerá do plano contratado, podendo ser de 1 a 5.

Retorno de erro esperado

Caso ocorra algum erro ou o anunciante não possua plano profissional ativo, a consulta retorna um status code > 400 e um JSON com o motivo e a mensagem do erro.

Códigos e motivos de erros da requisição retornados

Status Code	Descrição	Motivo	Mensagem
400	Falta campo de authorization no header da requisição	BAD_REQUEST	Check the header field(s)
401	Token inválido	ACCESS_DENIED	Check the client authentication token
429	Rate Limit configurado quando o cliente fizer mais requisições por segundo do que deveria	RATE_LIMIT	You have exceeded the X requests in X seconds limit!
500	Erro interno inesperado	UNEXPECTED_INTERNAL_ERROR	Unexpected internal error. Try again later

Exemplos de retorno

Consulta de 4 anúncios em situações diferentes, conforme condições abaixo:

Anúncio	Condição do anúncio em relação a destaque
B124	Todos os detaques aplicados e destaque ativo, ou seja, no período de 7 dias a partir da aplicação do destaque.
D1234	2 datas de destaques ocorridas e 1 data ainda por ser aplicada e destaque ativo (no período de 7 dias a partir da aplicação do destaque).
S995	Sem destaque aplicado. Retornará Anúncio não encontrado.
E4567	Ocorreu uma indisponibilidade no momento da consulta deste anúncio. Por favor, tente mais tarde.

• Request

  curl "https://apps.olx.com.br/autoupload/bump/ads?ad_ids=B124,S995,D1234,E4567" -H "accept: application/json" -H "Content-Type: application/json" -H "authorization: Bearer {access_token}"
  

• Response

  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  
  [
      {
          "id": "B124",
          "lastBumps": ['2022-09-01 00:00:00.00000', '2022-09-03 00:00:00.00000', '2022-09-05 00:00:00.00000'],
      },
      {
          "id": "D1234",
          "lastBumps": ['2022-09-04 00:00:00.00000', '2022-09-06 00:00:00.00000'],
          "nextBump": ['2022-09-08 00:00:00.00000']
      },
      {
          "id": "S995",
          "reason": "NOT_FOUND",
          "message": "Ad not found."
      },
      {
          "id": "E4567",
          "reason": "UNPROCESSABLE_AD",
          "message": "I couldn't get information for this ad. Please try again later"
      }
  ]
  

---

Para uma requisição com access_token inválido:

• Request

  curl "https://apps.olx.com.br/autoupload/bump/ads?ad_ids=B124,S995,D1234,E4567" -H "accept: application/json" -H "Content-Type: application/json" -H "authorization: Bearer {access_token}"
  

• Response

  HTTP/1.1 401 
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  
  {
      "reason": "ACCESS_DENIED", 
      "message": "Check the client authentication token."
  }