TracePass
Inizia ora
Passaporti

Creare un passaporto

Crea un singolo passaporto digitale di prodotto. Il passaporto è vincolato a un prodotto (productId) e identificato da un GS1 GTIN + un numero di serie univoco all'interno di quel GTIN. I nuovi passaporti iniziano nello stato `draft` — i campi vengono popolati tramite successive chiamate PATCH e il passaporto viene pubblicato dalla dashboard una volta completata la revisione.

POST/api/v1/passports
Scarica OpenAPI 3.1
POST/api/v1/passports

Creare un passaporto

Crea un singolo passaporto digitale di prodotto. Il passaporto è vincolato a un prodotto (productId) e identificato da un GS1 GTIN + un numero di serie univoco all'interno di quel GTIN. I nuovi passaporti iniziano nello stato `draft` — i campi vengono popolati tramite successive chiamate PATCH e il passaporto viene pubblicato dalla dashboard una volta completata la revisione.

Il GTIN deve essere di 14 cifre (o un EAN di 13 cifre, completato a 14) con una cifra di controllo GS1 valida e non ancora registrato a un altro tenant. Conta come una scrittura v1 E consuma uno slot DPP dalla quota `maxDpps` del vostro piano — quando tale quota è esaurita e il vostro piano supporta l'eccedenza, la chiamata restituisce 402 con un corpo `overage_required`; ritentate con `confirmOverage: true` per accettare l'addebito per passaporto.

Rispetta l'header opzionale `Idempotency-Key` — la piattaforma riproduce la risposta 201 originale per 24 ore con la stessa chiave, quindi un nuovo tentativo di rete è sicuro.

Header

  • Authorizationobbligatorio

    string

    `Bearer <token>` — una chiave API `tp_` (Developer → API Keys; più semplice, per server-to-server) oppure un access token OAuth 2.0 (Developer → OAuth Apps; per app autorizzate dall'utente, scoped e revocabili). La pagina Authentication contiene il flusso OAuth completo e l'elenco degli scopes.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 (o qualsiasi stringa opaca ≤ 64 caratteri) per operazione logica. La prima risposta viene riprodotta per 24 ore.

Campi del corpo

  • productIdobbligatorio

    ObjectId

    ID del prodotto a cui appartiene il passaporto. Deve appartenere all'azienda della chiave API.

    e.g. 6650a1b2c3d4e5f6a7b8c9d0

  • identifier

    ProductIdentifier

    Identificatore taggato per schema EN 18219. È richiesto esattamente uno tra `identifier` e il blocco legacy `gs1`. Accetta cinque schemi: `gs1` (GTIN + numero di serie), `iso15459` (ID agenzia non-GS1), `iec61406` (IEC Identification Link URI), `did` (W3C DID), `doi` (Digital Object Identifier). Per `doi`, il campo `granularity` è OBBLIGATORIO — deve essere `"model"`, `"batch"` o `"item"` (EN 18219 §5.6.2(b): un DOI deve dichiarare se identifica il modello del prodotto, un lotto di produzione o un singolo esemplare). I passaporti batteria accettano solo `gs1` e `iso15459`; `iec61406`, `did` e `doi` sono rifiutati ai sensi dell'art. 77(3) del Regolamento sulle batterie, che richiede un identificatore basato su ISO/IEC 15459.

  • gs1.gtin

    string (14 digits, or 13-digit EAN)

    GTIN-14 con cifra di controllo GS1 valida. Parte del blocco legacy `gs1` — per le nuove integrazioni preferire `identifier` con `scheme: "gs1"`. Non deve essere già registrato da un altro tenant.

    e.g. 04012345000016

  • gs1.serialNumber

    string (1-100 chars)

    Numero di serie univoco all'interno del GTIN. Lo schema più comune è il modello del prodotto + una sequenza (BP-48V-100-000001).

    e.g. BP-48V-100-000001

  • parties

    Record<role, Party>

    Blocco strutturale parties opzionale. Una mappa indicizzata per ruolo — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Ogni valore è una Party. Si veda l'endpoint Upsert party per la forma del corpo di ogni Party. I ruoli possono anche essere aggiunti o sostituiti dopo la creazione tramite PATCH /api/v1/passports/{id}/parties/{role}.

  • lineage

    LineageInput

    Solo per i passaporti delle batterie. Una batteria sottoposta alla preparazione per il riutilizzo, alla preparazione per il cambio di destinazione, al cambio di destinazione o alla rifabbricazione è munita di un nuovo passaporto collegato al passaporto o ai passaporti della batteria originaria (art. 77, paragrafo 7, del Regolamento sulle batterie). Inviate `{ predecessors: [ { internalPassportId | identifier, trigger } ] }` con al massimo 10 predecessori: `internalPassportId` per un vostro passaporto, `identifier` (il suo URI risolvibile) per qualsiasi altro. `trigger` è `preparation_for_reuse`, `preparation_for_repurposing`, `repurposing` o `remanufacturing`. `batteryStatus` è ricavato da questi valori, il blocco è immutabile dopo la creazione e i vostri passaporti originari ricevono un collegamento `successors`. Una batteria immessa sul mercato prima del 18 febbraio 2027 non ha un passaporto originario: inviate un elenco vuoto con `noPredecessorReason`. Le violazioni delle regole restituiscono 422 con il codice della regola in `error`, ad es. `duplicate_predecessor`, `predecessor_not_found`, `status_trigger_mismatch`.

  • confirmOverage

    boolean

    Accetta l'addebito di eccedenza per passaporto quando la quota `maxDpps` del piano è già esaurita. Obbligatorio solo dopo una risposta 402 a un tentativo precedente.

Richiesta

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": "6650a1b2c3d4e5f6a7b8c9d0",
    "gs1": {
      "gtin": "04012345000016",
      "serialNumber": "BP-48V-100-000001"
    }
  }'

Risposta

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "companyId": "6650a0b1c2d3e4f5a6b7c8d9",
  "productId": "6650a1b2c3d4e5f6a7b8c9d0",
  "templateId": "6650a1b2c3d4e5f6a7b8c9d1",
  "gs1": {
    "gtin": "04012345000016",
    "serialNumber": "BP-48V-100-000001",
    "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"
  },
  "status": "draft",
  "completionPercentage": 32,
  "fieldCounts": {
    "total": 52,
    "empty": 35,
    "approved": 17,
    "pendingReview": 0,
    "flagged": 0
  },
  "fields": { "...": "...seeded from product defaults + template defaults + company prefill..." },
  "createdAt": "2026-05-09T10:00:00.000Z"
}

Endpoint correlati