Consultar um cliente
GET /property-v1/customers
Devolve a ficha do clientRef que você pedir.
curl https://property-api.mapaprop.com/property-v1/customers \
-H "Authorization: Bearer $TOKEN" \
-H "x-client-ref: cliente-42"
Resposta 200:
{
"customer": {
"customerId": "MAPAPROP-PA-000002",
"clientRef": "cliente-42",
"mapapropCustomerId": 11431,
"createdAt": "2026-10-01T02:54:30.980Z",
"updatedAt": "2026-10-01T02:54:30.980Z",
"name": "Inmobiliaria Modelo",
"phone1": "2234567890",
"email": "contacto@inmobiliaria-modelo.test",
"country": 1,
"branch": { "name": "Sucursal Centro", "phone1": "2234567891" }
}
}
Se você ainda não declarou nada, responde 404 — e não um 200 com a ficha vazia, para que você possa
distinguir "não existe" de "existe e está incompleta".
Os três identificadores da ficha, e não são a mesma coisa
| Campo | De quem é | Quem muda |
|---|---|---|
clientRef | seu — como você identifica seu cliente. Viaja no cabeçalho x-client-ref | você, quando quiser |
customerId | da PropertyAPI — emitido ao criar a ficha, e é o que sempre devolvemos | ninguém |
mapapropCustomerId | a conta do Mapaprop à qual esta ficha está vinculada | ninguém: fica fixo na criação |
mapapropCustomerId só aparece se a ficha estiver vinculada a uma conta do Mapaprop. É tomado do
seu token ao criar a ficha, então você não o envia no corpo e o PUT não o modifica. Se o seu token
não representa uma conta do Mapaprop, o campo não vem — e isso é normal, não um dado faltante.
A conta do seu cliente em cada portal, de graça
Se o seu cliente tiver algum portal conectado, a resposta traz também um bloco portals ao lado de
customer, com quem ele é em cada um e a última coisa que lemos da conta dele:
{
"customer": { "...": "..." },
"portals": {
"zonapropapi": {
"status": "active",
"portalAccountId": "MAPAPROP-PA-000002",
"plans": [
{ "plan": "DESARROLLOS_HOME", "planTotal": 5, "planAvailable": 1 },
{ "plan": "HOME", "planTotal": 80, "planAvailable": 31 }
],
"plansReadAt": "2026-10-07T19:32:22.698Z",
"plansStale": true,
"quota": { "remaining": 1333, "limit": 1500, "readAt": "2026-10-07T19:33:43.600Z" }
},
"argenpropapi": {
"status": "active",
"portalAccountId": "310578",
"plans": null,
"plansReadAt": null,
"plansStale": false,
"quota": null
}
}
}
Esta leitura não custa nada: sai do nosso sistema, não do portal.
| Campo | O que é |
|---|---|
status | active se a conexão estiver vigente. revoked se foi desconectada |
portalAccountId | Quem é o seu cliente nesse portal. Também é emitido quando a conexão está revoked: é o dado que permite reconectá-lo à mesma conta |
plans | Os planos de publicação e quantos ainda estão livres. null se nunca os lemos |
plansReadAt | De quando é essa lista |
plansStale | true = houve uma publicação ou uma baixa depois dessa leitura |
quota | As chamadas mensais que restam ao seu cliente no portal |
portalAccountId significa coisas diferentes conforme o portal, e quem decide é o portal. No
Argenprop é o identificador que ele deu à imobiliária (310578). No Zonaprop é o código que
nós atribuímos (MAPAPROP-PA-000002), porque lá o código é posto por nós ao criar o cliente.
Não todos os portais informam planos nem cota, porque não todos funcionam igual. O Argenprop não
trabalha com planos: trabalha com pontos de uma assinatura que o seu cliente reparte entre os
anúncios dele para posicioná-los. Por isso ali plans e quota vão ser sempre null — eles não
descrevem o que o Argenprop tem.
🆕 Mas o saldo de pontos PODE ser consultado, em
pagar por posição: ali está quantos restam, com a
data em que lemos. O portalAccountId e o status você tem para todos. Detalhe:
Argenprop.
Olhe plansReadAt e plansStale antes de decidir com plans. São uma cópia, não o estado ao
vivo: se o seu cliente publicar a partir do painel do portal, a cota dele baixa e nós não ficamos
sabendo.
Quando plansStale for true e o número exato importar para você,
atualize-o contra o portal — isso sim gasta uma chamada.
plans: null e plans: [] não significam a mesma coisa: null é "nunca os lemos"; [] é "nós os
lemos e não tem nenhum com cota".
O bloco é omitido se o seu cliente não tiver conexões, e só traz os portais para os quais o seu
token está habilitado — igual a GET /connections.
Os dois 404
A sua verificação de "existe?" não muda: os dois são 404. O que muda é o corpo, porque a correção
é diferente em cada caso.
Você nunca o declarou
{
"error": "No hay una inmobiliaria declarada para este clientRef",
"detail": "Creala con POST /property-v1/customers antes de dar de alta propiedades."
}
→ POST, e você recebe um customerId novo.
Você deu baixa nele
{
"error": "customer_deleted",
"detail": "Esta inmobiliaria fue dada de baja el 2026-10-01T18:22:04.117Z. Volvé a crearla con POST /property-v1/customers: recupera el mismo customerId (MAPAPROP-PA-000002) y sus propiedades.",
"deletedAt": "2026-10-01T18:22:04.117Z",
"customerId": "MAPAPROP-PA-000002"
}
→ o mesmo POST o reativa, e ele recupera o customerId que
já tinha.
Se a sua integração distingue os dois casos, olhe o campo error: customer_deleted diz que o
cliente existiu e que você vai recuperar o id dele. O outro 404 diz que você vai receber um novo.
Códigos de resposta
| Código | O que aconteceu |
|---|---|
200 | A ficha |
400 | Falta o header x-client-ref |
401 | Token ausente ou inválido |
403 | O seu token não tem o scope property-api-read |
404 | Não há ficha utilizável — os dois casos acima |