CargOffer - API-Rest
Documentación del API de Cargoffer
Bienvenido
Sabemos que la documentación suele ser algo aburrido, tedioso, enrrevesado; y en general un lugar que nadie quiere visitar.
Así que, vamos a intentar que sea lo más agradable posible y lo más util para que pierdas el menor tiempo posible.
En Cargoffer vemos a todos los integradores como aliados y por lo tanto; parte de la familiar de Cargoffer. Por lo que si tienes una duda; avisanos y te ayudaremos en lo que podamos.
De la misma forma; todos somos humanos, y si ves algún error en la documentación; haznoslo saber, nos ayuda mucho a mejorar.
La documentación de Este API está hecha con cariño e intentado que sea comoda; así que, empecemos.
Índice
1. Introducción
Vamos a explicar en pocas palabras que es Cargoffer; nos definimos como MarketPlace Logistico Terrestre.
¿Que significa esto?
Simplificando; que somos un Software EndToEnd del proceso logistico terrestre. Esto engloba desde la parte de Bolsa de Carga hasta la validación de la entrega de la mercancía; pasando por la generacion documental, TMS y comunicación efectiva entre las partes.
Y Todo ello se puede hacer a través de la plataforma Cloud, o através de API. Si lo puedes hacer en Web, lopodrás integrar por API-Rest.
¿Como comunicarse?
Usamos un Standard como es API-Rest; y si necesitas ayuda al respecto, a lo mejor es necesario que busques algún tutorial o miniCurso sobre como comunicarte con un ApiRest: https://www.youtube.com/results?search_query=tutorial+ApiRest
Basicamente usaremos los siguientes protocolos:
- GET -> Listar y Recoger detalles de la información
- POST -> Crear información en la base de datos
- PUT -> Editar Información que exista previamente en la base de datos
- DELETE -> Borrar o desactivar información de la base de datos
¿Que Lenguajes Puedo usar?
Los ejemplos de las peticiones están en varios lenguajes; y en general cubren todo el espectro de los elenguajes más utilizados.
De todas formas; si el lenguaje que usas no están entre la lista, es más que probable que tu lenguaje tenga ejemplos de como hacer una petición Http a una URL; sigue esa información y cambia el protocolo y las cabeceras, queryParms, etc en cada caso.
Todas las peticiones son Http Standard; por lo que cualquier librería de conexión via Http te servirá. Nos hemos encargado de ello.
Flujo
Vamos a intentar definir el flujo normal de la plataforma y luego lo trasladamos al uso de la API.
La parte de Bolsa de Cargas comienza con la necesidad del cargador de publicar una subasta. Para que esta subasta se pueda producir hacen falta unos parametros configurados previamente.
- Metodo de pago
- Usamos Stripe para ello; es más comodo configurar esto a través de la plataforma (en el apartador de Configuración)
- Pero si prefieres usar el API; revisa la parte de Configuración
- Usamos Stripe para ello; es más comodo configurar esto a través de la plataforma (en el apartador de Configuración)
- Firma de Autorización
- Será usada para la firma de los documentos digitales; así como para el eCMR en representación del Cargador.
- Puede ser una firma manual en pantalla (en la plataforma) o usar una imagen de marca de agua.
- Tanto la imagen como la marca de agua será alojadas de forma segura y no serán accesibles hasta su uso en los documentos en los que sea estrictamente necesario.
- Al menos 2 direcciones diferentes (Origen/Destino)
- Como es Lógico es necesario tener un origen de la mercancía y un destino.
- En el API, hemos simplificado la inserción de las direcciones para evitar tener que enviar muchos campos. Si nos pasas la posición GPS, nosotros nos encargamos se sacar la información necesaria.
Cuando tenemos eso; podemos crear la necesidad de transporte. Esto es la especificación de cuando, donde y como tiene que entregarse una carga. Y si todo está OK y cumple las validaciones; se podrá publicar.
OJO: Solo se podrá publicar si cumple con todas las necesidades, pero se podrá guardar como borrador para continuar el proceso.
Tambien está disponible un .csv plantilla que podrás enviar con todos los servicios que quiers publicar; si te es más comodo.
Una Vez Publicada
Cuando una Subasta(Auction) está publicada; pueude estar en 2 estados posibles:
- Planning -> Cuando se ha publicado pero aún no ha comenzado el proceso de adminsión de pujas
- Published -> Cuando puede recibir pujas por parte de os transportistas.
(Si ha recibido al meos una puja y quieres aceptar el precio actual, sin tener que esperar a que termine la puja; echarle un ojo a la petición Aceptar Puja Actual)
2. Acceso al API
Hay varios tipos de Clave APi (apiKey).
Por un lado están las claves de Integrador; que tienen acceso a toda la parte de gestión, creación y administración de las compañias. Y tienen además, algunas peticiones exclusivas que están pmarcadas con el nombre de (Integrador) en el titulo.
Por otro lado; las cuentas de Cargador y Transportista; tienen una sección en Configuración ral respecto de los tipos que pueden tener, que son 3:
- Administracdor - Que ptiene control total sobre la cuenta. Esta con mucho cuidado.
- Gestión/Envíos - Para las tareas de día a dia; el resto de las peticiones estáran bloqueadas
- Finanzas/Facturación - Para la aprobación de as subastas, pago de facturas, etc.
Cuando se crea una clave APi; apuntala solo será visible una vez, el resto del tiempo solo será visible un fragmento; por seguridad.
Si has perdido la clave api; lo sentimos, tendrás que crear una nueva
2.1 - Autentificación
La autentificación de las peticiones se hace a través de un token generado dentro de la plataforma. A través de la interface web; dentro de las secciones: "Configuración" -> "ApiKeys"
Todas las peticiones tendrán como requisito obligatorio la incorporación de dicho apiKey; en caso de no suministrarlo, todas las peticiones al servidor serán rechazadas.
Esta clave apiKey será usada para identificarte en la plataforma; para registrar tu comportamiento en la misma, y para verificaciones de seguridad. En caso que notes un comportamiento extraño o inusual en la plataforma; recomendamos que borres la clave y generes una nueva.
Estas claves apiKey solo serán visibles en el momento de creación, por lo que deberás copiarla en un lugar seguro antes de cerrar la ventana.
Dentro de esta sección se creará el apiKey según el uso que se le vaya a dar. Para el caso; tenemos 3 posibles usos, y cada uno de ellos tendrá acceso a un tipo (o sección) de las peticiones:
- Admin -> Tendrás Acceso a todas las peticiones y secciones del ApiRest
- Envíos -> Tendrás Acceso solo a las peticiones que tengan que ver con los envíos
- Planificación (Borradores de Subasta)
- Creación de subastas
- Creación de Envios Privados
- Verificación de Estado de tus Envios
- Validación y Firmado de contrato de servicio (Entrega)
- etc.
- Entregas y Facturación -> Tendrás acceso a revisar el estado de las entregas, la exportación de la información y la facturación (pago) de los servicios que te han prestado los transportistas.
- Descarga de Facturas
- Revisión estado (y ETA) de las entregas
- Comunicación (Chat) con transportista
- Descarga de eCMR
- Exportación de Documentación del Servicio
- Visualización (y descarga) de las imagenes de prueba recogida/entrega
- etc.
3. Usos y Posibilidades
El uso del ApiRest con Cargoffer no está limitado; pero si que está monitorizado.
A su vez, está sujeto a un uso razonable de la plataforma; así como, una comunicación limitada a un numero de peticiones por minuto por usuario.
OJO: Decimos usuario; NO apiKey.
Por lo que en caso que una Compañia tenga un uso del API-Rest por encima de lo esperado, o se detecten posibles ataques de DDoS (o que puedan suponer un peligro a la estabilidad del servidor) serán directamente eliminadas de la base de datos; y se enviará una notificación a la persona responsable, comunicación una amonestación o limitación con el fin de garantizar el buen funcionamiento de la plataforma.
Se entiende como uso razonable de la plataforma; a las consultas de estado limitadas a 10 por minuto, y la creación/modificación de los datos a 4 por minuto.
En caso que los usuarios necesiten ampliar esta quota de servicio deberán comunicarlo por escrito.
4. Glosario
A continuación hablaremos de los terminos usados en la plataforma y a que serán referidos, así mismo; para que serán usados dentro de la plataforma Cargoffer.
4.1 Auction
Llamamos Auction (Envíos) a todos las subastas de Envíos; así que aquí tendrás las peticiones que tienen que con crear, listas, y editar las subastas de tus Cargas.
Estas podrán ser de caracter público; y recibir ofertas de los transportistas.
A la hora de crear estas subastas publicas se tendrá en cuenta el coste real del trayecto y gastos derivados del mismo; como pueden ser el coste de peajes, rodamientos, cambios de aceite, seguros, dietas (en caso de ser necesario, por horario), etc. Por lo que recibirás un error al respecto de ello en caso que no sea compatible con la principal linea roja de Cargoffer; un precio justo para todos.
Tenlo en cuenta cuando vayas a crear una subasta; pon el precio máximo que estás dispuesto a pagar, los transportistas pujarán a baja por tu servicio.
En el caso de los Envíos privados; será necesario que la cuenta sea Multitennant y tengas registradas en la plataforma los datos necesarios para tu gestión interna de los viajes: conductores, vehiculos y direcciones (recogida y entrega).
4.2 Delivery
Llamamos Delivery a las entregas. Estás entregas serán tanto las publicas como las privadas; y podrás recibir los datos del estado de cada uno de ellos.
En el detalle de cada Delivery (entrega) tendrás la información de los mensajes de comunicación con el transportista, los datos de contacto (telefono, email) y la documentación asociada a la entrega.
Por lo que en esta sección tendrás las peticiones que tienen que ver con este proceso; como puede ser ver el detalle, listar y filtras tu historico de entregas, etc.
4.3 Address
Para poder crear las Subastas/Auctions tienes que tener direcciones; en esta sección te ayudamos con las peticiones necesarias para gestionar las direcciones.
Las direcciones están registradas tanto en dirección fisica, como en posicionamiento GPS para evitar problemas a la hora de gestionar los Envíos. Así mismo; para poder hacer los calculos referentes a los gastos del transporte.
Ten en cuenta que te ayudamos poniendo un nombre a la dirección; para que te sea más facil reconocerlas en la selección cuando crees un Auction. Así como; un nombre de empresa y un telefono de contacto en caso de ser necesario para el transportista, o tu gestión interna.
4.4 Vehicles
Si tienes tu propia flota de transporte; esta es la sección que necesitas para poder gestionar todos tus vehiculos.
Tendrás acceso a la gestión de los vehiculos que podrán ser seleccionados para la creación de los Auction Privados. Por lo que serán seleccionables aquellos que sean compatibles con el servicio.
Ten en cuenta además; que te pediremos que la documentación de cada vehiculo esté al día, y te mandaremos recomendaciones sobre mantenimientos, renovaciones de documentación técnica y permisos de circulación (ITV).
En el proceso de alta y modificación (de la matricula) haremos una verificación de Marca/Modelo para revisar que los datos del vehiculo son correctos.
4.5 Conductores
Si tienes tu propia flota de transporte; esta es la sección que necesitas para poder gestionar todos tus conductores.
Tendrás acceso a la gestión de los conductores que podrán hacer los transportes de mercancía.
Tendremos en consideración los derechos de descanso, y que los conductores estén disponibles para cada viaje. Por lo que ten cuidado a la hora de intentar seleccionarlos para los Auction Privados; o recibirás un mensaje avisando sobre la incompatibilidad de los viajes.
5. Ejemplos de Uso
Aprende a través de ejemplos prácticos. Te proporcionaremos ejemplos de código para ayudarte a comprender cómo interactuar con nuestro API y cómo implementar funcionalidades específicas en tus aplicaciones.
6. Soporte y Comunidad
Queremos ayudarte en todo lo que necesites, y podamos ayudarte. Por lo que ponemos un correo a tu disposición para todas las dudas tecnicas que puedas tener:
info@cargoffer.comIntentaremos responderte lo antes posible; pero dependerá del numero de solicitudes que tenemos pendientes.
De la misma forma; en la plataforma tienes la sección de "Incidencias" para gestiones internas de la plataforma.
Authentication
- API Key: PROJECT
| Security Scheme Type: | apiKey |
|---|---|
| Header parameter name: | PROJECT |