Documentos

Los documentos se adjuntan a una solicitud, no directamente a un solicitante. Cada carga acerca la solicitud principal a «lista para enviar»: cuando pendingDocTypes está vacío, puede enviar la solicitud para su procesamiento.

Cargar un documento

POST /api/v1/kyc/requests/:requestId/documents    Ámbito: kyc:write

Carga multiparte. Pase documentType (y side, si corresponde) como parámetros de consulta, y el archivo en un campo de formulario file.

Parámetros de consulta

Cuerpo del formulario

Tipos de documento

Ejemplo

# Upload the front of a driver's license
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents?documentType=GOVERNMENT_ID&side=front" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/license-front.jpg"

Respuesta (201)

{
  "id": "doc_01J...",
  "documentType": "GOVERNMENT_ID",
  "side": "front",
  "status": "pending",
  "fileSize": 412938,
  "mimeType": "image/jpeg",
  "requestStatus": "PENDING_UPLOAD",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "message": "Document uploaded. Front of GOVERNMENT_ID received; back of GOVERNMENT_ID still required."
}

La respuesta siempre indica lo que falta mediante pendingDocTypes. Cuando ese array está vacío, su siguiente llamada debe ser POST /requests/:id/submit.

Valores de estado del documento

• pending: subido, pero aún no procesado (solo ocurre antes de enviar la solicitud).
• verified: superó todas las comprobaciones de autenticidad tras enviarse la solicitud.
• failed: no superó una comprobación de autenticidad. Revise los registros de comprobación vinculados en GET /requests/:id para ver el motivo concreto.
• corrupted: el archivo no pudo decodificarse. Vuelva a subirlo.

Errores

• 400 BAD_REQUEST:
  • El archivo supera los 10 MB.
  • Tipo MIME no admitido.
  • Falta side para GOVERNMENT_ID.
  • documentType no permitido por la configuración KYC de la organización.
• 404 NOT_FOUND: la solicitud principal no existe en esta organización.
• 409 CONFLICT: la solicitud no está en PENDING_UPLOAD. No puede añadir documentos a una solicitud que ya se ha enviado.

Obtener una URL de descarga

GET /api/v1/kyc/requests/:requestId/documents/:docId/url    Ámbito: kyc:read

Los documentos se almacenan en un almacenamiento de objetos privado. Para ver o descargar uno, obtenga una URL firmada de corta duración.

Respuesta

{
  "url": "https://storage.certivant.com/kyc/org_.../req_.../doc_....jpg?X-Amz-Signature=...",
  "expiresIn": 900
}

expiresIn está en segundos: la URL es válida durante 15 minutos. Genere una nueva cada vez que necesite mostrar un documento; no las almacene en caché.

La url devuelta es una URL de almacenamiento prefirmada (S3 / Azure Blob / GCS). Se abre directamente en una pestaña del navegador y se muestra sin cabecera Authorization:

• Imágenes (image/jpeg, image/png, image/webp) → <img src="{url}" />
• PDF (application/pdf) → <iframe src="{url}" /> u <object data="{url}" type="application/pdf" />

Compruebe el mimeType de cada documento (de GET /requests/:id) para decidir cómo mostrarlo.

Descargar los bytes en bruto

GET /api/v1/kyc/requests/:requestId/documents/:docId/download    Ámbito: kyc:read

Devuelve directamente los bytes del archivo del documento, con el Content-Type almacenado (image/jpeg, image/png, image/webp o application/pdf) y Content-Disposition: inline. Sin URL firmada, sin redirección.

curl -L "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents/doc_01J.../download" \
  -H "Authorization: Bearer ck_live_..." \
  -o government_id_front.jpg

Prefiera esta opción a la ruta de URL firmada cuando muestre documentos dentro de su propio panel:

• Funciona con todos los backends de almacenamiento, incluido el disco local, cuya URL firmada /uploads/… solo es accesible desde dentro del host de Certivant y devolvería 404 desde otro origen.
• Hágala pasar por su backend y sírvala desde el mismo origen (<img src="/your-proxy/doc"> para imágenes, <iframe> para PDF). La clave Authorization: Bearer permanece en el servidor y nunca llega al navegador.
• Nunca se expone ninguna URL de almacenamiento, así que no hay nada que filtrar ni que caduque.

Reemplazar documentos

No puede editar un documento en su lugar. Si el solicitante subió una foto borrosa y quiere una nueva toma:

1. La solicitud debe estar en PENDING_UPLOAD (o debe reenviar primero una solicitud rechazada para eliminar los documentos anteriores).
2. Suba un nuevo documento con el mismo documentType y side. El anterior queda reemplazado: solo se usa la versión más reciente para el procesamiento.

Esta regla existe por la integridad de la auditoría: un historial inmutable de cada carga se conserva en el registro de auditoría, incluso cuando cambia el documento activo.

Listar los documentos de una solicitud

No existe un endpoint de listado de documentos independiente. La lista completa se incluye en la respuesta de GET /api/v1/kyc/requests/:id:

{
  "id": "req_...",
  "documents": [
    { "id": "doc_a", "documentType": "GOVERNMENT_ID", "side": "front", "status": "verified", ... },
    { "id": "doc_b", "documentType": "GOVERNMENT_ID", "side": "back", "status": "verified", ... },
    { "id": "doc_c", "documentType": "SELFIE", "status": "verified", ... }
  ]
}

Recorra documents y llame a /download (para pasar los bytes por su backend) o a /url (para un enlace firmado) en cualquier documento concreto que quiera mostrar.

Relacionado

• Solicitudes KYC: el endpoint principal al que se adjuntan sus documentos.
• Sesiones alojadas: permita que Certivant recopile los documentos directamente del solicitante.
• Esquemas: enumeración completa de documentType, status y valores relacionados.