CargOffer - API-Rest
Documentación del API de Cargoffer
Bienvenido
Sabemos que la documentación suele ser algo aburrido, tedioso, enrevesado; 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
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
Para que tengas una idea general de como funciona, te vamos a dejar este video donde se ve el proceso de creación de un e-CMR en la partet web, pero tranquil@ todo lo que se puede hacer por la intetrface (O casi todo) se puede hacer por API:
¿Que necesitamos?
Para poder crear un e-CMR Necesitamos algunos datos previamente creados:
- Dirección Origen (@Address)
- Dirección Destino (@Address)
- Pasarela de Pago Configurada (Stripe)
- Explicamos en la sección Pasarela como configurarla
- Cuenta Activa
- Validado el Correo Contacto
- Cuenta Strip Activa
- Aceptados Terminos y Condiciones
Explicación del Flujo
El flujo de creación tiene una cuenta origen; que puede ser un Cargador o un TruckerCia (Transportista), esta será la cuenta a la que se contabilizará la creación del eCMR y a quien se le cobrará. A partir de ese momento empieza el relleno de la información necesaria para el documento, y la vinculación con la otra parte.
A nivel general; el flujo es el mismo, si empieza un Cargador o un Transportista, la diferencia viene por la vinculación de las cuentas.
Flujo - Cargador Origen
- Cuando el Cargador crea el eCMR; debe rellenar el Origen/Destino (Address), poner los datos de fechas y tipo de mercancía según corresponda.
- Cuando está creado; se puede lanzar un correo al transportista; y empezar la vinculación.
- El transportista recibe un correo con el código ServiceCode; y el vinculo de enlace.
- El transportista debe asignar un conductor y un vehiculo al eCMR.
- (Optional) Se pueden subir documentos opcionales para el servicio.
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.
OJO:Solo hay un tipo de ApiKey y tendrá acceso a la gestión de toda la plataforma.
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.
Las limitaciones vendrán por el tipo de cuenta y factores relacionados con el modelo de negocio; como pueden ser facturas pendientes o limitaciones tecnicas por el volumen de peticiones. En caso que nos veamos limitados para cubrir la demanda de otros clientes por un uso abusivo, podremos limitar el uso de las peticiones de tu cuenta; pero te avisaremos.
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 a info@cargoffer.com
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.
Algunos de los terminos expuestos aquí corresponden con la plataforma general; te los ponemos igual, para que los tengas en mente si aparecen en alguna petición o son mencionados en las descripciones de los objetos.
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).
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.
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.
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.
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.
4. Stripe
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 |