DEVELOPING

Os planos do seu cliente no portal

GET /property-v1/customers/{portal}/account

Ao publicar, você envia um plan. Para escolhê-lo precisa saber quais planos o seu cliente tem e quantas publicações ainda lhe restam livres — e esse dado fica no portal, não no nosso sistema.

Você o tem em dois lugares, e convém usar os dois:

Onde	O que lhe dá	Custa
`GET /property-v1/customers`	A última coisa que lemos, com a data	nada
`GET /property-v1/customers/{portal}/account`	O que o portal diz agora, e atualiza o anterior	1 chamada da cota do seu cliente

O caminho barato é pedir o cliente —que é gratuito— e olhar o campo plansStale. Se disser true, houve uma publicação ou uma baixa depois dessa leitura; é aí que você decide se gasta a chamada.

Como se pede

curl https://property-api.mapaprop.com/property-v1/customers/zonapropapi/account \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: cliente-42"

Resposta 200:

{
  "portal": "zonapropapi",
  "portalAccountId": "17064147",
  "plans": [
    { "plan": "DESARROLLOS_HOME", "planTotal": 5,  "planAvailable": 1 },
    { "plan": "HOME",             "planTotal": 80, "planAvailable": 31 },
    { "plan": "SIMPLE",           "planTotal": 80, "planAvailable": 20 }
  ],
  "plansReadAt": "2026-10-07T19:32:22.975Z",
  "plansStale": false,
  "planExpirations": [
    { "plan": "HOME", "date": "2026-12-31T03:00:00.000Z", "quantity": 85 }
  ],
  "cached": true
}

Campo	O que é
`plans[].plan`	O nome do plano, tal como o portal o chama. É o valor que você envia como `plan` ao publicar
`plans[].planTotal`	Quantos tem contratados. Pode vir `null` se o portal não informar
`plans[].planAvailable`	Quantas publicações ainda lhe restam livres
`plansReadAt`	Quando lemos isto do portal
`plansStale`	`false` aqui sempre: acabamos de ler
`planExpirations`	Quando vencem e quantos. É omitido se o portal não informar nenhum
`cached`	Se guardamos a cópia. Em `false`, a leitura gratuita vai continuar lhe dando a anterior

O portal só lista os planos que têm cota. Um plano que o seu cliente contratou mas já esgotou não aparece na lista. Por isso "não está em plans" não significa "não o tem contratado": pode significar as duas coisas, e o portal não as distingue.

É isso que torna confuso o erro de publicação por plano: diz "a empresa tem utilizados todos os seus disponíveis" e se lê como se a conta estivesse sem nada.

Onde se encaixa no fluxo

1. POST /property-v1/customers                   você declara o cliente
2. conecta a conta dele no portal                 ← é aqui que entram os planos, sem custo extra
3. GET  /property-v1/customers                   você os vê, grátis, com a data
4. GET  /property-v1/customers/{portal}/account   você os atualiza contra o portal   (1 chamada)
5. PUT  …/publication/{portal}                   você publica

O passo 2 já guarda os planos: a chamada que verifica que o seu cliente autorizou é a mesma que os traz, então ao conectar você já os tem sem pagar nada.

Depois de cada publicação ou baixa, o passo 3 os devolve com plansStale: true.

Por que não os atualizamos sozinhos

Porque cada leitura sai da cota mensal do seu cliente no portal —que cada portal define à sua maneira; na Zonaprop são 1.500 chamadas— e é a mesma que você usa para publicar e para trazer consultas. Atualizar em cada publicação duplicaria o gasto da sua integração, e a decisão de quando vale a pena é sua.

E há um motivo mais forte: o portal não nos diz qual plano uma publicação consumiu. A resposta dele traz o código do anúncio, o id e os erros — nenhum plano. Se subtraíssemos o que você pediu poderíamos subtrair o errado, então preferimos avisar que a cópia ficou velha em vez de lhe dar um número inventado.

Se você nunca o chamar

Não acontece nada grave: você envia o seu plan ao publicar e, se o seu cliente não o tiver, a resposta do publish lhe diz quais ele tem no bloco planIssue. Este endpoint existe para que você possa consultá-lo quando quiser, não para que tenha que fazê-lo.

Códigos de resposta

Código	`error`	O que aconteceu
`200`	—	Os planos, recém-lidos do portal
`400`	`portal is required`	Falta o portal na rota
`400`	`clientRef is required (header x-client-ref)`	Falta identificar o cliente
`401`	`Unauthorized`	Token ausente ou inválido
`403`	`Missing scope: property-api-read`	O seu token não pode ler
`403`	`Missing required scope: zonapropapi:connect`	O seu token não está habilitado para esse portal
`409`	`portal_not_connected`	O seu cliente não tem uma conexão ativa com esse portal
`409`	`connection_incomplete`	A conexão existe mas está incompleta. Conecte-a novamente
`501`	`portal_sin_consulta_de_cuenta`	Ainda não consultamos a conta nesse portal
`502`	`portal_no_contesto`	O portal não respondeu. Tente de novo; não sobrescrevemos a cópia anterior

O 502 não apaga o que já tínhamos. Guardar uma lista vazia porque o portal não respondeu diria que o seu cliente não tem planos, e isso seria falso. A cópia anterior continua disponível no GET do cliente com a data.

Portais

Portal	`{portal}`	Estado
Zonaprop	`zonapropapi`	disponível
Argenprop · Cabaprop · MercadoLibre	—	`501`

Um 501 não significa que você errou: significa que esse portal ainda não tem esta consulta do nosso lado.

Relacionado

GET do cliente — a leitura gratuita, com plansStale
Publicar — onde se envia o plan e o que diz planIssue
Cota mensal e limites — as 1.500 chamadas