Přepravní REST API pro balíky, palety a výdejní místa

{ "ok": true, "data": { }, "timestamp": "2026-06-29T10:00:00.000Z" }

{ "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "Popis chyby", "timestamp": "..." } }

{
  "type": "BOX",
  "place_id": "P12345",
  "external_id": "OBJ-2026-0001",
  "sender_name": "Sklad s.r.o.", "sender_country": "CZ", "sender_psc": "13000",
  "sender_city": "Praha", "sender_street": "Jiřího z Poděbrad", "sender_h_number": "123",
  "sender_phone": "+420777111222",
  "recipient_name": "Jan Novák", "recipient_phone": "+420777123456",
  "recipient_email": "jan@example.cz",
  "currency": "czk", "cod": 1290,
  "packs": [ { "weight": 2.5, "x": 30, "y": 20, "z": 15 } ]
}

{
  "ok": true,
  "data": {
    "package_id": "8f3c1d2e-…",
    "tracking_number": "IPS2600000193",
    "state": 0,
    "type": "BOX",
    "price": null,
    "price_currency": "CZK",
    "external_id": "OBJ-2026-0001",
    "number_of_packages": "1",
    "packages": [
      { "tracking_number": "IPS2600000193", "labels_url": "https://ips.basileus.cz/public-api/v1/shipments/IPS2600000193/label?lt=…" }
    ],
    "labels_url": "https://ips.basileus.cz/public-api/v1/shipments/IPS2600000193/label?lt=…",
    "box": {
      "erp_tracking": "BS0035004063",
      "pick_up_code": "4827",
      "labels_url": "https://…",
      "status": "reserved"
    },
    "idempotent": false
  },
  "timestamp": "..."
}

curl -X POST https://ips.basileus.cz/public-api/v1/shipments \
  -H "X-API-KEY: <váš_api_klíč>" \
  -H "Content-Type: application/json" \
  -d @shipment.json

{ "ok": true, "data": { "valid": true, "errors": [] }, "timestamp": "..." }

{ "ok": true, "data": { "valid": false, "errors": [
  { "field": "weight_kg", "code": "range", "message": "Do boxu max 20 kg." }
] }, "timestamp": "..." }

{
  "ok": true,
  "data": {
    "tracking_number": "IPS2600000193",
    "external_id": "OBJ-2026-0001",
    "state": 6,
    "type": "BOX",
    "cod": 1290,
    "payed_cod": "0",
    "sender": { "name": "Sklad s.r.o." },
    "recipient": { "name": "Jan Novák" },
    "items": [ { "weight": 2.5, "x": 30, "y": 20, "z": 15 } ],
    "box": {
      "pick_up_code": "4827",
      "erp_tracking": "BS0035004063",
      "labels_url": "https://…"
    }
  },
  "timestamp": "..."
}

{ "ok": true, "data": { "tracking_number": "IPS2600000193", "state": 11, "message": "Zásilka byla zrušena." }, "timestamp": "..." }

curl https://ips.basileus.cz/public-api/v1/shipments/IPS2600000193/label?format=pdf \
  -H "X-API-KEY: <váš_api_klíč>" \
  -o stitek.pdf

curl https://ips.basileus.cz/public-api/v1/shipments/IPS2600000193/label?format=zpl \
  -H "X-API-KEY: <váš_api_klíč>"

{
  "type": "HD",
  "external_id": "OBJ-ADR-1",
  "sender_name": "...", "sender_psc": "13000", "sender_city": "Praha",
  "sender_street": "...", "sender_h_number": "1", "sender_country": "CZ", "sender_phone": "+420…",
  "recipient_name": "...", "recipient_psc": "60200", "recipient_city": "Brno",
  "recipient_street": "...", "recipient_h_number": "2", "recipient_country": "CZ", "recipient_phone": "+420…",
  "packs": [ { "weight": 20, "x": 60, "y": 40, "z": 40 } ],
  "adr": { "un_number": "1170", "class": "3", "quantity": 20, "unit": "L", "packing_group": "II" }
}

{ "ok": true, "data": { "count": 34, "codes": [
  { "un_number": "1203", "class": "3", "name": "BENZÍN", "unit": "L", "uom_note": "čistý objem", "packaging": "3H1 (Plast. kanystr)" }
] }, "timestamp": "..." }

{
  "type": "HD",
  "external_id": "OBJ-FILES-1",
  "sender_name": "Sklad s.r.o.", "sender_country": "CZ", "sender_psc": "13000",
  "sender_city": "Praha", "sender_street": "Jiřího z Poděbrad", "sender_h_number": "123", "sender_phone": "+420777111222",
  "recipient_name": "Jan Novák", "recipient_country": "CZ", "recipient_psc": "11000",
  "recipient_city": "Praha 1", "recipient_street": "Václavské nám.", "recipient_h_number": "1", "recipient_phone": "+420777123456",
  "packs": [ { "weight": 2.0, "x": 30, "y": 20, "z": 15 } ],
  "files": [
    { "name": "adr-document.pdf", "data": "JVBERi0xLjQKJeLjz9MKMy..." },
    { "name": "faktura.pdf", "data": "JVBERi0xLjQKJ..." }
  ]
}

{
  "ok": true,
  "data": {
    "count": 1,
    "places": [
      {
        "type": 2, "active": 1, "name": "Box Praha 1", "place_id": "P12345",
        "partner": "alza", "address": "Václavské nám. 1", "city": "Praha",
        "postalCode": "11000", "country": "CZ",
        "gps": { "lat": 50.08, "lng": 14.42 }, "operatingHours": null
      }
    ]
  },
  "timestamp": "..."
}

{
  "external_id": "OBJ-PAL-SEP-0001",

  "sender_company": "Fakturační s.r.o.", "sender_street": "Účetní 1", "sender_city": "Praha",
  "sender_zip": "11000", "sender_country": "CZ", "sender_phone": "+420777000001",

  "pickup_same_as_sender": false,
  "pickup_company": "Sklad Plzeň", "pickup_street": "Skladová 99", "pickup_city": "Plzeň",
  "pickup_zip": "30100", "pickup_country": "CZ", "pickup_phone": "+420777000002",

  "receiver_company": "Příjemce a.s.", "receiver_street": "Hlavní 5", "receiver_city": "Brno",
  "receiver_zip": "60200", "receiver_country": "CZ", "receiver_phone": "+420777000003",

  "delivery_same_as_receiver": false,
  "delivery_company": "Pobočka Ostrava", "delivery_street": "Nádražní 10", "delivery_city": "Ostrava",
  "delivery_zip": "70200", "delivery_country": "CZ", "delivery_phone": "+420777000004",

  "goods_character": "neam",
  "cod": 12000, "extra_insurance_value": 50000, "customer_reference": "REF-2026-1",
  "packs": [
    { "package_type": "EP", "weight": 240, "x": 120, "y": 80, "z": 100, "protective_wrap": "stretch_foil" }
  ]
}

{ "ok": true, "data": { "valid": true, "errors": [] }, "timestamp": "..." }

{ "ok": true, "data": { "valid": false, "errors": [
  { "field": "receiver_phone", "code": "required", "message": "receiver_phone je povinné." },
  { "field": "sender_zip", "code": "required", "message": "sender_zip je povinné." }
] }, "timestamp": "..." }

{ "url": "https://vase-domena.cz/ips-webhook", "events": ["shipment.status_changed"], "secret": "volitelný_vlastní_secret" }

{
  "event": "shipment.status_changed",
  "delivery_id": "…",
  "data": {
    "tracking_number": "IPS2600000193",
    "state": 7,
    "status": "delivered",
    "status_label": "Doručeno",
    "carrier_code": "DELIVERED",
    "at": "2026-06-29T10:00:00.000Z"
  }
}

X-IPS-Event: shipment.status_changed
X-IPS-Delivery: …
X-IPS-Signature: HMAC-SHA256(tělo, secret)