BETA

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

CampoDe quem éQuem muda
clientRefseu — como você identifica seu cliente. Viaja no cabeçalho x-client-refvocê, quando quiser
customerIdda PropertyAPI — emitido ao criar a ficha, e é o que sempre devolvemosninguém
mapapropCustomerIda conta do Mapaprop à qual esta ficha está vinculadaningué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.

CampoO que é
statusactive se a conexão estiver vigente. revoked se foi desconectada
portalAccountIdQuem é o seu cliente nesse portal. Também é emitido quando a conexão está revoked: é o dado que permite reconectá-lo à mesma conta
plansOs planos de publicação e quantos ainda estão livres. null se nunca os lemos
plansReadAtDe quando é essa lista
plansStaletrue = houve uma publicação ou uma baixa depois dessa leitura
quotaAs 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ódigoO que aconteceu
200A ficha
400Falta o header x-client-ref
401Token ausente ou inválido
403O seu token não tem o scope property-api-read
404Não há ficha utilizável — os dois casos acima

Relacionado