Documentación API

2 · Canales de conexión soportados

FLUX es flexible con el transporte: cualquiera de estas opciones sirve. Lo importante es la estructura y la frecuencia del dato, no el medio.

Se puede empezar con archivos planos diarios por SFTP y migrar a API en una segunda fase, o ir directo a API.

3 · Seguridad

Cifrado en tránsito y en reposo en todos los canales, y firma de mensajes en los que la admiten. Cada adquirente recibe credenciales propias y un ambiente de pruebas antes de operar.

Firma de las llamadas API

Sobre API REST, cada llamada se firma con HMAC-SHA256 siguiendo la especificación Standard Webhooks. La firma es la credencial: no hay usuario ni contraseña.

webhook-id:         identificador único de esta llamada (UUID)
webhook-timestamp:  epoch en segundos
webhook-signature:  v1,<firma base64>

La firma es el HMAC-SHA256, en base64, de {webhook-id}.{webhook-timestamp}.{cuerpo}, donde cuerpo es el JSON enviado byte a byte, sin reformatear.

• El secreto no es compartido: FLUX entrega uno distinto por cada par comercio–adquirente, de modo que una credencial expuesta no permite firmar por otro comercio.
• El webhook-id da idempotencia: repetir una llamada con el mismo id no reprocesa nada. Reintentar es seguro.
• Una llamada con webhook-timestamp fuera de la ventana de tolerancia se rechaza. Hay que mantener el reloj del emisor sincronizado.
• Sobre SFTP o correo, el archivo viaja cifrado a un destino dedicado por adquirente.

4 · Alta del comercio · datos de afiliación

Cuando un comercio se incorpora a FLUX, sus datos de afiliación permiten validar identidad y cuenta de abono.

5 · Historia transaccional · últimos 12 meses

Ventas al contado y en cuotas, con montos y comportamiento de abono. Con esto FLUX calcula la línea de adelanto del comercio. Corre una sola vez, al enrolar.

6 · Liquidación diaria y su composición

El monto liquidado por comercio y qué ventas y cuotas lo componen. Es lo que permite conciliar y recuperar los adelantos contra la cuota que efectivamente se liquidó.

Las filas con ↳ son el detalle: se repiten por cada ítem que compone la liquidación del día.

7 · Ventas del día

Transacciones nuevas, con identificación de cuotas y canal. Alimenta la oferta de nuevas cuotas adelantables.

8 · Altas y bajas de comercios

Qué comercios entran o salen del programa FLUX cada día. Saberlo le permite al adquirente aplicar la redirección de la liquidación de las cuotas adelantadas hacia FLUX.

9 · Calendario proyectado de liquidaciones a recibir

Las cuotas adelantadas cuya liquidación FLUX debe recibir, con su fecha y monto, para que el adquirente las abone a la cuenta recaudadora de FLUX en lugar de a la del comercio.

GET /v1/acquirer/settlement-calendar?date=2026-05-05

{
  "generatedAt": "2026-05-04T23:10:00Z",
  "items": [
    {
      "commerce_code":       "597012345678",
      "transaction_id":      "ADQ-99887766",
      "authorization_code":  "123456",
      "installment_number":  3,
      "installments_total":  12,
      "settlement_amount":   "19400",
      "projected_at":        "2026-05-05",
      "advance_id":          "FLX-ADV-00458"
    }
  ]
}

10 · Ejemplo completo · una venta en 12 cuotas

Venta de $240.000 en 12 cuotas del comercio 597012345678, con abono neto por cuota de ~$19.400 ya descontada la comisión del adquirente. Fecha de referencia: 15 de febrero de 2026.

1. 1

   Llega la venta al día siguiente

   Proceso 2B · Recibimos

   El adquirente envía la venta con su calendario de abono proyectado: 12 cuotas de ~$19.400, con liquidación mensual desde el 5 de marzo de 2026. Se marca como venta en cuotas, candidata a adelanto.

2. 2

   El comercio arma la oferta

   Oferta al comercio

   La cuota 1 no es adelantable. El comercio elige adelantar las cuotas 3, 4 y 5. FLUX calcula la comisión sobre el monto de abono, según los días de anticipación: 79, 110 y 140 días.

3. 3

   FLUX desembolsa

   Oferta al comercio

   Tras validar el OTP, FLUX transfiere $55.637 al comercio sobre $58.200 de abono. Los valores quedan congelados: monto de abono, comisión y días de adelanto por cuota.

4. 4

   FLUX informa al adquirente

   Procesos 3A y 3B · Entregamos

   Si es la primera operación del comercio, va en el alta diaria. En el calendario proyectado se informan las tres cuotas adelantadas con fecha, monto e identificador de adelanto FLX-ADV-00458.

5. 5

   Recupero mes a mes

   Proceso 2A · Recibimos

   El 5 de mayo, la composición de la liquidación diaria incluye la cuota 3 por $19.400. FLUX la cruza 1:1 contra el calendario y recupera el adelanto. Lo mismo en junio y julio. Las cuotas 6 a 12 siguen liquidándose normalmente al comercio.

11 · Puesta en marcha

Para avanzar en la conversación técnica:

1. 1

   Elegir el canal por flujo

   Empezar con archivos planos diarios por SFTP y migrar a API en una segunda fase, o ir directo a API.

2. 2

   Acordar el diccionario de datos definitivo

   Nombres, tipos, largos y catálogos de estados y tipos de movimiento de cada archivo o endpoint, a partir de las tablas de este documento.

3. 3

   Definir frecuencias y ventanas de corte

   Hora de disponibilidad de la liquidación y de las ventas del día.

4. 4

   Mecanismo de redirección

   Cómo se redirige la liquidación de las cuotas adelantadas hacia la cuenta recaudadora de FLUX.

5. 5

   Seguridad y certificación

   Cifrado en tránsito y reposo, firma de mensajes, credenciales y ambiente de pruebas. Se corre un lote completo hasta dejar en cero las filas rechazadas.