Conceitos e regras

A chave e as permissões

• A chave é da conta (a empresa), nunca de uma pessoa. Ela tem nome, permissões, validade opcional e, se quiser, uma lista de IPs.
• Cada rota exige uma permissão (properties:read, leads:write…). Sem ela, scope_missing. GET /v1/me mostra as permissões da chave.
• Duas chaves ativas ao mesmo tempo deixam trocar a chave sem parar a integração: crie a nova, troque no seu sistema, revogue a velha.
• O dono da conta recebe um e-mail 15 dias antes de a chave vencer e na véspera.

Limites

• Faixa padrão: 10 chamadas por segundo (pico de 20) e 300 mil por mês. Faixa ampliada: 20 por segundo (pico de 40) e 1 milhão por mês. A ImobyFlow ajusta sob medida.
• Passou do segundo: rate_limited — espere e tente de novo, com intervalo crescente. Passou do mês: monthly_quota_exceeded — a cota volta no dia 1º (UTC). O dono é avisado em 80% e em 100%.
• Quem relê a carteira inteira toda hora gasta a cota à toa: use os eventos para saber o que mudou.

Listas e paginação

• As listas vêm em páginas: limit diz quantos itens, e cada resposta traz nextCursor. Mande-o de volta em cursor até ele vir nulo.
• O cursor vale só para a rota e a conta que o devolveram — e não se mexe nele. Mexido ou trocado: invalid_cursor.
• Para sincronizar, updatedSince traz só o que mudou desde uma data. Os eventos fazem melhor: em ordem, com 30 dias de memória.

Erros

Todo erro vem em application/problem+json (RFC 9457), com um code estável — é por ele que o seu sistema decide o que fazer, nunca pelo texto. O type é o endereço da página do erro, com a causa e o conserto. invalidParams traz todos os problemas do pedido de uma vez.

Mande o requestId quando falar com o suporte. Ver todos os códigos.

Como a escrita funciona

• Campo ausente não apaga: o pedido só muda o que trouxe. Para limpar um campo, mande null.
• Campo desconhecido é erro (invalid_param com unknown_field). Um bedroom no lugar de bedrooms não pode passar calado.
• Nada mudou? A resposta diz UNCHANGED e nada é gravado. Reenviar a carteira inteira não custa escrita.
• A edição feita na tela vence: o campo que a equipe mudou no painel não é sobrescrito e volta em result.conflicts.
• ?dryRun=true (modo ensaio): valida e diz o que aconteceria — criaria, atualizaria, nada mudou, estouraria a cota — sem gravar nada.
• Mande uma Idempotency-Key (um UUID) em cada escrita. Se a rede cair e você repetir o MESMO pedido com a MESMA chave em 24 horas, recebe a mesma resposta, sem gravar de novo (Idempotent-Replayed: true).
• Dois pedidos para o mesmo código ao mesmo tempo: o segundo recebe concurrent_write. Não mande o mesmo código em paralelo.

As regras da plataforma que valem para quem integra

São as mesmas da tela. Elas protegem as recomendações e os parceiros — e é por elas que um dado "aceito" às vezes não aparece onde você esperava.

• Bairro é fechado no catálogo. Mande neighborhoodSlug da lista de cidades e bairros. Bairro em texto passa por um dicionário de apelidos; o que ele não reconhece fica para a análise da ImobyFlow e o imóvel sai das recomendações até lá.
• Sem capa, sem recomendação. A primeira foto é a capa. As fotos mandadas por endereço são baixadas depois da resposta — acompanhe em photoSync.
• A régua dos 60 dias. Imóvel que ninguém confirma sai do ar. Gravar o imóvel pela API confirma; para confirmar sem mudar nada, use a confirmação em lote.
• Uma origem por conta. Com a sincronização automática do feed do CRM ligada, a API não grava imóvel (feed_sync_active): o feed arquivaria o que não estivesse no arquivo dele.
• Imóvel novo passa pela análise da ImobyFlow antes de aparecer para parceiros, como pela tela.
• Cota do plano. Só imóvel disponível ocupa cota. Criar acima do teto: plan_limit_reached. Atualizar quem já existe nunca é barrado.
• Lixeira com trava. Excluir manda para a lixeira por 30 dias. No máximo 20% da carteira (e pelo menos 10 itens) em 24 horas — um laço no seu sistema não esvazia a carteira (shrink_guard).
• Clientes: consentimento. Na criação, consentGiven: true. A imobiliária é a controladora do dado e declara a base legal.
• Clientes: movimentação. Cliente sem movimentação por 60 dias é arquivado. A sincronização sozinha não conta: mande lastActivityAt com a data do seu sistema, ou registre os atendimentos.
• Clientes: um só por pessoa. O PUT pelo código acha a pessoa que já está aqui pelo telefone ou e-mail e liga o seu código a ela (LINKED), sem duplicar.
• Parceria: dono único do funil. Só o lado que captou o cliente move a etapa (canMoveFunnel).
• Captação: aceitar gasta crédito. Só com a permissão captacao:accept e o termo específico aceito pelo dono no painel. Contato e endereço só aparecem depois do aceite.

Sincronizar a carteira, passo a passo

1. Carga inicial: mande a carteira em lotes de até 500, com o código do seu sistema em externalRef. Primeiro com ?dryRun=true, para ver o que seria recusado.
2. Depois, a cada mudança no seu sistema: PUT /v1/properties/by-ref/{código}. Ele cria ou atualiza, e não grava nada quando nada mudou.
3. Vendeu ou alugou: POST /v1/properties/{id}/status. Saiu da carteira: DELETE.
4. No caminho de volta, leia os eventos ou receba os webhooks: o que a equipe mudou na tela e as oportunidades novas do Radar.

Segurança e LGPD

• Guarde a chave no servidor, num cofre ou variável de ambiente. Nunca no JavaScript do seu site, nunca no aplicativo do cliente final.
• A lista de IPs da chave fecha a porta para quem copiar a chave: só os servidores da lista conseguem usá-la.
• A imobiliária é a controladora dos dados dos clientes; a ImobyFlow é a operadora. Os Termos da API trazem o acordo de tratamento de dados.
• Eventos e webhooks não levam dado pessoal: só ids e os nomes dos campos que mudaram.