The parking booking API we would want if we were the reseller

Most parking booking APIs are a single create endpoint and nothing else. Everything hard about the relationship then falls back onto email, where a person reads it and retypes it into another system.

We sit on the receiving end of that wire. ParkAgenda ingests reseller bookings for off airport car parks, which means we spend our days reading other people's payloads and other people's confirmation emails. This post is written from the other side. If we were the reseller integrating with a car park, here is what we would ask for, and here is what ParkAgenda actually exposes today.

Four failures cover almost all of the pain

Reseller integrations break in four places, and each one has a shape that prevents it. A create that gets retried and books the car twice, a cancellation that leaves the commission ambiguous, an availability number that means one thing at your end and another at ours, and a change the operator makes on their side that never travels back.

None of that is exotic. All four are settled by the API contract, before anybody writes a line of code against it.

Idempotency on create, or you will double book a Friday in July

Every create call needs a key supplied by the caller, and a second call carrying the same key must return the first booking instead of making a new one. Without that, a timeout turns into a duplicate every single time.

Here is the example. The numbers are constructed to make the shape visible, not taken from a customer. Take a 400 space car park selling 60 per cent of its volume through resellers. On the Friday the July peak starts, one reseller pushes 180 arrivals for that day. Six of those calls time out at the gateway after thirty seconds. The write had already succeeded. The response never came back, so the reseller's queue retried, which is what a sane queue should do.

The car park now holds 186 bookings for 180 cars. Six ghosts is one and a half per cent of the site, which sounds survivable. It is not. The peak day was already showing reservation occupancy above 100 per cent, and those six are the reason the operator stopped selling at four in the afternoon on the best day of the month.

Two details decide whether idempotency is useful or decorative.

• The key should be the reseller's own booking reference. That is the value both sides can find again during a support call. A UUID generated by the car park is useless to the person on the phone.
• The replay must return the original booking, with the same identifier, and say that it was a replay. A bare 409 with no body is not idempotency. It is a puzzle handed to a developer at eleven at night.

A cancellation has to answer the money question

A cancellation that returns only a status leaves the operator to reconstruct the commission by hand at the end of the month. The response should carry what the customer paid, what is refundable, and whether the commission is retained.

Take a booking sold at 84 EUR with a 22 per cent commission, so 18.48 EUR to the reseller. The customer cancels 40 hours before arrival. Does the reseller keep the commission on a cancelled stay? Some do, some do not, and some keep it inside 48 hours and release it outside. All three are legitimate commercial positions. Not one of them is legible from a field that says cancelled.

At 70 cancellations a month across three resellers, that ambiguity becomes a spreadsheet diff somebody performs on the last Friday of the month. It is the most common reason an operator's commission figure disagrees with the reseller's statement.

Availability should return the number the operator will sell

An availability endpoint should answer with sellable units and the moment they were calculated, not with capacity minus bookings. Those are different numbers and the difference is deliberate.

Reservation occupancy for a date is the sum of the stay windows over the capacity, and it is allowed to run past 100 per cent, because cars leave in the morning and arrive in the evening. On the same 400 space site, 416 stays can cross a Sunday and the car park is still fine, because the highest number of cars physically present at any one moment is 379. If the endpoint answers zero free, the operator loses sales they could have taken. If it answers 400 minus 416, it answers a negative number, and the reseller stops selling a site that has room.

So the operator sets the figure. They decide how far past the physical count they are willing to go, and the endpoint returns that. Two rules make it usable.

• Stamp it. A cached availability figure with no timestamp is a rumour.
• Never treat a read as a hold. Only the create call reserves anything, and the create call has to be allowed to refuse.

Tell the reseller when the operator changes something

Operators change bookings all day and almost no parking system tells the source. A callback on the handful of events that matter, plus a since-cursor endpoint to catch up on the ones you missed, removes a daily phone call.

The events worth pushing are short and specific. A no-show. A departure that happened hours after the booked time. A plate correction. Two duplicates merged into one. A cancellation taken at the counter rather than online.

Now the honest part. ParkAgenda does not send outbound webhooks. We receive them, from our payment provider for our own billing and from our email provider for delivery events, and we emit none. That is the largest gap between the API described above and the API we run, and there is no sense discovering it together on the second call.

What ParkAgenda exposes today

There is a real REST API with an OpenAPI 3 document behind it, bearer token authentication, and four working paths for a booking to arrive. It is not a self-service API programme and we do not describe it as one.

• REST over HTTPS, with resource routes for bookings, parkings, organizations, shifts, shuttle legs, analytics, cash and vehicle check-ins.
• An OpenAPI 3 document covering the operations, their parameters, their request bodies and their responses.
• Bearer JWT authentication against our own identity tenant. There are no API keys and no client credentials, so every caller needs an identity that we create.
• Four ways in for a booking: the reseller's own email format read by an adapter written for that reseller, an API pull on a cursor where the source offers one, CSV import for a migration or for a source that offers neither, and manual entry at the counter. All four produce the same booking record, attributed to its source.
• Anything that cannot be applied safely is quarantined with the raw message and the reason. A person promotes it, reprocesses it, whitelists the sender or dismisses it. Nothing is dropped quietly.
• Exports out for bookings, raw analytics data and the cash recap.

What it does not expose, said plainly

• No public or partner API programme, no self-service sign-up, no API keys.
• No outbound webhooks and no event subscriptions.
• No two-way sync. A pull is a read. We never write back into a reseller's system.
• No connector marketplace and no integration catalogue. New sources are built one adapter at a time, which is exactly how the two live ones were added.

If you want ParkAgenda to talk to something you already run, we build the connector with your supplier. That is a project with a scope and a date on it, rather than a switch on a settings page. Slower than a marketplace, and true. What integrating with a car park actually means walks through who does which part.

The hosting questions a technical buyer always asks

ParkAgenda runs on Microsoft Azure in a European region. Traffic is served over TLS, storage is encrypted at rest by the platform, every timestamp is stored in UTC, and each parking carries its own IANA timezone, so a digest sent at eight in the evening is eight in the evening at that site rather than at head office.

Ingestion is idempotent on the way in as well. A booking email delivered twice is deduplicated on its Message-ID or a hash of its body. Same discipline as an idempotency key on a create call, applied to a channel that never offered one.

We do not publish an uptime percentage. There is no service level agreement behind one, and a number with no measurement method and no credit attached is decoration. When there is an SLA, it will say how availability is measured and what happens when it is missed.

The backend, the operator console and this site are built and run by JADEV, the group behind ParkAgenda. The people who write the ingestion code are the people who read the failed intakes on a Monday morning.

Questions we get asked

Can we get an API key and start integrating this week?

No. Access needs an identity in our tenant, which we create, and an integration is scoped with us first. There is no self-service path today. If that is a blocker for your project, better to know it now.

Does ParkAgenda push updates back to the reseller?

No. Ingestion runs one way. When the operator cancels at the counter, the reseller finds out the way they always have. That is why the callback section above sits on our list rather than in our documentation.

Our reseller has no API at all, only confirmation emails.

That is the common case and it is handled. An adapter is written for that reseller's format so they do not have to change anything on their side. Reading a reseller booking email covers what that involves and why it never stays solved.

Next step

If your reseller has an API you have not been able to use, send us their documentation. We will tell you which of the four paths fits, what the connector would involve, and what we would not be able to do. The feature list is the shorter version of the same answer.