Validación documental: API, webhooks y ERP

La validación documental operando como un silo aislado genera hasta un 23% de errores adicionales en los expedientes, según el análisis interno de 45.000 expedientes procesados por CheckFile en 2025. Cuando un operador sube manualmente archivos a una herramienta independiente, copia resultados en un CRM y luego actualiza un ERP, cada paso introduce retrasos, riesgo de error y pistas de auditoría rotas.

La integración API reduce el tiempo de verificación por expediente de 30-45 minutos a menos de 90 segundos, eliminando la intervención manual en el 82% de los casos según datos de clientes del sector financiero. Este artículo detalla tres patrones de integración que conectan CheckFile directamente a su sistema de información --ya sea Salesforce, SAP, un CRM propio o un motor de flujos de trabajo interno. Si busca primero la referencia de endpoints, consulte la guía de API.

Tres patrones de integración

Los tres patrones cubren el 95% de los casos de uso empresariales para validación documental automatizada.

El Reglamento eIDAS 2 (Reglamento UE 2024/1183) exige pistas de auditoría trazables para transacciones documentales electrónicas, lo que hace que la integración API sea un requisito de cumplimiento, no solo una opción de eficiencia.

Patrón 1 -- Carga por lotes

La carga por lotes es el punto de entrada más sencillo para la integración. Un único endpoint recibe múltiples documentos y devuelve resultados consolidados.

# Subir un lote de 3 documentos
curl -X POST https://api.checkfile.ai/api/v1/files/batch \
  -H "X-API-Key: ck_live_su_clave" \
  -F "files[]=@factura_001.pdf" \
  -F "files[]=@nota_simple.pdf" \
  -F "files[]=@datos_bancarios.pdf" \
  -F "dossier_id=EXP-2026-0042" \
  -F "callback_url=https://su-app.com/webhooks/checkfile"

Patrón 2 -- API en tiempo real

La API en tiempo real es el patrón estándar para flujos de onboarding de clientes. El operador permanece en su herramienta principal mientras la validación ocurre en segundo plano.

# Subir un documento individual
curl -X POST https://api.checkfile.ai/api/v1/files \
  -H "X-API-Key: ck_live_su_clave" \
  -H "Idempotency-Key: upload-exp042-nota-simple" \
  -F "file=@nota_simple.pdf" \
  -F "document_type=company_registration" \
  -F "rules=freshness_90d,company_number_match"

Patrón 3 -- Webhooks dirigidos por eventos

Los webhooks invierten el flujo: en lugar de consultar la API, CheckFile notifica a su sistema tan pronto como el procesamiento se completa. Este patrón es el más eficiente para pipelines de alto volumen y la base de cualquier integración ERP de producción.

Payload del webhook: documento validado

{
  "event": "file.validated",
  "timestamp": "2026-02-21T14:22:18Z",
  "data": {
    "file_id": "fil_8b2c4d1e",
    "dossier_id": "EXP-2026-0042",
    "document_type": "company_registration",
    "status": "validated",
    "confidence_score": 0.97,
    "extracted_fields": {
      "company_name": "Industrias ACME S.L.",
      "company_number": "B12345678",
      "incorporation_date": "2019-03-15",
      "registered_address": "C/ Gran Vía 42, 28013 Madrid",
      "director": "María García López",
      "document_date": "2026-01-28"
    }
  }
}

Gestión del webhook en Python

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_su_secreto_de_firma"

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

@app.route("/webhooks/checkfile", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-CheckFile-Signature", "")
    if not verify_signature(request.data, signature):
        abort(401)

    event = request.json
    event_type = event["event"]
    data = event["data"]

    if event_type == "file.validated":
        update_crm_document_status(
            dossier_id=data["dossier_id"],
            document_type=data["document_type"],
            status="validated",
            extracted_fields=data["extracted_fields"]
        )
    elif event_type == "file.rejected":
        trigger_operator_alert(
            dossier_id=data["dossier_id"],
            reasons=data["rejection_reasons"]
        )

    return {"received": True}, 200

Patrones de integración ERP por plataforma

Las integraciones con ERP empresariales siguen dos modelos según la plataforma de destino. La elección del patrón correcto determina el tiempo de desarrollo y la solidez de la integración a largo plazo.

La Directiva NIS2 (Directiva UE 2022/2555), transpuesta en España a partir de enero 2026, exige que las integraciones entre sistemas críticos incluyan autenticación mutua y registro de auditoría, reforzando la obligatoriedad de las integraciones estructuradas sobre el intercambio manual de documentos.

Salesforce

La integración más común utiliza un Apex Trigger o Flow activado por el webhook de CheckFile. La arquitectura típica:

1. Middleware ligero (AWS Lambda o Cloud Function) recibe el webhook de CheckFile.
2. El middleware llama a la API REST de Salesforce para actualizar el objeto correspondiente.
3. Un Salesforce Flow reacciona a la actualización y desencadena la lógica de negocio posterior.

SAP

Para SAP S/4HANA o SAP Business One, dos enfoques coexisten:

Vía SAP Integration Suite. Un iFlow recibe el webhook, transforma el payload e inyecta los datos en SAP.

Vía middleware genérico. Un conector Python o Node.js recibe el webhook y llama a la API OData de SAP directamente.

Gestión de errores y estrategias de reintento

CheckFile reintenta automáticamente los webhooks en caso de fallo. El calendario de reintentos sigue un backoff exponencial que garantiza la entrega sin saturar el endpoint receptor:

Idempotencia

Su endpoint de webhook debe ser idempotente. Utilice el campo file_id como clave de idempotencia para evitar procesamiento duplicado. Los 5 reintentos pueden generar hasta 6 entregas del mismo evento: su lógica de negocio debe manejar este escenario sin efectos secundarios.

Ruta de migración: de la carga manual al pipeline completamente automatizado

La migración se ejecuta en cuatro etapas incrementales, cada una con valor operativo independiente.

Etapa 1 -- Interfaz web. Use el panel de CheckFile para validar sus primeros documentos manualmente.

Etapa 2 -- API en tiempo real. Integre la API de carga en su aplicación. Los operadores ya no abandonan su herramienta principal.

Etapa 3 -- Webhooks. Active los webhooks para recibir resultados automáticamente. Su CRM/ERP se actualiza sin intervención humana.

Etapa 4 -- Pipeline completamente automatizado. Los documentos se suben automáticamente al recibirlos. Los webhooks alimentan el ERP. Los operadores solo gestionan excepciones, que representan el 15-20% de los expedientes en flujos maduros.

Para organizaciones bajo obligaciones de la Ley 10/2010 de prevención del blanqueo de capitales y supervisión del SEPBLAC, la etapa 4 con pistas de auditoría automáticas es el único enfoque que satisface los requisitos de trazabilidad sin coste operativo creciente.

La plataforma de verificación documental de CheckFile se integra con Salesforce, SAP y ERPs propios mediante los patrones descritos. Los precios incluyen acceso a la API en todos los planes, con un entorno sandbox para probar su integración antes de pasar a producción. Consulte también nuestra guía sobre validación cruzada de documentos para entender qué capas de verificación activan estos pipelines.

FAQ

¿Qué diferencia hay entre la API en tiempo real y los webhooks?

La API en tiempo real es un modelo pull: su aplicación envía un documento y espera la respuesta en la misma conexión HTTP (2-15 segundos). Los webhooks son un modelo push: CheckFile notifica a su servidor cuando el procesamiento termina, sin que su aplicación deba mantener una conexión abierta. Para alto volumen, los webhooks son significativamente más eficientes.

¿Las integraciones API cumplen con el RGPD?

Sí. Los datos procesados por la API de CheckFile se almacenan en servidores dentro de la UE, bajo los términos del Acuerdo de Procesamiento de Datos (DPA) incluido en el contrato. Las claves API se gestionan con rotación programable y los logs de acceso cumplen con los plazos de conservación del RGPD.

¿Se puede probar la integración sin datos reales?

Sí. CheckFile proporciona un entorno sandbox con datos de prueba y webhooks simulables. El sandbox replica el comportamiento de producción, incluyendo los tiempos de respuesta y los formatos de payload.

¿Cuántos documentos por minuto puede procesar la API?

Los límites de velocidad varían según el plan. El plan Business permite hasta 300 documentos por minuto. Para volúmenes superiores, la carga por lotes con callback URL es el patrón recomendado.