Към основното съдържание
Battery Compliance
Започнете безплатно
Меню

Разработчици

Свържете вашия ERP или производствени системи: създавайте и публикувайте паспорти на батерии, четете и обновявайте ги през DPP API, което следва EN 18222, и получавайте събития чрез уебхук. Достъпът до API е включен във всеки план, включително Free.

Две API

  • API за управление на паспорти

    /openapi.json

    За дружеството, което притежава паспортите: списък на модели и артикули (с курсор, с updatedSince за синхронизиране), създаване на артикули, диапазони и копия на модели, обновяване на данните на артикул, публикуване (на един артикул или във фонов режим) и получаване на QR кодове. Удостоверяване с API ключ.

    Справка: API за управление на паспорти

  • DPP API (EN 18222)

    /openapi-dpp.json

    API за жизнения цикъл и фина гранулярност по EN 18222: четене на паспорти на вашето ниво на достъп, търсене на идентификатори на паспорти по идентификатор на продукта, записване на събития (ремонт, състояние на изправност, статус) с токен за достъп OAuth 2.0. Публичните данни могат да се четат без токен.

    Справка: DPP API (EN 18222)

Четене на паспорт

Всеки адрес на паспорт отговаря с JSON, когато го поискате – не е нужен ключ за публични данни. Заглавките носят версията, нейния SHA-256 и подписа Ed25519, така че можете да проверите прочетеното спрямо нашите публични ключове.

curl -i -H "Accept: application/json" \https://batterycompliance.eu/id/BG123456789/EBIKE-48V/SN0001 HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8X-Passport-Version: 3X-Passport-Access-Level: publicX-Passport-SHA256: bd4c49c7b04ac463…81146b938X-Passport-Signature: Tw0bRkvf+s3IS1MQ…MPZ7Dg==X-Passport-Key-Id: batterycompliance-2026-09-25Link: </schema/battery-passport/2.0.0>; rel="describedby" { "dppHeader": { "dppStatus": { "dppStatusValue": "active" }, … },  "identifiersAndProductData": { "batterySerialNumber": "SN0001", … }, … }
Дългите стойности са съкратени. С токен за достъп същият адрес връща полетата на вашето ниво на достъп, а X-Passport-Access-Level го назовава.

Как работят API

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

API ключовете се създават от собственика на дружеството в Дружество → API ключове и се показват веднъж. Изпращайте ги като Authorization: Bearer bcp_live_…. Обхвати: items:read, items:write (включва и четене), items:publish, qr:read.

Клиентите на OAuth 2.0 (client credentials) се създават от собственика на дружеството за неговите партньори или от платформата за органи и одобрени трети лица. Вземете токен с POST /oauth/token (grant_type=client_credentials); той важи 15 минути. Обхвати: dpp:read, dpp:search, dpp:write.

Лимити и грешки

60 заявки в минута на API ключ (заглавки X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) и 120 в минута на клиент на OAuth или, без токен, на адрес. При надвишаване: HTTP 429 с Retry-After.

API за управление на паспорти отговаря на грешки с обект error с code, message и details; DPP API отговаря с statusCode, payload и result със статус кодовете на EN 18222.

Обновяванията през DPP API приемат заглавка Idempotency-Key: същият ключ със същата заявка в рамките на 24 часа връща първия отговор и не създава втора версия.

Публични паспорти

Всеки паспорт има постоянен адрес (GS1 Digital Link /01/{GTIN}/21/{serial} или /id/{operator}/{model}/{serial}). С Accept: application/json или ?format=json връща JSON на последната версия за вашето ниво на достъп; ?version=N – дадена версия; /versions – списъка.

Всяка версия е подписана: X-Passport-SHA256 носи SHA-256 на каноничния JSON по RFC 8785 на пълната версия, X-Passport-Signature – нейния подпис Ed25519 върху този шестнадесетичен низ, а X-Passport-Key-Id – ключа, който е подписал. Публичните ключове и схемата са изброени в Машинночетими описания.

Уебхукове

Вместо редовни запитвания добавете крайна точка в Дружество → Уебхукове. Събитията – passport.published, publish_job.finished, item.lifecycle_recorded, access_request.created, passport.transferred, label_template.issued, dossier.ready, import_batch.assigned, import_batch.confirmed, import_batch.rejected – се изпращат с POST като JSON със заглавките X-Webhook-Id, X-Webhook-Timestamp и X-Webhook-Signature = v1= + шестнадесетичен HMAC-SHA256 на timestamp.body с вашия таен ключ. Отговорете с 2xx в рамките на 10 секунди; неуспешните доставки се повтарят в продължение на 24 часа.

Машинночетими описания

Вземете API ключ

Регистрирайте дружеството си, после създайте ключ в Дружество → API ключове. Ключовете се показват веднъж и се съхраняват само като хеш.

Започнете безплатноСвържете се с нас