Conceitos-chave

📘

Leia antes de integrar

Estas são as regras que valem em toda a API pública. Entendendo elas, os endpoints de imóveis, pessoas, leads e atendimento ficam previsíveis, e a maior parte dos erros deixa de acontecer.

🗂️ Tudo por nome, não por id

Cada convênio tem o seu próprio catálogo. Tipos de imóvel, características, bairros, cidades, tipos de contato, tipos de relação, motivos (de descarte, de cancelamento de visita, de parecer) e tipos de atividade variam de uma imobiliária para outra. Por isso, na API pública você envia tudo pelo nome cadastrado, nunca por um id interno.

Antes de escrever, consulte o catálogo do convênio:

🚧

Nome desconhecido ou ambíguo

Um nome que não existe no convênio volta 422 UNKNOWN_NAME. Um nome que casa com mais de um cadastro volta 422 AMBIGUOUS_NAME (a mensagem traz os ids para você desambiguar). A API não cria cadastros auxiliares sozinha: consulte o schema e envie o nome exato. As exceções são explícitas e têm escopo próprio: incluir cidade e bairro (localizacao:write) e mídia (midias:write).

🏷️ Características do imóvel

Característica também é cadastro do convênio, então varia de um para outro. Consulte GET /schema/properties?propertyType=<nome> para saber quais existem e de que tipo. A leitura devolve sempre uma lista, e essa é a forma recomendada também na escrita, porque deixa explícito o nome e o valor de cada item:

{
  "characteristics": [
    { "name": "Quartos", "value": 3 },
    { "name": "Aquec. elétrico", "value": true }
  ]
}

{
  "characteristics": {
    "Quartos": 3,
    "Alarme": true
  }
}

❗️

Não repita uma característica

O mesmo nome duas vezes volta 422 com DUPLICATE_CHARACTERISTIC.

🔢 Valores numéricos

Características de tipo number são inteiras: 3 sim, 3.5 não (casa decimal em campo inteiro volta 422 com INVALID_CHARACTERISTIC_VALUE). Para valor fracionário existem os tipos decimal, currency e percent; o catálogo diz qual é qual.

Número aceita os dois formatos, sem adivinhação:

🛡️ Moderação e duplicidade

📘

Imóvel nasce em moderação

Todo imóvel criado por POST /properties nasce em em_moderacao e só entra em feed de portal quando alguém do convênio o libera no produto. Por isso, vago_disponivel não é aceito em PATCH /properties/{id}/status. Detalhes em Ambiente e moderação.

Reenvios são seguros e a duplicidade é tratada para você:

🧭 Ação nomeada, nunca edição livre

No fluxo comercial (atendimento, visita, proposta, atividade), a API não tem "edição livre" do registro: ela oferece ações nomeadas, uma por rota (annotations, discard, visitas, status, feedback, propostas, complete, cancel). Quando a ação não pode ser feita, a resposta traz um código estável:

Não existe parâmetro para pular regra. E a API não exclui cadastro: registro sai de uso mudando a situação (descartar, cancelar, inativar). O que se desfaz é só vínculo: tirar etiqueta, desvincular proprietário, remover foto.

🔒 Dado pessoal tem uma porta só

Registros e imóveis trazem a pessoa pelo id (e, no máximo, o nome). Documento, telefone, e-mail e endereço saem só por GET /people/{id}, com pessoas:read. Proprietário do imóvel e locador do contrato saem só como personId.

📡 Webhooks

Toda escrita pela API dispara o webhook do evento (imóvel incluído, visita agendada, anotação no atendimento...), com o autor api_key, do mesmo jeito que as alterações feitas pela imobiliária. O cadastro dos endpoints é feito no sistema, em Configurações.

⏱️ Limites de requisição

Dois tetos por chave: 120 requisições por minuto e 1.000 por hora (ajustáveis por chave). Ao estourar, a resposta é 429 com o cabeçalho Retry-After.

👍

Um 429 nunca descarta em silêncio

Se você recebeu 429, a requisição não foi processada. Aguarde o prazo do Retry-After e reenvie: nada foi perdido.

⚠️ Erros

Toda resposta de erro tem a mesma forma em toda a /pub/v1, com um code estável entre versões para você decidir por código sem parsear a mensagem em português:

{
  "statusCode": 422,
  "code": "UNKNOWN_NAME",
  "error": "Unprocessable Entity",
  "message": "..."
}

O 409 acrescenta duplicates; um 5xx nunca carrega detalhe interno. A tabela completa de status e códigos está em Erros e códigos.

➡️ Próximos passos

• Enviar um lead
• Publicar um imóvel
• Buscar e sincronizar
• Referência da API