Logistik
Carriers and integrators send normalised fleet data to the inbound front door. Each connection has its own unguessable token (in the URL path) and its own HMAC signing secret. The payload follows the canonical envelope below; unknown keys are ignored and malformed entries are dropped defensively. Logged-in carriers manage connections (create, rotate, test) self-service under the Fleet → Integrations area.
https://api.betakom.deA live truck position. Sent under "positions".
| Field | Type | Required | Description |
|---|---|---|---|
externalUnitId | string | required | Your stable id for the vehicle. |
at | string (ISO 8601) | required | Timestamp of the fix. |
lat / lng | number | required | WGS-84 coordinates. |
speedKmh / headingDeg | number | optional | Speed and heading. |
isMoving / ignitionOn | boolean | optional | Motion / ignition state. |
driverName | string | optional | Driver display name. |
A dispatch plan with ordered legs. Sent under "plans".
| Field | Type | Required | Description |
|---|---|---|---|
externalUnitId | string | required | Vehicle id the plan is assigned to. |
externalPlanId | string | required | Your stable plan/tour id (idempotency key). |
status | enum | optional | planned | in_progress | completed | cancelled (default planned). |
legs[] | array | optional | [{ seq, kind: pickup|delivery|reposition|rest, place{lat,lng,postalCode,country,name}, windowStart, windowEnd, loadState: loaded|empty, goodsDescription, weightKg }]. |
sourceFetchedAt | string (ISO 8601) | optional | When you read this plan from your system. |
A declared free-capacity offer. Sent under "availability".
| Field | Type | Required | Description |
|---|---|---|---|
availableFrom | string (ISO 8601) | required | Start of the availability window. |
availableTo | string (ISO 8601) | optional | End of the window. |
externalUnitId / externalOfferId | string | optional | Vehicle id / offer id (offer id is the idempotency key). |
origin | object | optional | { lat, lng, postalCode, country, radiusKm }. |
preferredDestination | object | optional | { region, country, lat, lng }. |
bodyType / capacityKg | string / number | optional | Vehicle body type and free capacity. |
/api/v1/carriers-module/my-company/integrations/inbound/{connector}/{token}The inbound front door. The {token} in the path scopes the request to one carrier connection; the body is HMAC-signed with that connection's secret. The message is landed idempotently and processed asynchronously by the ingestion worker.
| Field | Type | Required | Description |
|---|---|---|---|
connector | string | required | Connector id, e.g. "inbound-webhook". |
token | string | required | Your connection's inbound token (issued when the connection is created). |
| Field | Type | Required | Description |
|---|---|---|---|
x-betakom-signature | string | required | HMAC-SHA256 of the raw body, keyed with the connection's inbound secret. |
{
"positions": [
{ "externalUnitId": "TRK-1", "at": "2026-07-01T10:00:00Z", "lat": 48.13, "lng": 11.57,
"speedKmh": 80, "headingDeg": 270, "isMoving": true, "ignitionOn": true, "driverName": "M. Muster" }
],
"plans": [
{ "externalUnitId": "TRK-1", "externalPlanId": "TOUR-42", "status": "planned",
"legs": [
{ "seq": 0, "kind": "pickup",
"place": { "lat": 48.1, "lng": 11.5, "postalCode": "80331", "country": "DE", "name": "Muenchen" },
"windowStart": "2026-07-02T08:00:00Z", "windowEnd": "2026-07-02T12:00:00Z",
"loadState": "empty", "goodsDescription": "Paletten", "weightKg": 12000 }
] }
],
"availability": [
{ "externalUnitId": "TRK-2", "externalOfferId": "OFFER-7",
"availableFrom": "2026-07-03T00:00:00Z", "availableTo": "2026-07-05T00:00:00Z",
"origin": { "lat": 50.1, "lng": 8.6, "postalCode": "60311", "country": "DE", "radiusKm": 50 },
"preferredDestination": { "region": "Ruhr", "country": "DE" },
"bodyType": "tautliner", "capacityKg": 24000 }
]
}