Cómo configurar notificaciones de finalización de pedidos API

Qué eventos deben considerarse finalización del pedido

Primero determine qué estado en la API significa la finalización real del pedido. Según el proveedor, puede ser un pedido completado, entregado, cancelado, rechazado, devuelto o parcialmente completado. No vincule la automatización solo a la palabra «éxito»: el pedido puede pasar por varios estados intermedios y luego detenerse por un límite, una verificación o una cancelación.

No solo hay que procesar el resultado positivo. Si el servicio envía una notificación de error, cancelación, devolución o ejecución parcial, también debe registrarse en el sistema interno. De lo contrario, en el panel, el CRM o el bot el pedido quedará en espera, aunque su ejecución posterior ya no vaya a producirse.

Elabore una tabla de correspondencia de estados

No transfiera el estado de la API a la interfaz sin procesarlo. Los nombres y la lógica del proveedor pueden cambiar, y un mismo estado interno a veces agrupa varios externos. Guarde el valor original por separado: será útil para analizar errores y contrastar con la documentación.

• pending, created, queued — pedido nuevo o pendiente de procesamiento.
• processing, in_progress, running — el pedido se está ejecutando.
• completed, delivered, success — pedido completado.
• partial, partially_completed — pedido parcialmente completado.
• cancelled, rejected, failed — pedido cancelado o finalizado con error.
• refunded, returned — el pedido requiere devolución o ajuste.
• Estado desconocido — no cambia la ficha automáticamente y se envía a revisión.

Los nombres anteriores se ofrecen como ejemplo de esquema. La tabla final debe construirse según los estados de la API concreta. La desventaja del mapeo manual es que hay que mantenerlo tras una actualización de la API: un nuevo estado puede llegar al controlador antes de que exista una regla para él.

Elija webhooks, sondeo de la API o ambos esquemas

Un webhook es una solicitud del servicio a su URL cuando cambia el estado del pedido. El sondeo de la API funciona al contrario: su sistema consulta la información del pedido a intervalos. Para las notificaciones de finalización suelen ser más cómodos los webhooks, porque la actualización llega sin solicitudes constantes al método de comprobación de estado.

• Los webhooks son adecuados para reaccionar rápido: actualizar la ficha, iniciar la siguiente etapa o enviar un mensaje al responsable.
• El sondeo es adecuado si el proveedor no admite notificaciones callback o el servidor no acepta solicitudes externas.
• El esquema combinado usa webhooks como canal principal y el sondeo para buscar pedidos perdidos o bloqueados.

La desventaja del sondeo es la latencia y la carga adicional sobre la API. La desventaja de los webhooks es que hay que proteger el endpoint, tener en cuenta los duplicados y no depender del orden de entrega de los eventos.

Configure el endpoint para recibir eventos

Para las notificaciones se necesita una dirección HTTPS pública accesible desde el servicio API. En la configuración de la integración normalmente se indica la URL del controlador, el secreto de firma y la lista de eventos: cambio de estado, finalización, cancelación, error o ejecución parcial.

Asigne una ruta separada solo para eventos de API. Así es más fácil configurar el registro, restringir el acceso, establecer límites de solicitudes y no mezclar el tráfico de servicio con los formularios del sitio. No use la dirección del entorno de pruebas para pedidos reales: tras actualizar el entorno, el proveedor seguirá enviando eventos a la URL guardada.

Antes de lanzar, compruebe el método de solicitud y el formato del cuerpo según la documentación. Lo más habitual es POST con JSON, pero hay form-data, parámetros de query o un esquema propio de serialización. El error de análisis debe registrarse en el log; de lo contrario, será difícil distinguir un payload incorrecto de un fallo de la aplicación.

Mantenga la relación entre el pedido y el evento

Al crear un pedido mediante la API, guarde el identificador que devolvió el proveedor. Junto a él, guarde el número interno del pedido, el tipo de servicio, el estado original, la hora del último cambio y la respuesta original de la API de forma segura. Vincule el webhook entrante por el ID del proveedor, no por el enlace al canal, el nombre del servicio o el nombre del cliente.

Si la API permite enviar un identificador externo al crear el pedido, añada su número de pedido en un campo como external_id o client_reference. Esto facilita la búsqueda en los logs y el análisis de situaciones controvertidas. Pero no haga del número externo la única clave: algunos proveedores no lo devuelven en cada notificación.

No cree un nuevo pedido a partir de un ID desconocido del webhook. El evento desconocido debe guardarse en el log y comprobarse por separado. La creación automática de un registro puede provocar datos erróneos o el procesamiento de una solicitud falsificada.

Utilice una estructura de payload comprensible

Los nombres exactos de los campos dependen de la API. Lo siguiente no es el contrato de un servicio concreto, sino un ejemplo de evento JSON en el que puede basarse al diseñar el controlador interno. Son importantes el identificador del evento, el ID del pedido en el proveedor, el estado, la hora del cambio y los datos para el diagnóstico.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

No use la cantidad de unidades completadas como indicio de finalización sin el estado. El pedido puede haberse completado parcialmente, y la cifra del payload puede estar redondeada, actualizada con retraso o no haberse enviado en absoluto. La desventaja de guardar el cuerpo completo del evento es que puede contener datos personales o campos internos, por lo que esos registros deben enmascararse y limitarse en plazo de conservación.

Verifique la firma sobre el cuerpo original de la solicitud

La URL abierta del controlador puede recibir una solicitud no solo del servicio API. Si el proveedor envía una firma, un secreto o un token, verifíquelos antes de modificar el pedido. Un esquema habitual es HMAC-SHA256: el proveedor calcula la firma a partir de los bytes del cuerpo de la solicitud y un secreto compartido, y luego envía el resultado en una cabecera HTTP.

El principio de cálculo es el siguiente: se toma el cuerpo original de la solicitud, por ejemplo los bytes JSON sin cambios, y el secreto de la integración. Después se calcula HMAC-SHA256. Si el resultado en hexadecimal coincide con el valor de la cabecera, el cuerpo no cambió después de la firma y la solicitud probablemente la envió una parte que conoce el secreto.

Ejemplo condicional: HMAC_SHA256(secreto, raw_body) = firma de la cabecera X-Signature. El nombre de la cabecera, el algoritmo y el formato del resultado deben tomarse solo de la documentación de la API. Algunos servicios añaden una marca de tiempo o el ID del evento a la cadena de firma. En ese caso no se puede verificar solo el cuerpo JSON.

No modifique el JSON antes de verificar la firma

La firma se verifica sobre los bytes originales de la solicitud, no sobre el objeto JSON que la aplicación ya analizó y volvió a construir. Al volver a serializar pueden cambiar el orden de los campos, los espacios, el escapado de caracteres, el salto de línea o la codificación. Para una persona el JSON seguirá siendo el mismo, pero el conjunto de bytes cambiará y el HMAC ya no coincidirá.

Para evitarlo, primero obtenga el raw body como bytes o buffer, guárdelo en memoria, calcule la firma y solo tras una verificación correcta analice el JSON. No aplique al cuerpo trim, conversión de codificación, ordenación de claves ni formateo. En el middleware del framework compruebe si el JSON se analiza automáticamente antes de acceder al cuerpo original.

La desventaja de este esquema es que el controlador pasa a depender del orden del middleware. Con una configuración incorrecta, la aplicación solo verá el objeto transformado y las notificaciones legítimas empezarán a rechazarse.

Ejemplo de controlador con verificación HMAC

A continuación, un ejemplo condicional en Python. Muestra el orden de las acciones, no una integración lista: las cabeceras, el algoritmo, el formato de la firma y los campos del payload deben sustituirse por los valores de la documentación del proveedor.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Para la comparación use una función que no se detenga en el primer carácter que no coincida. Esto reduce el riesgo de filtración de datos sobre la firma a través del tiempo de respuesta. No envíe el secreto al código del cliente, no lo añada a la URL y no lo registre completo en los logs.

Haga idempotente el procesamiento de eventos

El proveedor puede entregar el mismo evento varias veces. Las causas son habituales: su servidor tardó en responder, la conexión se interrumpió después de guardar los datos, el endpoint devolvió temporalmente un error o el servicio inició un reenvío según sus propias reglas. Un reenvío no significa que la API haya creado un nuevo pedido.

La idempotencia significa que un mismo evento cambia el resultado solo una vez. Si no se tiene en cuenta esta regla, el duplicado volverá a enviar un mensaje al cliente, creará varias tareas para el gestor, abonará una compensación o iniciará una operación repetida.

Lo mejor es usar el event_id del payload. Guárdelo en una tabla separada o en un registro de eventos procesados con una restricción única. Si no hay un ID separado, forme la clave con campos estables: ID del pedido del proveedor, tipo de evento, estado y hora del cambio. Esta variante es peor: con marcas de tiempo imprecisas, eventos distintos pueden parecer iguales.

Guarde el evento y el estado en una sola operación

La comprobación de «si el evento ya se procesó» y el registro del resultado deben ejecutarse de forma atómica. De lo contrario, dos solicitudes idénticas que lleguen al mismo tiempo verán ambas la ausencia de registro e iniciarán la acción dos veces. Una opción práctica es un índice único por event_id y una transacción de base de datos.

La continuación condicional del controlador es así:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

La desventaja de responder con un código exitoso para un pedido desconocido es que el proveedor puede no repetir la entrega. Por eso los eventos desconocidos deben monitorizarse por separado y analizarse con rapidez. Si la documentación de la API recomienda otro código de respuesta para estos casos, sígala.

Tenga en cuenta la alteración del orden de los eventos

Los webhooks no siempre llegan estrictamente según la hora de cambio del estado. Primero puede llegar un evento de finalización y después una notificación retrasada del estado «en curso». Si simplemente se registra el último valor recibido, el pedido completado volverá a estar activo.

Defina transiciones permitidas. Por ejemplo, un estado intermedio no puede sobrescribir el final, y un pedido cancelado no pasa a completado sin una comprobación aparte. Si la API permite corregir el estado final, guarde el motivo, el valor original y la fuente del cambio.

Si el payload contiene la hora de cambio del pedido, compare precisamente esa, no la hora de recepción del webhook. Cuando la API no envía esa marca, use prioridades de estados y verificación mediante el método de obtención del pedido. La desventaja de las prioridades es que no sustituyen la secuencia real, sobre todo si el proveedor permite la devolución desde un estado final.

Confirme la entrega rápidamente y saque las acciones a una cola

No realice operaciones largas antes de responder al proveedor. La verificación de la firma, la búsqueda del pedido, el registro del evento y la actualización del estado normalmente pueden completarse rápido. El envío de un mensaje, la sincronización con el CRM, la generación de un informe o las solicitudes a sistemas de terceros es mejor pasarlos a una cola de tareas.

El orden de trabajo es el siguiente: verificar la firma, guardar de forma atómica el evento y el cambio de estado, devolver una respuesta exitosa y luego ejecutar las acciones secundarias. Si responde antes de guardar, los datos se perderán en caso de fallo. Si responde después de un envío largo de la notificación, el proveedor puede considerar la entrega fallida y enviar un duplicado.

La desventaja de la cola es que aparece un componente separado que hay que controlar: errores de tareas, retrasos y ejecuciones repetidas. Pero un fallo en la notificación al gestor no bloquea la recepción de los estados de los pedidos.

Configure notificaciones para el equipo y el cliente

Tras el cambio de estado no hay que notificar a todos por igual. Al gestor normalmente le importan las cancelaciones, los errores, la ejecución parcial y los pedidos que no cambian durante mucho tiempo. Al cliente suele bastarle un resultado claro: el pedido se completó, se canceló o requiere aclaración.

• Pedido completado — actualización en el área personal o mensaje breve al cliente.
• Error de ejecución — notificación al responsable con el motivo que envió la API.
• Ejecución parcial — tarea para revisar el ajuste, la devolución o la siguiente acción.
• Estado desconocido — registro en el log y mensaje al especialista técnico.
• ID de pedido desconocido — comprobación separada del vínculo entre su sistema y el proveedor.

No envíe un mensaje en cada transición técnica. El feed se convertirá rápidamente en ruido y un problema importante pasará desapercibido. La notificación interna debe contener el número de pedido, el servicio, el estado actual, el ID externo y un enlace a la ficha.

Lleve un registro y verifique los pedidos no finalizados

Los logs son necesarios para entender si el servicio envió un evento, qué cuerpo llegó, por qué no pasó la firma y en qué etapa se detuvo el procesamiento. Guarde la hora de recepción, el ID del evento, el ID del pedido, el tipo de evento, el resultado de la verificación de la firma, el estado interno y el código de respuesta. Enmascare secretos, tokens y datos personales.

Supervise por separado los errores de entrega, las firmas no válidas, los pedidos desconocidos, los estados no admitidos, los duplicados y los eventos que no pueden aplicarse por el orden de los estados. El aumento de estos registros puede indicar un cambio en el esquema de la API, un secreto caducado, un fallo de la ruta o un error en la lógica del controlador.

Verifique periódicamente los pedidos en estados intermedios mediante el método de obtención de datos de la API. Esta comprobación no sustituye a los webhooks, pero ayuda a detectar un evento perdido, un fallo de la cola o un caso en el que el estado externo cambió sin una notificación correcta.