This document is a specification for web service API integration for external clients. The web service API provides methods for creating shipments, printing parcels, pickup requests, tracking and etc.

To get a test account please send us an e-mail to Register and provide the following info:

Name
Company name
Direct Phone number
Skype Name (if available)

To get technical support for the integration please send us an e-mail to Tech Support and provide the following info:

UserName
Error context (if relevant)
Error message (if relevant)

and detailed explanation of the situation you need support for.

1.1 Scope

This document specifies Web Service API used to connect external customers to the core system functionality to create, print or track shipments and parcels, using available courier services with their limitations, additional services and options.

1.2 Terms And Conditions

Date data types referred in this document that contains actual dates (without time) should be passed as “yyyy-MM-dd” formatted string in the request. Date responses are in the same format.
Date data types referred in this document as datetime should be passed as “yyyy-MM-ddTHH:mm:ssZ” formatted string in the request. Datetime responses are in the same format.
Boolean data types referred in this document in url based requests could be passed as “true/false, 1/0, y/n, yes/no” case insensitive values. In JSON fields boolean values allowed are only “true/false”.
Response data structures may be changed in the future adding additional fields. Therefore, client applications should be able to accept unknown fields in responses for backward compatibility

1.3 Overview

The document specifies communication protocol for integration, which is request/response based over HTTP. Each method provides REST/JSON schema to send requests to the server and receive response in JSON (but not in any case) format.

In addition, each method supports URL GET schema to simplify integrations. This approach is a deviation from standard REST patterns for implementation, but however is identified as easy for integration, well accepted and requested by customers.

The web service API requires user password authentication for each method. All users have a reference to a single client. Some clients may have contracts which include more than one member (different departments/offices etc). Depending on his/her permissions, a user is either allowed to work with shipments of these members or not.

1.4 JSON Schema

API JSON schema is available for download here

1.5 Examples

Examples can be found here

2 Overall Description

BASE_URL=_

2.1 Shipment Service

Web service URL: BASE_URL/shipment

2.1.1 Create Shipment Request (CreateShipmentRequest)

Method: POST

Content-type: application/json; charset=utf-8

Input parameters:

CreateShipmentRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
sender	ShipmentSender	No	Defines the sender of the shipment and shipment's pickup place. If not specified, the logged user is considered as a sender.
recipient	ShipmentRecipient	Yes	Defines the recipient of the shipment and shipment’s delivery place.
service	ShipmentService	Yes	Defines shipment service level agreement.
content	ShipmentContent	Yes	Defines shipment’s content - number of parcels, weight, size, etc.
payment	ShipmentPayment	Yes	Defines who-pays-what in shipment and other payment parameters.
shipmentNote	String	No	Customer’s note associated with the shipment.	200 characters
ref1	String	No	Reference number or text.	30
ref2	String	No	Reference number or text.	30
consolidationRef	String	No	Consolidation reference number or text.	30
requireUnsuccessfulDeliveryStickerImage	Boolean	No	Require unsuccessful delivery sticker image flag.

Example Request:

{

"userName":"testUser",

"password":"password",

"service":{

"serviceId":2002,

"additionalServices":{

"declaredValue":{

"amount":100.0

"returns":{

"rod":{

"enabled":true

"returnReceipt":{

"enabled":true

"swap":{

"serviceId":2002,

"parcelsCount":1

}

"content":{

"parcelsCount":1,

"totalWeight":20.0,

"contents":"FURNITURE",

"package":"BOX"

"payment":{

"courierServicePayer":"SENDER"

"recipient":{

"phone1":{

"number":"0999123321"

"privatePerson": true,

"clientName":"TEST",

"contactName":"TEST",

"email":"[email protected]",

"address":{

"siteName":"Sibiu",

"streetType":"str.",

"streetName":"ACILIU",

"streetNo":"3"

}

"shipmentNote":"Test note",

"ref1":"R1",

"ref2":"R2"

}

2.1.2 Create Shipment Response (CreateShipmentResponse)

Output parameters:

CreateShipmentResponse
Name	Type	Data
id	String	Generated shipment id.
parcels	CreatedShipmentParcel[]	Generated parcels.
price	ShipmentPrice	Returned, if customer has access to view the amounts of the shipment.
pickupDate	Date (date)	Shipment pickup date.
deliveryDeadline	Date (datetime)	Deadline for delivery. Returned, if available.
error	Error	Response error.

Example response:

{

"id":"80002589418",

"pickupDate":"2018-01-22",

"price":{

"amount":47.17,

"vat":8.96,

"total":56.13,

"details":{

"netAmount":{

"amount":46.5,

"vatPercent":0.19

"fixedDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"dropOffDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"pickUpDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"additionalDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"fuelSurcharge":{

"amount":0.47,

"percent":1.0,

"vatPercent":0.19

"islandSurcharge":{

"amount":0.0,

"vatPercent":0.19

"codPremium":{

"amount":0.0,

"vatPercent":0.19

"insurancePremium":{

"amount":0.2,

"vatPercent":0.19

}

"amountLocal":47.17,

"vatLocal":8.96,

"totalLocal":56.13,

"currencyLocal":"RON",

"detailsLocal":{

"netAmount":{

"amount":46.5,

"vatPercent":0.19

"fixedDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"dropOffDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"pickUpDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"additionalDiscount":{

"amount":0.0,

"percent":0.0,

"vatPercent":0.19

"fuelSurcharge":{

"amount":0.47,

"percent":1.0,

"vatPercent":0.19

"islandSurcharge":{

"amount":0.0,

"vatPercent":0.19

"codPremium":{

"amount":0.0,

"vatPercent":0.19

"insurancePremium":{

"amount":0.2,

"vatPercent":0.19

}

"currencyExchangeRateUnit":1,

"currencyExchangeRate":1.0

"deliveryDeadline":"2018-01-23T17:30:00+0200"

}

2.1.3 Create Shipment - URL (GET) Schema

This approach is used to create shipments, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment

Method: GET

Content-type: “application/x-www-form-urlencoded; charset=utf-8”

The response is the same as method using JSON schema.

URL parameters:

CreateShipmentRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
Sender details If the logged user is the sender, you may skip providing sender details at all. If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also. However, in these cases, if the user needs to change the defaults stored in the system, the following parameters could be provided in addition: sender phone(s) sender contact in case the referred customer is a company (not a private person), otherwise should be skipped sender email sender address note If you provide information in other sender parameters, you’ll receive an error that data is not expected in that field. Otherwise, sender_id should stay empty and it is required to provide as a minimum: sender phone sender name sender privatePerson flag sender contact in case privatePerson is false, otherwise should be skipped sender address or dropoffOfficeId
senderId \| sender_id	Long	No.	Client id to refer а sender.	Validated for existence.
senderPhone \| sender_phone	String	Mandatory in case sender_id is empty and sender_name is not. Otherwise, it is allowed but not mandatory.	Sender phone number.
senderPhoneExt \| sender_phone_ext	String	No	Sender phone number extension.
senderPhone2 \| sender_phone2	String	No	Sender phone number 2.
senderPhone2Ext \| sender_phone2_ext	String	No	Sender phone number 2 extension.
senderPhone3 \| sender_phone3	String	No	Sender phone number extension.
senderPhone3Ext \| sender_phone3_ext	String	No	Sender phone number 3 extension.
senderName \| sender_name	String	If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory.	Sender name.	Minimum 3 symbols, maximum 60
senderContact \| sender_contact	String	No Required, if privatePerson flag is false.	Sender contact name.	Maximum 60 symbols.
senderEmail \| sender_email	String	No	Sender email.	Maximum 255 symbols.
senderPrivatePerson \| sender_private_person	Boolean (true/false, y/n, “yes/no” - all case insensitive)	If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory.	Sender private person flag.
Sender Address See ShipmentAddress for more details. The sender address is expected when sender_id is empty and sender_name is not and sender_dropoff_office_id is empty and not required. In other words, the sender address is required when the sender is not a referred customer or logged user and pickup at sender’s address is expected.
senderAddressCountryId \| sender_address_country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.
senderAddressStateId \| sender_address_state_id	String	Required, if country supports states.	Country state. Used for addresses of type 2 (foreign address).
senderAddressSiteId \| sender_address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided.	Site id. Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country
senderAddressSiteType \| sender_address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address).	Max 20
senderAddressSiteName \| sender_address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50
senderAddressPostcode \| senderAddressPostCode \| sender_address_postcode	String	No	Can be used in conjunction with countryId to find unique site. Used for all address types.	Validated for valid postcode in site and country. Max 10
senderAddressStreetId \| sender_address_street_id	Long	No	Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
senderAddressStreetType \| sender_address_street_type	String	No Forbidden, if street_id is provided.	Street type. Used for addresses of type 1 (local address).	Max 15
senderAddressStreetName \| sender_address_street_name	String	No Forbidden, if street_id is provided.	Street name. Used for addresses of type 1 (local address).	Max 50
senderAddressStreetNumber \| sender_address_street_number	String	No	Street number. Used for addresses of type 1 (local address).	Max 10
senderAddressComplexId \| sender_address_complex_id	Long	No	Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
senderAddressComplexType \| sender_address_complex_type	String	No Forbidden, if complex_id is provided.	Complex type. Used for addresses of type 1 (local address).	Max 15
senderAddressComplexName \| sender_address_complex_name	String	No Forbidden, if complex_id is provided.	Complex name. Used for addresses of type 1 (local address).	Max 50
senderAddressBlock \| senderAddressBlockNo \| sender_address_block	String	No	Block No. Used for addresses of type 1 (local address).	Max 32
senderAddressEntrance \| senderAddressEntranceNo \| sender_address_entrance	String	No	Entrance. Used for addresses of type 1 (local address).	Max 10
senderAddressFloor \| senderAddressFloorNo \| sender_address_floor	String	No	Floor. Used for addresses of type 1 (local address).	Max 10
senderAddressApartment \| senderAddressApartmentNo \| sender_address_apartment	String	No	Apartment. Used for addresses of type 1 (local address).	Max 10
senderAddressPoiId \| sender_address_poi_id	Long	No	Point of interest identifier. Used for addresses of type 1 (local address).
senderAddressNote \| sender_address_note	String	No	Address note. Used for addresses of type 1 (local address).	200
senderAddressLine1 \| sender_address_line1	String	Required for address type 2.	Address line 1. Used for addresses of type 2 (foreign address).	Max 35
senderAddressLine2 \| sender_address_line2	String	No	Address line 2. Used for addresses of type 2 (foreign address).	Max 35
senderAddressX \| sender_address_x	Double	No	GIS coordinates - X. Used for all address types.
senderAddressY \| sender_address_y	Double	No	GIS coordinates - Y. Used for all address types.
dropoffOfficeId \| dropOffOfficeId \| senderDropoffOfficeId \| senderDropOffOfficeId \| dropoff_office_id \| sender_dropoff_office_id	Integer	Required, if the sender is an internal customer. If sender address is provided, it is forbidden.	Drop off office id.	Should refer to a valid accessible office.
sender_geo_pudo_id \| senderGeoPUDOId \| senderDropoffGeoPUDOId \| senderDropOffGeoPUDOId \| dropoff_geo_pudo_id \| dropoff_geo_pudo_id \| dropoffGeoPUDOId \| dropOffGeoPUDOId	String	No. Must be empty if dropoffOfficeId is provided	DPD drop off office PUDO id	Should refer to a valid accessible DPD office.
Shipment Recipient If you refer an existing customer, provide client’s id in recipient_id parameter and other recipient parameters may be skipped at all. However, if the user needs to change the defaults stored in the system, the following parameters could be provided in addition: recipient phone(s) recipient contact in case the referred customer is a company (not a private person), otherwise should be skipped recipient email recipient address note If you provide information in other recipient parameters, you’ll receive error that data is not expected in that field. Otherwise, recipient_id should stay empty and it is required to provide as a minimum: recipient phone - could be omitted but is required for the same day delivery services, saturday delivery and delivery abroad recipient name recipient privatePerson flag recipient contact in case privatePerson is false otherwise should be skipped recipient address or pickupOfficeId
recipientId \| recipient_id	Long	No.	Client id to refer a recipient.	Validated for existence.
recipientPhone \| recipient_phone	String	Mandatory in case recipient_id is empty and recipient_name is not. Otherwise, it is allowed but not mandatory.	Recipient phone number.
recipientPhoneExt \| recipient_phone_ext	String	No	Recipient phone number extension.
recipientPhone2 \| recipient_phone2	String	No	Recipient phone number 2.
recipientPhone2Ext \| recipient_phone2_ext	String	No	Recipient phone number 2 extension.
recipientPhone3 \| recipient_phone3	String	No	Recipient phone number extension.
recipientPhone3Ext \| recipient_phone3_ext	String	No	Recipient phone number 3 extension.
recipientName \| recipient_name	String	If recipient_id is provided, it is forbidden. Otherwise, it is mandatory.	Recipient name.	Minimum 3 symbols, maximum 60
recipientContact \| recipient_contact	String	No Required, if privatePerson flag is false.	Recipient contact name.	Maximum 60.
recipientEmail \| recipient_email	String	No	Recipient email.	Maximum 255. Mandatory for international shipments
recipientPrivatePerson \| recipient_private_person	Boolean (true/false, y/n, “yes/no” - all case insensitive)	If recipient_id is provided, it is forbidden. Otherwise, it is mandatory.	Recipient private person flag.
Recipient Address See ShipmentAddress for more details. The recipient address is expected when recipient_id is empty and recipient_name is not and recipient_pickup_office is empty and not required. In other words, the recipient address is required when the recipient is not a referred customer and delivery at recipient’s address is expected.
recipientAddressCountryId \| recipient_address_country_id	Integer	No	Country ISO code. If not provided, local country is assumed. Used for all address types.
recipientAddressStateId \| recipient_address_state_id	String	Required, if country supports states.	Country state. Used for addresses of type 2 (foreign address).
recipientAddressSiteId \| recipient_address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided.	Site id. Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country
recipientAddressSiteType \| recipient_address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address).	Max 20
recipientAddressSiteName \| recipient_address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50
recipientAddressPostcode \| recipientAddressPostCode \| recipient_address_postcode	String	No	Can be used in conjunction with countryId to find unique site. Used for all address types.	Validated for valid postcode in site and country. Max 10
recipientAddressStreetId \| recipient_address_street_id	Long	No	Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
recipientAddressStreetType \| recipient_address_street_type	String	No Forbidden, if street_id is provided.	Street type. Used for addresses of type 1 (local address).	Max 15
recipientAddressStreetName \| recipient_address_street_name	String	No Forbidden, if street_id is provided.	Street name. Used for addresses of type 1 (local address).	Max 50
recipientAddressStreetNumber \| recipient_address_street_number	String	No	Street number. Used for addresses of type 1 (local address).	Max 10
recipientAddressComplexId \| recipient_address_complex_id	Long	No	Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
recipientAddressComplexType \| recipient_address_complex_type	String	No Forbidden, if complex_id is provided.	Complex type. Used for addresses of type 1 (local address).	Max 15
recipientAddressComplexName \| recipient_address_complex_name	String	No Forbidden, if complex_id is provided.	Complex name. Used for addresses of type 1 (local address).	Max 50
recipientAddressBlock \| recipientAddressBlockNo \| recipient_address_block	String	No	Block No. Used for addresses of type 1 (local address).	Max 32
recipientAddressEntrance \| recipientAddressEntranceNo \| recipient_address_entrance	String	No	Entrance. Used for addresses of type 1 (local address).	Max 10
recipientAddressFloor \| recipientAddressFloorNo \| recipient_address_floor	String	No	Floor. Used for addresses of type 1 (local address).	Max 10
recipientAddressApartment \| recipientAddressApartmentNo \| recipient_address_apartment	String	No	Apartment. Used for addresses of type 1 (local address).	Max 10
recipientAddressPoiId \| recipient_address_poi_id	Long	No	Point of interest identifier. Used for addresses of type 1 (local address).
recipientAddressNote \| recipient_address_note	String	No	Address note. Used for addresses of type 1 (local address).	200
recipientAddressLine1 \| recipient_address_line1	String	Required for address type 2	Address line 1. Used for addresses of type 2 (foreign address).	Max 35
recipientAddressLine2 \| recipient_address_line2	String	No	Address line 2. Used for addresses of type 2 (foreign address).	Max 35
recipientAddressX \| recipient_address_x	Double	No	GIS coordinates - X. Used for all address types.
recipientAddressY \| recipient_address_y	Double	No	GIS coordinates - Y. Used for all address types.
pickupOfficeId \| pickUpOfficeId \| recipientPickupOfficeId \| recipientPickUpOfficeId \| pickup_office_id \| recipient_pickup_office_id	Integer	Required, if recipient is internal client. If recipient address is provided, it is forbidden	Pickup office id.	Should refer to valid accessible office.
recipient_geo_pudo_id \| recipientGeoPUDOId \| recipientPickupGeoPUDOId \| recipientPickUpGeoPUDOId \| pickup_geo_pudo_id \| pickupGeoPUDOId \| pickUpGeoPUDOId	String	No. Must be empty if pickupOfficeId is provided	DPD pickup office PUDO id	Should refer to a valid accessible DPD office.
Shipment Service See ShipmentService for more details. Shipment service defines agreement with customer for courier service. This includes: Pickup date Service id (code) Optional defer days or saturday delivery Additional services (like COD, Declared value, SWAP, ROD and etc.)
pickupDate \| pickup_date	Date (date) Example: “2017-12-11"	No (default value is today)	The date for shipment pick-up.	Could be today or a future date.
autoAdjustPickupDate \| auto_adjust_pickup_date \| autoadjust_pickup_date	Boolean	No (default is false)	To find first available date for pickup starting from pickupDate according to pickup schedule for services
serviceId \| service_id	int	Yes	Service to be used for shipment.	Service id (code) should be valid for destination.
deferredDays \| deferred_days	Integer	No (default value is 0)	This parameter allows users to specify by how many (business) days they would like to postpone the shipment delivery from the standard term.	Allowed values are 0, 1 and 2.
saturdayDelivery \| saturday_delivery	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	This parameter may adjust the delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured recipient working schedule.
COD Additional Service For more information see ShipmentCODAdditionalService.
codAmount \| cod_amount	double	No	Defines shipment COD base amount.	Validated against maximum allowed amounts for destination.
codCurrency \| cod_currency	String	No (default is the currency code of the destination country)	Defines shipment COD currency code.	Validated against allowed currency code of destination country.
codProcessingType \| cod_processing_type	enum [“CASH”, “POSTAL_MONEY_TRANSFER”]	No (default is “CASH”)	Defines COD processing type.	Appropriate contract and annexes may be required.
codPayoutThirdParty \| cod_payout_third_party	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	If this flag is set, the COD is paid to a third party (not to the sender).	Requires the third party to be the payer of the courier service.
codPayoutLoggedClient \| cod_payout_logged_client	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	If this flag is set, the COD is paid to a logged client.
codWithShippingPrice \| cod_with_shipping_price	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Flag indicating whether the shipping price should be included in the COD.
codCardPaymentForbidden \| cod_card_payment_forbidden	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Flag indicating that COD/PMT card payment is forbidden.
Options before payment details Additional Service For more information see ShipmentOBPD.
obpd_option	enum [“OPEN”, “TEST”]	No (For certain destinations could be required.)	Defines option to be used. Open parcels before payment or open and test parcels before payment.	Return shipment is validated for destination.
obpd_return_service_id	Integer	No (For certain destinations could be required.)	Defines service id to be used on return, if COD payment is refused.	Return shipment is validated for destination.
obpd_return_payer	enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”]	No (For certain destinations could be required.)	Defines who pays the return shipment, if COD payment is refused.	Return shipment is validated for destination.
Declared Value (Extended Liability) Additional Service For more information see ShipmentDeclaredVaueAdditionalService. Declared value payer is required when declared value amount is provided and is set in payment section.
declaredValueAmount \| declared_value_amount	double	No	Defines shipment Declared Value (extended liability) base amount. Declared value amount is always in local system currency.	Validated against maximum allowed amounts.
fragile \| declaredValueFragile \| declared_value_fragile	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Defines fragile flag for shipment content.	Fragile shipments requires declared value sub service.
Fixed Time Delivery Additional Service Fixed time delivery is an additional service that provides instruction to deliver shipment at a certain time on the delivery date.
fixedTimeDelivery \| fixed_time_delivery	Integer	No	This option fixes the time of delivery on the delivery date. 1130 - means 11:30 920 - means 09:20	This option is checked against configured allowed time frame for the service.
Return of Documents (ROD) Additional Service For more information see ShipmentRODAdditionalService. Return documents is an additional service that provides instruction to collect documents on shipment delivery in return.
rodEnabled \| rod_enabled	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Enabled flag
rodComment \| rod_comment	String	No	Return documents comment.	Max size 512
rodReturnToClientId \| rod_return_to_client_id	Long	No	Defines customer - recipient for the ROD shipment. If not specified and rod_return_to_office_id is not specified also, the reverse shipment is returned to the primary shipment sender.	Cannot be specified together with rod_return_to_office_id. The same value should be set for ROD and Return Receipt, if the sub-service presents. Cannot be specified if SWAP presents
rodReturnToOfficeId \| rod_return_to_office_id	Integer	No	Defines delivery pickup depot for ROD shipment. If not specified and rod_return_to_client_id is not specified also, the return shipment is returned to primary shipment sender.	Cannot be specified together with rod_return_to_client_id. The same value should be set for ROD, Return Receipt and SWAP, if the sub-service presents.
rodThirdPartyPayer \| rod_third_party_payer	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Defines a third party payer for ROD shipment. Otherwise, payer is the primary shipment sender.	Requires a third party payer of the primary shipment. The same value should be set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents.
Return Receipt Additional Service For more information see ShipmentReturnReceiptAdditionalService. Return receipt is an additional service that provides instruction to collect a receipt on shipment delivery in return.
receiptEnabled \| receipt_enabled	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Enabled flag
receiptReturnToClientId \| receipt_return_to_client_id	Long	No	Defines customer - recipient for the Return Receipt shipment. If not specified and receipt_return_to_office_id is not specified also, the return shipment is returned to the primary shipment sender.	Cannot be specified together with receipt_return_to_office_id. The same values should be set for ROD and Return Receipt, if the sub service presents. Cannot be specified if SWAP presents
receiptReturnToOfficeId \| receipt_return_to_office_id	Integer	No	Defines delivery pickup depot for the Return Receipt shipment. If not specified and receipt_return_to_client_id is not specified also, the return shipment is returned to the primary shipment sender.	Cannot be specified together with receipt_return_to_client_id. The same values should be set for ROD, Return Receipt and SWAP, if the sub service presents.
receiptThirdPartyPayer \| receipt_third_party_payer	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Defines a third party payer for the Return Receipt shipment. Otherwise, payer is the primary shipment sender.	Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
SWAP Additional Service For more information see ShipmentSWAPAdditionalService. SWAP is an additional service that provides instruction to collect a reverse shipment with predefined parameters on shipment delivery in return.
swapServiceId \| swap_service_id	int	No	Service to be used in return.	Validated for allowance and destination.
swapParcelsCount \| swap_parcels_count	int	No	Number of parcels to return.	Validated against maximum allowed parcels.
swapDeclaredValueAmount \| swap_declared_value_amount	Double	No	Declared value for the reverse shipment.	Validated for allowance and maximum amount.
swapDeclaredValueFragile \| swap_declared_value_fragile	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Fragile content flag for the reverse shipment.	Fragile shipments requires declared value.
swapReturnToOfficeId \| swap_return_to_office_id	Integer	No	Defines delivery pickup depot for the SWAP shipment. If not specified, the return shipment is returned to the primary shipment sender.	The same value should be set for ROD, Return Receipt and SWAP, if sub-service presents.
swapThirdPartyPayer \| swap_third_party_payer	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Defines a third party payer for the SWAP shipment. Otherwise, payer is the primary shipment sender.	Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
Return of Pallets (ROP) Additional Service For more information see ShipmentROPAdditionalService. Return of pallets is an additional service that provides instruction to collect pallets (used to wrap parcels for transport) in return.
ropPallets \| rop_pallets	String Format for single pair is: “<serviceId>,<parcelsCount>” Multiple pairs are separated with %7C (‘\|’) character. See ShipmentROPAdditionalServiceLine	No	Defines pallets to return grouped by service id.	Total number of returned pallets should not exceed parcels count of the primary shipment.
ropThirdPartyPayer \| rop_third_party_payer	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Defines a third party payer for the returned pallets. Otherwise, payer is the primary shipment sender.	Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
Return Voucher Additional Service For more information see ShipmentReturnVoucherAdditionalService. Return voucher provides an option for the recipient to initiate a return, based on the delivered shipment, within predefined voucher validity period.
voucherServiceId \| voucher_service_id	int	No	Service id of the return voucher shipment.
voucherPayer \| voucher_payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	No	Defines the return voucher payer.	Allowed payers are validated against service configuration and destination.
voucherValidityPeriod \| voucher_validy_period	Integer	Required if caller client has no annex for return voucher.	Return voucher validity period in days. The annex return voucher period is used by default in case caller client has such in his contract and value is omitted	Verified to not exceed the configured internal maximum in the system
Special Delivery Additional Service Special delivery is an additional service that provides instruction to the courier to do additional (special) checks and actions on delivery. These checks and actions are negotiated and contracted in a special delivery annex. For example, the courier could be instructed to check IDs of recipient party at delivery.
specialDeliveryId \| special_delivery_id	Integer	No	Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex.	Requires annex for special delivery.
Delivery to Floor Additional Service Delivery to floor is an additional service that provides instruction to the courier that the shipment should not be delivered to the entrance of a multi floor building, but should be moved to a certain floor before delivery.
deliveryToFloor \| delivery_to_floor	Integer	No	Specifies the floor number in the building where to deliver shipment.	This additional service requires annex.
Shipment Content For more information see ShipmentContent. Defines what is to be delivered with the shipment.
parcelsCount \| parcels_count	Integer	Required when parcels list is empty and pending_parcels is false.	Total shipment’s parcels count. Ignored, if parcels list is not empty. The parcels count is the number of parcels in the lits in that case.	Validated against minimum and maximum allowed for the service.
totalWeight \| total_weight	Double	Required when parcels list is empty and pending_parcels is false.	Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcel’s weight in that case.	Validated against minimum and maximum allowed for the service.
contents	String	Yes	Shipment’s contents description.	100
package	String	Yes	Shipment’s package.	50
documents	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Documents flag of the shipment.
palletized	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Palletized flag of the shipment.
parcels	String Format for single parcel is: <seqNo>,<weight>, <width>x<depth>x<height>, <packageUniqueNumber>, <id>, <ignored, kept for backward compatibility>, <ref1>, <ref2>, <Pickup External Carrier Parcel number in format carrier name-parcelnumber>, <Delivery External Carrier Parcel number in format carrier name-parcelnumber> Multiple parcels should be separated with %7C (‘\|’) character. See ShipmentParcel	Required for pallet and postal services. For multiple parcels add the same url parameter again. The parameters are parsed in the order of their occurrence. If the sequence is incomplete, the missing parameters are considered empty.	Parcels. If omitted, a single default (first) parcel will be created for non-pallet and non-postal services.	Validated against service configuration and pickup and delivery capacity of the depots and the couriers.
pendingParcels \| pending_parcels	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Partial shipment flag indicating parcels are not complete and new parcels are expected.
exciseGoods \| excise_goods	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Flag shipment contains excise goods.
Shipment Payment For more information see ShipmentPayment. Defines who-pays-what in shipment and other payment parameters.
courierServicePayer \| courier_service_payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	Yes	Courier service payer.	Validated against the service, destination, contracts and annexes.
declaredValuePayer \| declared_value_payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	No	Declared value payer. If not provided, the courier service payer is assumed. Not expected, if the declared value amount is empty.	Validated against the service, destination, contracts and annexes.
packagePayer \| package_payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	No	Package payer. If not provided, the courier service payer is assumed.	Validated against the service, destination, contracts and annexes.
thirdPartyClientId \| third_party_client_id	Long	No	Defines shipment third party - used as a payer of any of shipment payable components.	Third party customer should be registered customer with valid contract and annex for delayed payment at pickup date. Third party customer should be customer(object) in the same contract as the logged user.
Discount card For more information see ShipmentDiscountCardId. Discount cards provide promotional discounts.
discountCardContractId \| discount_card_contract_id	Long	No	Discount card contract id.	Validated against a referred contract.
discountCardId \| discount_card_id	Long	No	Discount card id for contract.	Validated against a referred discount card.
Sender Bank account For more information see BankAccount. Sender COD payout bank account.
senderBankAccountIban \| sender_bank_account_iban	String	No	Sender bank account iban	IBAN format validation is applied
senderBankAccountHolder \| sender_bank_account_holder	String	No	Sender bank account holder	Max 60 characters
administrativeFee \| administrative_fee	Boolean	No	Flag to apply administrative fee on price calculations	Usage of administrative fee is enabled and configured in client contract. Ignored if not applicable for user.
Common parameters
shipmentNote \| shipment_note	String	No	Customer note associated with the shipment.	200 characters
ref1	String	No	Reference number or text.	30
ref2	String	No	Reference number or text.	30
consolidation_ref \| consolidationRef	String	No	Consolidation reference number or text.	30
require_unsuccessful_delivery_sticker_image \| requireUnsuccessfulDeliveryStickerImage	Boolean	No	Require unsuccessful delivery sticker image flag.

Examples:

BASE_URL/shipment?username=test&password=test&language=EN&sender_id=34993782000&recipient_id=34993782000&service_id=2113&parcels_count=1&total_weight=3&courier_service_payer=SENDER&contents=FURNITURE&package=BOX

BASE_URL/shipment?username=test&password=test&language=EN&sender_id=34993782000&service_id=2002&courier_service_payer=SENDER&contents=FURNITURE&package=BOX&recipient_address_site_name=SIBISEL&recipient_name=Mr.%20Name&recipient_address_postcode=337083&recipient_address_street_name=STREET%20NAME&recipient_address_country_id=642&recipient_private_person=y&parcels=1,5,8x8x8%7C2,3,8x8x8&recipient_phone=423234&recipient_phone_ext=33&pickup_date=2017-12-06&cod_amount=33&cod_currency=RON&swap_service_id=2002&swap_parcels_count=2&swap_declared_value_amount=33

2.1.4 Cancel Shipment Request (CancelShipmentRequest)

Web service URL: BASE_URL/shipment/cancel

Method: POST

Content-type: application/json; charset=utf-8

Web service URL: BASE_URL/shipment

Method: DELETE

Content-type: application/json; charset=utf-8

Cancel shipment. Shipment can be cancelled, it is not ordered yet.

CancelShipmentRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
shipmentId	String	Yes	Shipment id	Should have access rights to cancel the shipment.
comment	String	Yes	Cancel comment	Max 1024

Example JSON:

{

"userName":"testUser",

"password":"password",

"shipmentId":"80002589418",

"comment":"Cancel comment"

}

2.1.5 Cancel Shipment Response (CancelShipmentResponse)

Cancel response is an empty JSON, if the shipment is successfully cancelled. Otherwise, an error is included.

CancelShipmentResponse
Name	Type	Data
error	Error	Response error

Example JSON:

{}

2.1.6 Cancel Shipment - URL (GET) schema

This approach is used to cancel shipments, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/cancel

Method: GET

Content-type: “application/x-www-form-urlencoded; charset=utf-8”

The response is the same as method using JSON schema.

URL parameters:

CancelShipmentRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
shipmentId \| shipment_id	String	Yes	Shipment id	Should have access rights to cancel shipment.
comment	String	Yes	Cancel comment	Max 1024

2.1.7 Add parcel Request (AddParcelRequest)

Parcels can be added to shipments in pending parcels state (shipments created with pendingParcels flag true)

Web service URL: BASE_URL/shipment/add_parcel

Method: POST

Content-type: application/json; charset=utf-8

AddParcelRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
shipmentId	String	Yes	Shipment id	Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).
parcel	ShipmentParcel	Yes	Parcel to add. Parcel id and sequence number are auto-generated and therefore ignored if present in request
codAmount	Double	No	COD amount to add with this parcel to increase total COD amount
declaredValueAmount	Double	No	Declared value (extended liability) amount to add with this parcel to increase total amount	If this parcel increases the amount of declared value, the shipment should be opened with Declared value (extended liability) additional service

Example JSON:

{

"userName":"testUser",

"password":"password",

"shipmentId":"80002589418",

"parcel": {

"weight":3,

"size": {

"width":5,

"height":5,

"depth":5

}

"codAmount":5.0

}

2.1.8 Add Parcel Response (AddParcelResponse)

Add parcel response returns generated parcel. Otherwise, an error is included.

CancelShipmentResponse
Name	Type	Data
parcel	CreatedShipmentParcel	Created shipment parcel (with generated id and sequence number)
error	Error	Response error

Example JSON:

{}

2.1.9 Add parcel Request (AddParcelRequest) - URL (GET) Schema

This approach is used to add parcels, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/add_parcel

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

AddParcelRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
shipmentId \| shipment_id	String	Yes	Shipment id	Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).
weight	Double	Yes	Parcel weight
size	String Format is <width>x<depth>x<height>	No (Required for pallet and postal services)	Parcel size
packageUniqueNumber \| package_unique_number	Long	No	Parcel package unique number
externalCarrierParcelNumber \| external_carrier_parcel_number	String	No	External carrier parcel id
codAmount \| cod_amount	Double	No	COD amount to add with this parcel to increase total COD amount
declaredValueAmount \| declared_value_amount	Double	No	Declared value (extended liability) amount to add with this parcel to increase total amount	If this parcel increases the amount of declared value, the shipment should be opened with Declared value (extended liability) additional service

Example request:

BASE_URL/shipment/add_parcel?username=test&password=test&language=EN&shipment_id=89981002110&size=10x15x20&weight=13.5&cod_amount=5

2.1.10 Finalize Pending Shipment Request (FinalizePendingShipmentRequest)

Pending shipments (opended with pendingParcels flag equal to true) should be finalized with this method

Web service URL: BASE_URL/shipment/finalize

Method: POST

Content-type: application/json; charset=utf-8

FinalizePendingShipmentRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
shipmentId	String	Yes	Shipment id	Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).

Example JSON:

{

"userName":"testUser",

"password":"password",

"shipmentId":"80002589418"

}

2.1.11 Finalize Pending Shipment Response (FinalizePendingShipmentResponse)

The response is the same as CreateShipmentResponse.

2.1.12 Finalize Pending Shipment Request (FinalizePendingShipmentRequest) - URL (GET) schema

This approach is used to finalize pending shipments providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/finalize

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FinalizePendingShipmentRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
shipmentId \| shipment_id	String	Yes	Shipment id	Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).

Example request:

BASE_URL/shipment/finalize?username=test&password=test&shipment_id=89981002110

2.1.13 Shipment Information Request (ShipmentInformationRequest)

This method provides shipment information

Web service URL: BASE_URL/shipment/info

Method: POST

Content-type: application/json; charset=utf-8

ShipmentInformationRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
shipmentIds	String[]	Yes	Shipment ids

2.1.14 Shipment Information Response (ShipmentInformationResponse)

ShipmentInformationResponse
Name	Type	Data
shipments	Shipment[]	Shipment information
error	Error	Response error

2.1.15 Shipment Information Request (ShipmentInformationRequest) - URL (GET) schema

This approach is used to get shipment information providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/info

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

ShipmentInformationRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
shipmentIds \| shipment_ids	String[]	Yes	Comma separated list of shipment ids

2.1.16 Secondary Shipments Request (SecondaryShipmentsRequest)

This method provides secodary shipments information

Web service URL: BASE_URL/shipment/{shipmentId}/secondary

Method: POST

Content-type: application/json; charset=utf-8

SecondaryShipmentsRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
types	enum[] (array with values from enum: [“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”]) (Same as enum in field type in PrimaryShipment)	Yes	Filters the list for shipments of the specified type(s) only. No filter is applied if not provided (all secondary shipments are returned). RETURN_SHIPMENT - any of return of documents (rod) / returnReceipt / swap / return of pallets (rop) STORAGE_PAYMENT - warehouse charges REDIRECT - redirect shipment SEND_BACK - return to sender MONEY_TRANSFER - money transfer TRANSPORT_DAMAGED - damaged shipment transport VOUCHER_RETURN - return with voucher

2.1.17 Secondary Shipments Response (SecondaryShipmentsResponse)

SecondaryShipmentsResponse
Name	Type	Data
shipments	SecondaryShipment[]	List of secondary shipments
error	Error	Response error

2.1.18 Secondary Shipments Request - URL (GET) schema

This approach is used to get secondary shipments providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/{shipmentId}/secondary

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

SecondaryShipmentsRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
types	enum[] (array with values from enum: [“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”]) (Same as enum in field type in PrimaryShipment)	Yes	Comma separated list of secondry shipment types. Filters the list for shipments of the specified type(s) only. No filter is applied if not provided (all secondary shipments are returned). RETURN_SHIPMENT - any of return of documents (rod) / returnReceipt / swap / return of pallets (rop) STORAGE_PAYMENT - warehouse charges REDIRECT - redirect shipment SEND_BACK - return to sender MONEY_TRANSFER - money transfer TRANSPORT_DAMAGED - damaged shipment transport VOUCHER_RETURN - return with voucher

2.1.19 Update Shipment Request (UpdateShipmentRequest)

Web service URL: BASE_URL/shipment/update

Method: POST

Content-type: application/json; charset=utf-8

Full update of already created shipment. Allowed only if shipment is not requested for pick up or is not picked up yet.

Currently saved shipment data is cleared and replaced with new shipment data

Input parameters:

UpdateShipmentRequest
Name	Type	Required	Data	Constraints
CreateShipmentRequest fields are here
id	String	Yes	Shipment id	Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update

2.1.20 Update Shipment Response (UpdateShipmentResponse)

Response is CreateShipmentResponse - same returned in createShipment method

Output parameters:

UpdateShipmentResponse
Name	Type	Data
CreateShipmentResponse fields are here

2.1.21 Update Shipment - URL (GET) Schema

This approach is used to update shipments, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/update

Method: GET

Content-type: “application/x-www-form-urlencoded; charset=utf-8”

Full update of already created shipment. Allowed only if shipment is not requested for pick up or is not picked up yet.

Currently saved shipment data is cleared and replaced with new shipment data

The response is the same as method using JSON schema.

URL parameters:

UpdateShipmentRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
CreateShipmentRequest params are here
id	String	Yes	Shipment id	Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update

2.1.22 Update Shipment Properties Request (UpdateShipmentPropertiesRequest)

Web service URL: BASE_URL/shipment/update/properties

Method: POST

Content-type: application/json; charset=utf-8

Update shipment properties. All properties can be changed if shipment is not requested for pick up or is not picked up yet.

Recipient phone and COD properties can be updated after pickup request if shipment is still not given to courier for delivery and is not cancelled or closed

Input parameters:

UpdateShipmentPropertiesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
id	String	Yes	Shipment id	Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update
properties	Map<String, String>	Yes	The map key is shipment property name and the map value is new propery value to be set in shipment.	The allowed key (property) names are the same as url parameter names (synonims) defined in CreateShipmentRequest The values expected to be in the format defined for corresponding url parameter in that method sepcification.

Example Request:

{

"userName":"testUser",

"password":"password",

"id":"89988881389",

"properties":{

"total_weight":13,

"pickup_date":"2020-04-15"

}

2.1.23 Update Shipment Propeties Response (UpdateShipmentPropertiesResponse)

Response is UpdateShipmentResponse - same returned in updateShipment method

Output parameters:

UpdateShipmentPropertiesResponse
Name	Type	Data
UpdateShipmentResponse fields are here

2.1.24 Update Shipment Properties - URL (GET) Schema

This approach is used to update shipment properties, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/update/properties

Method: GET

Content-type: “application/x-www-form-urlencoded; charset=utf-8”

Update shipment properties. All properties can be changed if shipment is not requested for pick up or is not picked up yet.

Recipient phone and COD properties can be updated after pickup request if shipment is still not given to courier for delivery and is not cancelled or closed

The response is the same as method using JSON schema.

URL parameters:

UpdateShipmentPropertiesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
CreateShipmentRequest params are here
id	String	Yes	Shipment id	Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update

2.1.25 Find Parcels By Reference Request (FindParcelsByRefRequest)

This method returns parcels by reference number

Web service URL: BASE_URL/shipment/search

Method: POST

Content-type: application/json; charset=utf-8

FindParcelsByRefRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
ref	String	Yes	Client reference
searchInRef	int	Yes	Specifies where to search: 0 means [Ref1 or Ref2], 1 means [Ref1], 2 means [Ref2]
shipmentsOnly	boolean	No	If true - search in shipments only, otherwise in shipment and parcels. Default is true
includeReturns	boolean	No	If true - search in return shipments also. Default is false
fromDateTime	Date (String in format “yyyy-MM-dd'T'HH:mm:ssZ”)	No	Pick-up date - from. Up to 6 months before
toDateTime	Date (String in format “yyyy-MM-dd'T'HH:mm:ssZ”)	No	Pick-up date - to

Example JSON:

{

"userName":"testUser",

"password":"password",

"ref":"634",

"fromDateTime":"2020-10-01T00:00:00+0300",

"toDateTime":"2020-10-15T00:00:00+0300",

}

2.1.26 Find Parcels By Reference Response (FindParcelsByRefResponse)

FindParcelsByRefResponse
Name	Type	Data
barcodes	String[]	List of barcodes found
error	Error	Response error

2.1.27 Find Parcels By Reference Request (FindParcelsByRefRequest) - URL (GET) schema

This approach is used to find parcels by reference providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/search

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindParcelsByRefRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
ref	String	Yes	Client reference
searchInRef \| search_in_ref	int	Yes	Specifies where to search: 0 means [Ref1 or Ref2], 1 means [Ref1], 2 means [Ref2]
shipmentsOnly \| shipments_only	boolean (true/false, y/n, “yes/no” - all case insensitive)	No	If true - search in shipments only, otherwise in shipment and parcels. Default is true
includeReturns \| include_returns	boolean (true/false, y/n, “yes/no” - all case insensitive)	No	If true - search in return shipments also. Default is false
fromDateTime \| from_date_time	Date (String in format “yyyy-MM-dd'T'HH:mm:ssZ”)	No	Pick-up date - from. Up to 6 months before
toDateTime \| to_date_time	Date (String in format “yyyy-MM-dd'T'HH:mm:ssZ”)	No	Pick-up date - to

2.1.28 Handover To Courier Request (HandoverToCourierRequest)

Web service URL: BASE_URL/shipment/handover

Method: POST

Content-type: application/json; charset=utf-8

HandoverToCourierRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
parcels	ParcelHandover[]	Yes	Parcel barcodes with datetime to register handover to courier operations	Should refer accessible shipment parcels

2.1.29 Handover To Courier Response (HandoverToCourierResponse)

Response is empty on success. Otherwise, an error is included.

HandoverToCourierResponse
Name	Type	Data
error	Error	Response error

2.1.30 Handover To Courier (HandoverToCourierRequest) - URL (GET) Schema

This approach is used to handover parcels to courier, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/handover

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

HandoverToCourierRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
parcels	String Format: <id>,<dateTime> Multiple items are separated with %7C (‘\|’) character. Datetime is in format dd.MM.yyyy HH:mm:ss	No	Parcel ids	Should refer accessible shipment parcels
externalCarrierParcels \| external_carrier_parcels	String Format: <externalCarrierParcelId>,<dateTime> Multiple items are separated with %7C (‘\|’) character. Datetime is in format dd.MM.yyyy HH:mm:ss	No	External carrier parcel ids	Should refer accessible shipment parcels

2.1.31 Handover To Midway Carrier Request (HandoverToMidwayCarrierRequest)

Web service URL: BASE_URL/shipment/handover-to-midway-carrier

Method: POST

Content-type: application/json; charset=utf-8

HandoverToMidwayCarrierRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
parcels	MidwayCarrierParcelHandover[]	Yes	Parcel barcodes with datetime, country and site name to register handover to midway carrier operations	Should refer accessible shipment parcels

2.1.32 Handover To Midway Carrier Response (HandoverToMidwayCarrierResponse)

Response is empty on success. Otherwise, an error is included.

HandoverToMidwayCarrierResponse
Name	Type	Data
error	Error	Response error

2.1.33 Handover To Midway Carrier Request (HandoverToCourierRequest) - URL (GET) Schema

This approach is used to handover parcels to midway carrier, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/handover-to-midway-carrier

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

HandoverToMidwayCarrierRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
parcels	String Format: <id>,<countryId>,<dateTime>,<siteName> or <id>,<countryId>,<dateTime> Multiple items are separated with %7C (‘\|’) character. Datetime is in format dd.MM.yyyy HH:mm:ss	No	Parcel ids	Should refer accessible shipment parcels

2.1.34 Barcode Information Request (BarcodeInformationRequest)

Get parcel information by parcel barcode

Web service URL: BASE_URL/shipment/barcode-information

Method: POST

Content-type: application/json; charset=utf-8

BarcodeInformationRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
parcel	ShipmentParcelRef	Yes	Parcel to get info for	Validated for allowed access.

Example JSON:

{

"userName":"testUser",

"password":"password",

"parcel": {

"fullBarcode":"1000509431237540020002030017"

}

2.1.35 Barcode Information Response (BarcodeInformationResponse)

Barcode information response

BarcodeInformationResponse
Name	Type	Data
labelInfo	LabelInfo	Label info
primaryShipment	PrimaryShipment	Primary shipment.
primaryParcelId	String	Primary parcel id.
returnShipmentId	String	Return shipment id.
returnParcelId	String	Return parcel id.
redirectShipmentId	String	Redirect shipment id.
redirectParcelId	String	Redirect parcel id.
initialShipmentId	String	Initial shipment id.
initialParcelId	String	Initial parcel id.
error	Error	Response error

Example JSON:

{

"labelsInfo”: {

"hubId": 2,

"officeId": 2,

"deadlineDay": 18,

"deadlineMonth": 2,

"tourId": 2203,

"fullBarcode": "1000509431237540020002030017"

"initialShipmentId": "50943123000"

}

2.1.36 Barcode Information Request (BarcodeInfomationRequest) - URL (GET) schema

This approach is used to get barcode information providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/shipment/barcode-information

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

BarcodeInformationRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
fullBarcode \| full_barcode	String	Yes if no id or externalCarrierParcelNumber is provided	Full barcode	Validated for allowed access.
id	String	Yes if no fullBarcode or externalCarrierParcelNumber is provided	Parcel id	Validated for allowed access.
externalCarrierParcelNumber \| external_carrier_parcel_number	String	Yes if no id or fullBarcode is provided	External carrier parcel number	Validated for allowed access.

Example request:

BASE_URL/shipment/barcode-information?username=test&password=test&fullBarocde=1000899999993951420001320013

2.2 Print Service

Web service URL: BASE_URL/print

Used to create labels (waybills, stickers and etc.)

PDF Examples:

2.2.1 Print Request (PrintRequest)

Web service URL: BASE_URL/print

Method: POST

Content-type: application/json; charset=utf-8

PrintRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
format	enum [“pdf”, “zpl”]	No (default is pdf)	Output format
paperSize	enum [“A4”, “A6”, “A4_4xA6”]	Yes	Print paper size	Validated for allowed format. For example zpl is allowed with A6 only.
parcels	ParcelToPrint[]	Yes	Parcels to print	Validated for allowed access.
printerName	String	No	Printer name to be used for direct printing.
dpi	enum [“dpi203”, “dpi300”]	No (default is dpi203)	Dpi used for rendering. Makes sense for zpl format, otherwise ignored
additionalWaybillSenderCopy	enum [“NONE”, “ON_SAME_PAGE”, “ON_SINGLE_PAGE”]	No (default is NONE)	Defines whether and how to print additional waybill copy for sender.	A4 pdf printing is required if print mode is different than NONE.

Example JSON:

{

"userName":"testUser",

"password":"password",

"paperSize":"A4_4xA6",

"parcels": [

{

"parcel": {

"id":"80002338331"

}

{

"parcel": {

"id":"80002338159"

}

]

}

2.2.2 Print Response (PrintResponse)

In case the response is a PDF document, the result content type is application/pdf.

Content-type: application/pdf

And content contains pdf bytes.

In case it is a zpl, the content type is text/plain.

Content-type:text/plain

And content contains zpl text string.

In case of an error, the content type is application/json.

Content-type:application/json

And content is a JSON with Error structure.

2.2.3 Print Request - URL (GET) schema

This approach is used to print parcels, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/print

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

PrintRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
format	enum [“pdf”, “zpl”]	No (default is pdf)	Output format
paperSize \| paper_size	enum [“A4”, “A6”, “A4_4xA6”]	Yes	Print paper size	Validated for allowed format. For example zpl is allowed with A6 only.
parcels	String Format: <id>, <additionalBarcodeValue>, <additionalBarcodeLabel>, <additionalBarcodeFormat> Multiple parcels are separated with %7C (‘\|’) character	No	Parcels to print. Parcel parameters are parsed in the order of their occurrence and missing parameters are considered empty.
externalCarrierParcels \| external_carrier_parcels	String Format: <externalCarrierParcelId>, <additionalBarcodeValue>, <additionalBarcodeLabel>, <additionalBarcodeFormat> Multiple parcels are separated with %7C (‘\|’) character	No	External carrier parcels to print. Parcel parameters are parsed in the order of their occurrence and missing parameters are considered empty.
printerName \| printer_name	String	No	Printer name to be used for direct printing. Includes javascript in pdf to print document directly to the provided printer on document opening. Make sense for pdf printing.
dpi	enum [“dpi203”, “dpi300”]	No (default is dpi203)	Dpi used for rendering. Makes sense for zpl format, otherwise ignored
additionalWaybillSenderCopy \| additional_waybill_wender_copy	enum [“NONE”, “ON_SAME_PAGE”, “ON_SINGLE_PAGE”]	No (default is NONE)	Defines whether and how to print additional waybill copy for sender.	A4 pdf printing is required if print mode is different than NONE.

2.2.4 Extended Print Request

Web service URL: BASE_URL/print/extended

Method: POST

Content-type: application/json; charset=utf-8

The same PrintRequest structure is send to /extended path to get JSON response with an extended routing information described in next section.

2.2.5 Extended Print Response (ExtendedPrintResponse)

ExtendedPrintResponse
Name	Type	Data
data	byte[] (BASE64 encoded string)	Response data - base64 encoded binary data (pdf)
printLabelsInfo	LabelInfo[]	Print labels info
error	Error	Response error

Example JSON:

{

"data": "ADABDAS..."

"labelsInfo”: [

{

"parcelId": "50943123754",

"hubId": 2,

"officeId": 2,

"deadlineDay": 18,

"deadlineMonth": 2,

"tourId": 2203,

"fullBarcode": "1000509431237540020002030017"

}

]

}

2.2.6 Extended Print Request - URL (GET) schema

This approach is used to print parcels, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/print/extended

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The same PrintRequest parameters are sent to /extended path to get JSON response with an extended routing information.

The response is the same as method using in JSON POST schema.

2.2.7 Label Info Request (LabelInfoRequest)

Web service URL: BASE_URL/print/labelInfo

Method: POST

Content-type: application/json; charset=utf-8

LabelInfoRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
parcels	ShipmentParcelRef[]	Yes	Parcels to get label info for	Validated for allowed access.

Example JSON:

{

"userName":"testUser",

"password":"password",

"parcels": [

{

"id":"80002338331"

}

{

"id":"80002338159"

}

]

}

2.2.8 Label Info Response (LabelInfoResponse)

LabelInfoResponse
Name	Type	Data
printLabelsInfo	LabelInfo[]	Print labels info
error	Error	Response error

Example JSON:

{

"labelsInfo”: [

{

"parcelId": "50943123754",

"hubId": 2,

"officeId": 2,

"deadlineDay": 18,

"deadlineMonth": 2,

"tourId": 2203,

"fullBarcode": "1000509431237540020002030017"

}

]

}

2.2.9 Label Info Request - URL (GET) schema

This approach is used to get print label info, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/print/labelInfo

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

LabelInfoRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
parcels	String Format: <id> Multiple parcels are separated with %7C (‘\|’) character.	No	Parcels to get print label info for.	Validated for allowed access.
externalCarrierParcels \| external_carrier_parcels	String Format: <externalCarrierParcelId> Multiple parcels are separated with %7C (‘\|’) character.	No	External carrier parcels to get print label info for.

2.2.10 Print Voucher Request (PrintVoucherRequest)

Web service URL: BASE_URL/print/voucher

Method: POST

Content-type: application/json; charset=utf-8

PrintVoucherRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
shipmentIds	String[]	Yes	Shipment ids	Validated for allowed access. All shipments must have voucher request
printerName	String	No	Printer name to be used for direct printing. Includes javascript in pdf to print document directly to the provided printer on document opening.
format	enum [“pdf”, “zpl”]	No (default is pdf)	Output format
dpi	enum [“dpi203”, “dpi300”]	No (default is dpi203)	Dpi used for rendering. Makes sense for zpl format, otherwise ignored

Example JSON:

{

"userName":"testUser",

"password":"password",

"shipmentIds": ["80002338331"]

}

2.2.11 Print Voucher Response (PrintVoucherResponse)

The result content type is application/pdf.

Content-type: application/pdf

And content contains pdf bytes.

In case of an error, the content type is application/json.

Content-type:application/json

And content is a JSON with Error structure.

2.2.12 Print Voucher Request - URL (GET) schema

This approach is used to print vouchers, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/print/voucher

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

PrintVoucherRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
shipmentIds \| shipment_ids	String (comma separated shipment ids)	Yes	Shipment ids.	Validated for allowed access. All shipments must have voucher request
printerName \| printer_name	String	No	Printer name to be used for direct printing. Includes javascript in pdf to print document directly to the provided printer on document opening.

2.3 Track And Trace Service

Web service URL: BASE_URL/track

2.3.1 Track Request (TrackRequest)

Web service URL: BASE_URL/track

Method: POST

Content-type: application/json; charset=utf-8

TrackRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
parcels	TrackShipmentParcelRef[]	Yes	Parcels to track
lastOperationOnly	Boolean	No	Flag to return last operation only’

2.3.2 Track Response (TrackResponse)

TrackResponse
Name	Type	Mandatory	Data
parcels	TrackedParcel[]	Yes	Parcel track information
error	Error	No	Response error

2.3.3 Track Request - URL (GET) schema

This approach is used to track parcels, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/track

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

TrackRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
parcels	String Format: <id> Multiple parcels are separated with %7C (‘\|’) character.	No	Parcel ids to track
externalCarrierParcels \| external_carrier_parcels	String Format: <externalCarrierParcelId> Multiple parcels are separated with %7C (‘\|’) character.	No	External carrier parcel ids to track
refs	String Format: <ref> Multiple parcels are separated with %7C (‘\|’) character.	No	Parcel references to search and track referred parcels
lastOperationOnly \| last_opeartion_only	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Flag to return last operation only.

Example:

BASE_URL/track?username=test&password=test&language=EN&client_system_id=9&parcels=89981001249%7C89981001254&last_opeartion_only=n

2.3.4 Bulk Tracking Data Files Request (BulkTrackingDataFilesRequest)

Bulk tracking data files are json files with file id assigned and contain data in format: TrackedParcel[]

A greater file id corresponds to a later file publishing.

This method is used to provide links for downloading published data files with tracking information.

This method requires bulk tracking service enrolment, for which you may contact your key account manager.

Web service URL: BASE_URL/track/bulk

Method: POST

Content-type: application/json; charset=utf-8

BulkTrackingDataFilesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
lastProcessedFileId	Long	Yes	The greatest data file id processed in client system. To get all published data files during last 10 days use 0 as lastProcessedFileId	The last processed file id must refer to a file published during last 10 days. Otherwise, error is returned.

2.3.5 Bulk Tracking Data Files Response (BulkTrackingDataFilesResponse)

BulkTrackingDataFilesResponse
Name	Type	Mandatory	Data
files	BulkTrackingDataFile[]	Yes	Bulk traking data files ordered by file id in ascending order. The geratest file id returned in this response is expected to be passed in next request for incremental processing
error	Error	No	Response error

2.3.6 Bulk Tracking Data Files Request - URL (GET) schema

This approach is used to get published bulk tracking file links, providing data in an URL instead of JSON data in the content.

Bulk tracking data files are json files with file id assigned and contain data in format: TrackedParcel[]

A greater file id corresponds to a later file publishing.

This method is used to provide links for downloading published data files with tracking information.

This method requires bulk tracking service enrolment, for which you may contact your key account manager.

Web service URL: BASE_URL/track/bulk

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

BulkTrackingDataFilesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
last_processed_file_id	Long	Yes	The greatest data file id processed in client system. To get all published data files during last 10 days use 0 as lastProcessedFileId	The last processed file id must refer to a file published during last 10 days. Otherwise, error is returned.

2.4 Pickup

Web service URL: BASE_URL/pickup

2.4.1 Pickup Request (PickupRequest)

Web service URL: BASE_URL/pickup

Method: POST

Content-type: application/json; charset=utf-8

PickupRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
pickupDateTime	Date (String in format “yyyy-MM-dd'T'HH:mm:ssZ”)	No	Pickup datetime. If not provided, it is assumed now. Seconds and milliseconds are ignored.
autoAdjustPickupDate	Boolean	No (default value is false)	To find first available date for pickup starting from pickupDate according to pickup schedule for services
pickupScope	enum [“EXPLICIT_SHIPMENT_ID_LIST”, “ALL_CREATED_BY_LOGGED_USER”, “ALL_CREATED_BY_SAME_CLIENT”] “ALL_CREATED_BY_SAME_CONTRACT_USERS”]	No Default is EXPLICIT_SHIPMENT_ID_LIST	Scope of shipments to order.	ALL_CREATED_BY_SAME_CONTRACT_USERS can be used in case a logged user have the access rights to access shipments created by other users in the same contract.
explicitShipmentIdList	String[]	No Required when pickup scope is EXPLICIT_SHIPMENT_ID_LIST
visitEndTime	String (format HH:ss)	Yes Example 9:30, or 11:35	The last possible time when the address could be visited on the pickup date.
contactName	String	No	Contact name.
phoneNumber	ShipmentPhoneNumber	No	Customer’s phone number.

Example JSON:

{

"userName":"testUser",

"password":"password",

"pickupDateTime":"2017-12-05T14:30:00+0200",

"explicitShipmentIdList":["80002338331", "80002338159"],

"visitEndTime": 18:20

}

2.4.2 Pickup Response (PickupResponse)

PickupResponse
Name	Type	Mandatory	Data
orders	PickupOrder[]	Yes	Pickup orders created
error	Error	No	Response error

2.4.3 Pickup Request - URL (GET) schema

This approach is used to request a pickup, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/pickup

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

PickupRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
pickupDateTime \| pickup_date_time	Date (String in format “dd.MM.yyyy HH:mm”)	No	Pickup date time. If not provided it is assumed the current datetime.Seconds and milliseconds are ignored.
autoAdjustPickupDate \| auto_adjust_pickup_date \| autoadjust_pickup_date	Boolean	No (default is false)	To find first available date for pickup starting from pickupDate according to pickup schedule for services
pickupScope \| pickup_scope	enum [“EXPLICIT_SHIPMENT_ID_LIST”, “ALL_CREATED_BY_LOGGED_USER”, “ALL_CREATED_BY_SAME_CLIENT”, “ALL_CREATED_BY_SAME_CONTRACT_USERS”]	No Default is EXPLICIT_SHIPMENT_ID_LIST	Scope of shipments to order.	ALL_CREATED_BY_SAME_CONTRACT_USERS can be used in case a logged user have the access rights to access shipments created by other users in the same contract.
explicitShipmentIdList \| explicit_shipment_id_list	String (comma separated list of ids)	No Required when pickup scope is EXPLICIT_SHIPMENT_ID_LIST
visitEndTime \| visit_end_time	String (format HH:ss)	Yes	The last possible time when the address could be visited on the pickup date.
contactName \| contact_name	String	No	Contact name.
phoneNumber \| phone_number	String	No	Customer’s phone number.	Validated for valid phone number.
phoneNumberExt \| phone_number_ext	String	No	Customer’s phone number extension.	Validated for valid phone number extension.

Example:

BASE_URL/pickup?username=test&password=test&language=EN&client_system_id=9&pickup_date_time=2017-12-07T16%3A00%3A00%2B0200&explicit_shipment_id_list=89981001489&visit_end_time=19%3A00&phone_number=123123&pickup_scope=EXPLICIT_SHIPMENT_ID_LIST

2.4.4 Pickup Terms Request (PickupTermsRequest)

Web service URL: BASE_URL/pickup/terms

Method: POST

Content-type: application/json; charset=utf-8

PickupTermsRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
serviceId	int	Yes	Service Id
startingDate	Date (String in format “yyyy-MM-dd”)	No	The first date when the shipment will be ready for pickup. If not provided, it is assumed today.	Should not be a date before today
sender	CalculationSender	No (If not specifed, logged user is used)	Client and location for pickup.
senderHasPayment	Boolean	No	Flag to indicate, whether sender should pay at least one of courier service, declared value or packings.If this parameter is missing assumed value is - false.

2.4.5 Pickup Terms Response (PickupTermsResponse)

PickupTermsResponse
Name	Type	Mandatory	Data
cutoffs	DateTime[] (format yyyy-MM-dd'T'HH:mm:ssZ)	Yes	Pickup cutoffs for next days. Pickup is not allowed for missing days in the result list
error	Error	No	Response error

2.4.6 Pickup Terms Request - URL (GET) schema

This approach is used to request pickup terms, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/pickup/terms

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

PickupTermsRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
serviceId \| service_id	int	Yes	Service id
startingDate \| starting_date	Date (String in format “yyyy-MM-dd”)	No	The first date when the shipment will be ready for pickup. If not provided, it is assumed today.	Should not be a date before today
Calculation sender details If logged user is the sender, you may skip providing sender details at all. If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also. Otherwise, sender_id should stay empty and it is required to provide as a minimum: sender privatePerson flag sender address location or dropoffOfficeId
senderId \| sender_id	Long	No	Client id to refer Ð° sender	Validate for existence.
senderPrivatePerson \| sender_private_person	Boolean (true/false, y/n, âyes/noâ - all case insensitive)	If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory	Sender private person flag.
Sender Address Location Details See AddressLocation for more details. The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at senderâs address is expected.
senderAddressCountryId \| sender_address_country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.	Validate for valid country code
senderAddressStateId \| sender_address_state_id	String	Required if country requires state	Country state. Used for addresses of type 2 (foreign address).	Validate for valid country state.
senderAddressSiteId \| sender_address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided	Site id. Used for all address types	Validate for valid site and value is required
senderAddressSiteType \| sender_address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)	Max 20 characters
senderAddressSiteName \| sender_address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50 characters
senderAddressPostcode \| senderAddressPostCode \| sender_address_postcode	String	No	Can be used in conjunction with countryId to find unique site. Used for all address types	Max 10 characters
dropoffOfficeId \| dropOffOfficeId \| senderDropoffOfficeId \| senderDropOffOfficeId \| dropoff_office_id \| sender_dropoff_office_id	Integer	Required, if the sender is an internal customer. If sender address is provided, it is forbidden.	Drop off office id.	Should refer to a valid accessible office
senderHasPayment \| sender_has_payment	Boolean	No	Flag to indicate, whether sender should pay at least one of courier service declared value or packings. If this parameter is missing assumed value is - false.

Example:

BASE_URL/pickup/terms?username=test&password=test&language=EN&client_system_id=9&starting_date=2017-12-07&service_id=2002

2.5 Location Service

Web service URL: BASE_URL/location

2.5.1 Country

This section specifies methods to query system for allowed countries

Web service URL: BASE_URL/location/country

2.5.1.1 Get Country Request (GetCountryRequest)

Web service URL: BASE_URL/location/country/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get country by id. Country id is provided as parameter in URL path

GetCountryRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.1.2 Get Country Response (GetCountryResponse)

GetCountryResponse
Name	Type	Mandatory	Data
country	Country	No	Found country or null if not found
error	Error	No	Response error

2.5.1.3 Get Country Request - URL (GET) schema

This approach is used to get country by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/country/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetCountryRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/country/642?username=test&password=test

2.5.1.4 Find Country Request (FindCountryRequest)

Web service URL: BASE_URL/location/country

Method: POST

Content-type: application/json; charset=utf-8

Find country using search criteria

FindCountryRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
name	String	No	Country search term. Filters the results by country name prefix or part of country name
isoAlpha2	String	No	Country iso alpha 2. Filters result by exact match if presents. ISO alpha 2 value uniquely identifies country and other criterias are not needed if this one presents
isoAlpha3	String	No	Country iso alpha 3. Filters result by exact match if presents. ISO alpha 3 value uniquely identifies country and other criterias are not needed if this one presents

Example JSON:

{

"userName":"testUser",

"password":"password",

"name":"ROMA"

}

2.5.1.5 Find Country Response (FindCountryResponse)

The countries in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
Country name prefix matches, followed by
Country name contains matches (search term is in the name but not a prefix)

The result is limited to 10 records.

FindCountryResponse
Name	Type	Mandatory	Data
countries	Country[]	No	Array of countries
error	Error	No	Response error

2.5.1.6 Find Country Request - URL (GET) schema

This approach is used to find country, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/country

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindCountryRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
name	String	No	Country search term. Filters the results by country name prefix or part of country name
isoAlpha2 \| iso_alpha2	String	No	Country iso alpha 2. Filters result by exact match if presents. ISO alpha 2 value uniquely identifies country and other criterias are not needed if this one presents
isoAlpha3 \| iso_alpha3	String	No	Country iso alpha 3. Filters result by exact match if presents. ISO alpha 3 value uniquely identifies country and other criterias are not needed if this one presents

Example:

BASE_URL/location/country/?username=test&password=test&name=ro

2.5.1.7 Get All Countries Request (GetAllCountriesRequest)

Web service URL: BASE_URL/location/country/csv

Method: POST

Content-type: application/json; charset=utf-8

Get all countries as csv file

GetAllCountriesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.1.8 Get All Countries Response (GetAllCountriesResponse)

See Country data structure for additional information.

Response is CSV (comma separated) file int UTF8 encoding. The format is:

id - ISO country id
name - Country name in local language
nameEn - Country name in English
isoAlpha2 - ISO alpha 2 code
isoAlpha3 - ISO alpha 3 code
postCodeFormats - all allowed postcode patterns are separated with comma and the whole value is escaped with quotation marks
requireState - flag whether country requires state
addressType - address type (1 or 2) for this country (see ShipmentAddress)
currencyCode - current active currency code used for COD
defaultOfficeId - default office id
streetTypes - comma separated list of all street types escaped with quotation marks in local language. This value is applicable for addressType 1 only
streetTypesEn - comma separated list of all street types escaped with quotation marks in English. This value is applicable for addressType 1 only
complexTypes - comma separated list of all complex types escaped with quotation marks in local language. This value is applicable for addressType 1 only
complexTypesEn - comma separated list of all complex types escaped with quotation marks in English. This value is applicable for addressType 1 only
siteNomen - site nomenclature (0, 1 ,2)

2.5.1.9 Get All Countries Request - URL (GET) schema

This approach is used to get all countries as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/country

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

GetAllCountriesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/country/csv?username=test&password=test

2.5.2 State

This section specifies methods to query system for allowed states

Web service URL: BASE_URL/location/state

2.5.2.1 Get State Request (GetStateRequest)

Web service URL: BASE_URL/location/state/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get state by id. State id is provided as parameter in URL path

GetStateRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.2.2 Get State Response (GetStateResponse)

GetStateResponse
Name	Type	Mandatory	Data
site	State	No	State found or null if not found
error	Error	No	Response error

2.5.2.3 Get State Request - URL (GET) schema

This approach is used to get state by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/state/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Site id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetStateRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/state/CA-AB?username=test&password=test

2.5.2.4 Find State Request (FindStateRequest)

Web service URL: BASE_URL/location/state

Method: POST

Content-type: application/json; charset=utf-8

Find state using search criteria

FindStateRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
countryId	integer	Yes	Country id
name	String	No	Search term for state name. Filters the results by state name prefix or part of state name.

Example JSON:

{

"userName":"testUser",

"password":"password",

"countryId":840,

"name":"A"

}

2.5.2.5 Find State Response (FindStateResponse)

The states in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
State name prefix matches, followed by
State name contains matches (search term is in the name but not a prefix)

The result is limited to 10 records.

FindStateResponse
Name	Type	Mandatory	Data
states	State[]	No	Array of sites
error	Error	No	Response error

2.5.2.6 Find State Request - URL (GET) schema

This approach is used to find site, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/state

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindStateRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
countryId \| country_id	integer	Yes	Country id
name	String	No	Search term for state name. Filters the results by state name prefix or part of state name.

Example:

BASE_URL/location/state/?username=test&password=test&country_id=840&name=a

2.5.2.7 Get All States Request (GetAllStatesRequest)

Web service URL: BASE_URL/location/state/csv/{countryId}

Method: POST

Content-type: application/json; charset=utf-8

Get all states for a country in csv file. Country id is specified as path parameter

GetAllStatesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.2.8 Get All States Response (GetAllStatesResponse)

See State data structure for additional information.

Response is CSV (comma separated) file int UTF8 encoding. The format is:

id - state id
name - state name in local language
nameEn - state name in English
isoAlpha - ISO alpha code
countryId - country id (ISO code)

2.5.2.9 Get All States Request - URL (GET) schema

This approach is used to get all states as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/state/{countryId}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is is specified as a path parameter. The response is the same as method using JSON schema.

URL parameters:

GetAllStatesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/state/csv/840?username=test&password=test

2.5.3 Site

This section specifies methods to query system for allowed sites

Web service URL: BASE_URL/location/site

2.5.3.1 Get Site Request (GetSiteRequest)

Web service URL: BASE_URL/location/site/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get site by id. Site id is provided as parameter in URL path

GetSiteRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.3.2 Get Site Response (GetSiteResponse)

GetSiteResponse
Name	Type	Mandatory	Data
site	Site	No	Found site or null if not found
error	Error	No	Response error

2.5.3.3 Get Site Request - URL (GET) schema

This approach is used to get site by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/site/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Site id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetSiteRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/site/642279132?username=test&password=test

2.5.3.4 Find Site Request (FindSiteRequest)

Web service URL: BASE_URL/location/site

Method: POST

Content-type: application/json; charset=utf-8

Find site using search criteria

FindSiteRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
countryId	integer	Yes	Country id
name	String	No	Search term for site name. Filters the results by site name prefix or part of site name.
postCode	String	No	Filter results by postcode - valid postcode for site
type	String	No	Filter results by site type (exact match)
municipality	String	No	Filter by municipality (prefix match)
region	String	No	Filter by region (prefix match)

Example JSON:

{

"userName":"testUser",

"password":"password",

"countryId":642,

"name":"A"

}

2.5.3.5 Find Site Response (FindSiteResponse)

The sites in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
Site name prefix matches, followed by
Site name contains matches (search term is in the name but not a prefix)

The result is limited to 10 records.

FindSiteResponse
Name	Type	Mandatory	Data
sites	Site[]	No	Array of sites
error	Error	No	Response error

2.5.3.6 Find Site Request - URL (GET) schema

This approach is used to find site, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/site

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindSiteRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
countryId \| country_id	integer	Yes	Country id
name	String	No	Search term for site name. Filters the results by site name prefix or part of site name.
postcode \| postCode \| post_code	String	No	Filter results by postcode - valid postcode for site
type	String	No	Filter results by site type (exact match)
municipality	String	No	Filter by municipality (prefix match)
region	String	No	Filter by region (prefix match)

Example:

BASE_URL/location/site/?username=test&password=test&country_id=642&name=a

2.5.3.7 Get All Sites Request (GetAllSitesRequest)

Web service URL: BASE_URL/location/site/csv/{countryId}

Method: POST

Content-type: application/json; charset=utf-8

Get all sites for a country in csv file. Country id is specified as path parameter

GetAllSitesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.3.8 Get All Sites Response (GetAllSitesResponse)

See Site data structure for additional information.

Response is CSV (comma separated) file int UTF8 encoding. The format is:

id - site id
countryId - country id (ISO code)
mainSiteId - reference to main site if this site is a "satellite" one
type - site type in local language
typeEn - site type in English
name - site name in local language
nameEn - site name in English
municipality - municipality in local language
municipalityEn - municipality in English
region - region in local language
regionEn - region in English
postCode - default post code for this site (if any)
addressNomenclature - code for address nomenclature (streets, complexes, blocks, poi) support. Values are: 0 - no address nomenclature, 1 - partial address nomenclature, 2 - full address nomenclature
x - X (longitude) coordinate of site center
y - Y (latitude) coordinate of site center
servingDays - serving days for this site. Format: 7 serial digits (0 or 1) where each digit corresponds to a day in week (the first digit corresponds to Monday, the second to Tuesday and so on). Value of '0' (zero) means that the site is not served by Speedy on this day while '1' (one) means that it is served. (Example: the text "0100100" means that the site is served on Tuesday and Friday only.)
servingOfficeId - Site's serving office
servingHubOfficeId - The hub office ID to which serving office is connected

2.5.3.9 Get All Sites Request - URL (GET) schema

This approach is used to get all sites as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/site/{countryId}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is is specified as a path parameter. The response is the same as method using JSON schema.

URL parameters:

GetAllSitesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/site/csv/642?username=test&password=test

2.5.4 Street

This section specifies methods to query system for allowed streets

Web service URL: BASE_URL/location/street

2.5.4.1 Get Street Request (GetStreetRequest)

Web service URL: BASE_URL/location/street/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get street by id. Street id is provided as parameter in URL path

GetStreetRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.4.2 Get Street Response (GetStreetResponse)

GetStreetResponse
Name	Type	Mandatory	Data
street	Street	No	Found street or null if not found
error	Error	No	Response error

2.5.4.3 Get Street Request - URL (GET) schema

This approach is used to get street by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/street/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Street id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetStreetRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/street/642075720?username=test&password=test

2.5.4.4 Find Street Request (FindStreetRequest)

Web service URL: BASE_URL/location/street

Method: POST

Content-type: application/json; charset=utf-8

Find street using search criteria

FindStreetRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
siteId	integer	Yes	Site id
name	String	No	Search term for street name. Filters the results by street name prefix or part of street name.
type	String	No	Filter results by street type (exact match)

Example JSON:

{

"userName":"testUser",

"password":"password",

"siteId":642279132,

"name":"A"

}

2.5.4.5 Find Street Response (FindStreetResponse)

The streets in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
Street name prefix matches, followed by
Street name contains matches (search term is in the name but not a prefix)

The result is limited to 10 records.

FindStreetResponse
Name	Type	Mandatory	Data
streets	Street[]	No	Array of streets
error	Error	No	Response error

2.5.4.6 Find Street Request - URL (GET) schema

This approach is used to find street, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/street

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindStreetRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
siteId \| site_id	long	Yes	Site id
name	String	No	Search term for street name. Filters the results by street name prefix or part of street name.
type	String	No	Filter results by street type (exact match)

Example:

BASE_URL/location/street/?username=test&password=test&site_id=642279132&name=a

2.5.4.7 Get All Streets Request (GetAllStreetsRequest)

Web service URL: BASE_URL/location/street/csv/{countryId}

Method: POST

Content-type: application/json; charset=utf-8

Get all streets for a country in csv file. Country id is specified as path parameter.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

GetAllStreetsRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.4.8 Get All Streets Response (GetAllStreetsResponse)

See Street data structure for additional information.

Response is CSV (comma separated) file int UTF8 encoding. The format is:

id - street id
siteId - site id
type - street type in local language
typeEn - street type in English
name - street name in local language
nameEn - street name in English
actualId - actual street id (in case this street is renamed)

2.5.4.9 Get All Streets Request - URL (GET) schema

This approach is used to get all streets as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/street/{countryId}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is is specified as a path parameter. The response is the same as method using JSON schema.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

URL parameters:

GetAllStreetsRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/street/csv/642?username=test&password=test

2.5.5 Complex

This section specifies methods to query system for allowed complexes

Web service URL: BASE_URL/location/complex

2.5.5.1 Get Complex Request (GetComplexRequest)

Web service URL: BASE_URL/location/complex/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get complex by id. Complex id is provided as parameter in URL path

GetComplexRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.5.2 Get Complex Response (GetComplexResponse)

GetComplexResponse
Name	Type	Mandatory	Data
complex	Complex	No	Complex found or null if not found
error	Error	No	Response error

2.5.5.3 Get Complex Request - URL (GET) schema

This approach is used to get complex by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/complex/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Complex id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetComplexRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/complex/1?username=test&password=test

2.5.5.4 Find Complex Request (FindComplexRequest)

Web service URL: BASE_URL/location/complex

Method: POST

Content-type: application/json; charset=utf-8

Find complex using search criteria

FindComplexRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
siteId	integer	Yes	Site id
name	String	No	Search term for complex name. Filters the results by complex name prefix or part of complex name.
type	String	No	Filter results by complex type (exact match)

Example JSON:

{

"userName":"testUser",

"password":"password",

"siteId":100,

"name":"A"

}

2.5.5.5 Find Complex Response (FindComplexResponse)

The complexes in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
Complex name prefix matches, followed by
Complex name contains matches (search term is in the name but not a prefix)

The result is limited to 10 records.

FindComplexResponse
Name	Type	Mandatory	Data
complexes	Complex[]	No	Array of complexes
error	Error	No	Response error

2.5.5.6 Find Complex Request - URL (GET) schema

This approach is used to find complex, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/complex

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindComplexRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
siteId \| site_id	long	Yes	Site id
name	String	No	Search term for complex name. Filters the results by xomplex name prefix or part of xomplex name.
type	String	No	Filter results by complex type (exact match)

Example:

BASE_URL/location/complex/?username=test&password=test&site_id=100&name=a

2.5.5.7 Get All Complexes Request (GetAllComplexesRequest)

Web service URL: BASE_URL/location/complex/csv/{countryId}

Method: POST

Content-type: application/json; charset=utf-8

Get all complexes for a country in csv file. Country id is specified as path parameter.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

GetAllComplexesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.5.8 Get All Complexes Response (GetAllComplexesResponse)

See Complex data structure for additional information.

Response is CSV (comma separated) file int UTF8 encoding. The format is:

id - street id
siteId - site id
type - street type in local language
typeEn - street type in English
name - street name in local language
nameEn - street name in English
actualId - actual street id (in case this street is renamed)

2.5.5.9 Get All Complexes Request - URL (GET) schema

This approach is used to get all complexes as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/complex/{countryId}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is is specified as a path parameter. The response is the same as method using JSON schema.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

URL parameters:

GetAllComplexesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/complex/csv/642?username=test&password=test

2.5.6 Block

This section specifies methods to query system for allowed blocks

Web service URL: BASE_URL/location/block

2.5.6.1 Find Block Request (FindBlockRequest)

Web service URL: BASE_URL/location/block

Method: POST

Content-type: application/json; charset=utf-8

Find block using search criteria

FindBlockRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
siteId	integer	Yes	Site id
name	String	No	Search term for block name. Filters the results by block name prefix or part of block name.

Example JSON:

{

"userName":"testUser",

"password":"password",

"siteId":10135,

"name":"A"

}

2.5.6.2 Find Block Response (FindBlockResponse)

The blocks in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
Block name prefix matches, followed by
Block name contains matches (search term is in the name but not a prefix)

The result is limited to 10 records.

FindBlockResponse
Name	Type	Mandatory	Data
blocks	Block[]	No	Array of blocks
error	Error	No	Response error

2.5.6.3 Find Block Request - URL (GET) schema

This approach is used to find block, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/block

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindBlockRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
siteId \| site_id	long	Yes	Site id
name	String	No	Search term for block name. Filters the results by block name prefix or part of block name.

Example:

BASE_URL/location/block/?username=test&password=test&site_id=10135&name=a

2.5.6.4 Get All Blocks Request (GetAllBlocksRequest)

Web service URL: BASE_URL/location/block/csv/{countryId}

Method: POST

Content-type: application/json; charset=utf-8

Get all blocks for a country in csv file. Country id is specified as path parameter.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

GetAllBlockRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.6.5 Get All Blocks Response (GetAllBlocksResponse)

See Block data structure for additional information.

Response is CSV (comma separated) file int UTF8 encoding. The format is:

siteId - site id
name - block name in local language
nameEn - block name in English

2.5.6.6 Get All Blocks Request - URL (GET) schema

This approach is used to get all blocks as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/block/{countryId}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is is specified as a path parameter. The response is the same as method using JSON schema.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

URL parameters:

GetAllBlocksRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/block/csv/100?username=test&password=test

2.5.7 POI (Point of Interest)

This section specifies methods to query system for allowed points of interest

Web service URL: BASE_URL/location/poi

2.5.7.1 Get POI Request (GetPOIRequest)

Web service URL: BASE_URL/location/poi/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get POI by id. POI id is provided as parameter in URL path

GetPOIRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.7.2 Get POI Response (GetPOIResponse)

GetPOIResponse
Name	Type	Mandatory	Data
poi	PointOfInterest	No	POI found or null if not found
error	Error	No	Response error

2.5.7.3 Get POI Request - URL (GET) schema

This approach is used to get POI by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/poi/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

POI id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetPOIRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/poi/1?username=test&password=test

2.5.7.4 Find POI Request (FindPOIRequest)

Web service URL: BASE_URL/location/poi

Method: POST

Content-type: application/json; charset=utf-8

Find POI using search criteria

FindPOIRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
siteId	integer	Yes	Site id
name	String	No	Search term for POI name. Filters the results by POI name prefix or part of POI name.

Example JSON:

{

"userName":"testUser",

"password":"password",

"siteId":100,

"name":"A"

}

2.5.7.5 Find POI Response (FindPOIResponse)

The points of interest in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
POI name prefix matches, followed by
POI name contains matches (search term is in the name but not a prefix)

The result is limited to 10 records.

FindPOIResponse
Name	Type	Mandatory	Data
pois	PointOfInterest[]	No	Array of points of interest
error	Error	No	Response error

2.5.7.6 Find POI Request - URL (GET) schema

This approach is used to find POI, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/poi

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindPOIRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
siteId \| site_id	long	Yes	Site id
name	String	No	Search term for POI name. Filters the results by POI name prefix or part of POI name.

Example:

BASE_URL/location/poi/?username=test&password=test&site_id=100&name=a

2.5.7.7 Get All Points of Interest Request (GetAllPOIRequest)

Web service URL: BASE_URL/location/poi/csv/{countryId}

Method: POST

Content-type: application/json; charset=utf-8

Get all Points of Interest for a country in csv file. Country id is specified as path parameter.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

GetAllPOIRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.7.8 Get All Points of Interest Response (GetAllPOIResponse)

See PointOfInterest data structure for additional information.

Response is CSV (comma separated) file int UTF8 encoding. The format is:

id - POI id
siteId - site id
name - POI name in local language
nameEn - POI name in English
address - POI address in local language
addressEn - POI address in English
x - X coordinate
y - Y coordinate
type - POI type in local language
typeEn - POI type in English

2.5.7.9 Get All Points of Interest Request - URL (GET) schema

This approach is used to get all Points of Interest as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/poi/{countryId}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is is specified as a path parameter. The response is the same as method using JSON schema.

This method requires a license (additional licensing contract) and permissions (access rights).

To obtain such license please contact your key account manager.

URL parameters:

GetAllPOIRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/poi/csv/100?username=test&password=test

2.5.8 Postcodes

This section specifies methods to query system for allowed country postcodes

Web service URL: BASE_URL/location/postcode

2.5.8.1 Get All Postcodes Request (GetAllPostcodesRequest)

Web service URL: BASE_URL/location/postcode/csv/{countryId}

Method: POST

Content-type: application/json; charset=utf-8

Get all postcodes for a country in csv file. Country id is specified as path parameter.

GetAllPostcodesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.8.2 Get All Postcodes Response (GetAllPostcodesResponse)

Response is CSV (comma separated) file int UTF8 encoding. The format is:

postcode - Postcode
siteId - site id

2.5.8.3 Get All Postcodes Request - URL (GET) schema

This approach is used to get all postcodes as CSV file (UTF8 encoded), providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/postcode/csv/{countryId}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Country id is is specified as a path parameter. The response is the same as method using JSON schema.

URL parameters:

GetAllPostcodesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/postcodes/csv/642?username=test&password=test

2.5.9 Office

This section specifies methods to query system for available offices

Web service URL: BASE_URL/location/office

2.5.9.1 Get Office Request (GetOfficeRequest)

Web service URL: BASE_URL/location/office/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get office by id. Office id is provided as parameter in URL path

GetOfficeRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

Example JSON:

{

"userName":"testUser",

"password":"password",

}

2.5.9.2 Get Office Response (GetOfficeResponse)

GetOfficeResponse
Name	Type	Mandatory	Data
office	Office	No	Office found or null if not found
error	Error	No	Response error

2.5.9.3 Get Office Request - URL (GET) schema

This approach is used to get office by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/office/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Office id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetOfficeRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

Example:

BASE_URL/location/office/2?username=test&password=test

2.5.9.4 Find Office Request (FindOfficeRequest)

Web service URL: BASE_URL/location/office

Method: POST

Content-type: application/json; charset=utf-8

Find office using search criteria

FindOfficeRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
countryId	Integer	No	Country id ISO. Limits the search scope in the set of offices for specified country. System default country is used if country id is omitted. If -1 is specified - offices in all countires are searched
siteId	Long	No	Site id. Limits the search scope in the set of offices for specified site. If omitted - all country offices are searched
siteName	String	No	Filters the results by office site name prefix or part of it.
name	String	No	Search term for office name. Filters the results by office name prefix or part of site name.
limit	Long	No	The number of records to return in response. All records are returned if this parameter is ommited

Example JSON:

{

"userName":"testUser",

"password":"password",

"countryId":642,

"name":"A"

}

2.5.9.5 Find Office Response (FindOfficeResponse)

The offices in return are these that match search criteria in request and ordered by:

Exact match is on top, followed by
Office name prefix matches, followed by
Office name contains matches (search term is in the name but not a prefix)

FindOfficeResponse
Name	Type	Mandatory	Data
offices	Office[]	No	Array of offices
error	Error	No	Response error

2.5.9.6 Find Office Request - URL (GET) schema

This approach is used to find office, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/office

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindOfficeRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
countryId \| country_id	Integer	No	Country id ISO. Limits the search scope in the set of offices for specified country. System default country is used if country id is omitted. If -1 is specified - offices in all countires are searched.
siteId \| site_id	Long	No	Site id.Limits the search scope in the set of offices for specified site. If omitted - all country offices are searched
siteName \| site_name	String	No	Filters the results by office site name prefix or part of it
name	String	No	Search term for office name. Filters the results by office name prefix or part of office name.
limit	Long	No	The number of records to return in response. All records are returned if this parameter is ommited

Example:

BASE_URL/location/office/?username=test&password=test&country_id=642&name=a

2.5.9.7 Find Nearest Offices Request (FindNearestOfficesRequest)

Web service URL: BASE_URL/location/office/nearest-offices

Method: POST

Content-type: application/json; charset=utf-8

Find nearest offices using search criteria

FindNearestOfficesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
address	ShipmentAddress	Yes	Address to which the nearest offices are searched	Only country id is mandatory
distance	Integer	No	Maximum office distance ( in meters ) from provided address
limit	Integer	No	The number of records to return in response.
officeType	enum ["OFFICE", "APT"]	No	Filter offices by type.
officeFeatures	enum ["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][]	No	Supported office features

Example JSON:

{

"userName":"testUser",

"password":"password",

"address" {

"countryId":100,

"siteName":"Sofia"

}

"distance":1500,

"officeFeatures" [

"CARD_PAYMENT"

]

}

2.5.9.8 Find Nearest Offices Response (FindNearestOfficesResponse)

The offices in return are these that match search criteria in request and ordered by distance

FindNearestOfficesResponse
Name	Type	Mandatory	Data
offices	OfficeResult[]	No	Array of offices
x	Double	No	Provided address X coord
y	Double	No	Provided address Y coord
error	Error	No	Response error

2.5.9.9 Find Nearest Offices - URL (GET) schema

This approach is used search nearest offices, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/location/office/nearest-offices

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

FindNearestOfficesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
Shipment Address See ShipmentAddress for more details.
countryId \| country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.
stateId \| state_id	String	Required, if country supports states.	Country state. Used for addresses of type 2 (foreign address).
siteId \| site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided.	Site id. Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country
siteType \| site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address).	Max 20
siteName \| site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50
postcode \| postCode \| post_code	String	No	Can be used in conjunction with countryId to find unique site. Used for all address types.	Validated for valid postcode in site and country. Max 10
streetId \| street_id	Long	No	Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
streetType \| street_type	String	No Forbidden, if street_id is provided.	Street type. Used for addresses of type 1 (local address).	Max 15
streetName \| street_name	String	No Forbidden, if street_id is provided.	Street name. Used for addresses of type 1 (local address).	Max 50
streetNumber \| street_number	String	No	Street number. Used for addresses of type 1 (local address).	Max 10
complexId \| complex_id	Long	No	Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
complexType \| complex_type	String	No Forbidden, if complex_id is provided.	Complex type. Used for addresses of type 1 (local address).	Max 15
complexName \| complex_name	String	No Forbidden, if complex_id is provided.	Complex name. Used for addresses of type 1 (local address).	Max 50
block \| blockNo \| block_no	String	No	Block No. Used for addresses of type 1 (local address).	Max 32
entrance \| entranceNo \| entrance_no	String	No	Entrance. Used for addresses of type 1 (local address).	Max 10
floor \| floorNo \| floor_no	String	No	Floor. Used for addresses of type 1 (local address).	Max 10
apartment \| apartmentNo \| apartment_no	String	No	Apartment. Used for addresses of type 1 (local address).	Max 10
poiId \| poi_id	Long	No	Point of interest identifier. Used for addresses of type 1 (local address).
addressNote \| address_note \| note	String	No	Address note. Used for addresses of type 1 (local address).	200
addressLine1 \| address_line1 \| line1	String	Required for address type 2.	Address line 1. Used for addresses of type 2 (foreign address).	Max 35
addressLine2 \| address_line2 \| line2	String	No	Address line 2. Used for addresses of type 2 (foreign address).	Max 35
X \| x	Double	No	GIS coordinates - X. Used for all address types.
Y \| y	Double	No	GIS coordinates - Y. Used for all address types.
limit	Integer	No	The number of records to return in response.
distance	Integer	No	Maximum office distance ( in meters ) from the provided address
type	Integer	No	enum["CASH", "POSTAL_MONEY_TRANSFER"]
office_features \| officeFeatures	Integer	No	enum["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][] Multiple values are separated with %7C ( '\|' ) character.

2.6 Calculation Service

Web service URL: BASE_URL/calculate

2.6.1 Calculation Request (CalculationRequest)

Web service URL: BASE_URL/calculate

Method: POST

Content-type: application/json; charset=utf-8

CalculationRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
sender	CalculationSender	No	Defines the pickup place. If not specified, the logged user location is considered as a sender location.
recipient	CalculationRecipient	Yes	Defines the recipient delivery place.
service	CalculationService	Yes	Defines service agreemen
content	CalculationContent	Yes	Defines content - parcels, weight and etc
payment	ShipmentPayment	Yes	Defines who-pays-what in shipment

2.6.2 Calculation Response (CalculationResponse)

CalculationResponse
Name	Type	Mandatory	Data
calculations	CalculationResult[][]	Yes	Calculations for all service ids in request
error	Error	No	Response error

2.6.3 Calculation Request - URL (GET) schema

This approach is used to calculate, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/calculate

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

CalculationRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
Calculation sender details If logged user is the sender, you may skip providing sender details at all. If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also. Otherwise, sender_id should stay empty and it is required to provide as a minimum: sender privatePerson flag sender address location or dropoffOfficeId
senderId \| sender_id	Long	No	Client id to refer Ð° sender	Validate for existence.
senderPrivatePerson \| sender_private_person	Boolean (true/false, y/n, âyes/noâ - all case insensitive)	If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory	Sender private person flag.
Sender Address Location Details See AddressLocation for more details. The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at senderâs address is expected.
senderAddressCountryId \| sender_address_country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.	Validate for valid country code
senderAddressStateId \| sender_address_state_id	String	Required if country requires state	Country state. Used for addresses of type 2 (foreign address).	Validate for valid country state.
senderAddressSiteId \| sender_address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided	Site id. Used for all address types	Validate for valid site and value is required
senderAddressSiteType \| sender_address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)	Max 20 characters
senderAddressSiteName \| sender_address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50 characters
senderAddressPostcode \| senderAddressPostCode \| sender_address_postcode	String	Required if country requires post code	Can be used in conjunction with countryId to find unique site. Used for all address types	Max 10 characters
dropoffOfficeId \| dropOffOfficeId \| senderDropoffOfficeId \| senderDropOffOfficeId \| dropoff_office_id \| sender_dropoff_office_id	Integer	Required, if the sender is an internal customer. If sender address is provided, it is forbidden.	Drop off office id.	Should refer to a valid accessible office
sender_geo_pudo_id \| senderGeoPUDOId \| dropoff_geo_pudo_id \| dropoffGeoPUDOId	String	No. Must be empty if dropoffOfficeId is provided	DPD drop off office PUDO id	Should refer to a valid accessible DPD office.
Calculation recipient details If you refer an existing customer, provide client's id in recipient_id parameter and other recipient parameters may be skipped at all Otherwise, recipient_id should stay empty and it is required to provide as a minimum:. recipient privatePerson flag recipient address location or pickupOfficeId
recipientId \| recipient_id	Long	No	Client id to refer Ð° recipient	Validate for existence.
recipientPrivatePerson \| recipient_private_person	Boolean (true/false, y/n, âyes/noâ - all case insensitive)	If recipient_id is provided, it is forbidden. Otherwise, it is mandatory	Recipient private person flag.
Recipient Address Location Details See AddressLocation for more details. The recipient address location is expected when recipient_id is empty and recipient_pickup_office_id is empty and not required. In other words, the recipient address location is required when the recipient is not a referred customer and delivery at recipientâs address is expected.
recipientAddressCountryId \| recipient_address_country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.	Validate for valid country code
recipientAddressStateId \| recipient_address_state_id	String	Required if country requires state	Country state. Used for addresses of type 2 (foreign address).	Validate for valid country state.
recipientAddressSiteId \| recipient_address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided	Site id. Used for all address types	Validate for valid site and value is required
recipientAddressSiteType \| recipient_address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)	Max 20 characters
recipientAddressSiteName \| recipient_address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50 characters
recipientAddressPostcode \| recipientAddressPostCode \| recipient_address_postcode	String	Required if country requires post code	Can be used in conjunction with countryId to find unique site. Used for all address types	Max 10 characters
pickupOfficeId \| pickUpOfficeId \| recipientPickupOfficeId \| recipientPickUpOfficeId \| pickup_office_id \| recipient_pickup_office_id	Integer	Required, if the recipient is an internal customer. If recipient address is provided, it is forbidden.	Pickup office id.	Should refer to a valid accessible office
recipient_geo_pudo_id \| recipientGeoPUDOId \| pickup_geo_pudo_id \| pickupGeoPUDOId	String	No. Must be empty if pickupOfficeId is provided	DPD pickup office PUDO id	Should refer to a valid accessible DPD office.
Calculation Service Details See CalculationService for more details. Shipment service defines agreement with customer for courier service. This includes: Pickup date Service ids (codes) Optional defer days or saturday delivery Additional services (like COD, Declared value,and etc.)
pickupDate \| pickup_date	Date (date) Example: â2018-01-22"	No (default value is today)	The date for shipment pick-up	Could be today or a future date.
autoAdjustPickupDate \| auto_adjust_pickup_date \| autoadjust_pickup_date	Boolean	No (default is false)	To find first available date for pickup starting from pickupDate according to pickup schedule for services
serviceIds \| service_ids	String (comma separated service ids)	Yes	Service ids to get calculation for.	Each service id (code) should be valid for destination
deferredDays \| deferred_days	Integer	No (default value is 0)	This parameter allowscusers to specify by how many (business) days they would like to postpone the shipment delivery from the standard term..	Allowed values are 0, 1 and 2
saturdayDelivery \| saturday_delivery	Boolean	No)	This parameter may adjust the delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured recipient working schedule.
COD Additional Service For more information see ShipmentCODAdditionalService.
codAmount \| cod_amount	double	No	Defines shipment COD base amount.	Validated against maximum allowed amounts for destination.
codCurrency \| cod_currency	String	No (default is the currency code of the destination country)	Defines shipment COD currency code.	Validated against allowed currency code of destination country.
codProcessingType \| cod_processing_type	enum [“CASH”, “POSTAL_MONEY_TRANSFER”]	No (default is “CASH”)	Defines COD processing type.	Appropriate contract and annexes may be required.
codPayoutThirdParty \| cod_payout_third_party	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	If this flag is set, the COD is paid to a third party (not to the sender).	Requires the third party to be the payer of the courier service.
codWithShippingPrice \| cod_with_shipping_price	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Flag indicating whether the shipping price should be included in the COD.
Options before payment details Additional Service For more information see ShipmentOBPD.
obpd_option	enum [“OPEN”, “TEST”]	No (For certain destinations could be required.)	Defines option to be used. Open parcels before payment or open and test parcels before payment.	Return shipment is validated for destination.
obpd_return_service_id	Integer	No (For certain destinations could be required.)	Defines service id to be used on return, if COD payment is refused.	Return shipment is validated for destination.
obpd_return_payer	enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”]	No (For certain destinations could be required.)	Defines who pays the return shipment, if COD payment is refused.	Return shipment is validated for destination.
Declared Value (Extended Liability) Additional Service For more information see ShipmentDeclaredVaueAdditionalService. Declared value payer is required when declared value amount is provided and is set in payment section.
declaredValueAmount \| declared_value_amount	double	No	Defines shipment Declared Value (extended liability) base amount. Declared value amount is always in local system currency.	Validated against maximum allowed amounts.
fragile \| declaredValueFragile \| declared_value_fragile	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Defines fragile flag for shipment content.	Fragile shipments requires declared value sub service.
declaredValueIgnoreIfNotApplicable \| declared_value_ignore_if_not_applicable	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Flag to ignore declared value additional service in case it is not applicable for shipment on calculation	E-shops usually configure declared value (extended liability) by default for their shipments, However there are some certain internal rules when this option is not available. The flag is used in calculation service to provide price to end clients without repeating the calculation request with removed additional service
Fixed Time Delivery Additional Service Fixed time delivery is an additional service that provides instruction to deliver shipment at a certain time on the delivery date.
fixedTimeDelivery \| fixed_time_delivery	Integer	No	This option fixes the time of delivery on the delivery date. 1130 - means 11:30 920 - means 09:20	This option is checked against configured allowed time frame for the service.
Special Delivery Additional Service Special delivery is an additional service that provides instruction to the courier to do additional (special) checks and actions on delivery. These checks and actions are negotiated and contracted in a special delivery annex. For example, the courier could be instructed to check IDs of recipient party at delivery.
specialDeliveryId \| special_delivery_id	Integer	No	Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex.	Requires annex for special delivery.
Delivery to Floor Additional Service Delivery to floor is an additional service that provides instruction to the courier that the shipment should not be delivered to the entrance of a multi floor building, but should be moved to a certain floor before delivery.
deliveryToFloor \| delivery_to_floor	Integer	No	Specifies the floor number in the building where to deliver shipment.	This additional service requires annex.
Calculation Content For more information see CalculationContent. Defines what is to be delivered with the shipment.
parcelsCount \| parcels_count	Integer	Required when parcels list is empty	Total shipmentâs parcels count. Ignored, if parcels list is not empty. The parcels count is the number of parcels in the lits in that case	Validated against minimum and maximum allowed for the service
totalWeight \| total_weight	Double	Required when parcels list is empty	Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcelâs weight in that case.	Validated against minimum and maximum allowed for the service
documents	Boolean (true/false, y/n, âyes/noâ - all case insensitive)	No	Documents flag of the shipment
palletized	Boolean (true/false, y/n, âyes/noâ - all case insensitive)	No	Palletized flag of the shipment
parcels	String Format for single parcel is: <seqNo>,<weight>, <width>x<depth>x<height>, <packageUniqueNumber>, <id>, <externalCarrierParcelNumber> Multiple parcels should be separated with %7C (‘\|’) character. See ShipmentParcel	Required for pallet and postal services. For multiple parcels add the same url parameter again. The parameters are parsed in the order of their occurrence. If the sequence is incomplete, the missing parameters are considered empty.	List of parcels. If provided, parcel_count and total_weight are ignored	Validated against service configuration and pickup and delivery capacity of the depots and the couriers.
Shipment Payment For more information see ShipmentPayment. Defines who-pays-what in shipment and other payment parameters.
courierServicePayer \| courier_service_payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	Yes	Courier service payer.	Validated against the service, destination, contracts and annexes.
declaredValuePayer \| declared_value_payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	No	Declared value payer. If not provided, the courier service payer is assumed. Not expected, if the declared value amount is empty.	Validated against the service, destination, contracts and annexes.
packagePayer \| package_payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	No	Package payer. If not provided, the courier service payer is assumed.	Validated against the service, destination, contracts and annexes.
thirdPartyClientId \| third_party_client_id	Long	No	Defines shipment third party - used as a payer of any of shipment payable components.	Third party customer should be registered customer with valid contract and annex for delayed payment at pickup date. Third party customer should be customer(object) in the same contract as the logged user.
Discount card For more information see ShipmentDiscountCardId. Discount cards provide promotional discounts.
discountCardContractId \| discount_card_contract_id	Long	No	Discount card contract id.	Validated against a referred contract.
discountCardId \| discount_card_id	Long	No	Discount card id for contract.	Validated against a referred discount card.

2.7 Client Service

Web service URL: BASE_URL/client

2.7.1 Get Client Request (GetClientRequest)

Web service URL: BASE_URL/client/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get client by id. Client id is provided as parameter in URL path

GetClientRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

2.7.2 Get Client Response (GetClientResponse)

GetClientResponse
Name	Type	Mandatory	Data
client	Client	No	Client data
error	Error	No	Response error

2.7.3 Get Client Request - URL (GET) schema

This approach is used to get client by id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/client/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

Client id is provided as URL path paramter. The response is the same as method using JSON schema.

URL parameters:

GetClientRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

2.7.4 Get Contract Clients Request (GetContractClientsRequest)

Web service URL: BASE_URL/client/contract

Method: POST

Content-type: application/json; charset=utf-8

Get clients with same contract as logged user's one, if any

GetContractClientsRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

2.7.5 Get Contract Clients Response (GetContractClientsResponse)

GetContractClientsResponse
Name	Type	Mandatory	Data
clients	Client[]	No	Clients with same contract as logged users's one, if any
error	Error	No	Response error

2.7.6 Get Contract Clients Request - URL (GET) schema

This approach is used to get clients with the same contract as logged user's one, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/client/contract

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

GetContractClientsRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

2.7.7 Create Contact Request (CreateContactRequest)

Web service URL: BASE_URL/client/contact

Method: POST

Content-type: application/json; charset=utf-8

Create contact associating externalId as unique reference

CreateContactRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
externalContactId	String	Yes	External contact id (caller client Id unique reference)	Max 36 characters. Unique for caller
secretKey	String	No	External contact secret key	Max 36 characters
phone1	ShipmentPhoneNumber	Yes	Contact phone number (for example: +40799123456, 0040799123456, +359999123456 - international format numbers or 0799123456, 0999123456 - local numers).	Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. Only phone numbers starting with "0" (zero) or "+" sign are allowed.
phone2	ShipmentPhoneNumber	No	Contact phone number 2.	Validate for valid phone number, if presents.
clientName	String	Yes	Contact customer name.	Validate for valid name (minimum 3 symbols, maximum 60).
objectName	String	Forbidden for private persons. Not mandatory for companies	Contact customer object name.	Validate for valid name (maximum 60 symbols).
contactName	String	Forbidden for private persons. Required for companies	Contact name of contact	Maximum 60
email	String	No	Contact email.	Maximum 255
privatePerson	Boolean	Yes	Private person flag.
address	ShipmentAddress	Yes	Contact address.	Validated for valid values.

2.7.8 Create Contact Response (CreateContactResponse)

CreateContactResponse
Name	Type	Mandatory	Data
clientId	Long	No	Client Id associated for created contact in the system
error	Error	No	Response error

2.7.9 Create Contact Request - URL (GET) schema

This approach is used to create contact, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/client/contact

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

CreateContactRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
externalContactId \| external_contact_id	String	Yes	External contact id (caller client Id unique reference)	Max 30 characters. Unique for caller
secretKey \| secret_key	String	No	External contact secret key	Max 36 characters
phone1	String	Yes	First phone number.
phone1Ext \| phone1_ext	String	No	First phone number extension.
phone2	String	No	Second phone number.
phone2Ext \| phone2_ext	String	No	Second phone number extension.
clientName \| client_name	String	Yes	Conact customer name.	Minimum 3 symbols, maximum 60
objectName \| object_name	String	Forbidden for private persons. Not mandatory for companies	Conact customer object name.	Minimum 3 symbols, maximum 60
contactName \| contact_name	String	No Forbidden for private persons. Required for companies.	Contact name of contact.	Maximum 60.
email	String	No	Contact email.	Maximum 255
privatePerson \| private_person	Boolean (true/false, y/n, “yes/no” - all case insensitive)	Yes	Contact private person flag.
Contact Address See ShipmentAddress for more details.
addressCountryId \| address_country_id	Integer	No	Country ISO code. If not provided, local country is assumed. Used for all address types.
addressStateId \| address_state_id	String	Required, if country supports states.	Country state. Used for addresses of type 2 (foreign address).
addressSiteId \| address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided.	Site id. Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country
addressSiteType \| address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address).	Max 20
addressSiteName \| address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50
addressPostcode \| addressPostCode \| address_postcode	String	No	Can be used in conjunction with countryId to find unique site. Used for all address types.	Validated for valid postcode in site and country. Max 10
addressStreetId \| address_street_id	Long	No	Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
addressStreetType \| address_street_type	String	No Forbidden, if street_id is provided.	Street type. Used for addresses of type 1 (local address).	Max 15
addressStreetName \| address_street_name	String	No Forbidden, if street_id is provided.	Street name. Used for addresses of type 1 (local address).	Max 50
addressStreetNumber \| address_street_number	String	No	Street number. Used for addresses of type 1 (local address).	Max 10
addressComplexId \| address_complex_id	Long	No	Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
addressComplexType \| address_complex_type	String	No Forbidden, if complex_id is provided.	Complex type. Used for addresses of type 1 (local address).	Max 15
addressComplexName \| address_complex_name	String	No Forbidden, if complex_id is provided.	Complex name. Used for addresses of type 1 (local address).	Max 50
addressBlock \| addressBlockNo \| address_block	String	No	Block No. Used for addresses of type 1 (local address).	Max 32
addressEntrance \| addressEntranceNo \| address_entrance	String	No	Entrance. Used for addresses of type 1 (local address).	Max 10
addressFloor \| addressFloorNo \| address_floor	String	No	Floor. Used for addresses of type 1 (local address).	Max 10
addressApartment \| addressApartmentNo \| address_apartment	String	No	Apartment. Used for addresses of type 1 (local address).	Max 10
addressPoiId \| address_poi_id	Long	No	Point of interest identifier. Used for addresses of type 1 (local address).
addressNote \| address_note	String	No	Address note. Used for addresses of type 1 (local address).	200
addressLine1 \| address_line1	String	Required for address type 2	Address line 1. Used for addresses of type 2 (foreign address).	Max 35
addressLine2 \| address_line2	String	No	Address line 2. Used for addresses of type 2 (foreign address).	Max 35
addressX \| address_x	Double	No	GIS coordinates - X. Used for all address types.
addressY \| address_y	Double	No	GIS coordinates - Y. Used for all address types.

2.7.10 Get Contact By External Id Request (GetContactByExternalIdRequest)

Web service URL: BASE_URL/client/contact/external/{id}

Method: POST

Content-type: application/json; charset=utf-8

Get contact by external id. External client id is provided as parameter in URL path

GetContactByExternalIdRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
secretKey	String	No	Secret key	Max 36 characters

2.7.11 Get Contact By External Id Response (GetContactByExternalIdResponse)

GetContactByExternalIdResponse
Name	Type	Mandatory	Data
client	Client	No	Client data
error	Error	No	Response error

2.7.12 Get Contact By External Id Request - URL (GET) schema

This approach is used to get contact by external id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/client/contact/external/{id}

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

External contact id is provided as URL path parameter. The response is the same as method using JSON schema.

URL parameters:

GetContactByExternalIdRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
secretKey \| secret_key	String	No	Secret key	Max 36 characters

2.7.13 Get Own Client Id Request (GetOwnClientIdRequest)

Web service URL: BASE_URL/client

Method: POST

Content-type: application/json; charset=utf-8

Get own client id

GetOwnClientIdRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

2.7.14 Get Own Client Id Response (GetOwnClientIdResponse)

GetOwnClientIdResponse
Name	Type	Mandatory	Data
clientId	Long	Yes	Own client id
error	Error	No	Response error

2.7.15 Get Own Client Id Request - URL (GET) schema

This approach is used to get own client id, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/client

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

GetOwnClientIdRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

2.7.16 Contract Info Request (ContractInfoRequest)

Web service URL: BASE_URL/client/contract/info

Method: POST

Content-type: application/json; charset=utf-8

Get information about logged user contract

ContractInfoRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.

2.7.17 Contract Info Response (ContractInfoResponse)

ContractInfoResponse
Name	Type	Mandatory	Data
id	Long	Yes	Contract id
specialDeliveryRequirements	SpecialDeliveryRequirements	No	Special delivery requirements
error	Error	No	Response error

2.7.18 Contract Info Request - URL (GET) schema

This approach is used to get contract information, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/client/contract/info

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

ContractInfoRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.

2.8 Validation Service

Web service URL: BASE_URL/validation

2.8.1 Validate Address Request (ValidateAddressRequest)

Web service URL: BASE_URL/validation/address

Method: POST

Content-type: application/json; charset=utf-8

This method validates shipment address

ValidateAddressRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
address	ShipmentAddress	No	Shipment address to validate

2.8.2 Validate Address Response (ValidationResponse)

ValidationResponse
Name	Type	Mandatory	Data
valid	Boolean	No	Validation result flag
error	Error	No	Response error

2.8.3 Validate Address Request - URL (GET) schema

This approach is used to validate address, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/validation/address

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

ValidateAddressRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
Shipment Address See ShipmentAddress for more details.
countryId \| country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.
stateId \| state_id	String	Required, if country supports states.	Country state. Used for addresses of type 2 (foreign address).
siteId \| site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided.	Site id. Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country
siteType \| site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address).	Max 20
siteName \| site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50
postcode \| postCode \| post_code	String	No	Can be used in conjunction with countryId to find unique site. Used for all address types.	Validated for valid postcode in site and country. Max 10
streetId \| street_id	Long	No	Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
streetType \| street_type	String	No Forbidden, if street_id is provided.	Street type. Used for addresses of type 1 (local address).	Max 15
streetName \| street_name	String	No Forbidden, if street_id is provided.	Street name. Used for addresses of type 1 (local address).	Max 50
streetNumber \| street_number	String	No	Street number. Used for addresses of type 1 (local address).	Max 10
complexId \| complex_id	Long	No	Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address).
complexType \| complex_type	String	No Forbidden, if complex_id is provided.	Complex type. Used for addresses of type 1 (local address).	Max 15
complexName \| complex_name	String	No Forbidden, if complex_id is provided.	Complex name. Used for addresses of type 1 (local address).	Max 50
block \| blockNo \| block_no	String	No	Block No. Used for addresses of type 1 (local address).	Max 32
entrance \| entranceNo \| entrance_no	String	No	Entrance. Used for addresses of type 1 (local address).	Max 10
floor \| floorNo \| floor_no	String	No	Floor. Used for addresses of type 1 (local address).	Max 10
apartment \| apartmentNo \| apartment_no	String	No	Apartment. Used for addresses of type 1 (local address).	Max 10
poiId \| poi_id	Long	No	Point of interest identifier. Used for addresses of type 1 (local address).
addressNote \| address_note \| note	String	No	Address note. Used for addresses of type 1 (local address).	200
addressLine1 \| address_line1 \| line1	String	Required for address type 2.	Address line 1. Used for addresses of type 2 (foreign address).	Max 35
addressLine2 \| address_line2 \| line2	String	No	Address line 2. Used for addresses of type 2 (foreign address).	Max 35
X \| x	Double	No	GIS coordinates - X. Used for all address types.
Y \| y	Double	No	GIS coordinates - Y. Used for all address types.

2.8.4 Validate Postcode Request (ValidatePostCodeRequest)

Web service URL: BASE_URL/validation/postcode

Method: POST

Content-type: application/json; charset=utf-8

This method validates post code

ValidatePostCodeRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
countryId	Integer	Yes - if siteId is not specified	Country id
siteId	Long	Yes - if countryId is not specified	Site id
postCode	String	Yes	Postcode to validate

2.8.5 Validate Postcode Response (ValidationResponse)

Same as 2.8.2 ValidationResponse

2.8.6 Validate Postcode Request - URL (GET) schema

This approach is used to validate post code, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/validation/postcode

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

ValidatePostCodeRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
countryId \| country_id	Integer	Yes - if siteId is not specified	Country id
siteId \| site_id	Long	Yes - if countryId is not specified	Site id
postcode \| postCode \| post_code	String	Yes	Postcode to validate

2.8.7 Validate Phone Request (ValidatePhoneRequest)

Web service URL: BASE_URL/validation/phone

Method: POST

Content-type: application/json; charset=utf-8

This method validates phone number

ValidatePhoneRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
number	String	Yes	Phone number
ext	String	No	Phone number extension

2.8.8 Validate Phone Response (ValidationResponse)

Same as 2.8.2 ValidationResponse

2.8.9 Validate Phone Request - URL (GET) schema

This approach is used to validate phone, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/validation/phone

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

ValidatePhoneRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
number	String	Yes	Phone number
ext	String	No	Phone number extension

2.8.10 Validate Shipment Request (ValidateShipmentRequest)

Web service URL: BASE_URL/validation/shipment

Method: POST

Content-type: application/json; charset=utf-8

This method applies validation on shipment request

Input parameters:

ValidateShipmentRequest
Name	Type	Required	Data	Constraints
CreateShipmentRequest fields are here

2.8.11 Validate Shipment Response (ValidateShipmentResponse)

Same as 2.8.2 ValidationResponse

2.8.12 Validate Shipment - URL (GET) Schema

This approach is used to validate shipments, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/validation/shipment

Method: GET

Content-type: “application/x-www-form-urlencoded; charset=utf-8”

The response is the same as method using JSON schema.

URL parameters:

ValidateShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

CreateShipmentRequest params are here

2.9 Services Service

Web service URL: BASE_URL/services

2.9.1 Services Request (ServicesRequest)

Web service URL: BASE_URL/services

Method: POST

Content-type: application/json; charset=utf-8

Get available services for date

ServicesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
date	Date (yyyy-MM-dd)	No	Date. Current date is assumed if not provided

2.9.2 Services Response (ServicesResponse)

ServicesResponse
Name	Type	Mandatory	Data
services	CourierService[]	Yes	Available courier services
error	Error	No	Response error

2.9.3 Services Request - URL (GET) schema

This approach is used to get services, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/services

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

ServicesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
date	Date (yyyy-MM-dd)	No	Date. Current date is assumed if not provided

2.9.4 Destination Services Request (DestinationServicesRequest)

Web service URL: BASE_URL/services/destination

Method: POST

Content-type: application/json; charset=utf-8

Get available services for date and destination

DestinationServicesRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
date	Date (yyyy-MM-dd)	No	Date. Current date is assumed if not provided
sender	CalculationSender	No	Defines the pickup place. If not specified, the logged user client location is considered as a sender location.
recipient	CalculationRecipient	Yes	Defines the recipient delivery place.

2.9.5 Destination Services Response (DestinationServicesResponse)

DestinationServicesResponse
Name	Type	Mandatory	Data
services	ExtendedCourierService[]	Yes	Available courier services for destination
error	Error	No	Response error

2.9.6 Destination Services Request - URL (GET) schema

This approach is used to get services for date and destination, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/services/destination

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

DestinationServicesRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
date	Date (yyyy-MM-dd)	No	Date. Current date is assumed if not provided
Calculation sender details If logged user is the sender, you may skip providing sender details at all. If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also. Otherwise, sender_id should stay empty and it is required to provide as a minimum: sender privatePerson flag sender address location or dropoffOfficeId
senderId \| sender_id	Long	No	Client id to refer Ð° sender	Validate for existence.
senderPrivatePerson \| sender_private_person	Boolean (true/false, y/n, âyes/noâ - all case insensitive)	If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory	Sender private person flag.
Sender Address Location Details See AddressLocation for more details. The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at senderâs address is expected.
senderAddressCountryId \| sender_address_country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.	Validate for valid country code
senderAddressStateId \| sender_address_state_id	String	Required if country requires state	Country state. Used for addresses of type 2 (foreign address).	Validate for valid country state.
senderAddressSiteId \| sender_address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided	Site id. Used for all address types	Validate for valid site and value is required
senderAddressSiteType \| sender_address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)	Max 20 characters
senderAddressSiteName \| sender_address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50 characters
senderAddressPostcode \| senderAddressPostCode \| sender_address_postcode	String	Required if country requires post code	Can be used in conjunction with countryId to find unique site. Used for all address types	Max 10 characters
dropoffOfficeId \| dropOffOfficeId \| senderDropoffOfficeId \| senderDropOffOfficeId \| dropoff_office_id \| sender_dropoff_office_id	Integer	Required, if the sender is an internal customer. If sender address is provided, it is forbidden.	Drop off office id.	Should refer to a valid accessible office
Calculation recipient details If you refer an existing customer, provide client's id in recipient_id parameter and other recipient parameters may be skipped at all Otherwise, recipient_id should stay empty and it is required to provide as a minimum:. recipient privatePerson flag recipient address location or pickupOfficeId
recipientId \| recipient_id	Long	No	Client id to refer Ð° recipient	Validate for existence.
recipientPrivatePerson \| recipient_private_person	Boolean (true/false, y/n, âyes/noâ - all case insensitive)	If recipient_id is provided, it is forbidden. Otherwise, it is mandatory	Recipient private person flag.
Recipient Address Location Details See AddressLocation for more details. The recipient address location is expected when recipient_id is empty and recipient_pickup_office_id is empty and not required. In other words, the recipient address location is required when the recipient is not a referred customer and delivery at recipientâs address is expected.
recipientAddressCountryId \| recipient_address_country_id	Integer	No	Country ISO code. If not provided, the local country is assumed. Used for all address types.	Validate for valid country code
recipientAddressStateId \| recipient_address_state_id	String	Required if country requires state	Country state. Used for addresses of type 2 (foreign address).	Validate for valid country state.
recipientAddressSiteId \| recipient_address_site_id	Long	Required, if country has full site nomenclature and pair (site_type, site_name) not provided	Site id. Used for all address types	Validate for valid site and value is required
recipientAddressSiteType \| recipient_address_site_type	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)	Max 20 characters
recipientAddressSiteName \| recipient_address_site_name	String	Forbidden, if site id is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.	Max 50 characters
recipientAddressPostcode \| recipientAddressPostCode \| recipient_address_postcode	String	Required if country requires post code	Can be used in conjunction with countryId to find unique site. Used for all address types	Max 10 characters
pickupOfficeId \| pickUpOfficeId \| recipientPickupOfficeId \| recipientPickUpOfficeId \| pickup_office_id \| recipient_pickup_office_id	Integer	Required, if the recipient is an internal customer. If recipient address is provided, it is forbidden.	Pickup office id.	Should refer to a valid accessible office

2.10 Payments Service

Web service URL: BASE_URL/payments

2.10.1 Payout Request (PayoutRequest)

Web service URL: BASE_URL/payments

Method: POST

Content-type: application/json; charset=utf-8

Get shipment payout details for a period

PayoutRequest
Name	Type	Required	Data	Constraints
userName	String	Yes	User name
password	String	Yes	Password
language	String	No
clientSystemId	Long	No	Client system id	Validated against system register for external customers.
fromDate	DateTime (yyyy-MM-dd'T'HH:mm:ssZ)	Yes	Start of period date time.
toDate	DateTime (yyyy-MM-dd'T'HH:mm:ssZ)	Yes	End of period date time.
includeDetails	boolean	No (default value is false)	Include payout details flag

2.10.2 Payout Response (PayoutResponse)

PayoutResponse
Name	Type	Mandatory	Data
payouts	Payout[]	Yes	Shipment payouts for a period
error	Error	No	Response error

2.10.3 Payout Request - URL (GET) schema

This approach is used to get shipment payouts, providing data in an URL instead of JSON data in the content.

Web service URL: BASE_URL/payments

Method: GET

Content-type: application/x-www-form-urlencoded; charset=utf-8

The response is the same as method using JSON schema.

URL parameters:

PayoutRequest
URL Parameter Name (synonyms are separated with \|)	Type	Required	Data	Constraints
userName \| username \| user_name	String	Yes	User name
password	String	Yes	Password
language \| lang	String	No
clientSystemId \| client_system_id	Long	No	Client system id	Validated against system register for external customers.
date_from	Date (yyyy-MM-dd'T'HH:mm:ssZ)	Yes	Start of period date time.
date_to	Date (yyyy-MM-dd'T'HH:mm:ssZ)	Yes	End of period date time.
include_details	boolean (true/false, y/n, “yes/no” - all case insensitive)	No (Default value is false)	Flag to include payout details.

3 Data Structures

3.1 Shipment Service (ShipmentService)

Shipment service defines service level agreement for the shipment - when shipment should be picked up, service code to be used, sub-services, etc.

ShipmentService
Name	Type	Required	Data	Constraints
pickupDate	Date Example: “2017-11-21"	No (default value is today)	The date for shipment pickup.	Could be today or a future date.
autoAdjustPickupDate	Boolean	No (default value is false)	To find first available date for pickup starting from pickupDate according to pickup schedule for services
serviceId	int	Yes	Service to be used for the shipment.	Service id (code) should be valid for the destination.
additionalServices	ShipmentAdditionalServices	No	Defines sub-services (like COD, Declared value, etc.) associated with the shipment.	Sub-services may be allowed or forbidden for selected service and/or destination.
deferredDays	Integer	No (default value is 0)	This parameter allows users to specify by how many (business) days they would like to postpone the shipment delivery from the standard term.	Allowed values are 0, 1 and 2.
saturdayDelivery	Boolean	No	This parameter may adjust delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured delivery customer working schedule.

Example:

{

"pickupDate":"2017-11-21",

"serviceId":2,

"additionalServices":{

"cod":{

"amount":100.0,

"currencyCode":"RON",

"payoutToThirdParty":false,

"processingType":"CASH",

"includeShippingPrice":false

"declaredValue":{

"amount":100.0,

"fragile":false

"fixedTimeDelivery": 1130,

"returns":{

"rod":{

"enabled":true,

"comment":"Ret doc comment",

"returnToClientId":1234567,

"thirdPartyPayer":false

"returnReceipt":{

"enabled":true,

"returnToClientId":1234567,

"thirdPartyPayer":false

"swap":{

"serviceId":3,

"parcelsCount":2,

"declaredValue":13.0,

"fragile":false,

"returnToClientId":1234567

"rop":{

"pallets":[

{

"serviceId":601,

"parcelsCount":3

{

"serviceId":602,

"parcelsCount":2

}

]

"returnVoucher":{

"serviceId":3,

"payer":"RECIPIENT"

}

"specialDeliveryId":2,

"deliveryToFloor":3

"deferredDays":2,

"saturdayDelivery":true

}

3.1.1 Shipment Additional Services (ShipmentAdditionalServices)

Allowance of additional services usage in the shipments is controlled and determined by the courier service configuration. All shipment additional services could be either:

forbidden for usage with selected courier service
allowed for usage with selected courier service
required for usage with selected courier service

Some of the additional services may require additional prerequisites (like valid contracts and annexes or serving offices in pickup or delivery site) to be available for usage.

ShipmentSubServices
Name	Type	Required	Data	Constraints
cod	ShipmentCODAdditionalService	No	Defines shipment COD sub-service.	Seller could be required to have a valid contract and annex for COD for the destination.
obpd	ShipmentOBPD	No	Defines shipment options before payment details.
declaredValue	ShipmentDeclaredValueAdditionalService	No	Defines shipment declared value (extended liability) sub-service.
fixedTimeDelivery	Integer	No	This option fixes the time of delivery on the delivery date. 1130 - means 11:30 920 - means 09:20	This option is checked against the configured allowed time frame for the service.
returns	ShipmentReturnAdditionalServices	No	Defines a return sub-services.	Return shipments are verified for a return destination.
specialDeliveryId	Integer	No	Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex.	Requires an annex for special delivery.
deliveryToFloor	Integer	No	Specifies the floor number in the building where to deliver the shipment.	This sub-service requires an annex.

Example JSON:

{

"cod":{

"amount":100.0,

"currencyCode":"RON",

"payoutToThirdParty":false,

"processingType":"CASH",

"includeShippingPrice":false

"declaredValue":{

"amount":100.0,

"fragile":false

"fixedTimeDelivery": 1130,

"returns":{

"rod":{

"enabled":true,

"comment":"Ret doc comment",

"returnToClientId":66666666,

"thirdPartyPayer":false

"returnReceipt":{

"enabled":true,

"returnToClientId":66666666,

"thirdPartyPayer":false

"swap":{

"serviceId":3,

"parcelsCount":2,

"declaredValue":13.0,

"fragile":false,

"returnToClientId":66666666

"rop":{

"pallets":[

{

"serviceId":601,

"parcelsCount":3

{

"serviceId":602,

"parcelsCount":2

}

]

"returnVoucher":{

"serviceId":3,

"payer":"RECIPIENT"

}

"specialDeliveryId":2,

"deliveryToFloor":3

"deferredDays":2,

"saturdayDelivery":true

}

Or simplest case (COD, with SWAP and ROD and disabled saturday delivery):

{

"cod":{

"amount":100.0,

"returns":{

"rod":{

"enabled":true,

"swap":{

"serviceId":3,

"parcelsCount":2,

}

"saturdayDelivery":false

}

3.1.1.1 COD Additional Service (ShipmentCODAdditionalService)

ShipmentCODAdditionalService
Name	Type	Required	Data	Constraints
amount	double	Yes	Defines shipment COD base amount.	Validated against the maximum allowed amounts for the destination.
currencyCode	String	No (default is the currency code for destination country)	Defines shipment COD currency code.	Validated against the allowed currency code for destination country.
processingType	enum [“CASH”, “POSTAL_MONEY_TRANSFER”]	No (default is “CASH”)	Defines COD processing type.	Appropriate contract and annexes may be required.
payoutToThirdParty	Boolean	No	If this flag is set, the COD is paid to third party (not to the sender).	Requires a third party to be the payer of the courier service.
payoutToLoggedClient	Boolean	No	If this flag is set, the COD is paid to the logged client.
includeShippingPrice	Boolean	No	Flag indicating whether the shipping price should be included in the COD.
cardPaymentForbidden	Boolean	No	Flag indicating that COD/PMT card payment is forbidden.

Example full JSON:

{

"amount":100.0,

"currencyCode":"RON",

"payoutToThirdParty":false,

"processingType":"CASH",

"includeShippingPrice":false

"cardPaymentForbidden":false

}

Or the simplest case:

{

"amount":100.0

}

3.1.1.2 Declared Value (Extended Liability) Additional Service(ShipmentDeclaredValueAdditionalService)

ShipmentDeclaredValueAdditionalService
Name	Type	Required	Data	Constraints
amount	double	Yes	Defines shipment Declared Value base amount. Declared value amount is always in local system currency.	Validated against the maximum allowed amounts.
fragile	Boolean	No	Defines fragile flag for shipment content.	Fragile shipments require a declared value sub service.
ignoreIfNotApplicable	Boolean	No (Used in calculation service only, ignored in create shipment service)	Flag to ignore declared value additional service in case it is not applicable for shipment on calculation	E-shops usually configure declared value (extended liability) by default for their shipments, However there are some certain internal rules when this option is not available. The flag is used in calculation service to provide price to end clients without repeating the calculation request with removed additional service

Example JSON:

{

"amount":100.0,

"fragile":false

}

Or using defaults you can specify 100.00 base amount non-fragile shipment with courier service payer with just:

{

"amount":100.0

}

3.1.1.2 Shipment Return Additional services (ShipmentReturnAdditionalServices)

Defines series of return sub-services, which require a reverse shipment to be generated at primary shipment delivery. All the reverse shipments are validated for allowance and for destination.

ShipmentReturnAdditionalServices
Name	Type	Required	Data	Constraints
rod	ShipmentRODAdditionalService	No	Defines Return Of Documents (ROD) sub-service.	The reverse shipment is validated for service and destination.
returnReceipt	ShipmentReturnReceiptAdditionalService	No	Defines Return Receipt sub-service.	The reverse shipment is validated for service and destination.
swap