Estado 

El soporte de claves de idempotencia es parcial en la actualidad. Las mutaciones internas de reintento seleccionadas —por ejemplo, los flujos de reintento de facturación de pedidos y de reintento de facturación de reembolsos— ya aceptan una clave de idempotencia y la utilizan para deduplicar las llamadas al procesador de pagos. Aún no existe un argumento idempotencyKey estandarizado en todas las mutaciones de creación orientadas al cliente en el Graph de Zonos; eso está en la hoja de ruta. Hasta que esté disponible, utilice los patrones que se indican a continuación para mantener las mutaciones seguras para reintentar.

Mutaciones seguras por defecto 

Algunas mutaciones son naturalmente idempotentes porque realizan upsert mediante un identificador estable que usted proporciona. Cuando las invoca con la misma entrada, el resultado es el mismo: no hay riesgo de crear duplicados.

• Las mutaciones que reciben un identificador único proporcionado por el comerciante (por ejemplo, un externalId de pedido) devolverán el registro existente en una llamada repetida en lugar de crear uno nuevo.
• Las operaciones de solo lectura (consultas) siempre son seguras para reintentar.

Cuando pueda adjuntar su propio identificador estable al recurso que está creando, prefiera esa vía.

Patrones para mutaciones que no son naturalmente idempotentes 

Para mutaciones que crean recursos sin una clave proporcionada por el comerciante, trátelas siguiendo el principio de como máximo una vez desde su lado:

1. Persista la solicitud antes de enviarla. Escriba una fila en su propia base de datos (estado pending) antes de la llamada de red.
2. Envíe la mutación. En caso de éxito, registre el id del recurso devuelto en su fila pendiente (estado committed).
3. Ante un error de red, no reintente a ciegas. Consulte el Graph de Zonos para determinar si el recurso se creó (por ejemplo, listando recursos creados en los últimos minutos para su cuenta, o consultando un recurso relacionado que pueda correlacionar). Solo reintente si puede confirmar que el recurso no está presente.
4. Use una restricción única en su propia base de datos sobre la clave de negocio que represente la solicitud, de modo que un reintento duplicado desde su propia aplicación no pueda enviar dos veces.

La entrega de webhooks es al menos una vez 

Cuando consuma webhooks de Zonos, diseñe los controladores para que sean idempotentes: el mismo evento puede entregarse más de una vez. Deduplique por el id del evento. Consulte Webhooks para el campo de id del evento.

Hacia dónde se dirige la plataforma 

La plataforma subyacente ya ejecuta flujos de claves de idempotencia en producción para reintentos de facturación: la clave delimita un intento de reintento y evita llamadas duplicadas al procesador de pagos. Estamos trabajando para exponer el mismo patrón como argumento opcional idempotencyKey en mutaciones de creación orientadas al cliente. Cuando se proporcione, el Graph devolverá la respuesta original para cualquier llamada posterior con la misma clave dentro de una ventana de retención. Esta página se actualizará cuando la funcionalidad esté disponible de forma general.

Si las claves de idempotencia estandarizadas en mutaciones orientadas al cliente bloquean su integración, contacte con soporte.