La integracion

Las “órdenes de entrega” son las solicitudes realizadas a Cargamos para efectuar un servicio de entrega. Dichas órdenes deben ser validadas teniendo en cuenta que el shipper esté autorizado para ser servido, la información suministrada sea suficiente para efectuar el servicio, que exista cobertura para la ubicación solicitada; y que el nivel de servicio solicitado (por medio de las fechas shipperDropoffDate y expectedDeliveryDate) pueda ser honrado bajo los tiempos, ubicaciones y condiciones del contrato firmado con Cargamos. Una vez esta orden de entrega es validada, se convierte en un shipment. Todo este proceso, desde que se provee la orden hasta que se valida y se genera el shipment en el sistema, sucede durante el denominado proceso de integración.

Cargamos provee varios mecanismos para integrar las órdenes. Entre estos se encuentran una API, proveer hojas de cálculo con la información solicitada y SDKs en varios lenguajes están siendo desarrollados y pronto estarán disponibles. Una vez los SDKs estén disponibles, estos no son más que wrappers sobre la API que facilitan el proceso de llamado de la misma. Por ende, la documentación presentada en esta y las siguientes secciones aplica a cualquier método de integración utilizado, ya que se deberá recolectar la misma información.

Al realizar la integración de una orden, los siguientes bloques de información deberán ser provistos:

Recipient Location
Recipient Information
Package Information
Service Level Parameters

1. Recipient Location: ubicación del destinatario. Incluye información utilizada para determinar si se tiene cobertura
2. Recipient Information: información básica del destinatario. Incluye información utilizada para contactar al destinatario en caso de que se presenten problemas para ubicarlo
3. Package Information: información del paquete. Incluye información de peso y dimensiones, así como información para Carta Porte .
4. Service Level Parameters: parámetros que describen la solicitud de nivel de servicio de la entrega. Incluye las fechas shipperDropoffDate y expectedDeliveryDate, así como Ids adicionales para identificar el paquete (i.e. shipperTrackingId). Nótese que estos Ids adicionales son opcionales.

El proceso se realiza de forma síncrona. Se compone de una solicitud y de su respectiva respuesta.

Fig. Proceso de integración

Resultados de la solicitud de integración

Una vez se realiza la integración, su respuesta puede ser positiva o negativa. Una respuesta positiva implica que se aceptó la solicitud de orden de servicio y se procederá a crear el shipment. Si se tiene configurado las notificaciones vía webhooks, se recibirá un mensaje indicando la transición hacia un estado de CREATED. Ejemplos de las respuestas se pueden observar en la sección de referencia de la API, pero en resumen se retorna una copia de la solicitud, con dos campos adicionales: trackingId y shipmentId.

El trackingId es un identificador que se espera se encuentre en el código de barras de la etiqueta del paquete. Nótese que es posible suministrar el trackingId deseado por medio del campo shipperTrackingId durante la solicitud de integración. Este campo también es el que debe de ser utilizado por medio del endpoint shipment-tracking para solicitar información del estado del shipment, e igual se proveerá vía webhook para identificar el shipment en cuestión.

El campo shipmentId es el identificador del recurso asignado dentro del sistema de Cargamos para identificar el shipment. Con la excepción del endpoint de endpoint shipment-tracking, el sistema puede identificar la información del paquete o tomar acciones con cualquiera de los campos, ya sea s trackingId o shipmentId.

Es posible de igual forma, que la respuesta del proceso de integración sea negativa. Esto sucede usualmente cuando se presenta algún error en el llamado, no se tiene cobertura, no se tiene autorización o cuando no se puede garantizar la entrega dentro de los parámetros del nivel de servicio solicitados.

Algunos ejemplos de una respuesta de error se muestra a continuación:

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

Nota

Nota: Otro tipo común de errores son de tipo CONFLICT, los cuales suelen suceder porque se esta proveyendo el mismo valor de shipperTrackingId el cual se espera sea único por shipper.