Publicar en un portal
Cuando la propiedad ya está cargada y la cuenta del portal conectada, esto la publica.
PUT /property-v1/properties/{paId}/publication/{portal}
No mandás la propiedad de nuevo: ya la tenemos, y la publicamos tal como quedó guardada. Nosotros la traducimos al formato del portal.
| Portal | Valor de {portal} | Estado |
|---|---|---|
| Zonaprop | zonapropapi | disponible |
| Argenprop | argenpropapi | disponible |
| Mapaprop | mapapropapi | disponible — no es un portal externo |
| Cabaprop, MercadoLibre | — | todavía no |
Requiere el scope {portal}:publish — por ejemplo zonapropapi:publish. Es distinto del :connect: podés estar habilitado para conectar cuentas de un portal y no para publicar en él.
Antes de publicar
Tres cosas, en este orden:
- La ficha de tu cliente — Clientes
- Su cuenta del portal conectada — Conectar con un enlace
- La propiedad cargada, con su
paId— Alta de propiedades
La llamada
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
plan | string | según el portal | El plan de publicación. Pisa el que hayas puesto en publication dentro del objeto |
branch | objeto | no | Los datos de contacto de este aviso. Pisan, campo por campo, los de la ficha del cliente |
curl -X PUT https://property-api.mapaprop.com/property-v1/properties/01M3PTZ8YBMM5DSNW03WP8VD9E/publication/zonapropapi \
-H "Authorization: Bearer <TU_TOKEN>" \
-H "x-client-ref: cliente-42" \
-H "Content-Type: application/json" \
-d '{ "plan": "SUPERDESTACADO" }'
Respuesta 200:
{
"status": "published",
"portal": "zonapropapi",
"paId": "01M3PTZ8YBMM5DSNW03WP8VD9E",
"plan": "SUPERDESTACADO",
"quota": { "remaining": 1493, "limit": 1500 }
}
El contacto del aviso
Por defecto, el aviso sale con los datos de contacto que declaraste en la ficha de tu cliente
(customer.branch), congelados cuando diste de alta la propiedad. Si querés que este aviso salga
con otros, mandalos en branch:
curl -X PUT https://property-api.mapaprop.com/property-v1/properties/01M3PTZ8YBMM5DSNW03WP8VD9E/publication/zonapropapi \
-H "Authorization: Bearer <TU_TOKEN>" \
-H "x-client-ref: cliente-42" \
-H "Content-Type: application/json" \
-d '{
"plan": "SUPERDESTACADO",
"branch": {
"agentEmail": "carina@inmobiliaria.com",
"name": "Carina Milesse",
"email": "ventas@inmobiliaria.com",
"phone1": "5493425067641"
}
}'
Campo de branch | Qué es |
|---|---|
agentEmail | El asesor responsable del aviso en el portal |
name | El nombre que se muestra como contacto |
email | El correo que se muestra como contacto |
phone1 | El teléfono que se muestra como contacto |
Los cuatro son opcionales y se resuelven de a uno. El que mandás gana; el que no mandás sigue saliendo de la ficha. Así podés cambiar sólo el teléfono de un aviso sin repetir el resto.
Hay una excepción: si mandás email sin agentEmail, el asesor pasa a ser ese mismo correo.
El asesor no se queda con el de la ficha — sigue al email que mandaste. Si querés cambiar el
correo que se muestra sin tocar el asesor, mandá los dos.
agentEmail tiene que ser un usuario que exista en la cuenta del portal.
No es texto libre como los otros tres: el portal lo resuelve contra los usuarios de esa cuenta. Si
mandás una dirección que no pertenece a ninguno, el portal no te devuelve un error: la reemplaza
en silencio por la del administrador de la cuenta, y la publicación sale 200.
Para saber qué usuarios tiene cargados tu cliente, mirá su panel del portal. Y tené en cuenta que los usuarios se dan de alta allá, no por esta API.
El portal no verifica que los cuatro campos cuenten la misma historia. Podés publicar con el asesor de una persona y el nombre y el teléfono de otra, y la publicación va a salir igual. La coherencia es tuya: si elegís un asesor, conviene que mandes también su nombre y su teléfono.
El plan también podés dejarlo fijo en el objeto, en publication. Si mandás los dos, gana el de esta llamada: así podés cambiar de plan sin reescribir la propiedad.
El plan de la respuesta es el que MANDAMOS, no necesariamente el que el portal asignó. Es el que
viajó de verdad —así que si lo dejaste fijo en el objeto, acá lo ves aunque no lo hayas puesto en la
llamada—, pero el portal puede asignar otro: lo medimos en Zonaprop con avisos sueltos.
El plan que quedó lo trae la consulta de estado, en
publicationState. Lo decimos en vez de callarlo porque programar asumiendo que el pedido es el
asignado te rompe la facturación, no la pantalla.
Para saber qué planes tiene tu cliente y cuántos le quedan libres, mirá
los planes de tu cliente: la lectura gratis sale del
GET del cliente y no te cuesta nada.
Esto vale para el plan y sólo para el plan. Los otros campos de publication —los de tu cuenta
en el portal, como el anunciante o la sucursal— siguen la regla inversa: gana lo que declara el
objeto, porque ahí el objeto es la fuente de verdad de su propia configuración. El plan es una
decisión de esta publicación; los datos de cuenta son de la propiedad.
Si el portal rechaza por el PLAN, te decimos cuáles tenés
Cuando el portal contesta que el plan no sirve, su mensaje es confuso a propósito de nada: dice "la empresa tiene utilizados todos sus disponibles", que suena a que tu cliente se quedó sin cupo. Casi siempre es otra cosa: ese plan no está contratado en esa cuenta.
Así que te lo traducimos, con la lista de los que sí tiene:
{
"status": "failed",
"planIssue": {
"requested": "DESARROLLOS_DESTACADO",
"portalError": "ERR-0502",
"detail": "El portal rechazó la publicación por el plan `DESARROLLOS_DESTACADO`: o no está contratado en esa cuenta, o no tiene publicaciones disponibles. Los planes disponibles son: DESARROLLOS_HOME.",
"availablePlans": [{ "plan": "DESARROLLOS_HOME", "disponible": 1 }],
"youCanFixIt": true
}
}
| Campo | Qué es |
|---|---|
requested | El plan que realmente viajó al portal. Si dejaste uno fijo en el objeto y mandaste otro en la llamada, acá ves el que se usó |
availablePlans | Los que la cuenta tiene con publicaciones disponibles. Puede no venir si el portal no nos contestó |
El bloque sólo aparece cuando el portal rechaza por el plan, y no le cuesta ni una llamada a tu cliente: la lista sale de la última lectura que tenemos guardada, no del portal.
Nosotros nunca le consultamos los planes al portal por nuestra cuenta — el cupo de llamadas es de tu cliente, y cuándo gastarla lo decidís vos con la consulta de cuenta.
Por eso la lista viene con availablePlansReadAt: es una copia, no el estado en vivo. Si tu cliente
publicó desde el panel del portal, su cupo bajó y nosotros no nos enteramos.
Si todavía no leímos sus planes, el mensaje te lo dice y te nombra el endpoint — en vez de darte una lista vacía que parecería decir que no tiene ninguno.
Y lo mismo cuando el plan FALTA
Si no mandás plan en ningún lado, la respuesta es un 409 publication_data_missing — y el faltante del plan
también te llega con la lista:
{
"error": "publication_data_missing",
"missing": [{
"field": "plan",
"fix": "Mandalo en el objeto, en \"publication.api.zonaprop.plan\". Esta cuenta tiene disponible (nuestra última lectura, 2026-10-07T20:35:15.020Z): HOME (31 de 80), SIMPLE (20 de 80).",
"availablePlans": [{ "plan": "HOME", "disponible": 31, "contratado": 80 }],
"availablePlansReadAt": "2026-10-07T20:35:15.020Z"
}]
}
Después de publicar, la copia de sus planes queda vieja
Publicar consume un plan, así que la lista que teníamos guardada deja de estar al día. En vez de
descontarla por nuestra cuenta, la marcamos: el GET del cliente
te la devuelve con plansStale: true.
No le restamos nada, y es a propósito: el portal no nos dice qué plan consumió —su respuesta trae el código del aviso, su id y sus errores, ningún plan— y para un aviso suelto puede asignar uno distinto del que pediste. Restar el pedido sería restar el equivocado.
Así que te decimos "esto es de las 19:32 y desde entonces publicaste", y vos decidís si lo actualizás contra el portal —que cuesta 1 llamada— o si con la copia te alcanza.
Lo mismo vale al dar de baja: ahí el plan vuelve al cupo, y la copia envejece igual.
Un publish que falla no marca la copia como vieja: si el portal rechazó todo, no consumió ningún plan y no hay nada que haya cambiado.
Los cuatro valores de status
status | Qué significa |
|---|---|
published | Todos los avisos salieron |
partial | Algunos sí y otros no. development.codesWithError te dice cuáles |
failed | Ninguno salió. El portal rechazó la publicación |
received | El portal lo tomó y sigue procesando (desarrollos de 16 unidades o más). No es published |
Un 200 quiere decir que la llamada salió, no que el aviso quedó online. Son dos cosas distintas:
la llamada puede completarse perfecto y el portal rechazar el aviso —por ejemplo porque tu cliente no
tiene publicaciones disponibles— y eso te llega como status: "failed" con un 200. Programá contra
el status, no contra el código HTTP.
Por qué un 200 y no un error: el error no es tuyo ni nuestro, y la respuesta trae información útil
(el detalle por aviso). Un 4xx te haría descartarla.
partial y failed existen desde el 2026-10-07. Antes, una publicación que el portal rechazaba
entera te llegaba como published — el status sólo miraba si el camino era directo o diferido.
Si tenés un switch sobre status, agregá los dos casos.
Volver a llamar ACTUALIZA, no duplica
Publicar dos veces la misma propiedad no crea dos avisos. La segunda llamada actualiza el que ya existe. Podés reintentar sin miedo: si una llamada falló y no sabés si llegó, volvé a llamar.
Es la propiedad más importante de este endpoint, y la razón por la que no hay un "crear" y un "actualizar" separados: una sola operación, y el resultado depende de si el aviso ya existe.
Pero no todo campo se puede cambiar sobre un aviso que ya existe
Actualizar no es lo mismo que crear: hay campos que el portal fija al publicar y después no deja mover. Cuál es cada uno lo decide el portal, así que está en la tabla de qué cambia en cada portal.
En Argenprop, por ejemplo, el re-publish actualiza todo —precio, zona, superficie, fotos—
menos el type: el tipo de propiedad queda fijo en el aviso. Si cambió, el portal rechaza la
escritura y la salida es dar de baja y volver a
publicar, que crea el aviso de nuevo con el tipo correcto.
Corregir la zona de un aviso ya publicado sí entra por este endpoint en Argenprop: no hace falta darlo de baja. Es la diferencia con portales que fijan la zona al crear el aviso.
Pero hay una ventana: el portal procesa de a una por código
Mientras el portal está procesando una publicación, una segunda escritura sobre el mismo código no entra. Es un bloqueo del portal, por código, y dura lo que le lleve terminar la anterior.
Te lo contestamos como 409 portal_processing, que es la señal de reintentá:
{
"error": "portal_processing",
"detail": "El portal todavía está procesando la publicación anterior de este código. Reintentá en unos segundos: la operación es idempotente y no duplica el aviso.",
"retryAfter": 60,
"reference": "Ks9dLm2xIAMEXAMPLE="
}
| Campo | Qué es |
|---|---|
retryAfter | Segundos que te sugerimos esperar antes de reintentar. Depende de lo que publicaste (ver abajo) |
reference | El identificador de esta llamada, por si el 409 no se resuelve nunca |
retryAfter no es un número fijo: la ventana del portal es mucho más larga cuando procesa un lote.
| Lo que publicaste | retryAfter |
|---|---|
| Un aviso suelto, o un desarrollo de menos de 16 unidades | 60 |
| Un desarrollo de 16 unidades o más (el portal lo procesa en diferido) | 600 |
Es un 409 y no un 502 a propósito. Un 502 dice "el portal falló" y la mayoría de los
clientes HTTP lo tratan como error del servidor: se descarta y no se reintenta. Esto es un
conflicto temporal — no falló nada, sólo llegaste antes de que terminara lo anterior.
Reintentar es seguro: el aviso no se duplica.
retryAfter es una sugerencia nuestra, no un dato del portal: él no nos dice cuánto le falta.
Los dos números salen de medir la ventana en Zonaprop: con 4 unidades un minuto alcanzó, y con 20
seguía rechazando a los 8 minutos y medio. Por eso es un valor por régimen y no uno solo.
Si al reintentar te vuelve el mismo 409, no es que algo esté roto — es que todavía está procesando.
Usalo como punto de partida de tu backoff, y si se repite muchas veces, pasanos el reference.
Con un desarrollo grande, consultar el estado NO te dice si ya podés escribir. Con 16 unidades o
más el portal procesa en diferido (status: "received") y termina con el aviso principal mucho antes
que con el lote: si consultás, te va a contestar por el aviso — no por el candado. Medido: el estado
decía procesado y el portal siguió rechazando la escritura más de 5 minutos.
Para esa ventana, esperar y reintentar es lo que funciona, y además es gratis: consultar gasta una llamada del cupo de tu cliente. Detalle en Publicar un desarrollo.
Cuando no se puede publicar: 422
No es un error de tu llamada — es que falta un dato. Por eso vienen dos listas separadas:
{
"error": "not_publishable",
"detail": "La propiedad no se puede publicar en este portal todavía.",
"blockers": [
{ "field": "title", "kind": "missing", "message": "Falta el título" }
],
"accountBlockers": [
{ "field": "options.zoneNaventId", "kind": "missing",
"message": "La zona de la propiedad no tiene mapeo guardado en Zonaprop" }
]
}
| Lista | Qué significa | Quién lo resuelve |
|---|---|---|
blockers | falta un dato de la propiedad | vos: corregí el objeto y volvé a intentar |
accountBlockers | falta algo de la cuenta en el portal (zona sin mapear, plan, sucursal) | se resuelve una vez y sirve para todas las propiedades de ese cliente |
Están separadas porque el arreglo es distinto. Si venís de accountBlockers, revisar el JSON de la propiedad no te va a llevar a ningún lado: está bien.
Podés anticipar casi todos los blockers con POST /properties/verify, que no crea ni publica nada.
Cuando falta un dato de la cuenta: 409 account_data_missing
El mapeo salió completo, pero con datos de ejemplo. No lo publicamos así: saldría un aviso con datos que no son del cliente.
Es el caso en que la verificación te dio verde y la
publicación falla. No es una contradicción: el verify rellena los datos de cuenta con ejemplos
a propósito, para poder contestarte lo único que le preguntaste —si tu objeto mapea bien—
aunque la cuenta todavía no esté configurada. Al publicar, ese relleno no puede viajar.
{
"error": "account_data_missing",
"detail": "Faltan datos de la cuenta del portal para publicar de verdad. No lo mandamos con valores de ejemplo: saldría un aviso con datos que no son del cliente.",
"missing": [
{ "field": "branch.phone1", "portal": "zonaprop", "source": "customer", "youCanFixIt": true,
"fix": "Completá la inmobiliaria con PUT /property-v1/customers: \"phone1\" (en la inmobiliaria o en su \"branch\")." },
{ "field": "plan", "portal": "zonaprop", "source": "publication", "youCanFixIt": true,
"fix": "Mandalo en el objeto, en \"publication.api.zonaprop.plan\"." }
],
"reference": "a1b2c3d4-…"
}
Cada faltante dice de dónde sale ese dato, porque el arreglo es distinto en cada caso:
source | De dónde sale | Qué hacer |
|---|---|---|
customer | la ficha del cliente | completala con PUT /customers — el campo va en fix |
publication | lo declarás por propiedad | mandalo en publication.api.{portal} |
connection | el vínculo del cliente con el portal | la cuenta no está vinculada: pedí un enlace de conexión |
mapaprop | lo asignamos nosotros | es un problema nuestro: pasanos la reference |
youCanFixIt contesta la única pregunta que importa: ¿lo arreglo yo, o es de ustedes? Si viene
en false, revisar tu JSON no te va a llevar a ningún lado.
Códigos de respuesta
| Código | Qué pasó | Qué hacer |
|---|---|---|
200 | Publicado | — |
400 | El portal no está disponible todavía, o el body no es JSON válido | Revisá el valor de {portal} |
403 | Tu token no tiene el scope {portal}:publish | Escribinos para habilitarlo |
404 | Esa propiedad no existe para este cliente | Revisá el paId y el x-client-ref |
409 | La cuenta no está conectada al portal | Pedí un enlace de conexión |
409 | El cliente está dado de baja (customer_not_active) | Reactivalo con POST /property-v1/customers — ver Clientes |
409 | Falta una elección de publicación (publication_data_missing) | Ver arriba: cada faltante viene con su fix |
409 | Faltan datos de la cuenta (account_data_missing) | Ver arriba: cada faltante viene con su fix |
409 | El portal todavía está procesando la publicación anterior de ese código (portal_processing) | Esperá y reintentá — viene con retryAfter |
409 | El portal ya no reconoce la cuenta de tu cliente como parte de tu integración (portal_account_unlinked) | Volvé a conectarla: pedí un enlace. Reintentar no la recupera — suele pasar cuando se reconectó desde otro lado, y afecta a todo lo de esa cuenta a la vez. Ver una sola conexión por inmobiliaria |
409 | El portal tiene la cuenta de tu cliente deshabilitada o bloqueada (portal_account_blocked) | Escribinos con el reference. Reintentar no la habilita y reconectarla tampoco: el bloqueo es sobre la cuenta. El vínculo con el portal lo gestionamos nosotros, así que el reclamo lo encauzamos de este lado |
422 | Falta un dato | Ver arriba |
502 | El portal rechazó la publicación, o no respondió | Ver abajo |
Los 409 no son todos iguales, y el campo error los distingue: portal_not_connected,
customer_not_active, account_data_missing y publication_data_missing piden que arregles algo antes de volver;
portal_processing sólo pide que esperes. Si tratás los cuatro igual, vas a reintentar los que
no sirve reintentar y vas a abandonar el único que sí.
El 502, que tiene dos sabores
{ "error": "portal_rejected",
"detail": "El portal rechazó la publicación. Si se repite, pasanos el `reference` y lo revisamos.",
"reference": "Ks9dLm2xIAMEXAMPLE=" }
- El portal rechazó → el
detaillo dice, y elreferenceidentifica tu llamada. - No respondió → el
detailte lo dice, y puede haberse publicado igual. Reintentar es seguro: no duplica.
No te decimos "no se publicó" cuando no lo sabemos.
Cambió el 2026-10-08. El caso "el portal todavía está procesando el aviso anterior" llegaba
acá, como un 502 con el texto genérico — así que no había forma de saber que era temporal. Ahora
es un 409 portal_processing con retryAfter (ver arriba). Si tenés un catch que trata
cualquier 502 como definitivo, sigue siendo correcto: lo reintentable salió de ahí.
El reference: guardalo y pasanoslo
Es el identificador de esa llamada puntual. Nosotros registramos del lado nuestro todo lo que el portal contestó, así que con ese dato encontramos tu caso exacto sin pedirte nada más: ni logs, ni capturas, ni el payload que mandaste.
Si un error se repite, escribinos a dev@mapaprop.com con el reference y el paId.
Cambió el 2026-10-02. Antes esta respuesta incluía un campo portalResponse con la respuesta
del portal tal como venía. Ya no se envía: cada portal tiene sus propios códigos y formatos, y
programar contra ellos te deja expuesto a que los cambien sin avisarte. En su lugar vas a recibir
errores normalizados por nosotros, iguales para todos los portales, y el reference para los
casos que haya que mirar a mano.
Específico de cada portal
- Zonaprop: el plan es obligatorio y cada publicación consume del cupo mensual de tu cliente — Cupo mensual y límites
Relacionado
- Despublicar de un portal — el
DELETE, para dar de baja el aviso - La clave
publication— qué configurar dentro del objeto - Conectar con un enlace — conectar la cuenta del portal
POST /properties/verify— anticipar los blockers