Support Portal

Delivery and Sendwise

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 Sendwise.

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

Parameter

Mandatory

Type

Example

Description

order_id

Yes

String

"order123456"


The order reference inside your system

order_url

Recommended

String

"https://www.7s.com"


At which website the order was submitted

order_date

Yes


String

(dd.mm.yyyy hh:mm:ss)

"2017-08-15T16:53:07+01:00"


The Date when the order was created inside your system

boarding_complete

No

boolean

[true or false]

“False”

Information indicating (if an order consists of multiple parcels) that all shipments of an order have been imported (cf. for this 1.5 “Update an order to provide us with the “boarding complete” information”)

language

Recommended

Array[string]

“en”


What is the language of the customer for this order or the language for the shop_order_url defined.


If you intent to send mails/sms notifications to your customers, we recommend that you provide this information for each order.

The reason is that a notification can only be send if the shop_order_url and the Language are defined on the order

order_tags 

No

Array[string]

“SKU 1234”

Tags/Properties to allow you to segment your orders

promised_delivery_date

Recommended

String

"2017-08-15T16:53:07+01:00"


The delivery date you’ve promised the customer. The promised_delivery_date is an important parameter* (cf. comment below the table)

*Promised_delivery_date: Fundamental information since it’s used as input to calculate various KPI’s within Sendwise. 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

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

Parameter

Mandatory

Type

Example

Description

order_id

Yes

String

"order123456"

The order reference inside your system

state

Yes

Choice: 

See tabel below

“paid”

The current state of the order

datetime


Yes

String

(dd.mm.yyyy hh:mm:ss)


"2017-08-15T16:53:07+01:00"


The date and time

location

No

String

"Schwedter strasse 36A 10435 Berlin"


The physical location of the order

Available order-states

Status 

Description

new

Status when the order is imported

paid

Order was paid by the customer

in_production

This status is useful if you need to produce/made the item ordered by the customer

In_preparation 

The order is processed inside your warehouse

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

Parameter

Mandatory

Type

Example

Description

order_id 

Yes

String

"order123456"

The order reference inside your system.

The shipment will be link to this order. 

tracking_code 

Maybe

String

"tracking123456789"

The shipment tracking number given by the carrier.

Mandatory! 

If the tracking code is not available a value for the parameter “reference_number” needs to be provided (see parameter “reference_numer” and Bartolini Workaround)

reference_number 

Maybe

String

"ref123456"

The reference_number represents  normally your internal reference for this shipment inside your IT system.


This information is used when the carrier does not provide a tracking number before the FHS (e.g the Italian carrier BRT). Compare also the section Carriers that provide the tracking code after FHS


Mandatory if no tracking code is provided

carrier:

carrier: {carrier_name: “dhl”, carrier_country: “DE”}

carrier.carrier_name

Maybe

choice:

See the list of choice below


"dhl"


Selected carrier to ship the parcel.


Mandatory if a tracking number is provide

carrier.carrier_country

Maybe

choice:

See the list of choice below


“DE”

Country where the parcel is handed over to selected carrier / scanned for the first time by the selected carrier.


Mandatory if a tracking number is provided

carrier_service 

No

choice:

"standard"

"express"

"other"

"express"


Service / Product / Tariff used by the carrier

recipient_first_name 

Yes

String

“David”

Customer’s first name

recipient_last_name 

Yes

String

“Hasselhoff”

Customer’s last name

recipient_email 

Yes

Email

"d.hasselhoff@sevensenders.com"


Customer’s email address Send email notifications to you customer through Sendwise

Without this information, no mail notification can be send. 


In case you’re only using our delivery product, you can provide a “default” email-address (e.g. cs@yourcompany.de)

recipient_address 

Yes

String

"Schwedter str. 36A"


Customer’s address. Do not use line breaks. 


If a DHL “Packstation” has been chosen, please state “Packstation” and number (e.g “Packstation 123”)

recipient_zip 

Yes

String

"10435"


Customer’s ZIP code

recipient_city 

Yes

String

“Berlin”

Customer’s city

recipient_country 

Yes

String

“de”

Customer’s country. Use ISO 3166-1 alpha-2

recipient_phone 

No

phone:

Use + for the country code (see example)

"+4915224565981"


Customer’s phone number. Use this field to send sms notifications to your customer through Sendwise

Without this information, no sms notification can be send. 


Note: this is a paid feature. If you’re interested in sending sms to your customers - please get in contact with us

recipient_company_name 

No

String

“Seven Senders”

Customer’s company name if he/she choose to be delivered at his/her company. 


return_parcel 

No

boolean

[true or false]

“false”


Indicates whether the shipment is a return from the customer

pickup_point_selected 

No

boolean

[true or false]

“false”

Is the customer address a pickup point (i.e postal shop, retail shop etc) ?

weight 

Yes

number

1.12

Shipment weight in KG (including packaging)

trackableNo    

boolean

[true or false]

"true"        Indicates if a shipment is trackable. By default set to true. Setting this parameter is prerequisite for displaying information on the Tracking Page and/or Embedded Widget in case of non-trackable shipments.

planned_pickup_datetime 

Yes

date:

dd.mm.yyyy hh:mm:ss


"2017-08-19T15:47:00+0000"


Date and time agreed with the carrier to pick-up the shipment at your warehouse.


When using the delivery products, state the with Seven Senders agreed on pickup time. 


This timestamp triggers the start of the delivery lead time. The planned pickup date represents an important parameter” (cf. comment below the table)

comment 

No

String

“Please be careful”

Comment regarding this shipment left by the customer or for your internal usage

warehouse_address 

Yes

String

"Kochhannstr. 38 10247 Berlin"


Warehouse full address. Do not use line breaks.

warehouse 

Yes

Choice:

List of all warehouse

defined inside your account


"warehouse"


The Warehouse name defined inside your account. Important: the provided warehouse name needs to be identical to the one(s) defined in your Sendwise account. 

shipment_tag 

No

object


{"sku":"nikeAir2017"}


Tags/Properties to allow you to segment your shipments

*Planned_pickup_datetime: Fundamental information since it’s used as input to calculate various KPI’s within Sendwise. 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 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.

Country
Carrier
ATpostat, dpd, ups, dhl
BEbpost, dpd, kiala, mondialrelay, ups, dhl
CHswisspost, dpd, ups, dhl
CZceskaposta, dpd, ups
DEdhl, deutschepost, gls, ups, hermes, dpd, tnt, dachser, raben
DKpostnord, ups, dhl, dpd
EScorreos, seur,seur_international,asm, mrw, ups, dhl
FIposti, postnord, ups, dhl, dpd
FRcolissimo, chronopost, tnt, dpd, mondialrelay, colisprive, gls, dhl, ups, kuehne-nagel
GBroyalmail, yodel, parcelforce, hermes, dpd, dhl
ITbrt, tnt, gls, ups, dhl, nexive, posteitaliane, SDA posteitaliane
LUdhl, ups, kiala, dpd
NLpostnl, kiala, dpd, mondialrelay, tnt, ups, dhl
NOpostnord, ups, dhl, dpd
PLdpd, gls, ups, dhl, poczta polska
SEpostnord, ups, dhl
SKceskaposta, dpd, ups, dhl


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:

Status 

Description

New

The shipment has been created inside your Seven Senders account

Info

The carrier has received the shipment information into his system

Pickup

The shipment has been picked up by the carrier at your warehouse

Hub scan at LMC

The Last Mile Carrier has scanned your shipment inside his hub

Out for delivery

The Last Mile Carrier went to deliver the shipment to the customer

Delivered to pickup point

The shipment has been delivery to a third party

Delivered

The shipment was succesfully delivered to the customer

Lost

The shipment has been lost

Further Shipment Operations available

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 Sendwise 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'.

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)