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}

3.9 KiB Raw Permalink Blame History