Integração de Leads via Webhook

Visão geral

Esta documentação descreve o formato de payload, as regras de entrega e as validações necessárias para receber leads enviados pelo Grupo OLX.

O envio é feito por HTTPS POST para o endpoint homologado do Software/CRM. Cada lead é entregue em uma requisição separada, no formato JSON.

Importante

O status de recebimento é controlado apenas pelo código HTTP. O corpo da resposta não deve ser considerado.

Como funciona

• O Grupo OLX envia uma requisição HTTPS POST com Content-Type: application/json.
• Cada lead é enviado individualmente.
• Sucesso é definido por qualquer código HTTP da família 2xx.
• Respostas 3xx, 4xx ou 5xx são consideradas falhas.
• Se o lead não for processado com sucesso, há até 3 tentativas automáticas.
• Após 3 falhas, o lead é armazenado por até 14 dias para reenvio posterior.

Avisos

Qualquer código fora da família 2xx dispara retentativas. Sua aplicação deve ser idempotente e preparada para receber o mesmo lead mais de uma vez.

Entrega e retorno de status

Código	Significado
2xx	Lead recebido com sucesso.
3xx	Redirecionamento / falha.
4xx	Erro do cliente.
5xx	Erro do servidor.

Use apenas o código HTTP para definir o resultado da entrega. Não confie no conteúdo do corpo da resposta.

Exemplo de payload

{
  "leadOrigin": "Grupo OLX",
  "timestamp": "2017-10-23T15:50:30.619Z",
  "originLeadId": "59ee0fc6e4b043e1b2a6d863",
  "originListingId": "87027856",
  "clientListingId": "a40171",
  "name": "Nome Consumidor",
  "email": "nome.consumidor@email.com",
  "ddd": "11",
  "phone": "999999999",
  "phoneNumber": "11999999999",
  "message": "Olá, tenho interesse neste imóvel. Aguardo o contato. Obrigado. Lead gerado através do interesse do cliente por anúncios semelhantes. Sua opinião é muito importante para nós. Avalie a temperatura do lead e nos ajude a entregar leads mais quentes para seu negócio: https://feedback-lead.grupozap.com/integration/7e9d5492-aae4-416f-95f5-e1ae1c3536ce",
  "temperature": "Alta",
  "transactionType": "SELL",
  "extraData": {
    "leadCerto": true,
    "izi": "Visualize o histórico de mensagem do cliente com IZI: https://lead-conversation.grupozap.com/lead/59ee0fc6e4b043e1b2a6d863, para acessar a conversa utilize o codigo: DYvLUTJ9b09cM0zQ",
    "feedback": "Sua opinião é muito importante para nós. Avalie a temperatura do lead e nos ajude a entregar leads mais quentes para seu negócio: https://feedback-lead.grupozap.com/integration/7e9d5492-aae4-416f-95f5-e1ae1c3536ce",
    "leadType": "CONTACT_CHAT"
  }
}

Exemplo de payload (lead MCMV)

Exemplo completo de um payload recebido para um lead de simulação MCMV. Observe que originListingId e clientListingId não estão presentes e leadOrigin está definido como MCMV_OLX.

{
  "leadOrigin": "MCMV_OLX",
  "timestamp": "2026-07-10T10:15:30.000Z",
  "originLeadId": "mcmv-1234567890",
  "name": "João da Silva",
  "email": "joao.silva@example.com",
  "ddd": "11",
  "phone": "987654321",
  "message": "Simulação de financiamento MCMV realizada no portal.",
  "temperature": "Média",
  "transactionType": "SELL",
  "extraData": {
    "mcmv": {
      "sellerDocument": "12345678000190",
      "unitType": "APARTMENT",
      "propertyLocation": {
        "state": "SP",
        "city": "São Paulo"
      },
      "propertyValue": 250000,
      "subsidyRange": "FAIXA_1",
      "urgencyToBuy": "ALTA",
      "documentType": "CPF",
      "hasMinimumFgtsContribution": true,
      "downPayment": 20000,
      "estimatedFinancingAmount": 230000
    }
  }
}

Campos do payload

Campo	Tipo	Descrição	Observação
leadOrigin	string	Origem do lead.	Valores: Grupo OLX (leads de anúncio) ou MCMV_OLX (simulações no portal Minha Casa Minha Vida).
timestamp	string	Data e hora da criação do lead.	ISO 8601: 2017-10-23T15:50:30.619Z.
originLeadId	string	Identificador único do lead.	Use para evitar duplicidade; sempre presente.
originListingId	string	Identificador do anúncio no Grupo OLX.	Não presente para leads MCMV_OLX.
clientListingId	string	Identificador do anúncio no CRM do cliente.	Obrigatório para leads de anúncio; não presente para MCMV_OLX.
name	string	Nome do consumidor.
email	string	E-mail do consumidor.
ddd	string	Código de área do telefone.	Ex.: 11.
phone	string	Número do telefone.	Ex.: 999999999.
phoneNumber	string	Telefone completo (DDD + número).	Depreciado. Prefira ddd + phone.
message	string	Mensagem enviada pelo consumidor.	Pode trazer informações de canal, IZI ou sobre simulação MCMV.
temperature	string	Temperatura do lead.	Valores: Baixa, Média, Alta.
transactionType	string	Tipo de transação.	Valores: RENT, SELL.
extraData	object	Dados adicionais do lead.	Veja seção Campos de extraData.

Campos de extraData

Campo	Tipo	Descrição
leadCerto	boolean	Indica que o lead foi gerado por interesse em anúncios semelhantes.
izi	string	Texto com link e código de acesso à conversa da IZI.
feedback	string	Texto com link para avaliação da temperatura do lead.
leadType	string	Canal de origem do lead.
mcmv	object	Dados de leads gerados pela simulação do programa Minha Casa Minha Vida.

Campos de extraData.mcmv

Campo	Tipo	Descrição
sellerDocument	string	Documento de identificação do anunciante. Pode ser CPF (11 dígitos) ou CNPJ (14 dígitos). A validação do tipo deve ser feita pelo CRM pela quantidade de dígitos.
unitType	string	Tipo de unidade selecionada na simulação.
propertyLocation.state	string	Estado de preferência do imóvel.
propertyLocation.city	string	Cidade de preferência do imóvel.
propertyValue	number	Valor estimado do imóvel considerado na simulação.
subsidyRange	string	Faixa de subsídio do programa.
urgencyToBuy	string	Nível de urgência para compra.
documentType	string	Tipo de documento do lead.
hasMinimumFgtsContribution	boolean	Indica se há contribuição mínima do FGTS.
downPayment	number	Valor de entrada estimado.
estimatedFinancingAmount	number	Valor de financiamento estimado.

Canais de origem em leadType

• CLICK_SCHEDULE — agendamento.
• CLICK_WHATSAPP — WhatsApp.
• CONTACT_CHAT — chat.
• CONTACT_FORM — formulário.
• PHONE_VIEW — telefone.
• VISIT_REQUEST — visita.

Interpretação do campo message

O campo message pode trazer informações úteis sobre o canal ou a origem do lead.

• "Lead gerado através do interesse do cliente por anúncios semelhantes." → extraData.leadCerto = true
• "Visualize o histórico de mensagem do cliente com IZI: ..." → lead originado pela IZI.

Exemplos de trechos de mensagem

• "Gostaria de ter mais informações para alugar e comprar"
• "Você recebeu uma nova visualização de telefone"
• "Um novo contato foi estabelecido via WhatsApp"

Regras de validação

• clientListingId deve ser enviado em todas as requisições de anúncio; leads com leadOrigin: MCMV_OLX podem não conter esse campo.
• originLeadId deve ser usado para identificar leads duplicados.
• leadOrigin pode ser Grupo OLX (lead de anúncio) ou MCMV_OLX (lead de simulação MCMV); utilize esse valor para distinguir o tipo de lead.
• Apenas 2xx indica sucesso.

Avisos

Se clientListingId estiver ausente em um lead de anúncio, retorne 4xx para que o lead seja revisado e reprocessado posteriormente. Para leads com leadOrigin: MCMV_OLX, não retorne 4xx apenas por ausência de clientListingId, pois esses leads não estão vinculados a um anúncio.

Integrações específicas

Lead certo

O LeadCerto indica que o lead foi redistribuído para você porque o consumidor demonstrou interesse em um imóvel semelhante ao que você tem cadastrado.

• Campo: extraData.leadCerto
• Valor: true
• Significado: o contato foi gerado por interesse em imóveis parecidos.

Como funciona

• O LeadCerto conecta interesses de usuários a imóveis similares.
• Quando alguém demonstra interesse em um anúncio no Zap, Viva Real ou OLX, contatos podem ser encaminhados para anunciantes com ofertas compatíveis.

Condições importantes

• A pessoa interessada deve autorizar o recebimento de novos contatos.

Critérios de similaridade

O LeadCerto compara principais características do imóvel para encontrar bons correspondentes:

• tipo de transação (venda ou aluguel);
• tipo de imóvel (casa, apartamento, terreno, etc);
• região de localização;
• faixa de preço compatível;
• número de quartos;
• metragem do imóvel.

Quanto mais características coincidirem, maior a chance de você receber o lead.

IZI

• Campo: extraData.izi
• Conteúdo: texto com URL e código para acessar a conversa da IZI.

A IZI é uma ferramenta de inteligência artificial que automatiza o pré-atendimento de leads, mantendo o atendimento ativo 24 horas por dia, 7 dias por semana.

Ela responde dúvidas, reúne informações sobre imóveis e qualifica o contato antes do corretor assumir a conversa.

Vantagens da IZI

• Atendimento instantâneo pelo WhatsApp da imobiliária ou através do chat integrado no Canal Pro;
• Respostas geradas por IA;
• Coleta de informações úteis para agendamento de visitas.

Como funciona

• A IZI conversa com o lead inicialmente.
• O histórico e o resumo da interação ficam disponíveis no Canal Pro.
• Leads atendidos pela IZI são identificados no Gestor de Leads.

MCMV (Minha Casa Minha Vida)

• Campo: extraData.mcmv
• Conteúdo: objeto com os dados que o lead utilizou para realizar uma simulação para o programa Minha Casa Minha Vida no portal.

Leads de simulação do programa Minha Casa Minha Vida (MCMV) são diferentes dos leads tradicionais de anúncio: eles representam pessoas que fizeram uma simulação no portal do programa e não estão vinculadas a um anúncio específico.

• No objeto principal, leadOrigin terá o valor MCMV_OLX para distinguir esses leads.
• Em leads MCMV, os campos originListingId e clientListingId não estarão presentes.
• Os dados da simulação ficam em extraData.mcmv com a estrutura mostrada abaixo.

Exemplo de extraData.mcmv:

"mcmv": {
  "sellerDocument": "12345678000190",
  "unitType": "APARTMENT",
  "propertyLocation": {
    "state": "SP",
    "city": "São Paulo"
  },
  "propertyValue": 250000,
  "subsidyRange": "FAIXA_1",
  "urgencyToBuy": "ALTA",
  "documentType": "CPF",
  "hasMinimumFgtsContribution": true,
  "downPayment": 20000,
  "estimatedFinancingAmount": 230000
}

Observações:

• O campo sellerDocument identifica o anunciante e pode ser CPF (11 dígitos) ou CNPJ (14 dígitos). A validação do tipo deve ser feita pelo CRM pela quantidade de dígitos.
• Ao receber um lead com leadOrigin: MCMV_OLX, não espere clientListingId ou originListingId.
• Trate leads MCMV como leads de produto (simulação) e normalize o armazenamento conforme seu modelo de dados.

Feedback

• Campo: extraData.feedback
• Conteúdo: texto com link para avaliação de temperatura do lead.

Orientações contra duplicidade

Leads podem ser gerados por mais de um canal. Para evitar processamentos repetidos, compare sempre o campo originLeadId.

Imagem de referência

Integração via e-mail

Para cada lead gerado, além do envio aos CRMs, também é feito o disparo de um e-mail para os endereços de e-mail cadstrados no Canal Pro contendo os dados do lead e imóvel de interesse e os campos com informações nesse e-mail são identificados para que ferramentas de integração consigam capturar e processar esses leads.

Para guiar esse processo temos o seguinte mapeamento dos campos do e-mail:

E-mail de lead

Campos do email de lead

Cada campo do e-mail possui um atributo title que pode ser usado como seletor para extração dos dados.

#	Campo	Atributo title	Descrição
1	Nome do lead	lead-name	Nome do consumidor.
2	Telefone do lead	lead-phoneNumber	Telefone do consumidor.
3	E-mail do lead	lead-email	E-mail do consumidor.
4	Identificador do anúncio	listing-externalCode	Código do anúncio no CRM do cliente.
5	Bairro do anúncio	listing-neighborhood	Bairro do imóvel de interesse. Em leads LeadCerto, refere-se ao anúncio semelhante.
6	Endereço do anúncio	listing-address	Endereço do imóvel de interesse. Em leads LeadCerto, refere-se ao anúncio semelhante.
7	Valor do anúncio	listing-price	Valor do imóvel de interesse. Em leads LeadCerto, refere-se ao anúncio semelhante.

E-mail de lead Minha Casa Minha Vida

Campos do email de lead Minha Casa Minha Vida

Cada campo do e-mail possui um atributo title que pode ser usado como seletor para extração dos dados.

#	Campo	Atributo title	Descrição
1	Nome do lead	lead-name	Nome do consumidor.
2	E-mail do lead	lead-email	E-mail do consumidor.
3	Telefone do lead	lead-phone	Telefone do consumidor.
4	Valor do imóvel	property_value	Valor estimado do imóvel considerado na simulação.
5	Valor de entrada	down_payment	Valor de entrada estimado pelo consumidor.
6	Valor do financiamento	estimated_financing_amount	Valor de financiamento estimado na simulação.
7	Faixa de subsídio	subsidy_range	Faixa de subsídio do programa MCMV.

Exemplo de extração via seletor

// Lead padrão
document.querySelector('[title="lead-name"]').textContent;
document.querySelector('[title="lead-phoneNumber"]').textContent;
document.querySelector('[title="lead-email"]').textContent;
document.querySelector('[title="listing-externalCode"]').textContent;
document.querySelector('[title="listing-neighborhood"]').textContent;
document.querySelector('[title="listing-address"]').textContent;
document.querySelector('[title="listing-price"]').textContent;

// Lead MCMV
document.querySelector('[title="lead-name"]').textContent;
document.querySelector('[title="lead-email"]').textContent;
document.querySelector('[title="lead-phone"]').textContent;
document.querySelector('[title="property_value"]').textContent;
document.querySelector('[title="down_payment"]').textContent;
document.querySelector('[title="estimated_financing_amount"]').textContent;
document.querySelector('[title="subsidy_range"]').textContent;

Homologação

Após implementar a integração:

1. Valide seu endpoint
2. Envie as informações no formulário de homologação abaixo.

Se tiver dificuldade para acessar o formulário, utilize o link direto: https://docs.google.com/forms/d/e/1FAIpQLSd6WJ3xw-qoFzW2-6OvrEihTjurUwVsJYei-P4alae2S1yedQ/viewform

Suporte

Se tiver dúvidas, sugestões ou problemas, envie um e-mail para chamado.integracao@olxbr.com.

Exemplos de implementação

• Python
• NodeJS
• Java
• Go