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.

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

organizationstringObligatorio

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

idstringObligatorio

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

Parámetros de consulta

limitstringOpcional

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

cursorstringOpcional

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.

typestringOpcional

Devuelve solo los documentos de este tipo.

access_tierstringOpcional

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

organizationstringObligatorio

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

idstringObligatorio

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_idstringObligatorio

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

typestringObligatorio

Obligatorio al subir un archivo; debe estar ausente cuando se indica document_id. Uno de: certification, image, document, conformity_declaration.

access_tierstringObligatorio

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_namestringObligatorio

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

mime_typestringObligatorio

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_sizeintegerOpcional

Tamaño en bytes, hasta 10485760.

display_namestringOpcional

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