Conciliación

La conciliación (o recon, por reconciliation) es el mecanismo que corre por debajo de cada pago para garantizar que lo que dice tu integración, lo que dice el ledger de Alibanca y lo que realmente pasó en el banco sean la misma verdad. Es la red de seguridad que hace que puedas confiar en el saldo que te devuelve GET /v2/balance, que convierte el estado unknown en algo que se resuelve solo, y que caza cualquier descuadre de dinero antes de que tú lo notes. En esta página te explicamos qué es, cómo funciona el cuadre continuo, qué anomalías detecta y qué ves tú como integrador.

Qué es la conciliación y por qué te protege

Imagínate que llevas dos cuadernos de cuentas: uno lo escribes tú cada vez que emites un pago, y el otro lo escribe el banco cada vez que mueve dinero de verdad. La conciliación es el proceso de poner esos dos cuadernos lado a lado, línea por línea, y confirmar que dicen exactamente lo mismo. Si en algún renglón no coinciden, algo pasó que hay que investigar: un pago que salió pero nadie registró, un débito que ocurrió dos veces, un dinero que volvió. La conciliación existe para encontrar esas diferencias y resolverlas.

En Alibanca esto no es una tarea que alguien hace a fin de mes con una hoja de cálculo. Es un proceso continuo y automático: Alibanca cuadra permanentemente el saldo real que tiene en el banco contra su propio registro interno de movimientos. La palabra clave es continuo — no esperamos a que tú reportes un problema; el sistema está mirando el cuadre todo el tiempo.

¿Por qué esto te protege a ti, que estás integrando? Porque en el negocio de mover dinero el peor error no es que un pago falle — un pago que falla es limpio, sabes que no pasó nada y lo reintentas. El peor error es el descuadre silencioso: creer que moviste dinero cuando no, o moverlo dos veces sin darte cuenta. La conciliación es la disciplina que hace que esos errores no sobrevivan escondidos. Los saca a la luz, los clasifica y los resuelve.

El ledger de doble partida: la fuente de verdad

Antes de entender el cuadre, tienes que entender contra qué se cuadra. Alibanca lleva un ledger de doble partida (double-entry ledger). Un ledger es simplemente un libro de contabilidad: una lista ordenada e inmutable de asientos, donde cada asiento describe un movimiento de dinero. "De doble partida" significa que cada movimiento se anota dos veces: una como salida de una cuenta y otra como entrada a otra cuenta. Es el mismo principio que usan los bancos desde hace siglos, y no es un capricho: garantiza que el dinero nunca aparece ni desaparece de la nada, solo se mueve de un lado a otro.

La analogía más simple: si sacas 100 de tu bolsillo izquierdo, esos 100 tienen que aparecer en tu bolsillo derecho. Si sumas los dos bolsillos, el total no cambió. En doble partida, la suma de todo lo que entró siempre es igual a la suma de todo lo que salió. Si en algún momento esa igualdad se rompe — si un lado no cuadra con el otro — es una señal inequívoca de que hubo un error, y el sistema lo sabe de inmediato.

Por eso el ledger de doble partida es la fuente de verdad de tu saldo. No es una copia aproximada de lo que crees que pasó; es el registro disciplinado y balanceado de cada centavo que se movió a nombre de tu llave. Cuando pides GET /v2/balance, no estás leyendo un contador suelto que alguien pudo tocar por error: estás leyendo el resultado de ese libro balanceado.

El cuadre continuo: saldo del banco contra ledger

Ahora junta las dos piezas. Por un lado tienes el saldo real del banco: lo que efectivamente hay en la cuenta, según los movimientos que el banco confirma. Por el otro tienes el ledger de doble partida: lo que Alibanca registró que debía pasar. La conciliación es el motor que compara esas dos cifras de forma continua y confirma que cuadran.

Cuando cuadran, no hay nada que hacer: cada débito bancario tiene su asiento dueño en el ledger, cada asiento del ledger tiene su respaldo real en el banco, y la suma es idéntica. Ese es el estado sano, y es el estado normal. Cuando no cuadran, la conciliación no ignora la diferencia ni la "arregla" borrándola: la clasifica como una anomalía concreta y la lleva a resolución. Cada tipo de descuadre tiene un nombre y un tratamiento, porque no todos significan lo mismo.

Qué detecta la conciliación

El recon no busca "errores en general": busca patrones de descuadre específicos, cada uno con su nombre, su gravedad y su remedio. Estos son los cuatro que caza.

1. Débito bancario sin payout dueño → ORPHAN (excepción P0)

Este es el más grave. Significa que el banco movió dinero de verdad — hubo un débito real — pero en el ledger no existe un pago dueño de ese débito. En criollo: salió plata y no sabemos de parte de quién ni por qué. A esto se le llama un ORPHAN (huérfano): un débito sin padre. Se marca como excepción P0, la prioridad más alta, porque es dinero real sin explicación y no puede quedarse así ni un momento. La conciliación lo aísla y lo escala de inmediato para que se investigue y se resuelva contra el movimiento real que lo originó.

2. Crédito sin fondeo → devolución

Aquí pasa lo contrario: entró dinero a la cuenta (un crédito) que no corresponde a un fondeo que hayas hecho a propósito. El caso típico y sano es una devolución: un pago que el banco receptor rechazó y devolvió los fondos. La conciliación reconoce ese crédito, lo empareja con el pago original que rebotó y lo refleja correctamente, en vez de dejarlo como un dinero misterioso que aparece de la nada.

3. Doble-débito byte-idéntico

Este es el fantasma clásico de los sistemas de pago: el banco, por un reintento mal manejado o un timeout, debita dos veces exactamente el mismo movimiento — mismo monto, mismo destino, byte por byte igual. La conciliación detecta ese doble-débito byte-idéntico comparando los movimientos reales contra los asientos del ledger, y no lo deja pasar como si fueran dos pagos legítimos. Es una de las razones por las que la idempotencia importa tanto: la clave de idempotencia determinística permite emparejar y desduplicar con certeza.

4. Payout confirmado sin débito real

El espejo del ORPHAN. Aquí el ledger dice que un payout (una dispersión, un pago saliente) quedó confirmado, pero cuando se cuadra contra el banco, no hay débito real que lo respalde. O sea: registramos que salió dinero que en verdad nunca salió. La conciliación cacha esa inconsistencia y la corrige para que el saldo no muestre una salida que no ocurrió.

Cómo la conciliación respalda al estado unknown

Aquí es donde todo se conecta. Cuando emites un pago, su estado puede ser uno de tres:

El estado unknown es un ciudadano de primera clase, no un error disfrazado. Significa: el banco no respondió a tiempo — hubo un timeout o una caída — y todavía no sabemos si el dinero se movió o no. En un sistema mal diseñado, esta es la situación que produce los doble-pagos: el integrador ve "no sé", entra en pánico, y re-emite. Si el pago original sí había salido, acaba de pagar dos veces.

La conciliación es la red que resuelve el unknown. Como el recon cuadra continuamente el saldo real contra el ledger, un pago que quedó en unknown no se queda colgando para siempre: el cuadre termina revelando la verdad. O aparece el débito real que lo respalda (y el pago se resuelve como movido), o nunca aparece (y se resuelve como no movido). Por eso la regla de oro es tan tajante:

Dicho de otro modo: el unknown no es "un problema tuyo que tienes que apurarte a arreglar". Es "un caso abierto que la conciliación tiene bajo custodia". Tú lo consultas por GET /v2/payments/:id o esperas el webhook; el recon lo cierra.

Qué ves tú como integrador: el saldo confiable

Toda esta maquinaria — el ledger de doble partida, el cuadre continuo, las cuatro detecciones, la resolución del unknown — converge en una sola cosa práctica para ti: el saldo que puedes creer. Cuando consultas GET /v2/balance, la cifra que recibes no es un contador ingenuo que suma pagos "confirmados por optimismo". Es el resultado del ledger balanceado y conciliado contra la realidad del banco. Refleja el dinero que de verdad está disponible, con los descuadres ya cazados y las devoluciones ya reflejadas.

Devuelve el saldo disponible de tu cuenta, en unidades menores (céntimos) como string, por moneda. No lleva cuerpo. Como toda ruta autenticada, va firmada: acompáñala de tu x-api-key y tu x-signature (firma RSA-SHA256 sobre el envelope canónico). Antes de firmar nada por primera vez, recuerda que puedes llamar el público GET /v2/version para confirmar conexión.

# Sandbox — proveedor simulado, no mueve dinero real
curl https://alibanca-api-production.up.railway.app/v2/balance \
  -H "x-api-key: sk_test_tu_llave" \
  -H "x-signature: BASE64_FIRMA_RSA_SHA256"

La respuesta llega en el sobre estándar de éxito de Alibanca — status, traceId (útil para soporte y para rastrear una petición en los logs) y payload con los datos que pediste:

{
  "status": "success",
  "traceId": "trc_9f2a1c7b4e",
  "payload": {
    "currency": "VES",
    "availableMinor": "48250000"  // 482.500,00 VES en céntimos, como string
  }
}

Fíjate en tres detalles que no son casualidad. Primero, el monto viene como string en unidades menores ("48250000" = 482.500,00 VES): así lo lees y lo operas sin que un float te introduzca un error de centavo. Segundo, la moneda es "VES" — hoy la moneda soportada, con otras próximamente. Tercero, ese número ya pasó por la conciliación: no incluye un payout fantasma que nunca debitó ni omite una devolución que ya volvió. Es el saldo confiable.

Buenas prácticas alrededor de la conciliación

La conciliación te cubre las espaldas, pero hay hábitos de integración que la ayudan a hacer su trabajo — y que te evitan crearle un descuadre tú mismo. Estos son los que más importan.

Usa idempotency-keys determinísticas. La clave de idempotencia (header idempotency-key) es un string único por operación lógica. Reintentar con la misma clave devuelve el mismo resultado, no un pago nuevo. Esto es la base del reintento seguro y, además, le da al recon un ancla certera para emparejar y desduplicar movimientos. Si generas la clave a partir de datos estables de tu operación (no de un random nuevo en cada intento), un doble-débito byte-idéntico se vuelve imposible de crear por accidente.

Trata el saldo como una lectura, no como tu contabilidad. GET /v2/balance te da el saldo conciliado; no intentes reconstruirlo tú sumando pagos por tu cuenta y "corrigiendo" cuando no cuadra. Tu suma local no ve las devoluciones ni las resoluciones de unknown en tiempo real; el saldo del API sí. La fuente de verdad es el ledger, no tu réplica.

Deja que el unknown se resuelva solo. No pongas lógica que "fuerce" un desenlace: ni re-emitas, ni marques el pago como fallido por tu cuenta, ni ajustes tu contabilidad a mano. Consulta el estado por GET /v2/payments/:id o escucha el webhook (que llega firmado, verificable con la llave pública del JWKS en GET /v2/webhook/keys) y espera a que la conciliación cierre el caso.

Guarda el traceId. Cada respuesta trae un traceId. Regístralo junto a tu operación. Si alguna vez necesitas que soporte investigue un pago, ese identificador es el que ata tu registro con nuestros logs y con el asiento del ledger.

Errores comunes que la conciliación te ayuda a evitar

Re-emitir sobre un unknown. Es el error número uno y el más caro. Ves "no sé", asumes lo peor y creas un pago nuevo. Si el original sí se movió, pagaste doble. La conciliación existe precisamente para que no tengas que adivinar: el cuadre resuelve el unknown. No lo reintentes.

Confundir unknown con failed. Son opuestos en lo que autorizan. failed garantiza que no hubo débito — reintenta con clave nueva y tranquilo. unknown no garantiza nada todavía — no reintentes. Tratarlos igual es lo que rompe la seguridad del reintento.

Reutilizar una idempotency-key para operaciones distintas. Si dos operaciones lógicas diferentes comparten clave, el segundo pago te devolverá el resultado del primero — no lo que querías. La clave es por operación lógica: única para cada pago que de verdad quieres que sea distinto, estable para los reintentos del mismo.

Tratar un crédito inesperado como dinero libre. Si ves entrar un crédito, no asumas que es un fondeo tuyo para gastar. Puede ser una devolución de un pago que rebotó. La conciliación ya lo empareja y lo refleja correctamente en el saldo; confía en GET /v2/balance, no en tu interpretación del movimiento suelto.