Risorse

Documenti

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

Elencare i documenti collegati a un passaporto.

get/organizations/{organization}/passports/{id}/documents
Ambito
documents: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.

typestringFacoltativo

Restituisce solo i documenti di questo tipo.

access_tierstringFacoltativo

Restituisce solo i documenti pubblicati per questo livello di destinatari.

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/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents?access_tier=public" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Risposta · 200
{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "type": "conformity_declaration",
      "access_tier": "public",
      "file_name": "doc-2026-kestrel.pdf",
      "display_name": "EU Declaration of Conformity",
      "mime_type": "application/pdf",
      "file_size": 184320,
      "upload_state": "ready",
      "uploaded_at": "2026-07-29T15:44:02.008Z",
      "livemode": true,
      "created_at": "2026-07-29T15:43:51.660Z",
      "linked_at": "2026-07-29T15:43:51.660Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents?access_tier=public

Creare un documento e ottenere un URL di caricamento firmato.

post/organizations/{organization}/passports/{id}/documents
Ambito
documents: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

Questo endpoint accetta uno di due corpi della richiesta. Ne invii una sola forma: un corpo che combina i campi di entrambe viene rifiutato.

Collegare un documento già presente nella libreria

document_idstringObbligatorio

Collega un documento già presente nella libreria dell'organizzazione invece di caricarne uno. Non può essere combinato con nessuno dei campi di caricamento. Collegare un documento non ancora allegato risponde 201; ricollegarne uno già allegato risponde 200. Nessuna delle due risposte porta un oggetto upload.

Caricare un nuovo file

typestringObbligatorio

Obbligatorio in caricamento; deve essere assente quando document_id è valorizzato. Uno fra certification, image, document, conformity_declaration.

access_tierstringObbligatorio

Obbligatorio in caricamento; deve essere assente quando document_id è valorizzato. Uno fra public, restricted, authority. Determina chi potrà leggere il file una volta che il passaporto è online.

file_namestringObbligatorio

Obbligatorio in caricamento; deve essere assente quando document_id è valorizzato. Il nome con cui archiviare il file.

mime_typestringObbligatorio

Obbligatorio in caricamento; deve essere assente quando document_id è valorizzato. Uno fra application/pdf, image/png, image/jpeg, image/webp. Viene inoltrato tale e quale allo storage, che rifiuta un valore non corrispondente.

file_sizeintegerFacoltativo

Dimensione in byte, fino a 10485760.

display_namestringFacoltativo

L'etichetta che vede chi legge. Se omesso, vale file_name.

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/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "display_name": "EU Declaration of Conformity"
}'
Risposta · 201
{
  "object": "document",
  "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "display_name": "EU Declaration of Conformity",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "upload_state": "pending",
  "uploaded_at": null,
  "livemode": true,
  "created_at": "2026-08-02T09:40:12.331Z",
  "linked_at": "2026-08-02T09:40:12.331Z",
  "upload": {
    "url": "https://<project>.supabase.co/storage/v1/object/upload/sign/passport-assets/<organization>/library/<uuid>-doc-2026-kestrel.pdf?token=<jwt>",
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    },
    "expires_at": "2026-08-02T11:40:12.331Z",
    "max_bytes": 10485760
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents

Documenti — riferimento dell'API di PassportCraft | PassportCraft