API de verificación documental: guía de integración

Una API de verificación documental es una interfaz programática que permite a los desarrolladores enviar documentos de identidad, facturas, certificados o justificantes de domicilio y recibir resultados de verificación estructurados — comprobaciones de autenticidad, extracción de datos, señales de fraude — sin construir los modelos de IA subyacentes. La API de CheckFile procesa un documento en 4,2 segundos de media, alcanza un 98,7 % de precisión OCR en 24 idiomas y gestiona más de 3 200 tipos de documentos en 32 jurisdicciones.

El Reglamento de IA de la UE (Reglamento (UE) 2024/1689, art. 6 y anexo III) clasifica los sistemas de IA utilizados para la verificación de documentos de identidad en servicios financieros como de alto riesgo, exigiendo a los proveedores mantener documentación técnica, un sistema de gestión de riesgos y capacidades de supervisión humana. Cualquier API que integres debe cumplir estas obligaciones, o heredas la brecha de cumplimiento.

Esta guía cubre autenticación, endpoints principales, configuración de webhooks, gestión de errores, opciones de SDK y precios. Está dirigida a desarrolladores backend, equipos DevOps y responsables técnicos que evalúan APIs de verificación documental para integración en producción.

Este artículo tiene fines exclusivamente informativos y no constituye asesoramiento legal, financiero ni regulatorio.

Autenticación y seguridad

La API de CheckFile utiliza OAuth 2.0 client credentials para autenticación máquina a máquina, siguiendo el RFC 6749, Sección 4.4. Se intercambia client_id y client_secret por un token bearer de duración limitada (60 minutos de validez), que se incluye en el encabezado Authorization de cada solicitud posterior.

Todo el tráfico de la API está cifrado con TLS 1.3. Los documentos se cifran en reposo con AES-256, y los datos personales se eliminan automáticamente de los registros, cumpliendo con el artículo 32 del RGPD sobre medidas técnicas apropiadas (RGPD, art. 32).

 # Obtener token de acceso
curl -X POST https://api.checkfile.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=TU_ID&client_secret=TU_SECRET"

 # Respuesta
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Funciones de seguridad clave:

• Lista blanca de IPs — restringir el acceso a la API a IPs de servidor conocidas
• Limitación de tasa — configurable por plan (ver sección de precios)
• Firmas de webhooks — verificación HMAC-SHA256 en cada callback
• Registro de auditoría — cada llamada a la API se registra con marca de tiempo, ID de cliente, tipo de documento y resultado

Scopes y permisos

Endpoints principales

La API sigue convenciones RESTful con payloads JSON. URL base: https://api.checkfile.ai/v1.

Envío de documentos

POST /v1/documents/verify
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # Campos:
 # file (requerido) — imagen o PDF del documento (máx. 20 MB)
 # document_type (opcional) — "passport", "id_card", "invoice", "proof_of_address"
 # country (opcional) — código ISO 3166-1 alfa-2
 # webhook_url (opcional) — URL de callback para resultados asíncronos
 # reference_id (opcional) — tu referencia interna para correlación

Respuesta (HTTP 202 Accepted):

{
  "document_id": "doc_8f3a2b1c",
  "status": "processing",
  "estimated_completion_seconds": 4,
  "created_at": "2026-03-19T10:15:00Z"
}

Cuando se omite document_type, la API usa su motor de clasificación IA — que alcanza 96,1 % de precisión en nuestro benchmark de más de 3 200 tipos de documentos — para detectar el tipo automáticamente.

Obtención de resultados

GET /v1/documents/{document_id}
Authorization: Bearer {token}

Respuesta (HTTP 200):

{
  "document_id": "doc_8f3a2b1c",
  "status": "completed",
  "document_type": "dni",
  "country": "ES",
  "verification": {
    "authentic": true,
    "confidence": 0.97,
    "fraud_signals": [],
    "checks": {
      "mrz_valid": true,
      "photo_tamper": false,
      "expiry_valid": true,
      "data_consistency": true
    }
  },
  "extracted_data": {
    "full_name": "María García López",
    "date_of_birth": "1990-05-12",
    "document_number": "12345678Z",
    "expiry_date": "2031-05-11",
    "nationality": "ESP"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-19T10:15:00Z",
  "completed_at": "2026-03-19T10:15:03.840Z"
}

El objeto extracted_data alcanza un 94,3 % de precisión en extracción de campos en nuestro benchmark interno, cubriendo campos estructurados de todos los tipos de documentos soportados.

Verificación por lotes

Para integraciones de alto volumen, el endpoint batch acepta hasta 50 documentos por solicitud:

POST /v1/documents/verify/batch
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # files[] — array de archivos de documentos
 # options — objeto JSON con configuración compartida

Las solicitudes batch devuelven un batch_id y entregan resultados por webhook a medida que cada documento se completa.

Configuración de webhooks

Las arquitecturas basadas en eventos evitan la sobrecarga del polling. Registra un endpoint webhook para recibir notificaciones en tiempo real cuando las verificaciones finalicen.

POST /v1/webhooks
Authorization: Bearer {token}
Content-Type: application/json

{
  "url": "https://tu-app.com/webhooks/checkfile",
  "events": ["document.completed", "document.failed", "document.review_required"],
  "secret": "whsec_tu_clave_secreta"
}

Cada entrega de webhook incluye un encabezado X-CheckFile-Signature con un hash HMAC-SHA256 del payload. Verifícalo antes de procesar:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Política de reintentos del webhook: 3 intentos con backoff exponencial (5s, 30s, 300s). Tras 3 fallos, el webhook se desactiva y tu equipo recibe una alerta por correo.

SDK y opciones de integración

La API REST funciona desde cualquier lenguaje, pero los SDKs oficiales reducen el tiempo de integración de días a horas.

SDKs disponibles

Ejemplo de integración en Python

from checkfile import CheckFileClient

client = CheckFileClient(
    client_id="TU_CLIENT_ID",
    client_secret="TU_CLIENT_SECRET"
)

 # Verificación síncrona
result = client.documents.verify(
    file=open("dni.pdf", "rb"),
    document_type="id_card",
    country="ES"
)

print(f"Auténtico: {result.verification.authentic}")
print(f"Nombre: {result.extracted_data.full_name}")
print(f"Tiempo de procesamiento: {result.processing_time_ms}ms")

Ejemplo de integración en Node.js

import { CheckFileClient } from '@checkfile/sdk';
import { readFileSync } from 'fs';

const client = new CheckFileClient({
  clientId: process.env.CHECKFILE_CLIENT_ID,
  clientSecret: process.env.CHECKFILE_CLIENT_SECRET,
});

const result = await client.documents.verify({
  file: readFileSync('dni.pdf'),
  documentType: 'id_card',
  country: 'ES',
});

console.log(`Auténtico: ${result.verification.authentic}`);
console.log(`Confianza: ${result.verification.confidence}`);

Los SDKs gestionan la renovación de tokens, los reintentos con backoff exponencial y la verificación de firmas de webhook automáticamente. Nuestro análisis muestra que las integraciones basadas en SDK reducen el tiempo medio de puesta en producción de 8 días (REST directo) a 2 días.

Gestión de errores y límites de tasa

La API utiliza códigos HTTP estándar con cuerpos de error estructurados:

{
  "error": {
    "code": "DOCUMENT_UNREADABLE",
    "message": "El archivo cargado no pudo analizarse. Asegúrate de que DPI >= 300.",
    "details": { "min_dpi": 300, "detected_dpi": 72 },
    "request_id": "req_9f2c4d1e"
  }
}

Códigos de error comunes

Límites de tasa por plan

Los encabezados de límite de tasa (X-RateLimit-Remaining, X-RateLimit-Reset) se incluyen en cada respuesta. Construye tu lógica de reintentos basándote en estos encabezados en lugar de codificar retrasos fijos.

Cumplimiento normativo y tratamiento de datos

La verificación documental involucra datos personales en múltiples jurisdicciones. La API está diseñada con el cumplimiento como requisito de primer orden.

Desde marzo de 2026, el RGPD (Reglamento (UE) 2016/679, art. 28) exige a los responsables del tratamiento utilizar únicamente encargados que ofrezcan garantías suficientes de medidas técnicas y organizativas apropiadas. CheckFile actúa como encargado del tratamiento, con un contrato de encargo de tratamiento (DPA) incluido en todos los planes Business y Enterprise.

Para las entidades supervisadas por la CNMV (Comisión Nacional del Mercado de Valores) y sujetas a la Ley 10/2010 de prevención del blanqueo de capitales, la API proporciona:

• Retención: los documentos se eliminan tras el procesamiento salvo solicitud explícita de almacenamiento (configurable de 0 a 365 días)
• Residencia de datos: procesamiento en la UE por defecto; regiones US y APAC disponibles en planes Enterprise
• Pista de auditoría: cada llamada a la API genera un registro inmutable con hash del documento, marca de tiempo, resultado e ID del cliente
• Certificación SOC 2 Type II que cubre la infraestructura de la API
• Cumplimiento PCI DSS para el tratamiento de documentos financieros

Para integraciones sujetas a las directrices del Sepblac sobre identificación formal, CheckFile proporciona la documentación de garantías de terceros requerida, resultados de pruebas de continuidad de negocio y condiciones de estrategia de salida.

Estructura de precios

CheckFile utiliza un modelo de precio por documento con descuentos por volumen. Todos los planes incluyen acceso completo a la API, webhooks y registros de auditoría.

Consulta la página de precios para detalles sobre tramos de volumen, descuentos anuales y condiciones SLA Enterprise.

Nuestro análisis de plataforma muestra que las organizaciones que pasan de la verificación manual de documentos a la verificación por API reducen el coste por expediente un 67 % y el tiempo de procesamiento un 83 %. El período medio de amortización para clientes Business es inferior a 3 meses al procesar más de 500 documentos mensuales.

Patrones de arquitectura de integración

Patrón 1: síncrono (simple)

Para integraciones de bajo volumen (< 60 solicitudes/min), enviar y consultar:

Cliente → POST /v1/documents/verify → 202 Accepted
Cliente → GET /v1/documents/{id} (polling cada 2s) → 200 con resultados

Adecuado para flujos de onboarding donde el usuario espera la verificación.

Patrón 2: asíncrono con webhooks (recomendado)

Para cargas de trabajo en producción, enviar y recibir resultados por webhook:

Cliente → POST /v1/documents/verify (con webhook_url) → 202 Accepted
CheckFile → POST webhook_url (payload firmado) → Tu handler procesa el resultado

Desacopla envío de procesamiento. Escala linealmente con el volumen.

Patrón 3: pipeline por lotes

Para procesamiento back-office (revisiones KYC nocturnas, comprobaciones de cumplimiento masivas):

Cliente → POST /v1/documents/verify/batch (hasta 50 archivos) → batch_id
CheckFile → POST webhook_url por documento a medida que se completa
CheckFile → POST webhook_url con resumen batch.completed

Nuestra plataforma procesa más de 180.000 documentos al mes con estos patrones. El patrón asíncrono con webhooks cubre el 94 % de las integraciones en producción.

Primeros pasos

La integración sigue cuatro pasos:

1. Crear una cuenta en checkfile.ai y generar credenciales API desde el panel
2. Probar en sandbox — el entorno sandbox replica producción con documentos sintéticos (sin facturación)
3. Integrar usando el SDK o llamadas REST directas, comenzando con el patrón síncrono
4. Pasar a producción — cambiar a credenciales de producción y configurar webhooks

La documentación de la API incluye un playground interactivo para probar endpoints, y la página de precios detalla las opciones de plan según tu volumen previsto.

Para equipos que construyen flujos de verificación documental automatizados, la API se integra directamente con los patrones descritos en nuestra guía de configuración de workflows. Si estás evaluando soluciones de verificación de forma más amplia, nuestra guía de automatización de la verificación cubre todo el panorama de enfoques de verificación documental.

Preguntas frecuentes

Que tipos de documentos admite la API

La API de CheckFile admite más de 3.200 tipos de documentos en 32 jurisdicciones: pasaportes, DNI, permisos de conducir, facturas, extractos bancarios, justificantes de domicilio, declaraciones de la renta, nóminas y certificados de inscripción de empresas. El motor de clasificación IA identifica automáticamente el tipo de documento con un 96,1 % de precisión cuando se omite el parámetro document_type.

Cuanto tiempo tarda la verificación

El tiempo medio de procesamiento es de 4,2 segundos por documento. La latencia P95 es inferior a 12 segundos para tipos de documentos estándar. Los envíos por lotes procesan documentos en paralelo: un lote de 50 documentos se completa normalmente en 30 a 60 segundos, según la complejidad del documento.

Es la API conforme al RGPD

Sí. CheckFile actúa como encargado del tratamiento según el artículo 28 del RGPD con DPA firmado, infraestructura de procesamiento en la UE, retención de datos configurable (0 a 365 días) y eliminación automática de datos personales de los registros. Las certificaciones SOC 2 Type II e ISO 27001 cubren la infraestructura de la API.

Puedo probar la API antes de contratar un plan de pago

El plan Starter incluye 100 verificaciones gratuitas al mes, y el entorno sandbox permite pruebas ilimitadas con documentos sintéticos sin coste. No se requiere tarjeta de crédito para empezar.

Que ocurre si la API no puede verificar un documento

Los documentos que caen por debajo del umbral de confianza se marcan con estado review_required y se dirigen a tu cola de revisión humana por webhook. La respuesta incluye el resultado parcial con la puntuación de confianza, los datos extraídos y las señales de fraude específicas que activaron la marca. Esto garantiza que ningún documento quede sin procesar.