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
Letters in text fields which are not in Windows-1251 encoding (ANSI (Latin) + Cyrillic + some special characters) are transliterated to Latin alphabet in Windows-1251 character encoding table. For more details visit https://en.wikipedia.org/wiki/Windows-1251.

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.
id	String	No	Shipment id	Shipment ID from provided range. If shipment ID is empty the system will generate and return it in response
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.
id	String	No	Shipment id	Shipment ID from provided range. If shipment ID is empty the system will generate and return it in response
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_auto_select_nearest_office \| recipientAutoSelectNearestOffice	boolean	No	Not supported for every destination country	Must be supported for destination country
Auto-select Nearest Office Policy See AutoSelectNearestOfficePolicy for more details. Defines policy for nearest office auto selection. Applicable if recipientAutoSelectNearestOffice is true
recipientUnavailableNearestOfficeAction \| recipient_unavailable_nearest_office_action	enum [“DELIVERY_TO_ADDRESS”, “CANCEL_WITH_ERROR”]	No (default is “DELIVERY_TO_ADDRESS”)	Defines the policy to handle cases when nearest office is not available.
recipientNearestOfficeType \| recipient_nearest_office_type	enum [“OFFICE”, “APT”]	No	Not supported for every destination country	Office type filter. Values can be: “OFFICE” - select nearest office “APT” - select nearest locker (APT) No office filter selection is applied if value is not specified
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.
cod_fiscal_receipt_items	String Format for fiscal report item is: <description>,<vatGroup>, <amount>,<amountWithVat> Multiple fiscal report should be separated with %7C (‘\|’) character. See ShipmentCODFiscalReceiptItem	No	List of items in COD fiscal receipt to issue receipt on behalf of client.If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.	This feature depends on country regulations and must be enabled for client contract.The value in cod amount field is ignored if fiscal receipt items are provided.
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 / Electronic Return Receipt, ROP and SWAP, if the sub service presents.
Electronic 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.
electronicReceiptEmails \| electronic_receipt_emails	String[] String values are separeted by ','(comma) or ';'(semicolon)	No	List of electronic return receipt recipient emails
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 / Electronic 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 / Electronic 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 / Electronic 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.
lq	Boolean (true/false, y/n, “yes/no” - all case insensitive)	No	Flag shipment contains dangerous goods in limited quantities.
goodsValue	Double	No Required for pallet services (for Romanian shipments)	Defines shipment goods value amount.	Validated against maximum allowed amount.
goodsValueCurrencyCode	String	No Required, if goodsValue is provided.	Defines shipment goods value currency code.	Requires a valid currency code.
uitCode	String	No Required for Romanian shipments in cases defined by Romanian regulations.	Shipment UIT code.	Requires a valid UIT code.
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
codFiscalReceiptItems	ShipmentCODFiscalReceiptItem[]	This feature depends on country regulations and must be enabled for client contract. The value in codAmount is ignored if fiscal receipt items are provided. To use fiscal receipt items in this method the shipment must have COD defined with fiscal receipt already or COD must be emty	List of items to add in current fiscal receipt items list to issue receipt on behalf of client If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.
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
cod_fiscal_receipt_items	String Format for fiscal report item is: <description>,<vatGroup>, <amount>,<amountWithVat> Multiple fiscal report should be separated with %7C (‘\|’) character. See ShipmentCODFiscalReceiptItem	No	List of items to add in current fiscal receipt items list to issue receipt on behalf of client. If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.	This feature depends on country regulations and must be enabled for client contract. The value in codAmount is ignored if fiscal receipt items are provided. To use fiscal receipt items in this method the shipment must have COD defined with fiscal receipt already or COD must be emty
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 - see ShipmentAddress) for this country
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
cod	CODAdditionalServiceContractInfo	No	COD contract info
administrativeFeeAllowed	boolean	Yes	Administrative fee allowed
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.
fiscalReceiptItems	ShipmentCODFiscalReceiptItem[]	This feature depends on country regulations and must be enabled for client contract The value in amount field is ignored if fiscal receipt items are provided.	List of items to issue fiscal receipt on behalf of client If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.

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.1.1 Shipment COD Fiscal Receipt Item (ShipmentCODFiscalReceiptItem)

COD fiscal receipt item is used to form COD fiscal receipt to be issued on behalf of client

ShipmentCODFiscalReceiptItem
Name	Type	Required	Data	Constraints
description	String	Yes	Fiscal receipt item description	Max 50 characters
vatGroup	String	Yes	VAT group	Must match one of available VAT groups (for example "А" - 0% VAT, "Б" - 20%VAT, ...).
amount	double	Yes	Item amount before VAT.	Must be positive value
amountWithVat	double	Yes	Item amount with VAT included	Must not be lower that amount before VAT

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.3 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. Cannot be specified if electronicReturnReceipt is provided	The reverse shipment is validated for service and destination.
electronicReturnReceipt	ShipmentElectronicReturnReceiptAdditionalService	No	Defines electronic Return Receipt sub-service (return receipt by email). Cannot be specified if returnReceipt is provided	Electronic return receipt requires email.
swap	ShipmentSWAPAdditionalService	No	Defines SWAP sub-service.	The reverse shipment is validated for service and destination.
rop	ShipmentROPAdditionalService	No	Defines Return Of Pallets (ROP) sub-service.	The reverse shipment is validated for service and destination.
returnVoucher	ShipmentReturnVoucherAdditionalService	No	Defines Return Voucher associated with the shipment.	The reverse shipment is validated for service and destination.
sendBackClientId	Long	No	Client id to specify send back address in case of a shipment return. Used in shipment returns after Check/Test or in case recipient is not found. If not specified the shipment is returned to the primary shipment sender.	Should be a customer address (object) in the same contract as the sender of the shipment.

Example JSON:

{

"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"

}

Or a simpler scenario (ROD, Return Receipt and SWAP):

{

"rod":{

"enabled":true

"returnReceipt":{

"enabled":true

"swap":{

"serviceId":3,

"parcelsCount":2

}

3.1.1.3.1 Return of Documents (ROD) Additional service (ShipmentRODAdditionalService)

Return of Documents (ROD) additional service requires documents to be returned upon the delivery of the primary shipment.

ShipmentRODAdditionalService
Name	Type	Required	Data	Constraints
enabled	boolean	Yes	Enabled flag
comment	String	No	Return documents comment.	Max size 512
returnToClientId	Long	No	Defines the recipient for the ROD shipment. If not specified and returnToOfficeId is not specified also, the reverse shipment is returned to the primary shipment sender.	Cannot be specified together with returnToOfficeId. The same value should be set for ROD and Return Receipt, if the sub-service presents. Cannot be specified if SWAP presents
returnToOfficeId	Integer	No	Defines delivery pickup depot for the ROD shipment. If not specified and returnToClientId is not specified also, the reverse shipment is returned to the primary shipment sender.	Cannot be specified together with returnToClientId. The same value should be set for ROD, Return Receipt and SWAP, if the sub-service presents.
thirdPartyPayer	Boolean	No	Defines a third party payer for the ROD shipment. Otherwise the 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.

Example JSON:

{

"enabled":true,

"comment":"Ret doc comment",

"returnToClientId":12345678,

"thirdPartyPayer": false

}

Or with default values:

{

"enabled":true

}

3.1.1.3.2 Return Receipt Additional Service (ShipmentReturnReceiptAdditionalService)

Return Receipt additional service requires receipt to be returned upon the delivery of the primary shipment.

3.1.1.3.3 SWAP Additional Service (ShipmentSWAPAdditionalService)

SWAP additional service requires shipment with predefined parameters to be returned upon the delivery of the primary shipment.

ShipmentSWAPAdditionalService
Name	Type	Required	Data	Constraints
serviceId	int	Yes	Service to be used in return.	Validated for allowance and destination.
parcelsCount	int	Yes	Number of parcels to return.	Validated against maximum allowed parcels.
declaredValue	Double	No	Declared value (extended liability) for the reverse shipment.	Validated for allowance and maximum amount.
fragile	Boolean	No	Fragile content flag for the reverse shipment.	Fragile shipments require declared value.
returnToOfficeId	Integer	No	Defines delivery pickup depot for the SWAP shipment. If not specified, the reverse shipment is returned to the primary shipment sender.	The same values should be set for ROD, Return Receipt and SWAP, if the sub-service presents.
thirdPartyPayer	Boolean	No	Defines a third party payer for the SWAP shipment. Otherwise the payer is the primary shipment recipient.	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.

Example JSON:

{

"serviceId":3,

"parcelsCount":2,

"declaredValue":13.0,

"fragile":false,

"returnToClientId":12345678

}

Or with default values:

{

"serviceId":3,

"parcelsCount":2

}

3.1.1.3.4 Return of Pallets (ROP) Additional Service (ShipmentROPAdditionalService)

Return Of Pallets additional service requires shipment with predefined parameters to be returned upon the delivery of the primary shipment.

ShipmentROPAdditionalService
Name	Type	Required	Data	Constraints
pallets	ShipmentROPAdditionalServiceLine[]	Yes	Defines pallets to return grouped by service id.	Total number of returned pallets should not exceed the parcel count of the primary shipment.
thirdPartyPayer	Boolean	No	Defines a third party payer for the returned pallets. Otherwise the 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 / Electronic Return Receipt, ROP and SWAP, if the sub service presents.

Example JSON:

[

{

"serviceId":601,

"parcelsCount":3

{

"serviceId":2605,

"parcelsCount":2

}

]

3.1.1.3.4.1 ROP Additional Service Lines (ShipmentROPAdditionalServiceLine)

Return Of Pallet (ROP) sub service lines define for each return of pallet service how many parcels (pallets) should be returned.

ShipmentROPAdditionalServiceLine
Name	Type	Required	Data	Constraints
serviceId	int	Yes	ROP service to be used.	Validated against destination.
parcelsCount	int	Yes	Number of parcels to return.

Example JSON:

{

"serviceId":601,

"parcelsCount":3

}

3.1.1.3.5 Return Voucher Additional Service (ShipmentReturnVoucherAdditionalService)

Return Voucher sub service provides an option to the recipient to initiate a return within predefined voucher validity period, using the voucher preferences.

ShipmentReturnVoucherSubService
Name	Type	Required	Data	Constraints
serviceId	int	Yes	Service id of the return shipment.
payer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	Yes	Defines a return voucher payer.	Allowed payers are validated against the service configuration and destination.
validityPeriod	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

Example JSON:

{

"serviceId":3,

"payer":"RECIPIENT"

}

3.1.1.3.6 Electronic Return Receipt Additional Service (ShipmentElectronicReturnReceiptAdditionalService)

Electronic Return Receipt additional service requires receipt to be returned as an email attachment upon the delivery of the shipment

ShipmentElectronicReturnReceiptAdditionalService
Name	Type	Required	Data	Constraints
recipientEmails	String[]	Yes	List of electronic return receipt recipient emails
thirdPartyPayer	Boolean	No	Defines a third party payer for the Electronic Return Receipt. Otherwise the 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 / Electronic Return Receipt, ROP and SWAP, if the sub service presents.

3.1.1.4 Options before payment details Additional Service (ShipmentOBPD)

Options before payment are needed to define what options recipient has on delivery before the payment of the COD. User can open parcels or open and test the content of the parcels. Recipient may accept parcels and pay the COD or refuse to pay and return the parcels. The return shipment details are specified in the options also.

ShipmentOBPD
Name	Type	Required	Data	Constraints
option	enum [“OPEN”, “TEST”]	Yes	Defines the option to be used. Open parcels on payment or open and test parcels before payment.
returnShipmentServiceId	Integer	Yes	Defines service id to be used on return.
returnShipmentPayer	enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”]	Yes	Defines who pays the return shipment.

Example JSON:

{

"option":"TEST",

"returnShipmentServiceId":2,

"returnShipmentPayer":"SENDER"

}

3.2 Shipment Content (ShipmentContent)

Shipment content is used to describe what is to be delivered with the shipment.

ShipmentContent
Name	Type	Required	Data	Constraints
parcelsCount	Integer	Required when parcels list is empty.	Total shipment 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 the minimum and maximum allowed for the service.
totalWeight	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 parcels declaredWeight in that case.	Validated against the minimum and maximum allowed for the service.
contents	String	Yes	Shipment content’s description.	100
package	String	Yes	Shipment package.	50
documents	Boolean	No	Documents flag of the shipment.
palletized	Boolean	No	Palletized flag of the shipment.
parcels	ShipmentParcel[]	Required for pallet and postal services.	Parcels. If omitted a single default (first) parcel will be created for non-pallet and non-postal services.	Validated against the service configuration and pickup and delivery capacity of the depots and couriers.
pendingParcels	Boolean	No	If this flag is true, the shipment is created in pending parcels state. Shipments in pending parcels state allows adding parcels with addParcel method. Pending parcels state is closed with finalizePendingShipment method.
exciseGoods	Boolean	No	Flag shipment contains excise goods.
lq	Boolean	No	Flag shipment contains dangerous goods in limited quantities.
goodsValue	Double	No Required for pallet services (for Romanian shipments)	Defines shipment goods value amount.	Validated against maximum allowed amount.
goodsValueCurrencyCode	String	No Required, if goodsValue is provided.	Defines shipment goods value currency code.	Requires a valid currency code.
uitCode	String	No Required for Romanian shipments in cases defined by Romanian regulations.	Shipment UIT code.	Requires a valid UIT code.

Example JSON:

{

"contents":"FURNITURE",

"package":"BOX",

"documents":false,

"palletized":false,

"parcels":[

{

"seqNo":1,

"size":{

"width":80,

"depth":120,

"height":110

"weight":80.0,

"externalCarrierParcelNumber":"1726912312312313"

{

"seqNo":2,

"size":{

"width":80,

"depth":122,

"height":100

"weight":83.0,

"externalCarrierParcelNumber":"1726912312312315"

{

"seqNo":3,

"size":{

"width":83,

"depth":125,

"height":116

"weight":85.0,

"externalCarrierParcelNumber":"1726912312312314"

}

"pendingParcels":false

}

Or:

{

"contents":"FURNITURE",

"package":"BOX",

"parcels":[

{

"seqNo":1,

"weight":80.0

{

"seqNo":2,

"weight":83.0

{

"seqNo":3,

"weight":85.0

}

]

}

Or (for non-pallet and non-postal services):

{

"parcelsCount":3,

"totalWeight":248.0,

"contents":"FURNITURE",

"package":"BOX"

}

3.2.1 Shipment Parcel (ShipmentParcel)

Shipment parcel data structure.

ShipmentParcel
Name	Type	Required	Data	Constraints
id	String	No	Parcel identifier - barcode (if it is known).
seqNo	Integer	Required in createShipment method. Ignored in addParcel (auto-generated in this case)	Parcel sequence number in the shipment.	Should be unique for the shipment.
packageUniqueNumber	Long	No	Package number associated with parcel.
size	ShipmentParcelSize	Required for pallet and postal services.	Parcel size (width, height, depth) in cm.	Validated against the capacity of the couriers and depots. Used to calculate the volume weight, if applicable.
weight	double	Yes	Parcel weight in kg.	Validated against the capacity of the couriers and depots and service configuration.
ref1	String	No	Reference number or text.	20
ref2	String	No	Reference number or text.	20
pickupExternalCarrierParcelNumber	ExternalCarrierParcelNumber	No	External carrier parcel id for pickup
deliveryExternalCarrierParcelNumber	ExternalCarrierParcelNumber	No	External carrier parcel id for delivery

The declared weight of a parcel (used for price calculation) is the maximum of the weight and the volume weight (calculated from size). Volume weight in some cases is not calculated (for example for pallets).

Example JSON:

{

"seqNo":1,

"size":{

"width":80,

"depth":120,

"height":110

"weight":80.0

}

Or:

{

"seqNo":1,

"weight":80.0

}

3.2.1.1 Shipment Parcel Size (ShipmentParcelSize)

Shipment parcel size structure defines parcel size in the shipment.

ShipmentParcelSize
Name	Type	Required	Data	Constraints
width	int	Yes	Parcel width
depth	int	Yes	Parcel depth
height	int	Yes	Parcel height

Example JSON:

{

"width":80,

"depth":120,

"height":100

}

3.2.1.2 External carrier parcel number (ExternalCarrierParcelNumber)

Parcel number from external carrier linked to local shipment parcel

ExternalCarrierParcelNumber
Name	Type	Required	Data	Constraints
externalCarrier	enum [“ACS”]	Yes	External carrier reference name
parcelNumber	String	Yes	External carrier parcel number

3.3 Shipment Payment (ShipmentPayment)

Shipment payment structure defines who-pays-what in the shipment.

ShipmentPayment
Name	Type	Required	Data	Constraints
courierServicePayer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	Yes	Courier service payer.	Validated against the service, destination, contracts and annexes.
declaredValuePayer	enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ]	No	Declared value (extended liability) payer. If not provided, the courier service payer is assumed.	Validated against the service, destination, contracts and annexes.
packagePayer	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	Long	No	Defines shipment third party - used as a payer of any of shipment payable components.	Third party customer should be a registered customer with valid contract and annex for delayed payment at pickup date. The third party customer should be a customer (object) in the same contract as the logged user.
discountCardId	ShipmentDiscountCardId	No	Discount card to be used for discount calculation.	Validated against a referred contract.
senderBankAccount	BankAccount	No	Sender COD payout account information.	Valid IBAN should be present if bank account is provided.
administrativeFee	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

Example JSON:

{

"courierServicePayer":"SENDER",

"declaredValuePayer":"THIRD_PARTY",

"packagePayer":"RECIPIENT",

"thirdPartyClientId":1234567,

"discountCardId":{

"contractId":666666,

"cardId":3

}

Or, if the sender pays everything, then the JSON below is enough:

{

"courierServicePayer":"SENDER"

}

3.3.1 Shipment Discount Card (ShipmentDiscountCardId)

Discount cards provide promotional discounts.

ShipmentDiscountCardId
Name	Type	Required	Data	Constraints
contractId	long	Yes	Fixed discount card contract id.	Validated against the accessible contract.
cardId	long	Yes	Fixed discount card id.	Validated against the fixed discount card register.

Example JSON:

{

"contractId":12345678,

"cardId":3

}

3.3.2 Bank Account (BankAccount)

Bank account information.

BankAccount
Name	Type	Required	Data	Constraints
iban	String	Yes	IBAN.	Validated according to IBAN standards.
accountHolder	String	Yes	Bank account holder.

Example JSON:

{

"iban":"BG80BNBG96611020345678",

"accountHolder":"Todor Penev"

}

3.4 Shipment Sender And Recipient

3.4.1 Shipment Sender (ShipmentSender)

Shipment sender is not mandatory. If not specified, for the sender is considered the logged user.

ShipmentSender
Name	Type	Required	Data	Constraints
clientId	Long	No	Client id to refer a sender.	Validate for existence.
phone1	ShipmentPhoneNumber	Yes	Sender 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	Sender phone number 2.	Validate for valid phone number, if presents.
phone3	ShipmentPhoneNumber	No	Sender phone number 3.	Validate for valid phone number, if presents.
clientName	String	If clientId is provided, it is forbidden. Otherwise, it is mandatory.	Sender customer name.	Validate for valid name (minimum 3 symbols, maximum 60).
contactName	String	No Forbidden for private persons. Required for companies.	Sender contact name.	Maximum 60
email	String	No	Sender email.	Maximum 255
privatePerson	Boolean	If clientId is provided, it is forbidden. Otherwise, it is mandatory.	Sender private person flag.
address	ShipmentAddress	If clientId is provided or dropoff office is provided, it is forbidden. Otherwise, it is mandatory.	Sender address.	Validated for valid values.
dropoffOfficeId	Integer	Required, if the sender is an internal customer. If the address is provided, it is forbidden.	Drop off office id.	Should refer to a valid accessible office.
dropoffGeoPUDOId	String	No. Must be empty if dropoffOfficeId is provided	DPD drop off office PUDO id	Should refer to a valid accessible DPD office.

Example JSON:

{

"clientId":90909090909,

"phone1":{

"number":"08888123123"

"phone2":{

"number":"08888123153",

"extension":"321"

"clientName":"CLIENT NAME",

"objectName":"OBJECT NAME",

"contactName":"CONTACT NAME",

"email":"[email protected]",

"privatePerson":false,

"address":{

"countryId":100,

"siteId":68314,

"streetType":"bul.",

"streetName":"VITOSKA",

"streetNo":"55"

}

Or:

{

"clientId":90909090909,

"phone1":{

"number":"08888123123"

"contactName":"CONTACT NAME",

"email":"[email protected]"

}

3.4.2 Shipment Recipient (ShipmentRecipient)

ShipmentRecipient
Name	Type	Required	Data	Constraints
clientId	Long	No	Client id to refer recipient.	Validate for existence.
phone1	ShipmentPhoneNumber	Required, if shipment is with the same day delivery or delivery date is a half-working day or delivery country is abroad.	Recipient 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	Recipient phone number 2.	Validate for valid phone number, if presents.
phone3	ShipmentPhoneNumber	No	Recipient phone number 3.	Validate for valid phone number, if presents.
clientName	String	If clientId is provided, it is forbidden. Otherwise, it is mandatory.	Recipient customer name.	Validate for valid name (minmum 3 simbols, maximum 60).
objectName	String	If clientId is provided, it is forbidden. Otherwise, it is not mandatory.	Recipient customer object.	Validate for valid name (maximum 60 symbols).
contactName	String	No. Forbidden for private persons. Required for companies.	Recipient contact name.	Maximum 60
email	String	No	Recipient email	Maximum 255. Mandatory for international shipments
privatePerson	Boolean	If clientId is provided, it is forbidden. Otherwise, it is mandatory.	Recipient private person flag.
address	ShipmentAddress	If clientId is provided or pickup office is provided, it is forbidden. Otherwise, it is mandatory.	Recipient address.	Validated for valid values.
pickupOfficeId	Integer	Required, if the recipient is an internal customer. If address is provided, it is forbidden.	Pickup office id.	Should refer to a valid accessible office.
pickupGeoPUDOId	String	No. Must be empty if pickupOfficeId is provided	DPD pickup office PUDO id	Should refer to a valid accessible DPD office.
autoSelectNearestOffice	boolean	No	Not supported for every destination country	Must be supported for destination country
autoSelectNearestOfficePolicy	AutoSelectNearestOfficePolicy	No	Defines policy for nearest office auto selection. By default the system tries to find nearest office and if office cannot be determined the shipment is delivered to client address	Applicable if autoSelectNearestOffice is true

Example JSON:

{

"phone1":{

"number":"0888813323"

"clientName":"RCPT NAME",

"objectName":"RCPT OBJ NAME",

"contactName":"RCPT CONTACT NAME",

"email":"[email protected]",

"privatePerson":true,

"pickupOfficeId":33

}

Or:

{

"clientId":90909090909,

"phone1":{

"number":"0888813323"

"contactName":"RCPT CONTACT NAME",

"pickupOfficeId":33

}

3.4.3 Shipment Address (ShipmentAddress)

This structure is used to provide addresses. Addresses are two types:

Address type 1 (local addresses - currently supported by Romania and Bulgaria)
Address type 2 (foreign addresses - all non-local countries)

Address type 1 supports the following requisites:

countryId
siteId
siteType
siteName
postCode
complexId
complexType
complexName
streetId
streetType
streetName
streetNo
blockNo
entranceNo
floorNo
apartmentNo
poiId
addressNote
x
y

Address type 2 supports the following requisites:

countryId
stateId
siteId
siteName
postCode
addressLine1
addressLine2
x
y

ShipmentAddress
Name	Type	Required	Data	Constraints
countryId	Integer	No	Country ISO code. If not provided, local country is assumed. Used for all address types.	Validate for valid country code.
stateId	String	Required, if country supports states.	Country state. Used for addresses of type 2 (foreign address).	Validate for valid country state.
siteId	Long	Required, if country has full site nomenclature and pair (siteType, siteName) is not provided.	Site id. Used for all address types.	Validate for valid site and value is required.
siteType	String	Forbidden, if siteId is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with countryId and siteName to find unique site. Used for addresses of type 1 (local address).	Max 20
siteName	String	Forbidden, if siteId is provided. Otherwise, is not mandatory.	Site type can be used in conjunction with countryId and siteName to find unique site. Used for all address types.	Max 50
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
streetId	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).	Validate for valid street.
streetType	String	No. Forbidden, if streetId is provided.	Street type. Used for addresses of type 1 (local address).	Max 15
streetName	String	No. Forbidden, if streetId is provided.	Street name. Used for addresses of type 1 (local address).	Max 50
streetNo	String	No	Street number. Used for addresses of type 1 (local address).	Max 10
complexId	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).	Validate for valid complex.
complexType	String	No. Forbidden, if complexId is provided.	Complex type. Used for addresses of type 1 (local address).	Max 15
complexName	String	No. Forbidden, if complexId is provided.	Complex name. Used for addresses of type 1 (local address).	Max 50
blockNo	String	No	Block No. Used for addresses of type 1 (local address).	Max 32
entranceNo	String	No	Entrance. Used for addresses of type 1 (local address).	Max 10
floorNo	String	No	Floor. Used for addresses of type 1 (local address).	Max 10
apartmentNo	String	No	Apartment. Used for addresses of type 1 (local address).	Max 10
poiId	Long	No	Point of interest identifier. Used for addresses of type 1 (local address).	Validate for valid point of interest.
addressNote	String	No	Address note. Used for addresses of type 1 (local address).	200
addressLine1	String	Required for address type 2.	Address line 1. Used for addresses of type 2 (foreign address).	Max 35
addressLine2	String	No	Address line 2. Used for addresses of type 2 (foreign address).	Max 35
x	Double	No	GIS coordinates - X. Used for all address types.
y	Double	No	GIS coordinates - Y. Used for all address types.

For address type 1, special validation rule is applied:

not empty street (ID or Type&Name) and (streetNo or blockNo) or
not empty complex (ID or Type&Name) and (streetNo or blockNo) or
not empty poiId or
all components of the address within the site stored in addressNote

Example JSON address:

{

"countryId":100,

"siteId":68314,

"streetType":"bul.",

"streetName":"VITOSHA",

"streetNo":"55"

}

3.4.3.1 Address (Address)

This structure extends Shipment Address structure with additional fields for address represntation.

This structure is returned in responses.

Address
Name	Type	Required	Data	Constraints
ShipmentAddress fields are here
fullAddressString	String	Yes	Full address in a single text field
siteAddressString	String	Yes	The address site description in a single text
localAddressString	String	Yes	The address within the site in a single text

3.4.4 Shipment Phone Number (ShipmentPhoneNumber)

This structure is used to provide phone numbers.

ShipmentPhoneNumber
Name	Type	Required	Data	Constraints
number	String	Yes	Phone number.	Validate for valid phone number.
extension	String	No	Extension.	Validate for valid extension, if presents.

Example JSON:

{

"number":"0888813323",

"extension":"123"

}

Or just:

{

"number":"0888813323"

}

3.4.5 Auto-select Nearest Office Policy (AutoSelectNearestOfficePolicy)

This structure is used to define policy for nearest office auto selection. By default the system tries to find nearest office and if office cannot be determined the shipment is delivered to client address

AutoSelectNearestOfficePolicy
Name	Type	Required	Data	Constraints
unavailableNearestOfficeAction	enum [“DELIVERY_TO_ADDRESS”, “CANCEL_WITH_ERROR”]	No Default is “DELIVERY_TO_ADDRESS”	The action to take if nearest office is unavailable. Values can be: “DELIVERY_TO_ADDRESS” - do not change recipient location and deliver to client address “CANCEL_WITH_ERROR” - cancel shipment and return error in response
officeType	enum [“OFFICE”, “APT”]	No	Office type filter. Values can be: “OFFICE” - select nearest office “APT” - select nearest locker (APT) No office filter selection is applied if value is not specified	Not supported for every destination country

3.5 Shipment Parcels

Shipment parcel reference is returned in response of the create shipment request, it describes the generated parcel and references to it.

3.5.1 Created Shipment Parcel (CreatedShipmentParcel)

CreatedShipmentParcel
Name	Type	Mandatory	Data
seqNo	int	Yes	Sequence number within the shipment.
id	String	Yes	Generated parcel id.
externalCarrierId	Integer	No	External carrier id in case this parcel is mapped to an external carrier system
externalCarrierParcelNumber	String	No	External carrier parcel number in case this parcel is mapped to an external carrier system

Example JSON:

{

"id":"80002188603",

"seqNo":1

}

3.5.2 Shipment Parcel Reference (ShipmentParcelRef)

ShipmentParcelRef
Name	Type	Mandatory	Data	Constraint
id	String	No If externalCarrierParcelNumber is not provided, it is mandatory.	Parcel id
externalCarrierParcelNumber	String	No	External carrier parcel number used to create parcels.
fullBarcode	String	No	No If id or externalCarrierParcelNumber is not provided, it is mandatory.

Example JSON:

{

"id":"80002188603"

}

Or:

{

"externalCarrierParcelNumber":"7125912312312312313"

}

Or:

{

"fullBarcode":"1000509431237540020002030017"

}

3.5.3 Parcel Handover (ParcelHandover)

This structure extends ShipmentParcelRef structure with additional fields.

ParcelHandover
Name	Type	Mandatory	Data	Constraint
dateTime	DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ)	Yes	Datetime for hadover operation
ShipmentParcelRef fields are here

3.5.4 Track Shipment Parcel Reference (TrackShipmentParcelRef)

TrackShipmentParcelRef
Name	Type	Mandatory	Data	Constraint
ref	String	No	Reference to parcel or shipment. The reference is searched in ref1 and ref2 fields in parcels or in ref1 and ref2 fields in shipment. A parcel is included in tracking if reference is found in parcel references. Otherwise, only first shipment parcel (this one with the same number as shipment id) is included in tracking in case reference is found in shipment references.	If externalCarrierParcelNumber or parcelId is provided, it is ignored. Since the reference is not unique, the maximum barcodes to include for tracking is limited to 10 per reference in request.
ShipmentParcelRef fields are here

3.5.5 Midway Carrier Parcel Handover (MidwayCarrierParcelHandover)

MidwayCarrierParcelHandover
Name	Type	Mandatory	Data	Constraint
id	String	Yes	Parcel id
countryId	Long	Yes	Country ISO id
dateTime	DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ)	Yes	Datetime for hadover operation
siteName	String	No	Site name

3.6 Shipment Price (ShipmentPrice)

Shipment price structure is returned in response of the calculations or create shipment requests.

ShipmentPrice
Name	Type	Mandatory	Data
amount	double	Yes	Total amount (before VAT) in customer’s currency.
vat	double	Yes	VAT amount in customer’s currency.
total	double	Yes	Total amount (amount + vat) in customer’s currency.
currency	String	Yes	Customer currency code.
details	Map<String, ShipmentPriceAmount>	Yes	Amounts that form totals in customer’s currency (including net, discounts, surcharges). Keys in the map are the titles of the items included in the receipt.
amountLocal	double	Yes	Total amount before VAT in local system currency.
vatLocal	double	Yes	VAT in local system currency.
totalLocal	double	Yes	Total amount in local system currency (amountLocal + vatLocal).
currencyLocal	String	Yes	Local system currency code.
detailsLocal	Map<String, ShipmentPriceAmount>	Yes	Amounts that form totals in local system currency (including net, discounts, surcharges). Keys in the map are the titles of the items included in the receipt.
currencyExchangeRateUnit	int	Yes	Currency exchange rate unit for customer currency (1 unit of local system currency is equal to exchangeRateUnit / exchangeRate).
currencyExchangeRate	double	Yes	Currency exchange rate used for customer currency conversion.
returnAmounts	ReturnAmounts	No	Shipment returns amounts due

Example JSON:

{

"amount":37.81,

"vat":7.18,

"total":44.99,

"currency":"RON",

"receipt":{

"netAmount":{

"amount":37.81,

"vatPercent":19.0

"fixedDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"dropoffDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"pickupDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"additionalDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"fuelSurcharge":{

"amount":0.0,

"percent":0.0,

"vatPercent":19.0

"zoneSurcharge":{

"amount":0.0,

"vatPercent":19.0

"codCommission":{

"amount":0.0,

"vatPercent":19.0

"declaredValueSurcharge":{

"amount":0.0,

"vatPercent":19.0

}

"amountLocal":37.81,

"vatLocal":7.18,

"totalLocal":44.99,

"currencyLocal":"RON",

"receiptLocal":{

"netAmount":{

"amount":37.81,

"vatPercent":19.0

"fixedDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"dropoffDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"pickupDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"additionalDiscount":{

"amount":-0.0,

"percent":0.0,

"vatPercent":19.0

"fuelSurcharge":{

"amount":0.0,

"percent":0.0,

"vatPercent":19.0

"zoneSurcharge":{

"amount":0.0,

"vatPercent":19.0

"codCommission":{

"amount":0.0,

"vatPercent":19.0

"declaredValueSurcharge":{

"amount":0.0,

"vatPercent":19.0

}

"currencyExchangeRateUnit":1,

"currencyExchangeRate":1.0

}

3.6.1 Shipment Price Amount (ShipmentPriceAmount)

Shipment price amount is returned as a part of receipts in calculation responses.

ShipmentPriceAmount
Name	Type	Mandatory	Data
amount	double	Yes	Shipment price amount. Discounts are negative. Surcharges and net amount are positive.
percent	Double	No	Percent field is returned, if there is a percent associated with the amount. Fixed price amounts do not have a percent value. 20% is returned as 0.2.
vatPercent	double	Yes	VAT percent applicable to the amount. Amounts without VAT have 0.0 value in that field. Amounts with 20% VAT have 0.2 value in that field.

Example JSON:

{

"amount":13.45,

"percent":0.4,

"vatPercent":0.19

}

Or for fixed amount:

{

"amount":12.00,

"vatPercent":0.20

}

3.6.2 Return Amounts (ReturnAmounts)

Shipment price return amounts represents return services due amounts.

ReturnAmounts
Name	Type	Mandatory	Data
moneyTransfer	MoneyTransferPremium	No	Shipment money transfer premium.

3.6.2.1 Money Transfer Premium (MoneyTransferPremium)

Money transfer premium amount due.

MoneyTransferPremium
Name	Type	Mandatory	Data
amount	Double	No	Amount due in client currency
amountLocal	Double	No	Amount due in local currency
payer	enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”]	No	The payer of money transfer premium

3.7 Errors (Error)

Errors are returned in responses.

Error
Name	Type	Mandatory	Data
context	String	No	Message context, if associated. This refers to an item that is wrong and should be corrected.
message	String	Yes	Error message in language specified in the request.
id	String	Yes	System generated unique error id to be used as this error reference.
code	int	Yes	Error code. See Appendix 3 - Error Codes for more details.
component	String	No	The request component, if applicable, relevant to this error in JSONPath format with dot notation. (For example $.sender.address.siteId refers to siteId property in sender address.)

Example JSON:

{

"context":”sender.address.siteId”,

"message":”Value is required”

}

3.8 Parcel to Print (ParcelToPrint)

ParcelToPrint
Name	Type	Mandatory	Data	Constraints
parcel	ShipmentParcelRef	Yes	Parcel reference.
additionalBarcode	ParcelToPrintAdditionalBarcode	No	Additional barcode to be added in the label.	Available for A6 paper size only. Otherwise, ignored.

Example JSON:

{

"parcel": {

"Id":"80002188603"

"additionalBarcode": {

"value":"123456789104",

"label":"123456789104",

"format":"CODE128"

}

Or just:

{

"parcel": {

"Id":"80002188603"

}

3.8.1 Parcel to Print Additional Barcode (ParcelToPrintAdditionalBarcode)

Additional barcode information to print in the label is provided in this structure.

ParcelToPrintAdditionalBarcode
Name	Type	Mandatory	Data	Constraints
value	String	.Yes	Barcode value.	For barcode formats other than 'CODE128' it must contain digits only.
label	String	No	It is printed just below the barcode image.	For barcode formats other than 'CODE128' label must be equal to the value.
format	enum [“CODE128”, “EAN13”, “EAN8”, “UPCA”, “UPCE”]	Yes	Additional barcode format.

Example JSON:

{

"value":"123456789104",

"label":"123456789104",

"format":"CODE128"

}

3.8.2 Label Info (LabelInfo)

Print label information.

LabelInfo
Name	Type	Mandatory	Data	Constraints
parcelId	String	Yes	Parcel id.
hubId	Integer	No	Delivery Hub id.
officeId	Integer	No	Delivery Office id.
officeName	String	No	Delivery Office name.
deadlineDay	Integer	No	Delivery deadline day of month.
deadlineMonth	Integer	No	Delivery deadline month .
tourId	Integer	No	Tour Id.
fullBarcode	String	Yes	Barcode containing the parcel number and important routing information.
exportPriority	Integer	Yes	Export priority

Example JSON:

{

"parcelId": "50943123754",

"hubId": 2,

"officeId": 2,

"deadlineDay": 18,

"deadlineMonth": 2,

"tourId": 2203,

"fullBarcode": "1000509431237540020002030017"

}

3.9 TrackedParcel (TrackedParcel)

Track parcel information.

TrackedParcel
Name	Type	Mandatory	Data	Constraints
parcelId	String	Yes	Parcel id.
externalCarrierParcelNumbers	String[]	No	The list of all external carrier parcel numbers associated with the parcel.
operations	TrackedParcelOperation[]	Yes	The list of operations (scans).
externalCarrierParcelNumbersDetails	Map<String, ExternalCarrierParcelNumberDetails>	No	Map of external carrier parcel details. Keys in the map are external carrier parcel numbers.
error	Error	No	Error for this parcel.

3.9.1 Tracked Parcel Operation (TrackedParcelOperation)

TrackedParcelOperation
Name	Type	Mandatory	Data	Constraints
dateTime	Date (datetime)	Yes	Operation date time.
operationCode	int	Yes	Operation code. See Appendix1 for reference.
place	String	No	Place of operation.
description	String	Yes	Operation description.
comment	String	No	Operation comment.
exceptionCodes	String[]	No	List of exception codes for this operation. See Appendix2 for references.
returnShipmentId	String	No	If operation leads to return - the return shipment id is in this field.
redirectShipmentId	String	No	If operation leads to redirect - the redirected shipment id is in this field.
consignee	String	No	If operation leads to delivery - the recipient name is in this field.
podImageURL	String	No	If operation leads to pod capture - the pod image URL is in this field.
additionalInfo	TrackedParcelOperationAdditionalInfo	No	Additional information for operation

3.9.1.1 Tracked Parcel Operation Additional Info(TrackedParcelOperationAdditionalInfo)

TrackedParcelOperationAdditionalInfo
Name	Type	Mandatory	Data	Constraints
officeURL	String	No	Pickup office URL (applicable for operation 134)
geoPUDOId	String	No	Pickup office PUDO id in case pickup office is a DPD office (applicable for operation 134)
predict	TrackedParcelOperationAdditionalInfoPredict	For operation with code 175 (Predict)	Predict details

3.9.1.1.1 Tracked Parcel Predict Operation Additional Info(TrackedParcelOperationAdditionalInfoPredict)

TrackedParcelOperationAdditionalInfoPredict
Name	Type	Mandatory	Data	Constraints
predictedVisitDateTimeFrom	Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ)	Yes	Start of expected time window for delivery
predictedVisitDateTimeTo	Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ)	Yes	End of expected time window for delivery
includedDelayInMinutes	Integer	No	Expected delivery time delay in minutes (if any). The expected time window for delivery is adjusted with this delay
canceled	boolean	Yes	The value is true in case the predict is cancelled

3.9.2 External Carrier Parcel Number Details(ExternalCarrierParcelNumberDetails)

ExternalCarrierParcelNumberDetails
Name	Type	Mandatory	Data	Constraints
externalCarrierId	int	Yes	Id of the external carrier
externalCarrierName	String	Yes	Name of the external carrier
trackAndTraceUrl	String	No	Track and trace URL of the external carrier

3.10 Pickup order (PickupOrder)

Pickup order data.

PickupOrder
Name	Type	Mandatory	Data	Constraints
id	long	Yes	Order id.
shipmentIds	String[]	Yes	The list of all shipments associated with the order.
pickupPeriodFrom	Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ)	No	Estimated period start for courier pickup visit
pickupPeriodTo	Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ)	No	Estimated period end for courier pickup visit

3.11 Country

Country data

Country
Name	Type	Data
id	integer	Country ISO
name	String	Country name in requested language
nameEn	String	Country name in English
isoAlpha2	String	Country ISO alpha 2 code
isoAlpha3	String	Country ISO alpha 3 code
postCodeFormats	String[]	Allowed postcode format patterns. If empty string presents in allowed patterns this means - postcode format is not restricted and post code validation is not applied on addresses in this country. For non-empty patterns, the following characters are placeholders for: N - digit A - letter ? - digit or letter B - letter O - digit
requireState	String	Require state flag
addressType	integer	Address type for this country (1 or 2 - see ShipmentAddress)
currencyCode	String	Currency code used for COD in this country
defaultOfficeId	Integer	Default office id
streetTypes	AddressNomenclatureType[]	Valid street types for country (applicable if addressType is equal to 1)
complexTypes	AddressNomenclatureType[]	Valid complex types for country (applicable if addressType is equal to 1)
siteNomen	integer	Specifies site nomenclature (sites) for this country. Values can be: 0 - No site nomenclature for this country. 1 - Full site nomenclature for this country. 2 - Partial site nomenclature for this country.

3.11.1 Address Nomenclature Type (AddressNomenclatureType)

Used for address type 1 street types and complex types

AddressNomenclatureType
Name	Type	Data
name	String	Address nomenclature type name in requested language
nameEn	String	Address nomenclature type name in English

3.12 State

State data

State
Name	Type	Data
id	String	State id
name	String	State name in requested language
nameEn	String	State name in English
stateAlpha	String	State ISO alpha code
countryId	integer	State country id

3.13 Site

Site data

Site
Name	Type	Data
id	long	Site id
countryId	integer	Site country id
mainSiteId	Long	Here we have reference to main site if this site is a "satellite" one. A satellite site is considered equal (to their main site) in context of "same city" service allowance
type	String	Site type in requested language
typeEn	String	Site type in English
name	String	Site name in requested language
nameEn	String	Site name in English
municipality	String	Municipality name in requested language
municipalityEn	String	Municipality name in English
region	String	Region name in requested language
regionEn	String	Region name in English
postCode	String	Default post code for this site (if any)
addressNomenclature	integer	Code for address nomenclature (streets, complexes, blocks, poi) support. 0 - no address nomenclature 1 - full address nomenclature 2 - partial address nomenclature
x	Double	Site center GPS X (longitude) coordinate
y	Double	Site center GPS Y (latitude) coordinate
servingDays	String	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 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	Integer	Site's serving office
servingHubOfficeId	Integer	The hub office ID to which serving office is connected

3.14 Street

Street data

Street
Name	Type	Data
id	long	Street id
siteId	long	Street site id
type	String	Street type in requested language
typeEn	String	Street type in English
name	String	Street name in requested language
nameEn	String	Street name in English
actualId	Long	Actual street id (if this street is old and renamed)
actualType	String	Actual street type in requested language (if this street is old and renamed)
actualTypeEn	String	Actual street type in English (if this street is old and renamed)
actualName	String	Actual street name in local language
actualNameEn	String	Actual street name in English

3.15 Complex

Complex data

Complex
Name	Type	Data
id	long	Complex id
siteId	long	Complex site id
type	String	Complex type in requested language
typeEn	String	Complex type in English
name	String	Complex name in requested language
nameEn	String	Complex name in English
actualId	Long	Actual complex id (if this complex is old and renamed)
actualType	String	Actual complex type in requested language (if this complex is old and renamed)
actualTypeEn	String	Actual complex type in English (if this complex is old and renamed)
actualName	String	Actual complex name in requested language (if this complex is old and renamed)
actualNameEn	String	Actual complex name in English (if this complex is old and renamed)

3.16 Block

Block data

Block
Name	Type	Data
siteId	long	Block site id
name	String	Block name in requested language
nameEn	String	Block name in English

3.17 Point of interest (PointOfInterest)

Point of interest data

PointOfInterest
Name	Type	Data
id	long	POI id
siteId	long	POI site id
name	String	POI name in requested language
nameEn	String	POI name in English
type	String	POI type in requested language
typeEn	String	POI type in English
address	String	POI address in requested language
addressEn	String	POI address in English
x	Double	POI GPS X (longitude) coordinate
y	Double	POI GPS Y (latitude) coordinate

3.18 Office (Office)

Office data

Office
Name	Type	Data
id	Integer	Office id
name	String	Office name in requested language
nameEn	String	Office name in English
siteId	long	Office site id
address	Address	Office address in requested language
workingTimeFrom	String ("HH:mm")	Office work time start for days with standard (FULL) working schedule
workingTimeTo	String ("HH:mm")	Office work time end for days with standard (FULL) working schedule
workingTimeHalfFrom	String ("HH:mm")	Office work time start for days with saturday (HALF) working schedule
workingTimeHalfTo	String ("HH:mm")	Office work time end for days with saturday (HALF) working schedule
workingTimeDayOffFrom	String ("HH:mm")	Office work time start for non-working days (DAY OFF)
workingTimeDayOffTo	String ("HH:mm")	Office work time end for non-working days (DAY OFF)
sameDayDepartureCutoff	String ("HH:mm")	Office same day departure cutoff for days with standard (FULL) working schedule (departure of parcels delivered to office after the cutoff time is next working day)
sameDayDepartureCutoffHalf	String ("HH:mm")	Office same day departure cutoff for days with saturday (HALF) working schedule (departure of parcels delivered to office after the cutoff time is next working day)
sameDayDepartureCutoffDayOff	String ("HH:mm")	Office same day departure cutoff for non-working days (DAY OFF) working schedule (departure of parcels delivered to office after the cutoff time is next working day)
maxParcelDimensions	ShipmentParcelSize	Max parcels dimensions for this office
maxParcelWeight	double	Max parcel weight
type	enum ["OFFICE", "APT"]	Office type
nearbyOfficeId	Integer	Nearby office id
workingTimeSchedule	OfficeWorkingTimeSchedule[]	Office work time schedule for next days
palletOffice	boolean	Pallet office flag
cardPaymentAllowed	boolean	Flag, indicating this office allows card payments
cashPaymentAllowed	boolean	Flag, indicating this office allows cash payments
validFrom	Date (yyyy-MM-dd)	Valid from date
validTo	Date (yyyy-MM-dd)	Valid to date
cargoTypesAllowed	enum[] (array with values from enum: [“PARCEL”, “PALLET”, “TYRE”]) (Same as enum in field cargoType in CourierService)	Allowed cargo types
pickUpAllowed	boolean	Flag, indicating whether parcels can be picked up from office
dropOffAllowed	boolean	Flag, indicating whether parcels can be dropped-off in office

3.18.1 Office Working Time Schedule (OfficeWorkingTimeSchedule)

OfficeWorkingTimeSchedule
Name	Type	Data
date	Date (format: ""yyyy-MM-dd"")	Date this schedule is applicable for
workingTimeFrom	String ("HH:mm")	Office working time start for this date
workingTimeTo	String ("HH:mm")	Office working time end for this date
sameDayDepartureCutoff	String ("HH:mm")	Office same day departure cutoff for this day (departure of parcels delivered to office after the cutoff time is next working day)
standardSchedule	boolean	If true - it is from standard schedule, otherwise office working time is overridden for this specific day

3.19 Calculation Service

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

Calculation Service
Name	Type	Required	Data	Constraints
pickupDate	Date (Example: 2017-11-12)	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
serviceIds	integer[]	Yes	Services for which calculation is requested	Each 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 JSON:

{

"pickupDate":"2018-01-31",

"serviceIds":[2113, 2002],

"autoAdjustPickupDate":true,

"additionalServices":{

"cod":{

"amount":100.00

"currencyCode":"RON"

"declaredValue":{

"amount":100.00

"fragile":false

"fixedTimeDelivery":1130,

"deferredDays":2,

"saturdayDelivery":true

}

3.20 Calculation Sender

Calculation sender is not mandatory. If not specified logged user is the sender.

Calculation Sender
Name	Type	Required	Data	Constraints
clientId	Long	No	Client id to refer serving client	Validate for existence.
privatePerson	Boolean	If clientId is provided, it is forbidden. Otherwise, it is mandatory.	Private person flag.
addressLocation	AddressLocation	Required if office id and clientId are missing. Otherwise it is forbidden	Address location, implies pickup at client address
dropoffOfficeId	Integer	Required if address location and clientId are missing. If address location presents it is forbidden	Drop-off office id	Validated for valid office.
dropoffGeoPUDOId	String	No. Must be empty if dropoffOfficeId is provided	DPD drop off office PUDO id	Should refer to a valid accessible DPD office.

Example JSON:

{

"addressLocation":{

"countryId": 100

"siteId":68314

}

or:

{

"dropoffOfficeId": 2

}

3.21 Calculation Recipient

Calculation Recipient
Name	Type	Required	Data	Constraints
clientId	Long	No	Client id to refer serving client	Validate for existence.
privatePerson	Boolean	If clientId is provided, it is forbidden. Otherwise, it is mandatory.	Private person flag.
addressLocation	AddressLocation	Required if office id and clientId are missing. Otherwise it is forbidden	Address location, implies delivery at client address
pickupOfficeId	Integer	Required if address location and clientId are missing. If address location presents it is forbidden	Pickup office id	Validated for valid office.
pickupGeoPUDOId	String	No. Must be empty if pickupOfficeId is provided	DPD pickup office PUDO id	Should refer to a valid accessible DPD office.

3.22 Calculation Address Location

Calculation Address Location
Name	Type	Required	Data	Constraints
countryId	Integer	No	Country ISO code. If not provided, local country is assumed. Used for all address types.	Validated for valid country code.
stateId	String	Required, if country supports states	Country state. Used for addresses of type 2 (foreign address).	Validated for valid country state.
siteId	Long	Required, if country has full site nomenclature and pair (siteType, siteName) is not provided.	Site id. Used for all address types.	Validated for valid site
siteType	String	Forbidden, if siteId is provided. Otherwise, is not mandatory	Site type can be used in conjunction with countryId and siteName to find unique site. Used for addresses of type 1 (local address).	Max 20 characters
siteName	String	Forbidden, if siteId is provided. Otherwise, is not mandatory	Site type can be used in conjunction with countryId and siteName to find unique site. Used for all address types.	Max 50 characters
postCode	String	Required if country requires postcode for addresses	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 characters

3.23 Calculation Content

Calculation content is used to describe what is to be delivered with the shipment for calculation purposes.

Calculation Content
Name	Type	Required	Data	Constraints
parcelsCount	Integer	Required when parcels list is empty	Total shipment parcels count. Ignored, if parcels list is not empty.	Validated against the minimum and maximum allowed for the service.
totalWeight	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 parcels declaredWeight in that case.	Validated against the minimum and maximum allowed for the service.
documents	Boolean	No	Documents flag of the shipment
palletized	Boolean	No	Palletized flag of the shipment.
parcels	ShipmentParcel[]	Required for pallet and postal services.	List of parcels	Validated against the service configuration and pickup and delivery capacity of the depots and couriers.

3.24 Calculation Result

Calculation Result
Name	Type	Data
serviceId	integer	Service id
additionalServices	ShipmentAdditionalServices	Additional services included in calculation
price	ShipmentPrice	Returned, if customer has access to view the amounts of the shipment.
pickupDate	Date	Pickup date.
deliveryDeadline	DateTime	Deadline for delivery. Returned, if available
error	Error	Response error.

3.25 Client

Client
Name	Type	Data
clientId	Long	Client id
clientName	String	Client name
objectName	String	Object name
contactName	String	Contact name
address	Address	Client address
email	String	Client email
privatePerson	Boolean	Private person flag.

3.26 Shipment

Shipment
Name	Type	Data
id	String	Shipment id
sender	Sender	Shipment sender.
recipient	Recipient	Shipment recipient.
service	ShipmentService	Shipment service level agreement.
content	Content	Shipment content.
payment	Payment	Shipment payment.
shipmentNote	String	Customer’s note associated with the shipment.
ref1	String	Reference number or text.
ref2	String	Reference number or text.
price	ShipmentPrice	Shipment payment.
delivery	ShipmentDelivery	Shipment delivery.
primaryShipment	PrimaryShipment	Primary shipment.
returnShipmentId	String	Return shipment id (in case this shipment is returned to sender)
redirectShipmentId	String	Redirect shipment id (in case this shipment is redirected to new delivery location)
pendingShipment	Boolean	If this flag is true, the shipment is created in pending shipment state. Shipments in pending shipment state can have incomplete data that defines logisitics (without complete addresses, only sites) Pending shipment state is closed with updateShipment method that makes shipments complete.

3.26.1 Sender (Sender)

This structure extends Client structure with additional fields.

Sender
Name	Type	Data
Client fields are here
dropoffOfficeId	Integer	Drop-off office id
dropoffGeoPUDOId	String	DPD PUDO Id

3.26.2 Recipient (Recipient)

This structure extends Client structure with additional fields.

Recipient
Name	Type	Data
Client fields are here
pickupOfficeId	Integer	Pickup office id
pickupGeoPUDOId	String	DPD PUDO Id

3.26.3 Content (Content)

Content
Name	Type	Data
parcelsCount	Integer	Total shipment parcels count.
declaredWeight	Double	Shipment declared weight
measuredWeight	Double	Shipment measrued weight
calculationWeight	Double	Shipment calculation weight
contents	String	Shipment content’s description.
package	String	Shipment package.
documents	Boolean	Documents flag of the shipment (shipment content is documents)
palletized	Boolean	Palletized flag of the shipment.
parcels	Parcel[]	Shipment parcels
pendingParcels	Boolean	If this flag is true, the shipment is created in pending parcels state. Shipments in pending parcels state allows adding parcels with addParcel method. Pending parcels state is closed with finalizePendingShipment method.

3.26.3.1 Parcel (Parcel)

Shipment parcel details

Parcel
Name	Type	Data
id	String	Parcel id
seqNo	Integer	Parcel sequence nomber within the shipment
packageUniqueNumber	Long	Package number associated with parcel.
declaredSize	ShipmentParcelSize	Parcel declared size
measuredSize	ShipmentParcelSize	Parcel measured size
calculationSize	ShipmentParcelSize	Parcel calculation size
declaredWeight	Double	Parcel declared weight
measuredWeight	Double	Parcel measured weight
calculationWeight	Double	Parcel calculation weight
externalCarrierParcelNumbers	String[]	External carrier parcel numbers associated with this parcel
baseType	String	Base type name
size	String	Size name

3.26.4 Payment (Payment)

Payment
Name	Type	Data
courierServicePayer	enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”]	Courier service payer.
declaredValuePayer	enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”]	Declared value payer
packagePayer	enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”]	Package payer
thirdPartyClientId	Long	Third party payer client id in case one of the payers is THIRD_PARTY
discountCardId	ShipmentDiscountCardId	Discount card used in calculation.
codPayment	CODPayment	COD Payment details

3.26.4.1 CODPayment (CODPayment)

COD payment details

CODPayment
Name	Type	Data
date	Datetime (format yyyy-MM-dd'T'HH:mm:ssZ)	Pay out date
totalPayedOutAmount	double	Total paid out COD amount

3.26.5 Shipment Delivery (ShipmentDelivery)

ShipmentDelivery
Name	Type	Data
deadline	Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ)	Deadline for this shipment
deliveryDateTime	Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ)	Datetime of actual delivery (if schipment is delivered)
consignee	String	Shipment consignee (if schipment is delivered)
deliveryNote	String	Shipment delivery note (if schipment is delivered)

3.26.6 PrimaryShipment (PrimaryShipment)

PrimaryShipment
Name	Type	Data
id	String	Primary shipment id
type	enum [“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”]	Primary shipment type - how this secondary shipment is realted to primary one RETURN_SHIPMENT - if this shipment is one of return of documents (rod) / returnReceipt / swap / return of pallets (rop) for a primary one STORAGE_PAYMENT - if this shipment is for warehouse charges for a primary one REDIRECT - if this shipment redirects primary one SEND_BACK - if this shipment returns primary one to sender MONEY_TRANSFER - if this shipment is a money transfer for a primary one TRANSPORT_DAMAGED - if this shipment is for damaged primary shipment transport VOUCHER_RETURN - if this shipment is a voucher return for a primary one

3.26.7 Secondary Shipment(SecondaryShipment)

SecondaryShipment
Name	Type	Data
id	String	Secondary shipment id
type	enum [“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”] (Same as enum in field type in PrimaryShipment)	Primary shipment type - how this secondary shipment is realted to primary one RETURN_SHIPMENT - if this shipment is one of return of documents (rod) / returnReceipt / swap / return of pallets (rop) for a primary one STORAGE_PAYMENT - if this shipment is for warehouse charges for a primary one REDIRECT - if this shipment redirects primary one SEND_BACK - if this shipment returns primary one to sender MONEY_TRANSFER - if this shipment is a money transfer for a primary one TRANSPORT_DAMAGED - if this shipment is for damaged primary shipment transport VOUCHER_RETURN - if this shipment is a voucher return for a primary one
parcels	ShipmentParcelNumber[]	Shipment parcels
pickupDate	Date (yyyy-MM-dd)	Secondary shipment pickup date
serviceId	int	Secondary shipment service id
hasScans	boolean	Flag that shows whether the secondary shipment is scanned

3.26.8 Shipment Parcel Number(ShipmentParcelNumber)

ShipmentParcelNumber
Name	Type	Data
id	String	Parcel id
seqNo	int	Parcel sequence number in the shipment.

3.27 Courier Service

CourierService
Name	Type	Data
id	int	Courier service id
name	String	Courier service name in local language
nameEn	String	Courier service name in English
additionalServices	AdditionalCourierServices	Additional services options
cargoType	enum [“PARCEL”, “PALLET”, “TYRE”]	Cargo type
requireParcelWeight	boolean	Require weight for each parcel on create shipment
requireParcelSize	boolean	Require size for each parcel on create shipment

3.27.1 Additional Courier Services

AdditionalCourierServices
Name	Type	Data
cod	AdditionalCourierService	COD configuration
obpd	AdditionalCourierService	Options Before Payment or Delivery configuration
declaredValue	AdditionalCourierService	Declared value configuration
fixedTimeDelivery	AdditionalCourierService	Fixed time configuration
specialDelivery	AdditionalCourierService	Special delivery configuration
deliveryToFloor	AdditionalCourierService	Delivery to floor configuration
rod	AdditionalCourierService	Return of documents configuration
returnReceipt	AdditionalCourierService	Return receipt configuration
swap	AdditionalCourierService	SWAP configuration
rop	AdditionalCourierService	Return of pallets configuration
returnVoucher	AdditionalCourierService	Return voucher configuration

3.27.1.1 Additional Courier Service

AdditionalCourierService

Name

Type

Data

allowance

enum

[“FORBIDDEN”, “ALLOWED”, “REQUIRED”]

Allowance value

Forbidden - this additional service is not allowed for courier service
Allowed - this additional service is allowed for usage for courier service. It could be either used or skipped on create shipment
Required - this additional service is mandatory to be used with courier service on create shipment

3.28 Extended Courier Service

ExtendedCourierService
Name	Type	Data
CourierService fields are here
deadline	Date (yyyy-MM-dd'T'HH:mm:ssZ)	Deadline for delivery

3.29 Bulk Tracking Data File

BulkTrackingDataFile
Name	Type	Data
id	long	File id
url	String	File url

3.30 Payout

Payout
Name	Type	Data
date	Date (yyyy-MM-dd)	Payout date
docId	Long	Payout document id
docType	enum [“CASH”, “POSTAL_MONEY_TRANSFER”]	Payout document type
paymentType	enum [“CASH”, “BANK”]	Payout payment type
payee	String	Payee
currency	String	Payout currency
amount	double	Payout amount
details	PayoutDetails[]	List of payout details

3.30.1 Payout Details

PayoutDetails
Name	Type	Data
lineNo	int	Payout line number
shipmentId	String	Payout shipment id
pickupDate	Date (yyyy-MM-dd)	Date of shipment pickup
primaryShipmentPickupDate	Date (yyyy-MM-dd)	Date of primary shipment pickup in case this shipment is a secondary one
deliveryDate	Date (yyyy-MM-dd)	Shipment delivery date
sender	String	Shipment sender
recipient	String	Shipment recipient
note	String	Shipment note
ref1	String	Shipment ref1 (reference)
ref2	String	Shipment ref2 (reference)
currency	String	Payout currency
order	Long	Order id
amount	Double	Payout amount

3.31 SpecialDeliveryRequirements

SpecialDeliveryRequirements
Name	Type	Data
requiredForAllShipments	boolean	Indicates whether special delivery requirements are mandatory for each shipment
requirements	Requirement[]	List of requirements

3.31.1 Requirement

Requirement
Name	Type	Data
id	int	Special delivery requirement id
text	String	Requirement text

3.32 OfficeResult

This structure extends Office structure with additional fields.

OfficeResult
Name	Type	Data
distance	Integer	Distance from searched location
Office fields are here

3.33 CODAdditionalServiceContractInfo

CODAdditionalServiceContractInfo
Name	Type	Data
moneyTransferAllowed	boolean	COD as money transfer allowed flag
codFiscalReceiptAllowed	boolean	Issuing COD fiscal receipt on behalf of client allowed flag
hasCODAnnex	boolean	Logged client has COD annex flag
internationalCODAnnexes	CODInternationalAnnexContractInfo[]	List of international COD annex contract info

3.33.1 CODInternationalAnnexContractInfo

CODInternationalAnnexContractInfo
Name	Type	Data
countryId	int	International annex country id
countryName	String	International annex country name

4 Appendixes

4.1 Appendix 1 - Track And Trace Operation Codes

Track And Trace Operation Codes
Id	Description
1	Arrival Scan
2	Departure Scan
11	Received in Office
12	Out for Delivery
-14	Delivered
21	Processed in Office
38	Returned to Office
39	Courier Pick-up
44	Unsuccessful Delivery
69	Deferred delivery
111	Return to Sender
112	Processed to the Insurance dept.
114	Processed for Destruction
115	Redirected
116	Forwarded
121	Stopped by Sender
123	Refused by recipient
124	Delivered Back to Sender
125	Destroyed
127	Theft/Burglary
128	Canceled
129	Administrative Closure
134	Prepared for Self-collecting Consignee
144	Handover for contents check/test
148	Shipment data received
164	Unsuccessful shipment pickup
169	Delivery capacity reached (tour/office)
175	Predict
176	Export to foreign provider
181	Unexpected delay
190	Postponed delivery due to inaccurate/incomplete address
195	Refuse contents check/test
217	Handover to midway carrier
1134	Office/Locker ready for pickup message sent

4.2 Appendix 2 - Track And Trace Operation Exception Codes

Exception codes are associated to track and trace operation codes where relevant.

Track And Trace Operation Codes
Id	Description
11	Wrong address
12	Refused by recipient - damaged
14	Refused by recipient - not ordered
15	Refused by recipient
16	Refused by recipient - contents checked, found to be damaged
17	Return (pick-up) after wrong delivery
19	Recipient not present - informed first time
20	Self-collecting recipient
22	Broken in sub-contractor's custody
25	Closed (e.g. department store)
27	Lack of space
29	Shipment incomplete
32	Lack of time
35	Recipient not present, informed, on holiday
37	Recipient not present - third time
41	Force majeure
42	Recipient not present, informed 2nd time
46	Amount not paid
49	Customer's return
61	Delay due to unknown reason
66	ID check failed
67	Signature refused
80	Appointment scheduled
81	Regional holiday
84	Delivery note / order reference missing
1002	Incomplete address
1003	Does not answer the phone
1004	In office - not claimed
1005	Redirected
1006	Refused after content’s check/test
1007	New date scheduled
1008	Without delivery attempt
1020	Consignee not reachable - routed to office
9020	Not in warehouse

4.3 Appendix 3 - Error Codes

Error codes returned in Error structure.

Error Codes
Id	Name	Description
1	General Error	Returned when there is an error in request processing and it doesn't match any of recongizable errors described in this table
100	Invalid client data	Returned when there is invalid client data provided in request. Relevant for Shipment, Calculation and Client service methods
120	Invalid address	Returned when there is an error in address provided in request. Relevant for Shipment, Calculation and Client service methods
160	Invalid drop-off office	Returned when the selected sender drop-off office in request is not valid. Relevant for Shipment and Calculation service methods
180	Invalid pickup office	Returned when the selected recipient pickup office in request is not valid. Relevant for Shipment and Calculation service methods
300	Invalid third party	Returned when the selected third party payer in request is invalid. Relevant for Shipment and Calculation service methods
400	Invalid courier service	Returned when the courier service in request is invalid. Relevant for Shipment and Calculation service methods
410	Invalid COD additional service	Returned when COD additional service data in request is invalid. Relevant for Shipment and Calculation service methods
415	Invalid Declared Value additional service	Returned when Declared Value additional service data in request is invalid. Relevant for Shipment and Calculation service methods
420	Invalid OBPD additional service	Returned when Options Before Payment and Delivery additional service data in request is invalid. Relevant for Shipment and Calculation service methods
425	Invalid Delivery To Floor additional service	Returned when Delivery To Floor additional service data in request is invalid. Relevant for Shipment and Calculation service methods
430	Invalid Special Deliery additional service	Returned when Special Deliery additional service data in request is invalid. Relevant for Shipment and Calculation service methods
435	Invalid ROD additional service	Returned when Return of Documents additional service data in request is invalid. Relevant for Shipment and Calculation service methods
440	Invalid Return Receipt additional service	Returned when Return Receipt additional service data in request is invalid. Relevant for Shipment and Calculation service methods
445	Invalid SWAP additional service	Returned when SWAP additional service data in request is invalid. Relevant for Shipment and Calculation service methods
450	Invalid ROP additional service	Returned when Return of Pallets additional service data in request is invalid. Relevant for Shipment and Calculation service methods
455	Invalid Return Voucher additional service	Returned when Return Voucher additional service data in request is invalid. Relevant for Shipment and Calculation service methods
460	Invalid Fixed Time Delivery additional service	Returned when Fixed Time Delivery additional service data in request is invalid. Relevant for Shipment and Calculation service methods
500	Invalid pickup date	Returned when pickup date is not valid. Relevant for Shipment and Calculation service methods
510	Invalid deferred days	Returned when deferred days provided in request is not valid. Relevant for Shipment and Calculation service methods
515	Invalid discount card	Returned when discount card provided in request is not valid. Relevant for Shipment service methods
520	Invalid saturday delivery flag	Returned when saturday delivery flag provided in request is not valid. Relevant for Shipment and Calculation service methods
600	Invalid shipment contents	Returned when shipment contents provided in request is not valid. Relevant for Shipment service methods
605	Invalid shipment package	Returned when shipment package provided in request is not valid. Relevant for Shipment service methods
610	Invalid documents flag	Returned when documents flag provided in request is not valid. Relevant for Shipment and Calculation service methods
615	Invalid palletized flag	Returned when palletized flag provided in request is not valid. Relevant for Shipment and Calculation service methods
620	Invalid weight	Returned when total weight or parcel weight in request is not valid. Relevant for Shipment and Calculation service methods
630	Invalid parcels	Returned when there is an error in parcels data provided in request. Relevant for Shipment and Calculation service methods
700	Invalid courier service payment	Returned when there is an error in courier service payment data provided in request. Relevant for Shipment and Calculation service methods
710	Invalid packings payment	Returned when there is an error in packings payment data provided in request. Relevant for Shipment and Calculation service methods
800	Invalid ref1	Returned when shipment reference 1 provided in request. Relevant for Shipment service methods
805	Invalid ref2	Returned when shipment reference 2 provided in request. Relevant for Shipment service methods
810	Invalid shipment note	Returned when shipment note provided in request. Relevant for Shipment service methods