API guide

The OpenAPI document is generated from the code rather than maintained separately, so it cannot drift from what the API actually does. Postman imports it directly — Import → Link — and gives you every request with its parameters already filled in.

Two credentials, two audiences. They are never interchangeable.

One key covers your whole account. If you operate an OMC and two depots, that is one credential, not three — and you never tell us which company is acting. The order already records its OMC, its BDC and its depot, so we read the actor off the work.

A key's permissions are your PetroMon licence types, and holding one lets the key do everything that licence may do:

OMC     raise orders, read yours
BDC     approve, decline or cancel orders, custody transfers
DEPOT   depot approval, vehicle checks, loading, marking, cancelling, custody transfers

The portal offers only the licences your account actually holds. Asking for one it does not hold is refused when the key is issued, rather than granted and quietly ignored.

Limited per credential, not per connection — spreading calls across hosts doesn't buy headroom.

Four things the reference will not tell you, each of which produces a working-looking integration that is quietly wrong.

1. Codes, never ids

PetroMon's internal ids are never accepted and never returned. Everything is named by a code resolved from /api/v1/reference — bdcCode, depotCode, productCode, outletCode, brvNumber. Nothing you store can be invalidated by a renumbering inside PetroMon. A code that matches nothing is 422 unknown_code, naming the field.

Orders included: a stage call names the order in the path and carries no id in its body. A decline or cancellation names its reason the same way, by reasonCode from /api/v1/reference/reasons.

Reference lists carry only what you can use: deactivated companies and inactive products are absent rather than flagged, so anything returned can be ordered.

2. Compare statuses as names, never numbers

Statuses arrive as names — ordered, bdc_approved, good_standing, depot_approved, brv_checked, loaded, marked, released.

3. Each stage belongs to one party

The API refuses a stage your partner type does not drive, with actor_not_permitted. One integration cannot walk an order end to end.

Stage requests carry a status name — the status the order should end up in. The gateway turns it into PetroMon's number, so you never handle one. A decline or cancellation needs a comment and a reasonCode from /api/v1/reference/reasons, ends the order for good, and gives back any stock the BDC's approval reserved. Any other name is invalid_status, refused before the order is read.

Every name the stage endpoints accept, and nothing else. Case does not matter:

tagged is the one name that is not a status: tagging leaves the order where it is. PetroMon's PPMS cancellation, after loading, is deliberately not accepted — it would give back stock that has already left the depot.

Everything above is live. Release is not Not yet live — there is no route for it, so it answers 404 and is absent from the OpenAPI document rather than published and broken. It computes UPPF levies against a price window; it is not a status change on its own.

4. The volumes have to agree

On a road movement the vehicle's capacity replaces the volume you send — it is not a suggestion. Two sums are then checked, and both must be exact:

delivery lines            = the vehicle's capacity
tanks assigned to an outlet = that outlet's line

Either mismatch is invalid_volume, and the message names the outlet and both figures. Tank numbers come from compartments on /api/v1/reference/brvs. A worked example, with codes that resolve today, is in docs/API-EXAMPLES.md.

Branch on errorCode; the message is for logs. Every error carries a requestId that traces the call end to end.

One endpoint per environment, HTTPS only. Posting again re-points the existing one and leaves the secret alone — rotate to change it. Deleting disables rather than removes, so the delivery history survives.

Failed deliveries retry with backoff and dead-letter after eight attempts. A replay creates a new delivery rather than resetting the old one, so the record of what you were and weren't told stays intact.