BETA

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

PUT …/publication/{portal}.

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 dizCusta
GET /properties/{paId}o que nós registramos dessa publicaçãogratuito
GET …/publication/{portal}o que o portal diz: se está online, a URL, as visitas1 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 dizO que você faz
escolhe-se aquiler → decidir → PUT, como abaixo
escolhe-se ao publicarvolta ao passo 3: viaja com a publicação, e o GET diz em que campo
o portal não cobra por issonada: não há posição para comprar

Quando se escolhe aqui, a ordem é ler, decidir, atribuir — nunca atribuir às cegas:

  1. O GET diz quanto resta ao seu cliente, onde o anúncio está hoje e, se você pedir, em que posição ficaria gastando cada valor.
  2. Você decide (ou o seu usuário). Nós não escolhemos por ele.
  3. O PUT aplica 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 fichao erro diz que falta declarar o cliente, e como
publica antes de a conta dele estar conectadao erro diz que falta conectar essa conta, com o portal nomeado
publica um imóvel que não cadastrounã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