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 | ||
|---|---|---|
| Sou cliente do Mapaprop | uma vez, ao começar | o começo se você automatiza a sua própria conta: as quatro coisas que funcionam diferente |
| 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 |
| Prepare-se para o primeiro lead | uma vez, quando é ligado | o que vale a pena ter pronto no dia em que as consultas da conta do seu cliente começam a chegar sozinhas |
| 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 seis 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 — o caso da Zonaprop está em Cota mensal e limites.
| 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
paIdque 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: o listado é percorrido por páginas, e percorrê-lo inteiro para encontrar um imóvel é trabalho que você economiza guardando opaId. - Com qual
clientRefvocê 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
paIdque devolvemos.
5 · Mande todos os dados, mesmo que algum portal não use
O objeto é o da Mapaprop, não o de um portal. Pedimos todos os dados porque é o que nos permite publicar em todos os portais possíveis: cada um aceita um subconjunto diferente, e o subconjunto muda com o tipo de imóvel.
Quando um portal não aceita um campo que você mandou, não o descartamos em silêncio: dizemos em
omitted no verify, com o motivo e com o que acontece com o dado.
omitted é informação, não uma instrução para tirar o campo. O dado fica guardado e viaja para
os portais que aceitam. Se você o tirar do seu objeto para "limpá-lo", perde essa compatibilidade — e
vai precisar dela com o próximo portal.
6 · O listado é PERCORRIDO, e o que diz que você terminou não é ele ter vindo curto
Ler os imóveis de um cliente não é uma chamada: é um percurso por páginas. Enquanto devolvermos o ponteiro para a seguinte, ainda há imóveis — mesmo que a página tenha vindo curta, ou até vazia. Cortar o percurso porque veio menos do que você pediu deixa você sem parte do inventário, e nada o avisa.
É gratuito (regra 2), então percorrê-lo inteiro não custa cota do portal: a única coisa que custa é fazê-lo mal. A forma exata está em o listado.
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.