{
  "openapi": "3.1.0",
  "info": {
    "title": "Betakom Partner API",
    "version": "1.0.0",
    "description": "Public Betakom freight platform APIs. Authentication is HMAC-SHA256 for partner endpoints — see https://betakom.de/developers/authentication.",
    "contact": {
      "name": "Betakom Developer Support",
      "url": "https://betakom.de/developers/get-started"
    }
  },
  "servers": [
    {
      "url": "https://api.betakom.de",
      "description": "Production — Live environment. Calls create real orders and are billed."
    }
  ],
  "tags": [
    {
      "name": "Partner Order API",
      "description": "Push transport orders from your TMS onto the Betakom marketplace and drive their fulfilment lifecycle."
    },
    {
      "name": "Carrier Integration API",
      "description": "Push fleet data — live positions, dispatch plans, and declared availability — into Betakom's backhaul matcher."
    },
    {
      "name": "Pricing & Quote API",
      "description": "Get an instant freight rate for a lane (market price + Betakom margin)."
    },
    {
      "name": "Tracking API",
      "description": "Read the public status timeline and route summary for a shipment."
    }
  ],
  "paths": {
    "/api/v1/partners/orders/ingest": {
      "post": {
        "operationId": "partner-orders_ingest-order",
        "summary": "Create a marketplace order from a partner TMS",
        "description": "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.",
        "tags": [
          "Partner Order API"
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        },
        "security": [
          {
            "PartnerHmac": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "partnerOrderId": {
                    "type": "string",
                    "description": "Your order id. The idempotency key — a replay returns the original order."
                  },
                  "customer.email": {
                    "type": "string",
                    "description": "Customer email — the fulfilment-confirmation email is sent here."
                  },
                  "customer.name": {
                    "type": "string",
                    "description": "Customer / company name."
                  },
                  "customer.phone": {
                    "type": "string",
                    "description": "Customer phone."
                  },
                  "loading.country": {
                    "type": "string",
                    "description": "Pickup country, e.g. \"DE\"."
                  },
                  "loading.city": {
                    "type": "string",
                    "description": "Pickup city."
                  },
                  "loading.postalCode": {
                    "type": "string",
                    "description": "Pickup postal code."
                  },
                  "loading.address": {
                    "type": "string",
                    "description": "Pickup street address."
                  },
                  "loading.date": {
                    "type": "string",
                    "description": "Pickup date."
                  },
                  "loading.timeFrom / loading.timeTo": {
                    "type": "string",
                    "description": "Pickup time window."
                  },
                  "unloading.country": {
                    "type": "string",
                    "description": "Delivery country."
                  },
                  "unloading.*": {
                    "type": "string",
                    "description": "Same shape as loading (city, postalCode, address, date, timeFrom, timeTo)."
                  },
                  "vehicleType": {
                    "type": "string",
                    "description": "Requested vehicle type, e.g. \"sprinter\", \"24t\"."
                  },
                  "totalPriceEur": {
                    "type": "string",
                    "description": "Total agreed price in EUR. Must be > 0."
                  },
                  "currency": {
                    "type": "string",
                    "description": "Defaults to \"EUR\"."
                  },
                  "distanceKm": {
                    "type": "string",
                    "description": "Route distance in km."
                  },
                  "totalWeightKg": {
                    "type": "string",
                    "description": "Total cargo weight in kg."
                  },
                  "packages": {
                    "type": "string",
                    "description": "Packing list: [{ length, width, height, weight, quantity }]."
                  },
                  "extraServices": {
                    "type": "string",
                    "description": "Flags such as { tailLift: true }."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Free-text notes for the carrier."
                  }
                },
                "required": [
                  "partnerOrderId",
                  "customer.email",
                  "loading.country",
                  "unloading.country",
                  "totalPriceEur"
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/partners/orders/{id}/fulfill": {
      "get": {
        "operationId": "partner-orders_fulfill-confirm-page",
        "summary": "Render the fulfilment confirmation interstitial",
        "description": "Returns a confirmation page (no side effect — safe against email link prefetchers). Authenticated by the order's fulfillment_token.",
        "tags": [
          "Partner Order API"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The orderId returned by ingest.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "The fulfillment_token returned by ingest.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      },
      "post": {
        "operationId": "partner-orders_fulfill-confirm",
        "summary": "Confirm the order (make it binding)",
        "description": "Flips the order to binding once the customer confirms. Authenticated by the fulfillment_token.",
        "tags": [
          "Partner Order API"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The orderId returned by ingest.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "The fulfillment_token returned by ingest (sent in the query string).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/v1/partners/orders/{id}/decline": {
      "post": {
        "operationId": "partner-orders_decline-order",
        "summary": "Decline the order",
        "description": "Declines a pending partner order. Authenticated by the fulfillment_token in the query string.",
        "tags": [
          "Partner Order API"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The orderId returned by ingest.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "The fulfillment_token returned by ingest (sent in the query string).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/v1/carriers-module/my-company/integrations/inbound/{connector}/{token}": {
      "post": {
        "operationId": "carrier-integration_inbound-webhook",
        "summary": "Push fleet data to a carrier integration connection",
        "description": "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.",
        "tags": [
          "Carrier Integration API"
        ],
        "parameters": [
          {
            "name": "connector",
            "in": "path",
            "required": true,
            "description": "Connector id, e.g. \"inbound-webhook\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Your connection's inbound token (issued when the connection is created).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-betakom-signature",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 of the raw body, keyed with the connection's inbound secret.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Success"
          }
        },
        "security": [
          {
            "ConnectionToken": []
          }
        ]
      }
    },
    "/api/v1/public/freight-quotes": {
      "post": {
        "operationId": "pricing-quotes_freight-quote",
        "summary": "Request a freight quote for a lane",
        "description": "Request a freight quote for a lane",
        "tags": [
          "Pricing & Quote API"
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "loadingLocation": {
                    "type": "string",
                    "description": "Format \"postalCode city, countryCode\", e.g. \"10115 Berlin, DE\"."
                  },
                  "unloadingLocation": {
                    "type": "string",
                    "description": "Format \"postalCode city, countryCode\", e.g. \"80331 Munich, DE\"."
                  },
                  "weight": {
                    "type": "string",
                    "description": "Cargo weight in kg (> 0)."
                  },
                  "length": {
                    "type": "string",
                    "description": "Cargo length in metres — improves vehicle-type selection."
                  },
                  "accessApiKey": {
                    "type": "string",
                    "description": "Your shared Betakom freight-quotes API key."
                  }
                },
                "required": [
                  "loadingLocation",
                  "unloadingLocation",
                  "weight",
                  "accessApiKey"
                ]
              }
            }
          }
        }
      }
    },
    "/api/public/tracking/{orderId}": {
      "get": {
        "operationId": "tracking_track-order",
        "summary": "Get the tracking timeline + order summary",
        "description": "Get the tracking timeline + order summary",
        "tags": [
          "Tracking API"
        ],
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "description": "The Betakom order id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "t",
            "in": "query",
            "required": true,
            "description": "The signed share token for this order.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        },
        "security": [
          {
            "ShareToken": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PartnerHmac": {
        "type": "apiKey",
        "in": "header",
        "name": "x-betakom-signature",
        "description": "HMAC-SHA256 partner auth. Send x-partner-id, x-betakom-timestamp and x-betakom-signature = \"v1=\" + HMAC_SHA256(secret, \"<timestamp>.<rawBody>\"). See /developers/authentication."
      },
      "ConnectionToken": {
        "type": "apiKey",
        "in": "header",
        "name": "x-betakom-signature",
        "description": "Carrier inbound. The connection token is part of the URL path; the raw body is HMAC-signed with the connection secret in x-betakom-signature."
      },
      "ShareToken": {
        "type": "apiKey",
        "in": "query",
        "name": "t",
        "description": "Signed per-order share token."
      }
    }
  }
}