Integração de leads de aluguel

Aviso

Atualmente o recebimento de leads está em fase beta e é apenas suportado para leads do Aluguel Digital.

Você deverá seguir os passos abaixo, primeiro adquirindo seu token de autenticação e depois enviando as informações do lead.

---

---

Autenticação

Antes de qualquer coisa, você precisará adquirir um token de autenticação. Este será usado para nos informar que você está habilitado para nos enviar um lead de forma segura.

Utilizamos a autenticação OAUTH2 padronizada pela RFC 6749.

Para adquirir seu token de autenticação, você deverá requisitar o endereço https://account-api.grupozap.com usando o protocolo HTTP e o verbo POST , informando:

• grant_type : [Requerido] tipo de requisição. Manter sempre o valor client_credentials ;
• client_id : [Requerido] Informe aqui o identificador de cliente;
• client_secret : [Requerido] Informe aqui o seu token privado de cliente.

Exemplo de autenticação

Request

curl \
  -XPOST \
  -v https://account-api.grupozap.com/oauth/token \
  -d 'grant_type=client_credentials&client_id=example_client_id&client_secret=example_client_secret'

Possíveis respostas

Sucesso

HTTP 200

Sucesso. O seu token estará no corpo da resposta no formato JSON

{
	"access_token": "string",
	"token_type": "bearer",
	"expires_in": 0,
	"scope": "read",
}

Onde:

• access_token : O seu token de acesso. Esta informação deverá ser passada no POST de integração de leads.
• token_type : Sempre iremos devolver o seu token com o tipo bearer ;
• expires_in : Este é o tempo de vida do seu token em segundos. Depois deste período o seu token será invalidado e um novo token precisará ser gerado;
• scope : o escopo sempre será read (leitura).

Falha

Todas as respostas com falhas terão em seu corpo informações com mais detalhes sobre o motivo da falha, no formato JSON como o do exemplo abaixo:

{
	"error": "<mensagem de erro>",
	"error_description": "<descrição do erro>"
}

HTTP 400

Falha na requisição. Alguma informação fornecida está incorreta.

HTTP 401

Credenciais inválidas ou incorretas. Provavelmente o token de autenticação está incorreto ou inválido.

---

---

Enviando leads de aluguel

Requisição

Faça a requisição com protocolo HTTP para o endereço https://casio-api.grupozap.com/public/v2/lead utilizando o verbo POST .

Cabeçalho

O cabeçalho (ou header) deverá nos informar seu token de autenticação adquirido pela request de autenticação.

{
  "Authorization": "Bearer <token>"
}

Corpo

O corpo (ou body) da requisição deverá fornecer as seguintes informações para ser um lead válido:

{
  "advertiserId": "string|uuid",
  "contact": {
    "email": "string",
    "name": "string",
    "phoneNumber": "string"
  },
  "externalId": "string",
  "message": "string",
  "origin": "string",
  "owners": [
    {
      "email": "string",
      "name": "string",
      "phoneNumber": "string"
    }
  ],
  "transactionType": "RENTAL",
  "usageType": "RESIDENTIAL"
}

Onde:

• advertiserId: [Requerido] Código de identificação da imobiliária. Trata-se de um código padronizado uuid definido pela RFC 4122
• contact : [Requerido] Nó de informações de contato do lead, onde:
  • email : [Requerido] E-mail de contato do lead;
  • name : [Requerido] Nome completo do lead;
  • phoneNumber : Telefone completo do lead contendo apenas números, com DDD;
• externalId : [Requerido] Código de identificação do imóvel que o lead mostrou interesse em alugar;
• message : [Requerido] Mensagem enviada pelo lead quando este demonstrou interesse;
• origin : [Requerido] Canal de origem de chegada do lead;
• owners : Uma lista de responsáveis pelo lead e suas respectivas informações para contato;
  • email : [Requerido] E-mail do responsável pelo lead;
  • name : [Requerido] Nome completo do responsável pelo lead;
  • phoneNumber : Telefone completo do responsável pelo lead contendo apenas números, com DDD;
• transactionType : [Requerido] tipo de interesse do lead. Valores possíveis RENTAL e SALE. Caso seja enviado SALE, apenas aceitamos a requisição, mas não armazenamos nenhum dado.
• usageType : tipo de uso do interesse do lead. Valores possíveis RESIDENTIAL e COMMERCIAL Caso não seja enviado assumimos RESIDENTIAL. Caso seja enviado COMMERCIAL apenas aceitamos a requisição, mas não armazenamos nenhum dado.

Resposta

Sucesso

HTTP 201

Criado. Recebemos seu lead corretamente e um identificador foi retornado no corpo da resposta no formato JSON.

{
  "id": 0
}

HTTP 204

Sem conteúdo. Recebemos seu lead corretamente mas não vamos processá-lo devido a regras de negócio.

Falha

Todas as respostas com falhas terão em seu corpo informações com mais detalhes sobre o motivo da falha, no formato JSON como o do exemplo abaixo:

{
  "code" : "string",
  "error" : "string"
}

Onde:

• code : Código interno de erro do integrador;
• error : Mensagem com detalhes do erro.

HTTP 400

Alguma informação na request é inválida.

HTTP 401

Autorização inválida. Provavelmente seu token de autenticação está inválido e você precisará gerar um novo. Favor verificar como gerar um novo token

HTTP 403

Perfil inválido. A conta usada para autenticação não possui a permissão necessária para enviar um lead.

HTTP 422

Formatação inválida. Provavelmente há algo de errado com a estrutura do JSON enviada na requisição.

HTTP 500

Erro interno do integrador.