BETA

Consultar un cliente

GET /property-v1/customers

Devuelve la ficha del clientRef que pidas.

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

Respuesta 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" }
  }
}

Si todavía no declaraste nada, responde 404 — no un 200 con la ficha vacía, para que puedas distinguir "no existe" de "existe y está incompleta".

Los tres identificadores de la ficha, y no son lo mismo

CampoDe quién esQuién lo cambia
clientReftuyo — cómo vos identificás a tu cliente. Viaja en el header x-client-refvos, cuando quieras
customerIdde PropertyAPI — se emite al crear la ficha y es el que te devolvemos siemprenadie
mapapropCustomerIdla cuenta de Mapaprop a la que está vinculada esta fichanadie: queda fijo al crearla

mapapropCustomerId sólo aparece si la ficha está vinculada a una cuenta de Mapaprop. Se toma de tu token al crear la ficha, así que no se manda en el cuerpo y el PUT no lo modifica. Si tu token no representa a una cuenta de Mapaprop, el campo no viene — y eso es normal, no un dato faltante.

La cuenta de tu cliente en cada portal, gratis

Si tu cliente tiene conectado algún portal, la respuesta trae además un bloque portals al lado de customer, con quién es en cada uno y lo último que leímos de su cuenta:

{
  "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 lectura no cuesta nada: sale de nuestro sistema, no del portal.

CampoQué es
statusactive si la conexión está vigente. revoked si se desconectó
portalAccountIdQuién es tu cliente en ese portal. Se emite también cuando la conexión está revoked: es el dato que te permite reconectarlo a la misma cuenta
plansLos planes de publicación y cuántos le quedan libres. null si nunca los leímos
plansReadAtDe cuándo es esa lista
plansStaletrue = hubo una publicación o una baja después de esa lectura
quotaLas llamadas mensuales que le quedan a tu cliente en el portal

portalAccountId significa cosas distintas según el portal, y lo decide el portal. En Argenprop es el identificador que él le dio a la inmobiliaria (310578). En Zonaprop es el código que asignamos nosotros (MAPAPROP-PA-000002), porque ahí el código lo ponemos nosotros al crear el cliente.

No todos los portales informan planes ni cupo, porque no todos funcionan igual. Argenprop no trabaja con planes: trabaja con puntos de un abono que tu cliente reparte entre sus avisos para posicionarlos. Por eso ahí plans y quota van a ser null siempre — no describen lo que Argenprop tiene.

🆕 Pero el saldo de puntos sí se consulta, en pagar por posición: ahí está cuántos le quedan, con la fecha en que lo leímos. El portalAccountId y el status los tenés para todos. Detalle: Argenprop.

Mirá plansReadAt y plansStale antes de decidir con plans. Son una copia, no el estado en vivo: si tu cliente publica desde el panel del portal, su cupo baja y nosotros no nos enteramos.

Cuando plansStale es true y te importa el número exacto, actualizalo contra el portal — eso sí gasta una llamada.

plans: null y plans: [] no significan lo mismo: null es "nunca los leímos"; [] es "los leímos y no tiene ninguno con cupo".

El bloque se omite si tu cliente no tiene conexiones, y sólo trae los portales para los que tu token está habilitado — igual que GET /connections.

Los dos 404

Tu chequeo de "¿existe?" no cambia: los dos son 404. Lo que cambia es el cuerpo, porque el arreglo es distinto en cada caso.

Nunca lo declaraste

{
  "error": "No hay una inmobiliaria declarada para este clientRef",
  "detail": "Creala con POST /property-v1/customers antes de dar de alta propiedades."
}

→ POST, y recibís un customerId nuevo.

Lo diste de baja

{
  "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"
}

→ el mismo POST lo reactiva, y recupera el customerId que ya tenía.

Si tu integración distingue los dos casos, mirá el campo error: customer_deleted te dice que el cliente existió y que vas a recuperar su id. El otro 404 te dice que vas a recibir uno nuevo.

Códigos de respuesta

CódigoQué pasó
200La ficha
400Falta el header x-client-ref
401Token ausente o inválido
403Tu token no tiene el scope property-api-read
404No hay ficha usable — los dos casos de arriba

Relacionado