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 · dar baixa DELETE …/publication/{portal}
Os passos 1 e 3 são os obrigatórios. O 2 é gratuito e economiza chamadas; o 4, o 5 e o 6 são conforme a sua necessidade.
1 · Cadastrar o imóvel
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.
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.
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.
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.
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.
6 · 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 quatro regras que valem para todos os fluxos
- Publicação — os portais e o que muda em cada um
- Cadastro de imóveis · Verificar · Publicar