Create label

Content

API Key Authorization
Workflow
Create a label
- Available carrier
- Multi-Coli / Multi-Parcel Labels

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. The JWT token is valid until next token needs to be retrieved.

Workflow

Create a label via post/label endpoint
Response contains
- Tracking number
- URL to label file
- carrier

Remarks

If you request outbound and return label in same request, response contains array with all information

Create a Label

Carrier Labels are created by using the POST operation of the 'label' endpoint (Post/labels).

Parameters

Parameter	Mandatory	Type	Example	Description
format	No	String	'pdf'	The returned label format whether it's a pdf, zpl. The recommended is zpl. Supported values are: 'pdf', 'zpl', 'zpl300'. 'zpl' will return a 203 DPI zpl while 'zpl300' will return a 300 DPI zpl.
order_id	Yes	String	'order123456'	The order reference inside your system. Alternatively, you can provide us an unique Id
carrier:	carrier: {name: 'dhl', country: 'DE'}
carrier.name	Yes	String	'Seven Senders'	carrier_name refers to carrier used for creating the respective label. A list of supported combinations of carrier_name and carrier_country is provided in table below.
carrier.country	Yes	String	'DE'	Please always provide here the country of the injection hub. Use ISO 3166-1 alpha-2
recipient_first_name	Yes	String	'David'	Customer’s first name
recipient_last_name	Yes	String	'Hasselhoff'	Customer’s last name
recipient_email	Yes	String	'[email protected]'	Email address to send notifications to your customer. Will be provided to carrier if filled. Without this information, no mail notification can be send.
recipient_street	Yes	String	'Schwedter Str.'	Customer’s street. Do not use line breaks.
recipient_house_no	no	String	'36A'	Seperate field for house number of customer sending address.
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 (see Description)	phone: Use + for the country code (see example)	'+4915224565981'	Customer’s phone number. In general this field is not mandatory. For some carrier services this might be relevant. Will be clarified during implementation.
recipient_company_name	No	String	'Seven Senders'	Customer’s company name if he/she choose to be delivered at his/her company.
sender_first_name	No	String	'Peter'	Sender’s first name
sender_last_name	No	String	'Lustig'	Sender’s last name
sender_company_name	No	String	'ABC GmbH'	Sender’s company
sender_street	No	String	'Keplerstr.'	Sender’s street
sender_house_no	No	String	'47B'	Sender’s house number
sender_zip	No	String	'68165'	Sender’s ZIP code
sender_city	No	String	'Mannheim'	Sender’s city
send-country	No	String	"de"	Sender's country use ISO 3166-1 alpha-2
sender_phone	No	phone: Use + for the country code (see example)	'+4917621253654'	Sender' phone number
sender_email	No	Email	'[email protected]'	Sender's email address
return_parcel	No	string	'outbound'	Indicates if return label is requested. Supported values: 'outbound' --> only the outbound lablel is provided 'return' --> only the return label is provided 'both' --> outbound and matching return label are provided. Response will contain array in this case
weight	Yes	float	1.12	Shipment weight in kg (including packaging)
reference_number	no	string	'Order Reference 1234'	Reference information as shown on the outbound label
is_express	no	Boolean	'false'	field for upcoming additional services. Currently not in use
carrier_service	yes	String	'standard'	field to indicate carrier services. Please set it to 'standard' if not other option advised by Seven Senders
cod	yes	Boolean	'false'	indicates, if COD payment shall be collected via this shipment. If set to 'true' fields 'cod_value' and 'cod_currency' become mandatory
cod_value	no	float	13.65	COD value to be collected by carrier on parcel delivery. In case field 'cod' is set to true, this field must be filled with a value >0
cod_currency	no	string	'EUR'	currency in which COD value has to be collected

Remarks

If Sender information can be transferred to the label depends on the single implementation.

Usually its already fixed with label implementation. We'll approach you in case these fields need to be filled.

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.

In case you're missing a carrier/country combination please approach us.

Carrier.country	Carrier.name
AT	postat, dpd
BE	bpost, dpd, mondialrelay
CH	swisspost, dpd
DE	,dhl, dgls, hermes, dpd
DK	postnord
ES	celeritas, seur,seur_international
FI	postnord
FR	colissimo, dpd, mondialrelay, gls
GB	royalmail, hermes
IT	brta
LU	dhl, dpd
NL	postnl
NO	postnord
PL	dpd
SE	postnord

Multi-Coli / Multi-Parcel Labels

Intro

Goal: The goals of this document is to describe, how to create labels for a so called multi-coli shipment using the 7S label API.

Definition multi-coli: Multi-coli is an order which is split and shipped in multiple packages/parcels. The split may occur due to weight or size of the individual packages/parcels. All packages/parcels belong to the same order but receive separate labels with their unique reference number.

Note: Before creating Multi-Coli shipments please note the following:

order_id cannot be printed on the label
reference_number has to be unique overall/across all orders, hence can only be used once

Step-by-Step Label Creation for Multi-Coli

Step 1: get token

Step 2: Authorize

Step 3: create order

Request body

Response body

{

"order_id": "Testorder_3456",

"order_url": "flex.nl",

"order_date": "2020-05-26T13:31:42.470Z",

"boarding_complete": true,

"language": "en",

"promised_delivery_date": "2020-05-26T13:31:42.470Z"

}

{

"order_id": "Testorder_3456",

"order_url": "flex.nl",

"order_date": "2020-05-26T13:31:42+00:00",

"boarding_complete": true,

"state": "new",

"language": "en",

"states_history": [

{

"order_id": "Testorder_3456",

"state": "new",

"datetime": "2020-05-26T13:31:42+00:00",

"location": null

}

"order_tags": [],

"promised_delivery_date": "2020-05-26T13:31:42+00:00",

"tracking_page_url": "https://Flex_Test.tracking.7senders.com/#/order/Testorder_3456"

}

Step 4: create label/package number 1

Request body
Response body
{
  "format": "pdf",
  "reference_number": "package_2222",
  "sender_first_name": "First name",
  "sender_last_name": "Name",
  "sender_company_name": "Company",
  "sender_street": "Street",
  "sender_house_no": "1",
  "sender_zip": "12345",
  "sender_city": "City",
  "sender_country": "NL",
  "sender_phone": "123456789",
  "sender_email": "[email protected]",
  "cod": false,
  "order_id": "Testorder_3456",
  "carrier": {
    "name": "postnl",
    "country": "NL"
  },
  "carrier_service": "standard",
  "recipient_first_name": "First name",
  "recipient_last_name": "Name",
  "recipient_company_name": "Company",
  "recipient_email": "[email protected]",
  "recipient_street": "street",
  "recipient_house_no": "2",
  "recipient_zip": "12345",
  "recipient_city": "city",
  "recipient_country": "NL",
  "recipient_phone": "123456789",
  "return_parcel": "both",
  "weight": 1.5
}
{
  "reference_number": "package_2222",
  "tracking_code": "3SABCD0000280",
  "outbound": {
    "label_url": "https://api.sevensenders.com/v2/label-download/816413",
    "shipment_id": "60206543",
    "tracking_code": "3SABCD0000846",
    "print_format": "A6",
    "mime_type": "application/pdf"
  },
  "return": {
    "label_url": "https://api.sevensenders.com/v2/label-download/816414",
    "shipment_id": "60206544",
    "tracking_code": "3SABCD0000280",
    "print_format": "A6",
    "mime_type": "application/pdf"
  }
}

Step 5: create label/package number 2

Differences to step 4:

reference_number
recipient_first_name
recipient_last_name

Request body
Response body
{
  "format": "pdf",
  "reference_number": "package_3333",
  "sender_first_name": "First name",
  "sender_last_name": "Name",
  "sender_company_name": "Company",
  "sender_street": "Street",
  "sender_house_no": "1",
  "sender_zip": "12345",
  "sender_city": "City",
  "sender_country": "NL",
  "sender_phone": "123456789",
  "sender_email": "[email protected]",
  "cod": false,
  "order_id": "Testorder_3456",
  "carrier": {
    "name": "postnl",
    "country": "NL"
  },
  "carrier_service": "standard",
  "recipient_first_name": "First name2",
  "recipient_last_name": "Name2",
  "recipient_company_name": "Company",
  "recipient_email": "[email protected]",
  "recipient_street": "street",
  "recipient_house_no": "2",
  "recipient_zip": "12345",
  "recipient_city": "city",
  "recipient_country": "NL",
  "recipient_phone": "123456789",
  "return_parcel": "both",
  "weight": 1.5
}
{
  "reference_number": "package_3333",
  "tracking_code": "3SABCD0000281",
  "outbound": {
    "label_url": "https://api.sevensenders.com/v2/label-download/816416",
    "shipment_id": "60206761",
    "tracking_code": "3SABCD0000847",
    "print_format": "A6",
    "mime_type": "application/pdf"
  },
  "return": {
    "label_url": "https://api.sevensenders.com/v2/label-download/816417",
    "shipment_id": "60206763",
    "tracking_code": "3SABCD0000281",
    "print_format": "A6",
    "mime_type": "application/pdf"
  }
}

Step 6: download label

Label number 1Label number 2

Did you find it helpful? Yes No

Label number 1	Label number 2