TracePass
Inizia ora
Passaporti

Archiviare un passaporto (irreversibile)

Irreversibile. Il visualizzatore pubblico restituisce 404, l'URL GS1 Digital Link smette di risolvere, il codice QR muore definitivamente, a meno che il passaporto non sia stato reindirizzato a un nuovo fornitore. Usatelo SOLO per prodotti mai spediti — archiviare il passaporto di un prodotto già nelle mani dei clienti rompe ogni scansione QR che ne faranno.

POST/api/v1/passports/{id}/archive
Scarica OpenAPI 3.1
POST/api/v1/passports/{id}/archive

Archiviare un passaporto (irreversibile)

Irreversibile. Il visualizzatore pubblico restituisce 404, l'URL GS1 Digital Link smette di risolvere, il codice QR muore definitivamente, a meno che il passaporto non sia stato reindirizzato a un nuovo fornitore. Usatelo SOLO per prodotti mai spediti — archiviare il passaporto di un prodotto già nelle mani dei clienti rompe ogni scansione QR che ne faranno.

Il metodo HTTP è POST e il percorso include il segmento letterale archive — entrambi un attrito intenzionale. Per togliere invece un passaporto dall'API e da ogni superficie pubblica, eliminatelo in due passaggi: POST /api/v1/passports/{id}/mark-for-deletion, poi DELETE /api/v1/passports/{id}. Un passaporto contrassegnato per l'eliminazione non può essere archiviato (409 passport_already_marked_for_deletion). Conta come una scrittura v1. Rispetta Idempotency-Key. Attiva il webhook passport.archived. Idempotente: chiamare archive su un passaporto già archiviato restituisce 200.

I passaporti della batteria richiedono un motivo. Secondo il Regolamento sulle batterie il passaporto della batteria termina solo dopo che la batteria è stata riciclata (art. 77, paragrafo 8), quindi l'archiviazione ne indica il motivo: recycled, never_placed (mai immessa sul mercato) o duplicate_or_error. Senza motivo, un passaporto della batteria restituisce 400 reason_required. Per le altre categorie il corpo è facoltativo; un reason indicato deve essere uno degli stessi tre valori. Il motivo è incluso nel payload del webhook passport.archived. POST /api/v1/passports/by-serial/{serial}/archive accetta lo stesso corpo.

never_placed è rifiutato per un passaporto immesso sul mercato. Un passaporto registrato come immesso sul mercato risponde 409 reason_contradicts_placement con questo motivo. recycled e duplicate_or_error restano disponibili.

Parametri di percorso

  • idobbligatorio

    string (24 hex chars)

    ID del passaporto.

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.

Campi del corpo

  • reason

    enum

    recycled, never_placed o duplicate_or_error. Obbligatorio per i passaporti della batteria, facoltativo per le altre categorie.

    e.g. never_placed

Richiesta

curl -sS -X POST \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/archive \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "never_placed" }'

Risposta

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "status": "archived",
  "archivedAt": "2026-05-09T17:00:00.000Z",
  "archiveReason": "never_placed"
}

Endpoint correlati