BETA

Declarar un cliente

POST /property-v1/customers

Es el primer paso de todo: sin ficha no se puede dar de alta una propiedad, ni pedir un enlace de conexión, ni publicar.

El clientRef dice de qué cliente es la ficha, igual que en el resto de la API: va en el header x-client-ref (recomendado), en la query o en el body.

Lo mínimo que funciona son el nombre y el contacto:

curl -X POST https://property-api.mapaprop.com/property-v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: cliente-42" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Inmobiliaria Modelo",
        "email": "contacto@inmobiliaria-modelo.test",
        "phone1": "2234567890" }'

Y la ficha completa, con todo lo que se publica en el aviso:

{
  "name": "Inmobiliaria Modelo",
  "phone1": "2234567890",
  "mobile": "2235550000",
  "email": "contacto@inmobiliaria-modelo.test",
  "address": "Av. Colón 1234",
  "country": 1,
  "branch": {
    "email": "centro@inmobiliaria-modelo.test",
    "phone1": "2234567891",
    "name": "Sucursal Centro",
    "address": "San Martín 2500"
  }
}

Respuesta 201:

{
  "created": true,
  "customer": {
    "customerId": "MAPAPROP-PA-000002",
    "clientRef": "cliente-42",
    "createdAt": "2026-10-01T02:54:30.980Z",
    "updatedAt": "2026-10-01T02:54:30.980Z",
    "name": "Inmobiliaria Modelo",
    "phone1": "2234567890",
    "mobile": "2235550000",
    "email": "contacto@inmobiliaria-modelo.test",
    "address": "Av. Colón 1234",
    "country": 1,
    "branch": {
      "name": "Sucursal Centro",
      "phone1": "2234567891",
      "email": "centro@inmobiliaria-modelo.test",
      "address": "San Martín 2500"
    }
  }
}

Los campos

CampoTipo¿Obligatorio?
namestringsíEl nombre del cliente, como sale en el aviso
emailstringsí ⁽¹⁾El email al que llegan las consultas
phone1stringsí ⁽¹⁾El teléfono de contacto
phone2stringnoUn segundo teléfono
mobilestringnoEl móvil (en MercadoLibre va como segundo teléfono)
addressstringnoLa dirección
zipcodestringnoEl código postal
countrynumbernoEl país del cliente
branchobjectnoLa sucursal — ver abajo
branchesarraynoVarias sucursales, cada una con su branchRef — ver abajo

⁽¹⁾ email y phone1 valen en el cliente o en su branch — no hace falta repetirlos. Si declarás sólo la sucursal, con que estén ahí alcanza.

Los campos de texto admiten hasta 256 caracteres.

Por qué email y phone1 son obligatorios acá y no al publicar. Son el contacto que sale publicado en cada aviso: sin ellos, el portal no tiene a dónde mandarle las consultas al cliente.

Se te dicen en esta llamada —la única donde estás mirando los datos del cliente— en vez de tres pasos más tarde, cuando POST /publication ya no los encuentra.

Los nombres de clave son los mismos que usa el objeto de la propiedad, así que el bloque que ya armabas sirve tal cual. Lo que cambió es a dónde lo mandás: acá una vez, en vez de en cada alta.

La sucursal es opcional

Si no mandás branch, la sucursal hereda los datos del cliente. No es una comodidad nuestra: es lo que hace Mapaprop cuando se crea una cuenta, y es la razón de que 96 de cada 100 inmobiliarias tengan una sola sucursal con los mismos datos.

La herencia es campo por campo, no todo o nada: una sucursal que declara sólo su nombre se queda con el teléfono y el email del cliente. Por eso declararla no te obliga a repetir el resto.

Varias sucursales: branches

Si tu cliente tiene más de una oficina y querés que cada propiedad salga publicada con los datos de la suya, declarálas en branches. Cada una lleva una referencia que elegís vos (branchRef), y es con esa referencia que después la propiedad dice cuál quiere:

{
  "name": "Inmobiliaria López",
  "email": "info@lopez.com",
  "phone1": "3414445566",
  "branches": [
    { "branchRef": "centro", "name": "Centro", "email": "centro@lopez.com", "phone1": "3414445566" },
    { "branchRef": "norte",  "name": "Norte",  "email": "norte@lopez.com",  "phone1": "3415556677" }
  ]
}

Y al dar de alta la propiedad:

{ "canonical": { }, "portals": ["zonapropapi"], "branchRef": "norte" }
CampoTipoObligatorioQué es
branchRefstringsíTu referencia para esa sucursal. La elegís vos y no cambia nunca
mapapropBranchIdnumbernoEl id de la sucursal en Mapaprop, si tu cliente tiene cuenta — ver abajo

El resto de los campos son los mismos que branch. Hasta 50 sucursales por cliente.

La referencia tiene que ser única dentro del cliente: dos sucursales con el mismo branchRef se rechazan, porque entonces la propiedad no podría decir cuál quiere.

branch y branches conviven. Si ya usabas branch, no tenés que cambiar nada: sigue funcionando igual, y una propiedad que no manda branchRef publica con ella.

Si declarás branches y no declarás branch, cada propiedad tiene que mandar su branchRef: sin una sucursal por defecto no hay forma de saber cuál querés, y no elegimos por vos.

Si tu cliente tiene cuenta de Mapaprop (o si sos vos)

Lo más simple: no declares nada. Si la sucursal ya existe en Mapaprop, mandá su branchId como branchRef al dar de alta la propiedad y listo:

{ "canonical": { }, "branchRef": 777 }

Ese número es el que ves en tu cuenta, y lo leés con GET /branches. No hace falta declararlo en la ficha ni ponerle un nombre tuyo.

Ponerle TU nombre es opcional, y sirve si tu código prefiere hablar de "centro" en vez de un número:

{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }

Entonces sus sucursales ya existen y las edita en Mapaprop. En ese caso no repitas sus datos acá: declará sólo el vínculo entre tu referencia y su id real, que podés leer con GET /branches:

{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }

Los datos de contacto de esa sucursal salen de Mapaprop, no de lo que declares acá. Es lo que evita que queden dos versiones del mismo teléfono y que una de las dos quede vieja.

CampoTipo
name phone1 phone2 mobile email address zipcodestring
zone0 zone1 zone2 zone3number — los códigos de zona

Y si todavía no existen en Mapaprop, las creamos

Esto es para un cliente de Mapaprop automatizando su propia cuenta (el adicional Property API). Si declarás una sucursal con sus datos y sin mapapropBranchId, la creamos en tu cuenta y te devolvemos su id, ya vinculado a tu referencia:

{
  "branches": {
    "created": [ { "branchRef": "norte", "mapapropBranchId": 779 } ],
    "failed": []
  },
  "customer": { "…" }
}

A partir de ahí esa sucursal es una más de tu cuenta: la ves en Mapaprop, la editás donde quieras, y tus propiedades la eligen con branchRef: "norte".

Qué declarásQué pasa
branchRef + datos, sin mapapropBranchIdse crea en tu cuenta y te devolvemos el id
branchRef + mapapropBranchIdya existe: sólo se guarda el vínculo, no se toca
branchRef solo, sin datosno se crea nada — sería una sucursal vacía

Si una falla, las demás se crean igual. Cada sucursal es su propia operación: failed te dice cuáles no entraron y por qué — el cupo de sucursales de tu plan, una zona que no existe, un dato inválido. Corregís esas y repetís el PUT: las que ya se crearon no se duplican.

Esto no aplica si tus clientes no tienen cuenta de Mapaprop. Ahí sus sucursales viven en la ficha y no hay nada que crear en ningún otro lado — que es el caso de la mayoría de los integradores.

Repetir el POST es seguro

Un POST sobre un cliente que ya existe no emite otro id ni pisa los datos: devuelve la ficha que hay con created: false y status 200. Eso hace que un reintento por timeout sea seguro.

Para cambiar los datos está el PUT, que nunca toca el id.

Y reactiva un cliente dado de baja

Si el cliente estaba dado de baja, el mismo POST lo reactiva. Respuesta 200 con revived: true:

{
  "created": false,
  "revived": true,
  "customer": {
    "customerId": "MAPAPROP-PA-000002",
    "clientRef": "cliente-42",
    "name": "Inmobiliaria Modelo",
    "email": "contacto@inmobiliaria-modelo.test",
    "phone1": "2234567890",
    "revivedAt": "2026-10-02T11:05:41.882Z"
  }
}

Vuelve con el mismo customerId, así que sus avisos publicados siguen siendo suyos. Los datos que mandes en ese POST son los que quedan.

Códigos de respuesta

CódigoQué pasóQué hacer
201Se creó la ficha—
200Ya existía (created: false) o se reactivó (revived: true)—
400Falta name, email o phone1; country no es un entero positivo; branch no es un objeto; branches no es un array, o una de sus entradas no tiene branchRef, lo repite o pasa de 50; o un texto pasa de 256 caracteresEl campo viene en field
400Falta el clientRefMandá el header x-client-ref: sin él no sabemos de qué cliente es la ficha, y no lo adivinamos
401Token ausente o inválido—
403Tu token no tiene el scope property-api-createEscribinos para habilitarlo

Relacionado