API del passaporto digitale di prodotto: documentazione per sviluppatori

Panoramica

L’API client è un’interfaccia REST che utilizza JSON. Lavora sui dati del vostro mandante, cioè sugli stessi prodotti e passaporti dell’applicazione web. Gli usi tipici sono il collegamento di un sistema ERP o PLM, una sincronizzazione notturna dei dati di base o uno script che recupera codici QR da stampare.

L’URL di base è https://dpp.com2u.selfhost.eu/api/v1/integration. Tutte le risposte sono in JSON, tranne i download di codici QR e PDF.

Scaricare la specifica

Il riferimento leggibile da macchina di tutti gli endpoint, campi, esempi e risposte di errore è una specifica OpenAPI 3.1 con lo schema di sicurezza ApiKeyAuth:

• Scaricare openapi.json
• Scaricare openapi.yaml

L’API stessa fornisce lo stesso file a GET /api/v1/integration/openapi.json, senza chiave. Importatelo in Swagger UI, Postman o nel generatore di codice che preferite. Le descrizioni all’interno del file sono redatte in tedesco.

Avvio rapido

1. Registratevi o accedete. L’API fa parte dei piani a pagamento, vedere Prezzi.
2. Aprite l’area Mandante nella piattaforma e generate la chiave API. Copiatela subito, perché viene mostrata una sola volta.
3. Provate la connessione:

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

La risposta indica il vostro mandante, gli scope della chiave, il vostro piano e il consumo di chiamate API.

Autenticazione

Inviate la chiave a ogni chiamata nell’intestazione X-API-Key. Authorization: Bearer dpp_key_… funziona allo stesso modo. Il mandante viene sempre ricavato dalla chiave; un ID mandante passato come parametro viene ignorato. L’API non accetta i token di sessione dell’applicazione web.

La chiave appartiene alla persona che l’ha generata. Le azioni vengono eseguite con i diritti di tale persona come proprietario o amministratore. Se la persona perde questo ruolo, l’API risponde con 403 finché non viene generata una nuova chiave. Generare una nuova chiave revoca immediatamente la precedente. La piattaforma memorizza solo un hash SHA-256 della chiave.

Endpoint

Tutti i percorsi si trovano sotto /api/v1/integration. Ogni endpoint richiede uno scope; una nuova chiave li possiede tutti e quattro.

Creare un prodotto

name è obbligatorio. Senza schema_key vale lo schema predefinito del vostro mandante; GET /schemas restituisce le chiavi disponibili. Potete passare direttamente i campi dati. field_status definisce lo stato dei valori, e solo i valori approved confluiscono in un passaporto.

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":"Battery module X1","category":"Industrial batteries",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

La risposta con stato 201 contiene l’id del prodotto. È anche l’identificativo univoco di prodotto codificato nel codice QR. Vale la quota di prodotti del vostro piano, come nell’applicazione web.

Pubblicare un passaporto, scaricare il codice QR e il PDF

Un passaporto fissa i campi dati approvati come nuova versione. Se mancano campi obbligatori, l’API risponde con 422 e li elenca in 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

Per un codice QR vettoriale usate format=svg. Il PDF esiste solo dopo la pubblicazione; prima, l’API risponde con 404. Il codice QR rimanda alla pagina pubblica del passaporto, vedere Creare un passaporto digitale di prodotto da Excel per saperne di più.

Codici di errore

Per 401 e 403, detail contiene un oggetto con code e message, ad esempio insufficient_scope o api_not_in_plan. Per 402, detail indica la risorsa, il limite e il consumo finora.

Limiti

Tramite l’API compilate campi dati a livello di prodotto. I campi di lotti o di singole unità si gestiscono nell’applicazione web. Non c’è un limite di frequenza, ma una quota di chiamate per piano; ogni chiamata autenticata viene conteggiata. Il recupero della specifica non viene conteggiato. I piani e le quote attuali sono riportati nella pagina Prezzi. Per un’importazione in blocco senza API usate il modello di dati.