Envio de Leads

Documentação da API de integração de Leads

As informações dos leads serão enviados via protocolo HTTP ou HTTPS com o verbo POST com payload em formato JSON para o endpoint especificado para o cliente.

Cada lead será enviado de forma individual, a medida que forem gerados na plataforma OLX, contendo os seguintes campos:

Parâmetro	Obrigatório	Descrição
source	Sim	Origem do lead. Valores possíveis: whatsapp, telefone, chat, financing (simulação de financiamento), olx (outras origens).
adId1	Não	Identificador do anúncio no software de gestão (integrador).
listId	Sim	Identificador do anúncio na OLX
linkAd	Sim	Link do anúncio na OLX
name	Sim	Nome do cliente que entrou em contato.
email	Sim	Email do cliente que entrou em contato.
phone	Não	Telefone do cliente que entrou em contato. Sequência numérica de até 13 caracteres. Telefones podem vir com ou sem DDD.
message	Sim	Mensagem enviada pelo cliente.
createdAt	Sim	Data e hora da geração do lead.
adsInfo2	Não	Informações adicionais de anúncios. Disponível apenas para algumas categorias.
buyerHistory	Não	Histórico de comportamento do comprador na plataforma OLX. Disponível quando o comprador possui histórico de interações.
externalId	Não	Identificador único do lead.

¹ Caso o campo adId for enviado vazio, significa que o anúncio do cliente foi inserido manualmente (diretamente no portal OLX) e não pela nossa API de integração de anúncios

² Para mais informações detalhadas de anúncio, consultar a documentação Envio de leads com informações detalhadas de anúncio

buyerHistory

Quando disponível, o campo buyerHistory contém informações comportamentais do comprador:

Campo	Tipo	Descrição
buyer.publicAccountId	String	Identificador público da conta do comprador
buyer.email	String	E-mail do comprador
buyer.fullName	String	Nome completo do comprador
buyer.nickname	String	Apelido do comprador na plataforma
buyer.interactingWithAds	Int	Quantidade de anúncios com os quais o comprador interagiu
buyer.firstInteractionDate	DateTime	Data da primeira interação do comprador na plataforma
buyer.regionOfInterest.region	String	Região de interesse do comprador
buyer.regionOfInterest.ddd	String	DDD da região de interesse
adToExchange.subject	String	Título do anúncio que o comprador tem para troca
adToExchange.price	Double	Preço do anúncio para troca
adToExchange.friendlyUrl	String	URL do anúncio para troca
adToExchange.listId	Long	ID do anúncio para troca na OLX
adToExchange.thumbnail	String	URL da imagem do anúncio para troca

Segue um exemplo de um JSON para um lead enviado:

{
  "source": "financing",
  "adId": "a1234",
  "listId": "12345689",
  "linkAd": "https://www.olx.com.br/vi/12345689",
  "name": "Nome do cliente",
  "email": "email.docliente@gmail.com",
  "phone": "2199999999",
  "message": "Olá, gostaria de saber mais informações sobre o anúncio a1234", 
  "createdAt": "2019-02-12T14:30:00.500Z",
  "adsInfo": {
    "category": 2020,
    "subject": "Harley Davidson",
    "body": "Harley Davidson fat boy carburada, frente cabeça de touro",
    "type": "sell",
    "price": "90000",
    "zipcode": "25964000",
    "regdate": "90000",
    "mileage": "43000",
    "carcolor": "1",
    "fuel": "1",
    "car_steering": "1",
    "exchange": "1",
    "owner": "1",
    "financial": "2|3|4",
    "financial_status": "1",
    "vehicle_brand": "28",
    "vehicle_model": "7",
    "vehicle_version": "2",
    "cubiccms": "21",
    "moto_features": "1|2|3|4|5|6|7|8|9"
  },
  "buyerHistory": {
    "buyer": {
      "publicAccountId": "9f962d02-a8f9-4d1b-9b3d-91f7f0d5d115",
      "email": "comprador@email.com",
      "fullName": "Nome Sobrenome",
      "nickname": "comprador_olx",
      "interactingWithAds": 42,
      "firstInteractionDate": "2024-03-20T10:30:00Z",
      "regionOfInterest": {
        "region": "Rio de Janeiro",
        "ddd": "21"
      }
    },
    "adToExchange": {
      "subject": "Honda Civic 2018",
      "price": 78500.0,
      "friendlyUrl": "https://www.olx.com.br/d/rio-de-janeiro-e-regiao/autos-e-pecas/carros-vans-e-utilitarios/honda-civic-2018-123456789",
      "listId": 123456789,
      "thumbnail": "https://img.olx.com.br/images/12/123456789.jpg"
    }
  },
  "externalId": "123jdanjkdna-danjndaada"
}

Nota: adToExchange representa apenas o primeiro anúncio de troca do comprador, quando existir.

Restrições atuais

Atualmente, a OLX só suporta envio de leads via integração para algumas de suas categorias:

Categoria	Subcategoria	Código da Categoria
Autos	Carros, vans e utilitários	2020
Autos	Motos	2060
Autos	Caminhões	2040

Status code

Nosso controle de entrega de leads será feito com base no status code do protocolo HTTP:

• 2XX: Indica que o lead foi recebido com sucesso.
• 3XX, 4XX ou 5XX: Indica que houve erro no recebimento do lead.

A OLX guardará a resposta da entrega do lead para eventual troubleshoot. A priori, a OLX não tem política de reenvio ou reprocessamento de leads que não forem recebidos.

É recomendável que seja enviada um responseId, para identificar o recebimento do lead e a resposta devolvida referente a esse lead recebido.

Timeout

As requisições para o endpoint estão configuradas com timeout de 5 segundos. Caso a requisição que demore mais que 5 segundos, será considerada ERRO.