Integrar lead na OLX

Como integrar com a OLX?

Se você ainda não está integrado com a OLX para recebimento de leads, deverá disponibilizar um endpoint para a OLX homologar a integração de leads.

A OLX requer que cada anunciante tenha um endpoint único. Recomendamos estruturas similares a essas:

• https://seudominio.com.br/olx/lead/TOKEN
• https://TOKEN.seudominio.com.br/olx/lead

O TOKEN, nestes exemplos, é o identificador do anunciante na base do sistema ou CRM que receberá o lead. Pode ser utilizado para identificar um determinado cliente da base.

Recomendamos essa estrutura especificamente para sistemas integrados que serão usados por mais do que um anunciante (isso normalmente acontece quando um sistema de mercado é contratado por diversos anunciantes ou quando um sistema é usado por um anunciante que tem filiais e quer manter controle desse contexto).

Autenticação oAuth no OLX

Para utilizar a configuração da URL de envio do leads, é necessário autenticar-se em nome de um usuário do OLX através do protocolo oAuth. A documentação da autenticação oAuth encontra-se aqui para conseguir o access_token.

Na autenticação, o sistema solicitante receberá o client_id e o client_secret que deverão ser usados na URL de conexão. Durante o fluxo oAuth será requisitado que o usuário dê permissão ao integrador para gerenciar seus anúncios na OLX. No handshake do oAuth, é requisitado também o scope que a aplicação-cliente necessitará. Para utilizar o sistema de integração de anúncios via API, é preciso o scope autoservice.

Atenção: o scope necessita ter autoservice, caso contrário a requisição será invalidada.

Criar uma configuração de lead

A URL usada para fazer a requisição é https://apps.olx.com.br/autoservice/v1/lead, método POST. Essa requisição deve conter o access_token de cada anunciante no header como: Authorization: Bearer <access_token>.

Exemplo de requisição usando o cURL:

curl -POST 'https://apps.olx.com.br/autoservice/v1/lead' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
  "url": "https://seudominio.com.br/olx/lead/de42f9b4-6fdb-4d65-a8b8-30648ffa3685"
  "token": "b2x4OnVuZGVmaW5lZA"
}'

Valores do Body:

Parâmetro	Valores	Obrigatório	Descrição
url	string	sim	URL que irá receber a requisição do lead
token	string	não	Valor de um token esperado pela sua aplicação para caso precise de uma credencial extra de segurança. Será enviado no Header como Authorization conforme descrito aqui

A URL https://seudominio.com.br/olx/lead/de42f9b4-6fdb-4d65-a8b8-30648ffa3685 é apenas um exemplo. Você deve substituí-la pela URL do seu endpoint único por cliente em que está sendo configurado para receber o lead.

Após a requisição ser processada com sucesso, você receberá uma resposta indicando que a configuração de lead foi criada. A resposta será semelhante a esta:

{
    "id": "154f10e7-2586-4699-be05-f3587ac7e4fe",
    "url": "https://seudominio.com.br/olx/lead/de42f9b4-6fdb-4d65-a8b8-30648ffa3685",
    "token": "b2x4OnVuZGVmaW5lZA"
}

O campo id é o identificador único da configuração de lead, que pode ser usado para consultar ou alterar a configuração no futuro.

Consultar configuração do lead

A URL usada para fazer a requisição é https://apps.olx.com.br/autoservice/v1/lead/:id, método GET. Essa requisição deve conter o access_token de cada anunciante no header como: Authorization: Bearer <access_token>.

Exemplo de requisição usando o cURL:

curl -L \
--url 'https://apps.olx.com.br/autoservice/v1/lead/154f10e7-2586-4699-be05-f3587ac7e4fe' \
--header 'Authorization: Bearer <access_token>'

A resposta será semelhante a esta:

{
    "id": "154f10e7-2586-4699-be05-f3587ac7e4fe",
    "url": "https://seudominio.com.br/olx/lead/de42f9b4-6fdb-4d65-a8b8-30648ffa3685",
    "token": "b2x4OnVuZGVmaW5lZA"
}

Alterar configuração de notificação

A URL usada para fazer a requisição é https://apps.olx.com.br/autoservice/v1/lead/:id, método PUT. Essa requisição deve conter o access_token de cada anunciante no header como: Authorization: Bearer <access_token>.

Exemplo de requisição usando o cURL:

curl -X PUT 'https://apps.olx.com.br/autoservice/v1/lead/154f10e7-2586-4699-be05-f3587ac7e4fe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
  "url": "https://seudominio.com.br/olx/lead/de42f9b4-6fdb-4d65-a8b8-30648ffa3685"
}'

A URL https://seudominio.com.br/olx/lead/de42f9b4-6fdb-4d65-a8b8-30648ffa3685 é apenas um exemplo. Você deve substituí-la pela URL do seu endpoint único por cliente em que está sendo configurado para receber o lead.

A resposta será semelhante a esta:

{
    "id": "154f10e7-2586-4699-be05-f3587ac7e4fe",
    "url": "https://seudominio.com.br/olx/lead/de42f9b4-6fdb-4d65-a8b8-30648ffa3685"
}

Excluir configuração de notificação

A URL usada para fazer a requisição é https://apps.olx.com.br/autoservice/v1/lead/:id, método DELETE. Essa requisição deve conter o access_token de cada anunciante no header como: Authorization: Bearer <access_token>.

Aqui está um exemplo de como fazer essa requisição usando o cURL:

curl -X DELETE 'https://apps.olx.com.br/autoservice/v1/lead/154f10e7-2586-4699-be05-f3587ac7e4fe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>'

Retorno com código de sucesso 204 No Content.

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

Status Code	Descrição	Motivo	Mensagem
401	Token inválido ou vazio	ACCESS_DENIED	Check the client authentication token
401	Configuração de Lead não usa formato OLX	UNAUTHORIZED	Lead configuration does not use OLX format
404	URL e configuração não encontrada	NOT_FOUND	Configurations not found
429	Requisição bloqueada por exceder a taxa máxima de requisições por minuto (detalhes aqui)	RATE_LIMIT	You have exceeded the X requests in Y seconds limit!
500	Erro interno inesperado	UNEXPECTED_INTERNAL_ERROR	Unexpected internal error. Try again later