shippify
Courier / Shipper Api

Updated 10 months ago

Overview

We introduce the shipper/courier API. It helps companies make use of our core features to provide an efficient logistics service, such as:

Sections

Each of our API's sections manages a specific domain of our provided features. These are:

  • Authentication & Users
  • Route Management
  • Vehicles
  • Local inventory
  • Webhooks
  • Other services

Pending:

  • Availability Schedule
  • Availability routing

Authentication and Users

The users, from now on referred as shippers, compose a company's fleet of delivery-people. This section manages the registration and information of the shippers.

Registering a shipper: Creates a new shipper in the service and registers it to your company. Endpoint: POST /v0/shippers

Authenticating a shipper: Authenticates a shipper with their personal credentials (username - password). Endpoint: POST /v0/shippers/auth

Updating a shipper information: Updates a shipper's profile information (name, email, phone, etc). Endpoint: PUT /v0/shippers/:shipper_id

Retrieving a shipper information: Fetches a shipper's profile information (name, email, phone, etc). Endpoint: GET /v0/shippers/:shipper_id

Route Management

Tasks are the logistic unit for e-commerce companies. They describe the pickup and delivery information of a package that a shipper carries out. Routes are a collection of task points sorted optimally for a shipper's navigation.

Assigning a route to a shipper: Assigns an unassigned route to a shipper and marks it as pending for shipper response. Endpoint: PUT /v0/routes/:id/assign

Activating a route: Marks a route assigned to a shipper as accepted and ready to start. Endpoint: PUT /v0/routes/:id/activate

Completing a route: Marks a route assigned to a shipper as completed with no more tasks left. Endpoint: PUT /v0/routes/:id/complete

Updating a task point in a route Updates all the tasks associated to a point in a route. Depending on the current state of the tasks, it executes a pickup or delivery action. Endpoint PUT /v0/steps/complete

Retrieving a route's information: Fetches a route's information and current state. Endpoint: GET /v0/routes/:id

Finding nearby unassigned routes: Fetches a list of unassigned routes in the shipper's vicinity. The service takes into account the shipper's current capacity. Endpoint: GET /v0/routes/near

Retrieving a shipper's assigned routes: Fetches a list of routes assigned to a shipper. Endpoint: GET /v0/shippers/:shipper_id/routes

Vehicles

The API keeps track of all the vehicles available for a company. Using vehicle information, the API creates optimized routes based on a vehicle's:

  • Location
  • Schedule
  • Capacity

Registering a vehicle: Adds a new vehicle to a shipper's list of available vehicles. Endpoint: POST /v0/shippers/:shipper_id/vehicles

Unregistering a vehicle: Removes a vehicle from a shipper's list of available vehicles. Endpoint: DELETE /v0/shippers/:id/vehicles/:vehicle_id

Updating a shipper's current vehicle: Updates a shipper's current vehicle to another one associated. Endpoint: PUT /v0/shippers/:id/vehicles/current

Retrieving a shipper's current vehicle: Fetches a shipper's current vehicle information. Endpoint: GET /v0/shippers/:id/vehicles/current

Updating a vehicle information: Updates a vehicle's information. Endpoint: PUT /v0/vehicles/:vehicle_id

Retrieving a vehicle information: Fetches a vehicle's information. Endpoint: GET /v0/vehicles/:vehicle_id

Adding a vehicle photo: Adds a photo associated to a specific vehicle. Endpoint: POST /v0/vehicles/:vehicle_id/photos

Deleting a vehicle photo: Deletes a photo associated to a specific vehicle. Endpoint: DELETE /v0/vehicles/:vehicle_id/photos/:photo_id

Downloading a vehicle photo: Downloads a vehicle's photo. Endpoint: GET /v0/vehicles/:vehicle_id/photos/:photo_id

Inventory

The local inventory is a helpful tool for shippers to keep track of their vehicle's capacity and items inside.

Retrieving a shipper's item list: Fetches a list of the items located in a shipper's vehicle. Endpoint: GET /v0/shippers/:shipper_id/items

Getting a shipper's estimated available capacity: Estimates a shipper's remaining vehicle capacity. It takes into consideration the vehicle's capacity and the items in it.

Webhooks

Webhooks allow servers and other systems to listen for relevant events from a source provider. Using real-time tracking, clients can receive notifications updates of a shipper's location.

Tracking a shipper location: Notifies subscribed services of location updates of a company's shippers. Endpoint: POST /v0/shippers/:shipper_id/track

Other services

Real-time communication: Chat enables real-time communication with a shipper. The services establishes communication via a secure channel, group or direct messaging.