Logistik
The Betakom customs portal as an API, for business customers with an approved customs profile. Create a draft case, upload the papers, submit it, then poll it for status, the MRN and the documents our customs team issues (export accompanying document, exit confirmation, transit document, …). Requests run through exactly the same checks as the customer portal — lane rules, required papers, the credit line, today's tariff — and our customs team is notified the moment a case is submitted. Authenticate with a per-company API key that the company owner creates in the customer dashboard under Customs › API. Customs is offered for Germany: export from DE, import into DE, transit with one end in DE. There is no sandbox: every API key is live. Test with drafts — they are free, only your company sees them, and DELETE /cases/{id} discards them. Submitting a case files a real customs request with our team and is billed.
draft → pending (submitted) → in_progress (our team is working on it) ⇄ needs_customer (we asked you something) → finished | cancelled.
| Field | Type | Required | Description |
|---|---|---|---|
draft | status | optional | Created via API or portal, not yet submitted. Only you see it. |
pending | status | optional | Submitted; waiting for our customs team. You may still cancel. |
in_progress | status | optional | Our customs team is processing it. |
needs_customer | status | optional | We need something from you — see the latest message with kind = question. |
finished | status | optional | Done; mrn and deliverables are filled. |
cancelled | status | optional | Withdrawn by you or by us (cancelReason). |
Every error is JSON: { success: false, code, message }. Branch on code, not on message.
| Field | Type | Required | Description |
|---|---|---|---|
401 api_key_missing / api_key_invalid | auth | optional | No key sent, or the key is unknown, revoked, or its creator no longer belongs to the company. |
403 business_only / insufficient_scope / account_blocked | auth | optional | The key cannot use this API. |
403 profile_not_approved | customs | optional | The customs profile is not approved yet. |
429 rate_limited | limit | optional | More than 120 requests per minute for this key. Retry after the Retry-After header. |
503 service_unavailable | limit | optional | A short outage on our side. Safe to retry after the Retry-After header (seconds). |
/api/v1/customs/catalogWhat a valid request looks like, served from the same constants the server validates against: per procedure the lane rule, the document slots (and which are required) and the documents Betakom returns; transit / origin-proof types, transport modes, case statuses, EU member states, upload size and MIME types.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/profilecanFile = true once the customs profile (EORI + signed power of attorney) is approved — only then can cases be created. canImport = true when a deferment account is approved (needed for imports). The profile itself is maintained in the customer dashboard.
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/cases/price-preview| Field | Type | Required | Description |
|---|---|---|---|
procedure | string | required | export | import | transit | origin_proof |
positions | integer | optional | Number of goods positions (default 1). |
tariffNumbers | integer | optional | Number of distinct tariff numbers (default 1). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/casesAll cases of the company, drafts first, newest first, as summaries (status, mrn, priceTotal, documentsCount, deliverablesCount, requiredMissing, hasUnread).
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/casesCreates a DRAFT with the shipment details. Nothing reaches our customs team until you submit it. Requires an approved customs profile (403 profile_not_approved otherwise).
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
| Field | Type | Required | Description |
|---|---|---|---|
procedure | string | required | export | import | transit | origin_proof |
originCountry | string | required | ISO 3166-1 alpha-2, e.g. DE. See /catalog for the lane rule of each procedure. |
destinationCountry | string | required | ISO 3166-1 alpha-2, e.g. US. |
transitType | string | optional | T1 | T2 | T2F — required when procedure = transit. |
originProofType | string | optional | EUR1 | EUR_MED | ATR | REX | IHK — required when procedure = origin_proof. |
customerReference | string | optional | Your reference (max 80 chars), e.g. your order number. |
goodsDescription | string | optional | Short description of the goods (max 500 chars). |
transportMode | string | optional | road | sea | air | rail |
plannedDate | string | optional | YYYY-MM-DD — planned shipping date. |
positionsCount | integer | optional | Goods positions, 1–999 (default 1). Affects the price. |
tariffNumbersCount | integer | optional | Distinct tariff numbers, 1–999 (default 1). Affects the price. |
customerNote | string | optional | Note for our customs team (max 2000 chars). |
curl -X POST 'https://betakom.de/api/v1/customs/cases' \
-H "Authorization: Bearer $BETAKOM_API_KEY" \
-H 'content-type: application/json' \
-d '{
"procedure": "export",
"originCountry": "DE",
"destinationCountry": "US",
"customerReference": "PO-4711",
"goodsDescription": "Machine parts",
"transportMode": "road",
"positionsCount": 3,
"tariffNumbersCount": 2
}'/api/v1/customs/cases/{id}The full case: status, mrn, exitConfirmedAt, price, the document slots with your files, deliverables (documents from Betakom — download them with /documents/download), and the message thread (kind = question is a query from our customs team; answer it with /messages). Poll this endpoint to follow a case; a few minutes between polls is plenty.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/cases/{id}Same body as POST /cases. Drafts only (409 otherwise).
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/cases/{id}Deletes a draft that was never submitted. A submitted case is withdrawn with /cancel instead.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/cases/{id}/documentsmultipart/form-data with one or more `file` parts and an optional `slot` (see /catalog for the slots of each procedure; omit it to leave the files unassigned). Allowed while the case is draft, pending, in_progress or needs_customer. An upload on a needs_customer case answers our query and puts the case back to in_progress.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | required | The paper(s). Repeat the part for several files. PDF, images, Excel, Word or CSV; max 15 MB each. |
slot | string | optional | e.g. commercial_invoice, packing_list, transport_document. |
curl -X POST 'https://betakom.de/api/v1/customs/cases/123/documents' \
-H "Authorization: Bearer $BETAKOM_API_KEY" \
-F 'slot=commercial_invoice' \
-F 'file=@invoice.pdf'/api/v1/customs/cases/{id}/documents/downloadStreams one file of the case — yours or one of the deliverables (export accompanying document, exit confirmation, …). docId is the document's id from the case detail.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
docId | integer | required | Document id (slots[].files[].id or deliverables[].id). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
/api/v1/customs/cases/{id}/submitLive — there is no sandbox: this files a real customs request with our team and is billed. Turns the draft into a pending case at today's tariff and reserves the price on your credit line. Checks: every required slot holds a file (400 required_documents_missing, with the missing slots), a credit line exists and covers the price (402 no_credit_line / insufficient_credit). On success our customs team is notified immediately and the key's creator receives the confirmation e-mail.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
curl -X POST 'https://betakom.de/api/v1/customs/cases/123/submit' \
-H "Authorization: Bearer $BETAKOM_API_KEY"/api/v1/customs/cases/{id}/cancelOnly while the case is pending (our team has not started yet); releases the reserved credit. Once work has begun, ask our team via /messages.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | optional | Optional reason (max 500 chars). |
/api/v1/customs/cases/{id}/messagesWrites into the case thread and returns the updated case. A reply on a needs_customer case puts it back in front of our customs team.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | required | The case id (data.id from POST /cases). |
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | string | required | Bearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too. |
| Field | Type | Required | Description |
|---|---|---|---|
body | string | required | The message text. |