Authentication

One scheme per API. The Partner Order API uses HMAC-SHA256 request signing — the same scheme Stripe uses for webhooks. You never send your secret over the wire; instead you sign each request with it and Betakom recomputes the signature to verify it. Your partnerId and secret are issued during onboarding (see Get Started). The Customs Clearance API uses a per-company API key instead — see Customer API keys below.

Request headers

Every signed request carries these three headers:

FieldTypeRequiredDescription
x-partner-idstringrequiredYour public partner identifier (e.g. "acme"). Selects the credential — and therefore the environment — used to verify the signature.
x-betakom-timestampstringrequiredUnix seconds at signing time. Must be within ±5 minutes of Betakom server time, otherwise the request is rejected (replay protection).
x-betakom-signaturestringrequiredv1=<hex>, where <hex> = HMAC-SHA256(secret, "<timestamp>.<rawBody>"). The bare <hex> form (without the v1= prefix) is also accepted.

How to sign a request

  1. Serialize the request body to a string (payload). You must sign and send the exact same bytes — re-serializing JSON later will break the signature.
  2. Take the current Unix time in seconds (timestamp).
  3. Compute signature = HMAC-SHA256(secret, "<timestamp>.<payload>") and hex-encode it.
  4. Send x-partner-id, x-betakom-timestamp and x-betakom-signature: v1=<hex>.
Node.js
import crypto from 'crypto';

const PARTNER_ID = 'acme';
const SECRET = process.env.BETAKOM_PARTNER_SECRET; // shared with Betakom

async function ingestOrder(body) {
  const payload = JSON.stringify(body);
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const signed = `${timestamp}.${payload}`;
  const signature = 'v1=' + crypto
    .createHmac('sha256', SECRET)
    .update(signed)
    .digest('hex');

  return fetch('https://betakom.de/api/v1/partners/orders/ingest', {
    method: 'POST',
    headers: {
      'content-type':        'application/json',
      'x-partner-id':        PARTNER_ID,
      'x-betakom-timestamp': timestamp,
      'x-betakom-signature': signature,
    },
    body: payload, // sign and send the EXACT same bytes
  });
}
cURL
# 1. Build the body once and sign "<timestamp>.<body>"
TS=$(date +%s)
BODY='{"partnerOrderId":"PO-1001","customer":{"email":"kunde@example.com"},"loading":{"country":"DE","city":"Berlin","postalCode":"10115"},"unloading":{"country":"DE","city":"Muenchen","postalCode":"80331"},"vehicleType":"sprinter","totalPriceEur":480}'
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$BETAKOM_PARTNER_SECRET" | awk '{print $2}')

# 2. Send the same bytes you signed
curl -X POST 'https://betakom.de/api/v1/partners/orders/ingest' \
  -H 'content-type: application/json' \
  -H "x-partner-id: acme" \
  -H "x-betakom-timestamp: $TS" \
  -H "x-betakom-signature: v1=$SIG" \
  -d "$BODY"

Verification & errors

  • Replay protection: the timestamp must be within ±5 minutes of Betakom server time, or the request is rejected with 401.
  • Signature mismatch / unknown partner: returns 401 with a generic message (we don't reveal whether a partner exists or is inactive).
  • Body limits: the order-ingest endpoint caps bodies at 100 KB (413) and rate-limits to 60 requests/minute per partner (429).

Customer API keys

The Customs Clearance API is for Betakom business customers and uses a simpler scheme: a per-company API key. The company owner creates keys in the customer dashboard under Customs › API; each key is shown exactly once. Send it as a bearer token on every request:

cURL
curl 'https://betakom.de/api/v1/customs/cases' \
  -H "Authorization: Bearer bk_live_…"
  • X-API-Key: bk_live_… is accepted as an alternative header.
  • A key acts with the rights of the owner who created it. It stops working when it is revoked in the dashboard or when that person is removed from the company account — answered with 401 api_key_invalid.
  • At most 120 requests per minute per key (429 with Retry-After). Keep keys server-side; never ship them in a browser or mobile app.