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:

envelope de webhook

{
  "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.

Aditivo (no rompe)	Rompiente (nunca en silencio)
Un campo nuevo en una respuesta	Renombrar o quitar un campo existente
Un valor nuevo en un enum	Cambiar el tipo de un campo
Un endpoint o recurso nuevo	Volver requerido un parámetro antes opcional
Un `event_type` nuevo	Cambiar el significado de un campo o de un estado
Un header de respuesta nuevo	Retirar un endpoint

🧱 Escribe un cliente tolerante

Ignora campos que no conozcas en vez de fallar al deserializar.
Trata los enums como abiertos: maneja un status o event_type desconocido con una rama por defecto, no con un crash.
Recuerda que los campos null se omiten en las respuestas de /v1 (no llegan como null, simplemente no están) — no asumas que una llave siempre existe.

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.

Changelog

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

Fecha	Capacidad	Tipo
`2026-07-08`	Infraestructura de plataforma: Winal Connect (split/marketplace), Payouts/dispersión, Onboarding KYC/KYB, pago de servicios, BNPL, tokenización de red y card-present.	Aditivo
`2026-07-08`	Antifraude explicable, card-on-file / cobro 1-click, cobranza inteligente, conciliación bancaria y multisucursal/multicaja.	Aditivo
`2026-07-07`	Facturación CFDI 4.0 (PUE y PPD/REP), ruteo por costo con informe de ahorro, pólizas CONTPAQi/Aspel, propinas + corte de caja y CLI `winal`.	Aditivo
`2026-07-07`	Métodos ampliados y más conectores; `metadata` del intent en `PaymentIntentResponse` y en `data.metadata` del webhook.	Aditivo
`2026-07-07`	Disputas/contracargos, Payment Links + checkout hosteado (`/pay/{slug}`), suscripciones y SDKs oficiales C#/TS/PHP/Python.	Aditivo
`2026-07-01`	`api_version` base: payment intents, confirmación pública con `client_secret`, webhooks firmados y envelope de error estándar.	Base

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.