# Integração Leads

Este documento contém as informações para que os Softwares/CRMs realizem as integrações com nossa API. Assim, o anunciante poderá receber os seus contatos(leads) em seu CRM.

Nosso sistema de integração de leads precisa de uma URL (endpoint) para enviar as informações do lead para os Softwares/CRMs homologados. Esta requisição será realizada via protocolo HTTP no verbo POST, no endpoint especificado passando um JSON como corpo do request.

# Exemplos de endpoints que poderão ser utilizados:

https://yourdomain.com.br/grupozap/lead/ID-DO-ANUNCIANTE
https://crm-ou-imobiliaria.com.br/grupozap/lead/123456

OU

https://ID-DO-ANUNCIANTE.yourdomain.com.br/grupozap/lead
https://imobiliariaxpto.crm.com.br/grupozap/lead

ID-DO-ANUNCIANTE é parte da URL que representa o identificador do anunciante no sistema que irá receber a requisição. É uma forma de identificação do cliente no Software/CRM.

Caso não tenha ou não queira especificar o ID-DO-ANUNCIANTE o endpoint poderá ser implementado sem este identificador.

# Exemplos

https://yourdomain.com.br/grupozap/lead

Utilizando um único endpoint, o Software/CRM deverá identificar o cliente pelo clientListingId , mais detalhes abaixo:

# Envio dos Leads

Os leads serão enviados via protocolo HTTP no verbo POST, passando um JSON com as informações do lead no endpoint especificado e homologado por nosso time.

O processo de integração será acionado para cada lead individualmente sempre que recebermos um contato do usuário. Nosso controle de sucesso de envio dos leads será feito através dos códigos de status (opens new window) do protocolo HTTP da seguinte forma:

2xx: indica que o Software/CRM recebeu o lead com sucesso e que ações adicionais não são necessárias. Qualquer código de status da família 200 terá esse efeito. 3xx, 4xx ou 5xx: indica que houve falha no processamento do lead por parte do Software/CRM.

Caso o endpoint do Software/CRM retorne qualquer código de status que não são da família 200, haverá retentativa automática no envio do lead. O reenvio será executado por 3 vezes e, caso não haja sucesso, ele será armazenado temporariamente por até 14 dias, podendo ser reenviado a pedido do Software/CRM.

O controle do status de recebimento dos leads será feito exclusivamente através dos códigos de status do protocolo HTTP. Qualquer informação enviada no corpo da resposta será totalmente ignorada!

Contrato JSON:

{
  "leadOrigin": "VivaReal",
  "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."
}

Onde:

  • leadOrigin: Identificador do contrato do anunciante (VivaReal, Zap, GrupoZap);
  • timestamp: Data e horário da criação do lead no formato ISO_LOCAL_DATE_TIME;
  • originLeadId: Identificador do lead do GrupoZap;
  • originListingId: Identificador do anúncio do GrupoZap;
  • clientListingId: Identificador do anúncio para o anunciante (ListingId);
  • name: Nome do consumidor que gerou o lead;
  • email: E-Mail do consumidor que gerou o lead;
  • ddd: DDD do telefone do consumidor que gerou o lead Ex:11;
  • phone: Telefone do consumidor que gerou o lead Ex:999999999;
  • phoneNumber: [deprecado] Telefone do consumidor que gerou o lead (DDD + Phone) Ex:11999999999;
  • message: Mensagem do consumidor que gerou o lead;

# Observações Importantes:

# clientListingId

O campo clientListingId é único identificador do anúncio/empreendimento conhecido pelo Software/CRM e GrupoZap, este identificador chega até nós via carga Feeds como código da listing (ListingId) ou customizado diretamente nos Software/CRM pelo cliente. Considere este identificador para realizar a devida associação do lead com o anúncio/empreendimento do cliente. Caso este identificador não estiver contido na requisição, deverá retornar o statusCode da família 400 (4xx) para ser analisado e reprocessado futuramente.

# Integração Inexistente

Quando um cliente deixa de usar um CRM que tem integração de leads ativa com o Grupo Zap, CRM poderá retornar StatusCode=404 na resposta da integração, desta forma, nosso sistema irá identificar integrações inexistentes e remover de nossos cadastros evitando futuras requisições.

# Timeout

A requisição POST para o endpoint está configurada com timeout de 15 segundos, ou seja, qualquer requisição que demorar mais que 15 segundos será considerada ERRO sendo reenviadas de acordo com nossas regras de retentativas.

# Segurança

Para verificar a confiabilidade do emissor das requisições, será enviado no Header uma chave de segurança no padrão Basic Authentication (opens new window). A chave a ser verificada será no seguinte formato:

Exemplo:

Authorization: Basic dml2YXJlYWw6NTk0RjgwM0IzODBBNDEzOTZFRDYzRENBMzk1MDM1NDI=

# Validação de Segurança SECRET_KEY

Todas as nossas requisições de integração de leads contém o header Authorization com informações do emissor da requisição, abaixo temos um exemplo em NodeJS de como pegar esse header do request, decodar e confrontar com uma chave que podemos enviar para vocês.

Lembrando que a SECRET_KEY é por CRM não é por cliente, ou seja, não deve ser utilizada para identificação do cliente (anunciante) e sim para validar se a requisição está sendo realizado pelo GrupoZap.

Supondo que já enviamos a SECRET_KEY 594F803B380A41396ED63DCA39503542 :

NodeJS/Javascript

  • 1 - Obter o header Authorization;
const authorization = req.headers.Authorization;
// valor de authorization será `Basic dml2YXJlYWw6NTk0RjgwM0IzODBBNDEzOTZFRDYzRENBMzk1MDM1NDI=`

  • 2 - Ignore Basic e decodifique somente o valor;
const base64 = authorization.split(' ')[1];
// 'dml2YXJlYWw6NTk0RjgwM0IzODBBNDEzOTZFRDYzRENBMzk1MDM1NDI='

const value = new Buffer(base64, 'base64').toString('utf-8');
// 'vivareal:594F803B380A41396ED63DCA39503542'
  • 3 - Valide a SECRET_KEY;
// 'vivareal:594F803B380A41396ED63DCA39503542'
const secretKey = value.split(':')[1];
// 594F803B380A41396ED63DCA39503542

if (secretKey !== SECRET_KEY) {
    return res.sendStatus(401);
}

Caso a chave não for a que enviamos, deverá retornar response statusCode 401, provavelmente a requisição não foi realizada pelo GrupoZap

# Homologação

Assim que as implementações forem realizadas, valide seu endpoint e depois nos envie as seguintes informações para o e-mail abaixo:

  • Endpoint implementado
  • Nome do CRM Integrador
  • clientListingId que será utilizado na homologação
  • E-mail para cadastro e envio dos erros da integração de leads

homologacaodesoftwares@olxbr.com

# Dúvidas Sugestões ou Problemas

Caso tenha alguma dúvida, sugestão ou problemas durante a implementação da integração de Leads, abra uma Issue (opens new window) neste repositório que iremos responder assim que possível.

# Exemplos

Possuímos alguns projetos simples feitos exclusivamente para demonstrar o recebimento de leads:

Python (opens new window)
NodeJS (opens new window)
Java (opens new window)
Go (opens new window)