API en EasyCargo (parte 2)
En esta segunda entrega, nos centraremos en mostrar ejemplos prácticos del uso de la API de EasyCargo. Utilizaremos el Cliente API y realizaremos pruebas a través de la herramienta en línea ReqBin, que permite establecer comunicación con un servidor web (WWW). Esto nos facilita acceder a datos relevantes directamente desde nuestra calculadora de cubicaje de contenedores EasyCargo.
Aunque probar la API en un entorno de demostración es útil, en situaciones reales es común integrarla mediante un plugin en Java o realizar llamadas en Javascript desde sistemas como SAP. En próximos artículos abordaremos más sobre este tema, junto con casos concretos de implementación de la API, además de cómo trabajar con la plataforma Make.
Ejemplo de autenticación en ReqBin
La imagen anterior muestra el Cliente API de EasyCargo. Para poder enviar cualquier solicitud al servidor, primero el cliente debe estar autorizado. Esto se logra con una solicitud:
POST https://go.easycargo3d.com/api/v1/authentication
Esta solicitud debe incluir el nombre de usuario y su clave API en el cuerpo del mensaje. A cambio, el servidor devolverá un token de autenticación que deberá usarse en las siguientes solicitudes (a menos que se indique lo contrario) agregándolo en el encabezado.
Todas las interacciones a través de la API se ejecutan en nombre del usuario titular del token. El formato esperado para solicitudes y respuestas es JSON o XML.
Operaciones con cargas a través de la API
Una vez autenticados, pasamos a uno de los usos más relevantes de la API: gestionar los cargamentos. Imaginemos que el usuario «A» tiene las siguientes cargas guardadas en su cuenta de EasyCargo:
Con estas cargas practicaremos cómo estructurar solicitudes API. Si bien nos enfocamos en los cargamentos, otras funcionalidades —como la administración de usuarios— siguen un patrón similar. Por ello, cualquier lector con conocimientos básicos podrá desarrollar solicitudes adicionales sin inconvenientes.
La documentación oficial de la API de EasyCargo ofrece explicaciones detalladas de cada método disponible.
¿Qué se puede hacer con la API?
A través de solicitudes bien construidas es posible:
- Crear una nueva carga
- Eliminar una carga existente.
- Listar las cargas disponibles en una cuenta.
- Obtener detalles específicos sobre una carga concreta de la cuenta EasyCargo.
Cómo crear nuevos cargamentos vía API
Ejemplo de solicitud:
Generar una nueva carga directamente desde la API.
Una vez enviada la solicitud correctamente, la carga queda guardada en la cuenta. Además, puede abrirse desde la aplicación EasyCargo para su visualización o edición.
Proceso para eliminar una carga de EasyCargo
Ejemplo de solicitud:
Eliminar una carga existente en la cuenta de EasyCargo.
Al ejecutar correctamente esta operación, la carga será eliminada de manera definitiva.
Obtener lista de todas las cargas
Ejemplo de solicitud:
Obtener una lista completa de cargas disponibles en la cuenta EasyCargo.
Obtener detalles específicos de una carga
Ejemplo de solicitud:
Extraer información concreta sobre una carga específica.
Detalles técnicos adicionales
- Límite de solicitudes: La API permite realizar hasta 60 solicitudes por hora. Este límite se aplica en una ventana de tiempo móvil, por lo que el recuento se renueva de forma progresiva.
- Manejo de errores: Las respuestas de error siguen los códigos de estado HTTP estándar, e incluyen, mayoritariamente, un mensaje específico que indica la causa del fallo.
- Limitaciones: No es posible ejecutar cálculos de planificación de carga directamente desde la API. Para ello, el usuario debe iniciar sesión en la aplicación web de EasyCargo.
- Requisitos del cliente API: Debe permitir acceder y modificar encabezados, así como procesar datos en formato JSON o XML.
Parámetros opcionales
Algunos métodos de la API permiten incluir parámetros opcionales, como «from». Su significado se explica en la documentación oficial. Estos pueden utilizarse para filtrar los resultados. Por ejemplo, para obtener una lista de cargas creadas a partir de una fecha específica, se puede usar la siguiente URL:
https://go.easycargo3d.com/api/v1/shipments?from=2020-01-02&offset=0&limit=100
Este ejemplo contiene parámetros opcionales que permiten filtrar los resultados. Los parámetros se agregan después del signo de interrogación «?» en la dirección web. Si hay más de un parámetro, se separan con el símbolo «&», y cada uno sigue la estructura nombre=valor (también llamada name=value en inglés).
En este caso:
- from=2020-01-02 → indica que queremos ver solo las cargas creadas a partir del 2 de enero de 2020.
- offset=0 → establece que los resultados comienzan desde el primer registro (sin saltarse ninguno).
- limit=100 → limita la respuesta a un máximo de 100 cargas.
Este tipo de parámetros permite personalizar las consultas y obtener solo la información relevante que necesitas.
Cada uno de estos parámetros (como from, offset, limit) está descrito en la documentación y permite adaptar las solicitudes según las necesidades del usuario.
Como puedes ver, la API es un servicio de gran utilidad. Esta guía pretende servir como punto de partida para quienes deseen integrar EasyCargo en sus flujos de trabajo.
El artículo de hoy es el segundo de una serie dedicada a la API de EasyCargo. Si aún no has leído la primera parte, puedes hacerlo aquí. En la próxima entrega, exploraremos casos reales de implementación y beneficios concretos de automatizar tareas mediante nuestra interfaz de programación.
