Partner Order API

Ingest a transport order from your own system. Betakom creates a non-binding marketplace order; carriers can Take it, and the order only becomes binding once your customer confirms via the fulfilment link Betakom emails at Take time. Requests are authenticated with HMAC-SHA256 (see Authentication), deduplicated by (partnerId, partnerOrderId), and rate-limited per partner.

Umgebung

https://api.betakom.de

POST/api/v1/partners/orders/ingest

Create a marketplace order from a partner TMS

Creates an is_binding=false order. Idempotent on (x-partner-id, partnerOrderId): replaying the same partnerOrderId returns the original order with replay:true. Body must be ≤ 100 KB; sign and send the exact same bytes.

Ratenbegrenzung: 60 requests / minute / partner

Body-Parameter

Field	Type	Required	Description
`partnerOrderId`	string	required	Your order id. The idempotency key — a replay returns the original order.
`customer.email`	string	required	Customer email — the fulfilment-confirmation email is sent here.
`customer.name`	string	optional	Customer / company name.
`customer.phone`	string	optional	Customer phone.
`loading.country`	string (ISO 3166-1 alpha-2)	required	Pickup country, e.g. "DE".
`loading.city`	string	optional	Pickup city.
`loading.postalCode`	string	optional	Pickup postal code.
`loading.address`	string	optional	Pickup street address.
`loading.date`	string (YYYY-MM-DD)	optional	Pickup date.
`loading.timeFrom / loading.timeTo`	string (HH:mm)	optional	Pickup time window.
`unloading.country`	string (ISO 3166-1 alpha-2)	required	Delivery country.
`unloading.*`	object	optional	Same shape as loading (city, postalCode, address, date, timeFrom, timeTo).
`vehicleType`	string	optional	Requested vehicle type, e.g. "sprinter", "24t".
`totalPriceEur`	number	required	Total agreed price in EUR. Must be > 0.
`currency`	string	optional	Defaults to "EUR".
`distanceKm`	number	optional	Route distance in km.
`totalWeightKg`	number	optional	Total cargo weight in kg.
`packages`	array	optional	Packing list: [{ length, width, height, weight, quantity }].
`extraServices`	object	optional	Flags such as { tailLift: true }.
`notes`	string	optional	Free-text notes for the carrier.

Request

{
  "partnerOrderId": "PO-1001",
  "customer": { "email": "kunde@example.com", "name": "Muster GmbH" },
  "loading":  { "country": "DE", "city": "Berlin",   "postalCode": "10115", "date": "2026-07-02", "timeFrom": "08:00", "timeTo": "12:00" },
  "unloading":{ "country": "DE", "city": "Muenchen", "postalCode": "80331", "date": "2026-07-03" },
  "vehicleType": "sprinter",
  "totalPriceEur": 480,
  "totalWeightKg": 850,
  "packages": [{ "length": 120, "width": 80, "height": 100, "weight": 850, "quantity": 1 }],
  "extraServices": { "tailLift": true },
  "notes": "Anlieferung Rampe 4"
}

Authentication: HMAC-SHA256 — see the Authentication page for the exact signing algorithm.
Idempotent: a repeated partnerOrderId returns the original order with replay:true.
Errors: 401 (signature/timestamp), 413 (body > 100 KB), 429 (rate limit), 400 (validation).

GET/api/v1/partners/orders/{id}/fulfill

Render the fulfilment confirmation interstitial

Returns a confirmation page (no side effect — safe against email link prefetchers). Authenticated by the order's fulfillment_token.

Pfadparameter

Field	Type	Required	Description
`id`	integer	required	The orderId returned by ingest.

Query-Parameter

Field	Type	Required	Description
`token`	string	required	The fulfillment_token returned by ingest.

POST/api/v1/partners/orders/{id}/fulfill

Confirm the order (make it binding)

Flips the order to binding once the customer confirms. Authenticated by the fulfillment_token.

Pfadparameter

Field	Type	Required	Description
`id`	integer	required	The orderId returned by ingest.

Query-Parameter

Field	Type	Required	Description
`token`	string	required	The fulfillment_token returned by ingest (sent in the query string).

Errors: 401 if the token is missing, 403 if it does not match.

POST/api/v1/partners/orders/{id}/decline

Decline the order

Declines a pending partner order. Authenticated by the fulfillment_token in the query string.

Pfadparameter

Field	Type	Required	Description
`id`	integer	required	The orderId returned by ingest.

Query-Parameter

Field	Type	Required	Description
`token`	string	required	The fulfillment_token returned by ingest (sent in the query string).

Errors: 401 if the token is missing, 403 if it does not match.