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

organizationstringaObbligatorio

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

idstringaObbligatorio

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

Parametri di query

limitstringaFacoltativo

Quanti record restituire. Il server può restituirne meno.

cursorstringaFacoltativo

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

statusstringaFacoltativo

Restituisce solo le unità in questo stato.

unit_serialstringaFacoltativo

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",
      "values": {
        "status": {
          "value": "original",
          "source": "brand_statement",
          "observed_on": "2026-08-02",
          "reading_id": "a1100000-0000-4000-8000-000000000001",
          "unit_added_on": null
        }
      },
      "missing_fields": []
    }
  ],
  "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

organizationstringaObbligatorio

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

idstringaObbligatorio

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

Corpo della richiesta

unitselenco di oggettiObbligatorio

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_serialstringaObbligatorio

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

statusstringaFacoltativo

Stato facoltativo della batteria: original, repurposed, re-used, remanufactured o waste. Lo ometta per creare una batteria senza stato. Gli altri valori sono rifiutati per tutte le credenziali.

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",
      "values": {
        "status": {
          "value": "original",
          "source": "brand_statement",
          "observed_on": "2026-08-02",
          "reading_id": "a1100000-0000-4000-8000-000000000001",
          "unit_added_on": null
        }
      },
      "missing_fields": []
    },
    {
      "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",
      "values": {},
      "missing_fields": []
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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