Reintentos seguros sin procesamientos duplicados
Si enviaste una solicitud pero no recibiste respuesta, quizá debas enviarla de nuevo. Incluye un identificador de reintento para que el servidor compruebe si ya la procesó.
Al reintentar con el mismo identificador y el mismo contenido, se devuelve el resultado original sin emitir dos cupones ni añadir dos sellos.
Cómo usarlo
Crea un identificador de reintento único para cada operación nueva y envíalo en la cabecera Idempotency-Key. Reutiliza ese identificador solo al reintentar la misma operación si no recibiste respuesta.
curl -X POST "https://api.vivoldi.com/api/coupon/v1/create" \
-H "Authorization: APIKEY {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-20260920-000412" \
-d '{
"nm": "$5 discount coupon",
"discTypeIdx": 458,
"disc": 5
}'
Si no puedes enviar la cabecera, utiliza el campo requestId del cuerpo de la solicitud. Si envías ambos, sus valores deben coincidir.
| Campos | Descripción | Tipo |
|---|---|---|
Idempotency-Key |
Cabecera HTTP. Usa entre 8 y 64 caracteres: letras ASCII, números y . _ : -. Utiliza un valor distinto para cada operación nueva. |
string |
requestId |
Campo del cuerpo de la solicitud. Puede sustituir a la cabecera y tiene el mismo formato. | string |
Ámbito de aplicación
Se aplica a la creación y el canje de cupones, así como a la creación, adición y retirada de sellos y al canje de recompensas. Las API v2 de actualización de cupones y sellos también admiten identificadores de reintento.
El identificador es opcional. Si se omite, la solicitud se procesa como antes. Los registros se conservan durante 72 horas; después, una solicitud con el mismo valor puede tratarse como una operación nueva.
Los identificadores se distinguen por organización y tipo de operación. No reutilices un valor en operaciones distintas dentro de la misma organización.
Respuestas y gestión de errores
Si reintentas una solicitud ya completada con el mismo identificador y contenido, se devuelve el resultado original. La operación y el webhook no vuelven a ejecutarse.
Los conflictos devuelven HTTP 409 y code 409 en el cuerpo. Consulta message para conocer la causa. Incluso con HTTP 200, comprueba que code sea 0.
| Situación | HTTP | code |
Qué hacer |
|---|---|---|---|
| Reintento con el mismo identificador y contenido | 200 | 0 | Se devuelve el resultado original. No hace falta hacer nada más. |
| Mismo identificador usado con otro contenido | 409 | 409 | Usa un identificador nuevo para la nueva operación. |
| La solicitud anterior con el mismo identificador sigue en curso | 409 | 409 | Espera un momento y reintenta con el mismo identificador. |
| La cabecera y requestId tienen valores distintos | 400 | 1213 | Haz coincidir los valores o envía solo uno. |
| Formato de identificador no válido | 400 | 1216 | Usa entre 8 y 64 caracteres: letras ASCII, números y . _ : - |
| Otra solicitud modificó antes el mismo elemento | 409 | 409 | Consulta el estado más reciente y revisa tu solicitud. |
Buenas prácticas para reintentar
- Elige un valor, como un número de pedido, que puedas reutilizar al reintentar la misma operación. Si generas uno nuevo en cada intento, no se asociará con la solicitud anterior.
- Si no recibes respuesta, reintenta con el mismo identificador y contenido. Si cambias el contenido, usa un identificador nuevo.
- La respuesta a HTTP 409 depende de la causa. Si la operación sigue en curso, reintenta más tarde. Si se reutilizó un identificador o hubo una modificación simultánea, revisa la solicitud.