Versionado y cambios

Winal versiona en dos planos que no debes confundir: la ruta (/v1), que cambia solo ante rediseños incompatibles a gran escala, y la versión de API por fecha (api_version), que fija la forma exacta de los payloads. La regla de oro: tu integración no se rompe por un cambio que tú no pediste.

La ruta /v1

Todos los endpoints de integración cuelgan de /v1. Ese número mayor solo cambiaría ante un rediseño incompatible del API completo — algo raro y muy anunciado. Mientras exista /v1, seguirá aceptando el contrato que documentamos aquí.

api_version por fecha

La forma concreta de los recursos se identifica con una versión con fecha, del estilo 2026-07-01. La verás en cada entrega de webhook, en el campo api_version del envelope:

{
  "event_id": "8f2a1c3e-...",
  "event_type": "payment_intent.succeeded",
  "api_version": "2026-07-01",
  "livemode": false,
  "data": { "...": "..." }
}

Esa marca te dice contra qué contrato serializamos el payload. Fíjala en tu integración (guárdala o valídala) para saber, sin ambigüedad, qué forma esperar.

Cómo introducimos cambios

Distinguimos cambios aditivos (seguros, entran sin aviso) de cambios rompientes (nunca en silencio). Escribe tu cliente para tolerar los primeros.

Los cambios rompientes, cuando sean inevitables, se introducen bajo una api_version nueva y con aviso previo; tu integración existente sigue recibiendo la forma con la que la escribiste hasta que decidas migrar.

Deprecación

Cuando algo va a retirarse, lo marcamos como deprecado en la Referencia y en las notas de cambio, con una alternativa recomendada y una ventana de transición. Un endpoint deprecado sigue funcionando durante esa ventana; no desaparece de un día para otro.

2026-09-24 — Depósitos: el formulario de TAECEL, el aviso y el saldo al momento

Lo que un punto de venta necesita para que una farmacia fondee su saldo y sepa cuándo ya puede vender. Todo es aditivo salvo una corrección, abajo. El comprobante lo recibe y lo valida TAECEL en su propio formulario; Winal no ve ni guarda el archivo.

• Endpoints nuevos: GET /v1/recharge-report-links (el enlace del formulario de reporte de depósitos de cada bolsa propia de la cuenta, incluida la cuenta madre del integrador) y POST /v1/recharge-report-links/refresh (volver a leerlo del agregador).
• El saldo al momento: POST /v1/recharge-balance/refresh lee la bolsa en el momento, con un freno de 10 minutos por bolsa; GET /v1/recharges/balance gana el bloque refresh.
• Un event_type nuevo: recharge.deposit.detected, uno por abono nuevo en una bolsa de la cuenta. Si tu endpoint filtra por lista blanca de eventos, no lo recibirás hasta que lo agregues; si recibe todo, trata el tipo como desconocido o procésalo.
• Códigos nuevos: recharge.balance_refresh_unavailable, recharge.report_link_unavailable, recharge.report_link_source_not_found, recharge.report_link_requires_live_key (pedirlo con llave de prueba llamaría al agregador con credenciales REALES).
• Corrección en GET /v1/recharges/balance: uses_own_credentials salía false para cualquier bolsa —también la de la cuenta madre del integrador y la cuenta propia de una farmacia—, lo contrario de lo que el campo documenta (false = «ese saldo NO es tuyo, es de quien te administra»). Ahora es true cuando la bolsa es de la cuenta y false solo cuando es de quien la administra. Si tu punto de venta ocultaba el saldo de una bolsa propia por ese campo, a partir de hoy lo verá.

2026-09-20 — Varios agregadores de recargas: respaldo, ruteo y cuadre por agregador

Un solo programa en tres piezas, todas aditivas, en POST /v1/recharges, GET /v1/recharges, GET /v1/recharges/{id} y GET /v1/recharges/statement(.csv): nada se renombra, nada cambia de significado, ningún estado nuevo, ningún campo que ya leías cambia de posición. Si tu integración ya funciona, sigue funcionando sin tocar nada. Lo que sigue es lo que puedes empezar a usar.

• Una recarga es un pedido que Winal puede surtir por más de un agregador. Cuando el primero contesta un rechazo firme, Winal la intenta por el siguiente —en la misma petición si el rechazo fue inmediato— y te devuelve un solo resultado. Nunca ante un timeout: ahí la transacción pudo entrar y pasar a otro agregador serían dos recargas al mismo teléfono. Tampoco cuando un intento se cierra por no aparecer en el reporte de ventas del agregador: ese cierre termina el pedido (failure_code: "not_requested") sin respaldo, porque la ausencia en un reporte acotado por tiempo no prueba que no se entregó. Campos nuevos: attempts[] (un intento por agregador, con su estado, transacción, costo real y por qué fue ahí), attempt_count y failure_code (solo con status: "failed"). Los campos que ya leías —provider_ref, provider_transaction_id, provider_cost_minor, client_reference, connector_key, requested_at— son los del intento que entregó (o del último), que para un pedido de un solo intento son exactamente los de siempre. El id es el del pedido y es el mismo que ya guardaste: todos los ids emitidos antes siguen resolviendo. Detalle en Recargas → Cuando un agregador falla.
• Winal elige el agregador por salud, saldo y prioridad. Cada attempts[].routing trae evaluated[]: los agregadores evaluados con provider_key, eligible y el motivo en español («cortacircuito abierto hasta 21:32 UTC por 3 fallos del agregador para 'telcel' en 10 min», «sin saldo suficiente: $180.00 disponibles para $194.00», «prioridad del comercio para 'telcel': posición 1», «más barato de los sanos: $47.00 frente a $48.00»). Tu prioridad por operadora se fija en el tablero → Recargas → Agregadores, donde también ves por dónde iría AHORA una recarga y por qué. Los filtros, en orden, en Recargas → Cómo elige Winal el agregador.
• Cuadre por agregador. GET /v1/recharges/statement gana by_connector[] —el mismo período por agregador: cargos, en vuelo, rechazadas, abonos y cupo— y cada cifra del total es la suma de la misma cifra en los agregadores. El estado de cuenta, el CSV y el listado aceptan ?connector_key= para ver UN agregador; una clave desconocida se rechaza con 400 recharge.connector_key_unknown (nunca ceros). Una venta servida por respaldo aparece en el agregador que entregó, con su costo real. El CSV acotado lleva solo líneas de recarga (los pagos de servicio no guardan agregador); el CSV completo gana dos columnas al final, pedido_id e intento_no. La respuesta repite connector_key solo cuando filtras. Ver Recargas → Cuadrar por agregador.

• Un cierre que Winal ya no publica como fracaso firme. Cuando un intento no aparece en el reporte de ventas del agregador, Winal cierra la recarga —no la reintenta por otra vía— pero no afirma que no se entregó: el reporte se sella con el reloj del agregador y una venta que sí entró puede caer fuera de la ventana. Ese cierre trae ahora failure_code: "absent_from_report" (valor NUEVO del catálogo cerrado de failure_code) con outcome: "undetermined", settled: false, safe_to_retry: false y el campo nuevo needs_review: true. Antes salía como not_requested con safe_to_retry: true, y eso te pedía hacer exactamente el doble envío que Winal acababa de no hacer. Si programas if (!safe_to_retry) return; —lo que la doc recomienda— no tienes que cambiar nada: ahora te frena donde antes te dejaba seguir. Y Winal sigue leyendo los reportes de los tres días siguientes: si la venta aparece entregada, esa MISMA recarga pasa a delivered sola (por eso settled es false); si aparece fracasada, pasa a failure_code: "failed" con safe_to_retry: true. Ver Recargas → Lo que no se pudo determinar se vuelve a mirar.

Lo que NO cambia. Nada en la API nombra al agregador salvo el connector_key que ya venía en cada recarga y el filtro nuevo; el traspaso de saldo sigue exigiendo dos cuentas en el agregador (el destino es un clienteID del proveedor, no otra bolsa dentro de la misma cuenta); pouch_id sigue siendo solo del JSON del estado de cuenta; y las reglas de dinero —un timeout no es un fracaso, una entrega no se reversa— son las mismas.

2026-09-18 — Tu Idempotency-Key ahora es de tu ambiente

Un cambio de contrato en toda operación que mueve dinero o timbra un comprobante, más una capacidad nueva para quien administra cuentas. Cinco minutos de lectura; probablemente no tengas que cambiar nada.

El cambio de contrato: qué es distinto y qué sigue igual

Una Idempotency-Key se identificaba por (tu cuenta, la llave). Ahora se identifica por (tu cuenta, el AMBIENTE de tu credencial, la llave) — ver el detalle en Entornos y Base URL. Aplica a toda ruta que mueve dinero o emite un comprobante fiscal: cobros, refunds, payouts, traspasos de Connect, facturas, notas de crédito y complementos de pago (REP), recargas y pagos de servicio, y el nuevo traspaso de saldo entre bolsas.

Dentro de un mismo ambiente, nada cambia: la misma llave con el mismo cuerpo te sigue devolviendo la misma operación sin volver a ejecutarla, y con otro cuerpo sigue siendo un conflicto. Lo que cambia es el cruce ENTRE ambientes. Antes, tu sk_test_ y tu sk_live_ compartían el espacio de llaves de tu cuenta; si reutilizabas la misma Idempotency-Key en los dos —lo típico si la derivas de tu folio de ticket y probaste en sandbox con los mismos folios con los que vendes de verdad—, tu primera operación real en producción podía recibir de vuelta, silenciosamente, la respuesta que ya se había cacheado en pruebas: un acuse de éxito por una operación que solo ocurrió en el simulador. Ahora esa misma llave desde el otro ambiente es una petición nueva, que ejecuta y crea su propia operación.

Esto se arregló, y pudo haberte tocado

• Reintentar una factura (POST /v1/invoices/{id}/retry) y las dos rutas de cancelación ahora comparan el ambiente contra el del comprobante mismo (un dato de su propia fila, fijado al timbrar y que nunca cambia), no solo contra tu perfil fiscal actual. Un CFDI que nació en pruebas se reintenta y se cancela SIEMPRE con sk_test_ y el perfil en sandbox — aunque tu cuenta ya esté en producción. Detalle en invoice.livemode_mismatch.
• ¿Tienes facturas de PRUEBA que quedaron en error de cuando integrabas? No tienes nada que cerrar: nunca tuvieron valor fiscal ni te obligan ante el SAT (y, por lo de arriba, ya ni siquiera se pueden reintentar con tu llave de producción). Factura la venta real como un comprobante nuevo.
• Tu factura GLOBAL mensual o bimestral de pruebas ya no ocupa el período de la real. Antes, timbrar la global de agosto en sandbox mientras probabas bloqueaba la global REAL de agosto —una obligación fiscal— y la única salida era mover tu perfil a sandbox, cancelar ahí y regresarlo. Ya no hace falta: las dos globales del mismo mes, una por ambiente, coexisten sin chocar (tampoco se pueden sustituir entre sí). Ver Facturación CFDI → Factura global.

Nuevo: mueve saldo entre tus propias cuentas del agregador

Si administras cuentas de terceros (Cuentas administradas) y cada una tiene su PROPIA cuenta en el agregador de recargas, hoy fondear cada una exige un depósito bancario por separado. POST /v1/recharge-transfers mueve saldo YA depositado de una bolsa tuya a otra del mismo comercio: depositas una vez a tu cuenta central y repartes desde tu sistema. Detalle completo en Recargas de tiempo aire → Traspasar saldo entre tus bolsas.

Es irreversible una vez aplicado —el agregador no cancela ni reversa un traspaso exitoso, igual que una recarga entregada—. Si mandas de más, la única salida es que la cuenta destino te lo regrese con otro traspaso.

Nuevo, y ya lo puedes usar sin condiciones: el historial de tu bolsa

GET /v1/recharges/bag-movements lee el historial de movimientos de tu bolsa —incluidos los depósitos— tal como lo reporta el agregador, para conciliar un comprobante de depósito sin hacer la resta de saldos a mano. Ver Recargas de tiempo aire → Conciliar un depósito.

Changelog

Historial de capacidades del API, de lo más reciente a lo más antiguo. Las fechas son de disponibilidad en modo prueba.

Fase 0, modo prueba: el API está estable y probado de extremo a extremo; la única marca de api_version en circulación es 2026-07-01. Este changelog crecerá con cada versión con fecha que publiquemos.