Las rutas de callbacks son exclusivas del adaptador. No las llames desde una aplicación cliente.
Crea tu ruta de integración
- Despliega las dependencias del plugin, incluidos Midaz y el adaptador de conectividad de tu entorno.
- Obtén un token de acceso cuando la autenticación esté habilitada e identifica la cuenta que posee cada solicitud.
- Ejecuta un flujo público: una clave, una transferencia o un cobro.
- Conserva el identificador de operación que devuelve la solicitud de creación. Lee esa operación hasta que alcance un estado terminal después del callback del adaptador.
- Registra juntos la contabilización de Midaz y el resultado de la operación.
Convenciones de solicitud
Usa la referencia de cada operación como autoridad final. Estas convenciones se repiten en todo el plugin:
Un header de idempotencia ausente o no válido es un error del cliente. Reutilizar una clave con un payload diferente es un fallo de precondición, excepto cuando creas un cobro inmediato o con fecha de vencimiento: esas dos rutas devuelven el cobro existente con
200.
Lee el estado después de una escritura asíncrona
Una solicitud correcta puede significar que el plugin aceptó el trabajo, no que el pago o el cobro externo terminó. Para SPI, usa el identificador de transferencia o devolución devuelto con el endpoint de lectura de transferencia o devolución. Para los cobros, lee el cobro mediante su identificador. Trata estos resultados de forma distinta:- Error de validación o autorización: corrige la solicitud o el token. No repitas una entrada sin cambios.
- Respuesta de repetición: conserva el resultado original. No crees una segunda operación de negocio.
- Conflicto: lee el recurso y elige la siguiente transición legal.
- Error temporal de dependencia: conserva el valor de idempotencia antes de reintentar. Una ruta que documenta una dependencia de fallo seguro seguirá rechazando la escritura hasta que esa dependencia se restaure.