La respuesta breve
Guarda una Idempotency-Key para cada envío postal previsto en IRIS antes de enviar la solicitud. Si se pierde la respuesta, vuelve a intentarlo con la misma clave y sin modificar la carga útil. Una clave nueva representa otra intención de envío y puede generar otra carta con cargo. Elimina también los eventos de negocio entrantes duplicados en tu propio sistema.
El problema de la ambigüedad cuando se agota el tiempo de espera
Tu servidor envía una solicitud para una carta dirigida a un cliente, IRIS crea el pedido y la conexión de red se cierra antes de que tu servidor reciba la respuesta. Tu aplicación no puede determinar si existe un pedido basándose únicamente en ese tiempo de espera agotado. Al reintentar con una clave recién generada, la solicitud se trata como un nuevo envío postal y puede producir una segunda carta.
El momento correcto para crear la clave es cuando guardas de forma persistente la intención de envío aprobada. Consérvala junto con la carga útil exacta. No la generes dentro de un bucle genérico de reintentos HTTP. Un proceso de trabajo reiniciado debe recuperar la intención guardada en lugar de reconstruir una nueva a partir de la memoria.
Cómo maneja IRIS la reutilización de la misma clave
IRIS limita el alcance de la idempotencia a la cuenta de desarrollador. Su implementación actual calcula un hash de la carga útil validada del envío postal y lo compara con el de la solicitud original. Conserva la carga útil original y su estructura de serialización al reintentar.
| Situación | Manejo esperado |
|---|---|
| Misma clave y carga útil; la creación del pedido anterior se completó | Devuelve el pedido existente con replay: true. |
| Misma clave, distintos detalles del envío postal | 409 idempotency_mismatch; revisa el cambio previsto. |
| La solicitud anterior no se completó | 409 mailing_request_failed; concilia el estado antes de crear otra intención de envío. |
| El pedido guardado no está disponible | 409 mailing_order_missing; investiga el registro. |
| Saldo insuficiente para envíos postales | 402 insufficient_credits; agrega créditos mediante el flujo de trabajo de la cuenta. |
| Demasiadas solicitudes | 429 con Retry-After; espera y conserva la misma intención de envío. |
Elimina también los eventos de negocio duplicados
Una clave de idempotencia HTTP no determina si dos eventos del CRM describen la misma acción de negocio. Si tu CRM entrega el mismo evento dos veces y tu manejador genera dos identificadores de intención de envío, la API de envíos postales recibe dos solicitudes distintas. Agrega una restricción de unicidad en tu aplicación que abarque el evento de origen y la versión del documento.
Por ejemplo, usa un par único como source_event_id y correspondence_type para localizar una intención de envío guardada. Guarda de forma persistente en esa fila el identificador del documento, la carga útil aprobada, la persona que la revisó, la clave y el estado de envío de la solicitud. Dos procesos de trabajo deben competir por la misma fila, no aprobar ni enviar intenciones duplicadas de forma independiente. La eliminación de eventos duplicados se realiza en tu aplicación; la Idempotency-Key de IRIS protege el envío de la solicitud en sí.
Organiza la recuperación como una pequeña máquina de estados
Mantén la política de manejo de respuestas comprensible para la próxima persona de guardia. Un reintento debe conservar una intención de envío conocida, y una solicitud de negocio modificada debe someterse a una nueva revisión.
- Guarda de forma persistente la carga útil aprobada y la clave antes de hacer la primera solicitud POST /v1/mailings.
- Si la solicitud tiene éxito, guarda orderId y el precio devuelto. Trata replay: true como la recuperación del pedido existente.
- Si se agota el tiempo de espera o se produce un fallo de conexión con resultado incierto, marca el envío de la solicitud como incierto y reintenta la solicitud guardada con intervalos de espera progresivos y acotados.
- Ante una respuesta de validación o un código 409, detén el reenvío automático y concilia el registro de origen y el código de error.
- Cuando sea necesario cambiar los detalles, resuelve la intención de envío anterior antes de aprobar una nueva. Una clave nueva no sirve para corregir un resultado anterior desconocido.
Prueba la pérdida de una respuesta antes de enviar cartas a los clientes
En una prueba local, haz que tu API simulada cree un pedido y luego cierre la conexión sin devolver la respuesta JSON. Reinicia el proceso de trabajo y confirma que envíe la misma clave y la carga útil sin cambios. El resultado recuperado debe quedar asociado a la intención de envío original. Esto permite comprobar un escenario de fallo significativo sin generar correo físico.
Entrega también el mismo evento de origen dos veces, inicia dos procesos de trabajo a la vez y modifica el documento después de su aprobación. Tu sistema debe producir una sola intención de envío para el evento duplicado y exigir una nueva revisión del documento modificado. No interpretes la ausencia de un número de seguimiento como prueba de que no se creó ningún pedido.
Fuentes y lecturas adicionales
Publicado por IRIS Postal Forms, operado por Great Lakes Computing Office LLC. ¿Encontraste información desactualizada? Envía una corrección.