Best practices
The rest of the documentation is organised by endpoint: each page answers "what does this do?". Useful once you already know what to call.
This section answers the other question, the first one: in what order? These are the complete flows, with the decisions you are going to have to make and what each step costs.
You will not find fields, error codes or payloads here — those live on each endpoint's page and are linked where relevant. If you are looking for "what does it return", go to the endpoint; if you are looking for "what do I call first", stay.
The flows
| When | ||
|---|---|---|
| I am a Mapaprop customer | once, at the start | getting started if you automate your own account: the four things that work differently |
| Setting up a client | once per client | their record and the portal connection |
| Publishing a listing | every property | the base case: load, check, publish |
| Publishing a development | every development | it has an order of its own, worth knowing beforehand |
| Receiving enquiries | ongoing | the enquiries people leave on the listings |
| Get ready for the first lead | once, when it is switched on | what is worth having ready the day the enquiries of your client's account start reaching you on their own |
| Taking things down | when applicable | taking a listing down, disconnecting an account, deleting a client: three different things |
| When something does not work | — | where to start looking |
The six rules that apply to all of them
1 · Some things are done ONCE and some EVERY TIME
This is the most expensive design mistake in an integration, because it does not fail: it simply makes three times as many calls as needed.
| Once per client | Every time |
|---|---|
| declaring their record | loading or updating a property |
| connecting their portal account | publishing, checking the status, taking down |
| mapping their zones (we do that) | — |
2 · Reading our system is free; asking the portal costs
The call allowance belongs to your client, they contract it with the portal, and your integration spends it. Each portal defines it its own way — the Zonaprop case is in Monthly allowance and limits.
| Free | Spends one call from the allowance |
|---|---|
| checking an object | publishing and taking down |
| reading a property or listing them | asking the portal about the listing's status |
| reading the client's record and their stored plans | refreshing the plans against the portal |
⚠️ Errors spend too. An attempt rejected by the portal consumes the call all the same, so it pays to check first — which is free.
3 · Store two things on your side
- The
paIdwe return when you create a property. It is what you publish, read and take down with. If you lose it, you have the listing endpoint and you can look it up by your own code, but that is a step you did not need: the listing is walked page by page, and walking all of it to find one property is work you save yourself by storing thepaId. - Which
clientRefyou operated with. It is how you tell us which client you are talking about, and you choose it: use the id you already have in your system.
4 · Retrying is safe, and you do not have to keep track
- Publishing again updates the listing, it does not create another one. It is how you reflect a change in price or photos.
- Taking down twice answers fine both times. You do not have to remember whether you already did.
- What is not idempotent is creating: two submissions of the same property are two properties.
Send your own code and use the
paIdwe return.
5 · Send all the data, even if some portal does not use it
The object is Mapaprop's, not a portal's. We ask you for all the data because that is what lets us publish on every possible portal: each one accepts a different subset, and the subset changes with the property type.
When a portal does not accept a field you sent, we do not drop it silently: we tell you in
omitted in the verify, with the reason and with what happens to the data.
omitted is information, not an instruction to remove the field. The data is stored and travels
to the portals that do accept it. If you remove it from your object to "clean it up", you lose that
compatibility — and you will need it with the next portal.
6 · The listing is WALKED, and what tells you that you are done is not that it came short
Reading a client's properties is not one call: it is a walk through pages. As long as we return the pointer to the next one, there are properties left — even if the page came short, or even empty. Cutting the walk short because less came back than you asked for leaves you without part of the inventory, and nothing warns you.
It is free (rule 2), so walking all of it costs you no portal allowance: the only thing that costs is doing it wrong. The exact shape is in the listing endpoint.
The portals
The methods are the same for every portal: you pass the portal in the route and nothing else changes. What does change per portal —how the account is connected, what allowance it has, what plans— is in Publication, and the flows here point there instead of repeating it.
Where a portal behaves differently, we say so with its name attached. If you read a figure or a plan name with no portal next to it, that is a mistake on our side: write to us.
If your app connects a single client
The flows are written for the general case, where your app operates on several clients and you tell us which one on each call. If your app is enabled for one only, the client is already fixed on our side and you can ignore that step: everything else is the same.