Quando algo não sai
A ordem abaixo não é arbitrária: vai do gratuito ao caro e do que você pode ver ao que nós temos que olhar. Os dois primeiros passos resolvem a maioria dos casos e não gastam nada da cota do seu cliente.
A ordem
1 · leia o erro completo gratuito — e quase sempre diz qual passo falta
2 · verifique o objeto gratuito — POST /properties/verify
3 · leia o que temos guardado gratuito — GET /properties/{paId}
4 · pergunte ao portal custa 1 chamada
5 · escreva para nós com a referência do passo 1
1 · O erro completo, não só o código
Os nossos erros estão escritos para que digam o que fazer, não só que algo falhou. Além do código eles trazem uma descrição e, quando for o caso, o nome do campo ou do portal.
O mais importante: um erro nosso diz se o problema é seu (algo no que você mandou) ou do passo anterior (falta a ficha, falta a conexão). Se disser que falta conectar a conta, não é um problema de permissões do seu token.
2 · Verificar o objeto (gratuito)
POST /properties/verify com o mesmo objeto que falhou. Ele
diz, portal por portal, o que falta. Não pergunta nada ao portal, então não gasta cota nem depende
de o portal estar no ar.
Separa duas coisas que convém não misturar:
- O que falta no objeto → está sob o seu controle.
- O que falta da conta (o plano, a filial) → sai da conexão, não do imóvel.
3 · O que temos guardado (gratuito)
GET /properties/{paId} mostra o que registramos: se o
imóvel existe, que portais tem, e o que aconteceu na última tentativa de publicação.
É o passo que responde "a minha chamada chegou?" sem gastar nada.
4 · Perguntar ao portal (1 chamada)
GET …/publication/{portal} é a única coisa que sabe se o
anúncio está online agora e qual é a URL dele.
Deixe isso para o final: é o único que custa, e os três passos anteriores costumam explicar o problema sem ele.
Os casos que aparecem mais
| O que você vê | Por onde começar |
|---|---|
| "Publiquei e não vejo o anúncio" | O portal pode demorar para mostrá-lo. O passo 4 diz se ele já o tem; se disser que sim, é tempo de publicação do portal, não um problema da integração |
| "Publiquei de novo logo em seguida e foi rejeitado" | O portal processa um anúncio por vez: enquanto termina o anterior, não aceita o seguinte. Dizemos a você que é temporário, com quantos segundos esperar — espere e tente de novo, não mude nada. Acontece mais com grandes empreendimentos, nos quais o portal trabalha de forma diferida |
| "Dei baixa e voltou a ficar online" | A baixa chegou enquanto o portal ainda processava a publicação: respondeu normalmente e depois o portal terminou o trabalho pendente e publicou de novo. Espere até parar de processar e dê baixa outra vez. Acontece com empreendimentos grandes, onde o diferido é de minutos |
| O plano que pedi não está disponível | A resposta do publish diz quais o seu cliente tem. Se você não esperava isso, atualize os planos contra o portal: algum pode ter sido consumido ou vencido |
Um 403 | Olhe qual scope ele diz que falta. Se nomear um portal, o seu token não está habilitado para aquele portal — o que é diferente de não poder ler ou escrever |
| Diz que a conta não está conectada | Peça a ficha do cliente (gratuito) e olhe o estado das conexões dele. Pode ser que o seu cliente a tenha desconectado do lado do portal |
| 🔴 "Funcionava e, de repente, recusa TUDO" — publicar, dar baixa, consultar e ler planos, ao mesmo tempo, sem que você tenha mexido em nada | Quase sempre é que a conta do seu cliente foi reconectada a partir de outro lugar. Há portais que admitem uma única conexão por imobiliária —a Zonaprop é um deles—, portanto a última desliga a anterior. Resolve-se conectando-a novamente pela API: Conectar com um link. O detalhe está em Zonaprop |
| Uma lista de consultas vazia | Antes de supor que não há, confira que modo aquele portal suporta: pode ser que ali as consultas não sejam pedidas, e sim que cheguem sozinhas |
Diz que a zona não existe (zone2, rule: not_found) | O value traz o código de 4 segmentos que buscamos. Compare com o catálogo de zonas: ou a zona mudou, ou a sua tabela de equivalências ficou velha. A hierarquia também conta: uma zone2 correta pendurada em outra zone1 não existe |
Um atributo não foi publicado (attributes[n].id, rule: unknown) | Esse id não existe no catálogo daquele país — e os catálogos diferem entre países. Peça o catálogo com o país da propriedade e compare |
| Um dado que você mandou não aparece | Verifique (passo 2): se o portal não suportar aquele campo, dizemos isso ali em vez de descartá-lo em silêncio |
| "Atribuí pontos e a posição não mudou" | Olhe o saldo, não a posição. O portal demora para recalcular: se o saldo baixou, foi aplicado. A posição se atualiza depois — e o número da simulação é a estimativa, não uma promessa. Pagar por posição |
A simulação volta vazia com segment_insufficient_data | O mercado dessa propriedade é muito pequeno para o portal ter estatísticas. Não há números a dar — não é uma falha nossa nem algo para repetir |
A simulação volta vazia com not_indexed | Você publicou há muito pouco tempo. O saldo e a posição vêm do mesmo jeito; espere e peça de novo |
Não obtivemos resposta do portal (portal_unreachable) | Não significa que o seu dado esteja errado: significa que não sabemos o que aconteceu. A escrita pode ter entrado ou não. Tente de novo — repetir a mesma chamada não duplica nada (abaixo) |
| Parte de um empreendimento ficou sem associar | O empreendimento continua publicado e o que falhou volta por unidade com o seu motivo. Repita o publish do empreendimento: refaz-se só o que falta |
Tentar de novo é seguro, e só refaz o que falta
Vale para todos os portais, não é particular de nenhum: repetir uma operação de publicação não duplica anúncios nem refaz trabalho já feito. Antes de escrever, comparamos com o que o portal tem e agimos sobre a diferença.
| Se você repetir… | O que acontece |
|---|---|
| o publish de um anúncio que já está publicado | ele é atualizado, não criado de novo |
| o publish de um empreendimento | o pai é atualizado, e das unidades mexe-se só nas que faltam |
| uma baixa de algo que já não estava | responde bem do mesmo jeito. Você não precisa levar a conta |
O cadastro no Mapaprop tem a sua própria repetição
Se o seu token foi emitido a partir de uma conta Mapaprop, a propriedade é cadastrada lá sozinha. Quando isso
é interrompido, o bloco mapaprop do GET diz por quê e
POST /properties/{paId}/mapaprop tenta de novo.
state | o que fazer |
|---|---|
rejected | corrija o objeto com o PUT e depois repita: o bloco nomeia o campo |
blocked | não repita: é o estado da conta e nós resolvemos |
synced sem imagens | repita: envia apenas os acessórios, não cria a propriedade de novo |
⚠️ O que custa é a cota do seu cliente: cada chamada ao portal é cobrada dele, então tentar de novo em loop não é gratuito mesmo sendo seguro. Se um erro disse para você esperar, espere esse tempo.
🔴 E a distinção que mais confunde: o portal rejeitar o seu dado e nós não obtermos resposta não são a mesma coisa, mesmo que os dois cheguem como uma falha dessa unidade.
| O que significa | O que fazer | |
|---|---|---|
| o portal rejeitou | o seu dado ou a sua conta: falta algo, sobra algo, o anúncio ainda não existe | corrigir e voltar |
| não obtivemos resposta | não sabemos se entrou. O motivo é portal_unreachable | tentar de novo, sem mudar nada |
O que convém descartar antes de nos escrever
- O erro dizia que era TEMPORÁRIO? Se dissemos para esperar e tentar de novo —e quantos segundos—, tente isso primeiro: há rejeições que se resolvem sozinhas e não há nada a corrigir.
- Você verificou o objeto? É gratuito e responde a maioria.
- O erro nomeia um passo anterior (ficha, conexão)? Então o problema não está onde você está olhando.
- Você está usando o identificador que devolvemos, e não um seu, onde a rota pede o nosso?
- O portal suporta isso? Não todos suportam tudo, e o que não, dizemos sem gastar cota.
5 · Escreva para nós
O suporte sobe pela cadeia: o seu cliente escreve para você, e você escreve para nós. O seu cliente não precisa —nem convém— escrever para o portal por algo da integração.
O motivo é estrutural, não uma preferência nossa: o vínculo com o portal é da Mapaprop. O seu sistema não figura como integração do lado do portal, então uma reclamação apresentada em nome dele cai em uma conversa que do outro lado ninguém consegue localizar. Você escreve para nós e nós encaminhamos.
⚠️ Isso não muda o que o seu cliente contrata. A conta, o plano e o que ele paga continuam sendo diretamente com o portal — isso nunca passou por nós. O que sobe pela cadeia é o problema da integração, não a relação comercial.
dev@mapaprop.com. O que mais acelera a resposta:
- A referência que veio no erro. Com ela encontramos a sua chamada exata nos nossos registros — é a diferença entre olhar o caso e pedir que você o reproduza.
- O que você esperava e o que aconteceu, nessa ordem.
- O
clientRefe o identificador do imóvel.
Não nos mande o seu token nem a credencial do seu cliente. Não precisamos deles para diagnosticar, e se você os mandou por engano, avise para que possamos ajudá-lo a rotacioná-los.
Relacionado
- Boas práticas — os fluxos completos
- Verificar — o passo 2, o mais rentável
- Publicação — o que cada portal suporta