API docs by Redocly

Courier Service API (1.0.1)

Download OpenAPI specification:Download

License: Propietary

Events notification webhook Webhook

Events notification webhook

Request Body schema: application/json

Information regarding a new shipment event.

If an HTTP code other than '200' is returned, it will trigger a new webhook call under an exponential backoff mechanism for a maximum of 6 hours. The events are sent using a First In, First Out (FIFO) strategy, ensuring that they are received in the order they were generated. This means no new events will be received until the current one has been acknowledged.

attempts
integer <int32>

The current attempt for this event notification

received
string <date-time>

The date and time (in UTC) this event was received by the notifications service

status
string
Enum: "created" "accepted" "rejected" "picked_up" "crossdocked" "delivered" "scheduled" "failed_attempt" "dropped_off" "canceled" "returned" "damaged" "incident"
  • created: Shipment was created on the platform
  • accepted: Shipment was accepted as it's scheduled for pickup and delivery. It only applies to shipment with delivery_term="turbo"
  • rejected: Shipment can't be fullfilled within agreed time or falls out or distribution zone. It only applies to shipment with delivery_term="turbo"
  • picked_up: Shipment was picked up/collected
  • crossdocked: Shipment was received in a distribution center
  • delivered: Shipment was successfully delivered. In case of a PUDO/Locker dropoff, either as a primary location or as fallback, this status means the destinatary successfully picked up the shipment
  • scheduled: Shipment was scheduled on a route and it's ready for delivery/pickup/droppoff
  • failed_attempt: Failed delivery/dropff happened. In case of a PUDO/Locker dropoff, either as a primary location or as fallback, this status means the destinatary couldn't pickup the shipment
  • dropped_off: Shipment was dropped off. It means the shipment was left in location that's no the final destination (for instance a PUDO or Locker).
  • canceled: Shipment was canceled either by the customer, or the destinatary before it was collected/picked up. In case the LOP is already handling the shipment it will usually end in "returned" state.
  • incident: An operation issue, logistics issue, or any other non-temporary problem arised. The substatus field contains the issue detail (fraud_detected, package_damaged, package_lost, etc.)
substatus
string
Enum: "custom" "fraud_detected" "package_damaged" "package_lost" "rejected" "residence_unattended" "nonexistent_address" "address_discrepancy"

Substatus provides additional info about the notified status. It could be a platform standard or a custom one.

  • custom - Custom substatus. Additional info might be provided in custom_substatus_info field
  • fraud_detected - Only appears if status=incident
  • package_damaged - Only appears if status=incident
  • package_lost - Only appears if status=incident
  • rejected - Only appears if status=failed_attempt
  • residence_unattended - Only appears if status=failed_attempt
  • nonexistent_address - Only appears if status=failed_attempt
  • address_discrepancy - Only appears if status=failed_attempt
object (GeoInfo)
object
shipment_id
integer <int64>
tracking_number
string [ 5 .. 25 ] characters

Responses

Request samples

Content type
application/json
{
  • "attempts": 1,
  • "received": "2019-08-24T14:15:22Z",
  • "status": "failed_attempt",
  • "substatus": "nonexistent_address",
  • "event_location": {
    },
  • "custom_substatus_info": {
    },
  • "shipment_id": 194919312,
  • "tracking_number": "TN-1234567890"
}

Authentication endpoint

OAuth2 Client Credentials Log in endpoint

header Parameters
Authorization
required
string

Base64 encoded client_id:client_secret prepend with Basic

Request Body schema: application/x-www-form-urlencoded
grant_type
string

OAuth2 grant_type. Always send client_credentials

scope
string

Requested scope/s. Default acoount scopes will be returned if not specified

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6TGc4VHVhQUszbjdnOGxtMWIxVFp4T2d0ZllINnJCSjRHOGJtYWE1a2RBIn0.eyJleHAiOjE3MDMyMTE5ODcsImlhdCI6MTcwMzIxMTA4NywianRpIjoiNGM4NDgzZDUtYmY4NS00ODg3LTliYzEtMTZhODU4N2ZmMTY5IiwiaXNzIjoiaHR0cHM6Ly9vYXV0aC50ZXN0LnBhcXVlcnkuY29tL2F1dGgvcmVhbG1zL3BhcXVlcnkiLCJzdWIiOiJhODkzYTBiNi0xMWMzLTRhMjAtODUwMS0yMjVjZmJkMzU5NDUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJlU0Q2eENlY0dwQkNva2lUIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIvKiJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1wYXF1ZXJ5Iiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicm9sZXMgcHJvZmlsZSBlbWFpbCBzaGlwbWVudHMiLCJjbGllbnRIb3N0IjoiMTAuMjQ0LjMuMzUiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1lc2Q2eGNlY2dwYmNva2l0IiwiY2xpZW50QWRkcmVzcyI6IjEwLjI0NC4zLjM1IiwiY2xpZW50X2lkIjoiZVNENnhDZWNHcEJDb2tpVCJ9.JYzyl-ShgdM1DLxn_sGFjLfLV8hher_Pypy-ajNrR-9_Fvd14xXmiZj_jaJSaBLWuoNedEygqaHc11vIgchpDHHqvH2FpD_LMd--M2lo2R2b4ZDeF3d8fcCsDu3XHmCgKNTxbWoV_veVObWOiSkbwP8js5JF_UnXtfjWepj-UwgVkWYduLq3duMjuDmR-lo7HuOA7T-GUEzirvdGzMXmHPTI9hrESrQkAM43LHirs865zw_eVoy8L_EfcmuHUz7wAs9SvD2yTTWRFN8ixcG52WPsDKZFg2i_oj7whPuWAcnLIFY9T_8_8QO--V4y0_asOC3xjYOCfzBhXyuVIfOHeA",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "refresh_expires_in": 0,
  • "not_before_policy": 0,
  • "scope": "shipments profile email"
}

Creates a new Shipment. As default it's created synchronously.

A shipment with the provided data is created. Service does it best to create it synchronously, in case creation is taking too long an event will be fired upon creation

Authorizations:
laas_auth
Request Body schema: application/json
tracking_number
string [ 5 .. 25 ] characters

The shipment tracking number. If not provided it will be created and returned

caption
string

Optional if at least one shipping_items object is provided. In that case, if caption is null the name of the first shipment item will be used.

object (BaseCost)

The rate associated with this shipment delivery

required
object (MonetaryAmount)

A monetary amount

is_bundle
boolean

This shipment is comprised of several packages that should be delivered.

object (Bundle)

Describes a shipment bundle. A shipment bundle is shipment comprising more than one package. Note: In case a shipment includes only one package this field is not mandatory

needs_preparation
boolean

Whether this shipment must be prepared by logistics operator before delivery

Array of objects (ShippingItem)

A collection of shipping items. It's usually used along with needs_preparation: true

required
object

Where this shipment should be collected

required
object

Where this shipment should be delivered or dropped off

required
object (Individual)

A real person

required
object (Sender)

Who sends this shipment

object
object
logistics_type
required
string
Enum: "forward" "reverse"

The logistics service type

delivery_term
required
string
Enum: "standard" "priority" "express" "turbo"

Responses

Request samples

Content type
application/json
{
  • "tracking_number": "NES1234567890",
  • "caption": "string",
  • "base_cost": {
    },
  • "shipment_cost": {
    },
  • "is_bundle": true,
  • "bundle": {
    },
  • "needs_preparation": true,
  • "shipping_items": [
    ],
  • "pickup": {
    },
  • "dropoff": {
    },
  • "receiver": {
    },
  • "sender": {
    },
  • "payment": {
    },
  • "verification_method": {
    },
  • "logistics_type": "forward",
  • "delivery_term": "turbo"
}

Response samples

Content type
application/json
{}

Get Shipment Data by ID

Most updated version of the shipment data. It could differ from the original posted to /shipment endpoint for creation.

Authorizations:
laas_auth
path Parameters
shipment_id
required
integer <int64>
Example: 194919312

ID of the shipment to retrieve

Responses

Response samples

Content type
application/json
{
  • "shipment_id": 194919312,
  • "shipment": {
    }
}

Get the shipment POD

Gets the shipment Proof Of Delivery (POD). POD only applies when shipment has been deployed so an error is returned if shipment is in not yet delivered

Authorizations:
laas_auth
path Parameters
shipment_id
required
integer <int64>
Example: 194919312

ID of the shipment whose POD we want to retrieve

Responses

Response samples

Content type
application/json
{
  • "class": "pdf",
  • "content": {
    }
}

Get Shipment Driver

Get the driver to whom the shipment is scheduled

Authorizations:
laas_auth
path Parameters
shipment_id
required
integer <int64>

ID of the shipment whose driver we want to retrieve

Responses

Response samples

Content type
application/json
{
  • "identification_data": {
    }
}