ComplianceFlow API · v1

ComplianceFlow es una plataforma de APIs de compliance que unifica en una sola interfaz SII/Verifactu, KYC, scoring de fraude y análisis documental. Esta documentación está pensada para desarrolladores y equipos de producto que quieran integrar la API en sus sistemas.

Todas las llamadas se realizan sobre HTTPS y devuelven datos en formato JSON. Se recomienda empezar en el entorno sandbox y pasar a producción cuando la integración esté validada.

Base URLs

Sandbox

https://sandbox.api.complianceflow.es/v1

Producción

https://api.complianceflow.es/v1

2. Autenticación y entornos

La autenticación se realiza mediante API keys específicas por entorno (sandbox y producción). Cada petición debe incluir una cabecera x-api-key con una clave válida.

Las claves son secretas y no deben incrustarse en aplicaciones cliente públicas (frontends web o apps móviles). Utiliza siempre tu backend como proxy cuando consumas la API desde un frontal.

Cabeceras obligatorias

Cabecera	Tipo	Obligatoria	Descripción
`x-api-key`	string	Sí	Clave de acceso al entorno correspondiente (sandbox o producción).
`Content-Type`	string	Según endpoint	`application/json` o `multipart/form-data` para subida de ficheros.

Ejemplo de llamada autenticada (cURL)

curl -X GET "https://api.complianceflow.es/v1/usage/current-month" \
  -H "x-api-key: YOUR_PROD_API_KEY"

3. Convenciones de la API

Versionado: todas las rutas llevan prefijo /v1.
Formato: entrada y salida en JSON, salvo endpoints que aceptan ficheros.
Fechas: formato ISO‑8601 (ej. 2025-12-09T13:45:00Z).
Importes: numéricos con punto decimal y sin símbolo de moneda.

Los códigos HTTP siguen la semántica estándar: 2xx para éxito, 4xx para errores del cliente y 5xx para errores internos. El cuerpo de error se documenta en la sección siguiente.

4. Errores y códigos de estado

Todas las respuestas de error siguen una estructura homogénea que facilita el tratamiento automático y la trazabilidad.

Formato de error

{
  "error": "VALIDATION_ERROR",
  "message": "El campo amount es obligatorio",
  "details": {
    "field": "amount"
  },
  "trace_id": "b7a1f79e-9c3f-4c2f-8b4a-01c1f2a9c001"
}

Campo	Tipo	Descripción
`error`	string	Código interno de error (ej. `VALIDATION_ERROR`, `AUTH_ERROR`, `RATE_LIMIT`).
`message`	string	Mensaje legible para desarrolladores (no para mostrar al usuario final).
`details`	objeto	Información adicional según el contexto (campo inválido, etc.).
`trace_id`	string	Identificador único para soporte y auditoría.

Errores habituales

Código HTTP	`error`	Cuándo ocurre	Cómo actuar
400	`VALIDATION_ERROR`	Faltan campos obligatorios o el formato es incorrecto.	Revisa el cuerpo de la petición y corrige los campos indicados en `details`.
401	`AUTH_ERROR`	API key ausente, inválida o desactivada.	Confirma que estás usando la clave correcta para el entorno adecuado.
429	`RATE_LIMIT`	Se han superado los límites de peticiones permitidos.	Aplica backoff exponencial o contrata un plan con más capacidad.
500	`INTERNAL_ERROR`	Error inesperado en el servicio.	Reintenta más tarde y, si persiste, contacta con soporte indicando el `trace_id`.

5. Endpoints SII & Verifactu

POST /sii/invoice

Envía una factura al SII. Acepta un fichero PDF o imagen y devuelve un objeto JSON listo para registrar y, en su caso, enviar a la AEAT.

POST /v1/sii/invoice Sandbox & Producción

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`invoice_pdf`	form-data	file	Sí	Fichero PDF o imagen de la factura.
`external_id`	form-data	string	No	Identificador interno de la factura en tu sistema.

Ejemplo de petición (cURL)

curl -X POST "https://api.complianceflow.es/v1/sii/invoice" \
  -H "x-api-key: YOUR_PROD_API_KEY" \
  -F "invoice_pdf=@factura.pdf" \
  -F "external_id=ERP-12345"

Ejemplo de respuesta

{
  "sii_id": "2026E001",
  "estado": "Aceptado",
  "importe_total": 1250.00,
  "iva_21": 262.50,
  "proveedor_nif": "B12345678",
  "cliente_nif": "A87654321",
  "external_id": "ERP-12345",
  "trace_id": "b7a1f79e-9c3f-4c2f-8b4a-01c1f2a9c001"
}

6. Endpoints KYC

POST /kyc/complete

Realiza un flujo KYC completo combinando documento de identidad y selfie. Devuelve un resultado de verificación y un score de riesgo.

POST /v1/kyc/complete Sandbox & Producción

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`dni_front`	form-data	file	Sí	Imagen frontal del documento.
`dni_back`	form-data	file	No	Imagen trasera del documento (si aplica).
`selfie`	form-data	file	Sí	Selfie de la persona a verificar.

Ejemplo de respuesta

{
  "status": "APPROVED",
  "risk_score": 32,
  "document_type": "DNI",
  "document_number": "00000000X",
  "full_name": "Nombre Apellido",
  "reason_codes": [],
  "trace_id": "c2f3e9a0-1d39-4b33-b822-8212e4c0e9af"
}

7. Endpoints de fraude

POST /score/risk

Calcula un score de riesgo 0‑100 para una transacción, combinando reglas PSD2 y modelos de riesgo entrenados.

POST /v1/score/risk Sandbox & Producción

Ejemplo de petición (JSON)

{
  "amount": 2500,
  "currency": "EUR",
  "ip_country": "ES",
  "velocity_24h": 5,
  "merchant_category": "crypto"
}

Ejemplo de respuesta

{
  "risk_score": 78,
  "decision": "BLOCK",
  "reason_codes": ["AMOUNT_HIGH", "MCC_HIGH_RISK"],
  "trace_id": "d781f4e0-a0b7-4b7d-bb3a-92c3b5d22b8e"
}

Por defecto se recomienda tratar como alto riesgo los valores superiores a 70 y revisar manualmente los comprendidos entre 50 y 70.

8. Endpoints de documentos

POST /extract

Extrae datos estructurados de facturas, DNIs y otros documentos soportados.

POST /v1/extract Sandbox & Producción

POST /summarize

Genera un resumen ejecutivo de contratos y expedientes, incluyendo cláusulas clave detectadas.

POST /v1/summarize Sandbox & Producción

9. Guía rápida por lenguaje

Estos ejemplos muestran cómo hacer una llamada autenticada al endpoint /score/risk desde distintos lenguajes. Son perfectos para validar conectividad con sandbox.

Node.js (axios)

import axios from "axios";

const client = axios.create({
  baseURL: "https://sandbox.api.complianceflow.es/v1",
  headers: {
    "x-api-key": process.env.COMPLIANCEFLOW_API_KEY
  }
});

async function main() {
  const response = await client.post("/score/risk", {
    amount: 2500,
    currency: "EUR",
    ip_country: "ES"
  });

  console.log(response.data);
}

main().catch(console.error);

Python (requests)

import os
import requests

BASE_URL = "https://sandbox.api.complianceflow.es/v1"
API_KEY = os.environ.get("COMPLIANCEFLOW_API_KEY")

payload = {
  "amount": 2500,
  "currency": "EUR",
  "ip_country": "ES"
}

response = requests.post(
  f"{BASE_URL}/score/risk",
  json=payload,
  headers={"x-api-key": API_KEY},
  timeout=10
)

print(response.status_code, response.json())