Rest API | Harry - Gestor inteligente de leads imobiliários (1.7.0)

Introdução

O Harry possui API's (Application Programming Interface) para integração com parceiros e clientes, todas nossas API's seguem a arquitetura REST e sua comunicação é através do protocolo https.

Para ter acesso as nossas API's, solicite ao nosso suporte através do e-mail developer@goharry.com.br

Ambiente de PRODUÇÃO

https://api.goharry.com.br

Versionamento

Aqui no Harry utilizamos as melhores práticas de desenvolvimento pensando nos nossos clientes e parceiros.

Todas as nossas APIs seguem um ciclo de vida planejado para acompanhar a evolução dos produtos sem causar impacto nos usuários. Para isso, elas são versionadas e hoje todas estão disponíveis no /v1, garantindo retrocompatibilidade com os consumidores.

Este documento descreve a versão 1.7.0 da API. Nesta atualização foram incluídas a API para mover atendimentos, novos GETs auxiliares e melhorias nos retornos do webhook e dos atendimentos. A tabela a seguir traz o histórico das versões anteriores.

versão data mudanças
1.7.0 18/08/2025 Adicionado a API para mover de atendimentos, GETs auxiliares e atualização de retornos do webhook e dos atendimentos
1.6.0 12/01/2024 Adicionado os campos customizados na documentação do webhook
1.5.0 26/04/2022 Adicionado documentação do webhook
1.4.1 14/01/2022 Adicionado o campo scheduledAt na API de manipulação de visitas por parceiros
1.4.0 13/12/2021 Adicionado a API para manipulação de visitas por parceiros
1.3.0 30/07/2021 Adicionado a API para consulta de atendimentos pela imobiliária
1.2.0 05/07/2021 Adicionado a API para criação de atendimentos pela imobiliária
1.1.0 01/02/2021 Ajustes no contrato da API de envio de leads pelos canais de aquisição
1.0.0 24/09/2020 Adicionado a API para envio de leads pelos canais de aquisição

Autenticação

Atualmente utilizamos os métodos de autenticação:

HTTP Basic que consiste em adicionar o usuário e senha no header Authorization da requisição HTTP

Authorization: Basic <credenciais em Base64 no formato: usuário:senha>

Api Key que consiste em enviar um ApiKey como query string.

https://host/path?api_key=102930405060708089

Erro

Todas API's utilizam o padrão HTTP status codes para indicar o sucesso ou erro da requisição. O corpo da resposta será JSON no seguinte formato:

{
  "code": "400",
  "status": "Bad Request",
  "message": "MISSING_REQUEST_PARAMETER",
  "description": "Erro de validação",
  "correlationId": "d3e37230-10eb-47a6-a43e-88f5bbc2de58"
}

Webhooks

Como funcionam

O webhook é a maneira mais simples do Harry se comunicar com o seu sistema quando um evento ocorrer. Cadastrando um webhook, o seu sistema será avisado pelo Harry sempre que um dos eventos abaixo ocorrer.

O Harry irá realizar uma requisição POST para sua aplicação e a mesma deve retornar o um status da classe 200 quando receber um webhook, caso contrário o Harry irá retentar 3 vezes.

Eventos

O Harry envia os seguintes eventos por webhook:

  • customer_service_created (enviado quando um atendimento é criado)
  • customer_service_status_changed (enviado quando a etapa de um atendimento é alterada)
Você poderá diferenciar o evento pelo atributo "eventType".

Exemplos:

{
  "eventType": "customer_service_created", // tipo do evento que gerou a chamada
  "customerService": {
    "id": 1234567, // Identificador do atendimento
    "status": "Em atendimento", // nome da etapa atual do atendimento
    "businessType": "Vendas", // tipo do negócio
    "createdAt": "2022-04-01T10:00:00", // data e hora da criação do atendimento
    "updatedAt": "2022-04-01T10:15:00", // última atualização
    "scheduledAt": "2022-04-15", // data para retornar depois
    "temperature": "morno", // temperatura do atendimento
    "createdByAcquisitionChannel": "Site", // nome do canal de aquisição inicial
    "dealClosed": null,
    "amountClosed": null,
    "reason": null,
    "customer": {  // dados do lead
      "email": "lead@sememail.com",
      "name": "Nome do lead",
      "phone": "11999990000"
    },
    "estateAgent": {  // dados do corretor dono do atendimento
      "email": "corretor@sememail.com",
      "name": "Nome corretor"
    },
    "properties": [  // lista de imóveis do atendimento
      {
        "acquisitionChannel": "Site", // Canal de aquisição que gerou o contato
        "createdAt": "2022-04-01T10:00:00", // Data e hora que o contato foi realizado
        "message": "Olá, gostaria de visitar o imóvel", // Mensagem enviada pelo lead na hora do contato
         "property": { // Dados do imóvel
          "code": "string",
          "url": "string",
          "amount": 0
        },
        "interest": { // Dados do interesse do lead
          "level": "Baixo",
          "reason": "Busca outra localização",
          "observation": "Lead Teste não gostou do bairro"
        },
        "visit": {  // lista de visitas do atendimento
          "date":"2022-04-02", // Data da visita
          "startHour": "11:00", // Hora da visita
          "canceled": true, // Se a visita foi cancelada
          "canceledAt": "2022-04-01T11:00:00", // Quando a visita foi cancelada
          "finished": true, // Se a visita foi finalizada
          "finishedAt": "2022-04-01T12:00:00", // Quando a visita foi finalizada
          "reason": "Analisando a compra", // Motivo da finalização ou cancelamento da visita
          "feedback": "Lead Teste gostou do imóvel", // Feedback da visita
          "visitOwner": { // Corretor responsável pela visita
            "email": "corretor@sememail.com",
            "name": "Nome do corretor"
          }
        },
        "customFields": [
            {
                "name": "Campanha",
                "value": "Lançamento"
            },
            {
                "name": "Plataforma",
                "value": "Facebook"
            },
            {
                "name": "Anúncio",
                "value": "Vídeo lançamento"
            }
        ]
      }
    ]
  },
  "originUser": { // dados do usuário que gerou o evento
    "email": "corretor@sememail.com",
    "name": "Nome do corretor"
  }
}

Leads

Recursos utilizado pelos canais de aquisição para envio de novos leads

Criar um novo lead

Authorizations:
BasicAuth
path Parameters
channelName
required
string

Canal de Aquisição

Request Body schema: application/json

Corpo da Requisição.

acquisitionChannel
string

Canal de aquisição, caso não seja informado será considerado o canal de aquisição que está se integrando

businessType
string
Enum: "SALE" "RENT" "RAISE_PROPERTY"

Tipo de negócio do imóvel. Vendas, locação ou angariação

email
string

E-mail do lead

message
string

Mensagem enviada pelo lead

name
string

Nome do lead

phone
string

Telefone do lead

propertyAmount
number >= 1

Valor do imóvel

propertyCode
string

Código do imóvel

propertyUrl
string

Url do imóvel

enterpriseId
integer <int32>

ID da Imobiliária

Responses

Request samples

Content type
application/json
{
  • "acquisitionChannel": "site",
  • "businessType": "SALE",
  • "email": "lead@sememail.com",
  • "message": "Olá, gostaria de mais detalhes sobre o imóvel",
  • "name": "Lead Exemplo",
  • "phone": "11999999999",
  • "propertyAmount": "1500000.50",
  • "propertyCode": "COD-9485",
  • "enterpriseId": 1
}

Response samples

Content type
application/json
{
  • "id": 12345
}

Motivos de etapas

Consultar motivos de etapas

Authorizations:
BasicAuth
query Parameters
status
string

status

Responses

Request samples

curl --request GET \
--url 'https://api.goharry.com.br/public/v1/enterprises/domains/status-reasons' \
--header 'Authorization: Basic [YOUR_USERNAME_PASSWORD]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response samples

Content type
*/*
{
  "items": [
    {
      "id": 1,
      "reason": "Venda concluída",
      "type": "FINISHED"
    },
    {
      "id": 2,
      "reason": "Lead Teste desistiu da compra",
      "type": "FINISHED"
    },
    {
      "id": 3,
      "reason": "Documentação pendente",
      "type": "IN_PROPOSAL"
    }
  ],
  "page": 1,
  "pageSize": 10,
  "pages": 1,
  "totalItems": 3
}

Etapas de funil

Consultar etapas de funil

Authorizations:
BasicAuth
query Parameters
business_type
string

business_type

Responses

Request samples

curl --request GET \
--url 'https://api.goharry.com.br/public/v1/enterprises/domains/status-reasons' \
--header 'Authorization: Basic [YOUR_USERNAME_PASSWORD]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response samples

Content type
*/*
{
  "businessType": "SALE",
  "statuses": [
    {
      "status": "NEW",
      "description": "Novo",
      "order": 1,
      "actionRequired": true,
      "useOnPreService": true
    },
    {
      "status": "IN_PROGRESS",
      "description": "Em atendimento",
      "order": 2,
      "actionRequired": true,
      "useOnPreService": true
    },
    {
      "status": "VISIT_SCHEDULED",
      "description": "Visita agendada",
      "order": 3,
      "actionRequired": false,
      "useOnPreService": false
    }
  ]
}

Motivos de visitas

Consultar motivos de visitas

Authorizations:
BasicAuth
query Parameters
size
integer <int32>

size

Responses

Request samples

curl --request GET \
--url 'https://api.goharry.com.br/public/v1/enterprises/schedule-visit-reasons' \
--header 'Authorization: Basic [YOUR_USERNAME_PASSWORD]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response samples

Content type
*/*
{
  "items": [
    {
      "id": 1,
      "reason": "Lead Teste gostou do imóvel",
      "type": "FINISH",
      "order": 1,
      "editable": false,
      "enabled": true
    },
    {
      "id": 2,
      "reason": "Lead Teste não gostou da localização",
      "type": "FINISH",
      "order": 2,
      "editable": true,
      "enabled": true
    },
    {
      "id": 10,
      "reason": "Conflito de agenda",
      "type": "CANCEL",
      "order": 1,
      "editable": true,
      "enabled": true
    }
  ],
  "page": 1,
  "pageSize": 10,
  "pages": 1,
  "totalItems": 3,
  "next": null,
  "previous": null
}

Atendimentos

Recursos utilizado pela imobiliária para criação e leitura dos atendimentos

Criar um novo atendimento

Authorizations:
BasicAuth
Request Body schema: application/json

Corpo da Requisição.

name
string

Nome do lead

email
string

E-mail do lead

phone
string

Telefone do lead

message
string

Mensagem enviada pelo lead

businessType
string
Enum: "SALE" "RENT" "RAISE_PROPERTY"

Tipo de negócio do imóvel. Vendas, locação ou angariação

acquisitionChannel
string

Canal de aquisição

propertyCode
string

Código do imóvel

propertyAmount
number >= 1

Valor do imóvel

propertyUrl
string

Url do imóvel

Responses

Request samples

Content type
application/json
{
  • "name": "Lead Teste",
  • "email": "lead@sememail.com",
  • "phone": "11999999999",
  • "message": "Gostaria de visitar o imóvel...",
  • "businessType": "SALE",
  • "acquisitionChannel": "GrupoZap",
  • "propertyCode": "REF0004",
  • "propertyAmount": 550000,
}

Response samples

Content type
application/json
{
  • "id": 304030
}

Consultar atendimentos

Authorizations:
BasicAuth
query Parameters
user
string

Filtrar atendimentos por corretor. Informar o e-mail do corretor

team
string

Filtrar atendimentos por time. Informar o nome do time

business_type
string
Enum: "SALE" "RENT" "RAISE_PROPERTY"

Filtrar por tipo de negócio vendas, locação ou angariação

start_date
string <date>
Example: start_date=2021-07-05

Filtrar por atendimentos criado igual ou maior que a data informada

end_date
string <date>
Example: end_date=2021-07-05

Filtrar por atendimentos criado igual ou menor que a data informada

page
number <int32>
Example: page=1

Pagina da requisição

size
number <int32> <= 50
Example: size=10

Itens por requisição. Máximo de 50

sort
string
Enum: "id:asc" "id:desc" "status:asc" "status:desc" "user_id:asc" "user_id:desc" "business_type:asc" "business_type:desc" "temperature:asc" "temperature:desc" "created_at:asc" "created_at:desc" "updated_at:asc" "updated_at:desc" "finished_at:asc" "finished_at:desc" "scheduled_at:asc" "scheduled_at:desc"
Example: sort=created_at:desc

Utilizado para ordenação, pode ser combinado mais de um valor. ex: created_at:desc,status:desc

Responses

Request samples

curl --request GET \
--url 'https://api.goharry.com.br/public/v1/customer-services' \
--header 'Authorization: Basic [YOUR_USERNAME_PASSWORD]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Move atendimento

Authorizations:
BasicAuth
path Parameters
customer_service_id
required
string

ID do atendimento

Request Body schema: application/json
Array of objects (EnterpriseStatusRequestDTO)

Responses

Request samples

Content type
application/json
{
  • "status": "IN_PROGRESS",
  • "amountClosed": null,
  • "dealClosed": false,
  • "distributeAutomatic": null,
  • "distributeToSubsidiaryId": null,
  • "distributeToUserId": null,
  • "inProposalAmount": null,
  • "inProposalDate": null,
  • "inProposalEnterprisePropertyId": null,
  • "statusReasonId": null
}

Visitas

Recursos utilizado pelos parceiros para manipulação de visitas

Manipular eventos de visita

Authorizations:
ApiKeyAuth
Request Body schema: application/json

Corpo da Requisição.

visitId
number

Identificação da visita no Harry

eventType
string
Enum: "CREATE" "FINISH" "CANCEL" "FEEDBACK"

Tipo de evento para manipular a visita. Criação, finalização, cancelamento e feedback

feedback
string

Mensagem de feedback

updatedAt
string <date_time>

Data e hora gerada pelo evento

scheduledAt
any <date_time>

Data e hora do agendamento

Responses

Request samples

Content type
application/json
{
  • "visitId": "10203040",
  • "eventType": "CREATE",
  • "feedback": "Lead Teste gostou do imóvel",
  • "updatedAt": "2021-12-12T10:00:00",
  • "scheduledAt": "2021-12-12T10:00:00"
}

Response samples

Content type
application/json
{
  • "code": "400",
  • "status": "Bad Request",
  • "message": "MISSING_REQUEST_PARAMETER",
  • "description": "Erro de validação",
  • "correlationId": "d3e37230-10eb-47a6-a43e-88f5bbc2de58"
}