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 tutti i documenti della libreria documenti dello spazio di lavoro.

get/organizations/{organization}/documents

Ambito: documents: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.

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.

typestringaFacoltativo

Restituisce solo i documenti di questo tipo.

access_tierstringaFacoltativo

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/documents?type=conformity_declaration" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Risposta · 200

{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/documents?type=conformity_declaration

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

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.

typestringaFacoltativo

Restituisce solo i documenti di questo tipo.

access_tierstringaFacoltativo

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

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

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_idstringaObbligatorio

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

typestringaObbligatorio

Obbligatorio in caricamento; deve essere assente quando document_id è valorizzato. Uno fra certification, image, document, conformity_declaration. Un'image caricata con access_tier: public viene mostrata come foto del prodotto sulla pagina pubblicata del passaporto; più immagini formano una galleria. Questa API non può scegliere quale sia la foto principale: la imposta una persona nell'editor del passaporto, nelle foto del prodotto. Nessuno schema di categoria dichiara un campo immagine, quindi il caricamento è l'unico modo per dare una foto a un passaporto.

access_tierstringaObbligatorio

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_namestringaObbligatorio

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

mime_typestringaObbligatorio

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_sizeinteroFacoltativo

Dimensione in byte, fino a 10485760.

display_namestringaFacoltativo

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