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

TracePass v1 поддържа два метода за удостоверяване. API ключ (статичен Bearer token) е най-простият — подходящ за server-to-server и ERP интеграции. OAuth 2.0 с PKCE е за приложения на трети страни и AI асистенти, които действат от името на потребител със scoped, отзоваем достъп. И двата се подават като Bearer token в стандартния Authorizationheader; всяка операция за запис приема и Idempotency-Keyза безопасни повторения. Достъпни на всеки план, включително Free. Дневен лимит на заявките има само за Free (100/ден) и Basic (200/ден); Starter и по-горе са без ограничение.

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"

OAuth 2.0 (приложения, авторизирани от потребител)

Когато изграждате приложение, което други потребители на TracePass свързват — или AI асистент, който потребител авторизира — използвайте OAuth 2.0, вместо да искате от тях да поставят API ключ. Потребителят одобрява конкретни scopes на екран за съгласие; токенът за достъп, който генерира, е ограничен до сечението на ролята му в таблото и одобрените scopes. Регистрирайте приложението си в Developer → OAuth Apps (или програмно чрез Dynamic Client Registration на /api/oauth/register). Поддържаме authorization-code flow с PKCE — публичните клиенти (SPA / мобилни / MCP) не се нуждаят от secret; поверителните сървърни клиенти получават такъв.

Потокът

Discovery метаданните са на /.well-known/oauth-authorization-server (RFC 8414). Накратко: (1) насочете потребителя към /api/oauth/authorize с вашия client_id, redirect_uri, заявен scope, state и PKCE code_challenge (S256); (2) той одобрява и ние пренасочваме обратно с еднократен code; (3) разменете го на /api/oauth/token с вашия code_verifier за 15-минутен токен за достъп (плюс refresh token, ако е одобрен offline_access). Refresh токените се ротират при всяко използване; отзовавайте на /api/oauth/revoke (RFC 7009).

Scopes

Заявявайте само това, от което приложението ви се нуждае — екранът за съгласие показва на потребителя точно тях. Scope за запис допълнително изисква авторизиращият потребител да има роля с права за запис, така че viewer, който одобри passports:write, все пак не може да записва. API ключовете, за разлика от тях, са „всичко или нищо“ и пренебрегват scopes.

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: 200 writes/day via /api/v1. Currently 200 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 client-credentials grant-ът (машинна идентичност без потребител) и IP allow-listing са в roadmap-а, но все още не са пуснати. За чист server-to-server достъп днес използвайте API ключ — генерирайте по един за всяка интеграция, за да можете да го отзовете на ниво интеграция.