Entities

Delivery

A Delivery represents the main service sold by Cargonautes (ex OLVO): moving things around from one place to another, during defined timeslots.

  • The “things” moved around are Packages
  • A Delivery is composed of two tasks, a Pickup task, and a Dropoff task. Each task has its own timeslots – slot_starting_at and slot_ending_at
  • These Tasks happen at specific Places, that have an address, a recipient, etc.

Cyke has the concept of «default place» for a customer: it defines where you are hosted and where your outbound deliveries are sent from. It can be your own office/store, or it can be a hub owned by Cargonautes (ex OLVO) (in this case, you are responsible for bringing the packages to Cargonautes (ex OLVO).) Task details happening at this default place (usually a Pickup task), be it your own place or Cargonautes (ex OLVO) hub, do not need to be specified in the API creation call and will be automatically filled. When creating a Delivery through the API, you should only specify the details of the Tasks and Places that do happen at the final recipient place (your own client). That means that for most of the Deliveries, you only send a Dropoff task and its place. If you need an inbound Delivery where a messenger picks up a package and brings it to you, you’ll need only to specify a Pickup object and Place.

The delivery time slot is represented by two fields, slot_starting_at and slot_ending_at on the Tasks. As only the main Task (usually a dropoff) needs to be specified, the timeslot of the Task happening at your own place is automatically calculated. The API accepts most timeslots, unless they are already started. It is the client’s responsibility to implement the business rules linked to the desired time slot size, anticipation time, and opening hours and days – knowing that reduced slot size and anticipation can induce higher prices.

Attributes:

Name Type Description
sender_display_name string Optional.
If you want to deliver a parcel in the name of another name than yours, you can write it here. If given, this is the name that the recipient will see in the SMS that is sent to him, instead of your company’s name.
comments string Optional.
Any comments you could make about the delivery to help our staff.
client_order_reference string Optional.
An internal order reference of yours, ( typically your own purchase id for this delivery). You can later retrieve a delivery using this reference.
bring_back_containers boolean Optional.
If the messenger needs to bring back deposited containers (empty bottle, etc). If not specified, the company default is applied.
dropoff Task Optional as long as you give a pickup.
The address and recipient information where to deliver.
pickup Task Optional as long as you give a dropoff.
The address and recipient information where to pick the goods up.
packages array of Packages Should at least contain one Package.
The packages that your delivery contains. When updating packages, you must provide the whole array of packages as it will override the existing packages. Refer to the Package and PackageType entities and the code example below to see what is expected from a package.
reversed_packages array of Packages Only taken into account if bring_back_containers param is used.
The packages that should be collected upon delivery.

When getting an existing Delivery, you will also get access to additionnal fields:

Name Type Description
status string enum:
saved,
scheduled,
picked_up,
delivered,
cancelled,
failed		 The status of the delivery. saved means the delivery has been saved to our dispatch system and is currently not assigned to anybody. scheduled means the task has been assigned to one of our workers (the worker may not have started the task yet, though). picked_up is for deliveries composed of one pickup and one dropoff: it means the goods have been picked up by us, and are now waiting to be delivered. If the goods have been successfully delivered, the status is delivered, otherwise if the delivery failed, the status is failed. If the task has been cancelled, the status is cancelled.
price_cents integer If we include some pricing functionality for your company in Cyke, the price_cents would show the price of the delivery in cents. Otherwise, it will be equal to null.
direction string enum:
outbound,
inbound,
other		 Tells if the delivery’s main task is the dropoff (outbound), the pickup (inbound), or both the pickup and the dropoff (other).
original_delivery_id integer Optional.
Identifier of the original delivery if this delivery is a redelivery.
redelivery_id integer Optional.
Identifier of the redelivery if this delivery has one.

Task

A Task can be either a saved address that you have already in your account, or a place. In the first case you should give the Task’s unique number in this field:

{
  ...
  "pickup": 23,
  ...
}

Otherwise, juste give a JSON with an argument place inside:

{
  ...
  "pickup": {
    "slot_starting_at": "2019-09-04T16:00:00.000+02:00",
    "slot_ending_at": "2019-09-04T18:00:00.000+02:00",
    "place": {
      "recipient_name": "Cercei Lannister",
      "recipient_phone": "+33670707070",
      "address": "1 place du Palais Royal",
      "postal_code": "75001",
      "city": "Paris",
    }
  },
  ...
}

When getting an existing Task, you will also get access to the following fields:

Name Type Description
slot_starting_at string Mandatory.
The time after which the task should be completed. Has to be written in GMT format.

Example: “2020-11-09T16:00:00.000+02:00”
slot_ending_at string Mandatory.
The time before which the task should be completed. Has to be written in GMT format.

Example: “2020-11-09T18:00:00.000+02:00”
tracking_url string A public url your customers can use to track the messenger delivering their packages. Available once the delivery has started
completed_at string The datetime at which the delivery has been completed (delivered of failed)
Example: “2020-11-09T18:00:00.000+02:00””
failure_reason string The reason why the delivery task failed. Chosen by the messenger in their application.
notes string Notes filled freely by the messenger when they completed the task.
place Place See below at Place
completion_signature Object A url to access the recipient signature and accepted_by containing their name. Available once the delivery has been delivered
completion_pictures Array A collection of url to access the pictures. Available once the delivery has been delivered

Place

A Place is basically an address with some recipient information:

Attributes:

Name Type Description
recipient_name string Mandatory.
The recipient’s name and surname. When shipping to a company, give the operations manager’s name and phone.
recipient_phone string Mandatory, except for some particular cases (contact us for more information).
The recipient’s phone number. International format is strongly recommended. A tracking link will be sent to this number when the courier starts the task.

Example: “+32485549268”
recipient_email string Optional.
The recipient’s email address. In the future, a tracking link may be sent to this address before the courier arrives.

Example: “tartempion@example.org”
company_name string Optional.
The company’s name when shipping to an office, a shop, etc.
address string Mandatory.
The number and street name. Don’t give any other information here (it will fail otherwise). Instead, keep them for address_instructions.

Example: “1 place du Palais Royal”
postal_code string Mandatory.
The postal code of the address. Should be in the zone that we deliver in. Please contact us so we can give you the list o accepted locations.

Example: “75000”
city string Mandatory.
The city name.
address_instructions string Optional but highly recommended.
Any information that could help the courier reach the recipient’s front door. Access code, building number, interphone, alley, floor, apartment number, digicode, etc.

Example: « digicode 3495 on your left inside.”_

Package

A Package represents a parcel or any kind of merchandise that is to be transported on a Delivery.

Attributes:

Name Type Description
amount integer Mandatory.
The amount of packages of this kind in the delivery.
package_type_id integer The identifier of the package type on Cyke.
name string A name you can provide to identify and describe the package.
volume_dm3 float The quantity represented by the package. In liters.
weight_kg float The weight represented by the package. In kilograms.
fragility enum null, fragile or super_fragile.
temperature enum null, fresh or hot.
client_reference string An identifier of the package. Can be the barcode.

When creating a delivery, you will have to provide either:

  • volume_dm3, weight_kg and name to provide directly the mandatory information OR
  • A package_type_id to use the information from the PackageType

Note: In previous version of the API, you were able to describe a package with its type only, without id. This is no longer the recommended way.

PackageType

PackageTypes are examples of packages that you can use to describe the delivery packages without providing all the data for each package.

Each customer account has a list of accessible package types or size categories. PackagesTypes will describe objects that are delivered (ie. “Bottle 1.5L”, “Flower bunch size M”, etc.), while size categories will rather describe the size of a delivery – not what’s inside (ie. “small parcel < 12L”, “medium parcel < 15L”, etc.).

Package types must be agreed beforehand commercially, and configured in the Cyke staging and production environment before you can use them.

Attributes:

Name Type Description
id integer Mandatory.
The identifier of the package type on Cyke.
type string The exact name of the package type, as you can see it in your Cyke account.
volume float The quantity represented by the package type. In liters.
weight float The weight represented by the package type. In kilograms.
fragility enum null, fragile or super_fragile.
temperature enum null, fresh or hot.