Skip to main content
InicioBlogGuíasProbar una integración de la API de seguimiento en desarrollo: entorno de pruebas, números de prueba y webhooks simulados

Probar una integración de la API de seguimiento en desarrollo: entorno de pruebas, números de prueba y webhooks simulados

17TRACK

Para probar una integración de una API de seguimiento en desarrollo, utiliza tres métodos complementarios: un sandbox del proveedor o números de prueba documentados para comprobar el comportamiento de la API, fixtures locales para escenarios de envíos repetibles y webhooks simulados para tu endpoint receptor. Después, realiza una comprobación controlada en producción para validar las partes que las simulaciones no pueden demostrar, incluidas las credenciales, la configuración de la suscripción y la entrega real de eventos.

Prueba de una integración de una API de seguimiento en un sandbox de desarrollo y con números de prueba

Esta guía está dirigida a desarrolladores que conectan el seguimiento de envíos con una plataforma de comercio electrónico, un sistema de gestión de pedidos, un ERP o un servicio de notificaciones para clientes. El objetivo no es simplemente recibir una respuesta correcta de la API. Es demostrar que las actualizaciones de seguimiento producen el estado correcto del pedido sin mensajes duplicados, eventos perdidos ni contacto accidental con clientes reales.

Separa el comportamiento del proveedor del comportamiento de la aplicación

Una integración de seguimiento tiene al menos dos límites: las solicitudes que tu aplicación envía al proveedor y las actualizaciones que tu aplicación recibe o recupera posteriormente. Una solicitud correcta en el primer límite no demuestra que el segundo funcione.

Diseña el plan de pruebas en torno a esos límites, en lugar de esperar que un único número de seguimiento de prueba ejercite todo el sistema.

Método de pruebaQué puede validarQué no puede demostrar por sí solo
Sandbox del proveedorFormatos de solicitud compatibles, autenticación y comportamiento simulado descrito por el proveedorDisponibilidad de datos de transportistas en producción o comportamiento de entrega en producción
Números de prueba documentadosLos escenarios específicos asignados a esos númerosOtros estados, transportistas o secuencias de webhooks
Fixtures locales y mocks de APITu analizador, reglas de mapeo, persistencia y gestión de erroresSi el proveedor real acepta solicitudes o emite el mismo payload
Solicitudes de webhook simuladasGestión del endpoint, validación, deduplicación y efectos posterioresConfiguración de callbacks del proveedor o reintentos de entrega reales
Prueba controlada en producciónConectividad real y el flujo de envío observadoCada error poco frecuente, excepción o secuencia de entrega

Enfoque recomendado: haz que las pruebas locales sean deterministas, utiliza las pruebas compatibles con el proveedor cuando estén disponibles y reserva los envíos reales para confirmar la conexión entre sistemas.

Confirma el contrato del proveedor antes de crear fixtures

Empieza por la documentación oficial de la versión de la API que pretendes utilizar. Confirma la URL base, el método de autenticación, los requisitos de registro, el esquema de respuesta, la configuración de webhooks y cualquier recurso de prueba documentado. No deduzcas que existe un sandbox independiente solo porque el proveedor ofrece una API.

Para una integración con 17TRACK, utiliza la página de la API de seguimiento de 17TRACK y la documentación oficial de la API como puntos de partida. Verifica allí las especificaciones aplicables de solicitudes y callbacks antes de crear ejemplos específicos del proveedor. Los ejemplos siguientes son fixtures propiedad de la aplicación, no representaciones del esquema de la API de 17TRACK.

Resuelve estas preguntas antes de conectar el código de desarrollo con una cuenta externa:

  • ¿Las credenciales de desarrollo y producción son independientes y a qué entorno da acceso cada credencial?
  • ¿El sandbox admite callbacks o solo pruebas de solicitud-respuesta?
  • ¿Hay números de prueba documentados y qué resultados exactos producen?
  • ¿Los registros u otras solicitudes de prueba pueden consumir cuota de la cuenta o crear registros persistentes?
  • ¿Qué reglas documentadas existen para la autenticación de callbacks, confirmaciones, tiempos de espera y reintentos?
  • ¿Qué identificadores conectan un registro de seguimiento, un envío, un transportista y un evento de callback?

Si el comportamiento de las pruebas no está documentado con claridad, pide al proveedor que lo confirme. Mientras tanto, continúa probando tu propia lógica de procesamiento con mocks. Una capacidad del sandbox no confirmada es una incertidumbre de planificación, no una prueba de que el proveedor carezca de ella.

Crea un entorno de desarrollo aislado

Utiliza una base de datos independiente o un tenant aislado, secretos separados y pedidos sintéticos. Dirige los correos electrónicos, mensajes SMS y otras notificaciones a destinos de prueba o a un receptor de notificaciones. Un envío marcado como entregado en un fixture no debe activar un mensaje para un comprador real.

Añade un marcador de entorno explícito a los registros internos y logs. Mantén las credenciales del proveedor en el servidor, fuera del control de versiones, y oculta los secretos en las capturas de solicitudes. Si se necesita acceso público temporal para callbacks, expón únicamente la ruta de desarrollo prevista y conserva sus controles de autenticación.

Crea un pequeño conjunto de pedidos conocidos antes de enviar eventos. Incluye dos envíos asociados a un pedido y, si tu aplicación lo admite, la misma cadena de número de seguimiento con diferentes contextos de transportista. Estos casos revelan suposiciones según las cuales un número de seguimiento por sí solo siempre identifica un registro empresarial único.

Define de antemano el efecto esperado de cada prueba: el estado del envío, la asociación con el pedido, las entradas de la línea temporal, el número de notificaciones y el registro de auditoría. Esto convierte una demostración en una afirmación que puede aprobarse o fallar.

Utiliza los números de prueba únicamente para el propósito documentado

Un número de seguimiento tiene dos funciones de prueba distintas. Puede ser una entrada para validar el registro y puede identificar un envío que produce eventos de seguimiento. Un número que supera la validación de formato no necesariamente proporciona un historial de eventos útil.

Cuando hay números de prueba oficiales disponibles

Registra el escenario indicado por el proveedor junto a cada número. No debe suponerse que un número documentado para un envío entregado simula una excepción, una devolución o un intento de entrega fallido. Comprueba también si su resultado es fijo, cambia con el tiempo o requiere seleccionar un transportista concreto.

Mantén estos números en una configuración específica para pruebas de integración. No los disperses por las pruebas unitarias, donde los cambios en el comportamiento externo podrían hacer que pruebas que de otro modo serían deterministas dejaran de ser fiables.

Cuando no se han confirmado números de prueba oficiales

Utiliza identificadores sintéticos dentro de tu propia aplicación y simula el límite del proveedor. Nunca inventes un número de aspecto plausible suponiendo que está reservado para pruebas: podría coincidir con un envío real.

Para la validación en producción, utiliza envíos que controles y a los que estés autorizado a acceder. Evita copiar números de seguimiento de capturas públicas o conversaciones con clientes. Trata los historiales de envíos como potencialmente sensibles porque pueden contener ubicaciones, marcas de tiempo e información de entrega.

Un envío antiguo entregado puede ayudar a validar el análisis, pero es una dependencia deficiente para la integración continua. La disponibilidad de datos históricos y la respuesta externa pueden cambiar. Conserva un fixture anonimizado para pruebas repetibles y mantén separada la comprobación en producción.

Crea fixtures en torno a transiciones significativas del envío

Crea fixtures a partir del esquema documentado y, cuando estén disponibles, de respuestas reales anonimizadas. Mantén separados los payloads del proveedor de tu modelo interno de eventos normalizados. Prueba el adaptador entre ambos para que un mock interno no oculte un analizador del proveedor defectuoso.

Un conjunto inicial útil cubre estos escenarios:

  • Aún no hay eventos de seguimiento: conserva el envío sin afirmar que está en movimiento o entregado.
  • En tránsito: actualiza la línea temporal y conserva la asociación correcta con el pedido.
  • En reparto: aplica tu política de notificaciones sin tratar la entrega como completada.
  • Entregado: registra la finalización y ejecuta la acción empresarial prevista una sola vez.
  • Excepción o intento de entrega: conserva la distinción respecto de una entrega completada.
  • Movimiento de devolución: evita interpretar cada escaneo posterior como progreso hacia el destinatario original.
  • Estado desconocido: conserva suficiente información para el diagnóstico sin inventar un mapeo de estados.

Utiliza tus propios nombres normalizados para estos escenarios y asigna explícitamente a ellos los valores documentados del proveedor. No supongas que distintas API utilizan las mismas etiquetas de estado ni que una etiqueta tiene el mismo significado empresarial en todas partes.

Varía también la estructura de los datos: una lista de eventos vacía, campos opcionales ausentes, campos desconocidos adicionales, nombres de ubicaciones Unicode, marcas de tiempo con desplazamientos de zona horaria y valores obligatorios malformados. Tu analizador debe tolerar adiciones compatibles y rechazar los datos que no puedan procesarse de forma segura.

Envía webhooks simulados a través de la ruta receptora real

Un webhook simulado debe ejercitar la ruta receptora, el middleware de autenticación, la validación, el almacenamiento y el procesamiento por workers, no limitarse a llamar a la función final de actualización del estado.

El siguiente payload representa un evento interno sintético. Los nombres de los campos, el ID del evento y el estado son ilustrativos; no constituyen un contrato de callback del proveedor.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Guárdalo como tracking-event.json y publícalo en un receptor de pruebas local:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Este comando valida únicamente el enrutamiento y la gestión locales. No demuestra la autenticación del proveedor. Mantén una ruta exclusiva de desarrollo inaccesible en producción o prueba el receptor de producción utilizando el método de autenticación documentado por el proveedor y un secreto de prueba independiente.

Prueba la autenticación sin debilitar los controles de producción

Si el proveedor especifica callbacks firmados, implementa exactamente ese método en lugar de elegir un encabezado de firma o algoritmo arbitrario. En los métodos que firman los bytes de la solicitud, conserva el cuerpo original para la verificación; analizar y volver a serializar JSON puede cambiar esos bytes.

Prueba la autenticación válida, la ausencia de credenciales, los cuerpos manipulados y las firmas incorrectas cuando corresponda. Si el método documentado incluye marcas de tiempo o protección contra repeticiones, prueba también esas reglas. HMAC es una construcción estandarizada de autenticación de mensajes, pero su existencia no demuestra que un proveedor de seguimiento concreto la utilice.

Prueba duplicados, orden y recuperación

El procesamiento de envíos debe seguir siendo correcto cuando la misma actualización llega repetidamente o los eventos llegan en un orden inesperado. Estos son escenarios de prueba defensivos, no afirmaciones sobre la garantía de entrega de un proveedor concreto.

PruebaComportamiento esperado de la aplicación
Envía el mismo evento dos vecesConservar un único evento lógico y evitar notificaciones duplicadas a clientes.
Envía un escaneo de tránsito antiguo después de la entregaConservar el historial útil sin revertir automáticamente el estado de entregado.
Envía actualizaciones simultáneasAplicar transiciones de estado coherentes pese a los workers concurrentes.
Detén el procesamiento después de una recepción duraderaRecuperar y procesar el evento almacenado sin requerir un nuevo callback.
Falla el almacenamiento antes de que la recepción sea duraderaNo confirmar falsamente una aceptación correcta.
Envía un envío desconocidoSeguir una política definida de cuarentena o rechazo; nunca adivinar la asociación con el pedido.

Da preferencia a un identificador de evento estable y documentado para la deduplicación cuando se proporcione. De lo contrario, define una identidad cuidadosamente delimitada a partir de los campos relevantes y prueba las colisiones. Un número de seguimiento por sí solo no es una identidad de evento porque un envío puede generar muchas actualizaciones legítimas.

Separa el historial de eventos de la proyección actual del envío. Conservar los escaneos históricos no obliga a permitir que cada escaneo recibido tarde sobrescriba el estado mostrado. Tampoco es suficiente la regla de “utilizar la marca de tiempo más reciente”: las correcciones, los flujos de devolución y los distintos significados de las marcas de tiempo requieren una gestión explícita.

En el procesamiento asíncrono, confirma únicamente después de que el evento alcance un punto de transferencia duradero, como un registro de entrada confirmado o una cola duradera, según tu arquitectura. Sigue los requisitos documentados de confirmación del proveedor. HTTP define la semántica de los códigos de estado, pero el calendario de reintentos de un remitente concreto debe proceder de su propio contrato.

Realiza una comprobación controlada en producción y define los criterios de lanzamiento

Una vez superadas las pruebas deterministas, registra un envío autorizado mediante la integración real y confirma la ruta completa. Comprueba que el proveedor aceptó el registro previsto, que la configuración del callback apunta al entorno correcto y que los datos entrantes se asignan al envío esperado.

No exijas que todos los estados del envío aparezcan durante esa comprobación en producción. Los envíos reales no son fixtures controlables. Utiliza la ejecución real para validar la conectividad y la compatibilidad observada con el contrato; utiliza fixtures reproducibles para cubrir escenarios poco frecuentes o destructivos.

Antes del lanzamiento, exige los siguientes resultados:

  • Se gestionan las respuestas documentadas de éxito y error, incluidos los fallos por elemento si la API admite operaciones por lotes.
  • Los tiempos de espera no activan reintentos ciegos de creación cuando la primera solicitud ya podría haber tenido éxito.
  • Los eventos duplicados no pueden crear acciones empresariales duplicadas.
  • Los callbacks no válidos no pueden cambiar el estado del envío.
  • Los fallos de los workers dejan eventos recuperables en lugar de perderlos silenciosamente.
  • El tráfico de desarrollo no puede notificar a clientes reales ni modificar pedidos de producción.
  • Los logs conectan solicitudes, eventos recibidos, resultados de procesamiento e intentos de notificación sin exponer secretos.

Una versión está lista cuando puedes explicar tanto el flujo normal como la forma en que el sistema se recupera tras una solicitud incierta, un callback repetido o un worker interrumpido. Una única consulta de seguimiento correcta no es suficiente.

Preguntas frecuentes

¿Puedo probar una integración de seguimiento sin un sandbox?

Sí. Simula el límite de la API saliente, reproduce fixtures de callbacks documentados y prueba localmente tu normalización y tus reglas empresariales. Después utiliza un envío autorizado en producción para confirmar la conectividad real. Esto proporciona una cobertura considerable, pero no reproduce el comportamiento no documentado del proveedor.

¿Por qué mi solicitud de seguimiento tiene éxito, pero no devuelve eventos?

La aceptación de la solicitud y la disponibilidad de datos de seguimiento son resultados diferentes. Comprueba los detalles de la respuesta del proveedor, los requisitos de registro, las reglas de identificación del transportista y el comportamiento documentado para envíos sin eventos. No fabriques información de movimiento o entrega para rellenar una línea temporal vacía.

¿Un webhook simulado correcto demuestra que llegarán los webhooks reales?

No. Solo demuestra la ruta ejercitada por el mock. La entrega real también depende de la configuración del proveedor, la accesibilidad pública, TLS, la autenticación y el contrato real del callback. Valida estos aspectos con una entrega de prueba compatible con el proveedor o con un flujo real autorizado.

¿Debo devolver HTTP 200 antes de que termine el procesamiento?

Sigue el contrato documentado de confirmación del proveedor. En un diseño asíncrono, confirma después de la aceptación duradera y procesa después en un worker. Devolver éxito antes de la aceptación duradera puede provocar la pérdida de un evento si el proceso falla inmediatamente después.

¿Cómo debo probar las notificaciones a clientes?

Envía todas las notificaciones de desarrollo a un receptor controlado. Comprueba el destino, la plantilla, la transición que las activa y el número de envíos. Reproduce el mismo evento y simula reintentos del worker para verificar que una actualización de envío no genere mensajes repetidos a los clientes.

Fuentes