Conciliaciones

Una conciliación es el proceso de emparejar los movimientos de un extracto bancario con los apuntes del libro mayor. El objetivo es verificar que cada euro que entra o sale del banco tiene su contrapartida contable, y que ambos registros están de acuerdo en importe, fecha y referencia.

Celestín ejecuta ese proceso de forma automática mediante una cascada de seis niveles. Cada nivel intenta casar los registros que el anterior no pudo resolver, de lo más determinístico a lo más inteligente.

La cascada de matching

L1 — Exacto (nivel 1)

Condición: la referencia del movimiento bancario coincide exactamente con la referencia del apunte contable y el valor absoluto del importe es idéntico al céntimo (toCentsInt).

Este nivel tiene precisión del 100 %. Si dos registros pasan L1, el match es correcto. Es el nivel que cubre la mayoría de los movimientos en empresas con buenas prácticas de referenciación.

L1b — Referencia parcial (nivel 11)

Condición: una referencia contiene a la otra (≥ 4 caracteres) y el importe coincide exactamente.

SEPA trunca las referencias a 35 caracteres. Un banco puede recibir FACT-2026-0312-ACME-BARCELO mientras el libro mayor tiene FACT-2026-0312-ACME-BARCELONA-TECH. L1b detecta esa situación y las empareja.

L2 — Difuso (nivel 2)

Condición: el importe está dentro de ±0,05 € y la fecha está dentro de ±3 días (±15 días para cuentas PGC de impuestos y Seguridad Social: 473, 476, 477, 642).

La confianza es graduada entre 0,70 y 0,95 dependiendo de qué tan cerca están importe y fecha. L2 captura comisiones bancarias de liquidación, diferencias de redondeo y retrasos en el procesado de transferencias.

L4 — Agregado N:1 (nivel 4)

Condición: la suma de N apuntes contables (máximo 5) coincide con el importe de 1 movimiento bancario, filtrados por proximidad de fecha.

Útil cuando la empresa contabiliza una nómina total como un único asiento pero el banco la recibe como varios pagos individuales, o viceversa cuando se agrupan pagos a proveedor.

L5 — Memoria (nivel 5)

Celestín aprende de las conciliaciones pasadas. Cuando confirmas un match de nivel L1b, L2 o L3, el sistema guarda el patrón (descripción bancaria → descripción contable) y lo aplica automáticamente en futuras conciliaciones del mismo tenant.

La memoria es estrictamente por tenant y no se comparte entre organizaciones.

L3 — LLM (nivel 3)

Los registros que no han podido casarse por ningún método determinístico se envían a un modelo de lenguaje para matching semántico. El LLM analiza las descripciones en lenguaje natural y determina si corresponden a la misma operación.

Ejemplos típicos: "AMZN MARKETPLACE" ↔ "Material de oficina Amazon", "STRIPE PAYOUT" ↔ "Ingreso plataforma e-commerce".

Si la anonimización está activa, el LLM recibe tokens en lugar de los datos reales. El matching semántico funciona igual porque el LLM evalúa la estructura del texto, no los valores sensibles.

Idempotencia y reintentos

Incluye el header Idempotency-Key con un UUID v4 único por solicitud. Si la red falla y reenvías la misma petición con la misma clave, Celestín devuelve el resultado original en lugar de ejecutar una segunda conciliación.

POST /v1/reconciliations
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
Authorization: Bearer sk_live_...

La clave de idempotencia es válida durante 24 horas.

Forma de la respuesta

{
  "id": "rec_01HXYZ123ABC",
  "status": "completed",
  "tenant_id": "mi-empresa-sl",
  "created_at": "2026-03-15T09:12:34Z",
  "expires_at": "2026-03-16T09:12:34Z",
  "summary": {
    "bank_count": 49,
    "ledger_count": 52,
    "matched_count": 46,
    "exception_count": 3,
    "match_rate": 0.939,
    "level_distribution": {
      "1": 43,
      "11": 0,
      "2": 3,
      "4": 0,
      "5": 0,
      "3": 0
    }
  },
  "matches": [ ... ],
  "exceptions": [ ... ]
}

Campos destacados:

Campo	Tipo	Descripción
id	string	Identificador único de la conciliación, prefijo rec_
status	enum	pending | processing | completed | failed
expires_at	ISO 8601	TTL de 24 h; pasado este tiempo el recurso no existe
summary.match_rate	float	Fracción de movimientos bancarios con match (0.0–1.0)
matches[].level	integer	Nivel del algoritmo (1, 11, 2, 4, 5, 3)
matches[].confidence	float	Confianza del match (0.70–1.0)
exceptions[].reason	string	Por qué no tiene match
exceptions[].suggested_account	string	Cuenta PGC sugerida si aplica clasificación automática

TTL de 24 horas

Los resultados de conciliación son efímeros por diseño. Pasadas 24 horas desde created_at, el recurso se elimina y cualquier petición GET /v1/reconciliations/{id} devuelve 404 con el código de error reconciliation_expired.

Para retención a largo plazo, exporta los resultados inmediatamente tras recibirlos o suscríbete al webhook reconciliation.completed que incluye el payload completo.