Recursos

Documentos

Todos los endpoints de Documentos, con el ámbito que imponen, el cuerpo que admiten, una respuesta legible y los rechazos que pueden devolver.

Enumerar todos los documentos de la biblioteca de documentos del espacio de trabajo.

get/organizations/{organization}/documents

Ámbito: documents:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

Parámetros de consulta

limitcadenaOpcional

Cuántos registros devolver. El servidor puede devolver menos.

cursorcadenaOpcional

El next_cursor de la página anterior. Un cursor codifica los filtros con los que se emitió; enviarlo con otros filtros se rechaza con cursor_invalid.

typecadenaOpcional

Devuelve solo los documentos de este tipo.

access_tiercadenaOpcional

Devuelve solo los documentos publicados para este nivel de audiencia.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/documents?type=conformity_declaration" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Respuesta · 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

Listar los documentos vinculados a un pasaporte.

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

Ámbito: documents:read
Idempotency-Key: No se acepta
Devuelve: 200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Parámetros de consulta

limitcadenaOpcional

Cuántos registros devolver. El servidor puede devolver menos.

cursorcadenaOpcional

El next_cursor de la página anterior. Un cursor codifica los filtros con los que se emitió; enviarlo con otros filtros se rechaza con cursor_invalid.

typecadenaOpcional

Devuelve solo los documentos de este tipo.

access_tiercadenaOpcional

Devuelve solo los documentos publicados para este nivel de audiencia.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

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"

Respuesta · 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

Crear un documento y obtener una URL de subida firmada.

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

Ámbito: documents:write
Idempotency-Key: Se acepta
Devuelve: 201

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

idcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Cuerpo de la solicitud

Este endpoint admite uno de dos cuerpos de solicitud. Envíe una sola forma: un cuerpo que combine campos de ambas se rechaza.

Vincular un documento que ya está en la biblioteca

document_idcadenaObligatorio

Vincula un documento que ya está en la biblioteca de la organización en lugar de subir uno nuevo. No puede combinarse con ninguno de los campos de subida. Vincular un documento aún no adjunto responde 201; volver a vincular uno ya adjunto responde 200. Ninguna de las dos respuestas lleva un objeto upload.

Subir un archivo nuevo

typecadenaObligatorio

Obligatorio al subir un archivo; debe estar ausente cuando se indica document_id. Uno de: certification, image, document, conformity_declaration. Una image subida con access_tier: public se muestra como la foto del producto en la página publicada del pasaporte; varias forman una galería. Esta API no puede elegir cuál es la foto principal: la establece una persona en el editor del pasaporte, en las fotos del producto. Ningún esquema de categoría declara un campo de imagen, así que subirla es la única forma de dar una foto a un pasaporte.

access_tiercadenaObligatorio

Obligatorio al subir un archivo; debe estar ausente cuando se indica document_id. Uno de: public, restricted, authority. Determina quién puede leer el archivo una vez que el pasaporte esté publicado.

file_namecadenaObligatorio

Obligatorio al subir un archivo; debe estar ausente cuando se indica document_id. El nombre con el que se guardará el archivo.

mime_typecadenaObligatorio

Obligatorio al subir un archivo; debe estar ausente cuando se indica document_id. Uno de: application/pdf, image/png, image/jpeg, image/webp. Se envía tal cual al almacenamiento, que rechaza cualquier discrepancia.

file_sizeenteroOpcional

Tamaño en bytes, hasta 10485760.

display_namecadenaOpcional

La etiqueta que ve un lector. Si se omite, se usa file_name.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud

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"
}'

Respuesta · 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