Content
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'} | |||
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. | |
Yes | String | 'DE' | Please always provide here the country of the injection hub. | |
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 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 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 1 | Label number 2 |
 |  |