BETA

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 Mapapropuma vez, ao começaro começo se você automatiza a sua própria conta: as quatro coisas que funcionam diferente
Cadastrar um clienteuma vez por clientea ficha e a conexão com o portal
Publicar um anúnciocada imóvelo caso base: cadastrar, verificar, publicar
Publicar um empreendimentocada empreendimentotem uma ordem própria e convém saber disso antes
Receber consultascontínuoas consultas que as pessoas deixam nos anúncios
Prepare-se para o primeiro leaduma vez, quando é ligadoo que vale a pena ter pronto no dia em que as consultas da conta do seu cliente começam a chegar sozinhas
Dar baixaquando for o casobaixar 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 clienteCada vez
declarar a ficha delecadastrar ou atualizar um imóvel
conectar a conta dele no portalpublicar, 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.

GratuitoGasta uma chamada da cota
verificar um objetopublicar e dar baixa
ler um imóvel ou listá-losperguntar ao portal o estado do anúncio
ler a ficha do cliente e os planos guardados deleatualizar 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

  1. 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: o listado é percorrido por páginas, e percorrê-lo inteiro para encontrar um imóvel é trabalho que você economiza guardando o paId.
  2. 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.

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.