Publicar em um portal
Quando o imóvel já está cadastrado e a conta do portal conectada, isto o publica.
PUT /property-v1/properties/{paId}/publication/{portal}
Você não envia o imóvel de novo: nós já o temos, e o publicamos exatamente como ficou salvo. Nós o traduzimos para o formato do portal.
| Portal | Valor de {portal} | Situação |
|---|---|---|
| Zonaprop | zonapropapi | disponível |
| Argenprop | argenpropapi | disponível |
| Mapaprop | mapapropapi | disponível — não é um portal externo |
| Cabaprop, MercadoLibre | — | ainda não |
Requer o escopo {portal}:publish — por exemplo zonapropapi:publish. É diferente do :connect: você pode estar habilitado para conectar contas de um portal e não para publicar nele.
Antes de publicar
Três coisas, nesta ordem:
- A ficha do seu cliente — Clientes
- A conta do portal dele conectada — Conectar com um link
- O imóvel cadastrado, com o seu
paId— Cadastro de imóveis
A chamada
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
plan | string | depende do portal | O plano de publicação. Sobrepõe o que você tenha colocado em publication dentro do objeto |
branch | objeto | não | Os dados de contato deste anúncio. Sobrepõem, campo a campo, os da ficha do cliente |
curl -X PUT https://property-api.mapaprop.com/property-v1/properties/01M3PTZ8YBMM5DSNW03WP8VD9E/publication/zonapropapi \
-H "Authorization: Bearer <SEU_TOKEN>" \
-H "x-client-ref: cliente-42" \
-H "Content-Type: application/json" \
-d '{ "plan": "SUPERDESTACADO" }'
Resposta 200:
{
"status": "published",
"portal": "zonapropapi",
"paId": "01M3PTZ8YBMM5DSNW03WP8VD9E",
"plan": "SUPERDESTACADO",
"quota": { "remaining": 1493, "limit": 1500 }
}
O contato do anúncio
Por padrão, o anúncio sai com os dados de contato que você declarou na ficha do seu cliente
(customer.branch), congelados quando você cadastrou o imóvel. Se quiser que este anúncio saia
com outros, envie-os em branch:
curl -X PUT https://property-api.mapaprop.com/property-v1/properties/01M3PTZ8YBMM5DSNW03WP8VD9E/publication/zonapropapi \
-H "Authorization: Bearer <SEU_TOKEN>" \
-H "x-client-ref: cliente-42" \
-H "Content-Type: application/json" \
-d '{
"plan": "SUPERDESTACADO",
"branch": {
"agentEmail": "carina@inmobiliaria.com",
"name": "Carina Milesse",
"email": "ventas@inmobiliaria.com",
"phone1": "5493425067641"
}
}'
Campo de branch | O que é |
|---|---|
agentEmail | O corretor responsável pelo anúncio no portal |
name | O nome exibido como contato |
email | O e-mail exibido como contato |
phone1 | O telefone exibido como contato |
Os quatro são opcionais e se resolvem um a um. O que você envia vence; o que você não envia continua saindo da ficha. Assim dá para mudar apenas o telefone de um anúncio sem repetir o resto.
Há uma exceção: se você enviar email sem agentEmail, o assessor passa a ser esse mesmo
endereço. O assessor não fica com o da ficha — ele segue o email que você enviou. Para mudar
o endereço de contato sem tocar no assessor, envie os dois.
agentEmail precisa ser um usuário que exista na conta do portal.
Não é texto livre como os outros três: o portal o resolve a partir dos usuários daquela conta. Se
você enviar um endereço que não pertence a nenhum deles, o portal não devolve erro: substitui
em silêncio pelo do administrador da conta, e a publicação sai 200.
Para saber quais usuários o seu cliente tem cadastrados, veja o painel dele no portal. E leve em conta que os usuários são criados lá, não por esta API.
O portal não verifica se os quatro campos contam a mesma história. Dá para publicar com o corretor de uma pessoa e o nome e o telefone de outra, e a publicação sai do mesmo jeito. A coerência é sua: se você escolher um corretor, convém enviar também o nome e o telefone dele.
O plan também pode ficar fixo no objeto, em publication. Se você enviar os dois, vence o desta chamada: assim dá para trocar de plano sem reescrever o imóvel.
O plan da resposta é o que ENVIAMOS, não necessariamente o que o portal atribuiu. É o que
realmente viajou —então, se você o deixou fixo no objeto, você o vê aqui mesmo sem tê-lo enviado na
chamada—, mas o portal pode atribuir outro: medimos isso na Zonaprop com anúncios soltos.
O plano que ficou vem na consulta de estado, em
publicationState. Dizemos isso em vez de calar porque programar supondo que o pedido é o atribuído
quebra o seu faturamento, não a sua tela.
Para saber quais planos o seu cliente tem e quantos lhe restam livres, veja
os planos do seu cliente: a leitura gratuita sai do
GET do cliente e não lhe custa nada.
Isto vale para o plan e somente para o plan. Os outros campos de publication —os dados da sua
conta no portal, como o anunciante ou a filial— seguem a regra inversa: vence o que o objeto
declara, porque ali o objeto é a fonte de verdade da sua própria configuração. O plan é uma decisão
desta publicação; os dados de conta são da propriedade.
Quando o portal rejeita um plano, a mensagem dele engana: diz "a empresa utilizou todos os seus disponíveis", o que soa como se o seu cliente tivesse ficado sem cota. Quase sempre é outra coisa: aquele plano não está contratado naquela conta.
Então traduzimos, com a lista dos que ela tem:
{
"status": "failed",
"planIssue": {
"requested": "DESARROLLOS_DESTACADO",
"portalError": "ERR-0502",
"detail": "El portal rechazó la publicación por el plan `DESARROLLOS_DESTACADO`: o no está contratado en esa cuenta, o no tiene publicaciones disponibles. Los planes disponibles son: DESARROLLOS_HOME.",
"availablePlans": [{ "plan": "DESARROLLOS_HOME", "disponible": 1 }],
"youCanFixIt": true
}
}
| Campo | O que é |
|---|---|
requested | O plano que realmente viajou ao portal. Se você deixou um fixo no objeto e enviou outro na chamada, aqui vê o que foi usado |
availablePlans | Os que a conta tem com publicações disponíveis. Pode não vir se o portal não nos respondeu |
O bloco só aparece quando o portal rejeita por causa do plano, e não custa nem uma chamada ao seu cliente: a lista sai da última leitura que temos guardada, não do portal.
Nós nunca consultamos os planos no portal por conta própria — a cota de chamadas é do seu cliente, e quando gastá-la é você quem decide, com a consulta de conta.
É por isso que a lista vem com availablePlansReadAt: é uma cópia, não o estado ao vivo. Se o seu
cliente publicou a partir do painel do portal, a cota dele baixou e nós não ficamos sabendo.
Se ainda não lemos os planos dele, a mensagem diz isso e nomeia o endpoint — em vez de lhe dar uma lista vazia que pareceria dizer que ele não tem nenhum.
E o mesmo quando o plano FALTA
Se você não enviar plan em lugar nenhum, a resposta é um 409 publication_data_missing — e o item do plano
que falta também traz a lista:
{
"error": "publication_data_missing",
"missing": [{
"field": "plan",
"fix": "Mandalo en el objeto, en \"publication.api.zonaprop.plan\". Esta cuenta tiene disponible (nuestra última lectura, 2026-10-07T20:35:15.020Z): HOME (31 de 80), SIMPLE (20 de 80).",
"availablePlans": [{ "plan": "HOME", "disponible": 31, "contratado": 80 }],
"availablePlansReadAt": "2026-10-07T20:35:15.020Z"
}]
}
Depois de publicar, a cópia dos planos dele fica velha
Publicar consome um plano, então a lista que tínhamos guardada deixa de estar atualizada. Em vez de
descontá-la por nossa conta, nós a marcamos: o GET do cliente
a devolve com plansStale: true.
Não subtraímos nada, e é de propósito: o portal não nos diz qual plano consumiu —a resposta dele traz o código do anúncio, o id e os erros, nenhum plano— e, para um anúncio solto, pode atribuir um diferente do que você pediu. Subtrair o pedido seria subtrair o errado.
Por isso lhe dizemos "isto é das 19:32 e desde então você publicou", e você decide se o atualiza contra o portal —o que custa 1 chamada— ou se a cópia já lhe basta.
O mesmo vale ao dar baixa: ali o plano volta para a cota, e a cópia envelhece do mesmo jeito.
Um publish que falha não marca a cópia como velha: se o portal rejeitou tudo, não consumiu nenhum plano e não há nada que tenha mudado.
Os quatro valores de status
status | O que significa |
|---|---|
published | Todos os anúncios saíram |
partial | Alguns sim e outros não. development.codesWithError diz quais |
failed | Nenhum saiu. O portal rejeitou a publicação |
received | O portal o recebeu e ainda está processando (empreendimentos de 16 unidades ou mais). Não é published |
Um 200 quer dizer que a chamada passou, não que o anúncio ficou online. São duas coisas
distintas: a chamada pode se completar perfeitamente e o portal ainda assim rejeitar o anúncio — por
exemplo porque o seu cliente não tem publicações disponíveis — e isso chega a você como
status: "failed" com um 200. Programe contra o status, não contra o código HTTP.
Por que um 200 e não um erro: a falha não é sua nem nossa, e a resposta traz informação útil (o
detalhe anúncio por anúncio). Um 4xx faria você descartá-la.
partial e failed existem desde 2026-10-07. Antes, uma publicação que o portal rejeitava
inteira chegava a você como published — o status só olhava se o caminho era direto ou diferido.
Se você tem um switch sobre status, adicione os dois casos.
Chamar de novo ATUALIZA, não duplica
Publicar o mesmo imóvel duas vezes não cria dois anúncios. A segunda chamada atualiza o que já existe. Você pode tentar de novo sem medo: se uma chamada falhou e você não sabe se chegou, chame outra vez.
É a propriedade mais importante deste endpoint, e o motivo de não haver um "criar" e um "atualizar" separados: uma única operação, e o resultado depende de o anúncio já existir ou não.
Mas não todo campo pode ser alterado em um anúncio que já existe
Atualizar não é o mesmo que criar: há campos que o portal fixa ao publicar e depois não deixa mover. Quais são é decidido pelo portal, então estão na tabela de o que muda em cada portal.
No Argenprop, por exemplo, o re-publish atualiza tudo — preço, zona, área, fotos — menos o
type: o tipo de imóvel fica fixo no anúncio. Se mudou, o portal rejeita a escrita e a saída é
dar baixa e publicar novamente, o que cria o anúncio de
novo com o tipo correto.
Corrigir a zona de um anúncio já publicado passa sim por este endpoint no Argenprop: não é preciso dar baixa. É a diferença em relação a portais que fixam a zona ao criar o anúncio.
Mas existe uma janela: o portal processa um código por vez
Enquanto o portal está processando uma publicação, uma segunda escrita sobre o mesmo código não entra. É um bloqueio do portal, por código, e dura o tempo que ele levar para terminar a anterior.
Respondemos isso como 409 portal_processing, que é o sinal de tente de novo:
{
"error": "portal_processing",
"detail": "El portal todavía está procesando la publicación anterior de este código. Reintentá en unos segundos: la operación es idempotente y no duplica el aviso.",
"retryAfter": 60,
"reference": "Ks9dLm2xIAMEXAMPLE="
}
| Campo | O que é |
|---|---|
retryAfter | Segundos que sugerimos esperar antes de tentar de novo. Depende do que você publicou (veja abaixo) |
reference | O identificador desta chamada, caso o 409 nunca se resolva |
retryAfter não é um número fixo: a janela do portal é muito mais longa quando ele processa um lote.
| O que você publicou | retryAfter |
|---|---|
| Um anúncio avulso, ou um empreendimento com menos de 16 unidades | 60 |
| Um empreendimento com 16 unidades ou mais (o portal o processa de forma diferida) | 600 |
É um 409 e não um 502 de propósito. Um 502 diz "o portal falhou" e a maioria dos
clientes HTTP trata isso como erro do servidor: é descartado e não é repetido. Isto é um
conflito temporário — nada falhou, você só chegou antes de a anterior terminar.
Tentar de novo é seguro: o anúncio não é duplicado.
retryAfter é uma sugestão nossa, não um dado do portal: ele não nos diz quanto falta. Os dois
números saem de medir a janela no Zonaprop: com 4 unidades um minuto foi suficiente, e com 20 ele
ainda recusava depois de oito minutos e meio. É por isso que é um valor por regime e não um só.
Se ao tentar de novo voltar o mesmo 409, não é que algo esteja quebrado — é que ainda está
processando. Use isso como ponto de partida do seu backoff e, se repetir muitas vezes, nos envie o
reference.
Com um empreendimento grande, consultar o estado NÃO diz se você já pode escrever. Com 16
unidades ou mais o portal processa de forma diferida (status: "received") e termina com o anúncio
principal muito antes de terminar com o lote: se você consultar, ele vai responder sobre o anúncio —
não sobre a trava. Medido: o estado dizia processado e o portal continuou recusando a escrita por
mais de 5 minutos.
Para essa janela, esperar e tentar de novo é o que funciona, e além disso é grátis: consultar gasta uma chamada da cota do seu cliente. Detalhes em Publicar um empreendimento.
Quando não dá para publicar: 422
Não é um erro da sua chamada — é que falta um dado. Por isso vêm duas listas separadas:
{
"error": "not_publishable",
"detail": "La propiedad no se puede publicar en este portal todavía.",
"blockers": [
{ "field": "title", "kind": "missing", "message": "Falta el título" }
],
"accountBlockers": [
{ "field": "options.zoneNaventId", "kind": "missing",
"message": "La zona de la propiedad no tiene mapeo guardado en Zonaprop" }
]
}
| Lista | O que significa | Quem resolve |
|---|---|---|
blockers | falta um dado do imóvel | você: corrija o objeto e tente de novo |
accountBlockers | falta algo da conta no portal (zona sem mapeamento, plano, filial) | resolve-se uma vez e vale para todos os imóveis daquele cliente |
Estão separadas porque a correção é diferente. Se você veio de accountBlockers, revisar o JSON do imóvel não vai levar a lugar nenhum: ele está certo.
Dá para antecipar quase todos os blockers com POST /properties/verify, que não cria nem publica nada.
Quando falta um dado da conta: 409 account_data_missing
O mapeamento saiu completo, mas com dados de exemplo. Não publicamos assim: sairia um anúncio com dados que não são do cliente.
É o caso em que a verificação deu verde e a publicação
falha. Não é uma contradição: o verify preenche os dados da conta com exemplos de propósito,
para poder responder a única coisa que você perguntou — se o seu objeto mapeia bem — mesmo que a
conta ainda não esteja configurada. Ao publicar, esse preenchimento não pode viajar.
{
"error": "account_data_missing",
"detail": "Faltan datos de la cuenta del portal para publicar de verdad. No lo mandamos con valores de ejemplo: saldría un aviso con datos que no son del cliente.",
"missing": [
{ "field": "branch.phone1", "portal": "zonaprop", "source": "customer", "youCanFixIt": true,
"fix": "Completá la inmobiliaria con PUT /property-v1/customers: \"phone1\" (en la inmobiliaria o en su \"branch\")." },
{ "field": "plan", "portal": "zonaprop", "source": "publication", "youCanFixIt": true,
"fix": "Mandalo en el objeto, en \"publication.api.zonaprop.plan\"." }
],
"reference": "a1b2c3d4-…"
}
Cada faltante diz de onde sai esse dado, porque o conserto é diferente em cada caso:
source | De onde sai | O que fazer |
|---|---|---|
customer | a ficha do cliente | complete-a com PUT /customers — o campo vem em fix |
publication | você declara por imóvel | envie em publication.api.{portal} |
connection | o vínculo do cliente com o portal | a conta não está vinculada: solicite um link de conexão |
mapaprop | nós atribuímos | é um problema nosso: envie-nos a reference |
youCanFixIt responde a única pergunta que importa: eu conserto, ou é de vocês? Se vier false,
revisar o seu JSON não vai levar a lugar nenhum.
Códigos de resposta
| Código | O que aconteceu | O que fazer |
|---|---|---|
200 | Publicado | — |
400 | O portal ainda não está disponível, ou o body não é JSON válido | Confira o valor de {portal} |
403 | O seu token não tem o escopo {portal}:publish | Escreva para nós para habilitá-lo |
404 | Esse imóvel não existe para este cliente | Confira o paId e o x-client-ref |
409 | A conta não está conectada ao portal | Solicite um link de conexão |
409 | O cliente está com baixa (customer_not_active) | Reative-o com POST /property-v1/customers — veja Clientes |
409 | Falta uma escolha de publicação (publication_data_missing) | Veja acima: cada faltante vem com o seu fix |
409 | Faltam dados da conta (account_data_missing) | Veja acima: cada faltante vem com o seu fix |
409 | O portal ainda está processando a publicação anterior desse código (portal_processing) | Espere e tente de novo — vem com retryAfter |
409 | O portal já não reconhece a conta do seu cliente como parte da sua integração (portal_account_unlinked) | Conecte-a novamente: peça um link. Tentar de novo não a recupera — costuma acontecer quando foi reconectada a partir de outro lugar, e afeta tudo daquela conta ao mesmo tempo. Veja uma única conexão por imobiliária |
409 | O portal tem a conta do seu cliente desabilitada ou bloqueada (portal_account_blocked) | Escreva para nós com o reference. Tentar de novo não a habilita e reconectar também não: o bloqueio é sobre a conta. O vínculo com o portal é gerenciado por nós, então encaminhamos a reclamação deste lado |
422 | Falta um dado | Veja acima |
502 | O portal recusou a publicação, ou não respondeu | Veja abaixo |
Os 409 não são todos iguais, e o campo error os distingue: portal_not_connected,
customer_not_active, account_data_missing e publication_data_missing pedem que você corrija algo antes de voltar;
portal_processing só pede que espere. Se tratar os quatro igual, vai repetir os que não vale
repetir e vai desistir do único que vale.
O 502, que tem dois sabores
{ "error": "portal_rejected",
"detail": "El portal rechazó la publicación. Si se repite, pasanos el `reference` y lo revisamos.",
"reference": "Ks9dLm2xIAMEXAMPLE=" }
- O portal recusou → o
detailinforma isso, e oreferenceidentifica a sua chamada. - Não respondeu → o
detailinforma isso, e pode ter sido publicado mesmo assim. Tentar de novo é seguro: não duplica.
Não dizemos "não foi publicado" quando não sabemos.
Mudou em 2026-10-08. O caso "o portal ainda está processando o anúncio anterior" chegava
aqui, como um 502 com o texto genérico — então não havia como saber que era temporário. Agora é
um 409 portal_processing com retryAfter (veja acima). Se você tem um catch que trata
qualquer 502 como definitivo, continua correto: o que é repetível saiu de lá.
O reference: guarde-o e envie para nós
Identifica aquela chamada específica. Do nosso lado registramos tudo o que o portal respondeu, de modo que com esse valor encontramos o seu caso exato sem pedir mais nada: nem logs, nem capturas de tela, nem o payload que você enviou.
Se um erro se repetir, escreva para dev@mapaprop.com com o reference e o paId.
Mudou em 2026-10-02. Esta resposta incluía um campo portalResponse com a resposta do portal
tal como vinha. Ele não é mais enviado: cada portal tem seus próprios códigos e formatos, e
programar contra eles deixa você exposto a mudanças sem aviso. No lugar dele você vai receber
erros normalizados por nós, iguais para todos os portais, mais o reference para os casos que
precisam ser vistos manualmente.
Específico de cada portal
- Zonaprop: o plano é obrigatório e cada publicação consome a cota mensal do seu cliente — Cota mensal e limites
Relacionado
- Despublicar de um portal — o
DELETE, para retirar o anúncio - A chave
publication— o que configurar dentro do objeto - Conectar com um link — conectar a conta do portal
POST /properties/verify— antecipar os blockers