Tu aplicación inicia un pago, reembolso u otra operación admitida.
Guía para desarrolladores
Comandos síncronos. Resultados financieros asíncronos.
Las operaciones financieras suelen continuar después de la respuesta inicial. Usa comandos para iniciar trabajo, eventos para avisar a los sistemas que deben reaccionar y consultas para obtener el estado operativo más reciente sin acoplar la aplicación a callbacks específicos de proveedores.
01Comando
02Respuesta inicial
03Proceso del proveedor
04Evento
05Consulta de estado
Límite de integración
Los eventos transportan cambios del ciclo, no complejidad del proveedor
Las aplicaciones deben reaccionar al significado empresarial de un evento en lugar de aprender el modelo de callback de cada banco, PSP, adquirente o proveedor de terminal. El límite de plataforma mantiene el comportamiento específico del proveedor detrás de un modelo de integración más estable.
La respuesta síncrona identifica la operación y su estado actual.
La autenticación, actividad de terminal o procesamiento del proveedor puede continuar de forma asíncrona.
Un cambio del ciclo de vida se entrega a los sistemas que deben reaccionar.
El sistema consumidor puede consultar el estado actual cuando necesita contexto operativo autoritativo.
Patrón probado
Patrones de eventos semánticos
La experiencia de integración en producción demuestra el valor de los avisos de cambio de estado y finalización en pagos online y otros métodos. Lo reutilizable es el ciclo semántico, no el nombre específico del evento de un proveedor.
- Estado del pago modificado — la operación pasó a un nuevo estado de pago.
- Autenticación finalizada — el paso de autenticación del cliente alcanzó un resultado.
- Reembolso actualizado — un ajuste posterior al pago cambió de estado.
- Operación de terminal o canal completada — un flujo asíncrono de canal alcanzó un resultado.
Envoltorio conceptual de evento — no es un esquema actual de webhook
{
"event": "semantic-lifecycle-event",
"transaction_id": "durable-transaction-id",
"reference": "your-business-reference",
"state": "...",
"occurred_at": "..."
}Modelo de implementación
Guía de integración
Estos patrones describen comportamientos de integración probados en sistemas de producción. Definen el modelo técnico; no prometen que la API actual de Zopio vaya a utilizar un endpoint, campo o formato de contrato concreto.
Trata los eventos como notificaciones
Usa el evento para activar trabajo posterior sin ligar la lógica de negocio al formato de callback de un proveedor.
Conserva la identidad de transacción
Mantén cada actualización asíncrona conectada al mismo contexto transaccional duradero.
Consulta cuando importe el estado actual
Cuando un flujo necesite la verdad operativa más reciente, utiliza una consulta de estado en lugar de depender de un único callback.
Diseña consumidores tolerantes a repeticiones
Los sistemas posteriores deben reconocer actualizaciones ya procesadas y evitar duplicar acciones de negocio.
Mantén las diferencias de canal detrás del límite
Los flujos online, terminales y de pagos alternativos pueden mostrar comportamientos diferentes mientras comparten los mismos principios de integración.
Seguir explorando
Hablar sobre tu integración