BETA

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.

PortalValor de {portal}Situação
Zonapropzonapropapidisponível
Argenpropargenpropapidisponível
Mapapropmapapropapidisponí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:

  1. A ficha do seu cliente — Clientes
  2. A conta do portal dele conectada — Conectar com um link
  3. O imóvel cadastrado, com o seu paId — Cadastro de imóveis

A chamada

CampoTipoObrigatórioDescrição
planstringdepende do portalO plano de publicação. Sobrepõe o que você tenha colocado em publication dentro do objeto
branchobjetonãoOs 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 branchO que é
agentEmailO corretor responsável pelo anúncio no portal
nameO nome exibido como contato
emailO e-mail exibido como contato
phone1O 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
  }
}
CampoO que é
requestedO plano que realmente viajou ao portal. Se você deixou um fixo no objeto e enviou outro na chamada, aqui vê o que foi usado
availablePlansOs 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

statusO que significa
publishedTodos os anúncios saíram
partialAlguns sim e outros não. development.codesWithError diz quais
failedNenhum saiu. O portal rejeitou a publicação
receivedO 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="
}
CampoO que é
retryAfterSegundos que sugerimos esperar antes de tentar de novo. Depende do que você publicou (veja abaixo)
referenceO 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ê publicouretryAfter
Um anúncio avulso, ou um empreendimento com menos de 16 unidades60
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" }
  ]
}
ListaO que significaQuem resolve
blockersfalta um dado do imóvelvocê: corrija o objeto e tente de novo
accountBlockersfalta 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:

sourceDe onde saiO que fazer
customera ficha do clientecomplete-a com PUT /customers — o campo vem em fix
publicationvocê declara por imóvelenvie em publication.api.{portal}
connectiono vínculo do cliente com o portala conta não está vinculada: solicite um link de conexão
mapapropnó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ódigoO que aconteceuO que fazer
200Publicado—
400O portal ainda não está disponível, ou o body não é JSON válidoConfira o valor de {portal}
403O seu token não tem o escopo {portal}:publishEscreva para nós para habilitá-lo
404Esse imóvel não existe para este clienteConfira o paId e o x-client-ref
409A conta não está conectada ao portalSolicite um link de conexão
409O cliente está com baixa (customer_not_active)Reative-o com POST /property-v1/customers — veja Clientes
409Falta uma escolha de publicação (publication_data_missing)Veja acima: cada faltante vem com o seu fix
409Faltam dados da conta (account_data_missing)Veja acima: cada faltante vem com o seu fix
409O portal ainda está processando a publicação anterior desse código (portal_processing)Espere e tente de novo — vem com retryAfter
409O 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
409O 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
422Falta um dadoVeja acima
502O portal recusou a publicação, ou não respondeuVeja 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 detail informa isso, e o reference identifica a sua chamada.
  • Não respondeu → o detail informa 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