Skip to main content

Cargamos API Usage Guide

This tutorial aims to provide a simple initial integration process with the Cargamos service. This process is manual and not recommended for production integrations. The examples are provided using cURL.

Step 1: Registration​

The first step to deliver packages using the Cargamos service is to register. To do this, you need to fill out the form so that a representative from the Cargamos team can contact you as soon as possible to create your account and agree on operational and administrative terms.

An alternative, if administrative requirements have already been processed and you have an assigned account executive, is to send an email. For this example, we will request registration as a shipper by sending an email to integraciones@cargamos.com with the subject “REQUEST FOR REGISTRATION TO PERFORM INTEGRATIONS”.

Please send emails during Monday to Friday from 9 am to 5 pm Mexico City time.

Once the process is done internally by Cargamos, you should receive two emails:

  1. An email indicating that the shipper has been registered and providing a key
  2. An email requesting a password change. In case the link received in the email has expired, instructions on how to request a new one are shown in the Authorization section.
Info The key is the same for all users of the same shipper (organization).

Step 2: Request Access Tokens​

Once you have obtained the password and the key, proceed to obtain an access token.

First, we need to know the basic header that we need to use. Cargamos does not recommend the use of this online tool,, but as a guide, it is provided:

Basic header generator

Similarly, as an example, for the user john.doe@gmail.com with the password shipper, the resulting authentication header for basic is:

Authorization Basic am9obi5kb2VAZ21haWwuY29tOnNoaXBwZXI=

Finally, request an access token using the following command:

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

The response should resemble:

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

Where you can take the access token from the data.token. field.

Info:

If the access token expires during this tutorial, you can repeat this process to obtain a new one.

Step 3: Webhooks Configuration (Optional)​

This step is optional. If you have a URL to receive notifications, proceed by using the access token to register the URL (webhook) and the states of interest. In this example, the state is only 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

There are online tools available to test webhooks that can facilitate the process. Cargamos does not recommend any specific site, and it is the responsibility of the user to verify if it is appropriate to use them. An example of such online tools is https://webhook.site.

Info:

Refer to the API reference for the webhooks section if you need to manage this configuration. This example assumes that this is the first time a webhook is being registered.

Step 4: Integrate an Order​

Proceed to integrate an order. Note that this process will return a response with status 201, which implies that our request will be processed but is not a confirmation of the shipment creation, as this will be done asynchronously. However, if Step 3 was successful, we should receive a webhook of the transition to the CREATED state in the webhook. It is also possible to make a call to the shipment-tracking API to track the package and read the state of the shipment (which should be CREATED moments after integration).

The body of the order to be integrated is as follows:

{
  "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"
  }
}

The command to execute is:

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"}}'

You should receive a response similar to:

{
  "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"
  }
}
If the webhook is active with interests including "CREATED", this integration should have generated the following notification:
{
  "state": "CREATED", 
  "label_id": "DEMO00000008",
  "anomalies": null,
  "evidences": [], 
  "tracking_id":"INFPLJ8ED6SCW1H6W7RF", 
  "shipper_tracking_id": "DEMO00000008", 
  "timestamp": 1692658976035, 
  "lat": null, 
  "lng": null
  }

Step 5: Track the Shipment​

Finally, regardless of whether the webhook system has been configured, you can request the status of the shipment by using the following:

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

## Summary
Below is a summary of all the endpoints associated with this demo. The values for <code>key</code>, <code>basic</code> are provided as described in steps 1 and 2. The value for <code>access_token</code> is obtained from the response of the "Request an access token" endpoint. Note the use of IDs in the "Update a webhook", "Delete a webhook", and "Shipment-Tracking" endpoints.

| Environment   | Host                                    |
| -------------- | ---------------------------------------|
| Development	| https://dev.services.shippers.cargamos.com
| Production	| https://services.shippers.cargamos.com


```js
### 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}}