API dla Cyfrowego Paszportu Produktu: dokumentacja dla deweloperów

Przegląd

API dla klientów to interfejs REST wykorzystujący JSON. Działa na danych Twojej organizacji, czyli na tych samych produktach i paszportach, które widzisz w aplikacji internetowej. Typowe zastosowania to integracja z systemem ERP lub PLM, nocna synchronizacja danych podstawowych lub skrypt pobierający kody QR do druku.

Bazowy adres URL to https://dpp.com2u.selfhost.eu/api/v1/integration. Wszystkie odpowiedzi są w formacie JSON, z wyjątkiem pobierania kodu QR i pliku PDF.

Pobierz specyfikację

Czytelną maszynowo dokumentację referencyjną wszystkich endpointów, pól, przykładów i odpowiedzi błędów stanowi specyfikacja OpenAPI 3.1 ze schematem zabezpieczeń ApiKeyAuth:

• Pobierz openapi.json
• Pobierz openapi.yaml

Ten sam plik udostępnia samo API pod adresem GET /api/v1/integration/openapi.json, bez klucza. Zaimportuj go do Swagger UI, Postmana lub wybranego generatora kodu. Opisy w pliku są w języku niemieckim.

Szybki start

1. Zarejestruj się lub zaloguj. API jest dostępne w planach płatnych, zob. Cennik.
2. Otwórz na platformie sekcję Organizacja i wygeneruj klucz API. Skopiuj go od razu, ponieważ jest wyświetlany tylko raz.
3. Przetestuj połączenie:

curl -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/me

Odpowiedź zawiera Twoją organizację, zakresy (scopes) klucza, Twój plan oraz zużycie wywołań API.

Uwierzytelnianie

Przy każdym wywołaniu wysyłaj klucz w nagłówku X-API-Key. Równoważny jest nagłówek Authorization: Bearer dpp_key_…. Organizacja wynika zawsze z klucza — identyfikator organizacji przekazany jako parametr nie jest uwzględniany. API nie akceptuje tokenów sesji z aplikacji internetowej.

Klucz należy do osoby, która go wygenerowała. Operacje są wykonywane z jej uprawnieniami jako Owner lub Admin. Jeśli ta osoba utraci tę rolę, API odpowiada kodem 403, dopóki nie zostanie wygenerowany nowy klucz. Wygenerowanie nowego klucza natychmiast unieważnia dotychczasowy. Platforma przechowuje wyłącznie skrót SHA-256 klucza.

Endpointy

Wszystkie ścieżki znajdują się pod /api/v1/integration. Każdy endpoint wymaga określonego zakresu (scope); nowy klucz ma wszystkie cztery.

Tworzenie produktu

Pole name jest obowiązkowe. Bez schema_key stosowany jest domyślny schemat Twojej organizacji; dostępne klucze zwraca GET /schemas. Pola danych można przekazać od razu. Za pomocą field_status określasz status wartości — do paszportu trafiają wyłącznie wartości approved.

curl -X POST https://dpp.com2u.selfhost.eu/api/v1/integration/products \
  -H "X-API-Key: $DPP_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Moduł baterii X1","category":"Baterie przemysłowe",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

Odpowiedź ze statusem 201 zawiera id produktu. Jest to jednocześnie niepowtarzalny identyfikator produktu zakodowany w kodzie QR. Limit produktów w Twoim planie obowiązuje tak samo jak w aplikacji internetowej.

Publikowanie paszportu, pobieranie kodu QR i PDF

Paszport zamraża zatwierdzone pola danych jako nową wersję. Jeśli brakuje pól obowiązkowych, API odpowiada kodem 422 i wymienia je w missing_fields.

curl -X POST -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passports

curl -o qr.png -H "X-API-Key: $DPP_API_KEY" \
  "https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/qr?format=png&size=600"

curl -o passport.pdf -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/pdf

Aby uzyskać kod QR w formie wektorowej, użyj format=svg. Plik PDF jest dostępny dopiero po publikacji — wcześniej API odpowiada kodem 404. Kod QR prowadzi do publicznej strony paszportu; więcej na ten temat w artykule Cyfrowy Paszport Produktu z Excela.

Kody błędów

W przypadku 401 i 403 pole detail zawiera obiekt z code i message, na przykład insufficient_scope lub api_not_in_plan. W przypadku 402 pole detail podaje zasób, limit i dotychczasowe zużycie.

Ograniczenia

Przez API ustawiasz pola danych na poziomie produktu. Pola dla partii lub pojedynczych egzemplarzy uzupełniasz w aplikacji internetowej. Nie ma limitu szybkości, ale obowiązuje limit wywołań w ramach planu; liczy się każde uwierzytelnione wywołanie. Pobranie specyfikacji nie jest wliczane. Aktualne plany i limity znajdziesz na stronie Cennik. Szablon do masowego importu bez API oferuje szablon danych.