Integration

"Delivery orders" are requests made to Cargamos to perform a delivery service. These orders must be validated considering that the shipper is authorized to be served, the provided information is sufficient to carry out the service, there is coverage for the requested location, and that the requested service level (through the dates shipperDropoffDate and expectedDeliveryDate) can be honored within the times, locations, and conditions of the contract signed with Cargamos. Once this delivery order is validated, it becomes a shipment. This entire process, from when the order is provided to when it is validated and a shipment is generated in the system, occurs during the integration process.

Cargamos provides various mechanisms to integrate these orders. These include an API, providing spreadsheets with the requested information, and SDKs in various languages that are currently being developed and will soon be available. Once the SDKs are available, they are nothing more than wrappers over the API that facilitate the calling process. Therefore, the documentation presented in this and the following sections applies to any integration method used, as the same information will need to be collected.

When integrating an order, the following blocks of information must be provided:

Recipient Location
Recipient Information
Package Information
Service Level Parameters

1. Recipient Location: The recipient's location. Includes information used to determine if there is coverage.
2. Recipient Information: Basic information about the recipient. Includes information used to contact the recipient in case there are issues locating them.
3. Package Information: Details about the package. Includes weight and dimensions information, as well as details for the Carta Porte .
4. Service Level Parameters: Parameters describing the requested service level for the delivery. Includes dates such as shipperDropoffDate and expectedDeliveryDate, as well as additional IDs to identify the package (e.g., shipperTrackingId). Note that these additional IDs are optional.

The process is performed synchronously and consists of a request and its corresponding response.

Fig. Integration Process

Integration Request Results

Once the integration is performed, the response can be either positive or negative. A positive response implies that the service order request has been accepted, and the shipment will be created. If you have set up notifications via webhooks, you will receive a message indicating the transition to a CREATED state. Examples of the responses can be seen in the API reference section, but in summary, a copy of the request is returned with two additional fields: trackingId and shipmentId.

The trackingId is an identifier that is expected to be present in the barcode of the package label. Note that it's possible to provide the desired trackingId through the shipperTrackingId field during the integration request. This field should also be used through the shipment-tracking endpoint to request information about the shipment's status, and it will also be provided via webhook to identify the specific shipment.

The shipmentId field is the identifier assigned within the Cargamos system to identify the shipment. With the exception of the shipment-tracking endpoint, the system can identify package information or take actions using either the trackingId or shipmentId.

It's also possible for the integration process to yield a negative response. This typically happens when an error occurs in the call, there is no coverage, authorization is denied, or when delivery cannot be guaranteed within the parameters of the requested service level.

Some examples of error responses are shown below:

{
  "version": "1.0.0",
  "status": "BAD_REQUEST",
  "processId": "cbc35095-dd58-4289-ba87-57028819f3d8",
  "timestamp": 1692814516851,
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "A value provided as parameter is not valid for the request.",
      "details": "Value is not a valid enumeration member; permitted: 'mx', 'co', 'us', 'br'.",
      "location": "request.body",
      "parameter": "recipientLocation->country"
    }
  ]
}

{
    "version": "1.0.0",
    "status": "CONFLICT",
    "processId": "a3d6f39b-5332-4ca1-aa8f-425435e91e9d",
    "timestamp": 1692814595583,
    "errors": [
        {
            "code": "ALREADY_EXISTS",
            "message": "The resource you tried to create already exists.",
            "details": "The shipment you are trying to create, already exists. Integration lot id: 1. Time: 2023-07-18 21:11:29.332000",
            "location": "request.body",
            "parameter": "shipperTrackingId"
        }
    ]
}

{
    "version": "1.0.0",
    "status": "CONFLICT",
    "processId": "5e920127-71f7-49fc-a057-6c909a00e27e",
    "timestamp": 1692815077531,
    "errors": [
        {
            "code": "COVERAGE_FAILURE",
            "message": "Out of coverage.",
            "details": "There is no coverage for the given postalCode: 033002",
            "location": "request.body",
            "parameter":"recipientLocation.postalCode"
        }
    ]
}

Note

Note: Another common type of error is of type CONFLICT, which usually occurs when the same shipperTrackingId value is provided, which is expected to be unique per shipper.