Lanzar cambios en una integración de pagos: API, webhooks e informes financieros

El versionado de API empieza fuera del código. Un empleado de finanzas añadió una columna útil a la exportación. A la mañana siguiente, la conciliación automática registró las comisiones en el campo del importe. Nadie tocó la API de pagos ni hubo despliegue del sitio, pero el proceso del dinero ya había cambiado. Es un buen punto de partida: el contrato de una integración va mucho más allá de la URL de la solicitud de pago.

Un cambio puede afectar al SDK, a la versión de la API, al formato de las notificaciones, a la configuración de la cuenta, a la composición del informe y a la forma en que usted interpreta los estados. Si el equipo solo controla el código de la aplicación, parte de los lanzamientos ocurre sin su participación. A continuación se propone un proceso que hace visibles y verificables esos cambios.

Cuatro contratos sobre los datos

Primer contrato: qué envía la aplicación al proveedor y qué respuesta entiende. Segundo: qué eventos asíncronos recibe y cómo verifica su autenticidad. Tercero: qué registros financieros obtiene en los informes. Cuarto: qué considera el propio producto como resultado de esa información. Cambiar un contrato puede no romper técnicamente los demás, pero sí alterar su significado.

Stripe permite fijar la versión de las solicitudes a la API y, por separado, tener en cuenta la versión del webhook endpoint. Reglas de versionado de Stripe. Por eso la línea «SDK actualizado» no confirma que todos los consumidores reciban la estructura esperada. Documente la configuración que realmente se aplica en cada canal, no solo las versiones de las dependencias en el repositorio.

Adyen distingue entre cambios compatibles y cambios que requieren una nueva versión de la API; las versiones de las librerías siguen su propio esquema. Reglas de Adyen. El contrato exacto hay que leerlo en la documentación del proveedor. Añadir un campo nuevo permitido y cambiar el valor de un campo existente tienen consecuencias distintas para su manejador.

Un valor nuevo y desconocido debe ser visible

En un sistema de ejemplo, el parser entiende tres estados. Llega un cuarto. Opción peligrosa: clasificarlo como exitoso para que el proceso no falle. Otra opción peligrosa: descartar la fila y entregar al equipo financiero un informe «limpio». La política propuesta conserva el registro en el alcance permitido, marca el valor no soportado y lo envía a revisión sin ningún efecto financiero automático.

Con un campo opcional desconocido el comportamiento puede ser otro: ignorarlo correctamente si así lo prevé el contrato documentado. Por eso la regla «fallar ante cualquier campo nuevo» también es demasiado tosca. Separe la ampliación de la estructura, el estado de negocio desconocido, la ausencia de un campo obligatorio y el cambio de formato del importe. Cada caso necesita su propia prueba.

Un CSV financiero también es una API

Adyen advierte expresamente que cambiar la composición y el orden de las columnas del informe puede afectar al procesamiento automático. Configuración de columnas del Payment accounting report. Considere esos ajustes parte de la integración controlada, aunque se cambien con el ratón en el panel.

Conviene que el parser valide los encabezados esperados y los campos obligatorios, en lugar de confiar en que «el importe siempre está en la octava columna». Verifique además la moneda, el signo, la escala, el número de registros y las sumas de control cuando estén disponibles. Un encabezado correcto no protege frente a un cambio de significado del campo, así que hacen falta ejemplos de tipos de registro reales en un conjunto de prueba autorizado.

El responsable del informe debe saber qué sistemas lo leen. Antes de un cambio, prepare una muestra, compruebe los consumidores y acuerde el momento del cambio. Conserve la configuración anterior si el producto lo permite. No pida al equipo financiero que reordene columnas a mano cada mañana para ocultar una incompatibilidad.

Ensayo y límites del rollback

Reúna un pequeño conjunto de ejemplos sintéticos o anonimizados con permiso: pago, rechazo, reembolso parcial, retención, evento tardío, estado desconocido. Procéselo con el parser antiguo y con el nuevo sin ninguna acción financiera externa. Compare no solo si la carga fue correcta, sino también las obligaciones resultantes, los importes y la cola de excepciones.

Si es posible un cálculo en paralelo, la nueva versión primero calcula el resultado en modo observación, sin ejecutar cargos ni liquidaciones. La diferencia entre versiones debe estar explicada antes de ampliar el despliegue. Defina condiciones de parada: registros perdidos, moneda incorrecta, importes inexplicables o un cambio en si un pedido puede o no cumplirse.

Revertir el código no anula un reembolso ya creado ni restaura automáticamente la configuración anterior del panel. Para cada componente que cambie, indique la forma de volver atrás, sus limitaciones y qué hacer con las operaciones que ya se procesaron. Si no existe camino de vuelta, el plan debe describir con honestidad una corrección hacia delante, no prometer un botón mágico.

Conviene cerrar la actualización después del primer ciclo completo afectado, incluidos el informe y la conciliación, y no tras el primer HTTP 200. Al final, el equipo se queda con una ficha breve del cambio: qué se modificó, qué resultados se compararon, quién autorizó la ampliación y qué queda por vigilar.