Carga de Documentos

Para avanzar un remitente a niveles de cumplimiento más altos (Nivel 2 en adelante), puede que necesites cargar documentos de identidad y comprobantes de origen de fondos. Los documentos se verifican automáticamente (OCR con IA, cuando esté habilitado para tu tenant) o por el equipo de cumplimiento de Inyo.

Documentos de Identidad

Endpoint: POST /organizations/{tenant}/people/{personId}/documents/documentId/{subtype}/upload
Autenticación: Nivel de tenant (x-api-key)
Content-Type: multipart/form-data

El segmento de ruta {subtype} es el tipo de documento. Se aceptan tanto el formato de transmisión (passport, driverLicense, nationalId, ...) como el formato canónico en mayúsculas (PASSPORT, DRIVER_LICENSE, ...). Tipos comunes:

Un subtipo desconocido devuelve 422 con la lista de valores permitidos.

Campos del Formulario

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID/documents/documentId/PASSPORT/upload \
  --header "x-api-key: $API_KEY" \
  --form "file=@/path/to/passport.jpg" \
  --form "idNumber=AB1234567" \
  --form "expirationDate=2030-12-31"

Respuesta (201):

{
  "id": "4ec66735-216b-4ab4-b1d7-00558baa6d85",
  "subtype": "PASSPORT",
  "fileName": "passport.jpg",
  "verificationStatus": "PENDING",
  "createdAt": "2026-08-04T12:00:00+00:00",
  "idNumber": "AB1234567",
  "issuer": null,
  "expirationDate": "2030-12-31"
}

Origen de Fondos

Comprobante del origen de fondos del remitente (estado de cuenta bancario, recibo de nómina), requerido para los niveles de cumplimiento más altos.

Endpoint: POST /organizations/{tenant}/people/{personId}/documents/sourceOfFunds/upload
Autenticación: Nivel de tenant (x-api-key)
Content-Type: multipart/form-data

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID/documents/sourceOfFunds/upload \
  --header "x-api-key: $API_KEY" \
  --form "file=@/path/to/bank-statement.pdf"

Aplican las mismas reglas de archivo que para los documentos de identidad (pdf/jpg/jpeg/png, máx. 10 MB). La carga se almacena bajo el tipo PROOF_OF_FUNDS.

Estado de Verificación de Documentos

Después de la carga, los documentos se verifican de forma asíncrona — mediante OCR con IA (si está habilitado para tu tenant) en cuestión de minutos, o de lo contrario por el equipo de cumplimiento.

Obtener el Estado de Verificación Actual

Endpoint: GET /organizations/{tenant}/documents/{documentId}/verificationStatus/current
Autenticación: Nivel de tenant

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/documents/$DOCUMENT_ID/verificationStatus/current \
  --header "x-api-key: $API_KEY"

Obtener el Historial de Estados de Verificación

Endpoint: GET /organizations/{tenant}/documents/{documentId}/verificationStatus
Autenticación: Nivel de tenant

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/documents/$DOCUMENT_ID/verificationStatus \
  --header "x-api-key: $API_KEY"

Devuelve entradas con status, reason, verifiedBy y createdAt — el campo reason explica los rechazos para que puedas guiar al usuario a volver a cargar el documento.

Listar los Documentos de una Persona

Endpoint: GET /organizations/{tenant}/people/{personId}/documents
Autenticación: Nivel de tenant

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID/documents \
  --header "x-api-key: $API_KEY"

Estados de Verificación

Notificaciones por Webhook

Regístrate al webhook DocumentUpdatedEvents para recibir notificaciones cuando el estado de verificación de un documento cambie — un evento al cargar (PENDING) y otro cuando la verificación finaliza (VERIFIED/REJECTED). Ver Webhooks para la referencia del payload.

Mejores Prácticas

• Carga imágenes de alta calidad — las imágenes borrosas o recortadas serán rechazadas.
• Envía idNumber y expirationDate cuando los tengas — enriquecen el registro de cumplimiento y aceleran la revisión.
• Verifica el nivel de cumplimiento después de la verificación — una vez que un documento esté VERIFIED, llama a GET /participants/{id}/complianceLevels para ver si el remitente subió de nivel.
• Maneja los rechazos con cuidado — muestra el reason del rechazo y solicita al usuario que vuelva a cargar el documento.
• Usa webhooks en lugar de polling — regístrate a DocumentUpdatedEvents para recibir notificaciones de inmediato.

Datos de Prueba

Para pruebas en sandbox, ver Datos de Prueba y Pruebas en Sandbox — ciertas combinaciones de nombre/dirección activan comportamientos de cumplimiento específicos (aprobación, retención, rechazo).