This section contains all information needed to connect to Seven Senders via API when using our Delivery Service with labels not provided by Seven Senders and optional Seven Senders Portal.

• API Key Authorization
•  Workflow
• Create an Order
  • Parameters
  • Available Languages
  • Further Order Operations Available
• Update the State of an Order
  • Parameters
  • Available order-states
• Create a Shipment
  • Parameters
  • Carriers Providing Tracking Code after FHS
  • Available Carriers
  • Shipment Statuses
  • Further Shipment Operations Available
• Update an Order to provide the 'boarding complete' Information
• Additional Operations

API Key Authorization

The credentials for the API consist of a access-key, a string provided by Seven Senders. Before starting using the API, you need to request a JWT token by applying the POST/token operation containing your access-key. The JWT token should then be used inside the 'Authorization' header for every further request. Format: Authorization: Bearer YOUR_TOKEN

Workflow

In the following, the workflow is described step-by-step. 

Create an Order

Orders are created by using the POST operation of the 'order' endpoint (POST /order).

Parameters

*Promised_delivery_date: Fundamental information since it’s used as input to calculate various KPI’s within Seven Senders Portal. Therefore, we highly advise you to provide this information in an acceptable accuracy.

Available Languages

bg; cs; da; de; el; en; es; et; fi; fr; ga; hr; hu; it; lt; lv; mt; pl; pt; ro; ru; sk; sl; sv & uk

Further Order Operations Available

• GET/orders/{id} → retrieve a single order that has previously been imported
• GET/orders →  retrieve multiple orders that have previously been imported
• PUT/orders/{id} → updates (partially) an existing order

• DELETE/orders/{id} → delete one or multiple existing order/orders 

Note: the given ID within the response when creating an order is needed to update or delete an order.

Update the State of an Order 

Update the state of an order via the POST/order-states (operation coming soon) operation. 

Parameters

Available order-states

Create a Shipment

Shipments are created by using the POST operation of the 'shipment' endpoint (POST/shipment). In the optimum workflow you need to link it to the corresponding order. The link between shipment(s) and order is done through the 'order_id'. The order status will then automatically change to 'shipped'. 

Note: A shipment can only be linked to one order, but an order can consist of more than one shipment. 

Parameters

*Planned_pickup_datetime: Fundamental information since it’s used as input to calculate various KPI’s within Seven Senders Portal. Therefore, we highly advise you to take cut-off times, weekends etc. in to account when setting-up the “planned_pickup_datetime” logic.

Carriers Providing Tracking Code after FHS

There are some exceptions where the carrier is not providing a tracking code before the first hub scan at LMC (i.e. when the shipping label has been created).

Bartolini (BRT) (IT) is a carrier that does not always provide the tracking code before the FHS. Behavior depends on connection type and version of EDI file used. This section is relevant if you have solution type 'B' implemented.

Bartolini (BRT) Workaround

Normally when creating a shipment inside the Seven Senders system , a tracking number (parameter: “tracking_code”) is required (cf. Create a Shipment). In case of BRT you need to pass a unique reference number (Parameter: “reference_number”). This implies also that no values for the parameters “carrier_name” and “carrier_country” can be transmitted. Once BRT scans the parcels in the hub, Seven Senders automatically retrieves the generated tracking codes and updates the corresponding shipments.

Note: this reference number needs to be identical to the number transmitted to BRT when notifying them about the shipment!

Available Carriers

The table below contains the currently available carriers (subject to change). All currently available carrier are applicable by applying the GET/carriers operation.

Definition of carrier and carrier_country in case of cross border shipments

Defining the carrier and carrier_country in case of cross border shipments depends on the “set-up”. There are three scenarios (see picture below).

1. Scenario: Using the Seven Senders Delivery (direct injection) service

The carrier and carrier_country provided should be the carrier which is in charge for the 'last mile'.

• Shipping from: Germany (given it is the warehouse location) 
• Shipping to: France
• Carrier: Seven Senders and Colissimo

In this example the carrier is 'Colissimo' and the carrier_country 'fr'.

2. Scenario: Shipping with Carriers (own contracts)

The carrier and carrier_country should be defined as the one you’re handing the parcel to in the first place.

• Shipping from: Germany (given it is the warehouse location)
• Shipping to: France
• Carrier: DHL DE and DHL FR

In this scenario, the carrier is 'DHL' and the carrier_country 'de'.

3. Scenario: Shipping with Carriers (own contracts) + self-organized Direct Injection

The carrier and carrier_country is the one that is in charge for the 'last mile'.

• Shipping from: Germany (given it is the warehouse location)

• Shipping to: France

• Carrier: Freight Forwarding Company XYZ and DHL FR

In this scenario, the carrier is 'DHL' and the carrier_country 'fr'.

Shipment Statuses

After importing a shipment inside your account, Seven Senders takes over the update of the shipment's status. Seven Senders updates the shipment status based on information received from the carrier. A shipment can have the following status:

Further Shipment Operations available

• GET/shipments/{id] → retrieve a single shipment that has previously been imported
• GET/shipments → retrieve multiple shipments that has previously been imported
• PUT/shipments/{id} → updates completely or partially an existing shipment 
• DELETE/shipments → delete one or multiple existing shipments (operation is coming soon)

Note: the given ID within the response when creating an shipment is needed to update or delete an order.

Update an Order to provide the 'boarding complete' information

Whenever all items of an order have been shipped and the corresponding shipments were created inside the Seven Senders Portal account, you need to provide us this information by using the PUT/orders/{id} operation. Through the PUT/orders/{id} operation you have to update the 'boarding_complete' parameter. The parameter value needs to be changed from 'False' (not all items shipped”) to 'True' (all items shipped). 

Note: updating the “boarding_complete” parameter is important since this information is required to transfer an order (once all shipments have been delivered) to the state 'Completed': 

• If boarding complete = true (or null) and all shipments are delivered → order completed
• If boarding complete = true (or null) and 1 shipment is delivered → order NOT completed
• If boarding complete = false and 1 shipment created in delivered → order NOT completed
• If boarding complete = false and all shipment created in delivered → order NOT completed

Additional Operations

The following operations, provide you further information.

• GET/carriers →  retrieve all carriers available to create shipments in the Seven Senders system
• GET/shipments/{id}tracking_history→ retrieve all events for a given shipment inside your Seven Senders account.
• GET/warehouse → manage you warehouses used inside your Seven Senders account (operation is coming soon)