Please, wait
Table of Contents
2.1.1 Create Shipment Request (CreateShipmentRequest)
2.1.2 Create Shipment Response (CreateShipmentResponse)
2.1.3 Create Shipment - URL (GET) Schema
2.1.4 Cancel Shipment Request (CancelShipmentRequest)
2.1.5 Cancel Shipment Response (CancelShipmentResponse)
2.1.6 Cancel Shipment - URL (GET) schema
2.1.7 Add parcel Request (AddParcelRequest)
2.1.8 Add parcel Response (AddParcelResponse)
2.1.9 Add parcel Request (AddParcelRequest) - URL (GET) schema
2.1.10 Finalize Pending Shipment Request (FinalizePendingShipmentRequest)
2.1.11 Finalize Pending Shipment Response (FinalizePendingShipmentResponse)
2.1.12 Finalize Pending Shipment Request (FinalizePendingShipmentRequest) - URL (GET) schema
2.1.13 Shipment Information Request (ShipmentInformationRequest)
2.1.14 Shipment Information Response (ShipmentInformationResponse)
2.1.15 Shipment Information Request (ShipmentInformationRequest) - URL (GET) schema
2.1.16 Secondary Shipments Request (SecondaryShipmentsRequest)
2.1.17 Secondary Shipments Response (SecondaryShipmentsResponse)
2.1.18 Secondary Shipments Request (SecondaryShipmentsRequest) - URL (GET) schema
2.1.19 Update Shipment Request (UpdateShipmentRequest)
2.1.20 Update Shipment Response (UpdateShipmentResponse)
2.1.21 Update Shipment Request (UpdateShipmentRequest) - URL (GET) schema
2.1.22 Update Shipment Properties Request (UpdateShipmentPropertiesRequest)
2.1.23 Update Shipment Properties Response (UpdateShipmentPropertiesRequest)
2.1.24 Update Shipment Properties Request (UpdateShipmentPropertiesRequest) - URL (GET) schema
2.1.25 Find Parcels By Reference Request (FindParcelsByRefRequest)
2.1.26 Find Parcels By Reference Response (FindParcelsByRefResponse)
2.1.27 Find Parcels By Reference Request (FindParcelsByRefRequest) - URL (GET) schema
2.1.28 Handover To Courier Request (HandoverToCourierRequest)
2.1.29 Handover To Courier Response (HandoverToCourierResponse)
2.1.30 Handover To Courier Request (HandoverToCourierRequest) - URL (GET) schema
2.1.31 Handover To Midway Carrier Request (HandoverToMidwayCarrierRequest)
2.1.32 Handover To Midway Carrier Response (HandoverToMidwayCarrierResponse)
2.1.33 Handover To Midway Carrier Request (HandoverToMidwayCarrierRequest) - URL (GET) schema
2.1.34 Barcode Information Request (BarcodeInformationRequest)
2.1.35 Barcode Information Response (BarcodeInformationResponse)
2.1.36 Barcode Information Request (BarcodeInformationResponse) - URL (GET) schema
2.2.1 Print Request (PrintRequest)
2.2.2 Print Response (PrintResponse)
2.2.3 Print Request - URL (GET) schema
2.2.5 Extended Print Response (ExtendedPrintResponse)
2.2.6 Extended Print Request - URL (GET) schema
2.2.7 Label Info Request (LabelInfoRequest)
2.2.8 Label Info Response (LabelInfoResponse)
2.2.9 Label Info Request - URL (GET) schema
2.2.10 Print Voucher Request (PrintVoucherRequest)
2.2.11 Print Voucher Response (PrintVoucherResponse)
2.2.12 Print Voucher Request - URL (GET) schema
2.3.1 Track Request (TrackRequest)
2.3.2 Track Response (TrackResponse)
2.3.3 Track Request - URL (GET) schema
2.3.4 Bulk Tracking Data Files Request (BulkTrackingDataFielsRequest)
2.3.5 Bulk Tracking Data Files Response (BulkTrackingDataFielsResponse)
2.3.6 Bulk Tracking Data Files Request - URL (GET) schema
2.4.1 Pickup Request (PickupRequest)
2.4.2 Pickup Response (PickupResponse)
2.4.3 Pickup Request - URL (GET) schema
2.4.4 Pickup Terms Request (PickupTermsRequest)
2.4.5 Pickup Terms Response (PickupTermsResponse)
2.4.6 Pickup Terms Request - URL (GET) schema
2.5.1.1 Get Country Request (GetCountryRequest)
2.5.1.2 Get Country Response (GetCountryResponse)
2.5.1.3 Get Country Request - URL (GET) schema
2.5.1.4 Find Country Request (FindCountryRequest)
2.5.1.5 Find Country Response (FindCountryResponse)
2.5.1.6 Find Country Request - URL (GET) schema
2.5.1.7 Get All Countries Request (GetAllCountriesRequest)
2.5.1.8 Get All Countries Response (GetAllCountriesResponse)
2.5.1.9 Get All Countries Request - URL (GET) schema
2.5.2.1 Get State Request (GetStateRequest)
2.5.2.2 Get State Response (GetStateResponse)
2.5.2.3 Get State Request - URL (GET) schema
2.5.2.4 Find State Request (FindStateRequest)
2.5.2.5 Find State Response (FindStateResponse)
2.5.2.6 Find State Request - URL (GET) schema
2.5.2.7 Get All States Request (GetAllStatesRequest)
2.5.2.8 Get All States Response (GetAllStatesResponse)
2.5.2.9 Get All States Request - URL (GET) schema
2.5.3.1 Get Site Request (GetSiteRequest)
2.5.3.2 Get Site Response (GetSiteResponse)
2.5.3.3 Get Site Request - URL (GET) schema
2.5.3.4 Find Site Request (FindSiteRequest)
2.5.3.5 Find Site Response (FindSiteResponse)
2.5.3.6 Find Site Request - URL (GET) schema
2.5.3.7 Get All Sites Request (GetAllSitesRequest)
2.5.3.8 Get All Sites Response (GetAllSitesResponse)
2.5.3.9 Get All Sites Request - URL (GET) schema
2.5.4.1 Get Street Request (GetStreetRequest)
2.5.4.2 Get Street Response (GetStreetResponse)
2.5.4.3 Get Street Request - URL (GET) schema
2.5.4.4 Find Street Request (FindStreetRequest)
2.5.4.5 Find Street Response (FindStreetResponse)
2.5.4.6 Find Street Request - URL (GET) schema
2.5.4.7 Get All Streets Request (GetAllStreetsRequest)
2.5.4.8 Get All Streets Response (GetAllStreetsResponse)
2.5.4.9 Get All Streets Request - URL (GET) schema
2.5.5.1 Get Complex Request (GetComplexRequest)
2.5.5.2 Get Complex Response (GetComplexResponse)
2.5.5.3 Get Complex Request - URL (GET) schema
2.5.5.4 Find Complex Request (FindComplexRequest)
2.5.5.5 Find Complex Response (FindComplexResponse)
2.5.5.6 Find Complex Request - URL (GET) schema
2.5.5.7 Get All Complexes Request (GetAllComplexesRequest)
2.5.5.8 Get All Complexes Response (GetAllComplexesResponse)
2.5.5.9 Get All Complexes Request - URL (GET) schema
2.5.6.1 Find Block Request (FindBlockRequest)
2.5.6.2 Find Block Response (FindBlockResponse)
2.5.6.3 Find Block Request - URL (GET) schema
2.5.6.4 Get All Blocks Request (GetAllBlocksRequest)
2.5.6.5 Get All Blocks Response (GetAllBlocksResponse)
2.5.6.6 Get All Blocks Request - URL (GET) schema
2.5.7.1 Get POI Request (GetPOIRequest)
2.5.7.2 Get POI Response (GetPOIResponse)
2.5.7.3 Get POI Request - URL (GET) schema
2.5.7.4 Find POI Request (FindPOIRequest)
2.5.7.5 Find POI Response (FindPOIResponse)
2.5.7.6 Find POI Request - URL (GET) schema
2.5.7.7 Get All Points of Interest Request (GetAllPOIRequest)
2.5.7.8 Get All Points of Interest Response (GetAllPOIResponse)
2.5.7.9 Get All Points of Interest Request - URL (GET) schema
2.5.8.1 Get All Postcodes Request (GetAllPostcodesRequest)
2.5.8.2 Get All Postcodes Response (GetAllPostcodesResponse)
2.5.8.3 Get All Postcodes Request - URL (GET) schema
2.5.9.1 Get Office Request (GetOfficeRequest)
2.5.9.2 Get Office Response (GetOfficeResponse)
2.5.9.3 Get Office Request - URL (GET) schema
2.5.9.4 Find Office Request (FindOfficeRequest)
2.5.9.5 Find Office Response (FindOfficeResponse)
2.5.9.6 Find Office Request - URL (GET) schema
2.5.9.7 Find Nearest Offices Request (FindNearestOfficesRequest)
2.5.9.8 Find Nearest Offices Response (FindNearestOfficesResponse)
2.5.9.9 Find Nearest Offices Request - URL (GET) schema
2.6.1 Calculation Request (CalculationRequest)
2.6.2 Calculation Response (CalculationResponse)
2.6.3 Calculation Request - URL (GET) schema
2.7.1 Get Client Request (GetClientRequest)
2.7.2 Get Client Response (GetClientResponse)
2.7.3 Get Client Request - URL (GET) schema
2.7.4 Get Contract Clients Request (GetContractClientsRequest)
2.7.5 Get Contract Clients Response (GetContractClientsResponse)
2.7.6 Get Contract Clients Request - URL (GET) schema
2.7.7 Create Contact Request (CreateContactRequest)
2.7.8 Create Contact Response (CreateContactResponse)
2.7.9 Create Contact Request - URL (GET) schema
2.7.10 Get Contact By External Id Request (GetContactByExternalIdRequest)
2.7.11 Get Contact By External Id Response (GetContactByExternalIdResponse)
2.7.12 Get Contact By External Id Request - URL (GET) schema
2.7.13 Get Own Client Id Request (GetOwnClientIdRequest)
2.7.14 Get Own Client Id Response (GetOwnClientIdResponse)
2.7.15 Get Own Client Id Request - URL (GET) schema
2.7.16 Contract Info Request (ContractInfoRequest)
2.7.17 Contract Info Response (ContractInfoResponse)
2.7.18 Contract Info Request - URL (GET) schema
2.8.1 Validate Address Request (ValidateAddressRequest)
2.8.2 Validate Address Response (ValidationResponse)
2.8.3 Validate Address Request - URL (GET) schema
2.8.4 Validate Post Code Request (ValidatePostCodeRequest)
2.8.5 Validate Post Code Response (ValidationResponse)
2.8.6 Validate Post Code Request - URL (GET) schema
2.8.7 Validate Phone Request (ValidatePhoneRequest)
2.8.8 Validate Phone Response (ValidationResponse)
2.8.9 Validate Phone Request - URL (GET) schema
2.8.10 Validate Shipment Request (ValidateShipmentRequest)
2.8.11 Validate Shipment Response (ValidationResponse)
2.8.12 Validate Shipment Request - URL (GET) schema
2.9.1 Services Request (ServicesRequest)
2.9.2 Services Response (ServicesResponse)
2.9.3 Services Request - URL (GET) schema
2.9.4 Destination Services Request (DestinationServicesRequest)
2.9.5 Destination Services Response (DestinationServicesResponse)
2.9.6 Destination Services Request - URL (GET) schema
2.10.1 Payout Request (PayoutRequest)
2.10.2 Payout Response (PayoutResponse)
2.10.3 Payout Request - URL (GET) schema
3.1 Shipment Service (ShipmentService)
3.1.1 Shipment Additional Services (ShipmentAdditionalServices)
3.1.1.1 COD Additional Service (ShipmentCODAdditionalService)
3.1.1.1.1 Shipment COD Fiscal Receipt Item (ShipmentCODFiscalReceiptItem)
3.1.1.3 Shipment Return Additional services (ShipmentReturnAdditionalServices)
3.1.1.3.1 Return of Documents (ROD) Additional service (ShipmentRODAdditionalService)
3.1.1.3.2 Return Receipt Additional Service (ShipmentReturnReceiptAdditionalService)
3.1.1.3.3 SWAP Additional Service (ShipmentSWAPAdditionalService)
3.1.1.3.4 Return of Pallets (ROP) Additional Service (ShipmentROPAdditionalService)
3.1.1.3.4.1 ROP Additional Service Lines (ShipmentROPAdditionalServiceLine)
3.1.1.3.5 Return Voucher Additional Service (ShipmentReturnVoucherAdditionalService)
3.1.1.4 Options before payment details Additional Service (ShipmentOBPD)
3.2 Shipment Content (ShipmentContent)
3.2.1 Shipment Parcel (ShipmentParcel)
3.2.1.1 Shipment Parcel Size (ShipmentParcelSize)
3.2.1.2 External carrier parcel number (ExternalCarrierParcelNumber)
3.3 Shipment Payment (ShipmentPayment)
3.3.1 Shipment Discount Card (ShipmentDiscountCardId)
3.3.2 Bank Account (BankAccount)
3.4 Shipment Sender And Recipient
3.4.1 Shipment Sender (ShipmentSender)
3.4.2 Shipment Recipient (ShipmentRecipient)
3.4.3 Shipment Address (ShipmentAddress)
3.4.4 Shipment Phone Number (ShipmentPhoneNumber)
3.4.5 Auto-select Nearest Office Policy (AutoSelectNearestOfficePolicy)
3.5.1 Created Shipment Parcel (CreatedShipmentParcel)
3.5.2 Shipment Parcel Reference (ShipmentParcelRef)
3.5.3 Parcel Handover (ParcelHandover)
3.5.4 Track Shipment Parcel Reference (TrackShipmentParcelRef)
3.5.5 Midway Carrier Parcel Handover (MidwayCarrierParcelHandover)
3.6 Shipment Price (ShipmentPrice)
3.6.1 Shipment Price Amount (ShipmentPriceAmount)
3.6.2 Return Amounts (ReturnAmounts)
3.6.2.1 Money Transfer Premium (MoneyTransferPremium)
3.8 Parcel to Print (ParcelToPrint)
3.8.1 Parcel to Print Additional Barcode (ParcelToPrintAdditionalBarcode)
3.9 TrackedParcel (TrackedParcel)
3.9.1 Tracked Parcel Operation (TrackedParcelOperation)
3.9.1.1 Tracked Parcel Operation Additional Info (TrackedParcelOperationAdditionalInfo)
3.9.2 External Carrier Parcel Number Details (ExternalCarrierParcelNumberDetails)
3.10 Pickup order (PickupOrder)
3.11.1 Address Nomenclature Type (AddressNomenclatureType)
3.17 Point of interest (PointOfInterest)
3.18.1 Office working time schedule (OfficeWorkingTimeSchedule)
3.19 Calculation Service (CalculationService)
3.20 Calculation Sender (CalculationSender)
3.21 Calculation Recipient (CalculationRecipient)
3.22 Calculation Address Location (AddressLocation)
3.23 Calculation Content (CalculationContent)
3.24 Calculation Result (CalculationResult)
3.26.4.1 CODPayment (CODPayment)
3.26.5 Shipment Delivery (ShipmentDelivery)
3.26.6 Primary Shipment (PrimaryShipment)
3.26.7 Secondary Shipment (SecondaryShipment)
3.26.8 Shipment Parcel Number (ShipmentParcelNumber)
3.27.1 AdditionalCourierServices
3.27.1.1 AdditionalCourierService
3.31 SpecialDeliveryRequirements
3.33 CODAdditionalServiceContractInfo
3.33.1 CODInternationalAnnexContractInfo
4.1 Appendix 1 - Track And Trace Operation Codes
4.2 Appendix 2 - Track And Trace Operation Exception Codes
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:
To get technical support for the integration please send us an e-mail to Tech Support and provide the following info:
and detailed explanation of the situation you need support for.
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.
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.
API JSON schema is available for download here
Examples can be found here
BASE_URL=_
Web service URL: BASE_URL/shipment
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 |
No |
Defines the sender of the shipment and shipment's pickup place. If not specified, the logged user is considered as a sender. |
|
|
recipient |
Yes |
Defines the recipient of the shipment and shipment’s delivery place. |
|
|
service |
Yes |
Defines shipment service level agreement. |
|
|
content |
Yes |
Defines shipment’s content - number of parcels, weight, size, etc. |
|
|
payment |
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"
}
Output parameters:
CreateShipmentResponse |
||
Name |
Type |
Data |
id |
String |
Generated shipment id. |
parcels |
|
Generated parcels. |
price |
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 |
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"
}
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:
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:
|
||||
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:
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:
|
||||
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:
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:
|
||||
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.
|
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. |
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
or
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
Web service URL: BASE_URL/shipment/cancel
Method: POST
Content-type: application/json; charset=utf-8
Or
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"
}
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:
{}
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 |
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 |
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 |
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
}
Add parcel response returns generated parcel. Otherwise, an error is included.
CancelShipmentResponse |
||
Name |
Type |
Data |
parcel |
Created shipment parcel (with generated id and sequence number) |
|
error |
Error |
Response error |
Example JSON:
{}
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.
|
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
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"
}
The response is the same as CreateShipmentResponse.
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
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 |
|
ShipmentInformationResponse |
||
Name |
Type |
Data |
shipments |
Shipment[] |
Shipment information |
error |
Error |
Response error |
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 |
|
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).
|
|
SecondaryShipmentsResponse |
||
Name |
Type |
Data |
shipments |
List of secondary shipments |
|
error |
Error |
Response error |
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).
|
|
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 |
Response is CreateShipmentResponse - same returned in createShipment method
Output parameters:
UpdateShipmentResponse |
||
Name |
Type |
Data |
CreateShipmentResponse fields are here |
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 |
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"
}
}
Response is UpdateShipmentResponse - same returned in updateShipment method
Output parameters:
UpdateShipmentPropertiesResponse |
||
Name |
Type |
Data |
UpdateShipmentResponse fields are here |
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 |
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",
}
FindParcelsByRefResponse |
||
Name |
Type |
Data |
barcodes |
String[] |
List of barcodes found |
error |
Error |
Response error |
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 |
|
Register handover to courier barcode operations
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 |
Yes |
Parcel barcodes with datetime to register handover to courier operations |
Should refer accessible shipment parcels |
Response is empty on success. Otherwise, an error is included.
HandoverToCourierResponse |
||
Name |
Type |
Data |
error |
Error |
Response error |
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 |
Register handover to midway carrier barcode operations
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 |
Yes |
Parcel barcodes with datetime, country and site name to register handover to midway carrier operations |
Should refer accessible shipment parcels |
Response is empty on success. Otherwise, an error is included.
HandoverToMidwayCarrierResponse |
||
Name |
Type |
Data |
error |
Error |
Response error |
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 |
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 |
Yes |
Parcel to get info for |
Validated for allowed access. |
Example JSON:
{
"userName":"testUser",
"password":"password",
"parcel": {
"fullBarcode":"1000509431237540020002030017"
}
}
Barcode information response
BarcodeInformationResponse |
||
Name |
Type |
Data |
labelInfo |
Label info |
|
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"
}
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
Web service URL: BASE_URL/print
Used to create labels (waybills, stickers and etc.)
PDF Examples:
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 |
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"
}
}
]
}
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.
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. |
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.
ExtendedPrintResponse |
||
Name |
Type |
Data |
data |
byte[] (BASE64 encoded string) |
Response data - base64 encoded binary data (pdf) |
printLabelsInfo |
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"
}
]
}
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.
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 |
Yes |
Parcels to get label info for |
Validated for allowed access. |
Example JSON:
{
"userName":"testUser",
"password":"password",
"parcels": [
{
{
"id":"80002338331"
}
},
{
{
"id":"80002338159"
}
}
]
}
LabelInfoResponse |
||
Name |
Type |
Data |
printLabelsInfo |
Print labels info |
|
error |
Error |
Response error |
Example JSON:
{
"labelsInfo”: [
{
"parcelId": "50943123754",
"hubId": 2,
"officeId": 2,
"deadlineDay": 18,
"deadlineMonth": 2,
"tourId": 2203,
"fullBarcode": "1000509431237540020002030017"
}
]
}
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.
|
|
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"]
}
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.
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. |
|
Web service URL: BASE_URL/track
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 |
Yes |
Parcels to track |
|
|
lastOperationOnly |
Boolean |
No |
Flag to return last operation only’ |
|
TrackResponse |
|||
Name |
Type |
Mandatory |
Data |
parcels |
Yes |
Parcel track information |
|
error |
Error |
No |
Response error |
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
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. |
BulkTrackingDataFilesResponse |
|||
Name |
Type |
Mandatory |
Data |
files |
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 |
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. |
Web service URL: BASE_URL/pickup
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
}
PickupResponse |
|||
Name |
Type |
Mandatory |
Data |
orders |
Yes |
Pickup orders created |
|
error |
Error |
No |
Response error |
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
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 |
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. |
|
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 |
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:
|
||||
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
Web service URL: BASE_URL/location
This section specifies methods to query system for allowed countries
Web service URL: BASE_URL/location/country
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",
}
GetCountryResponse |
|||
Name |
Type |
Mandatory |
Data |
country |
No |
Found country or null if not found |
|
error |
Error |
No |
Response error |
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
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"
}
The countries in return are these that match search criteria in request and ordered by:
The result is limited to 10 records.
FindCountryResponse |
|||
Name |
Type |
Mandatory |
Data |
countries |
Country[] |
No |
Array of countries |
error |
Error |
No |
Response error |
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
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",
}
See Country data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for allowed states
Web service URL: BASE_URL/location/state
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",
}
GetStateResponse |
|||
Name |
Type |
Mandatory |
Data |
site |
No |
State found or null if not found |
|
error |
Error |
No |
Response error |
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
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"
}
The states in return are these that match search criteria in request and ordered by:
The result is limited to 10 records.
FindStateResponse |
|||
Name |
Type |
Mandatory |
Data |
states |
State[] |
No |
Array of sites |
error |
Error |
No |
Response error |
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
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",
}
See State data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for allowed sites
Web service URL: BASE_URL/location/site
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",
}
GetSiteResponse |
|||
Name |
Type |
Mandatory |
Data |
site |
No |
Found site or null if not found |
|
error |
Error |
No |
Response error |
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
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"
}
The sites in return are these that match search criteria in request and ordered by:
The result is limited to 10 records.
FindSiteResponse |
|||
Name |
Type |
Mandatory |
Data |
sites |
Site[] |
No |
Array of sites |
error |
Error |
No |
Response error |
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
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",
}
See Site data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for allowed streets
Web service URL: BASE_URL/location/street
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",
}
GetStreetResponse |
|||
Name |
Type |
Mandatory |
Data |
street |
No |
Found street or null if not found |
|
error |
Error |
No |
Response error |
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
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"
}
The streets in return are these that match search criteria in request and ordered by:
The result is limited to 10 records.
FindStreetResponse |
|||
Name |
Type |
Mandatory |
Data |
streets |
Street[] |
No |
Array of streets |
error |
Error |
No |
Response error |
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
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",
}
See Street data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for allowed complexes
Web service URL: BASE_URL/location/complex
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",
}
GetComplexResponse |
|||
Name |
Type |
Mandatory |
Data |
complex |
No |
Complex found or null if not found |
|
error |
Error |
No |
Response error |
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
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"
}
The complexes in return are these that match search criteria in request and ordered by:
The result is limited to 10 records.
FindComplexResponse |
|||
Name |
Type |
Mandatory |
Data |
complexes |
Complex[] |
No |
Array of complexes |
error |
Error |
No |
Response error |
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
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",
}
See Complex data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for allowed blocks
Web service URL: BASE_URL/location/block
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"
}
The blocks in return are these that match search criteria in request and ordered by:
The result is limited to 10 records.
FindBlockResponse |
|||
Name |
Type |
Mandatory |
Data |
blocks |
Block[] |
No |
Array of blocks |
error |
Error |
No |
Response error |
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
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",
}
See Block data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for allowed points of interest
Web service URL: BASE_URL/location/poi
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",
}
GetPOIResponse |
|||
Name |
Type |
Mandatory |
Data |
poi |
No |
POI found or null if not found |
|
error |
Error |
No |
Response error |
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
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"
}
The points of interest in return are these that match search criteria in request and ordered by:
The result is limited to 10 records.
FindPOIResponse |
|||
Name |
Type |
Mandatory |
Data |
pois |
No |
Array of points of interest |
|
error |
Error |
No |
Response error |
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
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",
}
See PointOfInterest data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for allowed country postcodes
Web service URL: BASE_URL/location/postcode
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",
}
Response is CSV (comma separated) file int UTF8 encoding. The format is:
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
This section specifies methods to query system for available offices
Web service URL: BASE_URL/location/office
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",
}
GetOfficeResponse |
|||
Name |
Type |
Mandatory |
Data |
office |
No |
Office found or null if not found |
|
error |
Error |
No |
Response error |
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
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"
}
The offices in return are these that match search criteria in request and ordered by:
FindOfficeResponse |
|||
Name |
Type |
Mandatory |
Data |
offices |
Office[] |
No |
Array of offices |
error |
Error |
No |
Response error |
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
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 |
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"
]
}
The offices in return are these that match search criteria in request and ordered by distance
FindNearestOfficesResponse |
|||
Name |
Type |
Mandatory |
Data |
offices |
No |
Array of offices |
|
x |
Double |
No |
Provided address X coord |
y |
Double |
No |
Provided address Y coord |
error |
Error |
No |
Response error |
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 |