Удостоверяване

TracePass v1 използва един механизъм за удостоверяване: статичен API ключ, подаден като Bearer token в стандартнияAuthorizationheader. Всяка операция за запис приема иIdempotency-Keyза безопасни повторения. Лимитите са за план, за UTC ден — достъпни са на всеки план, включително Free, с дневен брой заявки, който скалира с плана.

API ключове

Генерирайте ключове в Developer → API keys в таблото. Ключовете са обвързани с работно пространство: всеки ключ е свързан с едно работно пространство и наследява неговия план, лимити и одитна следа. Ключовете носят префикс tp_, последван от непрозрачен случаен суфикс — няма отделен live / test префикс и няма env-неймспейснат sandbox. Тествайте в работното си пространство Free или Basic, ако ви е нужна непродукционна среда.

Подавайте ключа като Bearer token при всяка заявка:

curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

Idempotency-Key

Всеки POST, PATCH и DELETE по v1 повърхността приема Idempotency-Key header. Изпратете UUID v4 (или произволен непрозрачен низ ≤ 255 знака) за всяка логическа операция; платформата съхранява първия отговор за 24 часа и го повтаря, ако същият ключ + същото работно пространство се появят отново. Повторенията по мрежата стават безопасни — няма да създадете два пъти паспорт, защото вашият HTTP клиент е направил повторение при преходен 5xx.

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "...", "gs1": { "gtin": "...", "serialNumber": "..." } }'

Повторно използване на същия ключ с различно тяло на заявката връща422 Unprocessable Entity с error: "Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body." — платформата не презаписва тихомълком, защото това почти винаги е грешка в клиента. Генерирайте нов ключ за реално нови операции.

Лимити на честотата

Прилагат се два тавана за UTC ден, за работно пространство:

1. v1 бюджет за записи — `maxV1WritesPerDay`

Брои всеки POST / PATCH / DELETE по v1 повърхността. Четенията не са включени в този брояч.

2. v1 бюджет за четене на паспорти — `maxV1PassportsPerDay`

Брои всеки GET по endpoints за паспорти (единично четене + пагиниран списък). Отделен от бюджета за запис, така че ERP, който изпраща актуализации, да не изяде квотата ви за четене и обратно.

Когато достигнете единия от двата тавана, отговорът е 429 Too Many Requests с тяло от типа { "error": "API rate limit: 500 writes/day via /api/v1. Currently 500 today; requested 1. Retry tomorrow (UTC) or upgrade your plan." }. Прозорецът се нулира в 00:00 UTC; не поддържаме плъзгащи се прозорци, защото те правят лимита по-труден за разсъждение надолу по веригата.

Отделна квота — maxDpps — ограничава общия брой активни DPP в работното ви пространство и се прилага чрез отговор 402 с тяло overage_required, когато планът поддържа overage за паспорт. Виж endpoint-а Create a passport за overage потока.

Какво още не поддържаме

OAuth 2.0 client-credentials, scoped sub-keys и IP allow-listing са в roadmap-а, но все още не са пуснати. Ако ви трябва някое от тях днес, генерирайте нов API ключ за всяка интеграция, за да можете да го отзовете на ниво интеграция — това е заобикалящото решение.