Publicar um anúncio
O caso base: um imóvel, um portal. Partimos do princípio de que o cliente já tem a ficha dele e a conta dele no portal conectada — se não, comece por cadastrar um cliente, que se faz uma única vez.
O caminho
1 · cadastrar o imóvel POST /properties → devolve o paId
2 · verificar POST /properties/verify gratuito, e convém
3 · publicar PUT …/publication/{portal}
4 · como ficou? GET /properties/{paId} gratuito · ou ao portal (custa)
5 · atualizar PUT …/publication/{portal} a MESMA chamada do passo 3
6 · pagar por posição GET …/publication/{portal}/positioning conforme o portal
7 · dar baixa DELETE …/publication/{portal}
Os passos 1 e 3 são os obrigatórios. O 2 é gratuito e economiza chamadas; do 4 ao 7, conforme a sua necessidade.
1 · Cadastrar o imóvel
Antes da primeira vez convém ler duas coisas: o modelo de imóvel —por que as chaves são as mesmas em todos os países— e o objeto JSON, que é o contrato dos campos.
POST /properties com o seu objeto. Devolvemos um paId:
guarde-o, é com ele que você vai fazer todo o resto.
Mande o seu próprio código no objeto. É a sua âncora: se perder o paId, você o recupera a partir
do listado procurando por ele — o listado se percorre por
páginas, então para uma carteira grande é mais barato guardar o paId do que procurá-lo.
As fotos e as plantas viajam dentro do mesmo objeto, não em chamadas à parte. Uma única chamada
com tudo. Nós as baixamos, então a resposta pode dizer que ainda estão em processamento — isso é
normal e não impede publicar. Se alguma não pôde ser baixada, o bloco images diz isso e se
tenta de novo sem ter que mandar o objeto outra vez.
Se você é cliente da Mapaprop e gerou o seu token pelo app, este mesmo passo faz algo a mais: a
propriedade entra sozinha na sua conta Mapaprop quando as fotos terminam de ser processadas,
sem que você peça nada. Ela fica carregada, não publicada — publicá-la continua sendo o passo 3. O
estado do cadastro viaja no bloco mapaprop e está explicado em
Mapaprop.
E a sua própria conta é um dos destinos do passo 3: publica-se com mapapropapi na mesma
rota, não consome a cota de nenhum portal e também publica nas redes das quais você faz
parte. O passo 2 não se aplica: verificar é contra os portais.
2 · Verificar (gratuito, e é o melhor investimento do fluxo)
POST /properties/verify diz, portal por portal, se
aquele anúncio sairia — e o que falta se não sair. Não pergunta nada ao portal, então não gasta
cota nem depende de o portal estar no ar.
Por que convém: uma tentativa recusada pelo portal gasta a chamada do mesmo jeito. Verificar primeiro é gratuito, então a conta é simples.
Ele separa duas coisas, e a distinção importa:
- O que falta no objeto → você corrige, no que manda.
- O que falta da conta (o plano, a filial) → sai da conexão do cliente, não do imóvel. Não é preciso mandar isso na verificação.
E verifica os dois catálogos: a zona, com a sua hierarquia, e os atributos contra o catálogo do país da propriedade. São os erros que saem mais caro descobrir tarde, porque nenhum dos dois é rejeitado: a propriedade entra do mesmo jeito, e depois não aparece nas buscas por localização ou fica sem uma característica. Olhando a propriedade não dá para perceber — por isso vale este passo.
Use-o também antes de ter a conta conectada. O verificador funciona igual e diz se o seu mapeamento do objeto está correto, então você pode ter a sua integração pronta antes de o seu cliente autorizar.
3 · Publicar
A única decisão do passo: nos portais que têm planos de publicação, você escolhe com qual publicar. Pode mandá-lo na chamada ou deixá-lo guardado na configuração do imóvel — e se mandar os dois, ganha o da chamada, para que você possa mudar de plano sem reescrever o imóvel.
Se o plano que você pediu não estiver disponível, a resposta diz quais o seu cliente tem. Não é preciso consultar isso antes.
A outra decisão, e é opcional: com quais dados de contato sai este anúncio. Por padrão usa os da ficha do seu cliente; se você quiser outros —o corretor que cuida daquele imóvel, o telefone dele— envia-os na mesma chamada. O e-mail do corretor precisa ser o de um usuário que exista na conta do portal, e é daí que sai a lista de usuários do seu cliente, que no nível básico não gasta cota. ⚠️ Se você enviar um que o portal não reconhece, ele não devolve erro: substitui pelo do administrador e publica do mesmo jeito.
E se a propriedade está reservada, vendida ou alugada, o anúncio reflete isso sozinho: o estado viaja dentro do objeto e é aplicado neste mesmo passo — veja o estado da propriedade no portal. Não há mais nada para chamar. ⚠️ Mas uma propriedade tem UM estado ou nenhum: dois ligados são rejeitados no passo 2.
4 · Ver como ficou — e aqui há dois caminhos que não são a mesma coisa
| O que diz | Custa | |
|---|---|---|
GET /properties/{paId} | o que nós registramos dessa publicação | gratuito |
GET …/publication/{portal} | o que o portal diz: se está online, a URL, as visitas | 1 chamada |
Leia primeiro o gratuito. Pergunte ao portal quando precisar de algo que só ele sabe —a URL do anúncio, as visitas— ou quando suspeitar que alguém o mudou do lado do portal.
⚠️ Não consulte o estado num loop. Com 400 imóveis são 400 chamadas da cota do seu cliente.
5 · Atualizar
Não existe um endpoint para atualizar a publicação: é o mesmo PUT do passo 3. Chamá-lo de novo
atualiza o anúncio em vez de duplicá-lo.
Então o fluxo de uma mudança de preço é: você atualiza o imóvel → publica de novo. Duas chamadas, e a segunda é a que chega ao portal.
Mas o portal precisa terminar a publicação anterior antes de aceitar a seguinte. Se você publica e atualiza na mesma rajada, a segunda chamada pode cair dentro dessa janela e o portal a rejeita.
É temporário e dizemos isso a você: a resposta traz quantos segundos convém esperar. Espere e chame de novo — você não perdeu nada e o anúncio não é duplicado.
⚠️ É a decisão que convém tomar no seu código, não à mão: quando dissermos que o portal ainda está processando, tente de novo com espera em vez de tratar como uma falha. O endpoint de publicação tem o contrato exato dessa resposta.
E existe uma segunda decisão, de desenho: esperar ou perguntar. Se você preferir não esperar às cegas, pode perguntar ao portal em que etapa está — a consulta de estado diz isso.
⚠️ Para um anúncio solto os dois caminhos servem. Para um empreendimento com muitas unidades não: ali perguntar engana, e o motivo está em publicar um empreendimento.
Perguntar gasta uma chamada da cota do seu cliente; esperar é grátis. Por isso a recomendação padrão não muda: diante da janela de processamento, tente de novo com espera. Consultar o estado é a alternativa para quem preferir saber em vez de esperar — e convém reservá-la para quando você precisa decidir algo com essa resposta.
6 · Pagar por posição (opcional, e não se faz igual em todos os portais)
Até aqui o anúncio está publicado. Onde ele aparece na listagem é outra decisão, e os portais que cobram por isso não cobram no mesmo momento do fluxo: em alguns ela se escolhe ao publicar —viaja com o passo 3— e em outros depois, sobre o anúncio já online.
Você não precisa saber de cor: pergunte. O GET é gratuito e diz.
GET …/publication/{portal}/positioning
PUT …/publication/{portal}/positioning
O GET sempre responde duas coisas: com o que se paga a posição naquele portal e onde ela se
escolhe. A partir daí, três caminhos:
O que o GET diz | O que você faz |
|---|---|
| escolhe-se aqui | ler → decidir → PUT, como abaixo |
| escolhe-se ao publicar | volta ao passo 3: viaja com a publicação, e o GET diz em que campo |
| o portal não cobra por isso | nada: não há posição para comprar |
Quando se escolhe aqui, a ordem é ler, decidir, atribuir — nunca atribuir às cegas:
- O
GETdiz quanto resta ao seu cliente, onde o anúncio está hoje e, se você pedir, em que posição ficaria gastando cada valor. - Você decide (ou o seu usuário). Nós não escolhemos por ele.
- O
PUTaplica e devolve a posição real em que ficou.
O ?simulate= custa uma chamada da cota do seu cliente por cada valor. Peça os que você vai
mostrar, não uma curva inteira "por precaução".
Recém publicado pode não haver dados ainda: o portal demora para indexar o anúncio. O saldo e a
posição vêm do mesmo jeito; a simulação chega com unavailable e o seu motivo. Peça de novo mais
tarde.
Detalhe completo: pagar por posição. O que é próprio de cada portal —com o que paga, que cota tem— está em Publicação.
7 · Dar baixa
DELETE …/publication/{portal} baixa o anúncio daquele
portal. É idempotente: se já não estava, responde bem do mesmo jeito, então você não precisa levar
a conta.
E atenção à distinção, que é a que mais confunde: baixar o anúncio, desconectar a conta e apagar o cliente são três coisas distintas e só a primeira baixa a publicação. Está em dar baixa.
A ordem importa: o que acontece se você fizer ao contrário
| Se você… | Dizemos assim |
|---|---|
| publica antes de o cliente ter a ficha | o erro diz que falta declarar o cliente, e como |
| publica antes de a conta dele estar conectada | o erro diz que falta conectar essa conta, com o portal nomeado |
| publica um imóvel que não cadastrou | não o encontramos por esse paId |
Os três são erros precoces e com nome: dizem qual passo você pulou, não "algo falhou".
O que você não precisa fazer
- Mapear zonas. Você manda a sua zona e nós resolvemos a do portal. Se uma não estiver mapeada, o verificador avisa antes de publicar.
- Levar a conta da cota. O portal a informa e nós a repassamos na resposta de publicar.
- Consultar os planos antes de cada publicação. Se o que você pediu não estiver, a resposta diz quais há.
- Tentar de novo com outro objeto quando o portal recusa. Verifique primeiro: é gratuito e diz o mesmo sem gastar.
Relacionado
- Boas práticas — as seis regras que valem para todos os fluxos
- Publicação — os portais e o que muda em cada um
- Cadastro de imóveis · Verificar · Publicar