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} value | Status |
|---|---|---|
| Zonaprop | zonapropapi | available |
| Argenprop | argenpropapi | available |
| Mapaprop | mapapropapi | available — 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:
- Your client's record — Clients
- Their portal account connected — Connect with a link
- The property uploaded, with its
paId— Creating properties
The call
| Field | Type | Required | Description |
|---|---|---|---|
plan | string | depends on the portal | The publication plan. Overrides the one set in publication inside the object |
branch | object | no | The 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 field | What it is |
|---|---|
agentEmail | The agent responsible for the ad on the portal |
name | The name shown as the contact |
email | The email address shown as the contact |
phone1 | The 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
}
}
| Field | What it is |
|---|---|
requested | The 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 |
availablePlans | The 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
status | What it means |
|---|---|
published | Every listing went out |
partial | Some did and some did not. development.codesWithError tells you which |
failed | None went out. The portal rejected the publication |
received | The 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="
}
| Field | What it is |
|---|---|
retryAfter | Seconds we suggest waiting before retrying. It depends on what you published (see below) |
reference | The 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 published | retryAfter |
|---|---|
| A standalone listing, or a development with fewer than 16 units | 60 |
| 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" }
]
}
| List | What it means | Who resolves it |
|---|---|---|
blockers | a piece of property data is missing | you: fix the object and try again |
accountBlockers | something 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:
source | Where it comes from | What to do |
|---|---|---|
customer | the client record | complete it with PUT /customers — the field comes in fix |
publication | you declare it per property | send it in publication.api.{portal} |
connection | the client's link with the portal | the account is not linked: request a connection link |
mapaprop | we assign it | it 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
| Code | What happened | What to do |
|---|---|---|
200 | Published | — |
400 | The portal is not available yet, or the body is not valid JSON | Check the {portal} value |
403 | Your token lacks the {portal}:publish scope | Write to us to enable it |
404 | That property does not exist for this client | Check the paId and the x-client-ref |
409 | The account is not connected to the portal | Request a connection link |
409 | The client is deactivated (customer_not_active) | Reactivate it with POST /property-v1/customers — see Clients |
409 | A publication choice is missing (publication_data_missing) | See above: each missing item comes with its fix |
409 | Account data is missing (account_data_missing) | See above: each missing item comes with its fix |
409 | The portal is still processing the previous publication of that code (portal_processing) | Wait and retry — it comes with retryAfter |
409 | The 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 |
409 | The 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 |
422 | A piece of data is missing | See above |
502 | The portal rejected the publication, or did not respond | See 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
detailsays so, and thereferenceidentifies your call. - It did not respond → the
detailsays 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
- Zonaprop: the plan is required and each publication consumes your client's monthly quota — Monthly quota and limits
Related
- Unpublish from a portal — the
DELETE, to take the listing down - The
publicationkey — what to configure inside the object - Connect with a link — connecting the portal account
POST /properties/verify— anticipating the blockers