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 comprobantes 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, incluyendo todos los documentos oficiales mexicanos (INE, RFC, CURP, CFDIs, actas constitutivas).

Este artículo se proporciona únicamente con fines informativos y no constituye asesoramiento jurídico, financiero ni regulatorio. Las referencias normativas son exactas a la fecha de publicación. Consulte a un profesional cualificado para obtener orientación adaptada a su situación.

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. En México, la CNBV y la UIF exigen que los sistemas de verificación documental automatizada cumplan con estándares de trazabilidad y auditoría bajo el marco PLD/FT. 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 la Ley Federal de Protección de Datos Personales en Posesión de los Particulares (LFPDPPP) sobre medidas de seguridad apropiadas y con los lineamientos del INAI.

 # 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 (MX para México)
 # 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-24T10: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": "ine",
  "country": "MX",
  "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 Fernanda López García",
    "date_of_birth": "1990-05-12",
    "document_number": "LOGM900512MDFRPR01",
    "expiry_date": "2031-05-11",
    "nationality": "MEX",
    "curp": "LOGM900512MDFRPR01"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-24T10:15:00Z",
  "completed_at": "2026-03-24T10: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, incluyendo documentos mexicanos como INE, pasaporte, constancia de situación fiscal del SAT y CFDIs.

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 electrónico.

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("ine.pdf", "rb"),
    document_type="id_card",
    country="MX"
)

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('ine.pdf'),
  documentType: 'id_card',
  country: 'MX',
});

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.

En México, la LFPDPPP (Ley Federal de Protección de Datos Personales en Posesión de los Particulares) exige a los responsables del tratamiento utilizar únicamente encargados que ofrezcan garantías suficientes de medidas de seguridad apropiadas, conforme a los lineamientos del INAI. CheckFile actúa como encargado del tratamiento, con un contrato de tratamiento de datos incluido en todos los planes Business y Enterprise.

Para las entidades supervisadas por la CNBV y sujetas a la LFPIORPI y las Disposiciones de la CNBV sobre PLD/FT, 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 (con opciones de residencia en México para cumplimiento LFPDPPP)
• 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 Disposiciones de la CNBV sobre identificación de clientes y los lineamientos de la UIF, 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 costo 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

¿Qué tipos de documentos mexicanos admite la API?

La API de CheckFile admite todos los documentos oficiales mexicanos, incluyendo credencial para votar (INE), pasaporte mexicano, CURP, constancia de situación fiscal del SAT, RFC, CFDIs (facturas electrónicas), actas constitutivas, actas de nacimiento, comprobantes de domicilio (CFE, Telmex, estados de cuenta bancarios) y constancias del Registro Público de Comercio. En total, soporta más de 3,200 tipos de documentos en 32 jurisdicciones. 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.

¿Cuánto 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.

¿La API cumple con la LFPDPPP y los lineamientos del INAI?

Sí. CheckFile actúa como encargado del tratamiento conforme a la LFPDPPP con contrato de tratamiento de datos firmado, infraestructura de procesamiento segura, 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. Para instituciones financieras, los registros de auditoría cumplen con las Disposiciones de la CNBV sobre conservación de documentación PLD/FT.

¿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 costo. No se requiere tarjeta de crédito para empezar.

¿Qué 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.