Casos por API

Un caso es el expediente de un solicitante, persona o empresa. Tu sistema lo crea, aporta los documentos y lo envía; FINORA KYC ejecuta el screening y el perfil de riesgo, y un oficial de cumplimiento de tu empresa decide. Si prefieres no construir pantallas para el solicitante, usa la verificación alojada.

1. Crear el caso

curl -s -X POST "$KYC_BASE/v1/casos" \
  -H "X-API-Key: $KYC_API_KEY" \
  -H "Idempotency-Key: alta-cliente-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "flujo": "persona-ve-basica",
    "nivel": "ESTANDAR",
    "referenciaExterna": "cliente-1001",
    "solicitante": {
      "tipo": "PERSONA",
      "nombres": "Ana María",
      "apellidos": "Pérez Rojas",
      "fechaNacimiento": "1990-05-14",
      "nacionalidad": "VE",
      "documento": { "tipo": "CEDULA_VE", "numero": "V12345678" },
      "correo": "ana.perez@correo.example",
      "telefono": "+584141234567"
    },
    "metadata": { "producto": "cuenta-digital" }
  }'

Campo	Notas
flujo	Plantilla de tu cuenta que define qué se pide, por ejemplo persona-ve-basica.
nivel	SIMPLIFICADA, ESTANDAR o REFORZADA.
solicitante.tipo	PERSONA o EMPRESA (con razonSocial y rif).
referenciaExterna	Id del cliente en tu sistema (hasta 80 caracteres). Vuelve en los webhooks.
canal	API por defecto.
metadata	Hasta 20 pares de texto para tu uso.

Respuesta 201 con la cabecera Location:

{
  "id": "cas_01J9Z3K8Q2W7XPT4M6N5R0B1CD",
  "estado": "ESPERANDO_SOLICITANTE",
  "flujo": "persona-ve-basica",
  "nivel": "ESTANDAR",
  "referenciaExterna": "cliente-1001",
  "solicitante": {
    "id": "sol_01J9Z3K8Q2W7XPT4M6N5R0B1CE",
    "tipo": "PERSONA",
    "nombreCompleto": "Ana María Pérez Rojas",
    "documentoUltimos4": "5678"
  },
  "verificaciones": [],
  "creadoEn": "2026-10-15T13:00:00Z",
  "actualizadoEn": "2026-10-15T13:00:00Z"
}

Las respuestas nunca traen imágenes, y del documento solo muestran los últimos 4 caracteres.

2. Subir los documentos

Multipart con tipo, cara y el archivo:

curl -s -X POST "$KYC_BASE/v1/casos/$CASO/documentos" \
  -H "X-API-Key: $KYC_API_KEY" -H "Idempotency-Key: doc-1001-cedula-anverso" \
  -F tipo=CEDULA_VE -F cara=ANVERSO -F archivo=@cedula-anverso.jpg

{ "id": "doc_01J9Z3K8Q2W7XPT4M6N5R0B1CF", "tipo": "CEDULA_VE", "estado": "RECIBIDO", "sha256": "9f86d081884c7d65…" }

• tipo: CEDULA_VE, PASAPORTE, RIF, LICENCIA, REGISTRO_MERCANTIL, ESTADO_CUENTA u OTRO.
• cara: ANVERSO, REVERSO o UNICA (por defecto).
• Máximo 10 MB. El tipo real se verifica por su contenido y se rechazan los PDF con JavaScript.
• El archivo se cifra antes de guardarse. sha256 es el hash del archivo original, para que concilies.
• La lectura (MRZ y OCR) es asíncrona: el resultado llega con el evento caso.documento.procesado.
• Solo se aceptan documentos mientras el caso está en ABIERTO o ESPERANDO_SOLICITANTE.

3. Subir la selfie

curl -s -X POST "$KYC_BASE/v1/casos/$CASO/selfie" \
  -H "X-API-Key: $KYC_API_KEY" -H "Idempotency-Key: selfie-1001" \
  -F selfie=@selfie.jpg

La selfie se guarda cifrada y queda para la revisión del oficial.

Próximamente

La comparación facial automática y la prueba de vida con un proveedor certificado, y el campo tokenSdk del SDK móvil. En sandbox puedes simular su resultado con la cabecera X-Kyc-Sandbox-Resultado.

4. Enviar el caso

Cuando el expediente está completo, envíalo. Se ejecutan el screening y el perfil de riesgo, y el caso pasa a la cola del oficial.

curl -s -X POST "$KYC_BASE/v1/casos/$CASO/enviar" \
  -H "X-API-Key: $KYC_API_KEY" -H "Idempotency-Key: enviar-1001"

Responde 202 con el caso. Si su estado no admite el envío, 409 TRANSICION_INVALIDA.

5. Leer la decisión

Escucha caso.decidido en tus webhooks o consulta el caso:

curl -s "$KYC_BASE/v1/casos/$CASO" -H "X-API-Key: $KYC_API_KEY"

{
  "id": "cas_01J9Z3K8Q2W7XPT4M6N5R0B1CD",
  "estado": "APROBADO",
  "referenciaExterna": "cliente-1001",
  "verificaciones": [
    { "tipo": "DOCUMENTO", "estado": "COMPLETADA", "resultado": "PASA" },
    { "tipo": "SCREENING", "estado": "COMPLETADA", "resultado": "PASA" }
  ],
  "riesgo": { "nivel": "MEDIO", "puntaje": 42, "proximaRevision": "2027-10-15" },
  "decision": { "estado": "APROBADO", "decididoPor": "HUMANO", "decididoEn": "2026-10-15T15:12:00Z" }
}

riesgo aparece cuando ya corrió el screening del caso.

Estados del caso

Estado	Significa	Evento
ABIERTO, ESPERANDO_SOLICITANTE	Se esperan documentos o datos.	caso.creado
EN_PROCESO	Enviado: corren screening, verificaciones y riesgo.
EN_REVISION	En la cola del oficial.	caso.en_revision
ESCALADO	Escalado a un supervisor (cuatro ojos).
APROBADO, RECHAZADO	Decisión de una persona de tu equipo. Final.	caso.decidido
EXPIRADO	El solicitante no completó a tiempo. Final.	caso.expirado
CANCELADO	Cancelado desde la consola de tu empresa antes de la decisión. Final.

APROBADO y RECHAZADO solo los alcanza una persona: ninguna regla automática aprueba ni rechaza un caso. Si el oficial pide más información, el caso vuelve a ESPERANDO_SOLICITANTE y puedes subir más documentos.