Boas práticas

O resto da documentação está organizado por endpoint: cada página responde "o que isto faz?". Útil quando você já sabe o que chamar.

Esta seção responde a outra pergunta, a primeira: em que ordem? São os fluxos completos, com as decisões que você vai ter que tomar e o que cada passo custa.

Aqui você não vai encontrar campos, códigos de erro nem payloads — isso fica na página de cada endpoint e está linkado onde corresponde. Se você procura "o que isto me devolve", vá ao endpoint; se procura "o que chamo primeiro", fique.

Os fluxos

	Quando
Cadastrar um cliente	uma vez por cliente	a ficha e a conexão com o portal
Publicar um anúncio	cada imóvel	o caso base: cadastrar, verificar, publicar
Publicar um empreendimento	cada empreendimento	tem uma ordem própria e convém saber disso antes
Receber consultas	contínuo	as consultas que as pessoas deixam nos anúncios
Dar baixa	quando for o caso	baixar um anúncio, desconectar uma conta, apagar um cliente: são três coisas distintas
Quando algo não sai	—	por onde começar a olhar

As quatro regras que valem para todos

1 · Há coisas que se fazem UMA VEZ e coisas que se fazem CADA VEZ

É o erro de desenho mais caro de uma integração, porque não falha: simplesmente faz o triplo das chamadas necessárias.

Uma vez por cliente	Cada vez
declarar a ficha dele	cadastrar ou atualizar um imóvel
conectar a conta dele no portal	publicar, consultar o estado, dar baixa
mapear as zonas dele (fazemos nós)	—

2 · Ler o nosso sistema é gratuito; perguntar ao portal se paga

A cota de chamadas é do seu cliente, ele a contrata com o portal, e a sua integração a gasta. Cada portal a define à sua maneira.

Gratuito	Gasta uma chamada da cota
verificar um objeto	publicar e dar baixa
ler um imóvel ou listá-los	perguntar ao portal o estado do anúncio
ler a ficha do cliente e os planos guardados dele	atualizar os planos contra o portal

⚠️ Os erros também gastam. Uma tentativa recusada pelo portal consome a chamada do mesmo jeito, então convém verificar antes — o que é gratuito.

3 · Guarde duas coisas do seu lado

O paId que devolvemos ao criar um imóvel. É com ele que você publica, consulta e dá baixa. Se o perder, você tem o listado e pode procurá-lo pelo seu próprio código, mas é um passo que não era necessário.
Com qual clientRef você operou. É como você nos diz de que cliente está falando, e quem o escolhe é você: use o id que já tem no seu sistema.

4 · Tentar de novo é seguro, e não precisa levar a conta

Publicar de novo atualiza o anúncio, não cria outro. É a forma de refletir uma mudança de preço ou de fotos.
Dar baixa duas vezes responde bem nas duas. Você não precisa lembrar se já deu.
O que não é idempotente é criar: dois cadastros do mesmo imóvel são dois imóveis. Mande o seu próprio código e use o paId que devolvemos.

Os portais

Os métodos são os mesmos para todos os portais: você passa o portal na rota e o resto não muda. O que muda por portal —como a conta é conectada, que cota tem, que planos— está em Publicação, e os fluxos daqui apontam para lá em vez de repetir.

Onde um portal se comporta de forma diferente, dizemos isso com o nome dele. Se você ler uma cifra ou um nome de plano sem portal ao lado, é um erro nosso: escreva para nós.

Se o seu aplicativo conecta um único cliente

Os fluxos estão escritos para o caso geral, em que o seu aplicativo opera sobre vários clientes e você nos diz com qual em cada chamada. Se o seu aplicativo está habilitado para um só, o cliente já está fixado do nosso lado e você pode ignorar esse passo: todo o resto é igual.