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.

Request
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 2000 Se devuelve el resultado original. No hace falta hacer nada más.
Mismo identificador usado con otro contenido 409409 Usa un identificador nuevo para la nueva operación.
La solicitud anterior con el mismo identificador sigue en curso 409409 Espera un momento y reintenta con el mismo identificador.
La cabecera y requestId tienen valores distintos 4001213 Haz coincidir los valores o envía solo uno.
Formato de identificador no válido 4001216 Usa entre 8 y 64 caracteres: letras ASCII, números y . _ : -
Otra solicitud modificó antes el mismo elemento 409409 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.