JiriUhlir
95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
# PPL CPL API — přehled služby
|
|
|
|
Stateless multi-tenant proxy nad PPL CPL API (Create Package Label).
|
|
Upstream: `https://api.dhl.com/ecs/ppl/myapi2` (production),
|
|
`https://api-dev.dhl.com/ecs/ppl/myapi2` (test).
|
|
Dokumentace PPL: https://ppl-cpl-api.apidog.io/
|
|
|
|
## Autentizace
|
|
|
|
Každý request nese hlavičky:
|
|
|
|
- `X-Client-Id` — PPL ClientId (secret)
|
|
- `X-Client-Secret` — PPL ClientSecret (secret)
|
|
- `X-Environment` — `production` (default) nebo `test`
|
|
- `Accept-Language` — volitelně, předává se do PPL (např. `cs-CZ`)
|
|
|
|
Služba z údajů získá OAuth Bearer token (`POST {base}/login/getAccessToken`,
|
|
grant `client_credentials`, scope `myapi2`) a **cachuje ho in-memory** pod
|
|
SHA-256 hashem údajů. Důvod: PPL vydá max. 12 tokenů/min a token platí 30 minut.
|
|
Token se obnovuje 60 s před expirací; na HTTP 401 z PPL se jednou obnoví
|
|
a request se zopakuje.
|
|
|
|
## Limity PPL, které služba respektuje
|
|
|
|
- min. 40 ms rozestup mezi requesty (globální throttle v procesu),
|
|
- max. 1000 zásilek / 100 objednávek v jednom batchi,
|
|
- batchId platí 30 dní,
|
|
- pouze Latin znaky bez diakritiky — viz transliterace níže.
|
|
|
|
## Transliterace diakritiky
|
|
|
|
CPL API odmítá texty s diakritikou. Těla `POST /shipments/batch`,
|
|
`/shipments/create-and-wait`, `/orders/batch` a `/orders/create-and-wait`
|
|
se defaultně rekurzivně transliterují přes unidecode (`Jiří Dvořák` →
|
|
`Jiri Dvorak`). Chování:
|
|
|
|
- query parametr `transliterate=true|false` na requestu má přednost,
|
|
- jinak platí env `CPL_TRANSLITERATE` (default `true`),
|
|
- generická `/proxy/...` NEtransliteruje nikdy (předává 1:1).
|
|
|
|
## Chybové odpovědi
|
|
|
|
Jednotný JSON `{error, message, detail}`; `detail` obsahuje původní
|
|
problem+json z PPL (typ, title, errors...).
|
|
|
|
| Status | Význam |
|
|
|---|---|
|
|
| 400 | validační chyba (vstup zde nebo v PPL) |
|
|
| 401 | chybějící X- hlavičky nebo PPL odmítlo údaje/token |
|
|
| 403 | chybí oprávnění (role) k metodě v PPL |
|
|
| 404 | batch/zásilka/objednávka neexistuje |
|
|
| 429 | rate limit PPL |
|
|
| 502 | výpadek / neočekávaná chyba PPL |
|
|
|
|
Všechny chyby se logují (bez secrets) — žádná tichá selhání.
|
|
|
|
## Konfigurace (environment variables)
|
|
|
|
| Proměnná | Default | Význam |
|
|
|---|---|---|
|
|
| `ROOT_PATH` | `""` | prefix za reverse proxy (`/apps/pplcplapi`) |
|
|
| `CPL_DEFAULT_ENVIRONMENT` | `production` | prostředí bez hlavičky X-Environment |
|
|
| `CPL_PRODUCTION_BASE_URL` / `CPL_TEST_BASE_URL` | viz výše | base URL upstreamu |
|
|
| `CPL_OAUTH_SCOPE` | `myapi2` | OAuth scope |
|
|
| `CPL_TRANSLITERATE` | `true` | default transliterace diakritiky |
|
|
| `UPSTREAM_TIMEOUT_SECONDS` | `60` | timeout volání PPL |
|
|
| `TOKEN_REFRESH_MARGIN_SECONDS` | `60` | předstih obnovy tokenu |
|
|
| `MIN_REQUEST_INTERVAL_SECONDS` | `0.04` | rozestup requestů na PPL |
|
|
| `BATCH_POLL_INTERVAL_SECONDS` | `1.0` | interval pollingu create-and-wait |
|
|
| `BATCH_WAIT_TIMEOUT_SECONDS` | `30` | default timeout create-and-wait |
|
|
| `LOG_LEVEL` | `INFO` | úroveň logování |
|
|
|
|
Žádné secrets se nekonfigurují přes env — vše chodí per-request v hlavičkách.
|
|
|
|
## Struktura kódu
|
|
|
|
```
|
|
app/
|
|
main.py — FastAPI aplikace, root_path, popis pro Swagger
|
|
config.py — env konfigurace
|
|
credentials.py — X- hlavičky -> Credentials (dependency)
|
|
token_cache.py — in-memory cache OAuth tokenů
|
|
cpl_client.py — autentizovaný httpx klient, throttle, relay helpery
|
|
transliterate.py — rekurzivní unidecode JSON těl
|
|
errors.py — typované chyby + handlery
|
|
routers/
|
|
meta.py — /health, /version
|
|
shipments.py — zásilky, etikety, tracking, storno, celní dokumenty
|
|
orders.py — objednávky svozu/přepravy
|
|
codelists.py — číselníky, /version-information, /cpl-info
|
|
lookups.py — /access-points, /address-whisper, /routing, /data/{guid}
|
|
customer.py — /customer, /customer/addresses, /customer/number-range
|
|
proxy.py — generická proxy /proxy/{cesta}
|
|
```
|