VTEX Pick and Pack Carriers Integration Protocol

Logistics

VTEX Pick and Pack VTEX Pick and Pack Carrriers Integration Protocol

Learn how to integrate carriers with VTEX Pick and Pack API Protocol

All API access is over HTTPS and accessed from https://api.pickingnpacking.com. All data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

All timestamps returned in UTC, ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ.

All distance measurements are in meters.

Basic authentication

API key available:


_10**xxx**

Steps to generate JWT

Create a token of authentication with service token.
When making each request listed below, include an Authorization header with the JWT generated in step 1, as shown below:


_10// Headers
_10{
_10  "Authorization": "JWT"
_10}

Service endpoints

Endpoint URLs

Endpoints are configurable when creating the carrier configuration.

Create service

This is the information that VTEX will send to the carrier to create a service.

URL: Carrier configuration
Method: Carrier configuration
Headers: Carrier configuration
Query: Carrier configuration

Schema


_99{
_99  orderId: String!
_99  carrierId: String!
_99  seller: String!
_99  sender: {
_99    name: String
_99    phone: String
_99    email: String
_99    city: String!
_99    state: String!
_99    country: String!
_99    address: String!
_99    neighborhood: String
_99    number: String
_99    reference: String
_99    addressComplement: String
_99    location: {
_99      latitude: Float
_99      longitude: Float
_99    }
_99    pickupDate: AWSDateTime!
_99    deliveryWindow: {
_99      name: String
_99      initialDate: AWSDateTime
_99      finalDate: AWSDateTime
_99    }
_99    zipCode: String!
_99  }!
_99  receiver: {
_99    name: String!
_99    phone: String
_99    email: String
_99    city: String!
_99    state: String!
_99    country: String!
_99    address: String!
_99    neighborhood: String
_99    number: String
_99    reference: String
_99    addressComplement: String
_99    location: {
_99      latitude: Float
_99      longitude: Float
_99    }
_99    identification: String
_99    deliveryDate: AWSDateTime! # UTC iso 8601
_99    deliveryWindow: {
_99        name: String
_99        initialDate: AWSDateTime
_99        finalDate: AWSDateTime
_99    },
_99    contactName: String
_99    zipCode: String!
_99  }!
_99  packages: [
_99    {
_99      id: String!
_99      orderId: String!
_99      envelope: String
_99      description: String
_99      categories: [String]
_99      dimensions: {
_99        width: String
_99        height: String
_99        length: String
_99      }
_99      weight: String
_99      totalValue: Float
_99      items: [
_99        {
_99          id: String!
_99          name: String!
_99          ean: String!
_99          refId: String
_99          image: String
_99          type: String
_99          price: Float!
_99          weight: String
_99          quantity: Int!
_99        }
_99      ]
_99    }
_99  ]
_99  type: PICKUP | DELIVERY | PICKUP_DELIVERY | RETURN!
_99  carrierServiceType: NATIONAL | INTERNATIONAL | EXPRESS | SPECIALIZED | OTHERS!
_99  comments: String
_99  paymentMethod: ONLINE | CASH_ON_DELIVERY | PIN_PAD!,
_99  settings: [
_99    {
_99      label: String
_99      value: String
_99      "key": String
_99    }
_99  ]
_99  timezone: {
_99    offset: Float!
_99    value: String!
_99  }!
_99}

Body Example


_103{
_103  "orderId": "SLR-29384924-01",
_103  "carrierId": "servientrega-50461c9f3335",
_103  "seller": "qaolimpica",
_103  "sender": {
_103    "name": "Tabitha Sears",
_103    "phone": "+57 2305781612",
_103    "email": "tabitha_sears@fortean.brother",
_103    "city": "Jenkinsville",
_103    "state": "Northern Mariana Islands",
_103    "country": "Brazil",
_103    "address": "77 Sullivan Place, Jenkinsville, Northern Mariana Islands",
_103    "addressComplement": "Labore sunt laboris reprehenderit nulla cupidatat irure labore sunt dolore est.",
_103    "number": "1029",
_103    "reference": "3",
_103    "location": {
_103      "latitude": -75.269008,
_103      "longitude": 137.499833
_103    },
_103    "pickupDate": "2022-04-25T18:06:41.202Z"
_103  },
_103  "receiver": {
_103    "name": "Pansy Graves",
_103    "phone": "+57 4240807147",
_103    "email": "pansy_graves@zentime.moda",
_103    "city": "Valle",
_103    "state": "Marshall Islands",
_103    "country": "Iceland",
_103    "neighborhood": "Billings",
_103    "number": "9840",
_103    "reference": "65C"
_103    "address": "63 Billings Place, Valle, Marshall Islands",
_103    "addressComplement": "In excepteur in Lorem id eu et id.",
_103    "location": {
_103      "latitude": -33.249891,
_103      "longitude": -135.052901
_103    },
_103    "identification": "9541933267",
_103    "deliveryDate": "2022-04-16T20:49:36.117Z",
_103    "contactName": "Savannah Porter",
_103    "deliveryWindow": {
_103        "name": "consectetur",
_103        "initialDate": "2022-04-25T22:50:41.209Z",
_103        "finalDate": "2022-05-05T21:50:41.210Z"
_103      }
_103  },
_103  "packages": [
_103    {
_103      "id": "6266df719ac55224b793ad36",
_103      "orderId": "SLR-1221800709659-01",
_103      "envelope": "Grande",
_103      "description": "Paquete delicado",
_103      "categories": ["Cellphone", "Technology"]
_103      "dimensions": {
_103        "width": "68",
_103        "height": "43",
_103        "length": "13"
_103      },
_103      "weight": "19",
_103      "totalValue": 5616.01,
_103      "items": [
_103        {
_103          "id": "6266df71a19ebe35637e1f42",
_103          "name": "Celular nokia AD1",
_103          "ean": "473390795673",
_103          "refId": "6266",
_103          "image": "https://static9.depositphotos.com/1628352/1107/i/600/depositphotos_11071361-stock-photo-tomato.jpg",
_103          "type": "Tech",
_103          "price": 774230.01,
_103          "weight": "4 kg",
_103          "quantity": 4
_103        },
_103        {
_103          "id": "6266df71803601c3bc4e2d99",
_103          "name": "Celular nokia AD2",
_103          "ean": "329949764612",
_103          "refId": "6266",
_103          "image": "https://static9.depositphotos.com/1628352/1107/i/600/depositphotos_11071361-stock-photo-tomato.jpg",
_103          "type": "Tech",
_103          "price": 23162,
_103          "weight": "14 kg",
_103          "quantity": 9
_103        }
_103      ]
_103    }
_103  ],
_103  "type": "PICKUP_DELIVERY",
_103  "carrierServiceType": "OTHERS",
_103  "comments": "Consectetur ex dolor adipisicing proident.",
_103  "paymentMethod": "CASH_ON_DELIVERY",
_103  "orderValue": 8000,
_103  "settings": [
_103    {
_103      "label": "Clave secreta",
_103      "value": "keysecret-0122",
_103      "key": "secrekey"
_103    }
_103  ],
_103  "timezone": {
_103    "offset": 300,
_103    "value": "America/Bogota"
_103  }
_103}

Expected response


_10{
_10 "status": "PENDING", // PENDING | ASSIGNED | PICKED | ON_ROUTE | INCIDENT | RETURNED | DELIVERED | CANCELED | ON_HOLD
_10 "serviceId": "ASDF23324KDSF2", // Id devuelto por la transportadora
_10 "shippingPrice": 20000.09 // If not exists send `null`
_10 "metaData": {}, // Carrier additional information for example: {"anyKey": "anyValue", "propertyCustom": "anyValue", "anyArray": ["anyValue"], "errorKeyExample": "Show error trace exampel"}, if not exists send `null`
_10 "shippingEstimatedDate": "2022-05-29T22:36:37.589Z" // If not exists send `null`
_10}

Status codes

HTTP Status Code	Description
200	Ok
401	Required authentication
400	Bad request
404	Resource not found
500	Internal error

There is a 5 seconds timeout before the service creation is confirmed. After that, it is possible to use any of the endpoints below.

Cancel service

In case a user or the application needs to cancel a service, this will be sent to the carrier's configured endpoints.

URL: Carrier config
Method: Carrier config
Headers: Carrier config
Query: Carrier config

Schema


_10{
_10  serviceId: String!
_10  carrierId: String!
_10  reason: String
_10}

Example


_10{
_10  "serviceId": "apknieot924892jaf-1231",
_10  "carrierId": "servientrega9234jaf",
_10  "reason": "La dirección de entrega esta mal registrada"
_10}

Response


_10{
_10  "message": "Service executed successfully",
_10  "data": {
_10    "serviceId": "apknieot924892jaf-1231",
_10    "carrierId": "servientrega9234jaf",
_10    "reason": "En el lugar de residencia no hay quien reciba el paquete"
_10  }
_10}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

Pause service

In case a user or the application needs to pause or resume a service, this will be sent to the carrier's configured endpoints.

URL: Carrier config
Method: Carrier config
Headers: Carrier config
Query: Carrier config

Schema


_10{
_10  serviceId: String!
_10  carrierId: String!
_10  pause: Boolean!
_10  reason: String
_10}

Example


_10{
_10  "serviceId": "apknieot924892jaf-1231",
_10  "carrierId": "servientrega9234jaf",
_10  "pause": false,
_10  "reason": "En el lugar de residencia no hay quien reciba el paquete"
_10}

Response


_10{
_10  "message": "Service executed successfully",
_10  "data": {
_10    "serviceId": "apknieot924892jaf-1231",
_10    "carrierId": "servientrega9234jaf",
_10    "cancel": true,
_10    "reason": "En el lugar de residencia no hay quien reciba el paquete"
_10  }
_10}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

Update shipping services

This endpoint will allow the carriers to update an ongoing shipping service.

Endpoint URL

REST API endpoints are prefixed with the following URL:

https://api.pickingnpacking.com/prod/v1

Get service

The following endpoint returns information about a service, which can be queried by providing the carrier ID and the corresponding service ID as query parameters. The response returned by the endpoint will contain the requested information.

GET: /tracking/hook/{carrierId}/{serviceId}
Authentication: API_KEY_PUBLIC

Schema


_137type ServiceResponseDto {
_137  id: ID!
_137  orderId: String!
_137  carrierId: String!
_137  serviceId: String # '{carrierId}&{serviceIdFromCarrier}'
_137  carrierLogo: String
_137  carrierName: String!
_137  seller: String!
_137  status: ServiceStatus!
_137  labels: [ServiceLabel]!
_137  trackingUrl: String
_137  comments: String
_137  evidences: [ServiceEvidence]!
_137  packages: [PackageService]!
_137  timeline: [TrackingTimeline]!
_137  type: ServiceType!
_137  notes: [ServiceNotes]!
_137  paymentMethod: String
_137  carrierServiceType: String
_137  shippingPrice: Float
_137  shippingEstimatedDate: AWSDateTime
_137  shippingFinishedDate: AWSDateTime
_137  metaData: AWSJSON
_137  timezone: CTimezone
_137  tags: [String]!
_137}
_137
_137enum ServiceStatus {
_137  CREATED
_137  PENDING
_137  ASSIGNED
_137  PICKED
_137  ON_ROUTE
_137  INCIDENT
_137  RETURNED
_137  DELIVERED
_137  CANCELED
_137  ON_HOLD
_137}
_137
_137type ServiceLabel {
_137  id: ID!
_137  url: String!
_137  name: String!
_137  type: ServiceLabelType!
_137}
_137
_137enum ServiceLabelType {
_137  PDF
_137  BASE64
_137  TEXT
_137  ZPL
_137}
_137
_137type ServiceEvidence {
_137  type: ServiceEvidenceType!
_137  content: String
_137  date: AWSDateTime!
_137  author: String
_137}
_137
_137enum ServiceEvidenceType {
_137  TEXT
_137  IMAGE
_137}
_137
_137type PackageService {
_137  id: ID!
_137  orderId: String!
_137  envelope: String
_137  dimensions: ServiceDimensionsPacking
_137  weight: String
_137  totalValue: Float
_137  items: [ServiceItemsPackage]!
_137  categories: [String]!
_137  description: String
_137}
_137
_137type ServiceDimensionsPacking {
_137  width: String
_137  height: String
_137  length: String
_137}
_137
_137type ServiceItemsPackage {
_137  id: ID!
_137  name: String!
_137  ean: String!
_137  refId: String
_137  image: String
_137  type: String
_137  price: Float!
_137  weight: String
_137  quantity: Int!
_137}
_137
_137type TrackingTimeline {
_137  id: ID!
_137  type: TrackingTimelineType!
_137  date: AWSDateTime!
_137  description: String
_137  author: String
_137  metaData: AWSJSON
_137}
_137
_137enum TrackingTimelineType {
_137  STATUS
_137  EVIDENCE
_137  NOTE
_137  LABEL
_137  OTHER
_137}
_137
_137enum ServiceType {
_137  PICKUP
_137  DELIVERY
_137  PICKUP_DELIVERY
_137  RETURN
_137}
_137
_137type ServiceNotes {
_137  type: ServiceNotesType!
_137  date: AWSDateTime!
_137  content: String!
_137  author: String
_137}
_137
_137enum ServiceNotesType {
_137  COMMENT
_137  ERROR
_137}
_137
_137type CTimezone {
_137  offset: Float # (-5, -3, ...)
_137  value: String # ("America/Bogota", ...)
_137  label: String
_137}

Response


_293{
_293  "message": "success",
_293  "data": {
_293    "id": "d9dc0d2c-5f49-4254-ad05-5551be273a2c",
_293    "orderId": "1313160501383-01",
_293    "carrierId": "627eb3b93a19fdc0cf5fe087",
_293    "serviceId": "627eb3b93a19fdc0cf5fe087&470083180050116775042433920287",
_293    "carrierName": "Blue Express",
_293    "seller": "exito96",
_293    "status": "DELIVERED",
_293    "type": "PICKUP_DELIVERY",
_293    "labels": [],
_293    "evidences": [
_293      {
_293        "type": "IMAGE",
_293        "date": "2023-02-27T13:25:08.538Z",
_293        "content": "https://tookan.s3.amazonaws.com/acknowledgement_images/1677504302764669967113822-470083180Signature.jpg",
_293        "author": "Juan C Testing P"
_293      },
_293      {
_293        "type": "IMAGE",
_293        "date": "2023-02-27T13:26:22.799Z",
_293        "content": "https://tookan.s3.amazonaws.com/acknowledgement_images/16775043776540952751646343-470083181Signature.jpg",
_293        "author": "Juan C Testing P"
_293      }
_293    ],
_293    "packages": [
_293      {
_293        "id": "1677504239859",
_293        "orderId": "1313160501383-01",
_293        "envelope": "Box",
_293        "dimensions": {
_293          "height": "2",
_293          "length": "2",
_293          "width": "2"
_293        },
_293        "weight": "2",
_293        "totalValue": 40000,
_293        "items": [
_293          {
_293            "id": "60",
_293            "name": "Neutrogena Hydro Boost Water Gel X 50 Gr",
_293            "ean": "EAN159",
_293            "quantity": 2,
_293            "price": 20000,
_293            "refId": "60",
_293            "image": "https://blueExpress.vteximg.com.br/arquivos/ids/155747-55-55/60.jpg?v=637917088184130000",
_293            "type": "PRODUCT",
_293            "weight": "1"
_293          },
_293          {
_293            "id": "59",
_293            "name": "Shampo Sin Sal + Mascarilla French Gold",
_293            "ean": "EAN158",
_293            "quantity": 2,
_293            "price": 20000,
_293            "refId": "59",
_293            "image": "https://blueExpress.vteximg.com.br/arquivos/ids/155746-55-55/59.jpg?v=637917087644630000",
_293            "type": "PRODUCT",
_293            "weight": "1"
_293          }
_293        ],
_293        "categories": ["Personal Care"],
_293        "description": "-"
_293      }
_293    ],
_293    "timeline": [
_293      {
_293        "id": "d8ecc1d7-52c9-4c1f-81ee-5524a66cc276",
_293        "date": "2023-02-27T13:25:09.749Z",
_293        "createdAt": "2023-02-27T13:25:09.749Z",
_293        "updatedAt": "2023-02-27T13:25:09.749Z",
_293        "type": "STATUS",
_293        "description": "Courier on route",
_293        "author": "System",
_293        "metaData": {
_293          "rating": 5,
_293          "totalDistanceTraveled": 0,
_293          "trackingUrl": "https://blueExpress.northlatam.com/tracking/index.html?jobID=41903e23c5157de2a3961c05cafc6e5b",
_293          "status": "ON_ROUTE"
_293        }
_293      },
_293      {
_293        "id": "27e6fe70-9a8e-4ca3-8454-d491bb1fe828",
_293        "date": "2023-02-27T13:26:22.809Z",
_293        "createdAt": "2023-02-27T13:26:22.809Z",
_293        "updatedAt": "2023-02-27T13:26:22.809Z",
_293        "type": "EVIDENCE",
_293        "description": "Added evidence",
_293        "author": "Juan C Testing P",
_293        "metaData": {
_293          "0": {
_293            "type": "IMAGE",
_293            "content": "https://tookan.s3.amazonaws.com/acknowledgement_images/16775043776540952751646343-470083181Signature.jpg",
_293            "author": "Juan C Testing P"
_293          }
_293        }
_293      },
_293      {
_293        "id": "3395c4b0-40fc-4681-8c13-f26119a1da16",
_293        "date": "2023-02-27T13:25:52.841Z",
_293        "createdAt": "2023-02-27T13:25:52.841Z",
_293        "updatedAt": "2023-02-27T13:25:52.841Z",
_293        "type": "STATUS",
_293        "description": "Courier on route",
_293        "author": "System",
_293        "metaData": {
_293          "rating": 5,
_293          "totalDistanceTraveled": 0,
_293          "trackingUrl": "https://blueExpress.northlatam.com/tracking/index.html?jobID=41903e23c5157de2a3961c05cafc6e5b",
_293          "status": "ON_ROUTE"
_293        }
_293      },
_293      {
_293        "id": "3d778bfa-dbd3-40de-a23e-03f6e1aa84ea",
_293        "date": "2023-02-27T13:24:45.684Z",
_293        "createdAt": "2023-02-27T13:24:45.684Z",
_293        "updatedAt": "2023-02-27T13:24:45.684Z",
_293        "type": "STATUS",
_293        "description": "Service pending",
_293        "author": "System",
_293        "metaData": {
_293          "rating": 5,
_293          "totalDistanceTraveled": 0,
_293          "trackingUrl": "https://blueExpress.northlatam.com/tracking/index.html?jobID=98cb758cc7049b956d13c15e67e5fd87",
_293          "status": "PENDING"
_293        }
_293      },
_293      {
_293        "id": "25b9dba7-4e65-4a10-b0b5-27f98997422a",
_293        "date": "2023-02-27T13:26:22.985Z",
_293        "createdAt": "2023-02-27T13:26:22.985Z",
_293        "updatedAt": "2023-02-27T13:26:22.985Z",
_293        "type": "NOTE",
_293        "description": "A new note has been added",
_293        "author": "Juan C Testing P",
_293        "metaData": {
_293          "0": {
_293            "type": "COMMENT",
_293            "note": "Entregado",
_293            "author": "Juan C Testing P"
_293          },
_293          "1": {
_293            "type": "COMMENT",
_293            "note": "Entregado a porteria",
_293            "author": "Juan C Testing P"
_293          }
_293        }
_293      },
_293      {
_293        "id": "a27af5ba-a765-4941-bde8-21f7795473cd",
_293        "date": "2023-02-27T13:24:03.496Z",
_293        "createdAt": "2023-02-27T13:24:03.496Z",
_293        "updatedAt": "2023-02-27T13:24:03.496Z",
_293        "type": "STATUS",
_293        "description": "Service creation",
_293        "author": "System",
_293        "metaData": null
_293      },
_293      {
_293        "id": "4cd358ff-c79b-421d-a0a1-bcdb70622886",
_293        "date": "2023-02-27T13:25:08.691Z",
_293        "createdAt": "2023-02-27T13:25:08.691Z",
_293        "updatedAt": "2023-02-27T13:25:08.691Z",
_293        "type": "NOTE",
_293        "description": "A new note has been added",
_293        "author": "Juan C Testing P",
_293        "metaData": {
_293          "0": {
_293            "type": "COMMENT",
_293            "note": "Recogido",
_293            "author": "Juan C Testing P"
_293          }
_293        }
_293      },
_293      {
_293        "id": "5c4137a5-c6db-479c-98ab-b40b9adc22dc",
_293        "date": "2023-02-27T13:25:08.547Z",
_293        "createdAt": "2023-02-27T13:25:08.547Z",
_293        "updatedAt": "2023-02-27T13:25:08.547Z",
_293        "type": "EVIDENCE",
_293        "description": "Added evidence",
_293        "author": "Juan C Testing P",
_293        "metaData": {
_293          "0": {
_293            "type": "IMAGE",
_293            "content": "https://tookan.s3.amazonaws.com/acknowledgement_images/1677504302764669967113822-470083180Signature.jpg",
_293            "author": "Juan C Testing P"
_293          }
_293        }
_293      },
_293      {
_293        "id": "912f2d4a-00d6-4ba0-a380-4bf0fa593d6e",
_293        "date": "2023-02-27T13:24:39.847Z",
_293        "createdAt": "2023-02-27T13:24:39.847Z",
_293        "updatedAt": "2023-02-27T13:24:39.847Z",
_293        "type": "STATUS",
_293        "description": "Assigned courier",
_293        "author": "System",
_293        "metaData": {
_293          "rating": 5,
_293          "totalDistanceTraveled": 0,
_293          "trackingUrl": "https://blueExpress.northlatam.com/tracking/index.html?jobID=98cb758cc7049b956d13c15e67e5fd87",
_293          "status": "ASSIGNED"
_293        }
_293      },
_293      {
_293        "id": "b44f7442-e7b5-4d87-8dc3-9c9ec480a269",
_293        "date": "2023-02-27T13:24:03.471Z",
_293        "createdAt": "2023-02-27T13:24:03.471Z",
_293        "updatedAt": "2023-02-27T13:24:03.471Z",
_293        "type": "STATUS",
_293        "description": "Service pending in PROD",
_293        "author": "System",
_293        "metaData": {
_293          "shippingEstimatedDate": null,
_293          "metaData": null,
_293          "serviceId": "470083180050116775042433920287",
_293          "shippingPrice": null,
_293          "status": "PENDING"
_293        }
_293      },
_293      {
_293        "id": "b992c08d-3b6c-4e95-9c87-9b41b82abc27",
_293        "date": "2023-02-27T13:25:07.834Z",
_293        "createdAt": "2023-02-27T13:25:07.834Z",
_293        "updatedAt": "2023-02-27T13:25:07.834Z",
_293        "type": "STATUS",
_293        "description": "Courier picked the package",
_293        "author": "System",
_293        "metaData": {
_293          "rating": 5,
_293          "totalDistanceTraveled": 0,
_293          "trackingUrl": "https://blueExpress.northlatam.com/tracking/index.html?jobID=98cb758cc7049b956d13c15e67e5fd87",
_293          "status": "PICKED"
_293        }
_293      },
_293      {
_293        "id": "23a4bd15-e33d-441c-a699-c0c20dda6a7a",
_293        "date": "2023-02-27T13:26:22.160Z",
_293        "createdAt": "2023-02-27T13:26:22.160Z",
_293        "updatedAt": "2023-02-27T13:26:22.160Z",
_293        "type": "STATUS",
_293        "description": "The package was delivered",
_293        "author": "System",
_293        "metaData": {
_293          "rating": 5,
_293          "totalDistanceTraveled": 0,
_293          "trackingUrl": "https://blueExpress.northlatam.com/tracking/index.html?jobID=41903e23c5157de2a3961c05cafc6e5b",
_293          "status": "DELIVERED"
_293        }
_293      }
_293    ],
_293    "notes": [
_293      {
_293        "type": "COMMENT",
_293        "date": "2023-02-27T13:25:08.682Z",
_293        "content": "Recogido",
_293        "author": "Juan C Testing P"
_293      },
_293      {
_293        "type": "COMMENT",
_293        "date": "2023-02-27T13:26:22.976Z",
_293        "content": "Entregado",
_293        "author": "Juan C Testing P"
_293      },
_293      {
_293        "type": "COMMENT",
_293        "date": "2023-02-27T13:26:22.976Z",
_293        "content": "Entregado a porteria",
_293        "author": "Juan C Testing P"
_293      }
_293    ],
_293    "timezone": {
_293      "offset": -300,
_293      "value": "America/Bogota",
_293      "label": null
_293    },
_293    "carrierLogo": "iVBORw0KGgoAAAANSUhEUgAAAhQAAAHICAYAAAAWbnMsA",
_293    "trackingUrl": "https://blueExpress.northlatam.com/tracking/index.html?jobID=41903e23c5157de2a3961c05cafc6e5b",
_293    "comments": "-",
_293    "paymentMethod": "ONLINE",
_293    "carrierServiceType": "EXPRESS",
_293    "shippingPrice": null,
_293    "shippingEstimatedDate": null,
_293    "shippingFinishedDate": null,
_293    "metaData": {
_293      "jobCapacityTest": true,
_293      "test": "This is field custom",
_293      "name": "Last Mile Test"
_293    }
_293  }
_293}

Update service (via webhook)

Service that allows updating the details of the tracking service via webhook.

PATCH: /tracking/hook/{carrierId}/{serviceId}
Authentication: API_KEY_PUBLIC

Parameters

Name	Type	In	Description
`carrierId`	string	path	Carrier ID
`serviceId`	string	path	Id generated by the service
`Authorization`	string	header	JWT generated with API KEY PUBLIC

Schema


_16{
_16  status: PENDING | ASSIGNED | PICKED | ON_ROUTE | INCIDENT | RETURNED | DELIVERED
_16  agent: {
_16    id: String!
_16    name: String!
_16    identification: String
_16    phone: String
_16    email: String
_16    vehicle: SCOOTER | VAN | CAR | TRUCK | BIKE | WALK | DRONE
_16  }
_16  trackingUrl: String
_16  totalDistanceTraveled: Int
_16  rating: Float # 1-5
_16  shippingPrice: Float
_16  shippingEstimatedDate: String
_16}

Example


_16{
_16  "status": "PENDING",
_16  "agent": {
_16    "id": "pedro1",
_16    "name": "Pedro!",
_16    "identification": "89082480",
_16    "phone": "242424234",
_16    "email": "pedro@gmailc.om",
_16    "vehicle": "SCOOTER"
_16  },
_16  "trackingUrl": "https://localhost.com",
_16  "totalDistanceTraveled": 2,
_16  "rating": 5,
_16  "shippingPrice": 150000,
_16  "shippingEstimatedDate": "2022-04-27T20:25:45.067Z"
_16}

Response


_19{
_19  "message": "Service updated successfully",
_19  "data": {
_19    "status": "PENDING",
_19    "agent": {
_19      "id": "pedro1",
_19      "name": "Pedro!",
_19      "identification": "89082480",
_19      "phone": "242424234",
_19      "email": "pedro@gmailc.om",
_19      "vehicle": "SCOOTER"
_19    },
_19    "trackingUrl": "https://localhost.com",
_19    "totalDistanceTraveled": 2,
_19    "rating": 5,
_19    "shippingPrice": 150000,
_19    "shippingEstimatedDate": "2022-04-27T20:25:45.067Z"
_19  }
_19}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

Create notes

Service that allows the carriers to add notes/information on services.

POST: /tracking/hook/notes/{carrierId}/{serviceId}
Authentication: API_KEY_PUBLIC

Parameters

Name	Type	In	Description
`carrierId`	string	path	Carrier ID
`serviceId`	string	path	Id generated by the service
`Authorization`	string	header	JWT generated with API KEY PUBLIC

Schema


_10[
_10  {
_10    type: ERROR | COMMENT!
_10    note: String!
_10    author: String
_10  }
_10]

Example


_12[
_12  {
_12    "type": "ERROR"
_12    "note": "El paquete tarda en ser despachado",
_12    "author": "Oscar Rojas"
_12  },
_12  {
_12    "type": "COMMENT"
_12    "note": "El paquete fue recogido",
_12    "author": "Oscar Rojas"
_12  }
_12]

Response


_15{
_15 "message": "Notes saved successfully",
_15 "data": [
_15    {
_15      "type": "ERROR"
_15      "note": "El paquete tarda en ser despachado",
_15      "author": "Oscar Rojas"
_15    },
_15    {
_15      "type": "COMMENT"
_15      "note": "El paquete ha fue recogido",
_15      "author": "Oscar Rojas"
_15    }
_15  ]
_15}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

Create evidence

Service that allows the carrier to add evidence like proof of delivery or pickup to the shipping service, photos, text, others.

POST: /tracking/hook/evidences/{carrierId}/{serviceId}
Authentication: API_KEY_PUBLIC

Parameters

Name	Type	In	Description
`carrierId`	string	path	Carrier ID
`serviceId`	string	path	Id generated by the service
`Authorization`	string	header	JWT generated with API KEY PUBLIC

Schema


_10[
_10  {
_10    type: IMAGE | TEXT!
_10    content: String!
_10    author: String
_10  }
_10]

Example


_12[
_12  {
_12    "type": "IMAGE",
_12    "content": "https://parkers-images.bauersecure.com/wp-images/18727/courier-van-insurance-01.jpg",
_12    "author": "Felipe Cardenas"
_12  },
_12  {
_12    "type": "TEXT",
_12    "content": "El paquete fue entregado",
_12    "author": "Felipe Cardenas"
_12  }
_12]

Response


_15{
_15  "message": "Evidences saved successfully",
_15  "data": [
_15    {
_15      "type": "IMAGE",
_15      "content": "https://parkers-images.bauersecure.com/wp-images/18727/courier-van-insurance-01.jpg",
_15      "author": "Felipe Cardenas"
_15    },
_15    {
_15      "type": "TEXT",
_15      "content": "El paquete fue entregado",
_15      "author": "Felipe Cardenas"
_15    }
_15  ]
_15}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

Create labels

Service that allows the carrier to add the shipping labels.

POST: /tracking/hook/labels/{carrierId}/{serviceId}
Authentication: API_KEY_PUBLIC

Parameters

Name	Type	In	Description
`carrierId`	string	path	Carrier ID
`serviceId`	string	path	Id generated by the service
`Authorization`	string	header	JWT generated with API KEY PUBLIC

Schema


_10{
_10  id: String!
_10  url: String!
_10  name: String!
_10  type: PDF | BASE64 | TEXT | ZPL!
_10}

If the label is type BASE64 or TXT, the max size that we allow is 180kb.

Example


_10{
_10  "id": "AS23424ADASFG",
_10  "url": "http://s3://mybucket-alpha/orc/2013-10-04-custdata/label-pickup.pdf",
_10  "name": "Etiqueta de entrega",
_10  "type": "PDF"
_10}

Response


_10{
_10  "message": "Label saved successfully",
_10  "data": {
_10    "id": "AS23424ADASFG",
_10    "url": "http://s3://mybucket-alpha/orc/2013-10-04-custdata/label-picup.pdf",
_10    "name": "Etiqueta de entrega",
_10    "type": "PDF"
_10  }
_10}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

Cancel service

Service that will cancel an ongoing shipping service.

POST: /tracking/hook/cancel/{carrierId}/{serviceId}
Authentication: API_KEY_PUBLIC

Parameters

Name	Type	In	Description
`carrierId`	string	path	Carrier ID
`serviceId`	string	path	Id generated by the service
`Authorization`	string	header	JWT generated with API KEY PUBLIC

Schema


_10{
_10  comment: String
_10  type: ERROR_CREATE_SERVICE  |  END_CLIENT_CANCELED  |  NO_THERE_DELIVERY_MAN_ASSIGN  |  OTHER!
_10}

Example


_10{
_10  "comment": "La direccion de entrega se cambio",
_10  "type": "END_CLIENT_CANCELED"
_10}

Response


_10{
_10  "message": "Service canceled successfully",
_10  "data": {
_10    "comment": "La direccion de entrega se cambio",
_10    "type": "END_CLIENT_CANCELED"
_10  }
_10}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

On hold service

Service that allows a carrier to temporarily pause a shipping service.

POST: /tracking/hook/on-hold/{carrierId}/{serviceId}
Authentication: API_KEY_PUBLIC

Parameters

Name	Type	In	Description
`carrierId`	string	path	Carrier ID
`serviceId`	string	path	Id generated by the service
`Authorization`	string	header	JWT generated with API KEY PUBLIC

Schema


_10{
_10  comment: String # reason
_10  type: ERROR_CREATE_SERVICE  |  END_CLIENT_PAUSE  |  NO_THERE_DELIVERY_MAN_ASSIGN  |  OTHER!
_10}

Example


_10{
_10  "comment": "La direccion de entrega se cambio",
_10  "type": "END_CLIENT_PAUSE"
_10}

Response


_10{
_10  "message": "Service on hold successfully",
_10  "data": {
_10    "comment": "La direccion de entrega se cambio",
_10    "type": "END_CLIENT_PAUSE"
_10  }
_10}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error

Create token

Endpoint available to generate authentication JWT.

REST API endpoints are prefixed with the following URL:

https://auth.pickingnpacking.com/prod

POST: /token
Authentication: None

Schema


_10{
_10    apiKey: String!
_10}

Example

POST: https://auth.pickingnpacking.com/dev/token


_10{
_10  "apiKey": "db5a3cecfef9cb0a9815af7c2eb8f7d6:c400460c165cc9beb146ad4d757e3bb1a24ff15228c424a0bd7c37f0ac356c0f6230568705d93dd6ff68190c0eafe5a74cbb14229748f20d3e53cbcc790ba372"
_10}

Response


_10{
_10  "message": "success",
_10  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ2.eyJob4N0bmFtZSI6Im5ld2J1c2luZXNzMDEiLCJpYXQiOjE2MzM3MjE1NzksImV4cCI6MTYzMzcyMjQ3OX0.7QRZpElg1HYgyJpE6QTNgE2IN3vXbzIfulBS0Bvyzds"
_10}

Status codes

HTTP Status Code	Description
200	Ok
401	Requires authentication
400	Bad request
404	Resource not found
500	Internal error