Risorse

Unità

Tutti gli endpoint Unità, con l'ambito che impongono, il corpo che accettano, una risposta leggibile e i rifiuti che possono restituire.

Elencare le unità serializzate.

get/organizations/{organization}/passports/{id}/units

Ambito: units:read
Idempotency-Key: Non accettata
Restituisce: 200

Parametri di percorso

organizationstringObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Parametri di query

limitstringFacoltativo

Quanti record restituire. Il server può restituirne meno.

cursorstringFacoltativo

Il next_cursor della pagina precedente. Un cursore codifica i filtri con cui è stato emesso; inviarlo con filtri diversi viene rifiutato con cursor_invalid.

statusstringFacoltativo

Restituisce solo le unità in questo stato.

unit_serialstringFacoltativo

Restituisce la singola unità che porta questo numero di serie.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units?limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Risposta · 200

{
  "object": "list",
  "data": [
    {
      "object": "unit",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000117",
      "status": "original",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units?limit=25

Creare unità serializzate.

post/organizations/{organization}/passports/{id}/units

Ambito: units:write
Idempotency-Key: Accettata
Restituisce: 201

Parametri di percorso

organizationstringObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

idstringObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Corpo della richiesta

unitsarray of objectsObbligatorio

Da 1 a 1000 unità. Il passaporto padre deve appartenere alla categoria battery: le unità serializzate sono un concetto proprio delle batterie, e qualsiasi altro padre viene rifiutato con invalid_request. Un numero di serie ripetuto all'interno della stessa richiesta viene rifiutato riga per riga anziché deduplicato, così un processo di importazione massiva non crede mai di aver creato una riga che non ha creato.

unit_serialstringObbligatorio

Il numero di serie che questo esemplare fisico porta con sé, fino a 70 caratteri. Univoco all'interno del passaporto.

statusstringFacoltativo

Lo stato del ciclo di vita, dal vocabolario dell'allegato XIII: original, repurposed, re-used, remanufactured, waste. Memorizzato come testo libero fino a 70 caratteri: un valore fuori da quell'elenco viene accettato e poi non riconosciuto da nulla.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "units": [
    {
      "unit_serial": "BAT-2026-000117",
      "status": "original"
    },
    {
      "unit_serial": "BAT-2026-000118"
    }
  ]
}'

Risposta · 201

{
  "object": "list",
  "data": [
    {
      "object": "unit",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000117",
      "status": "original",
      "livemode": true,
      "created_at": "2026-08-02T09:31:18.446Z"
    },
    {
      "object": "unit",
      "id": "5a3e7c19-2b60-4d84-91f2-7e0c4b6a8d35",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/5a3e7c19-2b60-4d84-91f2-7e0c4b6a8d35",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_serial": "BAT-2026-000118",
      "status": null,
      "livemode": true,
      "created_at": "2026-08-02T09:31:18.446Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units