Pedidos duplicados al trabajar con la API: causas y protección

Por qué aparecen duplicados tras una sola acción

El dueño del panel puede pulsar un botón una vez y ver varios pedidos idénticos: seguidores, visualizaciones, reacciones u otro servicio. Normalmente el problema no está en el clic en sí, sino en la cadena entre el cliente, la API, la base de datos y el proveedor.

Desde el punto de vista del servidor, «una solicitud» no siempre es una sola. Puede que el cliente no recibiera la respuesta, reenviara la solicitud, y que la primera operación ya se hubiera guardado. A veces el pedido se crea una vez en la base del panel, pero se envía dos veces al proveedor. Son escenarios distintos y se corrigen de forma distinta.

Un tiempo de espera agotado no significa que el pedido no se haya creado

La causa más frecuente es que el cliente espera la respuesta durante un tiempo limitado. El servidor recibe la solicitud, crea el pedido, pero responde después del tiempo de espera establecido. El cliente considera la operación fallida y la envía de nuevo.

Como resultado, el primer pedido ya está en la base y la segunda solicitud crea otro más. Esto ocurre especialmente cuando la respuesta de una API externa es lenta, la cola está sobrecargada o la conexión entre servicios es inestable.

Un tiempo de espera agotado solo indica la ausencia de respuesta, no la ausencia de procesamiento de la solicitud.

Reintentos automáticos en el lado del cliente

Las bibliotecas para solicitudes HTTP, las tareas en segundo plano y los servicios de integración a menudo repiten la solicitud automáticamente. El motivo puede ser un error de conexión, un código de respuesta del servidor, una interrupción de la red o una respuesta demasiado lenta.

El reintento en sí es útil: reduce el número de pedidos perdidos durante fallos temporales. La desventaja de este enfoque es que, sin protección contra el reprocesamiento, convierte cualquier inestabilidad de la red en duplicados.

• el reintento puede iniciarse en el código del sitio o del bot;
• la cola puede reiniciar la tarea;
• la solicitud puede repetirse desde un proxy o un módulo de integración;
• el operador puede reenviar el pedido manualmente tras un error.

La solicitud repetida llega antes que la primera respuesta

A veces dos solicitudes idénticas llegan realmente a la API casi al mismo tiempo. Por ejemplo, el usuario envió el formulario dos veces, el frontend no bloqueó el botón o una tarea en segundo plano se inició de nuevo antes de que terminara la primera.

Si el controlador primero comprueba si existe el pedido y luego lo crea, dos operaciones paralelas pueden superar la comprobación al mismo tiempo. Cada una verá que el pedido aún no existe y cada una añadirá un nuevo registro.

Esta situación se denomina condición de carrera. Una simple comprobación previa en el código no protege completamente contra ella. La desventaja de comprobar sin una restricción a nivel de base de datos es que falla bajo carga paralela.

El pedido se guardó, pero la respuesta de la API se perdió

La solicitud pasa por varias etapas: el servidor recibe los datos, crea el registro, pone la tarea en la cola, envía la respuesta. El fallo puede ocurrir entre cualquiera de ellas. Por ejemplo, la base ya confirmó la creación del pedido, pero la conexión se interrumpió antes de transmitir la respuesta al cliente.

El cliente no sabe si el pedido fue aceptado y repite la operación. Una API sin un mecanismo de comprobación específico percibe la solicitud como nueva. En el registro esto suele parecer que el servicio creó dos pedidos «por sí solo», aunque recibió dos peticiones entrantes.

Clave de idempotencia para crear un pedido

Para las operaciones de creación se necesita una clave de idempotencia única. El cliente la genera antes del primer envío y la transmite junto con los parámetros del pedido. Al repetir por un tiempo de espera agotado o un error se utiliza la misma clave.

La API guarda la clave junto con el resultado del procesamiento. Si llega una solicitud con una clave ya conocida, el servidor no crea un nuevo pedido, sino que devuelve el resultado de la primera petición: el identificador del pedido, su estado o el error generado anteriormente.

Una clave debe corresponder a una operación de negocio, no a una conexión HTTP.

La desventaja del método es que las claves deben almacenarse, depurarse según las reglas y comprobarse en el lado de la API. Si se genera una nueva clave en cada reintento, la protección no funcionará. Si se usa una misma clave para pedidos distintos, parte de las nuevas operaciones se rechazarán por error.

La unicidad debe controlarse en la base de datos

La idempotencia es mejor complementarla con una restricción de unicidad en la base de datos. Para ello se elige una combinación que describa inequívocamente el pedido: identificador interno del cliente, clave de idempotencia, tipo de servicio y otros campos necesarios.

La base de datos debe rechazar el segundo registro, incluso si dos controladores llegaron a crear al mismo tiempo. Tras el conflicto, la API devuelve el pedido existente, no un error sin explicación.

La desventaja de una restricción de unicidad estricta es que no puede basarse solo en el enlace o el nombre de usuario. El cliente puede pedir conscientemente un mismo servicio para el mismo canal varias veces. Una restricción demasiado amplia bloqueará compras repetidas normales.

La cola puede entregar la tarea más de una vez

Las colas de tareas suelen funcionar según el principio de «entrega al menos una vez». Si un worker procesó la tarea pero no llegó a confirmar su ejecución, la cola puede entregar la misma tarea de nuevo a otro worker.

Para la cola, esta es una forma normal de no perder la tarea. Para la creación de un pedido sin idempotencia, es una fuente de duplicados. El identificador de la tarea o una clave de operación específica debe transmitirse hasta el controlador final, incluido el módulo de envío del pedido al proveedor.

La desventaja de desactivar la reentrega es que, si un worker cae, parte de los pedidos puede perderse. Es más seguro aceptar posibles repeticiones y hacer que el controlador sea resistente a ellas.

Los duplicados surgen entre el panel y el proveedor

El pedido interno puede crearse una vez, pero la solicitud a la API externa enviarse dos veces. La causa es la misma: el panel no recibió respuesta del proveedor y decidió repetir el envío. Si el proveedor llegó a aceptar la primera solicitud, en su lado aparecerán dos solicitudes idénticas.

Se necesita una vinculación específica del pedido interno con el externo: identificador de envío, clave de idempotencia o respuesta guardada del proveedor. No se puede dar por hecho que la protección en la entrada del propio panel protegerá automáticamente las llamadas salientes.

La desventaja de la conciliación con una API de terceros es que no todos los proveedores admiten la búsqueda por clave externa. En ese caso hay que registrar los intentos de envío y analizar por separado los estados indeterminados.

El webhook no debe crear un nuevo pedido

Los webhooks informan de cambios: el pedido fue aceptado, iniciado, completado, cancelado o requiere revisión. El error surge cuando el controlador del webhook percibe la notificación como una orden de crear el pedido de nuevo.

Un mismo webhook puede llegar repetidamente. El emisor repite la entrega si no recibió confirmación, y las notificaciones a veces llegan desordenadas. El controlador debe encontrar el pedido existente por el identificador externo y actualizar el estado.

La desventaja de procesar los webhooks solo por la hora de recepción es que una notificación tardía puede sobrescribir el estado actual con uno desactualizado. Se necesitan un identificador de evento, una versión del estado o reglas claras de transición.

Qué registros ayudarán a encontrar el origen de los duplicados

Para la investigación no basta con ver solo dos números de pedido. Se necesitan datos de cada etapa del procesamiento: hora de la solicitud, clave de idempotencia, identificador del cliente, parámetros del pedido, número de la tarea en segundo plano, respuesta de la API externa e intentos de reenvío.

• compare los duplicados por la clave de operación, no solo por el enlace;
• compruebe si hubo solicitudes idénticas en el registro de la API entrante;
• vea si la tarea se repitió en la cola;
• separe la creación del pedido interno del envío al proveedor;
• guarde el identificador externo de la solicitud inmediatamente después de recibir la respuesta.

La desventaja de unos registros demasiado breves es que el origen del problema desaparece antes de que se pueda analizar. La desventaja de un registro excesivo es que en el registro pueden acabar tokens, datos personales y otros campos sensibles, por lo que hay que enmascararlos.

Cómo gestionar un resultado indeterminado de la solicitud

Tras un tiempo de espera agotado no se puede crear inmediatamente un pedido de nuevo con datos nuevos. Primero la API debe comprobar la operación por la clave de idempotencia o el identificador del cliente. Si se encuentra el pedido, se devuelve su estado actual. Si el procesamiento aún está en curso, el cliente recibe un estado de espera.

1. Crear la clave de operación antes de la primera solicitud.
2. Enviar la misma clave en cada reintento.
3. Guardar la clave y el pedido en una misma operación protegida de la base de datos.
4. Transmitir el identificador de la operación a la cola y a la API externa.
5. Devolver el pedido creado anteriormente en caso de una nueva petición.

Este escenario requiere modificar la API y la integración del cliente. Su desventaja es una depuración más compleja y más estados del pedido, pero la reentrega de una solicitud deja de significar automáticamente una compra repetida.