Skip to main content
InicioBlogGuíasTu primera solicitud a la API de seguimiento: guía paso a paso de un cliente REST con Postman y Curl

Tu primera solicitud a la API de seguimiento: guía paso a paso de un cliente REST con Postman y Curl

17TRACK

Para realizar tu primera solicitud a la API de seguimiento, configura el endpoint, el encabezado de autenticación y el cuerpo JSON en un cliente REST, envía la solicitud y revisa tanto el estado HTTP como el cuerpo de la respuesta. Este tutorial utiliza la Tracking API de 17TRACK para demostrar el mismo flujo de trabajo en Postman y curl: registrar un envío, solicitar su información de seguimiento y comprobar si el resultado está listo para que tu aplicación lo utilice.

Tu primera solicitud a la Tracking API: guía de un cliente REST

El objetivo es una pequeña prueba de integración reproducible, no un despliegue en producción. Necesitarás una credencial de API y un número de seguimiento que estés autorizado a procesar. Los comandos siguientes utilizan el patrón de endpoint v2.2; confirma la versión del endpoint y los requisitos específicos de tu cuenta en la documentación de la API de 17TRACK antes de ejecutarlos.

17TRACK API Global Shipment Tracking Solution — Conecta con más de 3.500 transportistas de todo el mundo mediante una sola API para realizar un seguimiento de paquetes fácil, preciso y fiable. Probar gratis →

Comprende lo que debe lograr tu primera solicitud

Una integración de seguimiento de envíos tiene dos objetivos distintos: indicar al servicio qué envío debe seguir y recuperar la información de seguimiento asociada a ese envío. En el flujo mostrado aquí, son solicitudes separadas. El registro no significa que el paquete ya se haya movido, y un registro exitoso no garantiza que los eventos del transportista estén disponibles de inmediato.

17TRACK Order Tracking — Mantén a los clientes informados sobre el estado de entrega y mejora la experiencia poscompra de marca DTC. Más información →

Para tu primera prueba, utiliza un solo envío en lugar de un lote. Esto facilita aislar los errores de autenticación, los números de seguimiento no válidos y la interpretación de las respuestas. Tu primer hito útil no es simplemente «recibí HTTP 200», sino «la API aceptó la operación prevista y puedo explicar el resultado a nivel de envío».

Postman ofrece una interfaz visual para editar solicitudes y revisar respuestas. curl hace reproducible el mismo intercambio HTTP desde un terminal. Ninguno cambia las reglas de autenticación, los datos del envío ni el comportamiento de procesamiento de la API. Utiliza el que te ayude a investigar la solicitud con mayor claridad y después reproduce la configuración funcional en la otra herramienta.

Prepara tus credenciales, el envío y los detalles de la solicitud

Antes de abrir cualquiera de los dos clientes, reúne lo siguiente:

  • Una credencial de API autorizada: obténla mediante la configuración de tu cuenta de API de 17TRACK. Una sesión de seguimiento para consumidores no sustituye a una credencial de API.
  • Un número de seguimiento real: utiliza un envío que te pertenezca o al que tengas permiso para acceder. Para probar datos de seguimiento reales, un envío activo recientemente suele ser más útil que un número inventado.
  • El transportista, si se conoce: conserva el nombre del transportista para facilitar el diagnóstico. Si tu caso requiere un identificador de transportista, utiliza el valor y el campo definidos en la documentación de la API en lugar de adivinarlos.
  • El contrato actual de la solicitud: confirma la versión de la API, el encabezado de autenticación, el esquema de la solicitud y cualquier restricción de la cuenta.
  • Un espacio de trabajo seguro: evita incluir credenciales, datos de clientes o respuestas completas de seguimiento en repositorios públicos, capturas de pantalla o mensajes de soporte compartidos.

Los ejemplos mínimos de solicitud utilizan esta configuración:

ConfiguraciónConfiguración de ejemplo
URL basehttps://api.17track.net/track/v2.2
Operación de registroPOST /register
Operación de información de seguimientoPOST /gettrackinfo
Encabezado de autenticación17token: YOUR_API_TOKEN
Formato del cuerpoContent-Type: application/json, con una matriz JSON de objetos de envío

Conserva los números de seguimiento como cadenas. Convertir uno a un tipo numérico puede eliminar los ceros iniciales o modificar su valor de otra forma. El marcador YOUR_TRACKING_NUMBER que aparece abajo debe sustituirse por tu envío de prueba real; no es un número de ejemplo funcional.

Realiza la solicitud de registro en Postman

1. Crea un entorno de prueba pequeño

En Postman, crea un entorno con tres variables: base_url, tracking_token y tracking_number. Configura base_url con la URL base anterior e introduce tus credenciales y el número de envío en las otras variables. Selecciona ese entorno antes de enviar la solicitud.

Utiliza los controles disponibles de Postman para gestionar secretos para el token y revisa qué comparte o sincroniza tu espacio de trabajo. Ocultar un valor en la interfaz no sustituye al control de quién puede acceder a él. No exportes credenciales rellenadas con una colección destinada a compañeros o a documentación pública.

2. Configura el método, la URL y los encabezados

Crea una solicitud HTTP, selecciona POST e introduce {{base_url}}/register como URL. En la pestaña Headers, añade:

17token: {{tracking_token}}
Content-Type: application/json

En este ejemplo, la credencial debe estar en el encabezado personalizado 17token. No lo sustituyas por una configuración de token Bearer solo porque otra API utilice ese patrón. Comprueba también si la configuración heredada de la colección introduce un encabezado Authorization no deseado.

3. Añade el cuerpo JSON

Abre Body, elige raw y selecciona JSON. Introduce:

[
  {
    "number": "{{tracking_number}}"
  }
]

Los corchetes exteriores son importantes: esta solicitud utiliza una matriz aunque solo contenga un envío. Usa comillas dobles, elimina las comas finales y no incluyas comentarios en el JSON. Si la documentación exige información adicional para tu transportista o envío, añade los campos documentados antes de enviarla.

4. Envía la solicitud y revisa el resultado

Haz clic en Send. Primero, comprueba si recibiste alguna respuesta HTTP. Un fallo de DNS, un error TLS, un problema de proxy o un tiempo de espera agotado son diferentes de una respuesta que indique que la solicitud no era válida. Después, revisa el cuerpo de la respuesta para consultar el resultado de la operación y cualquier información de aceptación o rechazo a nivel de envío.

Guarda la solicitud como «Register test shipment». Registra el estado HTTP, el resultado de la API y cualquier mensaje de error sin copiar el token. Si el registro falla, resuelve el problema antes de continuar. Enviar repetidamente una solicitud sin cambios dificulta el diagnóstico y puede consumir recursos de la cuenta.

Reproduce la solicitud con curl

Los comandos siguientes utilizan un shell de estilo POSIX, como Bash o Zsh. PowerShell y Windows Command Prompt tienen reglas diferentes para las comillas y las variables. En PowerShell, utiliza curl.exe cuando sea necesario para invocar el ejecutable de curl en lugar de un alias específico del shell.

Establece la URL base y carga tus credenciales en una variable de entorno mediante tu flujo habitual de gestión de secretos:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Una variable de entorno mantiene la credencial fuera del ejemplo reutilizable, pero no constituye un sistema completo de gestión de secretos. Para pruebas locales, evita escribir un token real en un comando que tu historial del shell vaya a conservar. Para la automatización, utiliza el almacén de secretos de tu plataforma y limita la salida de los registros.

Crea un archivo llamado shipment.json y sustituye el marcador por tu número de seguimiento de prueba:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Envía la solicitud de registro:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Esto guarda el cuerpo de la respuesta en register-response.json e imprime el estado HTTP por separado. Los tiempos de espera de conexión y total son opciones para pruebas locales, no garantías del servicio de 17TRACK. Abre el archivo guardado para revisar el resultado de la API; la línea de estado por sí sola no es suficiente.

curl puede completar una transferencia correctamente aunque el servidor devuelva una respuesta de error HTTP. Del mismo modo, un fallo de transporte puede impedir que llegue una respuesta utilizable de la API. Al crear scripts, trata por separado el estado de salida de curl, el estado HTTP y el resultado a nivel de aplicación.

17RETURNS — Simplifica las devoluciones y los cambios para reducir la carga de trabajo de soporte DTC y la pérdida de ingresos. Más información →

Solicita la información de seguimiento del envío

Después de confirmar el registro, duplica la solicitud de Postman y cambia la URL a {{base_url}}/gettrackinfo. Conserva el método POST, el encabezado de autenticación, el tipo de contenido y el cuerpo del envío. Guárdala por separado para no volver a registrar accidentalmente el envío cuando quieras recuperar datos.

La solicitud curl equivalente es:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

No supongas que un envío recién registrado devolverá inmediatamente un historial completo de eventos. La disponibilidad de datos depende del envío y del procesamiento del servicio. Si la información aún no está disponible, sigue las instrucciones documentadas de recuperación y actualización en lugar de registrar repetidamente el mismo número o ejecutar un bucle de consulta demasiado frecuente.

Lee la respuesta en tres capas

  1. Transporte: ¿el cliente se conectó y recibió una respuesta HTTP?
  2. Operación: ¿la API aceptó la solicitud y el envío individual se procesó correctamente?
  3. Información del envío: ¿los datos devueltos identifican el paquete previsto y qué establecen realmente su estado o historial de eventos?

Utiliza el esquema oficial de respuesta para localizar los campos de estado, transportista y eventos. Conserva la diferencia entre un estado de envío normalizado y la descripción original del evento del transportista. Una consulta exitosa no demuestra que se haya entregado el paquete, y la ausencia de eventos no demuestra que se haya perdido.

Al almacenar marcas de tiempo, conserva la información de zona horaria o desplazamiento proporcionada. Evita ordenar cadenas de fecha sin procesar de formatos diferentes y asumir que representan una secuencia cronológica correcta. Distingue también entre el momento en que tu aplicación recuperó un registro y el momento en que ocurrió el evento del envío.

Soluciona problemas sin cambiarlo todo a la vez

  • Sin respuesta: comprueba el nombre de host, el acceso a la red, la configuración del proxy, la configuración TLS y el tiempo de espera local. No desactives la verificación de certificados como solución habitual.
  • Fallo de autenticación: confirma que el token está activo, que el encabezado 17token está presente y que el entorno seleccionado de Postman resuelve correctamente la variable. Comprueba que no haya espacios en blanco accidentales.
  • Solicitud no válida: verifica la versión de la API, la ruta de la operación, el método POST, el tipo de contenido y la estructura de matriz JSON según la documentación.
  • Envío rechazado: lee el error específico del envío. Comprueba el número y cualquier información requerida del transportista en lugar de tratar cada rechazo como un problema de autenticación.
  • Sin eventos de seguimiento: confirma el registro y la identidad del envío previsto. Comprueba si se necesita información del transportista y si hay actualizaciones disponibles antes de volver a intentarlo.
  • Postman funciona pero curl falla: compara la URL resuelta, los encabezados reales y los bytes del cuerpo. Las comillas del shell y las variables de entorno no definidas son causas habituales de divergencia entre las solicitudes.

Cambia una variable por prueba y conserva un registro breve del resultado. Si inspeccionas la consola de Postman o utilizas la salida detallada de curl, trata esa información como sensible: los encabezados de solicitud pueden exponer credenciales. Oculta los secretos y la información de los clientes antes de compartir diagnósticos.

Determina cuándo se ha completado el tutorial

Has completado una primera prueba de integración significativa cuando ambos clientes envían la solicitud prevista, comprendes el registro, la recuperación devuelve un resultado interpretable y puedes distinguir un fallo de la API de un envío sin información nueva. Que los códigos de estado HTTP coincidan no demuestra por sí solo que ambos clientes se hayan comportado de forma idéntica.

Antes de trasladar el flujo a una aplicación, conserva las credenciales en el servidor, valida las entradas y utiliza una gestión estructurada de errores. Consulta los límites de velocidad, los límites de lotes, las instrucciones de reintento y las opciones de entrega de actualizaciones documentados para tu cuenta. No supongas que es seguro volver a intentar ciegamente el registro después de un tiempo de espera agotado: el servidor puede haber procesado la solicitud aunque tu cliente no recibiera la respuesta.

Añade pruebas para una credencial no válida, JSON mal formado, un número de envío no válido, un envío ya registrado, datos de seguimiento no disponibles y un tiempo de espera de red. Cada caso debe conducir a un resultado deliberado de la aplicación, no a una excepción no controlada ni a un estado engañoso mostrado al cliente.

Preguntas frecuentes

¿Puedo probarlo sin un número de seguimiento real?

Puedes probar parte del comportamiento de validación de solicitudes con un valor no válido, pero eso no verifica el seguimiento de envíos. Para probar eventos reales, utiliza un envío autorizado o un recurso de prueba documentado si el servicio ofrece uno. No supongas que los números de ejemplo arbitrarios pertenecen a un entorno sandbox.

¿Por qué una respuesta HTTP 200 todavía contiene un fallo?

El estado HTTP y los resultados de la aplicación describen capas diferentes. Un servidor puede recibir y procesar correctamente una solicitud mientras informa de que un envío individual ha sido rechazado. Lee el cuerpo de la respuesta y el resultado documentado a nivel de envío, no solo el estado HTTP.

¿Por qué se utiliza POST para recuperar información de seguimiento?

Utiliza el método especificado por el contrato del endpoint. Este ejemplo de recuperación acepta identificadores de envío en un cuerpo de solicitud JSON mediante POST. Cambiarlo a GET porque la operación lee datos no conserva la solicitud documentada.

¿Debo incluir el token de API en JavaScript del navegador?

No incrustes una credencial privada de API en código frontend entregado públicamente. Dirige las solicitudes a través de un backend autorizado que proteja la credencial, valide las entradas y controle a qué información de envíos puede acceder cada usuario.

¿Necesito Postman y curl para producción?

No. Son herramientas útiles de prueba y diagnóstico. Tu aplicación de producción puede utilizar un cliente HTTP apropiado. Conserva una solicitud de Postman o un comando curl depurado como referencia reproducible, sin un token activo ni datos innecesarios de clientes.

Fuentes