first

2026-07-16 11:56:15 +02:00
parent b650357194
commit 0e05fef335
23 changed files with 1900 additions and 15 deletions
@@ -1,3 +1,50 @@
 # PPL CPL API

+Stateless multi-tenant proxy nad **PPL CPL API** (Create Package Label) běžící
+v AppFactory. Umožňuje tvorbu zásilek a tisk etiket, tracking, objednávky
+svozu/přepravy, číselníky, výdejní místa a našeptávač adres.
+
+## Přihlašovací údaje
+
+Předávají se **per-request v hlavičkách** (nikdy v těle, URL ani konfiguraci):
+
+| Hlavička | Význam |
+|---|---|
+| `X-Client-Id` | PPL CPL ClientId (přiděluje PPL) |
+| `X-Client-Secret` | PPL CPL ClientSecret |
+| `X-Environment` | volitelně `production` (default) / `test` |
+
+Služba si sama vyžádá OAuth Bearer token (client_credentials, scope `myapi2`)
+a cachuje ho in-memory podle hashe údajů — PPL limituje vydávání tokenů na
+12/min a token platí 30 minut.
+
+## Hlavní endpointy
+
+- `POST /shipments/batch` → vytvoření zásilek, vrací `batchId`
+- `GET /shipments/batch/{batchId}` → stav importu (Accepted/InProcess/Complete/Error)
+- `GET /shipments/batch/{batchId}/labels` → binární etikety (PDF/ZPL/JPG…)
+- `POST /shipments/create-and-wait` → celý tok v jednom requestu (volitelně etikety v base64)
+- `GET /shipments` → tracking
+- `POST /shipments/{n}/cancel`, `POST /shipments/{n}/redirect`, `POST /shipments/{n}/documents`
+- `POST /orders/batch`, `GET /orders/batch/{batchId}`, `POST /orders/create-and-wait`, `GET /orders`, `POST /orders/cancel`
+- `GET /codelists/{name}`, `GET /access-points`, `GET /address-whisper`, `GET /routing`
+- `GET /customer`, `GET /customer/addresses`, `POST /customer/number-range`
+- `/proxy/{cesta}` → generické volání libovolné metody CPL API 1:1
+
+Kompletní popis viz [documentation/](documentation/) a Swagger na `/docs`.
+
+## Poznámky
+
+- CPL API přijímá jen Latin znaky bez diakritiky — texty v create requestech se
+  defaultně transliterují (`transliterate=false` to vypne).
+- Služba dodržuje minimální rozestup requestů na PPL (40 ms).
+- Chyby: JSON `{error, message, detail}`, `detail` nese problem+json z PPL.
+
+## Lokální spuštění
+
+```bash
+pip install -r requirements.txt
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
 Generated by AppFactory.