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
| Campo | Tipo | ¿Obligatorio? | |
|---|---|---|---|
name | string | sí | El nombre del cliente, como sale en el aviso |
email | string | sí ⁽¹⁾ | El email al que llegan las consultas |
phone1 | string | sí ⁽¹⁾ | El teléfono de contacto |
phone2 | string | no | Un segundo teléfono |
mobile | string | no | El móvil (en MercadoLibre va como segundo teléfono) |
address | string | no | La dirección |
zipcode | string | no | El código postal |
country | number | no | El país del cliente |
branch | object | no | La sucursal — ver abajo |
branches | array | no | Varias 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" }
| Campo | Tipo | Obligatorio | Qué es |
|---|---|---|---|
branchRef | string | sí | Tu referencia para esa sucursal. La elegís vos y no cambia nunca |
mapapropBranchId | number | no | El 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.
| Campo | Tipo |
|---|---|
name phone1 phone2 mobile email address zipcode | string |
zone0 zone1 zone2 zone3 | number — 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ás | Qué pasa |
|---|---|
branchRef + datos, sin mapapropBranchId | se crea en tu cuenta y te devolvemos el id |
branchRef + mapapropBranchId | ya existe: sólo se guarda el vínculo, no se toca |
branchRef solo, sin datos | no 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ódigo | Qué pasó | Qué hacer |
|---|---|---|
201 | Se creó la ficha | — |
200 | Ya existía (created: false) o se reactivó (revived: true) | — |
400 | Falta 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 caracteres | El campo viene en field |
400 | Falta el clientRef | Mandá el header x-client-ref: sin él no sabemos de qué cliente es la ficha, y no lo adivinamos |
401 | Token ausente o inválido | — |
403 | Tu token no tiene el scope property-api-create | Escribinos para habilitarlo |
Relacionado
- Clientes — qué es la ficha y todos los métodos
GET·PUT·DELETE- Alta de propiedades — el paso siguiente