Integração Eventos

Por volta de 7 min

Integração de eventos de aluguel

Aviso

Atualmente o envio de eventos está em fase beta.

Este documento contém as informações para que os Softwares/CRMs/ERPs realizem a integração com a API do Aluguel Digital. Assim, o anunciante poderá receber os eventos relacionados a todas as etapas, desde a visita, passando por negociação e análise de crédito, até a assinatura do contrato, em seu CRM.

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

Segurança

IPs do ZAP

Nós recomendamos que a URL que será utilizada para o recebimento dos eventos seja acessível apenas aos IPs de saída do ZAP, caso você utilize algum sistema de firewall:

54.162.151.93
54.156.129.60
3.89.171.165
3.208.42.223
35.175.17.150
35.173.9.239
18.231.52.186
100.24.160.21

Autenticação HTTP Básica

Também é ideal que essa URL seja protegida por autenticação básica HTTP Basic Auth. É possível configurar a autenticação básica HTTP diretamente na URL utilizada. Exemplo: https://username:password@app.crm.com.br/v1/events

HTTPS

Recomendamos que a URL configurada esteja disponível em HTTPS, para garantir a criptografia dos dados em nível de rede.

Eventos

Atualmente temos os seguintes eventos, eles são enviados assim que ocorrem:

Lead

Evento	Descrição
LEAD_DISCARDED	Quando um lead é descartado, esse lead pode ser proveniente dos portais do ZAP ou ter sido recebido via integração
LEAD_NEW_OWNERS	Quando as pessoas responsáveis por um lead são trocadas

Corpo da requisição

{
  "type": "LEAD_DISCARDED", // qual é o evento disparado (ver tabela acima para as possibilidades)
  "advertiserId": "d4e0b094-95f5-de5e-a207-51fa9ecd432e", // id do anunciante no ZAP
  "createdAt": "2021-01-19T11:51:01.48779306-03:00", // data em que o evento ocorreu em formato ISO
  "contact": {
    "name": "João da Silva", // nome do contato relacionado ao lead
    "phoneNumber": "11922334455", // telefone do contato relacionado ao lead
    "email": "joao.silva@teste.com" // e-mail do contato relacionado ao lead
  },
  "lead": {
    "owners": [
      {
        "name": "Maria Souza", // nome da pessoa responsável pelo lead
        "email": "maria.souza@imobiliaria.com", // e-mail da pessoa responsável pelo lead
        "phoneNumber": "11966667777" // telefone da pessoa responsável pelo lead
      }
    ],
    "createdAt": "2020-12-16T11:00:34.650856-03:00", // data da criação do lead em formato ISO
    "updatedAt": "2021-01-19T11:51:01.481285-03:00" // data de última atualização do lead em formato ISO
  }
}

Visita

Evento	Descrição
SCHEDULE_NEW	Quando uma visita é agendada a algum dos imóveis da imobiliária
SCHEDULE_CANCELED	Quando uma visita é cancelada
SCHEDULE_FEEDBACK_NOT_RECEIVED	Quando uma visita passa da data, mas não sabemos se a ela aconteceu ou não após algum tempo
SCHEDULE_DONE	Visita foi realizada
SCHEDULE_NOT_DONE	Visita não foi realizada
SCHEDULE_NEW_OWNERS	Quando as pessoas responsáveis por uma visita são trocadas

Corpo da requisição

{
  "type": "SCHEDULE_DONE", // qual é o evento disparado (ver tabela acima para as possibilidades)
  "advertiserId": "d4e0b094-95f5-de5e-a207-51fa9ecd432e", // id do anunciante no ZAP
  "createdAt": "2021-01-19T11:54:58.300567935-03:00", // data em que o evento ocorreu em formato ISO
  "contact": {
    "name": "João da Silva", // nome do contato relacionado a visita
    "phoneNumber": "11922334455", // telefone do contato relacionado a visita
    "email": "joao.silva@teste.com" // e-mail do contato relacionado a visita
  },
  "listing": {
    "externalId": "SEGUNDO" // id do anúncio onde a visita foi agendada
  },
  "schedule": {
    "date": "2021-01-22T09:00:00-03:00", // data agendada para visita em formato ISO
    "owners": [
      {
        "name": "Maria Souza", // nome da pessoa responsável pela visita
        "email": "maria.souza@imobiliaria.com", // e-mail da pessoa responsável pela visita
        "phoneNumber": "11966667777" // telefone da pessoa responsável pela visita
      }
    ],
    "createdAt": "2020-12-16T11:00:34.650856-03:00", // data da criação da visita em formato ISO
    "updatedAt": "2021-01-19T11:51:01.481285-03:00" // data de última atualização da visita em formato ISO
  }
}

Negociação

Evento	Descrição
OFFER_NEW	Quando uma proposta é enviada, pode ser tanto uma proposta, quanto uma contra proposta
OFFER_REJECTED	Quando uma proposta é rejeitada, esse evento é seguido sempre por uma nova proposta `OFFER_NEW`
OFFER_ACCEPTED	Quando uma proposta é aceita
NEGOTIATION_CANCELED	Quando uma negociação é cancelada
NEGOTIATION_NEW_OWNERS	Quando as pessoas responsáveis por uma negociação são trocadas

Corpo da requisição

{
  "type": "OFFER_REJECTED", // qual é o evento disparado (ver tabela acima para as possibilidades)
  "advertiserId": "d4e0b094-95f5-de5e-a207-51fa9ecd432e", // id do anunciante no ZAP
  "createdAt": "2021-01-19T12:05:31.618177152-03:00", // data em que o evento ocorreu em formato ISO
  "contact": {
    "name": "João da Silva", // nome do contato relacionado a negociação
    "phoneNumber": "11922334455", // telefone do contato relacionado a negociação
    "email": "joao.silva@teste.com" // e-mail do contato relacionado a negociação
  },
  "listing": {
    "externalId": "SEGUNDO" // id do anúncio alvo da negociação
  },
  "negotiation": { // negociação relacionada ao evento, agrupa todas as propostas
    "targetValue": 1234, // valor anunciado para negociação
    "offers": [ // lista de propostas ordenada da mais recente para a mais antiga
      {
        "value": 1000, // valor proposto
        "createdAt": "2021-01-19T12:05:31.624826-03:00", // data de criação da proposta em formato ISO
        "updatedAt": "2021-01-19T12:05:31.624828-03:00" // data de última atualização da proposta em formato ISO
      },
      {
        "value": 667,
        "createdAt": "2021-01-19T12:04:54.123813-03:00",
        "updatedAt": "2021-01-19T12:05:31.618186-03:00"
      }
    ],
    "owners": [
      {
        "name": "Maria Souza", // nome da pessoa responsável pela negociação
        "email": "maria.souza@imobiliaria.com", // e-mail da pessoa responsável pela negociação
        "phoneNumber": "11966667777" // telefone da pessoa responsável pela negociação
      }
    ],
    "createdAt": "2021-01-19T12:04:54.110855-03:00", // data de criação da negociação em formato ISO
    "updatedAt": "2021-01-19T12:05:31.640439-03:00" // data de última atualização da negociação em formato ISO
  },
  "offer": { // proposta relacionada ao evento
    "value": 667,
    "createdAt": "2021-01-19T12:04:54.123813-03:00",
    "updatedAt": "2021-01-19T12:05:31.618186-03:00"
  }
}

Análise de Crédito

Evento	Descrição
CREDIT_ANALYSIS_NEW	Quando uma análise de crédito é criada
CREDIT_ANALYSIS_PENDING	Quando todas as pessoas indicadas aceitam compartilhar seus dados para início da análise de crédito
CREDIT_ANALYSIS_APPROVED	Quando a análise de crédito é aprovada
CREDIT_ANALYSIS_REJECTED	Quando a análise de crédito é rejeitada
CREDIT_ANALYSIS_DOCUMENTS_RECEIVED	Quando os documentos das pessoas indicadas para análise de crédito são recebidos
CREDIT_ANALYSIS_DOCUMENTS_APPROVED	Quando os documentos das pessoas indicadas para análise de crédito são aprovados
CREDIT_ANALYSIS_DOCUMENTS_REJECTED	Quando os documentos das pessoas indicadas para análise de crédito são rejeitados
CREDIT_ANALYSIS_NEW_OWNERS	Quando as pessoas responsáveis pela análise de crédito são trocadas

Corpo da requisição

{
  "type": "CREDIT_ANALYSIS_APPROVED", // qual é o evento disparado (ver tabela acima para as possibilidades)
  "advertiserId": "d4e0b094-95f5-de5e-a207-51fa9ecd432e", // id do anunciante no ZAP
  "createdAt": "2021-01-19T14:06:12.425634577-03:00", // data em que o evento ocorreu em formato ISO
  "contact": {
    "name": "João da Silva", // nome do contato relacionado a análise de crédito
    "phoneNumber": "11922334455", // telefone do contato relacionado a análise de crédito
    "email": "joao.silva@teste.com" // e-mail do contato relacionado a análise de crédito
  },
  "listing": {
    "externalId": "SEGUNDO" // id do anúncio alvo da análise de crédito
  },
  "creditAnalysis": { // análise de crédito relacionada ao evento
    "value": 666, // valor aprovado da proposta que será parâmetro para a análise de crédito
    "warranty": "ZAP", // qual a garantia utilizada para análise, possíveis valores: SECURITY_DEPOSIT, GUARANTOR, INSURANCE_GUARANTEE, GUARANTEE_LETTER, CAPITALIZATION_BONDS, CREDIT_CARD, ZAP
    "proposers": [ // pessoas incluídas na análise de crédito
      {
        "document": "00585319049", // documento da pessoa analisada
        "documentType": "CPF", // tipo do documento da pessoa utilizado na análise
        "name": "João da Silva", // nome da pessoa analisada
        "phoneNumber": "11922334455", // telefone da pessoa analisada
        "email": "joao.silva@teste.com", // e-mail da pessoa analisada
        "salary": 5000 // salário informado pela pessoa para análise
      }
    ],
    "integrationId": "123456", // código de referência da análise no parceiro de crédito
    "owners": [
      {
        "name": "Maria Souza", // nome da pessoa responsável pela negociação
        "email": "maria.souza@imobiliaria.com", // e-mail da pessoa responsável pela negociação
        "phoneNumber": "11966667777" // telefone da pessoa responsável pela negociação
      }
    ],
    "createdAt": "2021-01-19T14:06:05.361445-03:00", // data de criação da análise de crédito em formato ISO
    "updatedAt": "2021-01-19T14:06:12.410685-03:00" // data de última atualização da análise de crédito em formato ISO
  }
}

Contrato

Evento	Descrição
TRANSACTION_NEW	Quando uma transação é iniciada após a aprovação da análise de crédito, uma transação é um agrupador para os diversos tipos de contratos existentes
TRANSACTION_NEW_OWNERS	Quando as pessoas responsáveis pela transação são trocadas
TRANSACTION_CANCELED	Quando a transação é cancelada
CONTRACT_ADDED	Quando um contrato é adicionado a transação
CONTRACT_SIGNED	Quando um contrato é assinado por todos os signatários
CONTRACT_CANCELED	Quando um contrato é cancelado antes de todas as assinaturas

Corpo da requisição

{
  "type": "CONTRACT_ADDED", // qual é o evento disparado (ver tabela acima para as possibilidades)
  "advertiserId": "d4e0b094-95f5-de5e-a207-51fa9ecd432e", // id do anunciante no ZAP
  "createdAt": "2021-01-19T17:24:44.093419899-03:00", // data em que o evento ocorreu em formato ISO
  "contact": {
    "name": "João da Silva", // nome do contato relacionado a transação
    "phoneNumber": "11922334455", // telefone do contato relacionado a transação
    "email": "joao.silva@teste.com" // e-mail do contato relacionado a transação
  },
  "listing": {
    "externalId": "SEGUNDO"  // id do anúncio que está sendo alugado
  },
  "transaction": { // transação relacionada ao evento, agrupa os contratos
    "contracts": [
      {
        "type": "LEASE", // tipo do contrato, possíveis valores: PROPERTY_MANAGEMENT, LEASE, FIRE_INSURANCE_AUTHORIZATION, KEYS_DELIVERY_RECEIPT, LETTER_OF_ATTORNEY, PROPERTY_INSPECTION
        "createdAt": "2021-01-19T16:36:15.949986-03:00", // data de criação do contrato em formato ISO
        "updatedAt": "2021-01-19T16:36:20.040329-03:00" // data de última atualização do contrato em formato ISO
      },
      {
        "type": "PROPERTY_MANAGEMENT",
        "createdAt": "2021-01-19T17:24:44.063121-03:00",
        "updatedAt": "2021-01-19T17:24:44.063123-03:00"
      }
    ],
    "owners": [
      {
        "name": "Maria Souza", // nome da pessoa responsável pela transação
        "email": "maria.souza@imobiliaria.com", // e-mail da pessoa responsável pela transação
        "phoneNumber": "11966667777" // telefone da pessoa responsável pela transação
      }
    ],
    "createdAt": "2021-01-19T16:30:02.007563-03:00", // data de criação da transação em formato ISO
    "updatedAt": "2021-01-19T17:24:44.091029-03:00" // data de última atualização da transação em formato ISO
  },
  "contract": { // contrato relacionado ao evento
    "type": "PROPERTY_MANAGEMENT",
    "createdAt": "2021-01-19T17:24:44.063121-03:00",
    "updatedAt": "2021-01-19T17:24:44.063123-03:00"
  }
}

Timeout

Nosso sistema de integração de eventos aguardará 5 segundos antes de fechar a conexão com a URL configurada, caso seu sistema não responda nesse intervalo com um status HTTP 2XX o evento entrará na política de tratamento de erros descrita abaixo. Recomendamos que seu sistema responda o mais rápido possível as nossas requisições, caso exista algum processamento mais pesado para ser realizado, é ideal que seja feito de forma assíncrona.

Tratamento de erros

Se a URL configurada estiver indisponível ou retornando algum erro, nós iremos realizar tentativas com cada vez um intervalo maior entre elas, até o máximo intervalo de 12 horas, seguindo a seguinte tabela

Tentativa	Intervalo
1	Assim que o evento ocorre
2	00:02:00
3	00:04:00
4	00:08:00
5	00:16:00
6	00:32:00
7	01:04:00
8	02:08:00
9	04:16:00
10	08:32:00
11	12:00:00
12	12:00:00
13	12:00:00
14	12:00:00
15	12:00:00
16	12:00:00
17	Evento é descartado

Desta forma o evento só é perdido caso a URL fique indisponível durante mais de aproximadamente 3 dias

Dicas

Testes

Para ver as requisições enviadas em cada evento sem a necessidade de expor um serviço para a internet, você pode usar algum site para receber e logar as nossas requisições

https://webhook.site/open in new window - Cria um endpoint público e mostra as requisições completas recebidas nele
https://requestbin.com/open in new window - Tem a opção de criar a visualização das requisições pública ou privada (login pelo GitHub ou Google)

Além destes em uma rápida pesquisa no Google é possível encontrar diversos outros.

Respostas

Sempre responda com um status HTTP 2XX, caso contrário o evento entrará na política de tratamento de erros.
Responda o mais rápido possível, deixe processamentos mais pesados para serem feitos de forma assíncrona, lembre-se temos um timeout para considerar a requisição não concluída.

Processamento das requisições

Caso você não vá processar todos os eventos, é possível evitar o parsing do corpo da requisição verificando primeiramente o header X-Event, nele estará contido qual evento está sendo enviado na requisição.
Tente não fazer nenhum processamento pesado no recebimento das nossas requisições, utilize algum mecanismo de filas ou mesmo threads para responder o mais rápido possível e garantir o sucesso da requisição dentro do timeout estabelecido.

Integração Eventos

# Integração de eventos de aluguel

# Segurança

# IPs do ZAP

# Autenticação HTTP Básica

# HTTPS

# Eventos

# Lead

# Corpo da requisição

# Visita

# Corpo da requisição

# Negociação

# Corpo da requisição

# Análise de Crédito

# Corpo da requisição

# Contrato

# Corpo da requisição

# Timeout

# Tratamento de erros

# Dicas

# Testes

# Respostas

# Processamento das requisições

Integração de eventos de aluguel

Segurança

IPs do ZAP

Autenticação HTTP Básica

HTTPS

Eventos

Lead

Corpo da requisição

Visita

Corpo da requisição

Negociação

Corpo da requisição

Análise de Crédito

Corpo da requisição

Contrato

Corpo da requisição

Timeout

Tratamento de erros

Dicas

Testes

Respostas

Processamento das requisições