# 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:

  • 18.231.52.186
  • 35.175.17.150
  • 100.24.160.21
  • 54.156.129.60
  • 3.208.42.223
  • 35.173.9.239
  • 3.89.171.165

# 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

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.