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 |
addressLine1 | address_line1 | line1 |
String |
Required for address type 2. |
Address line 1. Used for addresses of type 2 (foreign address). |
Max 35 |
addressLine2 | address_line2 | line2 |
String |
No |
Address line 2. Used for addresses of type 2 (foreign address). |
Max 35 |
X | x |
Double |
No |
GIS coordinates - X. Used for all address types.
|
|
Y | y |
Double |
No |
GIS coordinates - Y. Used for all address types. |
|
limit |
Integer |
No |
The number of records to return in response. |
|
distance |
Integer |
No |
Maximum office distance ( in meters ) from the provided address |
|
type |
Integer |
No |
enum["CASH", "POSTAL_MONEY_TRANSFER"] |
|
office_features | officeFeatures |
Integer |
No |
enum["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][]
|
|
Web service URL: BASE_URL/calculate
Web service URL: BASE_URL/calculate
Method: POST
Content-type: application/json; charset=utf-8
CalculationRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
sender |
No
|
Defines the pickup place. If not specified, the logged user location is considered as a sender location. |
|
|
recipient |
Yes |
Defines the recipient delivery place. |
|
|
service |
Yes |
Defines service agreemen |
|
|
content |
Yes |
Defines content - parcels, weight and etc |
|
|
payment |
Yes |
Defines who-pays-what in shipment |
|
CalculationResponse |
|||
Name |
Type |
Mandatory |
Data |
calculations |
Yes |
Calculations for all service ids in request |
|
error |
Error |
No |
Response error |
This approach is used to calculate, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/calculate
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
CalculationRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
Calculation sender details If logged user is the sender, you may skip providing sender details at all. If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also. Otherwise, sender_id should stay empty and it is required to provide as a minimum:
|
||||
senderId | sender_id |
Long |
No |
Client id to refer а sender |
Validate for existence. |
senderPrivatePerson | sender_private_person |
Boolean (true/false, y/n, âyes/noâ - all case insensitive) |
If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory |
Sender private person flag. |
|
Sender Address Location Details See AddressLocation for more details. The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at senderâs address is expected. |
||||
senderAddressCountryId | sender_address_country_id |
Integer |
No |
Country ISO code. If not provided, the local country is assumed. Used for all address types. |
Validate for valid country code |
senderAddressStateId | sender_address_state_id |
String |
Required if country requires state |
Country state. Used for addresses of type 2 (foreign address). |
Validate for valid country state. |
senderAddressSiteId | sender_address_site_id |
Long |
Required, if country has full site nomenclature and pair (site_type, site_name) not provided |
Site id. Used for all address types |
Validate for valid site and value is required |
senderAddressSiteType | sender_address_site_type |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address) |
Max 20 characters |
senderAddressSiteName | sender_address_site_name |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types. |
Max 50 characters |
senderAddressPostcode | senderAddressPostCode | sender_address_postcode |
String |
Required if country requires post code |
Can be used in conjunction with countryId to find unique site. Used for all address types |
Max 10 characters |
dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId | senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id |
Integer |
Required, if the sender is an internal customer. If sender address is provided, it is forbidden. |
Drop off office id. |
Should refer to a valid accessible office |
sender_geo_pudo_id | senderGeoPUDOId | dropoff_geo_pudo_id | dropoffGeoPUDOId |
String |
No. Must be empty if dropoffOfficeId is provided |
DPD drop off office PUDO id |
Should refer to a valid accessible DPD office. |
Calculation recipient details If you refer an existing customer, provide client's id in recipient_id parameter and other recipient parameters may be skipped at all Otherwise, recipient_id should stay empty and it is required to provide as a minimum:.
|
||||
recipientId | recipient_id |
Long |
No |
Client id to refer а recipient |
Validate for existence. |
recipientPrivatePerson | recipient_private_person |
Boolean (true/false, y/n, âyes/noâ - all case insensitive) |
If recipient_id is provided, it is forbidden. Otherwise, it is mandatory |
Recipient private person flag. |
|
Recipient Address Location Details See AddressLocation for more details. The recipient address location is expected when recipient_id is empty and recipient_pickup_office_id is empty and not required. In other words, the recipient address location is required when the recipient is not a referred customer and delivery at recipientâs address is expected. |
||||
recipientAddressCountryId | recipient_address_country_id |
Integer |
No |
Country ISO code. If not provided, the local country is assumed. Used for all address types. |
Validate for valid country code |
recipientAddressStateId | recipient_address_state_id |
String |
Required if country requires state |
Country state. Used for addresses of type 2 (foreign address). |
Validate for valid country state. |
recipientAddressSiteId | recipient_address_site_id |
Long |
Required, if country has full site nomenclature and pair (site_type, site_name) not provided |
Site id. Used for all address types |
Validate for valid site and value is required |
recipientAddressSiteType | recipient_address_site_type |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address) |
Max 20 characters |
recipientAddressSiteName | recipient_address_site_name |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types. |
Max 50 characters |
recipientAddressPostcode | recipientAddressPostCode | recipient_address_postcode |
String |
Required if country requires post code |
Can be used in conjunction with countryId to find unique site. Used for all address types |
Max 10 characters |
pickupOfficeId | pickUpOfficeId | recipientPickupOfficeId | recipientPickUpOfficeId | pickup_office_id | recipient_pickup_office_id |
Integer |
Required, if the recipient is an internal customer. If recipient address is provided, it is forbidden. |
Pickup office id. |
Should refer to a valid accessible office |
recipient_geo_pudo_id | recipientGeoPUDOId | pickup_geo_pudo_id | pickupGeoPUDOId |
String |
No. Must be empty if pickupOfficeId is provided |
DPD pickup office PUDO id |
Should refer to a valid accessible DPD office. |
Calculation Service Details See CalculationService for more details. Shipment service defines agreement with customer for courier service. This includes:
|
||||
pickupDate | pickup_date |
Date (date) Example: â2018-01-22" |
No (default value is today) |
The date for shipment pick-up |
Could be today or a future date. |
autoAdjustPickupDate | auto_adjust_pickup_date | autoadjust_pickup_date |
Boolean |
No (default is false) |
To find first available date for pickup starting from pickupDate according to pickup schedule for services |
|
serviceIds | service_ids |
String (comma separated service ids) |
Yes |
Service ids to get calculation for. |
Each service id (code) should be valid for destination |
deferredDays | deferred_days |
Integer |
No (default value is 0) |
This parameter allowscusers to specify by how many (business) days they would like to postpone the shipment delivery from the standard term.. |
Allowed values are 0, 1 and 2 |
saturdayDelivery | saturday_delivery |
Boolean |
No) |
This parameter may adjust the delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured recipient working schedule. |
|
COD Additional Service For more information see ShipmentCODAdditionalService. |
||||
codAmount | cod_amount |
double
|
No
|
Defines shipment COD base amount. |
Validated against maximum allowed amounts for destination. |
codCurrency | cod_currency |
String |
No (default is the currency code of the destination country) |
Defines shipment COD currency code. |
Validated against allowed currency code of destination country. |
codProcessingType | cod_processing_type |
enum [“CASH”, “POSTAL_MONEY_TRANSFER”] |
No (default is “CASH”) |
Defines COD processing type. |
Appropriate contract and annexes may be required. |
codPayoutThirdParty | cod_payout_third_party |
Boolean (true/false, y/n, “yes/no” - all case insensitive) |
No |
If this flag is set, the COD is paid to a third party (not to the sender). |
Requires the third party to be the payer of the courier service. |
codWithShippingPrice | cod_with_shipping_price |
Boolean (true/false, y/n, “yes/no” - all case insensitive) |
No |
Flag indicating whether the shipping price should be included in the COD. |
|
Options before payment details Additional Service For more information see ShipmentOBPD. |
||||
obpd_option |
enum [“OPEN”, “TEST”]
|
No (For certain destinations could be required.)
|
Defines option to be used. Open parcels before payment or open and test parcels before payment. |
Return shipment is validated for destination. |
obpd_return_service_id |
Integer |
No (For certain destinations could be required.)
|
Defines service id to be used on return, if COD payment is refused. |
Return shipment is validated for destination. |
obpd_return_payer |
enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”] |
No (For certain destinations could be required.) |
Defines who pays the return shipment, if COD payment is refused. |
Return shipment is validated for destination. |
Declared Value (Extended Liability) Additional Service For more information see ShipmentDeclaredVaueAdditionalService. Declared value payer is required when declared value amount is provided and is set in payment section. |
||||
declaredValueAmount | declared_value_amount |
double
|
No
|
Defines shipment Declared Value (extended liability) base amount. Declared value amount is always in local system currency. |
Validated against maximum allowed amounts. |
fragile | declaredValueFragile | declared_value_fragile |
Boolean (true/false, y/n, “yes/no” - all case insensitive)
|
No |
Defines fragile flag for shipment content. |
Fragile shipments requires declared value sub service. |
declaredValueIgnoreIfNotApplicable | declared_value_ignore_if_not_applicable |
Boolean (true/false, y/n, “yes/no” - all case insensitive)
|
No |
Flag to ignore declared value additional service in case it is not applicable for shipment on calculation |
E-shops usually configure declared value (extended liability) by default for their shipments, However there are some certain internal rules when this option is not available. The flag is used in calculation service to provide price to end clients without repeating the calculation request with removed additional service |
Fixed Time Delivery Additional Service Fixed time delivery is an additional service that provides instruction to deliver shipment at a certain time on the delivery date. |
||||
fixedTimeDelivery | fixed_time_delivery |
Integer |
No |
This option fixes the time of delivery on the delivery date. 1130 - means 11:30 920 - means 09:20 |
This option is checked against configured allowed time frame for the service. |
Special Delivery Additional Service Special delivery is an additional service that provides instruction to the courier to do additional (special) checks and actions on delivery. These checks and actions are negotiated and contracted in a special delivery annex. For example, the courier could be instructed to check IDs of recipient party at delivery. |
||||
specialDeliveryId | special_delivery_id |
Integer |
No |
Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex. |
Requires annex for special delivery. |
Delivery to Floor Additional Service Delivery to floor is an additional service that provides instruction to the courier that the shipment should not be delivered to the entrance of a multi floor building, but should be moved to a certain floor before delivery. |
||||
deliveryToFloor | delivery_to_floor |
Integer |
No |
Specifies the floor number in the building where to deliver shipment. |
This additional service requires annex. |
Calculation Content For more information see CalculationContent. Defines what is to be delivered with the shipment. |
||||
parcelsCount | parcels_count |
Integer |
Required when parcels list is empty |
Total shipmentâs parcels count. Ignored, if parcels list is not empty. The parcels count is the number of parcels in the lits in that case |
Validated against minimum and maximum allowed for the service |
totalWeight | total_weight |
Double |
Required when parcels list is empty |
Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcelâs weight in that case. |
Validated against minimum and maximum allowed for the service |
documents |
Boolean (true/false, y/n, âyes/noâ - all case insensitive) |
No |
Documents flag of the shipment |
|
palletized |
Boolean (true/false, y/n, âyes/noâ - all case insensitive) |
No |
Palletized flag of the shipment |
|
parcels |
String Format for single parcel is: <seqNo>,<weight>, <width>x<depth>x<height>, <packageUniqueNumber>, <id>, <externalCarrierParcelNumber>
Multiple parcels should be separated with %7C (‘|’) character.
See ShipmentParcel |
Required for pallet and postal services. For multiple parcels add the same url parameter again. The parameters are parsed in the order of their occurrence. If the sequence is incomplete, the missing parameters are considered empty. |
List of parcels. If provided, parcel_count and total_weight are ignored |
Validated against service configuration and pickup and delivery capacity of the depots and the couriers. |
Shipment Payment For more information see ShipmentPayment. Defines who-pays-what in shipment and other payment parameters. |
||||
courierServicePayer | courier_service_payer |
enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ] |
Yes
|
Courier service payer. |
Validated against the service, destination, contracts and annexes. |
declaredValuePayer | declared_value_payer |
enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ] |
No |
Declared value payer. If not provided, the courier service payer is assumed. Not expected, if the declared value amount is empty. |
Validated against the service, destination, contracts and annexes. |
packagePayer | package_payer |
enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ] |
No |
Package payer. If not provided, the courier service payer is assumed. |
Validated against the service, destination, contracts and annexes. |
thirdPartyClientId | third_party_client_id |
Long |
No |
Defines shipment third party - used as a payer of any of shipment payable components. |
Third party customer should be registered customer with valid contract and annex for delayed payment at pickup date. Third party customer should be customer(object) in the same contract as the logged user. |
Discount card For more information see ShipmentDiscountCardId. Discount cards provide promotional discounts. |
||||
discountCardContractId | discount_card_contract_id |
Long |
No |
Discount card contract id. |
Validated against a referred contract. |
discountCardId | discount_card_id |
Long |
No |
Discount card id for contract. |
Validated against a referred discount card. |
Web service URL: BASE_URL/client
Web service URL: BASE_URL/client/{id}
Method: POST
Content-type: application/json; charset=utf-8
Get client by id. Client id is provided as parameter in URL path
GetClientRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
GetClientResponse |
|||
Name |
Type |
Mandatory |
Data |
client |
No |
Client data |
|
error |
Error |
No |
Response error |
This approach is used to get client by id, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/client/{id}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Client id is provided as URL path paramter. The response is the same as method using JSON schema.
URL parameters:
GetClientRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
Web service URL: BASE_URL/client/contract
Method: POST
Content-type: application/json; charset=utf-8
Get clients with same contract as logged user's one, if any
GetContractClientsRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
GetContractClientsResponse |
|||
Name |
Type |
Mandatory |
Data |
clients |
Client[] |
No |
Clients with same contract as logged users's one, if any |
error |
Error |
No |
Response error |
This approach is used to get clients with the same contract as logged user's one, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/client/contract
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
GetContractClientsRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
Web service URL: BASE_URL/client/contact
Method: POST
Content-type: application/json; charset=utf-8
Create contact associating externalId as unique reference
CreateContactRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
externalContactId |
String |
Yes |
External contact id (caller client Id unique reference) |
Max 36 characters. Unique for caller |
secretKey |
String |
No |
External contact secret key |
Max 36 characters |
phone1 |
Yes |
Contact phone number (for example: +40799123456, 0040799123456, +359999123456 - international format numbers or 0799123456, 0999123456 - local numers). |
Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. Only phone numbers starting with "0" (zero) or "+" sign are allowed. |
|
phone2 |
No |
Contact phone number 2. |
Validate for valid phone number, if presents. |
|
clientName |
String |
Yes |
Contact customer name. |
Validate for valid name (minimum 3 symbols, maximum 60). |
objectName |
String |
Forbidden for private persons. Not mandatory for companies |
Contact customer object name. |
Validate for valid name (maximum 60 symbols). |
contactName |
String |
Forbidden for private persons. Required for companies |
Contact name of contact |
Maximum 60 |
|
String |
No |
Contact email. |
Maximum 255 |
privatePerson |
Boolean |
Yes |
Private person flag. |
|
address |
Yes |
Contact address. |
Validated for valid values. |
CreateContactResponse |
|||
Name |
Type |
Mandatory |
Data |
clientId |
Long |
No |
Client Id associated for created contact in the system |
error |
Error |
No |
Response error |
This approach is used to create contact, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/client/contact
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
CreateContactRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
externalContactId | external_contact_id |
String |
Yes |
External contact id (caller client Id unique reference) |
Max 30 characters. Unique for caller |
secretKey | secret_key |
String |
No |
External contact secret key |
Max 36 characters |
phone1 |
String |
Yes |
First phone number. |
|
phone1Ext | phone1_ext |
String |
No |
First phone number extension. |
|
phone2 |
String |
No |
Second phone number. |
|
phone2Ext | phone2_ext |
String |
No |
Second phone number extension. |
|
clientName | client_name |
String |
Yes |
Conact customer name. |
Minimum 3 symbols, maximum 60 |
objectName | object_name |
String |
Forbidden for private persons. Not mandatory for companies |
Conact customer object name. |
Minimum 3 symbols, maximum 60 |
contactName | contact_name |
String |
No Forbidden for private persons. Required for companies. |
Contact name of contact. |
Maximum 60.
|
|
String |
No |
Contact email. |
Maximum 255 |
privatePerson | private_person |
Boolean (true/false, y/n, “yes/no” - all case insensitive) |
Yes |
Contact private person flag. |
|
Contact Address See ShipmentAddress for more details. |
||||
addressCountryId | address_country_id |
Integer |
No
|
Country ISO code. If not provided, local country is assumed. Used for all address types. |
|
addressStateId | address_state_id |
String |
Required, if country supports states. |
Country state. Used for addresses of type 2 (foreign address).
|
|
addressSiteId | address_site_id |
Long |
Required, if country has full site nomenclature and pair (site_type, site_name) not provided. |
Site id. Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country
|
|
addressSiteType | address_site_type |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address). |
Max 20 |
addressSiteName | address_site_name |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types. |
Max 50 |
addressPostcode | addressPostCode | address_postcode |
String |
No |
Can be used in conjunction with countryId to find unique site. Used for all address types. |
Validated for valid postcode in site and country. Max 10 |
addressStreetId | address_street_id |
Long |
No |
Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address). |
|
addressStreetType | address_street_type |
String |
No Forbidden, if street_id is provided. |
Street type. Used for addresses of type 1 (local address). |
Max 15 |
addressStreetName | address_street_name |
String |
No Forbidden, if street_id is provided. |
Street name. Used for addresses of type 1 (local address). |
Max 50 |
addressStreetNumber | address_street_number |
String |
No |
Street number. Used for addresses of type 1 (local address). |
Max 10 |
addressComplexId | address_complex_id |
Long |
No |
Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address). |
|
addressComplexType | address_complex_type |
String |
No Forbidden, if complex_id is provided. |
Complex type. Used for addresses of type 1 (local address). |
Max 15 |
addressComplexName | address_complex_name |
String |
No Forbidden, if complex_id is provided. |
Complex name. Used for addresses of type 1 (local address). |
Max 50 |
addressBlock | addressBlockNo | address_block |
String |
No |
Block No. Used for addresses of type 1 (local address). |
Max 32 |
addressEntrance | addressEntranceNo | address_entrance |
String |
No |
Entrance. Used for addresses of type 1 (local address). |
Max 10 |
addressFloor | addressFloorNo | address_floor |
String |
No |
Floor. Used for addresses of type 1 (local address). |
Max 10 |
addressApartment | addressApartmentNo | address_apartment |
String |
No |
Apartment. Used for addresses of type 1 (local address). |
Max 10 |
addressPoiId | address_poi_id |
Long |
No |
Point of interest identifier. Used for addresses of type 1 (local address). |
|
addressNote | address_note |
String |
No |
Address note. Used for addresses of type 1 (local address). |
200 |
addressLine1 | address_line1 |
String |
Required for address type 2 |
Address line 1. Used for addresses of type 2 (foreign address). |
Max 35 |
addressLine2 | address_line2 |
String |
No |
Address line 2. Used for addresses of type 2 (foreign address). |
Max 35 |
addressX | address_x |
Double |
No |
GIS coordinates - X. Used for all address types.
|
|
addressY | address_y |
Double |
No |
GIS coordinates - Y. Used for all address types. |
|
Web service URL: BASE_URL/client/contact/external/{id}
Method: POST
Content-type: application/json; charset=utf-8
Get contact by external id. External client id is provided as parameter in URL path
GetContactByExternalIdRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
secretKey |
String |
No |
Secret key |
Max 36 characters |
GetContactByExternalIdResponse |
|||
Name |
Type |
Mandatory |
Data |
client |
No |
Client data |
|
error |
Error |
No |
Response error |
This approach is used to get contact by external id, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/client/contact/external/{id}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
External contact id is provided as URL path parameter. The response is the same as method using JSON schema.
URL parameters:
GetContactByExternalIdRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
secretKey | secret_key |
String |
No |
Secret key |
Max 36 characters |
Web service URL: BASE_URL/client
Method: POST
Content-type: application/json; charset=utf-8
Get own client id
GetOwnClientIdRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
GetOwnClientIdResponse |
|||
Name |
Type |
Mandatory |
Data |
clientId |
Long |
Yes |
Own client id |
error |
Error |
No |
Response error |
This approach is used to get own client id, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/client
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
GetOwnClientIdRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
Web service URL: BASE_URL/client/contract/info
Method: POST
Content-type: application/json; charset=utf-8
Get information about logged user contract
ContractInfoRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
ContractInfoResponse |
|||
Name |
Type |
Mandatory |
Data |
id |
Long |
Yes |
Contract id |
specialDeliveryRequirements |
No |
Special delivery requirements |
|
cod |
No |
COD contract info |
|
administrativeFeeAllowed |
boolean |
Yes |
Administrative fee allowed |
error |
Error |
No |
Response error |
This approach is used to get contract information, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/client/contract/info
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ContractInfoRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
Web service URL: BASE_URL/validation
Web service URL: BASE_URL/validation/address
Method: POST
Content-type: application/json; charset=utf-8
This method validates shipment address
ValidateAddressRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
address |
No |
Shipment address to validate |
|
ValidationResponse |
|||
Name |
Type |
Mandatory |
Data |
valid |
Boolean |
No |
Validation result flag |
error |
Error |
No |
Response error |
This approach is used to validate address, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/validation/address
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ValidateAddressRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
Shipment Address See ShipmentAddress for more details. |
||||
countryId | country_id |
Integer |
No
|
Country ISO code. If not provided, the local country is assumed. Used for all address types. |
|
stateId | state_id |
String |
Required, if country supports states. |
Country state. Used for addresses of type 2 (foreign address).
|
|
siteId | site_id |
Long |
Required, if country has full site nomenclature and pair (site_type, site_name) not provided. |
Site id. Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country
|
|
siteType | site_type |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address). |
Max 20 |
siteName | site_name |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types. |
Max 50 |
postcode | postCode | post_code |
String |
No |
Can be used in conjunction with countryId to find unique site. Used for all address types. |
Validated for valid postcode in site and country. Max 10 |
streetId | street_id |
Long |
No |
Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address). |
|
streetType | street_type |
String |
No Forbidden, if street_id is provided. |
Street type. Used for addresses of type 1 (local address). |
Max 15 |
streetName | street_name |
String |
No Forbidden, if street_id is provided. |
Street name. Used for addresses of type 1 (local address). |
Max 50 |
streetNumber | street_number |
String |
No |
Street number. Used for addresses of type 1 (local address). |
Max 10 |
complexId | complex_id |
Long |
No |
Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address). |
|
complexType | complex_type |
String |
No Forbidden, if complex_id is provided. |
Complex type. Used for addresses of type 1 (local address). |
Max 15 |
complexName | complex_name |
String |
No Forbidden, if complex_id is provided. |
Complex name. Used for addresses of type 1 (local address). |
Max 50 |
block | blockNo | block_no |
String |
No |
Block No. Used for addresses of type 1 (local address). |
Max 32 |
entrance | entranceNo | entrance_no |
String |
No |
Entrance. Used for addresses of type 1 (local address). |
Max 10 |
floor | floorNo | floor_no |
String |
No |
Floor. Used for addresses of type 1 (local address). |
Max 10 |
apartment | apartmentNo | apartment_no |
String |
No |
Apartment. Used for addresses of type 1 (local address). |
Max 10 |
poiId | poi_id |
Long |
No |
Point of interest identifier. Used for addresses of type 1 (local address). |
|
addressNote | address_note | note |
String |
No |
Address note. Used for addresses of type 1 (local address). |
200 |
addressLine1 | address_line1 | line1 |
String |
Required for address type 2. |
Address line 1. Used for addresses of type 2 (foreign address). |
Max 35 |
addressLine2 | address_line2 | line2 |
String |
No |
Address line 2. Used for addresses of type 2 (foreign address). |
Max 35 |
X | x |
Double |
No |
GIS coordinates - X. Used for all address types.
|
|
Y | y |
Double |
No |
GIS coordinates - Y. Used for all address types. |
|
Web service URL: BASE_URL/validation/postcode
Method: POST
Content-type: application/json; charset=utf-8
This method validates post code
ValidatePostCodeRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
countryId |
Integer |
Yes - if siteId is not specified |
Country id |
|
siteId |
Long |
Yes - if countryId is not specified |
Site id |
|
postCode |
String |
Yes |
Postcode to validate |
|
Same as 2.8.2 ValidationResponse
This approach is used to validate post code, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/validation/postcode
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ValidatePostCodeRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
countryId | country_id |
Integer |
Yes - if siteId is not specified |
Country id |
|
siteId | site_id |
Long |
Yes - if countryId is not specified |
Site id |
|
postcode | postCode | post_code |
String |
Yes |
Postcode to validate |
|
Web service URL: BASE_URL/validation/phone
Method: POST
Content-type: application/json; charset=utf-8
This method validates phone number
ValidatePhoneRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
number |
String |
Yes |
Phone number |
|
ext |
String |
No |
Phone number extension |
|
Same as 2.8.2 ValidationResponse
This approach is used to validate phone, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/validation/phone
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ValidatePhoneRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
number |
String |
Yes |
Phone number |
|
ext |
String |
No |
Phone number extension |
|
Web service URL: BASE_URL/validation/shipment
Method: POST
Content-type: application/json; charset=utf-8
This method applies validation on shipment request
Input parameters:
ValidateShipmentRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
CreateShipmentRequest fields are here |
Same as 2.8.2 ValidationResponse
This approach is used to validate shipments, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/validation/shipment
Method: GET
Content-type: “application/x-www-form-urlencoded; charset=utf-8”
The response is the same as method using JSON schema.
URL parameters:
ValidateShipmentRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
CreateShipmentRequest params are here |
Web service URL: BASE_URL/services
Web service URL: BASE_URL/services
Method: POST
Content-type: application/json; charset=utf-8
Get available services for date
ServicesRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
date |
Date (yyyy-MM-dd) |
No |
Date. Current date is assumed if not provided |
|
ServicesResponse |
|||
Name |
Type |
Mandatory |
Data |
services |
Yes |
Available courier services |
|
error |
Error |
No |
Response error |
This approach is used to get services, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/services
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ServicesRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
date |
Date (yyyy-MM-dd) |
No |
Date. Current date is assumed if not provided |
|
Web service URL: BASE_URL/services/destination
Method: POST
Content-type: application/json; charset=utf-8
Get available services for date and destination
DestinationServicesRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
date |
Date (yyyy-MM-dd) |
No |
Date. Current date is assumed if not provided |
|
sender |
No |
Defines the pickup place. If not specified, the logged user client location is considered as a sender location. |
|
|
recipient |
Yes |
Defines the recipient delivery place. |
|
DestinationServicesResponse |
|||
Name |
Type |
Mandatory |
Data |
services |
Yes |
Available courier services for destination |
|
error |
Error |
No |
Response error |
This approach is used to get services for date and destination, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/services/destination
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
DestinationServicesRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
date |
Date (yyyy-MM-dd) |
No |
Date. Current date is assumed if not provided |
|
Calculation sender details If logged user is the sender, you may skip providing sender details at all. If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also. Otherwise, sender_id should stay empty and it is required to provide as a minimum:
|
||||
senderId | sender_id |
Long |
No |
Client id to refer а sender |
Validate for existence. |
senderPrivatePerson | sender_private_person |
Boolean (true/false, y/n, âyes/noâ - all case insensitive) |
If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory |
Sender private person flag. |
|
Sender Address Location Details See AddressLocation for more details. The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at senderâs address is expected. |
||||
senderAddressCountryId | sender_address_country_id |
Integer |
No |
Country ISO code. If not provided, the local country is assumed. Used for all address types. |
Validate for valid country code |
senderAddressStateId | sender_address_state_id |
String |
Required if country requires state |
Country state. Used for addresses of type 2 (foreign address). |
Validate for valid country state. |
senderAddressSiteId | sender_address_site_id |
Long |
Required, if country has full site nomenclature and pair (site_type, site_name) not provided |
Site id. Used for all address types |
Validate for valid site and value is required |
senderAddressSiteType | sender_address_site_type |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address) |
Max 20 characters |
senderAddressSiteName | sender_address_site_name |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types. |
Max 50 characters |
senderAddressPostcode | senderAddressPostCode | sender_address_postcode |
String |
Required if country requires post code |
Can be used in conjunction with countryId to find unique site. Used for all address types |
Max 10 characters |
dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId | senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id |
Integer |
Required, if the sender is an internal customer. If sender address is provided, it is forbidden. |
Drop off office id. |
Should refer to a valid accessible office |
Calculation recipient details If you refer an existing customer, provide client's id in recipient_id parameter and other recipient parameters may be skipped at all Otherwise, recipient_id should stay empty and it is required to provide as a minimum:.
|
||||
recipientId | recipient_id |
Long |
No |
Client id to refer а recipient |
Validate for existence. |
recipientPrivatePerson | recipient_private_person |
Boolean (true/false, y/n, âyes/noâ - all case insensitive) |
If recipient_id is provided, it is forbidden. Otherwise, it is mandatory |
Recipient private person flag. |
|
Recipient Address Location Details See AddressLocation for more details. The recipient address location is expected when recipient_id is empty and recipient_pickup_office_id is empty and not required. In other words, the recipient address location is required when the recipient is not a referred customer and delivery at recipientâs address is expected. |
||||
recipientAddressCountryId | recipient_address_country_id |
Integer |
No |
Country ISO code. If not provided, the local country is assumed. Used for all address types. |
Validate for valid country code |
recipientAddressStateId | recipient_address_state_id |
String |
Required if country requires state |
Country state. Used for addresses of type 2 (foreign address). |
Validate for valid country state. |
recipientAddressSiteId | recipient_address_site_id |
Long |
Required, if country has full site nomenclature and pair (site_type, site_name) not provided |
Site id. Used for all address types |
Validate for valid site and value is required |
recipientAddressSiteType | recipient_address_site_type |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address) |
Max 20 characters |
recipientAddressSiteName | recipient_address_site_name |
String |
Forbidden, if site id is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types. |
Max 50 characters |
recipientAddressPostcode | recipientAddressPostCode | recipient_address_postcode |
String |
Required if country requires post code |
Can be used in conjunction with countryId to find unique site. Used for all address types |
Max 10 characters |
pickupOfficeId | pickUpOfficeId | recipientPickupOfficeId | recipientPickUpOfficeId | pickup_office_id | recipient_pickup_office_id |
Integer |
Required, if the recipient is an internal customer. If recipient address is provided, it is forbidden. |
Pickup office id. |
Should refer to a valid accessible office |
Web service URL: BASE_URL/payments
Web service URL: BASE_URL/payments
Method: POST
Content-type: application/json; charset=utf-8
Get shipment payout details for a period
PayoutRequest |
||||
Name |
Type |
Required |
Data |
Constraints |
userName |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language |
String |
No |
|
|
clientSystemId |
Long |
No |
Client system id |
Validated against system register for external customers. |
fromDate |
DateTime (yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
Start of period date time. |
|
toDate |
DateTime (yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
End of period date time. |
|
includeDetails |
boolean |
No (default value is false) |
Include payout details flag |
|
PayoutResponse |
|||
Name |
Type |
Mandatory |
Data |
payouts |
Payout[] |
Yes |
Shipment payouts for a period |
error |
Error |
No |
Response error |
This approach is used to get shipment payouts, providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/payments
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
PayoutRequest |
||||
URL Parameter Name (synonyms are separated with |) |
Type |
Required |
Data |
Constraints |
userName | username | user_name |
String |
Yes |
User name |
|
password |
String |
Yes |
Password |
|
language | lang |
String |
No |
|
|
clientSystemId | client_system_id |
Long |
No |
Client system id |
Validated against system register for external customers. |
date_from |
Date (yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
Start of period date time. |
|
date_to |
Date (yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
End of period date time. |
|
include_details |
boolean (true/false, y/n, “yes/no” - all case insensitive) |
No (Default value is false) |
Flag to include payout details. |
|
Shipment service defines service level agreement for the shipment - when shipment should be picked up, service code to be used, sub-services, etc.
ShipmentService |
||||
Name |
Type |
Required |
Data |
Constraints |
pickupDate |
Date Example: “2017-11-21"
|
No (default value is today) |
The date for shipment pickup. |
Could be today or a future date. |
autoAdjustPickupDate |
Boolean |
No (default value is false) |
To find first available date for pickup starting from pickupDate according to pickup schedule for services |
|
serviceId |
int |
Yes |
Service to be used for the shipment. |
Service id (code) should be valid for the destination. |
additionalServices |
No |
Defines sub-services (like COD, Declared value, etc.) associated with the shipment. |
Sub-services may be allowed or forbidden for selected service and/or destination. |
|
deferredDays |
Integer |
No (default value is 0) |
This parameter allows users to specify by how many (business) days they would like to postpone the shipment delivery from the standard term.
|
Allowed values are 0, 1 and 2. |
saturdayDelivery |
Boolean |
No |
This parameter may adjust delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured delivery customer working schedule. |
|
Example:
{
"pickupDate":"2017-11-21",
"serviceId":2,
"additionalServices":{
"cod":{
"amount":100.0,
"currencyCode":"RON",
"payoutToThirdParty":false,
"processingType":"CASH",
"includeShippingPrice":false
},
"declaredValue":{
"amount":100.0,
"fragile":false
},
"fixedTimeDelivery": 1130,
"returns":{
"rod":{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"returnReceipt":{
"enabled":true,
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"swap":{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":1234567
},
"rop":{
"pallets":[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":602,
"parcelsCount":2
}
]
},
"returnVoucher":{
"serviceId":3,
"payer":"RECIPIENT"
}
},
"specialDeliveryId":2,
"deliveryToFloor":3
},
"deferredDays":2,
"saturdayDelivery":true
}
Allowance of additional services usage in the shipments is controlled and determined by the courier service configuration. All shipment additional services could be either:
Some of the additional services may require additional prerequisites (like valid contracts and annexes or serving offices in pickup or delivery site) to be available for usage.
ShipmentSubServices |
||||
Name |
Type |
Required |
Data |
Constraints |
cod |
|
No
|
Defines shipment COD sub-service. |
Seller could be required to have a valid contract and annex for COD for the destination. |
obpd |
|
No
|
Defines shipment options before payment details. |
|
declaredValue |
No |
Defines shipment declared value (extended liability) sub-service. |
|
|
fixedTimeDelivery |
Integer |
No |
This option fixes the time of delivery on the delivery date. 1130 - means 11:30 920 - means 09:20 |
This option is checked against the configured allowed time frame for the service. |
returns |
No
|
Defines a return sub-services.
|
Return shipments are verified for a return destination. |
|
specialDeliveryId |
Integer |
No |
Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex. |
Requires an annex for special delivery. |
deliveryToFloor |
Integer |
No |
Specifies the floor number in the building where to deliver the shipment. |
This sub-service requires an annex. |
Example JSON:
{
"cod":{
"amount":100.0,
"currencyCode":"RON",
"payoutToThirdParty":false,
"processingType":"CASH",
"includeShippingPrice":false
},
"declaredValue":{
"amount":100.0,
"fragile":false
},
"fixedTimeDelivery": 1130,
"returns":{
"rod":{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":66666666,
"thirdPartyPayer":false
},
"returnReceipt":{
"enabled":true,
"returnToClientId":66666666,
"thirdPartyPayer":false
},
"swap":{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":66666666
},
"rop":{
"pallets":[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":602,
"parcelsCount":2
}
]
},
"returnVoucher":{
"serviceId":3,
"payer":"RECIPIENT"
}
},
"specialDeliveryId":2,
"deliveryToFloor":3
},
"deferredDays":2,
"saturdayDelivery":true
}
Or simplest case (COD, with SWAP and ROD and disabled saturday delivery):
{
"cod":{
"amount":100.0,
},
"returns":{
"rod":{
"enabled":true,
},
"swap":{
"serviceId":3,
"parcelsCount":2,
},
}
},
"saturdayDelivery":false
}
ShipmentCODAdditionalService |
||||
Name |
Type |
Required |
Data |
Constraints |
amount |
double
|
Yes
|
Defines shipment COD base amount. |
Validated against the maximum allowed amounts for the destination. |
currencyCode |
String |
No (default is the currency code for destination country) |
Defines shipment COD currency code. |
Validated against the allowed currency code for destination country. |
processingType |
enum [“CASH”, “POSTAL_MONEY_TRANSFER”] |
No (default is “CASH”) |
Defines COD processing type. |
Appropriate contract and annexes may be required. |
payoutToThirdParty |
Boolean |
No |
If this flag is set, the COD is paid to third party (not to the sender). |
Requires a third party to be the payer of the courier service. |
payoutToLoggedClient |
Boolean |
No |
If this flag is set, the COD is paid to the logged client. |
|
includeShippingPrice |
Boolean |
No |
Flag indicating whether the shipping price should be included in the COD. |
|
cardPaymentForbidden |
Boolean |
No |
Flag indicating that COD/PMT card payment is forbidden. |
|
fiscalReceiptItems |
This feature depends on country regulations and must be enabled for client contract The value in amount field is ignored if fiscal receipt items are provided. |
List of items to issue fiscal receipt on behalf of client If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items. |
|
Example full JSON:
{
"amount":100.0,
"currencyCode":"RON",
"payoutToThirdParty":false,
"processingType":"CASH",
"includeShippingPrice":false
"cardPaymentForbidden":false
}
Or the simplest case:
{
"amount":100.0
}
COD fiscal receipt item is used to form COD fiscal receipt to be issued on behalf of client
ShipmentCODFiscalReceiptItem |
||||
Name |
Type |
Required |
Data |
Constraints |
description |
String
|
Yes
|
Fiscal receipt item description |
Max 50 characters |
vatGroup |
String |
Yes |
VAT group |
Must match one of available VAT groups (for example "А" - 0% VAT, "Б" - 20%VAT, ...). |
amount |
double |
Yes |
Item amount before VAT. |
Must be positive value |
amountWithVat |
double |
Yes |
Item amount with VAT included |
Must not be lower that amount before VAT |
ShipmentDeclaredValueAdditionalService |
||||
Name |
Type |
Required |
Data |
Constraints |
amount |
double
|
Yes
|
Defines shipment Declared Value base amount. Declared value amount is always in local system currency. |
Validated against the maximum allowed amounts. |
fragile |
Boolean |
No |
Defines fragile flag for shipment content. |
Fragile shipments require a declared value sub service. |
ignoreIfNotApplicable |
Boolean |
No (Used in calculation service only, ignored in create shipment service) |
Flag to ignore declared value additional service in case it is not applicable for shipment on calculation |
E-shops usually configure declared value (extended liability) by default for their shipments, However there are some certain internal rules when this option is not available. The flag is used in calculation service to provide price to end clients without repeating the calculation request with removed additional service |
Example JSON:
{
"amount":100.0,
"fragile":false
}
Or using defaults you can specify 100.00 base amount non-fragile shipment with courier service payer with just:
{
"amount":100.0
}
Defines series of return sub-services, which require a reverse shipment to be generated at primary shipment delivery. All the reverse shipments are validated for allowance and for destination.
ShipmentReturnAdditionalServices |
||||
Name |
Type |
Required |
Data |
Constraints |
rod |
|
No |
Defines Return Of Documents (ROD) sub-service. |
The reverse shipment is validated for service and destination. |
returnReceipt |
No |
Defines Return Receipt sub-service. Cannot be specified if electronicReturnReceipt is provided |
The reverse shipment is validated for service and destination. |
|
electronicReturnReceipt |
No |
Defines electronic Return Receipt sub-service (return receipt by email). Cannot be specified if returnReceipt is provided |
Electronic return receipt requires email. |
|
swap |
No
|
Defines SWAP sub-service. |
The reverse shipment is validated for service and destination. |
|
rop |
No |
Defines Return Of Pallets (ROP) sub-service. |
The reverse shipment is validated for service and destination. |
|
returnVoucher |
No |
Defines Return Voucher associated with the shipment. |
The reverse shipment is validated for service and destination. |
|
sendBackClientId |
Long |
No |
Client id to specify send back address in case of a shipment return. Used in shipment returns after Check/Test or in case recipient is not found. If not specified the shipment is returned to the primary shipment sender. |
Should be a customer address (object) in the same contract as the sender of the shipment. |
Example JSON:
{
"rod":{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"returnReceipt":{
"enabled":true,
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"swap":{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":1234567
},
"rop":{
"pallets":[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":602,
"parcelsCount":2
}
]
},
"returnVoucher":{
"serviceId":3,
"payer":"RECIPIENT"
}
}
Or a simpler scenario (ROD, Return Receipt and SWAP):
{
"rod":{
"enabled":true
},
"returnReceipt":{
"enabled":true
},
"swap":{
"serviceId":3,
"parcelsCount":2
}
}
Return of Documents (ROD) additional service requires documents to be returned upon the delivery of the primary shipment.
ShipmentRODAdditionalService |
||||
Name |
Type |
Required |
Data |
Constraints |
enabled |
boolean
|
Yes
|
Enabled flag |
|
comment |
String |
No |
Return documents comment. |
Max size 512 |
returnToClientId |
Long |
No |
Defines the recipient for the ROD shipment. If not specified and returnToOfficeId is not specified also, the reverse shipment is returned to the primary shipment sender. |
Cannot be specified together with returnToOfficeId. The same value should be set for ROD and Return Receipt, if the sub-service presents. Cannot be specified if SWAP presents |
returnToOfficeId |
Integer |
No |
Defines delivery pickup depot for the ROD shipment. If not specified and returnToClientId is not specified also, the reverse shipment is returned to the primary shipment sender. |
Cannot be specified together with returnToClientId. The same value should be set for ROD, Return Receipt and SWAP, if the sub-service presents. |
thirdPartyPayer |
Boolean |
No |
Defines a third party payer for the ROD shipment. Otherwise the payer is the primary shipment sender. |
Requires a third party payer of the primary shipment. The same value should be set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents. |
Example JSON:
{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":12345678,
"thirdPartyPayer": false
}
Or with default values:
{
"enabled":true
}
Return Receipt additional service requires receipt to be returned upon the delivery of the primary shipment.
See also Electronic Return Receipt
ShipmentReturnReceiptAdditionalService |
||||
Name |
Type |
Required |
Data |
Constraints |
enabled |
boolean
|
Yes
|
Enabled flag |
|
returnToClientId |
Long |
No |
Defines the recipient for the Return Receipt shipment. If not specified and returnToOfficeId is not specified also, the reverse shipment is returned to the primary shipment sender. |
Cannot be specified together with returnToOfficeId. The same values should be set for ROD and Return Receipt, if the sub service presents. Cannot be specified if SWAP presents
|
returnToOfficeId |
Integer |
No |
Defines delivery pickup depot for the Return Receipt shipment. If not specified and returnToClientId is not specified also, the reverse shipment is returned to the primary shipment sender. |
Cannot be specified together with returnToClientId. The same values should be set for ROD, Return Receipt and SWAP, if the sub service presents.
|
thirdPartyPayer |
Boolean |
No |
Defines a third party payer for the Return Receipt. Otherwise the payer is the primary shipment sender. |
Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt / Electronic Return Receipt, ROP and SWAP, if the sub service presents. |
Example JSON:
{
"enabled":true,
"returnToClientId":12345678,
"thirdPartyPayer": false
}
Or with default values:
{
"enabled":true
}
SWAP additional service requires shipment with predefined parameters to be returned upon the delivery of the primary shipment.
ShipmentSWAPAdditionalService |
||||
Name |
Type |
Required |
Data |
Constraints |
serviceId |
int
|
Yes
|
Service to be used in return. |
Validated for allowance and destination. |
parcelsCount |
int |
Yes |
Number of parcels to return. |
Validated against maximum allowed parcels. |
declaredValue |
Double |
No |
Declared value (extended liability) for the reverse shipment. |
Validated for allowance and maximum amount. |
fragile |
Boolean |
No |
Fragile content flag for the reverse shipment. |
Fragile shipments require declared value. |
returnToOfficeId |
Integer |
No |
Defines delivery pickup depot for the SWAP shipment. If not specified, the reverse shipment is returned to the primary shipment sender. |
The same values should be set for ROD, Return Receipt and SWAP, if the sub-service presents.
|
thirdPartyPayer |
Boolean |
No |
Defines a third party payer for the SWAP shipment. Otherwise the payer is the primary shipment recipient. |
Requires a third party payer of the primary shipment. The same value should be set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents. |
Example JSON:
{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":12345678
}
Or with default values:
{
"serviceId":3,
"parcelsCount":2
}
Return Of Pallets additional service requires shipment with predefined parameters to be returned upon the delivery of the primary shipment.
ShipmentROPAdditionalService |
||||
Name |
Type |
Required |
Data |
Constraints |
pallets |
ShipmentROPAdditionalServiceLine[]
|
Yes
|
Defines pallets to return grouped by service id. |
Total number of returned pallets should not exceed the parcel count of the primary shipment. |
thirdPartyPayer |
Boolean |
No |
Defines a third party payer for the returned pallets. Otherwise the payer is the primary shipment sender. |
Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt / Electronic Return Receipt, ROP and SWAP, if the sub service presents. |
Example JSON:
[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":2605,
"parcelsCount":2
}
]
Return Of Pallet (ROP) sub service lines define for each return of pallet service how many parcels (pallets) should be returned.
ShipmentROPAdditionalServiceLine |
||||
Name |
Type |
Required |
Data |
Constraints |
serviceId |
int
|
Yes
|
ROP service to be used. |
Validated against destination. |
parcelsCount |
int |
Yes |
Number of parcels to return. |
|
Example JSON:
{
"serviceId":601,
"parcelsCount":3
}
Return Voucher sub service provides an option to the recipient to initiate a return within predefined voucher validity period, using the voucher preferences.
ShipmentReturnVoucherSubService |
||||
Name |
Type |
Required |
Data |
Constraints |
serviceId |
int
|
Yes
|
Service id of the return shipment. |
|
payer |
enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ] |
Yes
|
Defines a return voucher payer. |
Allowed payers are validated against the service configuration and destination. |
validityPeriod |
Integer |
Required if caller client has no annex for return voucher. |
Return voucher validity period in days. The annex return voucher period is used by default in case caller client has such in his contract and value is omitted |
Verified to not exceed the configured internal maximum in the system |
Example JSON:
{
"serviceId":3,
"payer":"RECIPIENT"
}
Electronic Return Receipt additional service requires receipt to be returned as an email attachment upon the delivery of the shipment
ShipmentElectronicReturnReceiptAdditionalService |
||||
Name |
Type |
Required |
Data |
Constraints |
recipientEmails |
String[]
|
Yes
|
List of electronic return receipt recipient emails |
|
thirdPartyPayer |
Boolean |
No |
Defines a third party payer for the Electronic Return Receipt. Otherwise the payer is the primary shipment sender. |
Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt / Electronic Return Receipt, ROP and SWAP, if the sub service presents. |
ShipmentOBPD |
||||
Name |
Type |
Required |
Data |
Constraints |
option |
enum [“OPEN”, “TEST”]
|
Yes
|
Defines the option to be used. Open parcels on payment or open and test parcels before payment. |
|
returnShipmentServiceId |
Integer |
Yes |
Defines service id to be used on return. |
|
returnShipmentPayer |
enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”] |
Yes |
Defines who pays the return shipment. |
|
Example JSON:
{
"option":"TEST",
"returnShipmentServiceId":2,
"returnShipmentPayer":"SENDER"
}
Shipment content is used to describe what is to be delivered with the shipment.
ShipmentContent |
||||
Name |
Type |
Required |
Data |
Constraints |
parcelsCount |
Integer
|
Required when parcels list is empty.
|
Total shipment parcels count. Ignored, if parcels list is not empty. The parcels count is the number of parcels in the lits in that case. |
Validated against the minimum and maximum allowed for the service. |
totalWeight |
Double |
Required when parcels list is empty. |
Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcels declaredWeight in that case. |
Validated against the minimum and maximum allowed for the service. |
contents |
String |
Yes |
Shipment content’s description. |
100 |
package |
String |
Yes |
Shipment package. |
50 |
documents |
Boolean |
No |
Documents flag of the shipment. |
|
palletized |
Boolean |
No |
Palletized flag of the shipment. |
|
parcels |
Required for pallet and postal services. |
Parcels. If omitted a single default (first) parcel will be created for non-pallet and non-postal services. |
Validated against the service configuration and pickup and delivery capacity of the depots and couriers. |
|
pendingParcels |
Boolean |
No |
If this flag is true, the shipment is created in pending parcels state. Shipments in pending parcels state allows adding parcels with addParcel method. Pending parcels state is closed with finalizePendingShipment method. |
|
exciseGoods |
Boolean |
No |
Flag shipment contains excise goods. |
|
lq |
Boolean |
No |
Flag shipment contains dangerous goods in limited quantities. |
|
goodsValue |
Double |
No Required for pallet services (for Romanian shipments) |
Defines shipment goods value amount. |
Validated against maximum allowed amount. |
goodsValueCurrencyCode |
String |
No Required, if goodsValue is provided. |
Defines shipment goods value currency code. |
Requires a valid currency code. |
uitCode |
String |
No Required for Romanian shipments in cases defined by Romanian regulations. |
Shipment UIT code. |
Requires a valid UIT code. |
Example JSON:
{
"contents":"FURNITURE",
"package":"BOX",
"documents":false,
"palletized":false,
"parcels":[
{
"seqNo":1,
"size":{
"width":80,
"depth":120,
"height":110
},
"weight":80.0,
"externalCarrierParcelNumber":"1726912312312313"
},
{
"seqNo":2,
"size":{
"width":80,
"depth":122,
"height":100
},
"weight":83.0,
"externalCarrierParcelNumber":"1726912312312315"
},
{
"seqNo":3,
"size":{
"width":83,
"depth":125,
"height":116
},
"weight":85.0,
"externalCarrierParcelNumber":"1726912312312314"
}
],
"pendingParcels":false
}
Or:
{
"contents":"FURNITURE",
"package":"BOX",
"parcels":[
{
"seqNo":1,
"weight":80.0
},
{
"seqNo":2,
"weight":83.0
},
{
"seqNo":3,
"weight":85.0
}
]
}
Or (for non-pallet and non-postal services):
{
"parcelsCount":3,
"totalWeight":248.0,
"contents":"FURNITURE",
"package":"BOX"
}
Shipment parcel data structure.
ShipmentParcel |
||||
Name |
Type |
Required |
Data |
Constraints |
id |
String
|
No
|
Parcel identifier - barcode (if it is known). |
|
seqNo |
Integer |
Required in createShipment method. Ignored in addParcel (auto-generated in this case) |
Parcel sequence number in the shipment. |
Should be unique for the shipment. |
packageUniqueNumber |
Long |
No |
Package number associated with parcel. |
|
size |
Required for pallet and postal services. |
Parcel size (width, height, depth) in cm. |
Validated against the capacity of the couriers and depots. Used to calculate the volume weight, if applicable. |
|
weight |
double |
Yes |
Parcel weight in kg. |
Validated against the capacity of the couriers and depots and service configuration. |
ref1 |
String |
No |
Reference number or text. |
20 |
ref2 |
String |
No |
Reference number or text. |
20 |
pickupExternalCarrierParcelNumber |
No |
External carrier parcel id for pickup |
|
|
deliveryExternalCarrierParcelNumber |
No |
External carrier parcel id for delivery |
|
The declared weight of a parcel (used for price calculation) is the maximum of the weight and the volume weight (calculated from size). Volume weight in some cases is not calculated (for example for pallets).
Example JSON:
{
"seqNo":1,
"size":{
"width":80,
"depth":120,
"height":110
},
"weight":80.0
}
Or:
{
"seqNo":1,
"weight":80.0
}
Shipment parcel size structure defines parcel size in the shipment.
ShipmentParcelSize |
||||
Name |
Type |
Required |
Data |
Constraints |
width |
int |
Yes |
Parcel width |
|
depth |
int |
Yes |
Parcel depth |
|
height |
int |
Yes |
Parcel height |
|
Example JSON:
{
"width":80,
"depth":120,
"height":100
}
Parcel number from external carrier linked to local shipment parcel
ExternalCarrierParcelNumber |
||||
Name |
Type |
Required |
Data |
Constraints |
externalCarrier |
enum [“ACS”] |
Yes |
External carrier reference name |
|
parcelNumber |
String |
Yes |
External carrier parcel number |
|
Shipment payment structure defines who-pays-what in the shipment.
ShipmentPayment |
||||
Name |
Type |
Required |
Data |
Constraints |
courierServicePayer |
enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ] |
Yes
|
Courier service payer. |
Validated against the service, destination, contracts and annexes. |
declaredValuePayer |
enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ] |
No |
Declared value (extended liability) payer. If not provided, the courier service payer is assumed. |
Validated against the service, destination, contracts and annexes. |
packagePayer |
enum [ "SENDER", "RECIPIENT", "THIRD_PARTY" ] |
No |
Package payer. If not provided, the courier service payer is assumed. |
Validated against the service, destination, contracts and annexes. |
thirdPartyClientId |
Long |
No |
Defines shipment third party - used as a payer of any of shipment payable components. |
Third party customer should be a registered customer with valid contract and annex for delayed payment at pickup date. The third party customer should be a customer (object) in the same contract as the logged user. |
discountCardId |
No |
Discount card to be used for discount calculation. |
Validated against a referred contract. |
|
senderBankAccount |
No |
Sender COD payout account information. |
Valid IBAN should be present if bank account is provided. |
|
administrativeFee |
Boolean |
No |
Flag to apply administrative fee on price calculations |
Usage of administrative fee is enabled and configured in client contract. Ignored if not applicable for user |
Example JSON:
{
"courierServicePayer":"SENDER",
"declaredValuePayer":"THIRD_PARTY",
"packagePayer":"RECIPIENT",
"thirdPartyClientId":1234567,
"discountCardId":{
"contractId":666666,
"cardId":3
}
}
Or, if the sender pays everything, then the JSON below is enough:
{
"courierServicePayer":"SENDER"
}
Discount cards provide promotional discounts.
ShipmentDiscountCardId |
||||
Name |
Type |
Required |
Data |
Constraints |
contractId |
long |
Yes
|
Fixed discount card contract id. |
Validated against the accessible contract. |
cardId |
long |
Yes |
Fixed discount card id. |
Validated against the fixed discount card register. |
Example JSON:
{
"contractId":12345678,
"cardId":3
}
Bank account information.
BankAccount |
||||
Name |
Type |
Required |
Data |
Constraints |
iban |
String |
Yes
|
IBAN. |
Validated according to IBAN standards. |
accountHolder |
String |
Yes |
Bank account holder. |
|
Example JSON:
{
"iban":"BG80BNBG96611020345678",
"accountHolder":"Todor Penev"
}
Shipment sender is not mandatory. If not specified, for the sender is considered the logged user.
ShipmentSender |
||||
Name |
Type |
Required |
Data |
Constraints |
clientId |
Long |
No
|
Client id to refer a sender. |
Validate for existence. |
phone1 |
Yes |
Sender phone number (for example: +40799123456, 0040799123456, +359999123456 - international format numbers or 0799123456, 0999123456 - local numers). |
Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. Only phone numbers starting with "0" (zero) or "+" sign are allowed. |
|
phone2 |
No |
Sender phone number 2. |
Validate for valid phone number, if presents. |
|
phone3 |
No |
Sender phone number 3. |
Validate for valid phone number, if presents. |
|
clientName |
String |
If clientId is provided, it is forbidden. Otherwise, it is mandatory. |
Sender customer name. |
Validate for valid name (minimum 3 symbols, maximum 60). |
contactName |
String |
No Forbidden for private persons. Required for companies. |
Sender contact name. |
Maximum 60 |
|
String |
No |
Sender email. |
Maximum 255 |
privatePerson |
Boolean |
If clientId is provided, it is forbidden. Otherwise, it is mandatory. |
Sender private person flag. |
|
address |
If clientId is provided or dropoff office is provided, it is forbidden. Otherwise, it is mandatory. |
Sender address. |
Validated for valid values. |
|
dropoffOfficeId |
Integer |
Required, if the sender is an internal customer. If the address is provided, it is forbidden. |
Drop off office id. |
Should refer to a valid accessible office. |
dropoffGeoPUDOId |
String |
No. Must be empty if dropoffOfficeId is provided |
DPD drop off office PUDO id |
Should refer to a valid accessible DPD office. |
Example JSON:
{
"clientId":90909090909,
"phone1":{
"number":"08888123123"
},
"phone2":{
"number":"08888123153",
"extension":"321"
},
"clientName":"CLIENT NAME",
"objectName":"OBJECT NAME",
"contactName":"CONTACT NAME",
"email":"[email protected]",
"privatePerson":false,
"address":{
"countryId":100,
"siteId":68314,
"streetType":"bul.",
"streetName":"VITOSKA",
"streetNo":"55"
}
}
Or:
{
"clientId":90909090909,
"phone1":{
"number":"08888123123"
},
"contactName":"CONTACT NAME",
"email":"[email protected]"
}
ShipmentRecipient |
||||
Name |
Type |
Required |
Data |
Constraints |
clientId |
Long |
No
|
Client id to refer recipient. |
Validate for existence. |
phone1 |
Required, if shipment is with the same day delivery or delivery date is a half-working day or delivery country is abroad. |
Recipient phone number (for example: +40799123456, 0040799123456, +359999123456 - international format numbers or 0799123456, 0999123456 - local numers). |
Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. Only phone numbers starting with "0" (zero) or "+" sign are allowed. |
|
phone2 |
No |
Recipient phone number 2. |
Validate for valid phone number, if presents. |
|
phone3 |
No |
Recipient phone number 3. |
Validate for valid phone number, if presents. |
|
clientName |
String |
If clientId is provided, it is forbidden. Otherwise, it is mandatory. |
Recipient customer name. |
Validate for valid name (minmum 3 simbols, maximum 60). |
objectName |
String |
If clientId is provided, it is forbidden. Otherwise, it is not mandatory. |
Recipient customer object. |
Validate for valid name (maximum 60 symbols). |
contactName |
String |
No. Forbidden for private persons. Required for companies. |
Recipient contact name. |
Maximum 60 |
|
String |
No |
Recipient email |
Maximum 255. Mandatory for international shipments |
privatePerson |
Boolean |
If clientId is provided, it is forbidden. Otherwise, it is mandatory. |
Recipient private person flag. |
|
address |
If clientId is provided or pickup office is provided, it is forbidden. Otherwise, it is mandatory. |
Recipient address. |
Validated for valid values. |
|
pickupOfficeId |
Integer |
Required, if the recipient is an internal customer. If address is provided, it is forbidden. |
Pickup office id. |
Should refer to a valid accessible office. |
pickupGeoPUDOId |
String |
No. Must be empty if pickupOfficeId is provided |
DPD pickup office PUDO id |
Should refer to a valid accessible DPD office. |
autoSelectNearestOffice |
boolean |
No |
Not supported for every destination country |
Must be supported for destination country |
autoSelectNearestOfficePolicy |
No |
Defines policy for nearest office auto selection. By default the system tries to find nearest office and if office cannot be determined the shipment is delivered to client address |
Applicable if autoSelectNearestOffice is true |
Example JSON:
{
"phone1":{
"number":"0888813323"
},
"clientName":"RCPT NAME",
"objectName":"RCPT OBJ NAME",
"contactName":"RCPT CONTACT NAME",
"email":"[email protected]",
"privatePerson":true,
"pickupOfficeId":33
}
Or:
{
"clientId":90909090909,
"phone1":{
"number":"0888813323"
},
"contactName":"RCPT CONTACT NAME",
"pickupOfficeId":33
}
This structure is used to provide addresses. Addresses are two types:
Address type 1 supports the following requisites:
Address type 2 supports the following requisites:
ShipmentAddress |
||||
Name |
Type |
Required |
Data |
Constraints |
countryId |
Integer |
No
|
Country ISO code. If not provided, local country is assumed. Used for all address types. |
Validate for valid country code. |
stateId |
String |
Required, if country supports states. |
Country state. Used for addresses of type 2 (foreign address).
|
Validate for valid country state. |
siteId |
Long |
Required, if country has full site nomenclature and pair (siteType, siteName) is not provided. |
Site id. Used for all address types.
|
Validate for valid site and value is required. |
siteType |
String |
Forbidden, if siteId is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with countryId and siteName to find unique site. Used for addresses of type 1 (local address). |
Max 20 |
siteName |
String |
Forbidden, if siteId is provided. Otherwise, is not mandatory. |
Site type can be used in conjunction with countryId and siteName to find unique site. Used for all address types. |
Max 50 |
postCode |
String |
No |
Can be used in conjunction with countryId to find unique site Used for all address types. |
Validated for valid postcode in site and country. Max 10 |
streetId |
Long |
No |
Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address). |
Validate for valid street. |
streetType |
String |
No. Forbidden, if streetId is provided. |
Street type. Used for addresses of type 1 (local address). |
Max 15 |
streetName |
String |
No. Forbidden, if streetId is provided. |
Street name. Used for addresses of type 1 (local address). |
Max 50 |
streetNo |
String |
No |
Street number. Used for addresses of type 1 (local address). |
Max 10 |
complexId |
Long |
No |
Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site. Used for addresses of type 1 (local address). |
Validate for valid complex. |
complexType |
String |
No. Forbidden, if complexId is provided. |
Complex type. Used for addresses of type 1 (local address). |
Max 15 |
complexName |
String |
No. Forbidden, if complexId is provided. |
Complex name. Used for addresses of type 1 (local address). |
Max 50 |
blockNo |
String |
No |
Block No. Used for addresses of type 1 (local address). |
Max 32 |
entranceNo |
String |
No |
Entrance. Used for addresses of type 1 (local address). |
Max 10 |
floorNo |
String |
No |
Floor. Used for addresses of type 1 (local address). |
Max 10 |
apartmentNo |
String |
No |
Apartment. Used for addresses of type 1 (local address). |
Max 10 |
poiId |
Long |
No |
Point of interest identifier. Used for addresses of type 1 (local address). |
Validate for valid point of interest. |
addressNote |
String |
No |
Address note. Used for addresses of type 1 (local address). |
200 |
addressLine1 |
String |
Required for address type 2. |
Address line 1. Used for addresses of type 2 (foreign address). |
Max 35 |
addressLine2 |
String |
No |
Address line 2. Used for addresses of type 2 (foreign address). |
Max 35 |
x |
Double |
No |
GIS coordinates - X. Used for all address types.
|
|
y |
Double |
No |
GIS coordinates - Y. Used for all address types.
|
|
For address type 1, special validation rule is applied:
Example JSON address:
{
"countryId":100,
"siteId":68314,
"streetType":"bul.",
"streetName":"VITOSHA",
"streetNo":"55"
}
This structure extends Shipment Address structure with additional fields for address represntation.
This structure is returned in responses.
Address |
||||
Name |
Type |
Required |
Data |
Constraints |
ShipmentAddress fields are here |
||||
fullAddressString |
String |
Yes
|
Full address in a single text field |
|
siteAddressString |
String |
Yes |
The address site description in a single text |
|
localAddressString |
String |
Yes |
The address within the site in a single text |
|
This structure is used to provide phone numbers.
ShipmentPhoneNumber |
||||
Name |
Type |
Required |
Data |
Constraints |
number |
String |
Yes
|
Phone number. |
Validate for valid phone number. |
extension |
String |
No |
Extension. |
Validate for valid extension, if presents. |
Example JSON:
{
"number":"0888813323",
"extension":"123"
}
Or just:
{
"number":"0888813323"
}
This structure is used to define policy for nearest office auto selection. By default the system tries to find nearest office and if office cannot be determined the shipment is delivered to client address
AutoSelectNearestOfficePolicy |
||||
Name |
Type |
Required |
Data |
Constraints |
unavailableNearestOfficeAction |
enum [“DELIVERY_TO_ADDRESS”, “CANCEL_WITH_ERROR”] |
No Default is “DELIVERY_TO_ADDRESS” |
The action to take if nearest office is unavailable. Values can be:
|
|
officeType |
enum [“OFFICE”, “APT”] |
No |
Office type filter. Values can be:
No office filter selection is applied if value is not specified |
Not supported for every destination country |
Shipment parcel reference is returned in response of the create shipment request, it describes the generated parcel and references to it.
CreatedShipmentParcel |
|||
Name |
Type |
Mandatory |
Data |
seqNo |
int |
Yes |
Sequence number within the shipment. |
id |
String |
Yes |
Generated parcel id. |
externalCarrierId |
Integer |
No |
External carrier id in case this parcel is mapped to an external carrier system |
externalCarrierParcelNumber |
String |
No |
External carrier parcel number in case this parcel is mapped to an external carrier system |
Example JSON:
{
"id":"80002188603",
"seqNo":1
}
ShipmentParcelRef |
||||
Name |
Type |
Mandatory |
Data |
Constraint |
id |
String |
No If externalCarrierParcelNumber is not provided, it is mandatory. |
Parcel id |
|
externalCarrierParcelNumber |
String |
No |
External carrier parcel number used to create parcels. |
|
fullBarcode |
String |
No |
No If id or externalCarrierParcelNumber is not provided, it is mandatory. |
|
Example JSON:
{
"id":"80002188603"
}
Or:
{
"externalCarrierParcelNumber":"7125912312312312313"
}
Or:
{
"fullBarcode":"1000509431237540020002030017"
}
This structure extends ShipmentParcelRef structure with additional fields.
ParcelHandover |
||||
Name |
Type |
Mandatory |
Data |
Constraint |
dateTime |
DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
Datetime for hadover operation |
|
ShipmentParcelRef fields are here |
TrackShipmentParcelRef |
||||
Name |
Type |
Mandatory |
Data |
Constraint |
ref |
String |
No |
Reference to parcel or shipment. |
If externalCarrierParcelNumber or parcelId is provided, it is ignored. Since the reference is not unique, the maximum barcodes to include for tracking is limited to 10 per reference in request. |
ShipmentParcelRef fields are here |
MidwayCarrierParcelHandover |
||||
Name |
Type |
Mandatory |
Data |
Constraint |
id |
String |
Yes |
Parcel id |
|
countryId |
Long |
Yes |
Country ISO id |
|
dateTime |
DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
Datetime for hadover operation |
|
siteName |
String |
No |
Site name |
|
Shipment price structure is returned in response of the calculations or create shipment requests.
ShipmentPrice |
|||
Name |
Type |
Mandatory |
Data |
amount |
double |
Yes |
Total amount (before VAT) in customer’s currency. |
vat |
double |
Yes |
VAT amount in customer’s currency. |
total |
double |
Yes |
Total amount (amount + vat) in customer’s currency. |
currency |
String |
Yes |
Customer currency code. |
details |
Map<String, ShipmentPriceAmount> |
Yes |
Amounts that form totals in customer’s currency (including net, discounts, surcharges). Keys in the map are the titles of the items included in the receipt. |
amountLocal |
double |
Yes |
Total amount before VAT in local system currency. |
vatLocal |
double |
Yes |
VAT in local system currency. |
totalLocal |
double |
Yes |
Total amount in local system currency (amountLocal + vatLocal). |
currencyLocal |
String |
Yes |
Local system currency code. |
detailsLocal |
Map<String, ShipmentPriceAmount> |
Yes |
Amounts that form totals in local system currency (including net, discounts, surcharges). Keys in the map are the titles of the items included in the receipt. |
currencyExchangeRateUnit |
int |
Yes |
Currency exchange rate unit for customer currency (1 unit of local system currency is equal to exchangeRateUnit / exchangeRate). |
currencyExchangeRate |
double |
Yes |
Currency exchange rate used for customer currency conversion. |
returnAmounts |
No |
Shipment returns amounts due |
Example JSON:
{
"amount":37.81,
"vat":7.18,
"total":44.99,
"currency":"RON",
"receipt":{
"netAmount":{
"amount":37.81,
"vatPercent":19.0
},
"fixedDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"dropoffDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"pickupDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"additionalDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"fuelSurcharge":{
"amount":0.0,
"percent":0.0,
"vatPercent":19.0
},
"zoneSurcharge":{
"amount":0.0,
"vatPercent":19.0
},
"codCommission":{
"amount":0.0,
"vatPercent":19.0
},
"declaredValueSurcharge":{
"amount":0.0,
"vatPercent":19.0
}
},
"amountLocal":37.81,
"vatLocal":7.18,
"totalLocal":44.99,
"currencyLocal":"RON",
"receiptLocal":{
"netAmount":{
"amount":37.81,
"vatPercent":19.0
},
"fixedDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"dropoffDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"pickupDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"additionalDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"fuelSurcharge":{
"amount":0.0,
"percent":0.0,
"vatPercent":19.0
},
"zoneSurcharge":{
"amount":0.0,
"vatPercent":19.0
},
"codCommission":{
"amount":0.0,
"vatPercent":19.0
},
"declaredValueSurcharge":{
"amount":0.0,
"vatPercent":19.0
}
},
"currencyExchangeRateUnit":1,
"currencyExchangeRate":1.0
}
Shipment price amount is returned as a part of receipts in calculation responses.
ShipmentPriceAmount |
|||
Name |
Type |
Mandatory |
Data |
amount |
double |
Yes |
Shipment price amount. Discounts are negative. Surcharges and net amount are positive. |
percent |
Double |
No |
Percent field is returned, if there is a percent associated with the amount. Fixed price amounts do not have a percent value. 20% is returned as 0.2. |
vatPercent |
double |
Yes |
VAT percent applicable to the amount. Amounts without VAT have 0.0 value in that field. Amounts with 20% VAT have 0.2 value in that field. |
Example JSON:
{
"amount":13.45,
"percent":0.4,
"vatPercent":0.19
}
Or for fixed amount:
{
"amount":12.00,
"vatPercent":0.20
}
Shipment price return amounts represents return services due amounts.
ReturnAmounts |
|||
Name |
Type |
Mandatory |
Data |
moneyTransfer |
No |
Shipment money transfer premium. |
Money transfer premium amount due.
MoneyTransferPremium |
|||
Name |
Type |
Mandatory |
Data |
amount |
Double |
No |
Amount due in client currency |
amountLocal |
Double |
No |
Amount due in local currency |
payer |
enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”] |
No |
The payer of money transfer premium |
Errors are returned in responses.
Error |
|||
Name |
Type |
Mandatory |
Data |
context |
String |
No |
Message context, if associated. This refers to an item that is wrong and should be corrected. |
message |
String |
Yes |
Error message in language specified in the request. |
id |
String |
Yes |
System generated unique error id to be used as this error reference. |
code |
int |
Yes |
Error code. See Appendix 3 - Error Codes for more details. |
component |
String |
No |
The request component, if applicable, relevant to this error in JSONPath format with dot notation. (For example $.sender.address.siteId refers to siteId property in sender address.) |
Example JSON:
{
"context":”sender.address.siteId”,
"message":”Value is required”
}
ParcelToPrint |
|
|||
Name |
Type |
Mandatory |
Data |
Constraints |
parcel |
Yes |
Parcel reference. |
|
|
additionalBarcode |
No |
Additional barcode to be added in the label. |
Available for A6 paper size only. Otherwise, ignored. |
Example JSON:
{
"parcel": {
"Id":"80002188603"
},
"additionalBarcode": {
"value":"123456789104",
"label":"123456789104",
"format":"CODE128"
}
}
Or just:
{
"parcel": {
"Id":"80002188603"
}
}
Additional barcode information to print in the label is provided in this structure.
ParcelToPrintAdditionalBarcode |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
value |
String |
.Yes |
Barcode value. |
For barcode formats other than 'CODE128' it must contain digits only. |
label |
String |
No |
It is printed just below the barcode image. |
For barcode formats other than 'CODE128' label must be equal to the value.
|
format |
enum [“CODE128”, “EAN13”, “EAN8”, “UPCA”, “UPCE”]
|
Yes |
Additional barcode format. |
|
Example JSON:
{
"value":"123456789104",
"label":"123456789104",
"format":"CODE128"
}
Print label information.
LabelInfo |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
parcelId |
String |
Yes |
Parcel id. |
|
hubId |
Integer |
No |
Delivery Hub id. |
|
officeId |
Integer |
No |
Delivery Office id. |
|
officeName |
String |
No |
Delivery Office name. |
|
deadlineDay |
Integer |
No |
Delivery deadline day of month. |
|
deadlineMonth |
Integer |
No |
Delivery deadline month . |
|
tourId |
Integer |
No |
Tour Id. |
|
fullBarcode |
String |
Yes |
Barcode containing the parcel number and important routing information. |
|
exportPriority |
Integer |
Yes |
Export priority |
|
Example JSON:
{
"parcelId": "50943123754",
"hubId": 2,
"officeId": 2,
"deadlineDay": 18,
"deadlineMonth": 2,
"tourId": 2203,
"fullBarcode": "1000509431237540020002030017"
}
Track parcel information.
TrackedParcel |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
parcelId |
String |
Yes |
Parcel id. |
|
externalCarrierParcelNumbers |
String[] |
No |
The list of all external carrier parcel numbers associated with the parcel. |
|
operations |
Yes |
The list of operations (scans). |
|
|
externalCarrierParcelNumbersDetails |
Map<String, ExternalCarrierParcelNumberDetails> |
No |
Map of external carrier parcel details. Keys in the map are external carrier parcel numbers. |
|
error |
No |
Error for this parcel. |
|
TrackedParcelOperation |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
dateTime |
Date (datetime) |
Yes |
Operation date time. |
|
operationCode |
int |
Yes |
Operation code. See Appendix1 for reference. |
|
place |
String |
No |
Place of operation. |
|
description |
String |
Yes |
Operation description. |
|
comment |
String |
No |
Operation comment. |
|
exceptionCodes |
String[] |
No |
List of exception codes for this operation. See Appendix2 for references. |
|
returnShipmentId |
String |
No |
If operation leads to return - the return shipment id is in this field. |
|
redirectShipmentId |
String |
No |
If operation leads to redirect - the redirected shipment id is in this field. |
|
consignee |
String |
No |
If operation leads to delivery - the recipient name is in this field. |
|
podImageURL |
String |
No |
If operation leads to pod capture - the pod image URL is in this field. |
|
additionalInfo |
No |
Additional information for operation |
|
TrackedParcelOperationAdditionalInfo |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
officeURL |
String |
No |
Pickup office URL (applicable for operation 134) |
|
geoPUDOId |
String |
No |
Pickup office PUDO id in case pickup office is a DPD office (applicable for operation 134) |
|
predict |
For operation with code 175 (Predict) |
Predict details |
|
TrackedParcelOperationAdditionalInfoPredict |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
predictedVisitDateTimeFrom |
Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
Start of expected time window for delivery |
|
predictedVisitDateTimeTo |
Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ) |
Yes |
End of expected time window for delivery |
|
includedDelayInMinutes |
Integer |
No |
Expected delivery time delay in minutes (if any). The expected time window for delivery is adjusted with this delay |
|
canceled |
boolean |
Yes |
The value is true in case the predict is cancelled |
|
ExternalCarrierParcelNumberDetails |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
externalCarrierId |
int |
Yes |
Id of the external carrier |
|
externalCarrierName |
String |
Yes |
Name of the external carrier |
|
trackAndTraceUrl |
String |
No |
Track and trace URL of the external carrier |
|
Pickup order data.
PickupOrder |
||||
Name |
Type |
Mandatory |
Data |
Constraints |
id |
long |
Yes |
Order id. |
|
shipmentIds |
String[] |
Yes |
The list of all shipments associated with the order. |
|
pickupPeriodFrom |
Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ) |
No |
Estimated period start for courier pickup visit |
|
pickupPeriodTo |
Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ) |
No |
Estimated period end for courier pickup visit |
|
Country data
Country |
||
Name |
Type |
Data |
id |
integer |
Country ISO |
name |
String |
Country name in requested language |
nameEn |
String |
Country name in English |
isoAlpha2 |
String |
Country ISO alpha 2 code |
isoAlpha3 |
String |
Country ISO alpha 3 code |
postCodeFormats |
String[] |
Allowed postcode format patterns. If empty string presents in allowed patterns this means - postcode format is not restricted and post code validation is not applied on addresses in this country. For non-empty patterns, the following characters are placeholders for:
|
requireState |
String |
Require state flag |
addressType |
integer |
Address type for this country (1 or 2 - see ShipmentAddress) |
currencyCode |
String |
Currency code used for COD in this country |
defaultOfficeId |
Integer |
Default office id |
streetTypes |
Valid street types for country (applicable if addressType is equal to 1) |
|
complexTypes |
Valid complex types for country (applicable if addressType is equal to 1) |
|
siteNomen |
integer |
Specifies site nomenclature (sites) for this country. Values can be:
|
Used for address type 1 street types and complex types
AddressNomenclatureType |
||
Name |
Type |
Data |
name |
String |
Address nomenclature type name in requested language |
nameEn |
String |
Address nomenclature type name in English |
State data
State |
||
Name |
Type |
Data |
id |
String |
State id |
name |
String |
State name in requested language |
nameEn |
String |
State name in English |
stateAlpha |
String |
State ISO alpha code |
countryId |
integer |
State country id |
Site data
Site |
||
Name |
Type |
Data |
id |
long |
Site id |
countryId |
integer |
Site country id |
mainSiteId |
Long |
Here we have reference to main site if this site is a "satellite" one. A satellite site is considered equal (to their main site) in context of "same city" service allowance |
type |
String |
Site type in requested language |
typeEn |
String |
Site type in English |
name |
String |
Site name in requested language |
nameEn |
String |
Site name in English |
municipality |
String |
Municipality name in requested language |
municipalityEn |
String |
Municipality name in English |
region |
String |
Region name in requested language |
regionEn |
String |
Region name in English |
postCode |
String |
Default post code for this site (if any) |
addressNomenclature |
integer |
Code for address nomenclature (streets, complexes, blocks, poi) support.
|
x |
Double |
Site center GPS X (longitude) coordinate |
y |
Double |
Site center GPS Y (latitude) coordinate |
servingDays |
String |
Serving days for this site. Format: 7 serial digits (0 or 1) where each digit corresponds to a day in week (the first digit corresponds to Monday, the second to Tuesday and so on). Value of '0' (zero) means that the site is not served on this day while '1' (one) means that it is served. (Example: the text "0100100" means that the site is served on Tuesday and Friday only) |
servingOfficeId |
Integer |
Site's serving office |
servingHubOfficeId |
Integer |
The hub office ID to which serving office is connected |
Street data
Street |
||
Name |
Type |
Data |
id |
long |
Street id |
siteId |
long |
Street site id |
type |
String |
Street type in requested language |
typeEn |
String |
Street type in English |
name |
String |
Street name in requested language |
nameEn |
String |
Street name in English |
actualId |
Long |
Actual street id (if this street is old and renamed) |
actualType |
String |
Actual street type in requested language (if this street is old and renamed) |
actualTypeEn |
String |
Actual street type in English (if this street is old and renamed) |
actualName |
String |
Actual street name in local language |
actualNameEn |
String |
Actual street name in English |
Complex data
Complex |
||
Name |
Type |
Data |
id |
long |
Complex id |
siteId |
long |
Complex site id |
type |
String |
Complex type in requested language |
typeEn |
String |
Complex type in English |
name |
String |
Complex name in requested language |
nameEn |
String |
Complex name in English |
actualId |
Long |
Actual complex id (if this complex is old and renamed) |
actualType |
String |
Actual complex type in requested language (if this complex is old and renamed) |
actualTypeEn |
String |
Actual complex type in English (if this complex is old and renamed) |
actualName |
String |
Actual complex name in requested language (if this complex is old and renamed) |
actualNameEn |
String |
Actual complex name in English (if this complex is old and renamed) |
Block data
Block |
||
Name |
Type |
Data |
siteId |
long |
Block site id |
name |
String |
Block name in requested language |
nameEn |
String |
Block name in English |
Point of interest data
PointOfInterest |
||
Name |
Type |
Data |
id |
long |
POI id |
siteId |
long |
POI site id |
name |
String |
POI name in requested language |
nameEn |
String |
POI name in English |
type |
String |
POI type in requested language |
typeEn |
String |
POI type in English |
address |
String |
POI address in requested language |
addressEn |
String |
POI address in English |
x |
Double |
POI GPS X (longitude) coordinate |
y |
Double |
POI GPS Y (latitude) coordinate |
Office data
Office |
||
Name |
Type |
Data |
id |
Integer |
Office id |
name |
String |
Office name in requested language |
nameEn |
String |
Office name in English |
siteId |
long |
Office site id |
address |
Office address in requested language |
|
workingTimeFrom |
String ("HH:mm") |
Office work time start for days with standard (FULL) working schedule |
workingTimeTo |
String ("HH:mm") |
Office work time end for days with standard (FULL) working schedule |
workingTimeHalfFrom |
String ("HH:mm") |
Office work time start for days with saturday (HALF) working schedule |
workingTimeHalfTo |
String ("HH:mm") |
Office work time end for days with saturday (HALF) working schedule |
workingTimeDayOffFrom |
String ("HH:mm") |
Office work time start for non-working days (DAY OFF) |
workingTimeDayOffTo |
String ("HH:mm") |
Office work time end for non-working days (DAY OFF) |
sameDayDepartureCutoff |
String ("HH:mm") |
Office same day departure cutoff for days with standard (FULL) working schedule (departure of parcels delivered to office after the cutoff time is next working day) |
sameDayDepartureCutoffHalf |
String ("HH:mm") |
Office same day departure cutoff for days with saturday (HALF) working schedule (departure of parcels delivered to office after the cutoff time is next working day) |
sameDayDepartureCutoffDayOff |
String ("HH:mm") |
Office same day departure cutoff for non-working days (DAY OFF) working schedule (departure of parcels delivered to office after the cutoff time is next working day) |
maxParcelDimensions |
Max parcels dimensions for this office |
|
maxParcelWeight |
double |
Max parcel weight |
type |
enum ["OFFICE", "APT"] |
Office type |
nearbyOfficeId |
Integer |
Nearby office id |
workingTimeSchedule |
Office work time schedule for next days |
|
palletOffice |
boolean |
Pallet office flag |
cardPaymentAllowed |
boolean |
Flag, indicating this office allows card payments |
cashPaymentAllowed |
boolean |
Flag, indicating this office allows cash payments |
validFrom |
Date (yyyy-MM-dd) |
Valid from date |
validTo |
Date (yyyy-MM-dd) |
Valid to date |
cargoTypesAllowed |
enum[] (array with values from enum: [“PARCEL”, “PALLET”, “TYRE”]) (Same as enum in field cargoType in CourierService) |
Allowed cargo types |
pickUpAllowed |
boolean |
Flag, indicating whether parcels can be picked up from office |
dropOffAllowed |
boolean |
Flag, indicating whether parcels can be dropped-off in office |
OfficeWorkingTimeSchedule |
||
Name |
Type |
Data |
date |
Date (format: ""yyyy-MM-dd"") |
Date this schedule is applicable for |
workingTimeFrom |
String ("HH:mm") |
Office working time start for this date |
workingTimeTo |
String ("HH:mm") |
Office working time end for this date |
sameDayDepartureCutoff |
String ("HH:mm") |
Office same day departure cutoff for this day (departure of parcels delivered to office after the cutoff time is next working day) |
standardSchedule |
boolean |
If true - it is from standard schedule, otherwise office working time is overridden for this specific day |
Calculation service defines service level agreement for the shipment - when shipment should be picked up, service code to be used, sub-services, etc
Calculation Service |
||||
Name |
Type |
Required |
Data |
Constraints |
pickupDate |
Date |
No (default value is today) |
The date for shipment pickup. |
Could be today or a future date |
autoAdjustPickupDate |
Boolean |
No (default value is false) |
To find first available date for pickup starting from pickupDate according to pickup schedule for services |
|
serviceIds |
integer[] |
Yes |
Services for which calculation is requested |
Each service id (code) should be valid for the destination. |
additionalServices |
No |
Defines sub-services (like COD, Declared value, etc.) associated with the shipment. |
Sub-services may be allowed or forbidden for selected service and/or destination. |
|
deferredDays |
Integer |
No (default value is 0) |
This parameter allows users to specify by how many (business) days they would like to postpone the shipment delivery from the standard term. |
Allowed values are 0, 1 and 2 |
saturdayDelivery |
Boolean |
No |
This parameter may adjust delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured delivery customer working schedule |
|
Example JSON:
{
"pickupDate":"2018-01-31",
"serviceIds":[2113, 2002],
"autoAdjustPickupDate":true,
"additionalServices":{
"cod":{
"amount":100.00
"currencyCode":"RON"
},
"declaredValue":{
"amount":100.00
"fragile":false
},
"fixedTimeDelivery":1130,
},
"deferredDays":2,
"saturdayDelivery":true
}
Calculation sender is not mandatory. If not specified logged user is the sender.
Calculation Sender |
||||
Name |
Type |
Required |
Data |
Constraints |
clientId |
Long |
No |
Client id to refer serving client |
Validate for existence. |
privatePerson |
Boolean |
If clientId is provided, it is forbidden. Otherwise, it is mandatory. |
Private person flag. |
|
addressLocation |
Required if office id and clientId are missing. Otherwise it is forbidden |
Address location, implies pickup at client address |
|
|
dropoffOfficeId |
Integer |
Required if address location and clientId are missing. If address location presents it is forbidden |
Drop-off office id |
Validated for valid office. |
dropoffGeoPUDOId |
String |
No. Must be empty if dropoffOfficeId is provided |
DPD drop off office PUDO id |
Should refer to a valid accessible DPD office. |
Example JSON:
{
"addressLocation":{
"countryId": 100
"siteId":68314
}
}
or:
{
"dropoffOfficeId": 2
}
Calculation Recipient |
||||
Name |
Type |
Required |
Data |
Constraints |
clientId |
Long |
No |
Client id to refer serving client |
Validate for existence. |
privatePerson |
Boolean |
If clientId is provided, it is forbidden. Otherwise, it is mandatory. |
Private person flag. |
|
addressLocation |
Required if office id and clientId are missing. Otherwise it is forbidden |
Address location, implies delivery at client address |
|
|
pickupOfficeId |
Integer |
Required if address location and clientId are missing. If address location presents it is forbidden |
Pickup office id |
Validated for valid office. |
pickupGeoPUDOId |
String |
No. Must be empty if pickupOfficeId is provided |
DPD pickup office PUDO id |
Should refer to a valid accessible DPD office. |
Calculation Address Location |
||||
Name |
Type |
Required |
Data |
Constraints |
countryId |
Integer |
No |
Country ISO code. If not provided, local country is assumed. Used for all address types. |
Validated for valid country code. |
stateId |
String |
Required, if country supports states |
Country state. Used for addresses of type 2 (foreign address). |
Validated for valid country state. |
siteId |
Long |
Required, if country has full site nomenclature and pair (siteType, siteName) is not provided. |
Site id. Used for all address types. |
Validated for valid site |
siteType |
String |
Forbidden, if siteId is provided. Otherwise, is not mandatory |
Site type can be used in conjunction with countryId and siteName to find unique site. Used for addresses of type 1 (local address). |
Max 20 characters |
siteName |
String |
Forbidden, if siteId is provided. Otherwise, is not mandatory |
Site type can be used in conjunction with countryId and siteName to find unique site. Used for all address types. |
Max 50 characters |
postCode |
String |
Required if country requires postcode for addresses |
Can be used in conjunction with countryId to find unique site. Used for all address types. |
Validated for valid postcode in site and country. Max 10 characters |
Calculation content is used to describe what is to be delivered with the shipment for calculation purposes.
Calculation Content |
||||
Name |
Type |
Required |
Data |
Constraints |
parcelsCount |
Integer |
Required when parcels list is empty |
Total shipment parcels count. Ignored, if parcels list is not empty. |
Validated against the minimum and maximum allowed for the service. |
totalWeight |
Double |
Required when parcels list is empty |
Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcels declaredWeight in that case. |
Validated against the minimum and maximum allowed for the service. |
documents |
Boolean |
No |
Documents flag of the shipment |
|
palletized |
Boolean |
No |
Palletized flag of the shipment. |
|
parcels |
Required for pallet and postal services. |
List of parcels |
Validated against the service configuration and pickup and delivery capacity of the depots and couriers. |
Calculation Result |
||
Name |
Type |
Data |
serviceId |
integer |
Service id |
additionalServices |
Additional services included in calculation |
|
price |
Returned, if customer has access to view the amounts of the shipment. |
|
pickupDate |
Date |
Pickup date. |
deliveryDeadline |
DateTime |
Deadline for delivery. Returned, if available |
error |
Response error. |
Client |
||
Name |
Type |
Data |
clientId |
Long |
Client id |
clientName |
String |
Client name |
objectName |
String |
Object name |
contactName |
String |
Contact name |
address |
Client address |
|
|
String |
Client email |
privatePerson |
Boolean |
Private person flag. |
Shipment |
||
Name |
Type |
Data |
id |
String |
Shipment id |
sender |
Shipment sender. |
|
recipient |
Shipment recipient. |
|
service |
Shipment service level agreement. |
|
content |
Shipment content. |
|
payment |
Shipment payment. |
|
shipmentNote |
String |
Customer’s note associated with the shipment. |
ref1 |
String |
Reference number or text. |
ref2 |
String |
Reference number or text. |
price |
Shipment payment. |
|
delivery |
Shipment delivery. |
|
primaryShipment |
Primary shipment. |
|
returnShipmentId |
String |
Return shipment id (in case this shipment is returned to sender) |
redirectShipmentId |
String |
Redirect shipment id (in case this shipment is redirected to new delivery location) |
pendingShipment |
Boolean |
If this flag is true, the shipment is created in pending shipment state. Shipments in pending shipment state can have incomplete data that defines logisitics (without complete addresses, only sites) Pending shipment state is closed with updateShipment method that makes shipments complete. |
This structure extends Client structure with additional fields.
Sender |
||
Name |
Type |
Data |
Client fields are here |
||
dropoffOfficeId |
Integer |
Drop-off office id |
dropoffGeoPUDOId |
String |
DPD PUDO Id |
This structure extends Client structure with additional fields.
Recipient |
||
Name |
Type |
Data |
Client fields are here |
||
pickupOfficeId |
Integer |
Pickup office id |
pickupGeoPUDOId |
String |
DPD PUDO Id |
Content |
||
Name |
Type |
Data |
parcelsCount |
Integer
|
Total shipment parcels count. |
declaredWeight |
Double |
Shipment declared weight |
measuredWeight |
Double |
Shipment measrued weight |
calculationWeight |
Double |
Shipment calculation weight |
contents |
String |
Shipment content’s description. |
package |
String |
Shipment package. |
documents |
Boolean |
Documents flag of the shipment (shipment content is documents) |
palletized |
Boolean |
Palletized flag of the shipment. |
parcels |
Parcel[] |
Shipment parcels |
pendingParcels |
Boolean |
If this flag is true, the shipment is created in pending parcels state. Shipments in pending parcels state allows adding parcels with addParcel method. Pending parcels state is closed with finalizePendingShipment method. |
Shipment parcel details
Parcel |
||
Name |
Type |
Data |
id |
String |
Parcel id |
seqNo |
Integer |
Parcel sequence nomber within the shipment |
packageUniqueNumber |
Long |
Package number associated with parcel. |
declaredSize |
Parcel declared size |
|
measuredSize |
Parcel measured size |
|
calculationSize |
Parcel calculation size |
|
declaredWeight |
Double |
Parcel declared weight |
measuredWeight |
Double |
Parcel measured weight |
calculationWeight |
Double |
Parcel calculation weight |
externalCarrierParcelNumbers |
String[] |
External carrier parcel numbers associated with this parcel |
baseType |
String |
Base type name |
size |
String |
Size name |
Payment |
||
Name |
Type |
Data |
courierServicePayer |
enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”] |
Courier service payer. |
declaredValuePayer |
enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”] |
Declared value payer |
packagePayer |
enum [“SENDER”, “RECIPIENT”, “THIRD_PARTY”] |
Package payer |
thirdPartyClientId |
Long |
Third party payer client id in case one of the payers is THIRD_PARTY |
discountCardId |
Discount card used in calculation. |
|
codPayment |
COD Payment details |
COD payment details
CODPayment |
||
Name |
Type |
Data |
date |
Datetime (format yyyy-MM-dd'T'HH:mm:ssZ) |
Pay out date |
totalPayedOutAmount |
double |
Total paid out COD amount |
ShipmentDelivery |
||
Name |
Type |
Data |
deadline |
Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ) |
Deadline for this shipment |
deliveryDateTime |
Datetime (fromat: yyyy-MM-dd'T'HH:mm:ssZ) |
Datetime of actual delivery (if schipment is delivered) |
consignee |
String |
Shipment consignee (if schipment is delivered) |
deliveryNote |
String |
Shipment delivery note (if schipment is delivered) |
PrimaryShipment |
||
Name |
Type |
Data |
id |
String |
Primary shipment id |
type |
enum [“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”] |
Primary shipment type - how this secondary shipment is realted to primary one
|
SecondaryShipment |
||
Name |
Type |
Data |
id |
String |
Secondary shipment id |
type |
enum [“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”] (Same as enum in field type in PrimaryShipment) |
Primary shipment type - how this secondary shipment is realted to primary one
|
parcels |
Shipment parcels |
|
pickupDate |
Date (yyyy-MM-dd) |
Secondary shipment pickup date |
serviceId |
int |
Secondary shipment service id |
hasScans |
boolean |
Flag that shows whether the secondary shipment is scanned |
ShipmentParcelNumber |
||
Name |
Type |
Data |
id |
String |
Parcel id |
seqNo |
int |
Parcel sequence number in the shipment. |
CourierService |
||
Name |
Type |
Data |
id |
int |
Courier service id |
name |
String |
Courier service name in local language |
nameEn |
String |
Courier service name in English |
additionalServices |
Additional services options |
|
cargoType |
enum [“PARCEL”, “PALLET”, “TYRE”] |
Cargo type |
requireParcelWeight |
boolean |
Require weight for each parcel on create shipment |
requireParcelSize |
boolean |
Require size for each parcel on create shipment |
AdditionalCourierServices |
||
Name |
Type |
Data |
cod |
COD configuration |
|
obpd |
Options Before Payment or Delivery configuration |
|
declaredValue |
Declared value configuration |
|
fixedTimeDelivery |
Fixed time configuration |
|
specialDelivery |
Special delivery configuration |
|
deliveryToFloor |
Delivery to floor configuration |
|
rod |
Return of documents configuration |
|
returnReceipt |
Return receipt configuration |
|
swap |
SWAP configuration |
|
rop |
Return of pallets configuration |
|
returnVoucher |
Return voucher configuration |
AdditionalCourierService |
||
Name |
Type |
Data |
allowance |
enum [“FORBIDDEN”, “ALLOWED”, “REQUIRED”] |
Allowance value
|
ExtendedCourierService |
||||
Name |
Type |
Data |
||
CourierService fields are here |
||||
deadline |
Date (yyyy-MM-dd'T'HH:mm:ssZ) |
Deadline for delivery |
BulkTrackingDataFile |
||
Name |
Type |
Data |
id |
long |
File id |
url |
String |
File url |
Payout |
||
Name |
Type |
Data |
date |
Date (yyyy-MM-dd) |
Payout date |
docId |
Long |
Payout document id |
docType |
enum [“CASH”, “POSTAL_MONEY_TRANSFER”] |
Payout document type |
paymentType |
enum [“CASH”, “BANK”] |
Payout payment type |
payee |
String |
Payee |
currency |
String |
Payout currency |
amount |
double |
Payout amount |
details |
List of payout details |
PayoutDetails |
||
Name |
Type |
Data |
lineNo |
int |
Payout line number |
shipmentId |
String |
Payout shipment id |
pickupDate |
Date (yyyy-MM-dd) |
Date of shipment pickup |
primaryShipmentPickupDate |
Date (yyyy-MM-dd) |
Date of primary shipment pickup in case this shipment is a secondary one |
deliveryDate |
Date (yyyy-MM-dd) |
Shipment delivery date |
sender |
String |
Shipment sender |
recipient |
String |
Shipment recipient |
note |
String |
Shipment note |
ref1 |
String |
Shipment ref1 (reference) |
ref2 |
String |
Shipment ref2 (reference) |
currency |
String |
Payout currency |
order |
Long |
Order id |
amount |
Double |
Payout amount |
SpecialDeliveryRequirements |
||
Name |
Type |
Data |
requiredForAllShipments |
boolean |
Indicates whether special delivery requirements are mandatory for each shipment |
requirements |
List of requirements |
Requirement |
||
Name |
Type |
Data |
id |
int |
Special delivery requirement id |
text |
String |
Requirement text |
This structure extends Office structure with additional fields.
OfficeResult |
||||
Name |
Type |
Data |
||
distance |
Integer |
Distance from searched location |
||
Office fields are here |
CODAdditionalServiceContractInfo |
||
Name |
Type |
Data |
moneyTransferAllowed |
boolean |
COD as money transfer allowed flag |
codFiscalReceiptAllowed |
boolean |
Issuing COD fiscal receipt on behalf of client allowed flag |
hasCODAnnex |
boolean |
Logged client has COD annex flag |
internationalCODAnnexes |
List of international COD annex contract info |
CODInternationalAnnexContractInfo |
||
Name |
Type |
Data |
countryId |
int |
International annex country id |
countryName |
String |
International annex country name |
Track And Trace Operation Codes |
|
Id |
Description |
1 |
Arrival Scan |
2 |
Departure Scan |
11 |
Received in Office |
12 |
Out for Delivery |
-14 |
Delivered |
21 |
Processed in Office |
38 |
Returned to Office |
39 |
Courier Pick-up |
44 |
Unsuccessful Delivery |
69 |
Deferred delivery |
111 |
Return to Sender |
112 |
Processed to the Insurance dept. |
114 |
Processed for Destruction |
115 |
Redirected |
116 |
Forwarded |
121 |
Stopped by Sender |
123 |
Refused by recipient |
124 |
Delivered Back to Sender |
125 |
Destroyed |
127 |
Theft/Burglary |
128 |
Canceled |
129 |
Administrative Closure |
134 |
Prepared for Self-collecting Consignee |
144 |
Handover for contents check/test |
148 |
Shipment data received |
164 |
Unsuccessful shipment pickup |
169 |
Delivery capacity reached (tour/office) |
175 |
Predict |
176 |
Export to foreign provider |
181 |
Unexpected delay |
190 |
Postponed delivery due to inaccurate/incomplete address |
195 |
Refuse contents check/test |
217 |
Handover to midway carrier |
1134 |
Office/Locker ready for pickup message sent |
Exception codes are associated to track and trace operation codes where relevant.
Track And Trace Operation Codes |
|
Id |
Description |
11 |
Wrong address |
12 |
Refused by recipient - damaged |
14 |
Refused by recipient - not ordered |
15 |
Refused by recipient |
16 |
Refused by recipient - contents checked, found to be damaged |
17 |
Return (pick-up) after wrong delivery |
19 |
Recipient not present - informed first time |
20 |
Self-collecting recipient |
22 |
Broken in sub-contractor's custody |
25 |
Closed (e.g. department store) |
27 |
Lack of space |
29 |
Shipment incomplete |
32 |
Lack of time |
35 |
Recipient not present, informed, on holiday |
37 |
Recipient not present - third time |
41 |
Force majeure |
42 |
Recipient not present, informed 2nd time |
46 |
Amount not paid |
49 |
Customer's return |
61 |
Delay due to unknown reason |
66 |
ID check failed |
67 |
Signature refused |
80 |
Appointment scheduled |
81 |
Regional holiday |
84 |
Delivery note / order reference missing |
1002 |
Incomplete address |
1003 |
Does not answer the phone |
1004 |
In office - not claimed |
1005 |
Redirected |
1006 |
Refused after content’s check/test |
1007 |
New date scheduled |
1008 |
Without delivery attempt |
1020 |
Consignee not reachable - routed to office |
9020 |
Not in warehouse |
Error codes returned in Error structure.
Error Codes |
||
Id |
Name |
Description |
1 |
General Error |
Returned when there is an error in request processing and it doesn't match any of recongizable errors described in this table |
100 |
Invalid client data |
Returned when there is invalid client data provided in request. Relevant for Shipment, Calculation and Client service methods |
120 |
Invalid address |
Returned when there is an error in address provided in request. Relevant for Shipment, Calculation and Client service methods |
160 |
Invalid drop-off office |
Returned when the selected sender drop-off office in request is not valid. Relevant for Shipment and Calculation service methods |
180 |
Invalid pickup office |
Returned when the selected recipient pickup office in request is not valid. Relevant for Shipment and Calculation service methods |
300 |
Invalid third party |
Returned when the selected third party payer in request is invalid. Relevant for Shipment and Calculation service methods |
400 |
Invalid courier service |
Returned when the courier service in request is invalid. Relevant for Shipment and Calculation service methods |
410 |
Invalid COD additional service |
Returned when COD additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
415 |
Invalid Declared Value additional service |
Returned when Declared Value additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
420 |
Invalid OBPD additional service |
Returned when Options Before Payment and Delivery additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
425 |
Invalid Delivery To Floor additional service |
Returned when Delivery To Floor additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
430 |
Invalid Special Deliery additional service |
Returned when Special Deliery additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
435 |
Invalid ROD additional service |
Returned when Return of Documents additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
440 |
Invalid Return Receipt additional service |
Returned when Return Receipt additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
445 |
Invalid SWAP additional service |
Returned when SWAP additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
450 |
Invalid ROP additional service |
Returned when Return of Pallets additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
455 |
Invalid Return Voucher additional service |
Returned when Return Voucher additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
460 |
Invalid Fixed Time Delivery additional service |
Returned when Fixed Time Delivery additional service data in request is invalid. Relevant for Shipment and Calculation service methods |
500 |
Invalid pickup date |
Returned when pickup date is not valid. Relevant for Shipment and Calculation service methods |
510 |
Invalid deferred days |
Returned when deferred days provided in request is not valid. Relevant for Shipment and Calculation service methods |
515 |
Invalid discount card |
Returned when discount card provided in request is not valid. Relevant for Shipment service methods |
520 |
Invalid saturday delivery flag |
Returned when saturday delivery flag provided in request is not valid. Relevant for Shipment and Calculation service methods |
600 |
Invalid shipment contents |
Returned when shipment contents provided in request is not valid. Relevant for Shipment service methods |
605 |
Invalid shipment package |
Returned when shipment package provided in request is not valid. Relevant for Shipment service methods |
610 |
Invalid documents flag |
Returned when documents flag provided in request is not valid. Relevant for Shipment and Calculation service methods |
615 |
Invalid palletized flag |
Returned when palletized flag provided in request is not valid. Relevant for Shipment and Calculation service methods |
620 |
Invalid weight |
Returned when total weight or parcel weight in request is not valid. Relevant for Shipment and Calculation service methods |
630 |
Invalid parcels |
Returned when there is an error in parcels data provided in request. Relevant for Shipment and Calculation service methods |
700 |
Invalid courier service payment |
Returned when there is an error in courier service payment data provided in request. Relevant for Shipment and Calculation service methods |
710 |
Invalid packings payment |
Returned when there is an error in packings payment data provided in request. Relevant for Shipment and Calculation service methods |
800 |
Invalid ref1 |
Returned when shipment reference 1 provided in request. Relevant for Shipment service methods |
805 |
Invalid ref2 |
Returned when shipment reference 2 provided in request. Relevant for Shipment service methods |
810 |
Invalid shipment note |
Returned when shipment note provided in request. Relevant for Shipment service methods |