Procesamiento del estado «en ejecución» al consultar un pedido a través de la API

Qué significa processing en la respuesta de la API

El estado processing, in_progress u otro estado equivalente significa que el proveedor aceptó el pedido para su procesamiento, pero no fijó el resultado final. Para los servicios de promoción esto puede ser la verificación del enlace, la espera en cola, el inicio de la tarea o la entrega gradual del volumen solicitado.

Processing no confirma la ejecución exitosa ni significa un error. Después de él, el pedido puede pasar a completed, partial, canceled o failed. Mientras el proveedor devuelva un estado intermedio, no cree una nueva solicitud para el mismo enlace y el mismo volumen.

HTTP 200 con estado processing significa una respuesta exitosa de la API, no la finalización exitosa del pedido. Estos eventos deben almacenarse y procesarse por separado.

Qué datos se necesitan para consultar el pedido

Para el polling se necesita el ID externo del pedido que devolvió el proveedor al crearlo. Guárdelo junto con el ID interno, el volumen inicial, los parámetros del servicio, el enlace, la hora de creación y la respuesta original de la API. Buscar el pedido por el nombre del canal, el enlace o el volumen no es fiable: esos valores pueden coincidir en varias solicitudes.

Si tras la creación llegó un tiempo de espera agotado, no envíe la solicitud de nuevo automáticamente. El proveedor pudo haber aceptado la solicitud y la respuesta pudo perderse en el camino. Primero utilice el método de búsqueda de pedidos, si existe en la documentación, o derive el caso a revisión.

La desventaja de almacenar solo el estado actual es que, en caso de disputa, es imposible reconstruir cuándo pasó el pedido a processing, si hubo progreso y qué respuestas llegaron antes.

Ejemplo de solicitud de estado mediante curl

Tome la dirección exacta, el método de autorización y los nombres de los campos de la documentación del proveedor. A continuación se muestra una plantilla: los valores entre corchetes angulares deben sustituirse por los datos de la API concreta.

Solicitud GET para un pedido

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Ejemplo de respuesta:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

Los campos completed_quantity y remains se muestran solo como ejemplo de estructura. El proveedor puede usar progress, start_count, balance u otros nombres. La desventaja del enfoque GET es que parte de las API aceptan la consulta de estado solo mediante POST.

Ejemplo de solicitud POST y consulta por lotes

Solicitud POST del estado de un pedido

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

No pase la clave de API en la cadena de URL. Las direcciones de las solicitudes acaban en los registros del proxy, los sistemas de analítica, el historial del navegador y los logs técnicos. La desventaja de POST es que es más difícil comprobarlo manualmente a través de la barra de direcciones, pero eso no es motivo para trasladar el secreto a la URL.

Solicitud por lotes de pedidos activos

Si la API admite la consulta por lotes, envíe varios ID en una sola solicitud:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Vincule la respuesta con el pedido interno por el ID externo, no por la posición del elemento en el array. Desventaja de la consulta por lotes: el proveedor puede no devolver todos los pedidos, limitar el tamaño de la lista o informar un error solo para un ID.

Cómo programar el polling para processing

Tras la primera respuesta processing, ponga la siguiente consulta en cola. Elija el intervalo según la documentación de la API, los límites de frecuencia y la naturaleza del servicio. Para tareas en las que el estado cambia rápidamente, es admisible una consulta más frecuente al principio. Para la promoción gradual, las solicitudes cortas constantes normalmente no aportan nueva información.

Un esquema práctico es aumentar la pausa tras respuestas processing idénticas. La primera consulta se realiza tras un retraso inicial, luego el intervalo crece hasta un máximo establecido. Si la API devuelve progreso o una nueva hora de actualización, la cuenta puede iniciarse desde ese cambio.

• Tras crear el pedido, no consulte el estado inmediatamente muchas veces seguidas: el servicio puede necesitar tiempo para ponerlo en cola.
• Con processing repetido, aumente el intervalo entre solicitudes en lugar de mantener una frecuencia constante.
• Añada una pequeña desviación aleatoria a la hora de inicio de las tareas para que los pedidos no consulten la API al mismo tiempo.
• Si el proveedor envía Retry-After o una recomendación similar, úsela como prioritaria.
• Para pedidos con webhooks, mantenga un polling de control: la notificación puede no llegar.

La desventaja de un polling poco frecuente es que la interfaz puede mostrar un estado antiguo tras la finalización real. La desventaja de un polling demasiado frecuente es el riesgo de chocar con los límites de la API, recibir 429 y crear carga innecesaria.

Qué tiempos almacenar para controlar processing

Para distinguir una ejecución normal de un bloqueo, no basta con un solo estado actual. Para cada pedido activo almacene la hora de creación, la primera recepción de processing, la última respuesta exitosa de la API, el último cambio del estado externo y el último cambio de progreso.

También es útil guardar el volumen inicial, el volumen confirmado como ejecutado, el resto y el estado original del proveedor. Si la API no devuelve progreso, eso no es motivo para considerar el pedido bloqueado: oriente se por la hora de la última respuesta y el periodo de procesamiento esperado, si está indicado en las condiciones del servicio.

El tiempo máximo de espera no puede fijarse con un solo número para todos los servicios. Utilice el plazo que el proveedor indica para el servicio concreto, con un margen interno para la cola y la actualización de datos. Si el plazo no está indicado, establezca una regla aparte para cada categoría de servicios y revísela según el historial de procesamiento real.

Qué hacer si processing no cambia

Un processing prolongado no demuestra un error. Primero compruebe si llegaron respuestas exitosas de la API, si cambiaron completed_quantity o remains, si hubo webhooks y si cambiaron las reglas del servicio. La ausencia de crecimiento visible puede deberse al retraso de las estadísticas de la plataforma o a que el proveedor actualiza el progreso solo al final.

Cuando se supera el plazo interno de espera, no cancele el pedido automáticamente. Realice una consulta de estado extraordinaria, solicite los datos con un método aparte, si está previsto, y revise el historial de notificaciones. Si el proveedor sigue confirmando processing, pase el pedido a un estado interno de «requiere revisión», pero conserve el estado externo sin sustituirlo.

• Registre la hora de la última respuesta confirmada y toda la respuesta de la API.
• Compruebe si el progreso cambió desde la consulta anterior.
• Reduzca la frecuencia de las solicitudes automáticas tras alcanzar el umbral interno.
• Envíe a soporte el ID externo, el enlace, los parámetros del servicio, el historial de estados y los errores técnicos.
• No relance el resto hasta la respuesta del proveedor o un estado final explícito.

La desventaja de la revisión manual es que el pedido requiere la atención de soporte. Pero la cancelación automática o el duplicado son más peligrosos: la ejecución puede continuar en el proveedor.

Cómo separar un fallo de solicitud del estado del pedido

Un error de red, un tiempo de espera agotado, un HTTP 429 y una respuesta 5xx no informan del estado del propio pedido. Solo significan que no se pudo obtener un nuevo estado fiable. En tal situación, mantenga el último estado confirmado, registre el error técnico y programe una nueva consulta.

Con 429, tenga en cuenta Retry-After si se envía la cabecera. Con errores temporales de red y 5xx, aumente la pausa entre intentos. Con un error de autorización, firma o permisos de acceso, no haga reintentos frecuentes: hay que comprobar la clave, la vigencia del token, las restricciones por IP y la configuración de acceso.

Si la API devolvió HTTP 200, pero el JSON no se puede analizar o en la respuesta no hay order_id ni status, guarde el cuerpo de la respuesta completo y marque la consulta como incorrecta. No sustituya la ausencia de estado por completed, canceled o processing.

Cuándo detener las solicitudes automáticas repetidas

El polling no debe ser infinito. Limite el número de reintentos técnicos para errores temporales y controle por separado el plazo total en que el pedido permanece en processing. Tras agotar el límite de reintentos, pase la tarea de consulta a la cola de revisión, en lugar de crear nuevas solicitudes cada minuto sin resultado.

Repetir la solicitud de estado suele ser seguro si el método solo lee datos. Los métodos de creación, cancelación, recarga, reinicio y devolución no pueden repetirse mecánicamente tras un tiempo de espera agotado. Sin una clave idempotente o una confirmación explícita del proveedor, tal repetición puede modificar el pedido dos veces.

La desventaja de limitar los reintentos es que parte de las actualizaciones se convertirá en una tarea manual. Los reintentos infinitos son peores: enmascaran el fallo, consumen límites y complican el análisis de los registros.

Cómo aceptar el estado final tras processing

Evite la transición inversa de completed a processing por una respuesta tardía de polling o un webhook antiguo. En cada actualización, compare la hora del evento del proveedor, el número de versión si existe y el estado interno actual.

• new y pending pueden pasar a processing, canceled o failed.
• processing puede pasar a completed, partial, canceled o failed.
• partial no debe considerarse automáticamente como completed.
• completed, canceled y failed suelen considerarse finales y bloquean el retorno automático atrás.
• Un estado desconocido o una transición no permitida requieren una revisión aparte.

Una tabla de transiciones rígida también tiene una desventaja: el proveedor puede añadir un nuevo estado correcto. Por eso, conserve el estado original y no lo sobrescriba con la clasificación interna.

Cómo procesar partial y el resto del pedido

Partial significa que solo se ha confirmado una parte del volumen inicial. En la respuesta de la API puede haber la cantidad realmente ejecutada, el resto, el motivo y los datos sobre la compensación. Almacene estos valores por separado: el volumen inicial del pedido no puede sustituirse por la cantidad ejecutada.

Un ejemplo de respuesta final puede verse así:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Primero determine qué confirma exactamente la API: la devolución ya se realizó, la devolución solo está planificada, el resto se canceló o se requiere contactar con soporte. Si no hay campo sobre la devolución, no considere el resto compensado automáticamente.

No reinicie la parte no ejecutada sin una decisión aparte. El proveedor puede estar aún cerrando el cálculo, las estadísticas de la plataforma pueden actualizarse con retraso y una nueva solicitud puede crear una promoción duplicada. La desventaja de esperar la confirmación es que el resto no se cerrará al instante, pero no aparecerá un pedido adicional.

Los webhooks no sustituyen la consulta de control

El webhook permite actualizar la ficha del pedido inmediatamente después del evento, sin esperar al siguiente polling. En el manejador, encuentre el pedido por el ID externo, verifique la firma o el secreto, guarde el ID del evento y aplique la transición solo tras comprobar su validez.

La entrega repetida de un webhook debe ser segura: el mismo evento no puede considerarse un nuevo cambio. Los eventos también pueden llegar desordenados, así que no devuelva un pedido final atrás solo por un processing tardío.

El polling de control es necesario incluso con webhooks estables. La desventaja de los webhooks es una configuración más compleja: se requiere un manejador accesible, protección contra solicitudes falsas, deduplicación y un registro de eventos.

Qué mostrar al cliente durante processing y bloqueos

En la interfaz no hace falta mostrar todo el JSON técnico. Para processing basta con el estado «pedido en curso». Si la API transmitió un progreso fiable, muestre el volumen confirmado por separado del inicial y no lo presente como resultado definitivo.

Para un pedido que superó el plazo interno de control, use un estado comprensible como «estamos verificando la ejecución». No informe de cancelación, devolución o finalización completa hasta que lo confirme la respuesta del proveedor.

Las notificaciones son útiles al aceptar el pedido, en la ejecución final, en partial, en la cancelación, en el error y cuando se requiere revisión. Los mensajes tras cada polling generan ruido y no ayudan al cliente a entender el estado real de la solicitud.

Qué registros se necesitan en el log de procesamiento

El historial de respuestas ayuda a analizar un processing bloqueado, un webhook perdido, una disputa por ejecución parcial y una discrepancia entre la interfaz y la API. Para cada llamada guarde el ID externo, la fuente de la actualización, la hora de la solicitud y de la respuesta, el código HTTP, el estado original, el estado normalizado, el progreso, el resto y el texto del error técnico.

No escriba en los logs habituales claves de API, tokens, firmas y otros secretos. Limite el acceso a las respuestas en bruto: pueden contener datos que no deberían estar en la interfaz de soporte.

Antes del lanzamiento, compruebe los escenarios con processing repetido, ausencia de progreso, tiempo de espera agotado, 429, error 5xx, JSON incorrecto, webhook tardío, webhook duplicado, partial, canceled y estado desconocido. El modo de prueba es útil para la estructura de la integración, pero su desventaja es que puede no reproducir las colas y retrasos reales de la API de producción.