API pro digitální produktový pas: dokumentace pro vývojáře

Přehled

Zákaznické API je rozhraní REST pracující s JSON. Pracuje s daty vaší organizace, tedy se stejnými produkty a pasy, které vidíte ve webové aplikaci. Typickým využitím je napojení na systém ERP nebo PLM, noční synchronizace kmenových dat nebo skript, který stahuje QR kódy pro tisk.

Základní URL je https://dpp.com2u.selfhost.eu/api/v1/integration. Všechny odpovědi jsou ve formátu JSON, s výjimkou stahování QR kódu a PDF.

Stažení specifikace

Strojově čitelnou referencí všech endpointů, polí, příkladů a chybových odpovědí je specifikace OpenAPI 3.1 s bezpečnostním schématem ApiKeyAuth:

• Stáhnout openapi.json
• Stáhnout openapi.yaml

Stejný soubor poskytuje samotné API na adrese GET /api/v1/integration/openapi.json, bez klíče. Importujte jej do Swagger UI, Postmanu nebo generátoru kódu dle vlastní volby. Popisy uvnitř souboru jsou v němčině.

Rychlý start

1. Zaregistrujte se nebo se přihlaste. API je součástí placených tarifů, viz Ceník.
2. V platformě otevřete sekci Organizace a vygenerujte API klíč. Ihned si jej zkopírujte, protože se zobrazí pouze jednou.
3. Otestujte spojení:

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

Odpověď uvádí vaši organizaci, scopes klíče, váš tarif a spotřebu volání API.

Autentizace

Klíč posílejte při každém volání v hlavičce X-API-Key. Rovnocenně funguje Authorization: Bearer dpp_key_…. Organizace se vždy určuje podle klíče; ID organizace předané jako parametr se nevyhodnocuje. Tokeny relace webové aplikace API nepřijímá.

Klíč patří osobě, která jej vygenerovala. Akce probíhají s jejími oprávněními vlastníka nebo administrátora. Pokud tato osoba o roli přijde, API odpovídá kódem 403, dokud není vygenerován nový klíč. Vygenerováním nového klíče se dosavadní klíč okamžitě zneplatní. Platforma ukládá pouze hash klíče SHA-256.

Endpointy

Všechny cesty leží pod /api/v1/integration. Každý endpoint vyžaduje scope; nový klíč má všechny čtyři.

Založení produktu

name je povinné. Bez schema_key platí výchozí schéma vaší organizace; dostupné klíče vrací GET /schemas. Datová pole můžete předat rovnou. Pomocí field_status určíte stav hodnot; do pasu se dostanou pouze hodnoty 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":"Bateriový modul X1","category":"Průmyslové baterie",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

Odpověď se stavem 201 obsahuje id produktu. Je to zároveň jedinečný identifikátor produktu zakódovaný v QR kódu. Limit produktů vašeho tarifu platí stejně jako ve webové aplikaci.

Publikování pasu, stažení QR kódu a PDF

Pas zmrazí schválená datová pole jako novou verzi. Pokud chybí povinná pole, API odpoví kódem 422 a uvede je v 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

Pro vektorový QR kód použijte format=svg. PDF existuje až po zveřejnění, předtím API odpovídá kódem 404. QR kód odkazuje na veřejnou stránku pasu, více v návodu Vytvoření digitálního produktového pasu z Excelu.

Chybové kódy

U 401 a 403 obsahuje detail objekt s code a message, například insufficient_scope nebo api_not_in_plan. U 402 uvádí detail zdroj, limit a dosavadní spotřebu.

Omezení

Přes API nastavujete datová pole na úrovni produktu. Pole pro šarže nebo jednotlivé kusy spravujete ve webové aplikaci. Rate limit neexistuje, ale každý tarif má limit volání; počítá se každé ověřené volání. Načtení specifikace se nepočítá. Aktuální tarify a limity najdete na stránce Ceník. Pro hromadný import bez API slouží datová šablona.