BETA

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.

PortalValor de {portal}Estado
Zonapropzonapropapidisponible
Argenpropargenpropapidisponible
Mapapropmapapropapidisponible — 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:

  1. La ficha de tu cliente — Clientes
  2. Su cuenta del portal conectada — Conectar con un enlace
  3. La propiedad cargada, con su paId — Alta de propiedades

La llamada

CampoTipoRequeridoDescripción
planstringsegún el portalEl plan de publicación. Pisa el que hayas puesto en publication dentro del objeto
branchobjetonoLos 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 branchQué es
agentEmailEl asesor responsable del aviso en el portal
nameEl nombre que se muestra como contacto
emailEl correo que se muestra como contacto
phone1El 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
  }
}
CampoQué es
requestedEl 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ó
availablePlansLos 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

statusQué significa
publishedTodos los avisos salieron
partialAlgunos sí y otros no. development.codesWithError te dice cuáles
failedNinguno salió. El portal rechazó la publicación
receivedEl 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="
}
CampoQué es
retryAfterSegundos que te sugerimos esperar antes de reintentar. Depende de lo que publicaste (ver abajo)
referenceEl 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 publicasteretryAfter
Un aviso suelto, o un desarrollo de menos de 16 unidades60
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" }
  ]
}
ListaQué significaQuién lo resuelve
blockersfalta un dato de la propiedadvos: corregí el objeto y volvé a intentar
accountBlockersfalta 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:

sourceDe dónde saleQué hacer
customerla ficha del clientecompletala con PUT /customers — el campo va en fix
publicationlo declarás por propiedadmandalo en publication.api.{portal}
connectionel vínculo del cliente con el portalla cuenta no está vinculada: pedí un enlace de conexión
mapaproplo asignamos nosotroses 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ódigoQué pasóQué hacer
200Publicado—
400El portal no está disponible todavía, o el body no es JSON válidoRevisá el valor de {portal}
403Tu token no tiene el scope {portal}:publishEscribinos para habilitarlo
404Esa propiedad no existe para este clienteRevisá el paId y el x-client-ref
409La cuenta no está conectada al portalPedí un enlace de conexión
409El cliente está dado de baja (customer_not_active)Reactivalo con POST /property-v1/customers — ver Clientes
409Falta una elección de publicación (publication_data_missing)Ver arriba: cada faltante viene con su fix
409Faltan datos de la cuenta (account_data_missing)Ver arriba: cada faltante viene con su fix
409El portal todavía está procesando la publicación anterior de ese código (portal_processing)Esperá y reintentá — viene con retryAfter
409El 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
409El 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
422Falta un datoVer arriba
502El 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 detail lo dice, y el reference identifica tu llamada.
  • No respondió → el detail te 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