first

documentation/orders.md

@@ -0,0 +1,38 @@
+# Objednávky přepravy a svozu
+
+| Endpoint služby | Upstream CPL | Popis |
+|---|---|---|
+| `POST /orders/batch` | `POST order/batch` | vytvoření objednávek (max 100), vrací `batchId` |
+| `GET /orders/batch/{batchId}` | `GET order/batch/{batchId}` | stav zpracování |
+| `POST /orders/create-and-wait` | (kombinace) | synchronní obálka |
+| `GET /orders` | `GET order` | vyhledání objednávek |
+| `POST /orders/cancel` | `POST order/cancel` | zrušení objednávky |
+
+## Typy objednávek (`orderType`)
+
+- **CollectionOrder** — svoz z registrované adresy zákazníka (pravidelní
+  odesílatelé). `recipient` se neuvádí.
+- **TransportOrder** — vyzvednutí z libovolné adresy; `sender` i `recipient`
+  jsou povinné.
+
+Povinná pole: `referenceId` (1–50 znaků), `shipmentCount` (1–50), `sendDate`.
+Volitelné: `productType` (BUSS domácí / IMPO mezinárodní), `customerReference`,
+`email`, `note`, `sendTimeFrom`, `sendTimeTo`.
+
+## Stav zpracování
+
+`GET /orders/batch/{batchId}` vrací `items[]` s `importState`
+(Accepted/InProcess/Complete/Error) a případným `errorMessage`/`errorCode`.
+
+## Vyhledání
+
+`GET /orders?limit=100&offset=0` — filtry: `orderNumbers`, `orderReferences`
+(= referenceId z batch requestu), `customerReferences`, `shipmentNumbers`,
+`orderIds`, `dateFrom/dateTo`, `sendDate`, `productType`,
+`orderStates` (Created, PickedUp, NotPickedUp, Canceled), `orderType`.
+Odpověď vrací i přidělená čísla zásilek (`shipmentNumbers`).
+
+## Zrušení
+
+`POST /orders/cancel?orderReference=ORD-0001` (nebo `customerReference=...`),
+volitelné tělo `{"note": "důvod"}`.