Guía de uso API Cargamos

El presente tutorial tiene como propósito realizar una primera integración de la forma más sencilla posible. Este proceso será manual, y no es el mecanismo recomendado para integraciones en producción. Los ejemplos son provistos utilizando curl.

Paso 1: Registro

El primer paso para entregar paquetes haciendo uso del servicio de Cargamos es realizar el registro. Para hacer esto es necesario llenar el formulario para que un representante del equipo de Cargamos se ponga en contacto lo antes posible para crear tu cuenta y acordar términos operativos y administrativos.

Una alternativa si ya se tramitaron los requerimientos administrativos, y se tiene un ejecutivo de cuenta asignado, es enviarle un correo electrónico. Para este ejemplo solicitaremos el registro como shipper enviando un correo a integraciones@cargamos.com y el asunto “SOLICITUD DE REGISTRO PARA REALIZAR INTEGRACIONES”.

Nota:

Por favor enviar los correos en horario de lunes a viernes de 9am a 5pm horario Ciudad de México

Una vez se realice el proceso internamente por parte de Cargamos, se deberán de recibir dos correos electrónicos:

1. Correo indicando que el shipper fue dado de alta, y suministrando una key
2. Correo solicitando el cambio de contraseña. En caso tal de que el link recibido en el correo haya expirado, las instrucciones de cómo solicitar uno nuevo se muestran en la sección Autorización.

Info

Las key son las mismas para todos los usuarios del mismo shipper (organización).

Paso 2: Solicitud de tokens de acceso

Una vez se haya obtenido la contraseña y la key, se procede con la obtención de un token de acceso.

Primero necesitamos saber cual es el header basic que debemos de utilizar. Cargamos no recomienda el uso de esta herramienta en línea, pero como guía se suministra:

Basic header generator

De igual forma, como ejemplo, para el usuario john.doe@gmail.com con contraseña shipper, el header de autenticación resultante para basic es:

Authorization Basic am9obi5kb2VAZ21haWwuY29tOnNoaXBwZXI=

Finalmente, solicitamos un token de acceso por medio del siguiente comando

curl -d '{}'
-H "Content-Type: application/json"
-H "Authorization Basic am9obi5kb2VAZ21haWwuY29tOnNoaXBwZXI="
-X GET {host}/v1/login?key={key}

La respuesta debería de asemejarse a

{
  "version": "1.0.0",
  "status": "OK",
  "timestamp": 1675978304058,
  "data": {
    "token": "el_token",
    "expiresIn": "3600"
  }
}

de donde podemos tomar el token de acceso en el campo data.token.

Info:

En caso de que el token de acceso expire durante este tutorial, se puede repetir este flujo para obtener uno nuevo.

Paso 3: Configuración de los webhooks (Opcional)

Este paso es opcional. Si se tiene una URL en la cual se puedan recibir las notificaciones, procedemos, haciendo uso del token de acceso, registrando la URL (webhook) y los estados que son de interés. En este ejemplo el estado es únicamente CREATED.

curl -X POST --location "{host}/v1/webhooks?key={key}"
-H "Content-Type: application/json"
-H "Authorization: Bearer {access_token}"
-d "{\"interests\":[\"CREATED\"],\"targetAddress\": \"https://webhook.site/595e1811-9a4d-42a5-9ffb-ae907bf5a8a8\"}"

Info

Para probar webhooks existen herramientas en línea que pueden facilitar el proceso. Cargamos no recomienda ningún sitio en particular y es responsabilidad de quien lo use verificar si es apropiado usarlo. Un ejemplo de este tipo de herramientas online es https://webhook.site

Info:

Remitirse a la referencia de la API sección webhooks si se requiere administrar esta configuración. Este ejemplo asume que es la primera vez que se registra un webhook.

Paso 4: Integrar una orden

Se procede a realizar la integración de una órden. Nótese que este proceso regresará una respuesta con status 201, que implica que nuestra solicitud será procesada, pero no es propiamente una confirmación de la creación del shipment, ya que esto se realizará asíncronamente. Sin embargo, si el paso 3 se pudó realizar, debemos de obtener en el webhook la notificación de la transición al estado CREATED. También es posible realizar un llamado a la API de shipment-tracking para realizar el seguimiento del paquete y leer el estado del shipment (que debería de ser CREATED instantes después de la integración).

El cuerpo de la orden que se integrará es el siguiente:

{
  "recipientLocation": {
    "street": "Av. Popocatépetl",
    "number": "150d",
    "administrativeArea": "CDMX",
    "subAdministrativeArea": "Benito Juarez",
    "country": "MX",
    "neighborhood": "Portales Nte",
    "postalCode": "03300",
    "notes": "Dejar con el portero,",
    "reference": "Enfrente de Fuente de Cibeles"
  },
  "shipperTrackingId": "DEMO00000008",
  "shipperDropoffDate": "2023-06-10T16:18:05Z",
  "expectedDeliveryDate": "2023-06-11T16:18:05Z",
  "lotId": "1",
  "recipientInformation": {
    "fullName": "Pepe Cargamos",
    "phone": "5536012834"
  },
  "package": {
    "packageType": "UNIT",
    "description": "Caldera para sauna",
    "contentValue": 150.9,
    "valueCurrency": "MXN",
    "weight": 1,
    "weightUnit": "KG",
    "length": 1,
    "width": 1,
    "height": 1,
    "dimensionsUnit": "CM"
  }
}

El comando a ejecutar es:

curl --location -g --request POST '{host}/v1/shipments?key={key}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{"recipientLocation": {"street": "Av. Popocatépetl","number": "150d","administrativeArea": "CDMX","subAdministrativeArea": "Benito Juarez","country": "MX","neighborhood": "Portales Nte","postalCode": "03300","notes": "Dejar con el portero,","reference": "Enfrente de Fuente de Cibeles"},"shipperTrackingId": "DEMO00000008","shipperDropoffDate": "2023-06-10T16:18:05Z","expectedDeliveryDate": "2023-06-11T16:18:05Z","recipientInformation": {"fullName": "Pepe Cargamos","phone": "5536012834"},"package": {"packageType": "UNIT","description": "Caldera para sauna","contentValue": 150.9,"valueCurrency": "MXN","weight": 1,"weightUnit": "KG","length": 1,"width": 1,"height": 1,"dimensionsUnit": "CM"}}'

Se debería de recibir una respuesta similar a:

{
  "version": "1.0.0",
  "status": "CREATED",
  "processId": "a5a4d454-c8ad-42aa-95a5-30bcb257f1fb",
  "timestamp": 1676054548397,
  "data": {
    "recipientLocation": {
      "street": "Av. Popocatépetl",
      "number": "150d",
      "intNumber": null,
      "administrativeArea": "CDMX",
      "subAdministrativeArea": "Benito Juarez",
      "country": "MX",
      "neighborhood": "Portales Nte",
      "postalCode": "03300",
      "lat": null,
      "lng": null,
      "notes": "Dejar con el portero,",
      "reference": "Enfrente de Fuente de Cibeles"
    },
    "shipperTrackingId": "DEMO00000008",
    "shipperDropoffDate": "2023-06-10T16:18:05+00:00",
    "expectedDeliveryDate": "2023-06-11T16:18:05+00:00",
    "recipientInformation": {
      "fullName": "Pepe Cargamos",
      "phone": "5537012833",
      "email": null
    },
    "package": {
      "packageType": "UNIT",
      "description": "Caldera para sauna",
      "contentValue": 150,
      "valueCurrency": "MXN",
      "weight": 1,
      "weightUnit": "KG",
      "length": 1,
      "width": 1,
      "height": 1,
      "dimensionsUnit": "CM",
      "items": null
    },
    "dropoffLocation": {
      "street": "Calle Xochicalco",
      "administrativeArea": "Ciudad de México",
      "subAdministrativeArea": "Benito Juárez",
      "country": "MX",
      "neighborhood": "Piedad Narvarte",
      "neighborhoodType": "Suburb",
      "zipCode": "03000",
      "lat": 19.403051,
      "lng": -99.153442,
      "number": "14",
      "intNumber": null,
      "reference": "Parque Delta",
      "observations": "POD Delta"
    },
    "trackingId": "INFPLJ8ED6SCW1H6W7RF",
    "shipmentId": "186b76e3-c29a-5d20-b79f-53ee6ab3b97c"
  }
}

Nota

Si el webhook se encuentra activo con interests incluyendo CREATED, esta integración debió generar la siguiente notificación

{
  "state": "CREATED", 
  "label_id": "DEMO00000008",
  "anomalies": null,
  "evidences": [], 
  "tracking_id":"INFPLJ8ED6SCW1H6W7RF", 
  "shipper_tracking_id": "DEMO00000008", 
  "timestamp": 1692658976035, 
  "lat": null, 
  "lng": null
  }

Paso 5: Realizar seguimiento del shipment

Finalmente, independientemente de si se configuró el sistema de webhooks, es posible solicitar el status del shipment por medio de:

curl -X GET --location "{host}/v1/shipment-tracking/{trackingId}?key={key}"
-H "Accept: application/json"
-H "Authorization: Bearer {access_token}"

Resumen

A continuación se resumen todos los endpoints asociados a este demo. Los valores para key, basic son proporcionados como se describieron en el paso 1 y 2. El valor para access_token se obtiene de la respuesta del endpoint “Request an access token”. Nótese el uso de los Ids en los endpoints de “Update a webhook”, “Delete a webhook” y “Shipment-Tracking”.

Ambiente	Host
Desarrollo	https://dev.services.shippers.cargamos.com
Producción	https://services.shippers.cargamos.com

### Request an access token

GET {{host}}/v1/login?key={{key}}
Accept: application/json
Authorization: Basic {{basic}}


### Webhooks list
GET {{host}}/v1/webhooks?key={{key}}
Accept: application/json
Authorization: Bearer {{access_token}}


### Create a webhook
POST {{host}}/v1/webhooks?key={{key}}
Content-Type: application/json
Authorization: Bearer {{access_token}}


{
 "interests": [
   "CREATED"
 ],
 "targetAddress": "https://webhook.site/595e1811-9a4d-42a5-9ffb-ae907bf5a8a8"
}


### Update a webhook
PATCH {{host}}/v1/webhooks/42165796-4010-483c-84b1-7f565e8d6f2f?key={{key}}
Content-Type: application/json
Authorization: Bearer {{access_token}}


{
 "interests": [
   "CREATED"
 ],
 "targetAddress": "https://webhook.site/595e1811-9a4d-42a5-9ffb-ae907bf5a8a8"
}


### Delete a webhook
DELETE {{host}}/v1/webhooks/42165796-4010-483c-84b1-7f565e8d6f2f?key={{key}}
Content-Type: application/json
Authorization: Bearer {{access_token}}


### Integrate an order
POST {{host}}/v1/shipments?key={{key}}
Content-Type: application/json
Authorization: Bearer {{access_token}}


{
 "recipientLocation": {
   "street": "Av. Popocatépetl",
   "number": "150d",
   "administrativeArea": "CDMX",
   "subAdministrativeArea": "Benito Juarez",
   "country": "MX",
   "neighborhood": "Portales Nte",
   "postalCode": "03300",
   "notes": "Dejar con el portero,",
   "reference": "Enfrente de Fuente de Cibeles"
 },
 "shipperTrackingId": "DEMO00000005",
 "shipperDropoffDate": "2023-06-10T16:18:05Z",
 "expectedDeliveryDate": "2023-06-11T16:18:05Z",
 "recipientInformation": {
   "fullName": "Pepe Cargamos",
   "phone": "5537012833"
 },
 "package": {
   "packageType": "UNIT",
   "description": "Caldera para sauna",
   "contentValue": 150.9,
   "valueCurrency": "MXN",
   "weight": 1,
   "weightUnit": "KG",
   "length": 1,
   "width": 1,
   "height": 1,
   "dimensionsUnit": "CM"
 }
}


### Shipment-Tracking
GET {{host}}/v1/shipment-tracking/N9MCAWV8B4MNHZ7O0DR4?key={{key}}
Accept: application/json
Authorization: Bearer {{access_token}}