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

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

Избрани v1 операции за запис приемат header Idempotency-Key — продукти (създаване, пакетно, актуализиране, изтриване, архивиране), паспорти (създаване, пакетно, актуализиране, архивиране, спиране, актуализиране на поле, актуализиране на страна, флагове за състояние, записване на измервания), EPCIS capture и стартиране на scope каталог. Изпратете UUID v4 (или произволен непрозрачен низ ≤ 64 знака) за всяка логическа операция; платформата съхранява първия отговор за 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 ден, отчитани за всеки API ключ (OAuth приложението има собствен брояч):

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

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

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

Брои прочетените паспорти: заявка за списък брои размера на страницата си (limit, по подразбиране 20), дори когато последната страница връща по-малко; всяко друго четене брои 1 (единичен паспорт, неговият QR код, снимки на версии, EPCIS документ, проверка за съответствие и готовност за регистъра, както и EPCIS заявка, задача за EPCIS заснемане и каталогът за обхват). Отделен от бюджета за запис, така че 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 — ограничава броя на публикуваните паспорти в работното ви пространство. Паспорт, създаден през API, е чернова и не заема място, затова създаването никога не връща грешка за overage. Лимитът се прилага, когато публикувате от таблото. Над лимита таблото ви моли да потвърдите таксата за паспорт над лимита или отказва, ако планът ви няма такава тарифа; тогава надградете плана или архивирайте паспорти. Виж endpoint-а Create a passport.

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

OAuth client-credentials grant-ът (машинна идентичност без потребител) и IP allow-listing са в roadmap-а, но все още не са пуснати. За чист server-to-server достъп днес използвайте API ключ — генерирайте по един за всяка интеграция, за да можете да го отзовете на ниво интеграция.