BETA

Publish to a portal

Once the property is uploaded and the portal account connected, this publishes it.

PUT /property-v1/properties/{paId}/publication/{portal}

You do not send the property again: we already have it, and we publish it exactly as it was stored. We translate it to the portal's format.

Portal{portal} valueStatus
Zonapropzonapropapiavailable
Argenpropargenpropapiavailable
Mapapropmapapropapiavailable — not an external portal
Cabaprop, MercadoLibre—not yet

Requires the {portal}:publish scope — for example zonapropapi:publish. It is different from :connect: you may be allowed to connect accounts for a portal and not to publish on it.

Before publishing

Three things, in this order:

  1. Your client's record — Clients
  2. Their portal account connected — Connect with a link
  3. The property uploaded, with its paId — Creating properties

The call

FieldTypeRequiredDescription
planstringdepends on the portalThe publication plan. Overrides the one set in publication inside the object
branchobjectnoThe contact details for this ad. They override, field by field, the ones in the client's record
curl -X PUT https://property-api.mapaprop.com/property-v1/properties/01M3PTZ8YBMM5DSNW03WP8VD9E/publication/zonapropapi \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "x-client-ref: cliente-42" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "SUPERDESTACADO" }'

Response 200:

{
  "status": "published",
  "portal": "zonapropapi",
  "paId": "01M3PTZ8YBMM5DSNW03WP8VD9E",
  "plan": "SUPERDESTACADO",
  "quota": { "remaining": 1493, "limit": 1500 }
}

The ad's contact details

By default, the ad goes out with the contact details you declared in your client's record (customer.branch), frozen when you created the property. If you want this ad to go out with different ones, send them in branch:

curl -X PUT https://property-api.mapaprop.com/property-v1/properties/01M3PTZ8YBMM5DSNW03WP8VD9E/publication/zonapropapi \
  -H "Authorization: Bearer <YOUR_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"
        }
      }'
branch fieldWhat it is
agentEmailThe agent responsible for the ad on the portal
nameThe name shown as the contact
emailThe email address shown as the contact
phone1The phone number shown as the contact

All four are optional and are resolved one by one. The one you send wins; the one you leave out still comes from the record. That way you can change only the phone number on one ad without repeating the rest.

One exception: if you send email without agentEmail, the agent becomes that same address. The agent does not stay with the one on the record — it follows the email you sent. To change the contact address without touching the agent, send both.

agentEmail must be a user that exists in the portal account.

It is not free text like the other three: the portal resolves it against the users of that account. If you send an address that belongs to none of them, the portal does not return an error: it silently replaces it with the account administrator's, and the publication returns 200.

To find out which users your client has, check their portal panel. And bear in mind that users are created there, not through this API.

The portal does not check that the four fields tell the same story. You can publish with one person's agent address and another person's name and phone number, and the publication will go through all the same. Consistency is up to you: if you choose an agent, it is best to send their name and phone number as well.

You can also leave the plan fixed in the object, under publication. If you send both, the one in this call wins: that way you can change plans without rewriting the property.

The plan in the response is the one we SENT, not necessarily the one the portal assigned. It is the one that actually travelled —so if you left it fixed in the object, you see it here even if you did not send it in the call— but the portal can assign a different one: we measured that on Zonaprop with standalone listings.

The plan that ended up in place comes with the status lookup, under publicationState. We say so rather than keep quiet because coding on the assumption that the requested one is the assigned one breaks your billing, not your screen.

To find out which plans your client has and how many are still free, see your client's plans: the free read comes from the client GET and costs you nothing.

This applies to plan and only to plan. The other publication fields —your account's data on the portal, such as the advertiser or the branch— follow the opposite rule: what the object declares wins, because there the object is the source of truth of its own configuration. The plan is a decision of this publication; account data belongs to the property.

When the portal rejects a plan, its message is misleading: it says "the company has used up all of its available ones", which sounds like your client ran out of quota. Usually it is something else: that plan is not contracted on that account.

So we translate it, with the list of the ones it does have:

{
  "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
  }
}
FieldWhat it is
requestedThe plan that actually travelled to the portal. If you left one fixed on the object and sent another in the call, this is the one that was used
availablePlansThe ones the account has with publications available. It may be absent if the portal did not answer us

The block only appears when the portal rejects because of the plan, and it does not cost your client a single call: the list comes from the last reading we have stored, not from the portal.

We never ask the portal for the plans on our own — the call allowance belongs to your client, and when to spend it is your decision, through the account lookup.

That is why the list comes with availablePlansReadAt: it is a copy, not the live state. If your client published from the portal's own panel, their allowance dropped and we did not find out.

If we have not read their plans yet, the message says so and names the endpoint — rather than handing you an empty list that would look like they have none.

And the same when the plan is MISSING

If you do not send plan anywhere, the response is a 409 publication_data_missing — and the missing plan item also carries the list:

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

After publishing, the copy of their plans goes stale

Publishing consumes a plan, so the list we had stored stops being up to date. Instead of discounting it on our own, we flag it: the client GET returns it with plansStale: true.

We do not subtract anything, and that is on purpose: the portal does not tell us which plan it consumed —its response carries the listing code, its id and its errors, no plan— and for a standalone listing it can assign a different one from the one you requested. Subtracting the requested one would be subtracting the wrong one.

So we tell you "this is from 19:32 and you have published since then", and you decide whether to refresh it against the portal —which costs 1 call— or whether the copy is good enough.

The same applies when you take a listing down: there the plan comes back to the allowance, and the copy goes stale just the same.

A publish that fails does not flag the copy as stale: if the portal rejected everything, it consumed no plan and nothing has changed.

The four values of status

statusWhat it means
publishedEvery listing went out
partialSome did and some did not. development.codesWithError tells you which
failedNone went out. The portal rejected the publication
receivedThe portal took it and is still processing (developments of 16 units or more). It is not published

A 200 means the call went through, not that the listing ended up online. They are two different things: the call can complete perfectly and the portal still reject the listing — for example because your client has no publications available — and that reaches you as status: "failed" with a 200. Program against status, not against the HTTP code.

Why a 200 and not an error: the failure is neither yours nor ours, and the response carries useful information (the listing-by-listing detail). A 4xx would make you discard it.

partial and failed exist as of 2026-10-07. Before that, a publication the portal rejected entirely reached you as published — status only looked at whether the path was direct or deferred. If you have a switch on status, add the two cases.

Calling again UPDATES, it does not duplicate

Publishing the same property twice does not create two listings. The second call updates the existing one. You can retry safely: if a call failed and you do not know whether it went through, call again.

It is the most important property of this endpoint, and the reason there is no separate "create" and "update": a single operation, and the result depends on whether the listing already exists.

But not every field can be changed on a listing that already exists

Updating is not the same as creating: some fields are set by the portal when the listing is created and cannot be moved afterwards. Which ones is decided by the portal, so they live in the table of what changes in each portal.

On Argenprop, for example, the re-publish updates everything — price, zone, surface, photos — except type: the property type stays fixed on the listing. If it changed, the portal rejects the write and the way out is to unpublish and publish again, which creates the listing anew with the correct type.

Correcting the zone of an already published listing does go through this endpoint on Argenprop: there is no need to take it down. That is the difference with portals that fix the zone when the listing is created.

But there is a window: the portal processes one code at a time

While the portal is processing a publication, a second write on the same code does not get through. It is a portal lock, per code, and it lasts as long as it takes to finish the previous one.

We answer it as 409 portal_processing, which is the retry signal:

{
  "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="
}
FieldWhat it is
retryAfterSeconds we suggest waiting before retrying. It depends on what you published (see below)
referenceThe identifier of this call, in case the 409 never resolves

retryAfter is not a fixed number: the portal's window is much longer when it processes a batch.

What you publishedretryAfter
A standalone listing, or a development with fewer than 16 units60
A development with 16 units or more (the portal processes it in deferred mode)600

It is a 409 and not a 502 on purpose. A 502 says "the portal failed" and most HTTP clients treat it as a server error: it gets discarded and not retried. This is a temporary conflict — nothing failed, you just arrived before the previous one finished.

Retrying is safe: the listing is not duplicated.

retryAfter is a suggestion of ours, not a portal figure: it does not tell us how much longer it needs. Both numbers come from measuring the window on Zonaprop: with 4 units one minute was enough, and with 20 it was still rejecting after eight and a half minutes. That is why it is one value per regime and not a single one.

If the same 409 comes back when you retry, it is not that something is broken — it is still processing. Use it as the starting point of your backoff, and if it repeats many times, send us the reference.

With a large development, checking the status does NOT tell you whether you can write yet. With 16 units or more the portal processes in deferred mode (status: "received") and finishes with the parent listing long before it finishes with the batch: if you check, it will answer about the listing — not about the lock. Measured: the status said processed and the portal kept rejecting the write for more than 5 minutes.

For that window, waiting and retrying is what works, and it is also free: checking spends one call of your client's allowance. Details in Publishing a development.

When it cannot be published: 422

It is not an error in your call — a piece of data is missing. That is why there are two separate lists:

{
  "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" }
  ]
}
ListWhat it meansWho resolves it
blockersa piece of property data is missingyou: fix the object and try again
accountBlockerssomething about the account at the portal is missing (unmapped zone, plan, branch)resolved once, and it works for every property of that client

They are separate because the fix is different. If you are looking at accountBlockers, reviewing the property JSON will get you nowhere: it is fine.

You can anticipate almost every blocker with POST /properties/verify, which neither creates nor publishes anything.

When a piece of account data is missing: 409 account_data_missing

The mapping came out complete, but with example data. We do not publish it like that: it would produce a listing with details that do not belong to the client.

This is the case where verification gave you green and publishing fails. It is not a contradiction: verify fills the account data with examples on purpose, so it can answer the only thing you asked it — whether your object maps correctly — even if the account is not configured yet. When publishing, that filler cannot travel.

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

Each missing item says where that piece of data comes from, because the fix is different in each case:

sourceWhere it comes fromWhat to do
customerthe client recordcomplete it with PUT /customers — the field comes in fix
publicationyou declare it per propertysend it in publication.api.{portal}
connectionthe client's link with the portalthe account is not linked: request a connection link
mapapropwe assign itit is a problem on our side: send us the reference

youCanFixIt answers the only question that matters: do I fix it, or is it yours? If it comes back false, reviewing your JSON will not get you anywhere.

Response codes

CodeWhat happenedWhat to do
200Published—
400The portal is not available yet, or the body is not valid JSONCheck the {portal} value
403Your token lacks the {portal}:publish scopeWrite to us to enable it
404That property does not exist for this clientCheck the paId and the x-client-ref
409The account is not connected to the portalRequest a connection link
409The client is deactivated (customer_not_active)Reactivate it with POST /property-v1/customers — see Clients
409A publication choice is missing (publication_data_missing)See above: each missing item comes with its fix
409Account data is missing (account_data_missing)See above: each missing item comes with its fix
409The portal is still processing the previous publication of that code (portal_processing)Wait and retry — it comes with retryAfter
409The portal no longer recognises the account of your client as part of your integration (portal_account_unlinked)Connect it again: request a link. Retrying does not recover it — it usually happens when it was reconnected from somewhere else, and it affects everything on that account at once. See one single connection per agency
409The portal has your client's account disabled or blocked (portal_account_blocked)Write to us with the reference. Retrying does not enable it and reconnecting does not either: the block is on the account. The link with the portal is managed by us, so we channel the claim from this side
422A piece of data is missingSee above
502The portal rejected the publication, or did not respondSee below

Not all 409s are the same, and the error field tells them apart: portal_not_connected, customer_not_active, account_data_missing and publication_data_missing ask you to fix something before coming back; portal_processing only asks you to wait. If you treat all four the same, you will retry the ones that are not worth retrying and give up on the only one that is.

The 502, which has two flavours

{ "error": "portal_rejected",
  "detail": "El portal rechazó la publicación. Si se repite, pasanos el `reference` y lo revisamos.",
  "reference": "Ks9dLm2xIAMEXAMPLE=" }
  • The portal rejected it → the detail says so, and the reference identifies your call.
  • It did not respond → the detail says so, and it may have been published anyway. Retrying is safe: it does not duplicate.

We do not tell you "it was not published" when we do not know.

Changed on 2026-10-08. The case "the portal is still processing the previous listing" used to land here, as a 502 with the generic text — so there was no way to know it was temporary. It is now a 409 portal_processing with retryAfter (see above). If you have a catch that treats any 502 as definitive, it is still correct: what is retryable moved out of there.

The reference: keep it and send it to us

It identifies that one call. On our side we record everything the portal replied, so with that value we find your exact case without asking you for anything else: no logs, no screenshots, not the payload you sent.

If an error repeats, write to dev@mapaprop.com with the reference and the paId.

Changed on 2026-10-02. This response used to include a portalResponse field carrying the portal's reply as-is. It is no longer sent: every portal has its own codes and formats, and coding against them leaves you exposed to changes you are not told about. Instead you will receive errors normalised by us, the same across all portals, plus the reference for the cases that need a human to look at them.

Portal specifics