Please, wait

Logo
Your delivery experts
Web API Integration

Table of Contents

1 Introduction

1.1 Scope

1.2 Terms And Conditions

1.3 Overview

1.4 JSON Schema

1.5 Examples

2 Overall Description

2.1 Shipment Service

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 Print Service

2.2.1 Print Request (PrintRequest)

2.2.2 Print Response (PrintResponse)

2.2.3 Print Request - URL (GET) schema

2.2.4 Extended Print Request

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 Track And Trace Service

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 Pickup

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 Location Service

2.5.1 Country

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 State

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 Site

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 Street

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 Complex

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 Block

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 Point of Interest (POI)

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 Postcodes

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 Office

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 Calculation Service

2.6.1 Calculation Request (CalculationRequest)

2.6.2 Calculation Response (CalculationResponse)

2.6.3 Calculation Request - URL (GET) schema

2.7 Client Service

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 Validation Service

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 Services Service

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 Payments Service

2.10.1 Payout Request (PayoutRequest)

2.10.2 Payout Response (PayoutResponse)

2.10.3 Payout Request - URL (GET) schema

3 Data Structures

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.2 Declared Value (Extended liability) Additional Service(ShipmentDeclaredValueAdditionalService)

3.1.1.2 Shipment Return Additional services (ShipmentReturnAdditionalServices)

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

3.1.1.2.2 Return Receipt Additional Service (ShipmentReturnReceiptAdditionalService)

3.1.1.2.3 SWAP Additional Service (ShipmentSWAPAdditionalService)

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

3.1.1.2.4.1 ROP Additional Service Lines (ShipmentROPAdditionalServiceLine)

3.1.1.2.5 Return Voucher Additional Service (ShipmentReturnVoucherAdditionalService)

3.1.1.3 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.3.1 Address (Address)

3.4.4 Shipment Phone Number (ShipmentPhoneNumber)

3.5 Shipment Parcels

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.7 Errors (Error)

3.8 Parcel to Print (ParcelToPrint)

3.8.1 Parcel to Print Additional Barcode (ParcelToPrintAdditionalBarcode)

3.8.2 Label Info (LabelInfo)

3.9 TrackedParcel (TrackedParcel)

3.9.1 Tracked Parcel Operation (TrackedParcelOperation)

3.9.1.1 Tracked Parcel Operation Additional Info (TrackedParcelOperationAdditionalInfo)

3.9.1.1.1 Tracked Parcel Operation Predict Additional Info (TrackedParcelOperationAdditionalInfoPredict)

3.9.2 External Carrier Parcel Number Details (ExternalCarrierParcelNumberDetails)

3.10 Pickup order (PickupOrder)

3.11 Country

3.11.1 Address Nomenclature Type (AddressNomenclatureType)

3.12 State

3.13 Site

3.14 Street

3.15 Complex

3.16 Block

3.17 Point of interest (PointOfInterest)

3.18 Office (Office)

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.25 Client (Client)

3.26 Shipment (Shipment)

3.26.1 Sender (Sender)

3.26.2 Recipient (Recipient)

3.26.3 Content (Content)

3.26.3.1 Parcel (Parcel)

3.26.4 Payment (Payment)

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 Courier Service

3.27.1 AdditionalCourierServices

3.27.1.1 AdditionalCourierService

3.28 Extended Courier Service

3.29 Bulk Tracking Data File

3.30 Payout

3.30.1 Payout Details

3.31 SpecialDeliveryRequirements

3.31.1 Requirement

3.32 OfficeResult

4 Appendixes

4.1 Appendix 1 - Track And Trace Operation Codes

4.2 Appendix 2 - Track And Trace Operation Exception Codes

4.3 Appendix 3 - Error Codes


1 Introduction

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.

1.1 Scope

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

1.2 Terms And Conditions

1.3 Overview

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

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

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

1.4 JSON Schema

API JSON schema is available for download here

1.5 Examples

Examples can be found here

2 Overall Description

 BASE_URL=_

2.1 Shipment Service

Web service URL: BASE_URL/shipment

2.1.1 Create Shipment Request (CreateShipmentRequest)

Method: POST

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

Input parameters:

CreateShipmentRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

sender

ShipmentSender

No

Defines the sender of the shipment and shipment's pickup place. If not specified, the logged user is considered as a sender.

recipient

ShipmentRecipient

Yes

Defines the recipient of the shipment and shipment’s delivery place.

service

ShipmentService

Yes

Defines shipment service level agreement.

content

ShipmentContent

Yes

Defines shipment’s content - number of parcels, weight, size, etc.

payment

ShipmentPayment

Yes

Defines who-pays-what in shipment and other payment parameters.

shipmentNote

String

No

Customer’s note associated with the shipment.

200 characters

ref1

String

No

Reference number or text.

30

ref2

String

No

Reference number or text.

30

consolidationRef

String

No

Consolidation reference number or text.

30

requireUnsuccessfulDeliveryStickerImage

Boolean

No

Require unsuccessful delivery sticker image flag.

Example Request:

{

   "userName":"testUser",

   "password":"password",

   "service":{

      "serviceId":2002,

      "additionalServices":{

         "declaredValue":{

            "amount":100.0

         },

         "returns":{

            "rod":{

               "enabled":true

            },

            "returnReceipt":{

               "enabled":true

            },

            "swap":{

               "serviceId":2002,

               "parcelsCount":1

            }

         }

      }

   },

   "content":{

      "parcelsCount":1,

      "totalWeight":20.0,

      "contents":"FURNITURE",

      "package":"BOX"

   },

   "payment":{

      "courierServicePayer":"SENDER"

   },

   "recipient":{

      "phone1":{

         "number":"0999123321"

      },

      "privatePerson": true,

      "clientName":"TEST",

      "contactName":"TEST",

      "email":"[email protected]",

      "address":{

         "siteName":"Sibiu",

         "streetType":"str.",

         "streetName":"ACILIU",

         "streetNo":"3"

      }

   },

   "shipmentNote":"Test note",

   "ref1":"R1",

   "ref2":"R2"

}

2.1.2 Create Shipment Response (CreateShipmentResponse)

Output parameters:

CreateShipmentResponse

Name

Type

Data

id

String

Generated shipment id.

parcels

CreatedShipmentParcel[]

Generated parcels.

price

ShipmentPrice

Returned, if customer has access to view the amounts of the shipment.

pickupDate

Date (date)

Shipment pickup date.

deliveryDeadline

Date (datetime)

Deadline for delivery. Returned, if available.

error

Error

Response error.

Example response:

{

   "id":"80002589418",

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

   "price":{

      "amount":47.17,

      "vat":8.96,

      "total":56.13,

      "details":{

         "netAmount":{

            "amount":46.5,

            "vatPercent":0.19

         },

         "fixedDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "dropOffDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "pickUpDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "additionalDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "fuelSurcharge":{

            "amount":0.47,

            "percent":1.0,

            "vatPercent":0.19

         },

         "islandSurcharge":{

            "amount":0.0,

            "vatPercent":0.19

         },

         "codPremium":{

            "amount":0.0,

            "vatPercent":0.19

         },

         "insurancePremium":{

            "amount":0.2,

            "vatPercent":0.19

         }

      },

      "amountLocal":47.17,

      "vatLocal":8.96,

      "totalLocal":56.13,

      "currencyLocal":"RON",

      "detailsLocal":{

         "netAmount":{

            "amount":46.5,

            "vatPercent":0.19

         },

         "fixedDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "dropOffDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "pickUpDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "additionalDiscount":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":0.19

         },

         "fuelSurcharge":{

            "amount":0.47,

            "percent":1.0,

            "vatPercent":0.19

         },

         "islandSurcharge":{

            "amount":0.0,

            "vatPercent":0.19

         },

         "codPremium":{

            "amount":0.0,

            "vatPercent":0.19

         },

         "insurancePremium":{

            "amount":0.2,

            "vatPercent":0.19

         }

      },

      "currencyExchangeRateUnit":1,

      "currencyExchangeRate":1.0

   },

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

}

2.1.3 Create Shipment - URL (GET) Schema

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

 

Web service URL:  BASE_URL/shipment

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

CreateShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Sender details

If the logged user is the sender, you may skip providing sender details at all.

If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also. However, in these cases, if the user needs to change the defaults stored in the system, the following parameters could be provided in addition:

  • sender phone(s)
  • sender contact in case the referred customer is a company (not a private person), otherwise should be skipped
  • sender email
  • sender address note

If you provide information in other sender parameters, you’ll receive an error that data is not expected in that field.

Otherwise, sender_id should stay empty and it is required to provide as a minimum:

  • sender phone
  • sender name
  • sender privatePerson flag
  • sender contact in case privatePerson is false, otherwise should be skipped
  • sender address or dropoffOfficeId

senderId | sender_id

Long

No.

Client id to refer а sender.

Validated for existence.

senderPhone | sender_phone

String

Mandatory in case sender_id is empty and sender_name is not. Otherwise, it is allowed but not mandatory.

Sender phone number.

senderPhoneExt | sender_phone_ext

String

No

Sender phone number extension.

senderPhone2 | sender_phone2

String

No

Sender phone number 2.

senderPhone2Ext | sender_phone2_ext

String

No

Sender phone number 2 extension.

senderPhone3 | sender_phone3

String

No

Sender phone number extension.

senderPhone3Ext | sender_phone3_ext

String

No

Sender phone number 3 extension.

senderName | sender_name

String

If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory.

Sender name.

Minimum 3 symbols, maximum 60

senderContact | sender_contact

String

No

Required, if privatePerson flag is false.

Sender contact name.

Maximum 60 symbols.

senderEmail | sender_email

String

No

Sender email.

Maximum 255 symbols.

senderPrivatePerson | sender_private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory.

Sender private person flag.

Sender Address

See ShipmentAddress for more details.

The sender address is expected when sender_id is empty and sender_name is not and sender_dropoff_office_id is empty and not required. In other words, the sender address is required when the sender is not a referred customer or logged user and pickup at sender’s address is expected.

senderAddressCountryId | sender_address_country_id

Integer

No

Country ISO code. If not provided, the local country is assumed.

Used for all address types.

senderAddressStateId | sender_address_state_id

String

Required, if country supports states.

Country state.

Used for addresses of type 2 (foreign address).

senderAddressSiteId | sender_address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided.

Site id.

Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country

senderAddressSiteType | sender_address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for addresses of type 1 (local address).

Max 20

senderAddressSiteName | sender_address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for all address types.

Max 50

senderAddressPostcode | senderAddressPostCode | sender_address_postcode

String

No

Can be used in conjunction with countryId to find unique site.

Used for all address types.

Validated for valid postcode in site and country.

Max 10

senderAddressStreetId | sender_address_street_id

Long

No

Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

senderAddressStreetType | sender_address_street_type

String

No

Forbidden, if street_id is provided.

Street type.

Used for addresses of type 1 (local address).

Max 15

senderAddressStreetName | sender_address_street_name

String

No

Forbidden, if street_id is provided.

Street name.

Used for addresses of type 1 (local address).

Max 50

senderAddressStreetNumber | sender_address_street_number

String

No

Street number.

Used for addresses of type 1 (local address).

Max 10

senderAddressComplexId | sender_address_complex_id

Long

No

Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

senderAddressComplexType | sender_address_complex_type

String

No

Forbidden, if complex_id is provided.

Complex type.

Used for addresses of type 1 (local address).

Max 15

senderAddressComplexName | sender_address_complex_name

String

No

Forbidden, if complex_id is provided.

Complex name.

Used for addresses of type 1 (local address).

Max 50

senderAddressBlock | senderAddressBlockNo | sender_address_block

String

No

Block No.

Used for addresses of type 1 (local address).

Max 32

senderAddressEntrance | senderAddressEntranceNo | sender_address_entrance

String

No

Entrance.

Used for addresses of type 1 (local address).

Max 10

senderAddressFloor | senderAddressFloorNo | sender_address_floor

String

No

Floor.

Used for addresses of type 1 (local address).

Max 10

senderAddressApartment | senderAddressApartmentNo | sender_address_apartment

String

No

Apartment.

Used for addresses of type 1 (local address).

Max 10

senderAddressPoiId | sender_address_poi_id

Long

No

Point of interest identifier.

Used for addresses of type 1 (local address).

senderAddressNote | sender_address_note

String

No

Address note.

Used for addresses of type 1 (local address).

200

senderAddressLine1 | sender_address_line1

String

Required for address type 2.

Address line 1. Used for addresses of type 2 (foreign address).

Max 35

senderAddressLine2 | sender_address_line2

String

No

Address line 2. Used for addresses of type 2 (foreign address).

Max 35

senderAddressX | sender_address_x

Double

No

GIS coordinates - X.

Used for all address types.

senderAddressY | sender_address_y

Double

No

GIS coordinates - Y.

Used for all address types.

dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId | senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id

Integer

Required, if the sender is an  internal customer. If sender address is provided, it is forbidden.

Drop off office id.

Should refer to a valid accessible office.

sender_geo_pudo_id | senderGeoPUDOId | senderDropoffGeoPUDOId | senderDropOffGeoPUDOId | dropoff_geo_pudo_id | dropoff_geo_pudo_id | dropoffGeoPUDOId | dropOffGeoPUDOId

String

No. Must be empty if dropoffOfficeId is provided

DPD drop off office PUDO id

Should refer to a valid accessible DPD office.

Shipment Recipient

If you refer an existing customer, provide client’s id in recipient_id parameter and other recipient parameters may be skipped at all. However, if the user needs to change the defaults stored in the system, the following parameters could be provided in addition:

  • recipient phone(s)
  • recipient contact in case the referred customer is a company (not a private person), otherwise should be skipped
  • recipient email
  • recipient address note

If you provide information in other recipient parameters, you’ll receive error that data is not expected in that field.

Otherwise, recipient_id should stay empty and it is required to provide as a minimum:

  • recipient phone - could be omitted but is required for the same day delivery services, saturday delivery and delivery abroad
  • recipient name
  • recipient privatePerson flag
  • recipient contact in case privatePerson is false otherwise should be skipped
  • recipient address or pickupOfficeId

recipientId | recipient_id

Long

No.

Client id to refer a recipient.

Validated for existence.

recipientPhone | recipient_phone

String

Mandatory in case recipient_id is empty and recipient_name is not. Otherwise, it is allowed but not mandatory.

Recipient phone number.

recipientPhoneExt | recipient_phone_ext

String

No

Recipient phone number extension.

recipientPhone2 | recipient_phone2

String

No

Recipient phone number 2.

recipientPhone2Ext | recipient_phone2_ext

String

No

Recipient phone number 2 extension.

recipientPhone3 | recipient_phone3

String

No

Recipient phone number extension.

recipientPhone3Ext | recipient_phone3_ext

String

No

Recipient phone number 3 extension.

recipientName | recipient_name

String

If recipient_id is provided, it is forbidden. Otherwise, it is mandatory.

Recipient name.

Minimum 3 symbols, maximum 60

recipientContact | recipient_contact

String

No

Required, if privatePerson flag is false.

Recipient  contact name.

Maximum 60.

recipientEmail | recipient_email

String

No

Recipient email.

Maximum  255. Mandatory for international shipments

recipientPrivatePerson | recipient_private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

If recipient_id is provided, it is forbidden. Otherwise, it is mandatory.

Recipient  private person flag.

Recipient Address

See ShipmentAddress for more details.

The recipient address is expected when recipient_id is empty and recipient_name is not and recipient_pickup_office is empty and not required. In other words, the recipient address is required when the recipient is not a referred customer and delivery at recipient’s address is expected.

recipientAddressCountryId | recipient_address_country_id

Integer

No

Country ISO code. If not provided, local country is assumed.

Used for all address types.

recipientAddressStateId | recipient_address_state_id

String

Required, if country supports states.

Country state.

Used for addresses of type 2 (foreign address).

recipientAddressSiteId | recipient_address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided.

Site id.

Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country

recipientAddressSiteType | recipient_address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for addresses of type 1 (local address).

Max 20

recipientAddressSiteName | recipient_address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for all address types.

Max 50

recipientAddressPostcode | recipientAddressPostCode | recipient_address_postcode

String

No

Can be used in conjunction with countryId to find unique site.

Used for all address types.

Validated for valid postcode in site and country.

Max 10

recipientAddressStreetId | recipient_address_street_id

Long

No

Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

recipientAddressStreetType | recipient_address_street_type

String

No

Forbidden, if street_id is provided.

Street type.

Used for addresses of type 1 (local address).

Max 15

recipientAddressStreetName | recipient_address_street_name

String

No

Forbidden, if street_id is provided.

Street name.

Used for addresses of type 1 (local address).

Max 50

recipientAddressStreetNumber | recipient_address_street_number

String

No

Street number.

Used for addresses of type 1 (local address).

Max 10

recipientAddressComplexId | recipient_address_complex_id

Long

No

Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

recipientAddressComplexType | recipient_address_complex_type

String

No

Forbidden, if complex_id is provided.

Complex type.

Used for addresses of type 1 (local address).

Max 15

recipientAddressComplexName | recipient_address_complex_name

String

No

Forbidden, if complex_id is provided.

Complex name.

Used for addresses of type 1 (local address).

Max 50

recipientAddressBlock | recipientAddressBlockNo | recipient_address_block

String

No

Block No.

Used for addresses of type 1 (local address).

Max 32

recipientAddressEntrance | recipientAddressEntranceNo | recipient_address_entrance

String

No

Entrance.

Used for addresses of type 1 (local address).

Max 10

recipientAddressFloor | recipientAddressFloorNo | recipient_address_floor

String

No

Floor.

Used for addresses of type 1 (local address).

Max 10

recipientAddressApartment | recipientAddressApartmentNo | recipient_address_apartment

String

No

Apartment.

Used for addresses of type 1 (local address).

Max 10

recipientAddressPoiId | recipient_address_poi_id

Long

No

Point of interest identifier.

Used for addresses of type 1 (local address).

recipientAddressNote | recipient_address_note

String

No

Address note.

Used for addresses of type 1 (local address).

200

recipientAddressLine1 | recipient_address_line1

String

Required for address type 2

Address line 1. Used for addresses of type 2 (foreign address).

Max 35

recipientAddressLine2 | recipient_address_line2

String

No

Address line 2. Used for addresses of type 2 (foreign address).

Max 35

recipientAddressX | recipient_address_x

Double

No

GIS coordinates - X.

Used for all address types.

recipientAddressY | recipient_address_y

Double

No

GIS coordinates - Y.

Used for all address types.

pickupOfficeId | pickUpOfficeId | recipientPickupOfficeId | recipientPickUpOfficeId | pickup_office_id | recipient_pickup_office_id

Integer

Required, if recipient is internal client. If recipient address is provided, it is forbidden

Pickup office id.

Should refer to valid accessible office.

recipient_geo_pudo_id | recipientGeoPUDOId | recipientPickupGeoPUDOId | recipientPickUpGeoPUDOId | pickup_geo_pudo_id | pickupGeoPUDOId | pickUpGeoPUDOId

String

No. Must be empty if pickupOfficeId is provided

DPD pickup office PUDO id

Should refer to a valid accessible DPD office.

Shipment Service

See ShipmentService for more details.

Shipment service defines agreement with customer for courier service. This includes:

  • Pickup date
  • Service id (code)
  • Optional defer days or saturday delivery
  • Additional services (like COD, Declared value, SWAP, ROD and etc.)

pickupDate | pickup_date

Date (date)

Example:  “2017-12-11"

No

(default value is today)

The date for shipment pick-up.

Could be today or a future date.

autoAdjustPickupDate | auto_adjust_pickup_date | autoadjust_pickup_date

Boolean

No (default is false)

To find first available date for pickup starting from pickupDate according to pickup schedule for services

serviceId | service_id

int

Yes

Service to be used for shipment.

Service id (code) should be valid for destination.

deferredDays | deferred_days

Integer

No

(default value is 0)

This parameter allows                 users to specify by how many (business) days they would like to postpone the shipment delivery from the standard term.

Allowed values are 0, 1 and 2.

saturdayDelivery | saturday_delivery

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

This parameter may adjust the delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured recipient working schedule.

COD Additional Service

For more information see ShipmentCODAdditionalService.

codAmount | cod_amount

double

No

Defines shipment COD base amount.

Validated against maximum allowed amounts for destination.

codCurrency | cod_currency

String

No

(default is the currency code of the destination country)

Defines shipment COD currency code.

Validated against allowed currency code of destination country.

codProcessingType | cod_processing_type

enum

[“CASH”, “POSTAL_MONEY_TRANSFER”]

No

(default is “CASH”)

Defines COD processing type.

Appropriate contract and annexes may be required.

codPayoutThirdParty | cod_payout_third_party

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

If this flag is set, the COD is paid to a third party (not to the  sender).

Requires the third party to be the payer of the courier service.

codPayoutLoggedClient | cod_payout_logged_client

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

If this flag is set, the COD is paid to a logged client.

codWithShippingPrice | cod_with_shipping_price

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Flag indicating whether the shipping price should be included in the COD.

codCardPaymentForbidden | cod_card_payment_forbidden

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Flag indicating that COD/PMT card payment is forbidden.

cod_fiscal_receipt_items

String

Format for fiscal report item is:

<description>,<vatGroup>,

<amount>,<amountWithVat>

Multiple fiscal report should be separated with %7C (‘|’) character.

See ShipmentCODFiscalReceiptItem

No

List of items in COD fiscal receipt to issue receipt on behalf of client.If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.

This feature depends on country regulations and must be enabled for client contract.The value in cod amount field is ignored if fiscal receipt items are provided.

Options before payment details Additional Service

For more information see ShipmentOBPD.

obpd_option

enum

[“OPEN”, “TEST”]

No

(For certain destinations could be required.)

Defines option to be used.

Open parcels before payment or open and test parcels before payment.

Return shipment is validated for destination.

obpd_return_service_id

Integer

No

(For certain destinations could be required.)

Defines service id to be used on return, if COD payment is refused.

Return shipment is validated for destination.

obpd_return_payer

enum

[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]

No

(For certain destinations could be required.)

Defines who pays the return shipment, if COD payment is refused.

Return shipment is validated for destination.

Declared Value (Extended Liability) Additional Service

For more information see ShipmentDeclaredVaueAdditionalService.

Declared value payer is required when declared value amount is provided and is set in payment section.

declaredValueAmount | declared_value_amount

double

No

Defines shipment Declared Value (extended liability) base amount. Declared value amount is always in local system currency.

Validated against maximum allowed amounts.

fragile | declaredValueFragile | declared_value_fragile

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Defines fragile flag for shipment content.

Fragile shipments requires declared value sub service.

Fixed Time Delivery Additional Service

Fixed time delivery is an additional service that provides instruction to deliver shipment at a certain time on the delivery date.

fixedTimeDelivery | fixed_time_delivery

Integer

No

This option fixes the time of delivery on the delivery date. 1130 - means 11:30

920 - means 09:20

This option is checked against configured allowed time frame for the service.

Return of Documents (ROD) Additional Service

For more information see ShipmentRODAdditionalService.

Return documents is an additional service that provides instruction to collect documents on shipment delivery in return.

rodEnabled | rod_enabled

Boolean

(true/false, y/n, “yes/no”  - all case insensitive)

No

Enabled flag

rodComment | rod_comment

String

No

Return documents comment.

Max size 512

rodReturnToClientId | rod_return_to_client_id

Long

No

Defines customer - recipient for the ROD shipment. If not specified and rod_return_to_office_id is not specified also, the reverse shipment is returned to the primary shipment sender.

Cannot be specified together with rod_return_to_office_id. The same value should be set for ROD and Return Receipt, if the sub-service presents. Cannot be specified if SWAP presents

rodReturnToOfficeId | rod_return_to_office_id

Integer

No

Defines delivery pickup depot for ROD shipment. If not specified and rod_return_to_client_id is not specified also, the return shipment is returned to primary shipment sender.

Cannot be specified together with rod_return_to_client_id. The same value should be set for ROD, Return Receipt and SWAP, if the sub-service presents.

rodThirdPartyPayer | rod_third_party_payer

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Defines a third party payer for ROD shipment. Otherwise, payer is the  primary shipment sender.

Requires a third party payer of the primary shipment. The same value should be set for ROD, Return Receipt, ROP and SWAP, if the  sub-service presents.

Return Receipt Additional Service

For more information see ShipmentReturnReceiptAdditionalService.

Return receipt is an additional service that provides instruction to collect a receipt on shipment delivery in return.

receiptEnabled | receipt_enabled

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Enabled flag

receiptReturnToClientId | receipt_return_to_client_id

Long

No

Defines customer - recipient for the Return Receipt shipment. If not specified and receipt_return_to_office_id is not specified also, the return shipment is returned to the primary shipment sender.

Cannot be specified together with receipt_return_to_office_id. The same values should be set for ROD and Return Receipt, if the sub service presents. Cannot be specified if SWAP presents

receiptReturnToOfficeId | receipt_return_to_office_id

Integer

No

Defines delivery pickup depot for the Return Receipt shipment. If not specified and receipt_return_to_client_id is not specified also, the return shipment is returned to the primary shipment sender.

Cannot be specified together with receipt_return_to_client_id. The same values should be set for ROD, Return Receipt and SWAP, if the sub service presents.

receiptThirdPartyPayer | receipt_third_party_payer

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Defines a third party payer for the Return Receipt shipment. Otherwise, payer is the primary shipment sender.

Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.

SWAP Additional Service

For more information see ShipmentSWAPAdditionalService.

SWAP is an additional service that provides instruction to collect a reverse shipment with predefined parameters on shipment delivery in return.

swapServiceId | swap_service_id

int

No

Service to be used in return.

Validated for allowance and destination.

swapParcelsCount | swap_parcels_count

int

No

Number of parcels to return.

Validated against maximum allowed parcels.

swapDeclaredValueAmount | swap_declared_value_amount

Double

No

Declared value for the reverse shipment.

Validated for allowance and maximum amount.

swapDeclaredValueFragile | swap_declared_value_fragile

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Fragile content flag for the reverse shipment.

Fragile shipments requires declared value.

swapReturnToOfficeId | swap_return_to_office_id

Integer

No

Defines delivery pickup depot for the SWAP  shipment. If not specified, the return shipment is returned to the primary shipment sender.

The same value should be set for ROD, Return Receipt and SWAP, if sub-service presents.

swapThirdPartyPayer | swap_third_party_payer

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Defines a third party payer for the SWAP shipment. Otherwise, payer is the primary shipment sender.

Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.

Return of Pallets (ROP) Additional Service

For more information see ShipmentROPAdditionalService.

Return of pallets is an additional service that provides instruction to collect pallets (used to wrap parcels for transport) in return.

ropPallets | rop_pallets

String

Format for single pair is:

“<serviceId>,<parcelsCount>”

Multiple pairs are separated with %7C (‘|’) character.

See ShipmentROPAdditionalServiceLine

No

Defines pallets to return grouped by service id.

Total number of returned pallets should not exceed parcels count of the primary shipment.

ropThirdPartyPayer | rop_third_party_payer

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Defines a third party payer for the returned pallets. Otherwise, payer is the primary shipment sender.

Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.

Return Voucher Additional Service

For more information see ShipmentReturnVoucherAdditionalService.

Return voucher provides an option for the recipient to initiate a return, based on the delivered shipment, within predefined voucher validity period.

voucherServiceId | voucher_service_id

int

No

Service id of the return voucher shipment.

voucherPayer | voucher_payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

No

Defines the return voucher payer.

Allowed payers are validated against service configuration and destination.

voucherValidityPeriod | voucher_validy_period

Integer

Required if caller client has no annex for return voucher.

Return voucher validity period in days. The annex return voucher period is used by default in case caller client has such in his contract and value is omitted

Verified to not exceed the configured internal maximum in the system

Special Delivery Additional Service

Special delivery is an additional service that provides instruction to the courier to do additional (special) checks and actions on delivery. These checks and actions are negotiated and contracted in a special delivery annex. For example, the courier could be instructed to check IDs of recipient party at delivery.

specialDeliveryId | special_delivery_id

Integer

No

Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex.

Requires annex for special delivery.

Delivery to Floor Additional Service

Delivery to floor is an additional service that provides instruction to the courier that the shipment should not be delivered to the entrance of a multi floor building, but should be moved to a certain floor before delivery.

deliveryToFloor | delivery_to_floor

Integer

No

Specifies the floor number in the building where to deliver shipment.

This additional service requires annex.

Shipment Content

For more information see ShipmentContent.

Defines what is to be delivered with the shipment.

parcelsCount | parcels_count

Integer

Required when parcels list is empty and pending_parcels is false.

Total shipment’s parcels count. Ignored, if parcels list is not empty. The parcels count is the number of parcels in the lits in that case.

Validated against minimum and maximum allowed for the service.

totalWeight | total_weight

Double

Required when parcels list is empty and pending_parcels is false.

Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcel’s weight in that case.

Validated against minimum and maximum allowed for the service.

contents

String

Yes

Shipment’s contents description.

100

package

String

Yes

Shipment’s package.

50

documents

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Documents flag of the shipment.

palletized

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Palletized flag of the shipment.

parcels

String

Format for single parcel is:

<seqNo>,<weight>,

<width>x<depth>x<height>,

<packageUniqueNumber>,

<id>,

<ignored, kept for backward compatibility>,

<ref1>,

<ref2>,

<Pickup External Carrier Parcel number in format carrier name-parcelnumber>,

<Delivery External Carrier Parcel number in format carrier name-parcelnumber>

Multiple parcels should be separated with %7C (‘|’) character.

See ShipmentParcel

Required for pallet and postal services. For multiple parcels add the same url parameter again. The parameters are parsed in the order of their occurrence. If the sequence is incomplete, the missing parameters are considered empty.

Parcels. If omitted, a single default (first) parcel will be created for non-pallet and non-postal services.

Validated against service configuration and pickup and delivery capacity of the depots and the couriers.

pendingParcels | pending_parcels

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Partial shipment flag indicating parcels are not complete and new parcels are expected.

exciseGoods | excise_goods

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Flag shipment contains excise goods.

Shipment Payment

For more information see ShipmentPayment.

Defines who-pays-what in shipment and other payment parameters.

courierServicePayer | courier_service_payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

Yes

Courier service payer.

Validated against the service, destination, contracts and annexes.

declaredValuePayer | declared_value_payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

No

Declared value payer. If not provided, the courier service payer is assumed. Not expected, if the declared value amount is empty.

Validated against the service, destination, contracts and annexes.

packagePayer | package_payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

No

Package payer. If not provided, the courier service payer is assumed.

Validated against the service, destination, contracts and annexes.

thirdPartyClientId | third_party_client_id

Long

No

Defines shipment third party - used as a payer of any of shipment payable components.

Third party customer should be registered customer with valid contract and annex for delayed payment at pickup date. Third party customer should be customer(object) in the same contract as the logged user.

Discount card

For more information see ShipmentDiscountCardId.

Discount cards provide promotional discounts.

discountCardContractId | discount_card_contract_id

Long

No

Discount card contract id.

Validated against a referred contract.

discountCardId | discount_card_id

Long

No

Discount card id for contract.

Validated against a referred discount card.

Sender Bank account

For more information see BankAccount.

Sender COD payout bank account.

senderBankAccountIban | sender_bank_account_iban

String

No

Sender bank account iban

IBAN format validation is applied

senderBankAccountHolder | sender_bank_account_holder

String

No

Sender bank account holder

Max 60 characters

administrativeFee | administrative_fee

Boolean

No

Flag to apply administrative fee on price calculations

Usage of administrative fee is enabled and configured in client contract. Ignored if not applicable for user.

Common parameters

shipmentNote | shipment_note

String

No

Customer note associated with the shipment.

200 characters

ref1

String

No

Reference number or text.

30

ref2

String

No

Reference number or text.

30

consolidation_ref | consolidationRef

String

No

Consolidation reference number or text.

30

require_unsuccessful_delivery_sticker_image | requireUnsuccessfulDeliveryStickerImage

Boolean

No

Require unsuccessful delivery sticker image flag.

Examples:

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

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

2.1.4 Cancel Shipment Request (CancelShipmentRequest)

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"

}

2.1.5 Cancel Shipment Response (CancelShipmentResponse)

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

CancelShipmentResponse

Name

Type

Data

error

Error

Response error

Example JSON:

{}

2.1.6 Cancel Shipment - URL (GET) schema

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

 

Web service URL:  BASE_URL/shipment/cancel

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

CancelShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentId | shipment_id

String

Yes

Shipment id

Should have access rights to cancel shipment.

comment

String

Yes

Cancel comment

Max 1024

2.1.7 Add parcel Request (AddParcelRequest)

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

Web service URL:  BASE_URL/shipment/add_parcel

Method: POST

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

AddParcelRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

shipmentId

String

Yes

Shipment id

Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).

parcel

ShipmentParcel

Yes

Parcel to add. Parcel id and sequence number are auto-generated and therefore ignored if present in request

codAmount

Double

No

COD amount to add with this parcel to increase total COD amount

codFiscalReceiptItems

ShipmentCODFiscalReceiptItem[]

This feature depends on country regulations and must be enabled for client contract.

The value in codAmount is ignored if fiscal receipt items are provided.

To use fiscal receipt items in this method the shipment must have COD defined with fiscal receipt already or COD must be emty

List of items to add in current fiscal receipt items list to issue receipt on behalf of client

If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.

declaredValueAmount

Double

No

Declared value (extended liability) amount to add with this parcel to increase total amount

If this parcel increases the amount of declared value, the shipment should be opened with Declared value (extended liability) additional service

Example JSON:

{

   "userName":"testUser",

   "password":"password",

   "shipmentId":"80002589418",

   "parcel": {

       "weight":3,

       "size": {

           "width":5,

           "height":5,

           "depth":5

       }

   },

   "codAmount":5.0

}

2.1.8 Add Parcel Response (AddParcelResponse)

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

CancelShipmentResponse

Name

Type

Data

parcel

CreatedShipmentParcel

Created shipment parcel (with generated id and sequence number)

error

Error

Response error

Example JSON:

{}

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

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

Web service URL:  BASE_URL/shipment/add_parcel

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

AddParcelRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentId | shipment_id

String

Yes

Shipment id

Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).

weight

Double

Yes

Parcel weight

size

String

Format is <width>x<depth>x<height>

No

(Required for pallet and postal services)

Parcel size

packageUniqueNumber | package_unique_number

Long

No

Parcel package unique number

externalCarrierParcelNumber | external_carrier_parcel_number

String

No

External carrier parcel id

codAmount | cod_amount

Double

No

COD amount to add with this parcel to increase total COD amount

cod_fiscal_receipt_items

String

Format for fiscal report item is:

<description>,<vatGroup>,

<amount>,<amountWithVat>

Multiple fiscal report should be separated with %7C (‘|’) character.

See ShipmentCODFiscalReceiptItem

No

List of items to add in current fiscal receipt items list to issue receipt on behalf of client. If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.

This feature depends on country regulations and must be enabled for client contract. The value in codAmount is ignored if fiscal receipt items are provided. To use fiscal receipt items in this method the shipment must have COD defined with fiscal receipt already or COD must be emty

declaredValueAmount | declared_value_amount

Double

No

Declared value (extended liability) amount to add with this parcel to increase total amount

If this parcel increases the amount of declared value, the shipment should be opened with Declared value (extended liability) additional service

Example request:

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

2.1.10 Finalize Pending Shipment Request (FinalizePendingShipmentRequest)

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

Web service URL:  BASE_URL/shipment/finalize

Method: POST

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

FinalizePendingShipmentRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

shipmentId

String

Yes

Shipment id

Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).

Example JSON:

{

   "userName":"testUser",

   "password":"password",

   "shipmentId":"80002589418"

}

2.1.11 Finalize Pending Shipment Response (FinalizePendingShipmentResponse)

The response is the same as CreateShipmentResponse.

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

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

Web service URL:  BASE_URL/shipment/finalize

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FinalizePendingShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentId | shipment_id

String

Yes

Shipment id

Should refer shipment in pending parcels state (not finalized yet with finalizePendingShipment method).

Example request:

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

2.1.13 Shipment Information Request (ShipmentInformationRequest)

This method provides shipment information

Web service URL:  BASE_URL/shipment/info

Method: POST

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

ShipmentInformationRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

shipmentIds

String[]

Yes

Shipment ids

2.1.14 Shipment Information Response (ShipmentInformationResponse)

ShipmentInformationResponse

Name

Type

Data

shipments

Shipment[]

Shipment information

error

Error

Response error

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

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

Web service URL:  BASE_URL/shipment/info

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ShipmentInformationRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentIds | shipment_ids

String[]

Yes

Comma separated list of shipment ids

2.1.16 Secondary Shipments Request (SecondaryShipmentsRequest)

This method provides secodary shipments information

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

Method: POST

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

SecondaryShipmentsRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

types

enum[] (array with values from enum:

[“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”])

(Same as enum in field type in PrimaryShipment)

Yes

Filters the list for shipments of the specified type(s) only. No filter is applied if not provided (all secondary shipments are returned).

  • RETURN_SHIPMENT - any of return of documents (rod) / returnReceipt / swap / return of pallets (rop)
  • STORAGE_PAYMENT - warehouse charges
  • REDIRECT - redirect shipment
  • SEND_BACK - return to sender
  • MONEY_TRANSFER - money transfer
  • TRANSPORT_DAMAGED - damaged shipment transport
  • VOUCHER_RETURN - return with voucher

2.1.17 Secondary Shipments Response (SecondaryShipmentsResponse)

SecondaryShipmentsResponse

Name

Type

Data

shipments

SecondaryShipment[]

List of secondary shipments

error

Error

Response error

2.1.18 Secondary Shipments Request - URL (GET) schema

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

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

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

SecondaryShipmentsRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

types

enum[] (array with values from enum:

[“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”])

(Same as enum in field type in PrimaryShipment)

Yes

Comma separated list of secondry shipment types. Filters the list for shipments of the specified type(s) only. No filter is applied if not provided (all secondary shipments are returned).

  • RETURN_SHIPMENT - any of return of documents (rod) / returnReceipt / swap / return of pallets (rop)
  • STORAGE_PAYMENT - warehouse charges
  • REDIRECT - redirect shipment
  • SEND_BACK - return to sender
  • MONEY_TRANSFER - money transfer
  • TRANSPORT_DAMAGED - damaged shipment transport
  • VOUCHER_RETURN - return with voucher

2.1.19 Update Shipment Request (UpdateShipmentRequest)

Web service URL: BASE_URL/shipment/update

Method: POST

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

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

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

Input parameters:

UpdateShipmentRequest

Name

Type

Required

Data

Constraints

CreateShipmentRequest fields are here

id

String

Yes

Shipment id

Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update

2.1.20 Update Shipment Response (UpdateShipmentResponse)

Response is CreateShipmentResponse - same returned in createShipment method

Output parameters:

UpdateShipmentResponse

Name

Type

Data

CreateShipmentResponse fields are here

2.1.21 Update Shipment - URL (GET) Schema

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

 

Web service URL:  BASE_URL/shipment/update

Method: GET

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

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

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

The response is the same as method using JSON schema.

URL parameters:

UpdateShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

CreateShipmentRequest params are here

id

String

Yes

Shipment id

Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update

2.1.22 Update Shipment Properties Request (UpdateShipmentPropertiesRequest)

Web service URL: BASE_URL/shipment/update/properties

Method: POST

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

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

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

Input parameters:

UpdateShipmentPropertiesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

id

String

Yes

Shipment id

Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update

properties

Map<String, String>

Yes

The map key is shipment property name and the map value is new propery value to be set in shipment.

The allowed key (property) names are the same as url parameter names (synonims) defined in CreateShipmentRequest

The values expected to be in the format defined for corresponding url parameter in that method sepcification.

Example Request:

{

   "userName":"testUser",

   "password":"password",

   "id":"89988881389",

   "properties":{

      "total_weight":13,

      "pickup_date":"2020-04-15"

   }

}

2.1.23 Update Shipment Propeties Response (UpdateShipmentPropertiesResponse)

Response is UpdateShipmentResponse - same returned in updateShipment method

Output parameters:

UpdateShipmentPropertiesResponse

Name

Type

Data

UpdateShipmentResponse fields are here

2.1.24 Update Shipment Properties - URL (GET) Schema

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

 

Web service URL:  BASE_URL/shipment/update/properties

Method: GET

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

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

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

The response is the same as method using JSON schema.

URL parameters:

UpdateShipmentPropertiesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

CreateShipmentRequest params are here

id

String

Yes

Shipment id

Shipment with that id must exisists, should be accessible to method caller and shipment state must allow requested property update

2.1.25 Find Parcels By Reference Request (FindParcelsByRefRequest)

This method returns parcels by reference number

Web service URL:  BASE_URL/shipment/search

Method: POST

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

FindParcelsByRefRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

ref

String

Yes

Client reference

searchInRef

int

Yes

Specifies where to search: 0 means [Ref1 or Ref2], 1 means [Ref1], 2 means [Ref2]

shipmentsOnly

boolean

No

If true - search in shipments only, otherwise in shipment and parcels. Default is true

includeReturns

boolean

No

If true - search in return shipments also. Default is false

fromDateTime

Date

(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)

No

Pick-up date - from. Up to 6 months before

toDateTime

Date

(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)

No

Pick-up date - to

Example JSON:

{

    "userName":"testUser",

    "password":"password",

    "ref":"634",

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

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

}

2.1.26 Find Parcels By Reference Response (FindParcelsByRefResponse)

FindParcelsByRefResponse

Name

Type

Data

barcodes

String[]

List of barcodes found

error

Error

Response error

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

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

Web service URL:  BASE_URL/shipment/search

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindParcelsByRefRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

ref

String

Yes

Client reference

searchInRef | search_in_ref

int

Yes

Specifies where to search: 0 means [Ref1 or Ref2], 1 means [Ref1], 2 means [Ref2]

shipmentsOnly | shipments_only

boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

If true - search in shipments only, otherwise in shipment and parcels. Default is true

includeReturns | include_returns

boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

If true - search in return shipments also. Default is false

fromDateTime | from_date_time

Date

(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)

No

Pick-up date - from. Up to 6 months before

toDateTime | to_date_time

Date

(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)

No

Pick-up date - to

2.1.28 Handover To Courier Request (HandoverToCourierRequest)

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

ParcelHandover[]

Yes

Parcel barcodes with datetime to register handover to courier operations

Should refer accessible shipment parcels

2.1.29 Handover To Courier Response (HandoverToCourierResponse)

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

HandoverToCourierResponse

Name

Type

Data

error

Error

Response error

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

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

Web service URL:  BASE_URL/shipment/handover

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

HandoverToCourierRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

parcels

String

Format:

<id>,<dateTime>

Multiple items are separated with %7C (‘|’) character. Datetime is in format dd.MM.yyyy HH:mm:ss

No

Parcel ids

Should refer accessible shipment parcels

externalCarrierParcels | external_carrier_parcels

String

Format:

<externalCarrierParcelId>,<dateTime>

Multiple items are separated with %7C (‘|’) character. Datetime is in format dd.MM.yyyy HH:mm:ss

No

External carrier parcel ids

Should refer accessible shipment parcels

2.1.31 Handover To Midway Carrier Request (HandoverToMidwayCarrierRequest)

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

MidwayCarrierParcelHandover[]

Yes

Parcel barcodes with datetime, country and site name to register handover to midway carrier operations

Should refer accessible shipment parcels

2.1.32 Handover To Midway Carrier Response (HandoverToMidwayCarrierResponse)

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

HandoverToMidwayCarrierResponse

Name

Type

Data

error

Error

Response error

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

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

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

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

HandoverToMidwayCarrierRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

parcels

String

Format:

<id>,<countryId>,<dateTime>,<siteName>

or

<id>,<countryId>,<dateTime>

Multiple items are separated with %7C (‘|’) character. Datetime is in format dd.MM.yyyy HH:mm:ss

No

Parcel ids

Should refer accessible shipment parcels

2.1.34 Barcode Information Request (BarcodeInformationRequest)

Get parcel information by parcel barcode

Web service URL:  BASE_URL/shipment/barcode-information

Method: POST

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

BarcodeInformationRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

parcel

ShipmentParcelRef

Yes

Parcel to get info for

Validated for allowed access.

Example JSON:

{

    "userName":"testUser",

    "password":"password",

    "parcel": {

      "fullBarcode":"1000509431237540020002030017"    

   }

}

2.1.35 Barcode Information Response (BarcodeInformationResponse)

Barcode information response

BarcodeInformationResponse

Name

Type

Data

labelInfo

LabelInfo

Label info

primaryShipment

PrimaryShipment

Primary shipment.

primaryParcelId

String

Primary parcel id.

returnShipmentId

String

Return shipment id.

returnParcelId

String

Return parcel id.

redirectShipmentId

String

Redirect shipment id.

redirectParcelId

String

Redirect parcel id.

initialShipmentId

String

Initial shipment id.

initialParcelId

String

Initial parcel id.

error

Error

Response error

Example JSON:

{

    "labelsInfo”: {

        "hubId": 2,

        "officeId": 2,

        "deadlineDay": 18,

        "deadlineMonth": 2,

        "tourId": 2203,

        "fullBarcode": "1000509431237540020002030017"

   },

   "initialShipmentId": "50943123000"

}

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

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

Web service URL:  BASE_URL/shipment/barcode-information

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

BarcodeInformationRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

fullBarcode | full_barcode

String

Yes if no id or externalCarrierParcelNumber is provided

Full barcode

Validated for allowed access.

id

String

Yes if no fullBarcode or externalCarrierParcelNumber is provided

Parcel id

Validated for allowed access.

externalCarrierParcelNumber | external_carrier_parcel_number

String

Yes if no id or fullBarcode is provided

External carrier parcel number

Validated for allowed access.

Example request:

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

2.2 Print Service

Web service URL: BASE_URL/print

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

PDF Examples:

2.2.1 Print Request (PrintRequest)

Web service URL:  BASE_URL/print

Method: POST

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

PrintRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

format

enum

[“pdf”, “zpl”]

No

(default is pdf)

Output format

paperSize

enum

[“A4”, “A6”, “A4_4xA6”]

Yes

Print paper size

Validated for allowed format. For example zpl is allowed with A6 only.

parcels

ParcelToPrint[]

Yes

Parcels to print

Validated for allowed access.

printerName

String

No

Printer name to be used for direct printing.

dpi

enum

[“dpi203”, “dpi300”]

No

(default is dpi203)

Dpi used for rendering. Makes sense for zpl format, otherwise ignored

additionalWaybillSenderCopy

enum

[“NONE”, “ON_SAME_PAGE”, “ON_SINGLE_PAGE”]

No

(default is NONE)

Defines whether and how to print additional waybill copy for sender.

A4 pdf printing is required if print mode is different than NONE.

Example JSON:

{

    "userName":"testUser",

    "password":"password",

    "paperSize":"A4_4xA6",

    "parcels": [

        {

          "parcel": {

             "id":"80002338331"    

          }

       },

       {

          "parcel": {

             "id":"80002338159"    

          }

       }

     ]

}

2.2.2 Print Response (PrintResponse)

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

Content-type: application/pdf

And content contains pdf bytes.

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

Content-type:text/plain

And content contains zpl text string.

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

Content-type:application/json

And content is a JSON with Error structure.

2.2.3 Print Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/print

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

PrintRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

format

enum

[“pdf”, “zpl”]

No

(default is pdf)

Output format

paperSize | paper_size

enum

[“A4”, “A6”, “A4_4xA6”]

Yes

Print paper size

Validated for allowed format. For example zpl is allowed with A6 only.

parcels

String

Format:

<id>,

<additionalBarcodeValue>, <additionalBarcodeLabel>, <additionalBarcodeFormat>

Multiple parcels are separated with %7C (‘|’) character

No

Parcels to print.

Parcel parameters are parsed in the order of their occurrence and missing parameters are considered empty.

externalCarrierParcels | external_carrier_parcels

String

Format:

<externalCarrierParcelId>, <additionalBarcodeValue>, <additionalBarcodeLabel>, <additionalBarcodeFormat>

Multiple parcels are separated with %7C (‘|’) character

No

External carrier parcels to print.

Parcel parameters are parsed in the order of their occurrence and missing parameters are considered empty.

printerName | printer_name

String

No

Printer name to be used for direct printing. Includes javascript in pdf to print document directly to the provided printer on document opening. Make sense for pdf printing.

dpi

enum

[“dpi203”, “dpi300”]

No

(default is dpi203)

Dpi used for rendering. Makes sense for zpl format, otherwise ignored

additionalWaybillSenderCopy | additional_waybill_wender_copy

enum

[“NONE”, “ON_SAME_PAGE”, “ON_SINGLE_PAGE”]

No

(default is NONE)

Defines whether and how to print additional waybill copy for sender.

A4 pdf printing is required if print mode is different than NONE.

2.2.4 Extended Print Request

Web service URL:  BASE_URL/print/extended

Method: POST

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

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

2.2.5 Extended Print Response (ExtendedPrintResponse)

ExtendedPrintResponse

Name

Type

Data

data

byte[]

(BASE64 encoded string)

Response data - base64 encoded binary data (pdf)

printLabelsInfo

LabelInfo[]

Print labels info

error

Error

Response error

Example JSON:

{

    "data": "ADABDAS..."

    "labelsInfo”: [

        {

          "parcelId": "50943123754",

          "hubId": 2,

          "officeId": 2,

          "deadlineDay": 18,

          "deadlineMonth": 2,

          "tourId": 2203,

          "fullBarcode": "1000509431237540020002030017"

        }

    ]

}

2.2.6 Extended Print Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/print/extended

Method: GET

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

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

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

2.2.7 Label Info Request (LabelInfoRequest)

Web service URL:  BASE_URL/print/labelInfo

Method: POST

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

LabelInfoRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

parcels

ShipmentParcelRef[]

Yes

Parcels to get label info for

Validated for allowed access.

Example JSON:

{

    "userName":"testUser",

    "password":"password",

    "parcels": [

        {

          {

             "id":"80002338331"    

          }

       },

       {

          {

             "id":"80002338159"    

          }

       }

     ]

}

2.2.8 Label Info Response (LabelInfoResponse)

LabelInfoResponse

Name

Type

Data

printLabelsInfo

LabelInfo[]

Print labels info

error

Error

Response error

Example JSON:

{

    "labelsInfo”: [

        {

          "parcelId": "50943123754",

          "hubId": 2,

          "officeId": 2,

          "deadlineDay": 18,

          "deadlineMonth": 2,

          "tourId": 2203,

          "fullBarcode": "1000509431237540020002030017"

        }

    ]

}

2.2.9 Label Info Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/print/labelInfo

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

LabelInfoRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

parcels

String

Format:

<id>

Multiple parcels are separated with %7C (‘|’) character.

No

Parcels to get print label info for.

Validated for allowed access.

externalCarrierParcels | external_carrier_parcels

String

Format:

<externalCarrierParcelId>

Multiple parcels are separated with %7C (‘|’) character.

No

External carrier parcels to get print label info for.

2.2.10 Print Voucher Request (PrintVoucherRequest)

Web service URL:  BASE_URL/print/voucher

Method: POST

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

PrintVoucherRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

shipmentIds

String[]

Yes

Shipment ids

Validated for allowed access. All shipments must have voucher request

printerName

String

No

Printer name to be used for direct printing. Includes javascript in pdf to print document directly to the provided printer on document opening.

format

enum

[“pdf”, “zpl”]

No

(default is pdf)

Output format

dpi

enum

[“dpi203”, “dpi300”]

No

(default is dpi203)

Dpi used for rendering. Makes sense for zpl format, otherwise ignored

Example JSON:

{

    "userName":"testUser",

    "password":"password",

    "shipmentIds": ["80002338331"]

}

2.2.11 Print Voucher Response (PrintVoucherResponse)

The result content type is application/pdf.

Content-type: application/pdf

And content contains pdf bytes.

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

Content-type:application/json

And content is a JSON with Error structure.

2.2.12 Print Voucher Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/print/voucher

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

PrintVoucherRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentIds | shipment_ids

String (comma separated shipment ids)

Yes

Shipment ids.

Validated for allowed access. All shipments must have voucher request

printerName | printer_name

String

No

Printer name to be used for direct printing. Includes javascript in pdf to print document directly to the provided printer on document opening.

2.3 Track And Trace Service

Web service URL: BASE_URL/track

2.3.1 Track Request (TrackRequest)

Web service URL:  BASE_URL/track

Method: POST

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

TrackRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

parcels

TrackShipmentParcelRef[]

Yes

Parcels to track

lastOperationOnly

Boolean

No

Flag to return last operation only’

2.3.2 Track Response (TrackResponse)

TrackResponse

Name

Type

Mandatory

Data

parcels

TrackedParcel[]

Yes

Parcel track information

error

Error

No

Response error

2.3.3 Track Request - URL (GET) schema

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

 

Web service URL: BASE_URL/track

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

TrackRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

parcels

String

Format:

<id>

Multiple parcels are separated with %7C (‘|’) character.

No

Parcel ids to track

externalCarrierParcels | external_carrier_parcels

String

Format:

<externalCarrierParcelId>

Multiple parcels are separated with %7C (‘|’) character.

No

External carrier parcel ids to track

refs

String

Format:

<ref>

Multiple parcels are separated with %7C (‘|’) character.

No

Parcel references to search and track referred parcels

lastOperationOnly | last_opeartion_only

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Flag to return last operation only.

Example:

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

2.3.4 Bulk Tracking Data Files Request (BulkTrackingDataFilesRequest)

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

A greater file id corresponds to a later file publishing.

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

 

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

 

Web service URL:  BASE_URL/track/bulk

Method: POST

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

BulkTrackingDataFilesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

lastProcessedFileId

Long

Yes

The greatest data file id processed in client system. To get all published data files during last 10 days use 0 as lastProcessedFileId

The last processed file id must refer to a file published during last 10 days. Otherwise, error is returned.

2.3.5 Bulk Tracking Data Files Response (BulkTrackingDataFilesResponse)

BulkTrackingDataFilesResponse

Name

Type

Mandatory

Data

files

BulkTrackingDataFile[]

Yes

Bulk traking data files ordered by file id in ascending order. The geratest file id returned in this response is expected to be passed in next request for incremental processing

error

Error

No

Response error

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

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

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

A greater file id corresponds to a later file publishing.

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

 

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

 

Web service URL: BASE_URL/track/bulk

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

BulkTrackingDataFilesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

last_processed_file_id

Long

Yes

The greatest data file id processed in client system. To get all published data files during last 10 days use 0 as lastProcessedFileId

The last processed file id must refer to a file published during last 10 days. Otherwise, error is returned.

2.4 Pickup

Web service URL: BASE_URL/pickup

2.4.1 Pickup Request (PickupRequest)

Web service URL:  BASE_URL/pickup

Method: POST

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

PickupRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

pickupDateTime

Date

(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)

No

Pickup datetime. If not provided, it is assumed now. Seconds and milliseconds are ignored.

autoAdjustPickupDate

Boolean

No (default value is false)

To find first available date for pickup starting from pickupDate according to pickup schedule for services

pickupScope

enum

[“EXPLICIT_SHIPMENT_ID_LIST”,

“ALL_CREATED_BY_LOGGED_USER”,

“ALL_CREATED_BY_SAME_CLIENT”]

“ALL_CREATED_BY_SAME_CONTRACT_USERS”]

No

Default is EXPLICIT_SHIPMENT_ID_LIST

Scope of shipments to order.

ALL_CREATED_BY_SAME_CONTRACT_USERS can be used in case a logged user have the access rights to access shipments created by other users in the same contract.

explicitShipmentIdList

String[]

No

Required when pickup scope is EXPLICIT_SHIPMENT_ID_LIST

visitEndTime

String (format HH:ss)

Yes

Example 9:30, or 11:35

The last possible time when the address could be visited on the pickup date.

contactName

String

No

Contact name.

phoneNumber

ShipmentPhoneNumber

No

Customer’s phone number.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

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

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

  "visitEndTime": 18:20

}

2.4.2 Pickup Response (PickupResponse)

PickupResponse

Name

Type

Mandatory

Data

orders

PickupOrder[]

Yes

Pickup orders created

error

Error

No

Response error

2.4.3 Pickup Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/pickup

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

PickupRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

pickupDateTime | pickup_date_time

Date

(String in format “dd.MM.yyyy HH:mm”)

No

Pickup date time. If not provided it is assumed the current datetime.Seconds and milliseconds are ignored.

autoAdjustPickupDate | auto_adjust_pickup_date | autoadjust_pickup_date

Boolean

No (default is false)

To find first available date for pickup starting from pickupDate according to pickup schedule for services

pickupScope | pickup_scope

enum

[“EXPLICIT_SHIPMENT_ID_LIST”,

“ALL_CREATED_BY_LOGGED_USER”,

“ALL_CREATED_BY_SAME_CLIENT”,

“ALL_CREATED_BY_SAME_CONTRACT_USERS”]

No

Default is EXPLICIT_SHIPMENT_ID_LIST

Scope of shipments to order.

ALL_CREATED_BY_SAME_CONTRACT_USERS can be used in case a logged user have the access rights to access shipments created by other users in the same contract.

explicitShipmentIdList | explicit_shipment_id_list

String

(comma separated list of ids)

No

Required when pickup scope is EXPLICIT_SHIPMENT_ID_LIST

visitEndTime | visit_end_time

String (format HH:ss)

Yes

The last possible time when the address could be visited on the pickup date.

contactName | contact_name

String

No

Contact name.

phoneNumber | phone_number

String

No

Customer’s phone number.

Validated for valid phone number.

phoneNumberExt | phone_number_ext

String

No

Customer’s phone number extension.

Validated for valid phone number extension.

Example:

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

2.4.4 Pickup Terms Request (PickupTermsRequest)

Web service URL:  BASE_URL/pickup/terms

Method: POST

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

PickupTermsRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

serviceId

int

Yes

Service Id

startingDate

Date

(String in format “yyyy-MM-dd”)

No

The first date when the shipment will be ready for pickup. If not provided, it is assumed today.

Should not be a date before today

sender

CalculationSender

No (If not specifed, logged user is used)

Client and location for pickup.

senderHasPayment

Boolean

No

Flag to indicate, whether sender should pay at least one of courier service, declared value or packings.If this parameter is missing assumed value is - false.

2.4.5 Pickup Terms Response (PickupTermsResponse)

PickupTermsResponse

Name

Type

Mandatory

Data

cutoffs

DateTime[]

(format yyyy-MM-dd'T'HH:mm:ssZ)

Yes

Pickup cutoffs for next days. Pickup is not allowed for missing days in the result list

error

Error

No

Response error

2.4.6 Pickup Terms Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/pickup/terms

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

PickupTermsRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

serviceId | service_id

int

Yes

Service id

startingDate | starting_date

Date

(String in format “yyyy-MM-dd”)

No

The first date when the shipment will be ready for pickup. If not provided, it is assumed today.

Should not be a date before today

Calculation sender details

If logged user is the sender, you may skip providing sender details at all.

If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also.

Otherwise, sender_id should stay empty and it is required to provide as a minimum:

  • sender privatePerson flag
  • sender address location or dropoffOfficeId

senderId | sender_id

Long

No

Client id to refer а sender

Validate for existence.

senderPrivatePerson | sender_private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory

Sender private person flag.

Sender Address Location Details

See AddressLocation for more details.

The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at sender’s address is expected.

senderAddressCountryId | sender_address_country_id

Integer

No

Country ISO code. If not provided, the local country is assumed. Used for all address types.

Validate for valid country code

senderAddressStateId | sender_address_state_id

String

Required if country requires state

Country state. Used for addresses of type 2 (foreign address).

Validate for valid country state.

senderAddressSiteId | sender_address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided

Site id. Used for all address types

Validate for valid site and value is required

senderAddressSiteType | sender_address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)

Max 20 characters

senderAddressSiteName | sender_address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.

Max 50 characters

senderAddressPostcode | senderAddressPostCode | sender_address_postcode

String

No

Can be used in conjunction with countryId to find unique site. Used for all address types

Max 10 characters

dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId | senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id

Integer

Required, if the sender is an internal customer. If sender address is provided, it is forbidden.

Drop off office id.

Should refer to a valid accessible office

senderHasPayment | sender_has_payment

Boolean

No

Flag to indicate, whether sender should pay at least one of

courier service

declared value

or packings.

If this parameter is missing assumed value is - false.

Example:

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

2.5 Location Service

Web service URL: BASE_URL/location

2.5.1 Country

This section specifies methods to query system for allowed countries

Web service URL: BASE_URL/location/country

2.5.1.1 Get Country Request (GetCountryRequest)

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

Method: POST

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

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

GetCountryRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.1.2 Get Country Response (GetCountryResponse)

GetCountryResponse

Name

Type

Mandatory

Data

country

Country

No

Found country or null if not found

error

Error

No

Response error

2.5.1.3 Get Country Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetCountryRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.1.4 Find Country Request (FindCountryRequest)

Web service URL:  BASE_URL/location/country

Method: POST

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

Find country using search criteria

FindCountryRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

name

String

No

Country search term. Filters the results by country name prefix or part of country name

isoAlpha2

String

No

Country iso alpha 2. Filters result by exact match if presents. ISO alpha 2 value uniquely identifies country and other criterias are not needed if this one presents

isoAlpha3

String

No

Country iso alpha 3. Filters result by exact match if presents. ISO alpha 3 value uniquely identifies country and other criterias are not needed if this one presents

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "name":"ROMA"

}

2.5.1.5 Find Country Response (FindCountryResponse)

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

The result is limited to 10 records.

FindCountryResponse

Name

Type

Mandatory

Data

countries

Country[]

No

Array of countries

error

Error

No

Response error

2.5.1.6 Find Country Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/country

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindCountryRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

name

String

No

Country search term. Filters the results by country name prefix or part of country name

isoAlpha2 | iso_alpha2

String

No

Country iso alpha 2. Filters result by exact match if presents. ISO alpha 2 value uniquely identifies country and other criterias are not needed if this one presents

isoAlpha3 | iso_alpha3

String

No

Country iso alpha 3. Filters result by exact match if presents. ISO alpha 3 value uniquely identifies country and other criterias are not needed if this one presents

Example:

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

2.5.1.7 Get All Countries Request (GetAllCountriesRequest)

Web service URL:  BASE_URL/location/country/csv

Method: POST

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

Get all countries as csv file

GetAllCountriesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.1.8 Get All Countries Response (GetAllCountriesResponse)

See Country data structure for additional information.

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

2.5.1.9 Get All Countries Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/country

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

GetAllCountriesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.2 State

This section specifies methods to query system for allowed states

Web service URL: BASE_URL/location/state

2.5.2.1 Get State Request (GetStateRequest)

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

Method: POST

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

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

GetStateRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.2.2 Get State Response (GetStateResponse)

GetStateResponse

Name

Type

Mandatory

Data

site

State

No

State found or null if not found

error

Error

No

Response error

2.5.2.3 Get State Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetStateRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.2.4 Find State Request (FindStateRequest)

Web service URL:  BASE_URL/location/state

Method: POST

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

Find state using search criteria

FindStateRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

countryId

integer

Yes

Country id

name

String

No

Search term for state name. Filters the results by state name prefix or part of state name.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "countryId":840,

  "name":"A"

}

2.5.2.5 Find State Response (FindStateResponse)

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

The result is limited to 10 records.

FindStateResponse

Name

Type

Mandatory

Data

states

State[]

No

Array of sites

error

Error

No

Response error

2.5.2.6 Find State Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/state

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindStateRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

countryId | country_id

integer

Yes

Country id

name

String

No

Search term for state name. Filters the results by state name prefix or part of state name.

Example:

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

2.5.2.7 Get All States Request (GetAllStatesRequest)

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

Method: POST

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

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

GetAllStatesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.2.8 Get All States Response (GetAllStatesResponse)

See State data structure for additional information.

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

2.5.2.9 Get All States Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetAllStatesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.3 Site

This section specifies methods to query system for allowed sites

Web service URL: BASE_URL/location/site

2.5.3.1 Get Site Request (GetSiteRequest)

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

Method: POST

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

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

GetSiteRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.3.2 Get Site Response (GetSiteResponse)

GetSiteResponse

Name

Type

Mandatory

Data

site

Site

No

Found site or null if not found

error

Error

No

Response error

2.5.3.3 Get Site Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetSiteRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.3.4 Find Site Request (FindSiteRequest)

Web service URL:  BASE_URL/location/site

Method: POST

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

Find site using search criteria

FindSiteRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

countryId

integer

Yes

Country id

name

String

No

Search term for site name. Filters the results by site name prefix or part of site name.

postCode

String

No

Filter results by postcode - valid postcode for site

type

String

No

Filter results by site type (exact match)

municipality

String

No

Filter by municipality (prefix match)

region

String

No

Filter by region (prefix match)

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "countryId":642,

  "name":"A"

}

2.5.3.5 Find Site Response (FindSiteResponse)

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

The result is limited to 10 records.

FindSiteResponse

Name

Type

Mandatory

Data

sites

Site[]

No

Array of sites

error

Error

No

Response error

2.5.3.6 Find Site Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/site

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindSiteRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

countryId | country_id

integer

Yes

Country id

name

String

No

Search term for site name. Filters the results by site name prefix or part of site name.

postcode | postCode | post_code

String

No

Filter results by postcode - valid postcode for site

type

String

No

Filter results by site type (exact match)

municipality

String

No

Filter by municipality (prefix match)

region

String

No

Filter by region (prefix match)

Example:

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

2.5.3.7 Get All Sites Request (GetAllSitesRequest)

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

Method: POST

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

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

GetAllSitesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.3.8 Get All Sites Response (GetAllSitesResponse)

See Site data structure for additional information.

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

2.5.3.9 Get All Sites Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetAllSitesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.4 Street

This section specifies methods to query system for allowed streets

Web service URL: BASE_URL/location/street

2.5.4.1 Get Street Request (GetStreetRequest)

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

Method: POST

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

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

GetStreetRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.4.2 Get Street Response (GetStreetResponse)

GetStreetResponse

Name

Type

Mandatory

Data

street

Street

No

Found street or null if not found

error

Error

No

Response error

2.5.4.3 Get Street Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetStreetRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.4.4 Find Street Request (FindStreetRequest)

Web service URL:  BASE_URL/location/street

Method: POST

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

Find street using search criteria

FindStreetRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

siteId

integer

Yes

Site id

name

String

No

Search term for street name. Filters the results by street name prefix or part of street name.

type

String

No

Filter results by street type (exact match)

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "siteId":642279132,

  "name":"A"

}

2.5.4.5 Find Street Response (FindStreetResponse)

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

The result is limited to 10 records.

FindStreetResponse

Name

Type

Mandatory

Data

streets

Street[]

No

Array of streets

error

Error

No

Response error

2.5.4.6 Find Street Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/street

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindStreetRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

siteId | site_id

long

Yes

Site id

name

String

No

Search term for street name. Filters the results by street name prefix or part of street name.

type

String

No

Filter results by street type (exact match)

Example:

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

2.5.4.7 Get All Streets Request (GetAllStreetsRequest)

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

Method: POST

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

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

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

To obtain such license please contact your key account manager.

GetAllStreetsRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.4.8 Get All Streets Response (GetAllStreetsResponse)

See Street data structure for additional information.

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

2.5.4.9 Get All Streets Request - URL (GET) schema

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

 

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

Method: GET

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

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

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

To obtain such license please contact your key account manager.

URL parameters:

GetAllStreetsRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.5 Complex

This section specifies methods to query system for allowed complexes

Web service URL: BASE_URL/location/complex

2.5.5.1 Get Complex Request (GetComplexRequest)

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

Method: POST

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

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

GetComplexRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.5.2 Get Complex Response (GetComplexResponse)

GetComplexResponse

Name

Type

Mandatory

Data

complex

Complex

No

Complex found or null if not found

error

Error

No

Response error

2.5.5.3 Get Complex Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetComplexRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.5.4 Find Complex Request (FindComplexRequest)

Web service URL:  BASE_URL/location/complex

Method: POST

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

Find complex using search criteria

FindComplexRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

siteId

integer

Yes

Site id

name

String

No

Search term for complex name. Filters the results by complex name prefix or part of complex name.

type

String

No

Filter results by complex type (exact match)

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "siteId":100,

  "name":"A"

}

2.5.5.5 Find Complex Response (FindComplexResponse)

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

The result is limited to 10 records.

FindComplexResponse

Name

Type

Mandatory

Data

complexes

Complex[]

No

Array of complexes

error

Error

No

Response error

2.5.5.6 Find Complex Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/complex

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindComplexRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

siteId | site_id

long

Yes

Site id

name

String

No

Search term for complex name. Filters the results by xomplex name prefix or part of xomplex name.

type

String

No

Filter results by complex type (exact match)

Example:

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

2.5.5.7 Get All Complexes Request (GetAllComplexesRequest)

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

Method: POST

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

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

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

To obtain such license please contact your key account manager.

GetAllComplexesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.5.8 Get All Complexes Response (GetAllComplexesResponse)

See Complex data structure for additional information.

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

2.5.5.9 Get All Complexes Request - URL (GET) schema

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

 

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

Method: GET

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

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

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

To obtain such license please contact your key account manager.

URL parameters:

GetAllComplexesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.6 Block

This section specifies methods to query system for allowed blocks

Web service URL: BASE_URL/location/block

2.5.6.1 Find Block Request (FindBlockRequest)

Web service URL:  BASE_URL/location/block

Method: POST

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

Find block using search criteria

FindBlockRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

siteId

integer

Yes

Site id

name

String

No

Search term for block name. Filters the results by block name prefix or part of block name.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "siteId":10135,

  "name":"A"

}

2.5.6.2 Find Block Response (FindBlockResponse)

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

The result is limited to 10 records.

FindBlockResponse

Name

Type

Mandatory

Data

blocks

Block[]

No

Array of blocks

error

Error

No

Response error

2.5.6.3 Find Block Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/block

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindBlockRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

siteId | site_id

long

Yes

Site id

name

String

No

Search term for block name. Filters the results by block name prefix or part of block name.

Example:

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

2.5.6.4 Get All Blocks Request (GetAllBlocksRequest)

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

Method: POST

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

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

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

To obtain such license please contact your key account manager.

GetAllBlockRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.6.5 Get All Blocks Response (GetAllBlocksResponse)

See Block data structure for additional information.

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

2.5.6.6 Get All Blocks Request - URL (GET) schema

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

 

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

Method: GET

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

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

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

To obtain such license please contact your key account manager.

URL parameters:

GetAllBlocksRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.7 POI (Point of Interest)

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

Web service URL: BASE_URL/location/poi

2.5.7.1 Get POI Request (GetPOIRequest)

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

Method: POST

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

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

GetPOIRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.7.2 Get POI Response (GetPOIResponse)

GetPOIResponse

Name

Type

Mandatory

Data

poi

PointOfInterest

No

POI found or null if not found

error

Error

No

Response error

2.5.7.3 Get POI Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetPOIRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.7.4 Find POI Request (FindPOIRequest)

Web service URL:  BASE_URL/location/poi

Method: POST

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

Find POI using search criteria

FindPOIRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

siteId

integer

Yes

Site id

name

String

No

Search term for POI name. Filters the results by POI name prefix or part of POI name.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "siteId":100,

  "name":"A"

}

2.5.7.5 Find POI Response (FindPOIResponse)

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

The result is limited to 10 records.

FindPOIResponse

Name

Type

Mandatory

Data

pois

PointOfInterest[]

No

Array of points of interest

error

Error

No

Response error

2.5.7.6 Find POI Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/poi

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindPOIRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

siteId | site_id

long

Yes

Site id

name

String

No

Search term for POI name. Filters the results by POI name prefix or part of POI name.

Example:

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

2.5.7.7 Get All Points of Interest Request (GetAllPOIRequest)

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

Method: POST

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

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

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

To obtain such license please contact your key account manager.

GetAllPOIRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.7.8 Get All Points of Interest Response (GetAllPOIResponse)

See PointOfInterest data structure for additional information.

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

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

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

 

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

Method: GET

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

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

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

To obtain such license please contact your key account manager.

URL parameters:

GetAllPOIRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.8 Postcodes

This section specifies methods to query system for allowed country postcodes

Web service URL: BASE_URL/location/postcode

2.5.8.1 Get All Postcodes Request (GetAllPostcodesRequest)

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

Method: POST

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

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

GetAllPostcodesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.8.2 Get All Postcodes Response (GetAllPostcodesResponse)

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

2.5.8.3 Get All Postcodes Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetAllPostcodesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.9 Office

This section specifies methods to query system for available offices

Web service URL: BASE_URL/location/office

2.5.9.1 Get Office Request (GetOfficeRequest)

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

Method: POST

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

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

GetOfficeRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

Example JSON:

{

  "userName":"testUser",

  "password":"password",

}

2.5.9.2 Get Office Response (GetOfficeResponse)

GetOfficeResponse

Name

Type

Mandatory

Data

office

Office

No

Office found or null if not found

error

Error

No

Response error

2.5.9.3 Get Office Request - URL (GET) schema

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

 

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

Method: GET

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

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

URL parameters:

GetOfficeRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Example:

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

2.5.9.4 Find Office Request (FindOfficeRequest)

Web service URL:  BASE_URL/location/office

Method: POST

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

Find office using search criteria

FindOfficeRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

countryId

Integer

No

Country id ISO. Limits the search scope in the set of offices for specified country. System default country is used if country id is omitted. If -1 is specified - offices in all countires are searched

siteId

Long

No

Site id. Limits the search scope in the set of offices for specified site. If omitted - all country offices are searched

siteName

String

No

Filters the results by office site name prefix or part of it.

name

String

No

Search term for office name. Filters the results by office name prefix or part of site name.

limit

Long

No

The number of records to return in response. All records are returned if this parameter is ommited

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "countryId":642,

  "name":"A"

}

2.5.9.5 Find Office Response (FindOfficeResponse)

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

FindOfficeResponse

Name

Type

Mandatory

Data

offices

Office[]

No

Array of offices

error

Error

No

Response error

2.5.9.6 Find Office Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/location/office

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindOfficeRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

countryId | country_id

Integer

No

Country id ISO. Limits the search scope in the set of offices for specified country. System default country is used if country id is omitted. If -1 is specified - offices in all countires are searched.

siteId | site_id

Long

No

Site id.Limits the search scope in the set of offices for specified site. If omitted - all country offices are searched

siteName | site_name

String

No

Filters the results by office site name prefix or part of it

name

String

No

Search term for office name. Filters the results by office name prefix or part of office name.

limit

Long

No

The number of records to return in response. All records are returned if this parameter is ommited

Example:

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

2.5.9.7 Find Nearest Offices Request (FindNearestOfficesRequest)

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

Method: POST

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

Find nearest offices using search criteria

FindNearestOfficesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

address

ShipmentAddress

Yes

Address to which the nearest offices are searched

Only country id is mandatory

distance

Integer

No

Maximum office distance ( in meters ) from provided address

limit

Integer

No

The number of records to return in response.

officeType

enum ["OFFICE", "APT"]

No

Filter offices by type.

officeFeatures

enum ["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][]

No

Supported office features

Example JSON:

{

  "userName":"testUser",

  "password":"password",

  "address" {

    "countryId":100,

    "siteName":"Sofia"

  }

  "distance":1500,

  "officeFeatures" [

    "CARD_PAYMENT"

  ]

}

2.5.9.8 Find Nearest Offices Response (FindNearestOfficesResponse)

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

FindNearestOfficesResponse

Name

Type

Mandatory

Data

offices

OfficeResult[]

No

Array of offices

x

Double

No

Provided address X coord

y

Double

No

Provided address Y coord

error

Error

No

Response error

2.5.9.9 Find Nearest Offices - URL (GET) schema

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

 

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

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FindNearestOfficesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Shipment Address

See ShipmentAddress for more details.

countryId | country_id

Integer

No

Country ISO code. If not provided, the local country is assumed.

Used for all address types.

stateId | state_id

String

Required, if country supports states.

Country state.

Used for addresses of type 2 (foreign address).

siteId | site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided.

Site id.

Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country

siteType | site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for addresses of type 1 (local address).

Max 20

siteName | site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for all address types.

Max 50

postcode | postCode | post_code

String

No

Can be used in conjunction with countryId to find unique site.

Used for all address types.

Validated for valid postcode in site and country.

Max 10

streetId | street_id

Long

No

Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

streetType | street_type

String

No

Forbidden, if street_id is provided.

Street type.

Used for addresses of type 1 (local address).

Max 15

streetName | street_name

String

No

Forbidden, if street_id is provided.

Street name.

Used for addresses of type 1 (local address).

Max 50

streetNumber | street_number

String

No

Street number.

Used for addresses of type 1 (local address).

Max 10

complexId | complex_id

Long

No

Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

complexType | complex_type

String

No

Forbidden, if complex_id is provided.

Complex type.

Used for addresses of type 1 (local address).

Max 15

complexName | complex_name

String

No

Forbidden, if complex_id is provided.

Complex name.

Used for addresses of type 1 (local address).

Max 50

block | blockNo | block_no

String

No

Block No.

Used for addresses of type 1 (local address).

Max 32

entrance | entranceNo | entrance_no

String

No

Entrance.

Used for addresses of type 1 (local address).

Max 10

floor | floorNo | floor_no

String

No

Floor.

Used for addresses of type 1 (local address).

Max 10

apartment | apartmentNo | apartment_no

String

No

Apartment.

Used for addresses of type 1 (local address).

Max 10

poiId | poi_id

Long

No

Point of interest identifier.

Used for addresses of type 1 (local address).

addressNote | address_note | note

String

No

Address note.

Used for addresses of type 1 (local address).

200

addressLine1 | address_line1 | line1

String

Required for address type 2.

Address line 1. Used for addresses of type 2 (foreign address).

Max 35

addressLine2 | address_line2 | line2

String

No

Address line 2. Used for addresses of type 2 (foreign address).

Max 35

X | x

Double

No

GIS coordinates - X.

Used for all address types.

Y | y

Double

No

GIS coordinates - Y.

Used for all address types.

limit

Integer

No

The number of records to return in response.

distance

Integer

No

Maximum office distance ( in meters ) from the provided address

type

Integer

No

enum["CASH", "POSTAL_MONEY_TRANSFER"]

office_features | officeFeatures

Integer

No

enum["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][]

Multiple values are separated with %7C ( '|' ) character.

2.6 Calculation Service

Web service URL: BASE_URL/calculate

2.6.1 Calculation Request (CalculationRequest)

Web service URL:  BASE_URL/calculate

Method: POST

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

CalculationRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

sender

CalculationSender

No

Defines the pickup place. If not specified, the logged user location is considered as a sender location.

recipient

CalculationRecipient

Yes

Defines the recipient delivery place.

service

CalculationService

Yes

Defines service agreemen

content

CalculationContent

Yes

Defines content - parcels, weight and etc

payment

ShipmentPayment

Yes

Defines who-pays-what in shipment

2.6.2 Calculation Response (CalculationResponse)

CalculationResponse

Name

Type

Mandatory

Data

calculations

CalculationResult[][]

Yes

Calculations for all service ids in request

error

Error

No

Response error

2.6.3 Calculation Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/calculate

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

CalculationRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Calculation sender details

If logged user is the sender, you may skip providing sender details at all.

If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also.

Otherwise, sender_id should stay empty and it is required to provide as a minimum:

  • sender privatePerson flag
  • sender address location or dropoffOfficeId

senderId | sender_id

Long

No

Client id to refer а sender

Validate for existence.

senderPrivatePerson | sender_private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory

Sender private person flag.

Sender Address Location Details

See AddressLocation for more details.

The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at sender’s address is expected.

senderAddressCountryId | sender_address_country_id

Integer

No

Country ISO code. If not provided, the local country is assumed. Used for all address types.

Validate for valid country code

senderAddressStateId | sender_address_state_id

String

Required if country requires state

Country state. Used for addresses of type 2 (foreign address).

Validate for valid country state.

senderAddressSiteId | sender_address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided

Site id. Used for all address types

Validate for valid site and value is required

senderAddressSiteType | sender_address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)

Max 20 characters

senderAddressSiteName | sender_address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.

Max 50 characters

senderAddressPostcode | senderAddressPostCode | sender_address_postcode

String

Required if country requires post code

Can be used in conjunction with countryId to find unique site. Used for all address types

Max 10 characters

dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId | senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id

Integer

Required, if the sender is an internal customer. If sender address is provided, it is forbidden.

Drop off office id.

Should refer to a valid accessible office

sender_geo_pudo_id | senderGeoPUDOId | dropoff_geo_pudo_id | dropoffGeoPUDOId

String

No. Must be empty if dropoffOfficeId is provided

DPD drop off office PUDO id

Should refer to a valid accessible DPD office.

Calculation recipient details

If you refer an existing customer, provide client'€™s id in recipient_id parameter and other recipient parameters may be skipped at all

Otherwise, recipient_id should stay empty and it is required to provide as a minimum:.

  • recipient privatePerson flag
  • recipient address location or pickupOfficeId

recipientId | recipient_id

Long

No

Client id to refer а recipient

Validate for existence.

recipientPrivatePerson | recipient_private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

If recipient_id is provided, it is forbidden. Otherwise, it is mandatory

Recipient private person flag.

Recipient Address Location Details

See AddressLocation for more details.

The recipient address location is expected when recipient_id is empty and recipient_pickup_office_id is empty and not required. In other words, the recipient address location is required when the recipient is not a referred customer and delivery at recipient’s address is expected.

recipientAddressCountryId | recipient_address_country_id

Integer

No

Country ISO code. If not provided, the local country is assumed. Used for all address types.

Validate for valid country code

recipientAddressStateId | recipient_address_state_id

String

Required if country requires state

Country state. Used for addresses of type 2 (foreign address).

Validate for valid country state.

recipientAddressSiteId | recipient_address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided

Site id. Used for all address types

Validate for valid site and value is required

recipientAddressSiteType | recipient_address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)

Max 20 characters

recipientAddressSiteName | recipient_address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.

Max 50 characters

recipientAddressPostcode | recipientAddressPostCode | recipient_address_postcode

String

Required if country requires post code

Can be used in conjunction with countryId to find unique site. Used for all address types

Max 10 characters

pickupOfficeId | pickUpOfficeId | recipientPickupOfficeId | recipientPickUpOfficeId | pickup_office_id | recipient_pickup_office_id

Integer

Required, if the recipient is an internal customer. If recipient address is provided, it is forbidden.

Pickup office id.

Should refer to a valid accessible office

recipient_geo_pudo_id | recipientGeoPUDOId | pickup_geo_pudo_id | pickupGeoPUDOId

String

No. Must be empty if pickupOfficeId is provided

DPD pickup office PUDO id

Should refer to a valid accessible DPD office.

Calculation Service Details

See CalculationService for more details.

Shipment service defines agreement with customer for courier service. This includes:

  • Pickup date
  • Service ids (codes)
  • Optional defer days or saturday delivery
  • Additional services (like COD, Declared value,and etc.)

pickupDate | pickup_date

Date (date) Example: “2018-01-22"

No (default value is today)

The date for shipment pick-up

Could be today or a future date.

autoAdjustPickupDate | auto_adjust_pickup_date | autoadjust_pickup_date

Boolean

No (default is false)

To find first available date for pickup starting from pickupDate according to pickup schedule for services

serviceIds | service_ids

String (comma separated service ids)

Yes

Service ids to get calculation for.

Each service id (code) should be valid for destination

deferredDays | deferred_days

Integer

No (default value is 0)

This parameter allowscusers to specify by how many (business) days they would like to postpone the shipment delivery from the standard term..

Allowed values are 0, 1 and 2

saturdayDelivery | saturday_delivery

Boolean

No)

This parameter may adjust the delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured recipient working schedule.

COD Additional Service

For more information see ShipmentCODAdditionalService.

codAmount | cod_amount

double

No

Defines shipment COD base amount.

Validated against maximum allowed amounts for destination.

codCurrency | cod_currency

String

No

(default is the currency code of the destination country)

Defines shipment COD currency code.

Validated against allowed currency code of destination country.

codProcessingType | cod_processing_type

enum

[“CASH”, “POSTAL_MONEY_TRANSFER”]

No

(default is “CASH”)

Defines COD processing type.

Appropriate contract and annexes may be required.

codPayoutThirdParty | cod_payout_third_party

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

If this flag is set, the COD is paid to a third party (not to the  sender).

Requires the third party to be the payer of the courier service.

codWithShippingPrice | cod_with_shipping_price

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Flag indicating whether the shipping price should be included in the COD.

Options before payment details Additional Service

For more information see ShipmentOBPD.

obpd_option

enum

[“OPEN”, “TEST”]

No

(For certain destinations could be required.)

Defines option to be used.

Open parcels before payment or open and test parcels before payment.

Return shipment is validated for destination.

obpd_return_service_id

Integer

No

(For certain destinations could be required.)

Defines service id to be used on return, if COD payment is refused.

Return shipment is validated for destination.

obpd_return_payer

enum

[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]

No

(For certain destinations could be required.)

Defines who pays the return shipment, if COD payment is refused.

Return shipment is validated for destination.

Declared Value (Extended Liability) Additional Service

For more information see ShipmentDeclaredVaueAdditionalService.

Declared value payer is required when declared value amount is provided and is set in payment section.

declaredValueAmount | declared_value_amount

double

No

Defines shipment Declared Value (extended liability) base amount. Declared value amount is always in local system currency.

Validated against maximum allowed amounts.

fragile | declaredValueFragile | declared_value_fragile

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Defines fragile flag for shipment content.

Fragile shipments requires declared value sub service.

declaredValueIgnoreIfNotApplicable | declared_value_ignore_if_not_applicable

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

No

Flag to ignore declared value additional service in case it is not applicable for shipment on calculation

E-shops usually configure declared value (extended liability) by default for their shipments, However there are some certain internal rules when this option is not available. The flag is used in calculation service to provide price to end clients without repeating the calculation request with removed additional service

Fixed Time Delivery Additional Service

Fixed time delivery is an additional service that provides instruction to deliver shipment at a certain time on the delivery date.

fixedTimeDelivery | fixed_time_delivery

Integer

No

This option fixes the time of delivery on the delivery date. 1130 - means 11:30

920 - means 09:20

This option is checked against configured allowed time frame for the service.

Special Delivery Additional Service

Special delivery is an additional service that provides instruction to the courier to do additional (special) checks and actions on delivery. These checks and actions are negotiated and contracted in a special delivery annex. For example, the courier could be instructed to check IDs of recipient party at delivery.

specialDeliveryId | special_delivery_id

Integer

No

Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex.

Requires annex for special delivery.

Delivery to Floor Additional Service

Delivery to floor is an additional service that provides instruction to the courier that the shipment should not be delivered to the entrance of a multi floor building, but should be moved to a certain floor before delivery.

deliveryToFloor | delivery_to_floor

Integer

No

Specifies the floor number in the building where to deliver shipment.

This additional service requires annex.

Calculation Content

For more information see CalculationContent.

Defines what is to be delivered with the shipment.

parcelsCount | parcels_count

Integer

Required when parcels list is empty

Total shipment’s parcels count. Ignored, if parcels list is not empty. The parcels count is the number of parcels in the lits in that case

Validated against minimum and maximum allowed for the service

totalWeight | total_weight

Double

Required when parcels list is empty

Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcel’s weight in that case.

Validated against minimum and maximum allowed for the service

documents

Boolean (true/false, y/n, “yes/no” - all case insensitive)

No

Documents flag of the shipment

palletized

Boolean (true/false, y/n, “yes/no” - all case insensitive)

No

Palletized flag of the shipment

parcels

String

Format for single parcel is:

<seqNo>,<weight>,

<width>x<depth>x<height>,

<packageUniqueNumber>,

<id>,

<externalCarrierParcelNumber>

Multiple parcels should be separated with %7C (‘|’) character.

See ShipmentParcel

Required for pallet and postal services. For multiple parcels add the same url parameter again. The parameters are parsed in the order of their occurrence. If the sequence is incomplete, the missing parameters are considered empty.

List of parcels. If provided, parcel_count and total_weight are ignored

Validated against service configuration and pickup and delivery capacity of the depots and the couriers.

Shipment Payment

For more information see ShipmentPayment.

Defines who-pays-what in shipment and other payment parameters.

courierServicePayer | courier_service_payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

Yes

Courier service payer.

Validated against the service, destination, contracts and annexes.

declaredValuePayer | declared_value_payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

No

Declared value payer. If not provided, the courier service payer is assumed. Not expected, if the declared value amount is empty.

Validated against the service, destination, contracts and annexes.

packagePayer | package_payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

No

Package payer. If not provided, the courier service payer is assumed.

Validated against the service, destination, contracts and annexes.

thirdPartyClientId | third_party_client_id

Long

No

Defines shipment third party - used as a payer of any of shipment payable components.

Third party customer should be registered customer with valid contract and annex for delayed payment at pickup date. Third party customer should be customer(object) in the same contract as the logged user.

Discount card

For more information see ShipmentDiscountCardId.

Discount cards provide promotional discounts.

discountCardContractId | discount_card_contract_id

Long

No

Discount card contract id.

Validated against a referred contract.

discountCardId | discount_card_id

Long

No

Discount card id for contract.

Validated against a referred discount card.

2.7 Client Service

Web service URL: BASE_URL/client

2.7.1 Get Client Request (GetClientRequest)

Web service URL:  BASE_URL/client/{id}

Method: POST

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

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

GetClientRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

2.7.2 Get Client Response (GetClientResponse)

GetClientResponse

Name

Type

Mandatory

Data

client

Client

No

Client data

error

Error

No

Response error

2.7.3 Get Client Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/client/{id}

Method: GET

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

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

URL parameters:

GetClientRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

2.7.4 Get Contract Clients Request (GetContractClientsRequest)

Web service URL:  BASE_URL/client/contract

Method: POST

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

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

GetContractClientsRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

2.7.5 Get Contract Clients Response (GetContractClientsResponse)

GetContractClientsResponse

Name

Type

Mandatory

Data

clients

Client[]

No

Clients with same contract as logged users's one, if any

error

Error

No

Response error

2.7.6 Get Contract Clients Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/client/contract

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

GetContractClientsRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

2.7.7 Create Contact Request (CreateContactRequest)

Web service URL:  BASE_URL/client/contact

Method: POST

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

Create contact associating externalId as unique reference

CreateContactRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

externalContactId

String

Yes

External contact id (caller client Id unique reference)

Max 36 characters. Unique for caller

secretKey

String

No

External contact secret key

Max 36 characters

phone1

ShipmentPhoneNumber

Yes

Contact phone number (for example: +40799123456, 0040799123456, +359999123456 - international format numbers or 0799123456, 0999123456 - local numers).

Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. Only phone numbers starting with "0" (zero) or "+" sign are allowed.

phone2

ShipmentPhoneNumber

No

Contact phone number 2.

Validate for valid phone number, if presents.

clientName

String

Yes

Contact customer name.

Validate for valid name (minimum 3 symbols, maximum 60).

objectName

String

Forbidden for private persons. Not mandatory for companies

Contact customer object name.

Validate for valid name (maximum 60 symbols).

contactName

String

Forbidden for private persons. Required for companies

Contact name of contact

Maximum 60

email

String

No

Contact email.

Maximum  255

privatePerson

Boolean

Yes

Private person flag.

address

ShipmentAddress

Yes

Contact address.

Validated for valid values.

2.7.8 Create Contact Response (CreateContactResponse)

CreateContactResponse

Name

Type

Mandatory

Data

clientId

Long

No

Client Id associated for created contact in the system

error

Error

No

Response error

2.7.9 Create Contact Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/client/contact

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

CreateContactRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

externalContactId | external_contact_id

String

Yes

External contact id (caller client Id unique reference)

Max 30 characters. Unique for caller

secretKey | secret_key

String

No

External contact secret key

Max 36 characters

phone1

String

Yes

First phone number.

phone1Ext | phone1_ext

String

No

First phone number extension.

phone2

String

No

Second phone number.

phone2Ext | phone2_ext

String

No

Second phone number extension.

clientName | client_name

String

Yes

Conact customer name.

Minimum 3 symbols, maximum 60

objectName | object_name

String

Forbidden for private persons. Not mandatory for companies

Conact customer object name.

Minimum 3 symbols, maximum 60

contactName | contact_name

String

No

Forbidden for private persons. Required for companies.

Contact name of contact.

Maximum 60.

email

String

No

Contact email.

Maximum  255

privatePerson | private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

Yes

Contact private person flag.

Contact Address

See ShipmentAddress for more details.

addressCountryId | address_country_id

Integer

No

Country ISO code. If not provided, local country is assumed.

Used for all address types.

addressStateId | address_state_id

String

Required, if country supports states.

Country state.

Used for addresses of type 2 (foreign address).

addressSiteId | address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided.

Site id.

Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country

addressSiteType | address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for addresses of type 1 (local address).

Max 20

addressSiteName | address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for all address types.

Max 50

addressPostcode | addressPostCode | address_postcode

String

No

Can be used in conjunction with countryId to find unique site.

Used for all address types.

Validated for valid postcode in site and country.

Max 10

addressStreetId | address_street_id

Long

No

Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

addressStreetType | address_street_type

String

No

Forbidden, if street_id is provided.

Street type.

Used for addresses of type 1 (local address).

Max 15

addressStreetName | address_street_name

String

No

Forbidden, if street_id is provided.

Street name.

Used for addresses of type 1 (local address).

Max 50

addressStreetNumber | address_street_number

String

No

Street number.

Used for addresses of type 1 (local address).

Max 10

addressComplexId | address_complex_id

Long

No

Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

addressComplexType | address_complex_type

String

No

Forbidden, if complex_id is provided.

Complex type.

Used for addresses of type 1 (local address).

Max 15

addressComplexName | address_complex_name

String

No

Forbidden, if complex_id is provided.

Complex name.

Used for addresses of type 1 (local address).

Max 50

addressBlock | addressBlockNo | address_block

String

No

Block No.

Used for addresses of type 1 (local address).

Max 32

addressEntrance | addressEntranceNo | address_entrance

String

No

Entrance.

Used for addresses of type 1 (local address).

Max 10

addressFloor | addressFloorNo | address_floor

String

No

Floor.

Used for addresses of type 1 (local address).

Max 10

addressApartment | addressApartmentNo | address_apartment

String

No

Apartment.

Used for addresses of type 1 (local address).

Max 10

addressPoiId | address_poi_id

Long

No

Point of interest identifier.

Used for addresses of type 1 (local address).

addressNote | address_note

String

No

Address note.

Used for addresses of type 1 (local address).

200

addressLine1 | address_line1

String

Required for address type 2

Address line 1. Used for addresses of type 2 (foreign address).

Max 35

addressLine2 | address_line2

String

No

Address line 2. Used for addresses of type 2 (foreign address).

Max 35

addressX | address_x

Double

No

GIS coordinates - X.

Used for all address types.

addressY | address_y

Double

No

GIS coordinates - Y.

Used for all address types.

2.7.10 Get Contact By External Id Request (GetContactByExternalIdRequest)

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

Method: POST

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

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

GetContactByExternalIdRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

secretKey

String

No

Secret key

Max 36 characters

2.7.11 Get Contact By External Id Response (GetContactByExternalIdResponse)

GetContactByExternalIdResponse

Name

Type

Mandatory

Data

client

Client

No

Client data

error

Error

No

Response error

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

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

 

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

Method: GET

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

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

URL parameters:

GetContactByExternalIdRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

secretKey | secret_key

String

No

Secret key

Max 36 characters

2.7.13 Get Own Client Id Request (GetOwnClientIdRequest)

Web service URL:  BASE_URL/client

Method: POST

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

Get own client id

GetOwnClientIdRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

2.7.14 Get Own Client Id Response (GetOwnClientIdResponse)

GetOwnClientIdResponse

Name

Type

Mandatory

Data

clientId

Long

Yes

Own client id

error

Error

No

Response error

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

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

 

Web service URL:  BASE_URL/client

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

GetOwnClientIdRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

2.7.16 Contract Info Request (ContractInfoRequest)

Web service URL:  BASE_URL/client/contract/info

Method: POST

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

Get information about logged user contract

ContractInfoRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

2.7.17 Contract Info Response (ContractInfoResponse)

ContractInfoResponse

Name

Type

Mandatory

Data

id

Long

Yes

Contract id

specialDeliveryRequirements

SpecialDeliveryRequirements

No

Special delivery requirements

error

Error

No

Response error

2.7.18 Contract Info Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/client/contract/info

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ContractInfoRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

2.8 Validation Service

Web service URL: BASE_URL/validation

2.8.1 Validate Address Request (ValidateAddressRequest)

Web service URL:  BASE_URL/validation/address

Method: POST

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

This method validates shipment address

ValidateAddressRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

address

ShipmentAddress

No

Shipment address to validate

2.8.2 Validate Address Response (ValidationResponse)

ValidationResponse

Name

Type

Mandatory

Data

valid

Boolean

No

Validation result flag

error

Error

No

Response error

2.8.3 Validate Address Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/validation/address

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ValidateAddressRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

Shipment Address

See ShipmentAddress for more details.

countryId | country_id

Integer

No

Country ISO code. If not provided, the local country is assumed.

Used for all address types.

stateId | state_id

String

Required, if country supports states.

Country state.

Used for addresses of type 2 (foreign address).

siteId | site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided.

Site id.

Used for all address types. If not provided, but site type and name or post code is provided - the system will try to find unique match by them in country

siteType | site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for addresses of type 1 (local address).

Max 20

siteName | site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site.

Used for all address types.

Max 50

postcode | postCode | post_code

String

No

Can be used in conjunction with countryId to find unique site.

Used for all address types.

Validated for valid postcode in site and country.

Max 10

streetId | street_id

Long

No

Street identifier. If not provided, but street type and street name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

streetType | street_type

String

No

Forbidden, if street_id is provided.

Street type.

Used for addresses of type 1 (local address).

Max 15

streetName | street_name

String

No

Forbidden, if street_id is provided.

Street name.

Used for addresses of type 1 (local address).

Max 50

streetNumber | street_number

String

No

Street number.

Used for addresses of type 1 (local address).

Max 10

complexId | complex_id

Long

No

Complex identifier. If not provided, but complex type and complex name are provided - the system will try to find unique match by them in site.

Used for addresses of type 1 (local address).

complexType | complex_type

String

No

Forbidden, if complex_id is provided.

Complex type.

Used for addresses of type 1 (local address).

Max 15

complexName | complex_name

String

No

Forbidden, if complex_id is provided.

Complex name.

Used for addresses of type 1 (local address).

Max 50

block | blockNo | block_no

String

No

Block No.

Used for addresses of type 1 (local address).

Max 32

entrance | entranceNo | entrance_no

String

No

Entrance.

Used for addresses of type 1 (local address).

Max 10

floor | floorNo | floor_no

String

No

Floor.

Used for addresses of type 1 (local address).

Max 10

apartment | apartmentNo | apartment_no

String

No

Apartment.

Used for addresses of type 1 (local address).

Max 10

poiId | poi_id

Long

No

Point of interest identifier.

Used for addresses of type 1 (local address).

addressNote | address_note | note

String

No

Address note.

Used for addresses of type 1 (local address).

200

addressLine1 | address_line1 | line1

String

Required for address type 2.

Address line 1. Used for addresses of type 2 (foreign address).

Max 35

addressLine2 | address_line2 | line2

String

No

Address line 2. Used for addresses of type 2 (foreign address).

Max 35

X | x

Double

No

GIS coordinates - X.

Used for all address types.

Y | y

Double

No

GIS coordinates - Y.

Used for all address types.

2.8.4 Validate Postcode Request (ValidatePostCodeRequest)

Web service URL:  BASE_URL/validation/postcode

Method: POST

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

This method validates post code

ValidatePostCodeRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

countryId

Integer

Yes - if siteId is not specified

Country id

siteId

Long

Yes - if countryId is not specified

Site id

postCode

String

Yes

Postcode to validate

2.8.5 Validate Postcode Response (ValidationResponse)

Same as 2.8.2 ValidationResponse

2.8.6 Validate Postcode Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/validation/postcode

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ValidatePostCodeRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

countryId | country_id

Integer

Yes - if siteId is not specified

Country id

siteId | site_id

Long

Yes - if countryId is not specified

Site id

postcode | postCode | post_code

String

Yes

Postcode to validate

2.8.7 Validate Phone Request (ValidatePhoneRequest)

Web service URL:  BASE_URL/validation/phone

Method: POST

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

This method validates phone number

ValidatePhoneRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

number

String

Yes

Phone number

ext

String

No

Phone number extension

2.8.8 Validate Phone Response (ValidationResponse)

Same as 2.8.2 ValidationResponse

2.8.9 Validate Phone Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/validation/phone

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ValidatePhoneRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

number

String

Yes

Phone number

ext

String

No

Phone number extension

2.8.10 Validate Shipment Request (ValidateShipmentRequest)

Web service URL: BASE_URL/validation/shipment

Method: POST

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

This method applies validation on shipment request

Input parameters:

ValidateShipmentRequest

Name

Type

Required

Data

Constraints

CreateShipmentRequest fields are here

2.8.11 Validate Shipment Response (ValidateShipmentResponse)

Same as 2.8.2 ValidationResponse

2.8.12 Validate Shipment - URL (GET) Schema

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

 

Web service URL:  BASE_URL/validation/shipment

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ValidateShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

CreateShipmentRequest params are here

2.9 Services Service

Web service URL: BASE_URL/services

2.9.1 Services Request (ServicesRequest)

Web service URL:  BASE_URL/services

Method: POST

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

Get available services for date

ServicesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

date

Date (yyyy-MM-dd)

No

Date. Current date is assumed if not provided

2.9.2 Services Response (ServicesResponse)

ServicesResponse

Name

Type

Mandatory

Data

services

CourierService[]

Yes

Available courier services

error

Error

No

Response error

2.9.3 Services Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/services

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ServicesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

date

Date (yyyy-MM-dd)

No

Date. Current date is assumed if not provided

2.9.4 Destination Services Request (DestinationServicesRequest)

Web service URL:  BASE_URL/services/destination

Method: POST

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

Get available services for date and destination

DestinationServicesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

date

Date (yyyy-MM-dd)

No

Date. Current date is assumed if not provided

sender

CalculationSender

No

Defines the pickup place. If not specified, the logged user client location is considered as a sender location.

recipient

CalculationRecipient

Yes

Defines the recipient delivery place.

2.9.5 Destination Services Response (DestinationServicesResponse)

DestinationServicesResponse

Name

Type

Mandatory

Data

services

ExtendedCourierService[]

Yes

Available courier services for destination

error

Error

No

Response error

2.9.6 Destination Services Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/services/destination

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

DestinationServicesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

date

Date (yyyy-MM-dd)

No

Date. Current date is assumed if not provided

Calculation sender details

If logged user is the sender, you may skip providing sender details at all.

If you refer an existing customer, provide client’s id in sender_id parameter and other sender parameters may be skipped at all also.

Otherwise, sender_id should stay empty and it is required to provide as a minimum:

  • sender privatePerson flag
  • sender address location or dropoffOfficeId

senderId | sender_id

Long

No

Client id to refer а sender

Validate for existence.

senderPrivatePerson | sender_private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

If sender_id is provided, it is forbidden. If the sender is the logged user, should be omitted too. Otherwise, it is mandatory

Sender private person flag.

Sender Address Location Details

See AddressLocation for more details.

The sender address location is expected when sender_id is empty and sender_dropoff_office_id is empty and not required. In other words, the sender address location is required when the sender is not a referred customer or logged user and pickup at sender’s address is expected.

senderAddressCountryId | sender_address_country_id

Integer

No

Country ISO code. If not provided, the local country is assumed. Used for all address types.

Validate for valid country code

senderAddressStateId | sender_address_state_id

String

Required if country requires state

Country state. Used for addresses of type 2 (foreign address).

Validate for valid country state.

senderAddressSiteId | sender_address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided

Site id. Used for all address types

Validate for valid site and value is required

senderAddressSiteType | sender_address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)

Max 20 characters

senderAddressSiteName | sender_address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.

Max 50 characters

senderAddressPostcode | senderAddressPostCode | sender_address_postcode

String

Required if country requires post code

Can be used in conjunction with countryId to find unique site. Used for all address types

Max 10 characters

dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId | senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id

Integer

Required, if the sender is an internal customer. If sender address is provided, it is forbidden.

Drop off office id.

Should refer to a valid accessible office

Calculation recipient details

If you refer an existing customer, provide client's id in recipient_id parameter and other recipient parameters may be skipped at all

Otherwise, recipient_id should stay empty and it is required to provide as a minimum:.

  • recipient privatePerson flag
  • recipient address location or pickupOfficeId

recipientId | recipient_id

Long

No

Client id to refer а recipient

Validate for existence.

recipientPrivatePerson | recipient_private_person

Boolean

(true/false, y/n, “yes/no” - all case insensitive)

If recipient_id is provided, it is forbidden. Otherwise, it is mandatory

Recipient private person flag.

Recipient Address Location Details

See AddressLocation for more details.

The recipient address location is expected when recipient_id is empty and recipient_pickup_office_id is empty and not required. In other words, the recipient address location is required when the recipient is not a referred customer and delivery at recipient’s address is expected.

recipientAddressCountryId | recipient_address_country_id

Integer

No

Country ISO code. If not provided, the local country is assumed. Used for all address types.

Validate for valid country code

recipientAddressStateId | recipient_address_state_id

String

Required if country requires state

Country state. Used for addresses of type 2 (foreign address).

Validate for valid country state.

recipientAddressSiteId | recipient_address_site_id

Long

Required, if country has full site nomenclature and pair (site_type, site_name) not provided

Site id. Used for all address types

Validate for valid site and value is required

recipientAddressSiteType | recipient_address_site_type

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for addresses of type 1 (local address)

Max 20 characters

recipientAddressSiteName | recipient_address_site_name

String

Forbidden, if site id is provided. Otherwise, is not mandatory.

Site type can be used in conjunction with country_id and site_name to find unique site. Used for all address types.

Max 50 characters

recipientAddressPostcode | recipientAddressPostCode | recipient_address_postcode

String

Required if country requires post code

Can be used in conjunction with countryId to find unique site. Used for all address types

Max 10 characters

pickupOfficeId | pickUpOfficeId | recipientPickupOfficeId | recipientPickUpOfficeId | pickup_office_id | recipient_pickup_office_id

Integer

Required, if the recipient is an internal customer. If recipient address is provided, it is forbidden.

Pickup office id.

Should refer to a valid accessible office

2.10 Payments Service

Web service URL: BASE_URL/payments

2.10.1 Payout Request (PayoutRequest)

Web service URL:  BASE_URL/payments

Method: POST

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

Get shipment payout details for a period

PayoutRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

fromDate

DateTime (yyyy-MM-dd'T'HH:mm:ssZ)

Yes

Start of period date time.

toDate

DateTime (yyyy-MM-dd'T'HH:mm:ssZ)

Yes

End of period date time.

includeDetails

boolean

No (default value is false)

Include payout details flag

2.10.2 Payout Response (PayoutResponse)

PayoutResponse

Name

Type

Mandatory

Data

payouts

Payout[]

Yes

Shipment payouts for a period

error

Error

No

Response error

2.10.3 Payout Request - URL (GET) schema

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

 

Web service URL:  BASE_URL/payments

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

PayoutRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

date_from

Date (yyyy-MM-dd'T'HH:mm:ssZ)

Yes

Start of period date time.

date_to

Date (yyyy-MM-dd'T'HH:mm:ssZ)

Yes

End of period date time.

include_details

boolean

(true/false, y/n, “yes/no” - all case insensitive)

No (Default value is false)

Flag to include payout details.

3 Data Structures

3.1 Shipment Service (ShipmentService)

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

ShipmentService

Name

Type

Required

Data

Constraints

pickupDate

Date

Example:  “2017-11-21"

No

(default value is today)

The date for shipment pickup.

Could be today or a future date.

autoAdjustPickupDate

Boolean

No (default value is false)

To find first available date for pickup starting from pickupDate according to pickup schedule for services

serviceId

int

Yes

Service to be used for the shipment.

Service id (code) should be valid for the destination.

additionalServices

ShipmentAdditionalServices

No

Defines sub-services (like COD, Declared value, etc.) associated with the shipment.

Sub-services may be allowed or forbidden for selected service and/or destination.

deferredDays

Integer

No

(default value is 0)

This parameter allows users to specify by how many (business) days they would like to postpone the shipment delivery from the standard term.

Allowed values are 0, 1 and 2.

saturdayDelivery

Boolean

No

This parameter may adjust delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured delivery customer working schedule.

Example:

    {

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

      "serviceId":2,

      "additionalServices":{

         "cod":{

            "amount":100.0,

            "currencyCode":"RON",

            "payoutToThirdParty":false,

            "processingType":"CASH",

            "includeShippingPrice":false

         },

         "declaredValue":{

            "amount":100.0,

            "fragile":false

         },

         "fixedTimeDelivery": 1130,

         "returns":{

            "rod":{

               "enabled":true,

               "comment":"Ret doc comment",

               "returnToClientId":1234567,

               "thirdPartyPayer":false

            },

            "returnReceipt":{

               "enabled":true,

               "returnToClientId":1234567,

               "thirdPartyPayer":false

            },

            "swap":{

               "serviceId":3,

               "parcelsCount":2,

               "declaredValue":13.0,

               "fragile":false,

               "returnToClientId":1234567

            },

            "rop":{

               "pallets":[

                  {

                     "serviceId":601,

                     "parcelsCount":3

                  },

                  {

                     "serviceId":602,

                     "parcelsCount":2

                  }

               ]

            },

            "returnVoucher":{

               "serviceId":3,

               "payer":"RECIPIENT"

            }

         },

         "specialDeliveryId":2,

         "deliveryToFloor":3

      },

      "deferredDays":2,

      "saturdayDelivery":true

   }

3.1.1 Shipment Additional Services (ShipmentAdditionalServices)

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

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

ShipmentSubServices

Name

Type

Required

Data

Constraints

cod

ShipmentCODAdditionalService

No

Defines shipment COD sub-service.

Seller could be required to have a valid contract and annex for COD for the destination.

obpd

ShipmentOBPD

No

Defines shipment options before payment details.

declaredValue

ShipmentDeclaredValueAdditionalService

No

Defines shipment declared value (extended liability) sub-service.

fixedTimeDelivery

Integer

No

This option fixes the time of delivery on the delivery date. 1130 - means 11:30

920 - means 09:20

This option is checked against the configured allowed time frame for the service.

returns

ShipmentReturnAdditionalServices

No

Defines a return sub-services.

Return shipments are verified for a return destination.

specialDeliveryId

Integer

No

Specifies special delivery identifier for the shipments. Identifiers are determined in a special delivery annex.

Requires an annex for special delivery.

deliveryToFloor

Integer

No

Specifies the floor number in the building where to deliver the shipment.

This sub-service requires an annex.

Example JSON:

     {

         "cod":{

            "amount":100.0,

            "currencyCode":"RON",

            "payoutToThirdParty":false,

            "processingType":"CASH",

            "includeShippingPrice":false

         },

         "declaredValue":{

            "amount":100.0,

            "fragile":false

         },

         "fixedTimeDelivery": 1130,

         "returns":{

            "rod":{

               "enabled":true,

               "comment":"Ret doc comment",

               "returnToClientId":66666666,

               "thirdPartyPayer":false

            },

            "returnReceipt":{

               "enabled":true,

               "returnToClientId":66666666,

               "thirdPartyPayer":false

            },

            "swap":{

               "serviceId":3,

               "parcelsCount":2,

               "declaredValue":13.0,

               "fragile":false,

               "returnToClientId":66666666

            },

            "rop":{

               "pallets":[

                  {

                     "serviceId":601,

                     "parcelsCount":3

                  },

                  {

                     "serviceId":602,

                     "parcelsCount":2

                  }

               ]

            },

            "returnVoucher":{

               "serviceId":3,

               "payer":"RECIPIENT"

            }

         },

         "specialDeliveryId":2,

         "deliveryToFloor":3

      },

      "deferredDays":2,

      "saturdayDelivery":true

   }

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

      {

         "cod":{

            "amount":100.0,

         },

         "returns":{

            "rod":{

               "enabled":true,

            },

            "swap":{

               "serviceId":3,

               "parcelsCount":2,

            },

         }

      },

      "saturdayDelivery":false

   }

3.1.1.1 COD Additional Service (ShipmentCODAdditionalService)

ShipmentCODAdditionalService

Name

Type

Required

Data

Constraints

amount

double

Yes

Defines shipment COD base amount.

Validated against the maximum allowed amounts for the destination.

currencyCode

String

No

(default is the currency code for destination country)

Defines shipment COD currency code.

Validated against the allowed currency code for destination country.

processingType

enum

[“CASH”, “POSTAL_MONEY_TRANSFER”]

No

(default is “CASH”)

Defines COD processing type.

Appropriate contract and annexes may be required.

payoutToThirdParty

Boolean

No

If this flag is set, the COD is paid to third party (not to the sender).

Requires a third party to be the payer of the courier service.

payoutToLoggedClient

Boolean

No

If this flag is set, the COD is paid to the logged client.

includeShippingPrice

Boolean

No

Flag indicating whether the shipping price should be included in the COD.

cardPaymentForbidden

Boolean

No

Flag indicating that COD/PMT card payment is forbidden.

fiscalReceiptItems

ShipmentCODFiscalReceiptItem[]

This feature depends on country regulations and must be enabled for client contract

The value in amount field is ignored if fiscal receipt items are provided.

List of items to issue fiscal receipt on behalf of client

If shipment has fiscal receipt items, the COD amount is the total amount with VAT of all fiscal receipt items.

Example full JSON:

{

    "amount":100.0,

    "currencyCode":"RON",

    "payoutToThirdParty":false,

    "processingType":"CASH",

    "includeShippingPrice":false

    "cardPaymentForbidden":false

}

Or the simplest case:

{

    "amount":100.0

}

3.1.1.1.1 Shipment COD Fiscal Receipt Item (ShipmentCODFiscalReceiptItem)

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

ShipmentCODFiscalReceiptItem

Name

Type

Required

Data

Constraints

description

String

Yes

Fiscal receipt item description

Max 50 characters

vatGroup

String

Yes

VAT group

Must match one of available VAT groups (for example "А" - 0% VAT, "Б" - 20%VAT, ...).

amount

double

Yes

Item amount before VAT.

Must be positive value

amountWithVat

double

Yes

Item amount with VAT included

Must not be lower that amount before VAT

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

ShipmentDeclaredValueAdditionalService

Name

Type

Required

Data

Constraints

amount

double

Yes

Defines shipment Declared Value base amount. Declared value amount is always in local system currency.

Validated against the maximum allowed amounts.

fragile

Boolean

No

Defines fragile flag for shipment content.

Fragile shipments require a declared value sub service.

ignoreIfNotApplicable

Boolean

No (Used in calculation service only, ignored in create shipment service)

Flag to ignore declared value additional service in case it is not applicable for shipment on calculation

E-shops usually configure declared value (extended liability) by default for their shipments, However there are some certain internal rules when this option is not available. The flag is used in calculation service to provide price to end clients without repeating the calculation request with removed additional service

Example JSON:

{

    "amount":100.0,

    "fragile":false

}

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

{

    "amount":100.0

}

3.1.1.2 Shipment Return Additional services (ShipmentReturnAdditionalServices)

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

ShipmentReturnAdditionalServices

Name

Type

Required

Data

Constraints

rod

ShipmentRODAdditionalService

No

Defines Return Of Documents (ROD) sub-service.

The reverse shipment is validated for service and destination.

returnReceipt

ShipmentReturnReceiptAdditionalService

No

Defines Return Receipt sub-service.

The reverse shipment is validated for service and destination.

swap

ShipmentSWAPAdditionalService

No

Defines SWAP sub-service.

The reverse shipment is validated for service and destination.

rop

ShipmentROPAdditionalService

No

Defines Return Of Pallets (ROP) sub-service.

The reverse shipment is validated for service and destination.

returnVoucher

ShipmentReturnVoucherAdditionalService

No

Defines Return Voucher associated with the shipment.

The reverse shipment is validated for service and destination.

sendBackClientId

Long

No

Client id to specify send back address in case of a shipment return. Used in shipment returns after Check/Test or in case recipient is not found. If not specified the shipment is returned to the primary shipment sender.

Should be a customer address (object) in the same contract as the sender of the shipment.

Example JSON:

        {

            "rod":{

               "enabled":true,

               "comment":"Ret doc comment",

               "returnToClientId":1234567,

               "thirdPartyPayer":false

            },

            "returnReceipt":{

               "enabled":true,

               "returnToClientId":1234567,

               "thirdPartyPayer":false

            },

            "swap":{

               "serviceId":3,

               "parcelsCount":2,

               "declaredValue":13.0,

               "fragile":false,

               "returnToClientId":1234567

            },

            "rop":{

               "pallets":[

                  {

                     "serviceId":601,

                     "parcelsCount":3

                  },

                  {

                     "serviceId":602,

                     "parcelsCount":2

                  }

               ]

            },

            "returnVoucher":{

               "serviceId":3,

               "payer":"RECIPIENT"

            }

         }

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

        {

            "rod":{

               "enabled":true

            },

            "returnReceipt":{

               "enabled":true

            },

            "swap":{

               "serviceId":3,

               "parcelsCount":2

            }

         }

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

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

ShipmentRODAdditionalService

Name

Type

Required

Data

Constraints

enabled

boolean

Yes

Enabled flag

comment

String

No

Return documents comment.

Max size 512

returnToClientId

Long

No

Defines the recipient for the ROD shipment. If not specified and returnToOfficeId is not specified also, the reverse shipment is returned to the primary shipment sender.

Cannot be specified together with returnToOfficeId. The same value should be set for ROD and Return Receipt, if the sub-service presents. Cannot be specified if SWAP presents

returnToOfficeId

Integer

No

Defines delivery pickup depot for the ROD shipment. If not specified and returnToClientId is not specified also, the reverse shipment is returned to the primary shipment sender.

Cannot be specified together with returnToClientId. The same value should be set for ROD, Return Receipt and SWAP, if the sub-service presents.

thirdPartyPayer

Boolean

No

Defines a third party payer for the ROD shipment. Otherwise the payer is the primary shipment sender.

Requires a third party payer of the primary shipment. The same value should be set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents.

Example JSON:

{

    "enabled":true,

    "comment":"Ret doc comment",

    "returnToClientId":12345678,

    "thirdPartyPayer": false

}

Or with default values:

{

    "enabled":true

}

3.1.1.2.2 Return Receipt Additional Service (ShipmentReturnReceiptAdditionalService)

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

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, ROP and SWAP, if the sub service presents.

Example JSON:

{

    "enabled":true,

    "returnToClientId":12345678,

    "thirdPartyPayer": false

}

Or with default values:

{

    "enabled":true

}

3.1.1.2.3 SWAP Additional Service (ShipmentSWAPAdditionalService)

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

ShipmentSWAPAdditionalService

Name

Type

Required

Data

Constraints

serviceId

int

Yes

Service to be used in return.

Validated for allowance and destination.

parcelsCount

int

Yes

Number of parcels to return.

Validated against maximum allowed parcels.

declaredValue

Double

No

Declared value (extended liability) for the reverse shipment.

Validated for allowance and maximum amount.

fragile

Boolean

No

Fragile content flag for the reverse shipment.

Fragile shipments require declared value.

returnToOfficeId

Integer

No

Defines delivery pickup depot for the SWAP  shipment. If not specified, the reverse shipment is returned to the primary shipment sender.

The same values should be set for ROD, Return Receipt and SWAP, if the sub-service presents.

thirdPartyPayer

Boolean

No

Defines a third party payer for the SWAP shipment. Otherwise the payer is the primary shipment recipient.

Requires a third party payer of the primary shipment. The same value should be set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents.

Example JSON:

{

    "serviceId":3,

    "parcelsCount":2,

    "declaredValue":13.0,

    "fragile":false,

    "returnToClientId":12345678

}

Or with default values:

{

    "serviceId":3,

    "parcelsCount":2

}

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

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

ShipmentROPAdditionalService

Name

Type

Required

Data

Constraints

pallets

ShipmentROPAdditionalServiceLine[]

Yes

Defines pallets to return grouped by service id.

Total number of returned pallets should not exceed the parcel count of the primary shipment.

thirdPartyPayer

Boolean

No

Defines a third party payer for the returned pallets. Otherwise the payer is the primary shipment sender.

Requires a third party payer of the primary shipment. The same values should be set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.

Example JSON:

[

    {

        "serviceId":601,

        "parcelsCount":3

    },

    {

        "serviceId":2605,

        "parcelsCount":2

    }

]

3.1.1.2.4.1 ROP Additional Service Lines (ShipmentROPAdditionalServiceLine)

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

ShipmentROPAdditionalServiceLine

Name

Type

Required

Data

Constraints

serviceId

int

Yes

ROP service to be used.

Validated against destination.

parcelsCount

int

Yes

Number of parcels to return.

Example JSON:

{

    "serviceId":601,

    "parcelsCount":3

}

3.1.1.2.5 Return Voucher Additional Service (ShipmentReturnVoucherAdditionalService)

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

ShipmentReturnVoucherSubService

Name

Type

Required

Data

Constraints

serviceId

int

Yes

Service id of the return shipment.

payer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

Yes

Defines a return voucher payer.

Allowed payers are validated against the service configuration and destination.

validityPeriod

Integer

Required if caller client has no annex for return voucher.

Return voucher validity period in days. The annex return voucher period is used by default in case caller client has such in his contract and value is omitted

Verified to not exceed the configured internal maximum in the system

Example JSON:

{

    "serviceId":3,

    "payer":"RECIPIENT"

}

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

ShipmentOBPD

Name

Type

Required

Data

Constraints

option

enum

[“OPEN”, “TEST”]

Yes

Defines the option to be used.

Open parcels on payment or open and test parcels before payment.

returnShipmentServiceId

Integer

Yes

Defines service id to be used on return.

returnShipmentPayer

enum

[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]

Yes

Defines who pays the return shipment.

Example JSON:

{

    "option":"TEST",

    "returnShipmentServiceId":2,

    "returnShipmentPayer":"SENDER"

}

3.2 Shipment Content (ShipmentContent)

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

ShipmentContent

Name

Type

Required

Data

Constraints

parcelsCount

Integer

Required when parcels list is empty.

Total shipment parcels count. Ignored, if parcels list is not empty. The parcels count is the number of parcels in the lits in that case.

Validated against the minimum and maximum allowed for the service.

totalWeight

Double

Required when parcels list is empty.

Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcels declaredWeight in that case.

Validated against the minimum and maximum allowed for the service.

contents

String

Yes

Shipment content’s description.

100

package

String

Yes

Shipment package.

50

documents

Boolean

No

Documents flag of the shipment.

palletized

Boolean

No

Palletized flag of the shipment.

parcels

ShipmentParcel[]

Required for pallet and postal services.

Parcels. If omitted a single default (first) parcel will be created for non-pallet and non-postal services.

Validated against the service configuration and pickup and delivery capacity of the depots and couriers.

pendingParcels

Boolean

No

If this flag is true, the shipment is created in pending parcels state.

Shipments in pending parcels state allows adding parcels with addParcel method.

Pending parcels state is closed with finalizePendingShipment method.

exciseGoods

Boolean

No

Flag shipment contains excise goods.

Example JSON:

{

      "contents":"FURNITURE",

      "package":"BOX",

      "documents":false,

      "palletized":false,

      "parcels":[

         {

            "seqNo":1,

            "size":{

               "width":80,

               "depth":120,

               "height":110

            },

            "weight":80.0,

            "externalCarrierParcelNumber":"1726912312312313"

         },

         {

            "seqNo":2,

            "size":{

               "width":80,

               "depth":122,

               "height":100

            },

            "weight":83.0,

            "externalCarrierParcelNumber":"1726912312312315"

         },

         {

            "seqNo":3,

            "size":{

               "width":83,

               "depth":125,

               "height":116

            },

            "weight":85.0,

            "externalCarrierParcelNumber":"1726912312312314"

         }

      ],

      "pendingParcels":false

   }

Or:

{

      "contents":"FURNITURE",

      "package":"BOX",

      "parcels":[

         {

            "seqNo":1,

            "weight":80.0

         },

         {

            "seqNo":2,

            "weight":83.0

         },

         {

            "seqNo":3,

            "weight":85.0

         }

      ]

   }

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

{

      "parcelsCount":3,

      "totalWeight":248.0,

      "contents":"FURNITURE",

      "package":"BOX"

 }

3.2.1 Shipment Parcel (ShipmentParcel)

Shipment parcel data structure.

ShipmentParcel

Name

Type

Required

Data

Constraints

id

String

No

Parcel identifier - barcode (if it is known).

seqNo

Integer

Required in createShipment method. Ignored in addParcel (auto-generated in this case)

Parcel sequence number in the shipment.

Should be unique for the shipment.

packageUniqueNumber

Long

No

Package number associated with parcel.

size

ShipmentParcelSize

Required for pallet and postal services.

Parcel size (width, height, depth) in cm.

Validated against the capacity of the couriers and depots. Used to calculate the volume weight, if applicable.

weight

double

Yes

Parcel weight in kg.

Validated against the capacity of the couriers and depots and service configuration.

ref1

String

No

Reference number or text.

20

ref2

String

No

Reference number or text.

20

pickupExternalCarrierParcelNumber

ExternalCarrierParcelNumber

No

External carrier parcel id for pickup

deliveryExternalCarrierParcelNumber

ExternalCarrierParcelNumber

No

External carrier parcel id for delivery

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

Example JSON:

         {

            "seqNo":1,

            "size":{

               "width":80,

               "depth":120,

               "height":110

            },

            "weight":80.0

         }

Or:

         {

            "seqNo":1,

            "weight":80.0

         }

3.2.1.1 Shipment Parcel Size (ShipmentParcelSize)

Shipment parcel size structure defines parcel size in the shipment.

ShipmentParcelSize

Name

Type

Required

Data

Constraints

width

int

Yes

Parcel width

depth

int

Yes

Parcel depth

height

int

Yes

Parcel height

Example JSON:

   {

      "width":80,

      "depth":120,

      "height":100

   }

3.2.1.2 External carrier parcel number (ExternalCarrierParcelNumber)

Parcel number from external carrier linked to local shipment parcel

ExternalCarrierParcelNumber

Name

Type

Required

Data

Constraints

externalCarrier

enum

[“ACS”]

Yes

External carrier reference name

parcelNumber

String

Yes

External carrier parcel number

3.3 Shipment Payment (ShipmentPayment)

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

ShipmentPayment

Name

Type

Required

Data

Constraints

courierServicePayer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

Yes

Courier service payer.

Validated against the service, destination, contracts and annexes.

declaredValuePayer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

No

Declared value (extended liability) payer. If not provided, the courier service payer is assumed.

Validated against the service, destination, contracts and annexes.

packagePayer

enum

[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]

No

Package payer. If not provided, the courier service payer is assumed.

Validated against the service, destination, contracts and annexes.

thirdPartyClientId

Long

No

Defines shipment third party - used as a payer of any of shipment payable components.

Third party customer should be a registered customer with valid contract and annex for delayed payment at pickup date. The third party customer should be a customer (object) in the same contract as the logged user.

discountCardId

ShipmentDiscountCardId

No

Discount card to be used for discount calculation.

Validated against a referred contract.

senderBankAccount

BankAccount

No

Sender COD payout account information.

Valid IBAN should be present if bank account is provided.

administrativeFee

Boolean

No

Flag to apply administrative fee on price calculations

Usage of administrative fee is enabled and configured in client contract. Ignored if not applicable for user

Example JSON:

   {

      "courierServicePayer":"SENDER",

      "declaredValuePayer":"THIRD_PARTY",

      "packagePayer":"RECIPIENT",

      "thirdPartyClientId":1234567,

      "discountCardId":{

         "contractId":666666,

         "cardId":3

      }

   }

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

 {

      "courierServicePayer":"SENDER"

 }

3.3.1 Shipment Discount Card (ShipmentDiscountCardId)

Discount cards provide promotional discounts.

ShipmentDiscountCardId

Name

Type

Required

Data

Constraints

contractId

long

Yes

Fixed discount card contract id.

Validated against the accessible contract.

cardId

long

Yes

Fixed discount card id.

Validated against the fixed discount card register.

Example JSON:

      {

         "contractId":12345678,

         "cardId":3

      }

3.3.2 Bank Account (BankAccount)

Bank account information.

BankAccount

Name

Type

Required

Data

Constraints

iban

String

Yes

IBAN.

Validated according to IBAN standards.

accountHolder

String

Yes

Bank account holder.

Example JSON:

      {

         "iban":"BG80BNBG96611020345678",

         "accountHolder":"Todor Penev"

      }

3.4 Shipment Sender And Recipient

3.4.1 Shipment Sender (ShipmentSender)

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

ShipmentSender

Name

Type

Required

Data

Constraints

clientId

Long

No

Client id to refer a sender.

Validate for existence.

phone1

ShipmentPhoneNumber

Yes

Sender phone number (for example: +40799123456, 0040799123456, +359999123456 - international format numbers or 0799123456, 0999123456 - local numers).

Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. Only phone numbers starting with "0" (zero) or "+" sign are allowed.

phone2

ShipmentPhoneNumber

No

Sender phone number 2.

Validate for valid phone number, if presents.

phone3

ShipmentPhoneNumber

No

Sender phone number 3.

Validate for valid phone number, if presents.

clientName

String

If clientId is provided, it is forbidden. Otherwise, it is mandatory.

Sender  customer name.

Validate for valid name (minimum 3 symbols, maximum 60).

contactName

String

No

Forbidden for private persons. Required for companies.

Sender  contact name.

Maximum 60

email

String

No

Sender email.

Maximum  255

privatePerson

Boolean

If clientId is provided, it is forbidden. Otherwise, it is mandatory.

Sender  private person flag.

address

ShipmentAddress

If clientId is provided or dropoff office is provided, it is forbidden. Otherwise, it is mandatory.

Sender address.

Validated for valid values.

dropoffOfficeId

Integer

Required, if the sender is an internal customer. If the address is provided, it is forbidden.

Drop off office id.

Should refer to a valid accessible office.

dropoffGeoPUDOId

String

No. Must be empty if dropoffOfficeId is provided

DPD drop off office PUDO id

Should refer to a valid accessible DPD office.

Example JSON:

   {

      "clientId":90909090909,

      "phone1":{

         "number":"08888123123"

      },

      "phone2":{

         "number":"08888123153",

         "extension":"321"

      },

      "clientName":"CLIENT NAME",

      "objectName":"OBJECT NAME",

      "contactName":"CONTACT NAME",

      "email":"[email protected]",

      "privatePerson":false,

      "address":{

         "countryId":100,

         "siteId":68314,

         "streetType":"bul.",

         "streetName":"VITOSKA",

         "streetNo":"55"

      }

   }

Or:

   {

      "clientId":90909090909,

      "phone1":{

         "number":"08888123123"

      },

      "contactName":"CONTACT NAME",

      "email":"[email protected]"

   }

3.4.2 Shipment Recipient (ShipmentRecipient)

ShipmentRecipient

Name

Type

Required

Data

Constraints

clientId

Long

No

Client id to refer recipient.

Validate for existence.

phone1

ShipmentPhoneNumber

Required, if shipment is with the same day delivery or delivery date is a half-working day or delivery country is abroad.

Recipient phone number (for example: +40799123456, 0040799123456, +359999123456 - international format numbers or 0799123456, 0999123456 - local numers).

Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. Only phone numbers starting with "0" (zero) or "+" sign are allowed.

phone2

ShipmentPhoneNumber

No

Recipient phone number 2.

Validate for valid phone number, if presents.

phone3

ShipmentPhoneNumber

No

Recipient phone number 3.

Validate for valid phone number, if presents.

clientName

String

If clientId is provided, it is forbidden. Otherwise, it is mandatory.

Recipient  customer name.

Validate for valid name (minmum 3 simbols, maximum 60).

objectName

String

If clientId is provided, it is forbidden. Otherwise, it is not mandatory.

Recipient  customer object.

Validate for valid name (maximum 60 symbols).

contactName

String

No.

Forbidden for private persons. Required for companies.

Recipient  contact name.

Maximum 60

email

String

No

Recipient email

Maximum  255. Mandatory for international shipments

privatePerson

Boolean

If clientId is provided, it is forbidden. Otherwise, it is mandatory.

Recipient  private person flag.

address

ShipmentAddress

If clientId is provided or pickup office is provided, it is forbidden. Otherwise, it is mandatory.

Recipient address.

Validated for valid values.

pickupOfficeId

Integer

Required, if the recipient is an internal customer. If address is provided, it is forbidden.

Pickup office id.

Should refer to a valid accessible office.

pickupGeoPUDOId

String

No. Must be empty if pickupOfficeId is provided

DPD pickup office PUDO id

Should refer to a valid accessible DPD office.

Example JSON:

  {

      "phone1":{

         "number":"0888813323"

      },

      "clientName":"RCPT NAME",

      "objectName":"RCPT OBJ NAME",

      "contactName":"RCPT CONTACT NAME",

      "email":"[email protected]",

      "privatePerson":true,

      "pickupOfficeId":33

   }

Or:

  {

      "clientId":90909090909,

      "phone1":{

         "number":"0888813323"

      },

      "contactName":"RCPT CONTACT NAME",

      "pickupOfficeId":33

   }

3.4.3 Shipment Address (ShipmentAddress)

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

Address type 1 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"

 }

3.4.3.1 Address (Address)

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

This structure is returned in responses.

Address

Name

Type

Required

Data

Constraints

ShipmentAddress fields are here

fullAddressString

String

Yes

Full address in a single text field

siteAddressString

String

Yes

The address site description in a single text

localAddressString

String

Yes

The address within the site in a single text

3.4.4 Shipment Phone Number (ShipmentPhoneNumber)

This structure is used to provide phone numbers.

ShipmentPhoneNumber

Name

Type

Required

Data

Constraints

number

String

Yes

Phone number.

Validate for valid phone number.

extension

String

No

Extension.

Validate for valid extension, if presents.

Example JSON:

 {

     "number":"0888813323",

     "extension":"123"

 }

Or just:

 {

     "number":"0888813323"

 }

3.5 Shipment Parcels

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

3.5.1 Created Shipment Parcel (CreatedShipmentParcel)

CreatedShipmentParcel

Name

Type

Mandatory

Data

seqNo

int

Yes

Sequence number within the shipment.

id

String

Yes

Generated parcel id.

externalCarrierId

Integer

No

External carrier id in case this parcel is mapped to an external carrier system

externalCarrierParcelNumber

String

No

External carrier parcel number in case this parcel is mapped to an external carrier system

Example JSON:

     {

         "id":"80002188603",

         "seqNo":1      

     }

3.5.2 Shipment Parcel Reference (ShipmentParcelRef)

ShipmentParcelRef

Name

Type

Mandatory

Data

Constraint

id

String

No

If externalCarrierParcelNumber is not provided, it is mandatory.

Parcel id

externalCarrierParcelNumber

String

No

External carrier parcel number used to create parcels.

fullBarcode

String

No

No

If id or externalCarrierParcelNumber is not provided, it is mandatory.

Example JSON:

     {

         "id":"80002188603"    

     }

Or:

     {

         "externalCarrierParcelNumber":"7125912312312312313"    

     }

Or:

     {

         "fullBarcode":"1000509431237540020002030017"    

     }

3.5.3 Parcel Handover (ParcelHandover)

This structure extends ShipmentParcelRef structure with additional fields.

ParcelHandover

Name

Type

Mandatory

Data

Constraint

dateTime

DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ)

Yes

Datetime for hadover operation

ShipmentParcelRef fields are here

3.5.4 Track Shipment Parcel Reference (TrackShipmentParcelRef)

TrackShipmentParcelRef

Name

Type

Mandatory

Data

Constraint

ref

String

No

Reference to parcel or shipment.

The reference is searched in ref1 and ref2 fields in parcels or in ref1 and ref2 fields in shipment. A parcel is included in tracking if reference is found in parcel references. Otherwise, only first shipment parcel (this one with the same number as shipment id) is included in tracking in case reference is found in shipment references.

If externalCarrierParcelNumber or parcelId is provided, it is ignored.

Since the reference is not unique, the maximum barcodes to include for tracking is limited to 10 per reference in request.

ShipmentParcelRef fields are here

3.5.5 Midway Carrier Parcel Handover (MidwayCarrierParcelHandover)

MidwayCarrierParcelHandover

Name

Type

Mandatory

Data

Constraint

id

String

Yes

Parcel id

countryId

Long

Yes

Country ISO id

dateTime

DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ)

Yes

Datetime for hadover operation

siteName

String

No

Site name

3.6 Shipment Price (ShipmentPrice)

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

ShipmentPrice

Name

Type

Mandatory

Data

amount

double

Yes

Total amount (before VAT) in customer’s currency.

vat

double

Yes

VAT amount in customer’s currency.

total

double

Yes

Total amount (amount + vat) in customer’s currency.

currency

String

Yes

Customer currency code.

details

Map<String, ShipmentPriceAmount>

Yes

Amounts that form totals in customer’s currency (including net, discounts, surcharges). Keys in the map are the titles of the items included in the receipt.

amountLocal

double

Yes

Total amount before VAT in local system currency.

vatLocal

double

Yes

VAT in local system currency.

totalLocal

double

Yes

Total amount in local system currency (amountLocal + vatLocal).

currencyLocal

String

Yes

Local system currency code.

detailsLocal

Map<String, ShipmentPriceAmount>

Yes

Amounts that form totals in local system currency (including net, discounts, surcharges). Keys in the map are the titles of the items included in the receipt.

currencyExchangeRateUnit

int

Yes

Currency exchange rate unit for customer currency (1 unit of local system currency is equal to exchangeRateUnit / exchangeRate).

currencyExchangeRate

double

Yes

Currency exchange rate used for customer currency conversion.

returnAmounts

ReturnAmounts

No

Shipment returns amounts due

Example JSON:

    {

      "amount":37.81,

      "vat":7.18,

      "total":44.99,

      "currency":"RON",

      "receipt":{

         "netAmount":{

            "amount":37.81,

            "vatPercent":19.0

         },

         "fixedDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "dropoffDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "pickupDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "additionalDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "fuelSurcharge":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "zoneSurcharge":{

            "amount":0.0,

            "vatPercent":19.0

         },

         "codCommission":{

            "amount":0.0,

            "vatPercent":19.0

         },

         "declaredValueSurcharge":{

            "amount":0.0,

            "vatPercent":19.0

         }

      },

      "amountLocal":37.81,

      "vatLocal":7.18,

      "totalLocal":44.99,

      "currencyLocal":"RON",

      "receiptLocal":{

         "netAmount":{

            "amount":37.81,

            "vatPercent":19.0

         },

         "fixedDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "dropoffDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "pickupDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "additionalDiscount":{

            "amount":-0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "fuelSurcharge":{

            "amount":0.0,

            "percent":0.0,

            "vatPercent":19.0

         },

         "zoneSurcharge":{

            "amount":0.0,

            "vatPercent":19.0

         },

         "codCommission":{

            "amount":0.0,

            "vatPercent":19.0

         },

         "declaredValueSurcharge":{

            "amount":0.0,

            "vatPercent":19.0

         }

      },

      "currencyExchangeRateUnit":1,

      "currencyExchangeRate":1.0

   }

3.6.1 Shipment Price Amount (ShipmentPriceAmount)

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

ShipmentPriceAmount

Name

Type

Mandatory

Data

amount

double

Yes

Shipment price amount. Discounts are negative. Surcharges and net amount are positive.

percent

Double

No

Percent field is returned, if there is a percent associated with the amount. Fixed price amounts do not have a percent value. 20% is returned as 0.2.

vatPercent

double

Yes

VAT percent applicable to the amount. Amounts without VAT have 0.0 value in that field. Amounts with 20% VAT have 0.2 value in that field.

Example JSON:

{

     "amount":13.45,

     "percent":0.4,

     "vatPercent":0.19

 }

Or for fixed amount:

{

     "amount":12.00,

     "vatPercent":0.20

 }

3.6.2 Return Amounts (ReturnAmounts)

Shipment price return amounts represents return services due amounts.

ReturnAmounts

Name

Type

Mandatory

Data

moneyTransfer

MoneyTransferPremium

No

Shipment money transfer premium.

3.6.2.1 Money Transfer Premium (MoneyTransferPremium)

Money transfer premium amount due.

MoneyTransferPremium

Name

Type

Mandatory

Data

amount

Double

No

Amount due in client currency

amountLocal

Double

No

Amount due in local currency

payer

enum

[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]

No

The payer of money transfer premium

        

3.7 Errors (Error)

Errors are returned in responses.

Error

Name

Type

Mandatory

Data

context

String

No

Message context, if associated. This refers to an item that is wrong and should be corrected.

message

String

Yes

Error message in language specified in the request.

id

String

Yes

System generated unique error id to be used as this error reference.

code

int

Yes

Error code. See Appendix 3 - Error Codes for more details.

component

String

No

The request component, if applicable, relevant to this error in JSONPath format with dot notation.


(For example $.sender.address.siteId refers to siteId property in sender address.)

Example JSON:

{

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

     "message":”Value is required”

 }

3.8 Parcel to Print (ParcelToPrint)

 

ParcelToPrint

Name

Type

Mandatory

Data

Constraints

parcel

ShipmentParcelRef

Yes

Parcel reference.

additionalBarcode

ParcelToPrintAdditionalBarcode

No

Additional barcode to be added in the label.

Available for A6 paper size only. Otherwise, ignored.

Example JSON:

{

     "parcel": {

       "Id":"80002188603"

   },

     "additionalBarcode": {

       "value":"123456789104",

       "label":"123456789104",

       "format":"CODE128"

   }

 }

Or just:

{

     "parcel": {

       "Id":"80002188603"

   }

 }

3.8.1 Parcel to Print Additional Barcode (ParcelToPrintAdditionalBarcode)

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

ParcelToPrintAdditionalBarcode

Name

Type

Mandatory

Data

Constraints

value

String

.Yes

Barcode value.

For barcode formats other than 'CODE128' it must contain digits only.

label

String

No

It is printed just below the barcode image.         

For barcode formats other than 'CODE128' label must be equal to the value.

format

enum

[“CODE128”, “EAN13”, “EAN8”, “UPCA”, “UPCE”]

Yes

Additional barcode format.

Example JSON:

      {

       "value":"123456789104",

       "label":"123456789104",

       "format":"CODE128"

   }

3.8.2 Label Info (LabelInfo)

Print label information.

LabelInfo

Name

Type

Mandatory

Data

Constraints

parcelId

String

Yes

Parcel id.

hubId

Integer

No

Delivery Hub id.

officeId

Integer

No

Delivery Office id.

officeName

String

No

Delivery Office name.

deadlineDay

Integer

No

Delivery deadline day of month.

deadlineMonth

Integer

No

Delivery deadline month .

tourId

Integer

No

Tour Id.

fullBarcode

String

Yes

Barcode containing the parcel number and important routing information.

exportPriority

Integer

Yes

Export priority

Example JSON:

{

    "parcelId": "50943123754",

    "hubId": 2,

    "officeId": 2,

    "deadlineDay": 18,

    "deadlineMonth": 2,

    "tourId": 2203,

    "fullBarcode": "1000509431237540020002030017"

}

3.9 TrackedParcel (TrackedParcel)

Track parcel information.

TrackedParcel

Name

Type

Mandatory

Data

Constraints

parcelId

String

Yes

Parcel id.

externalCarrierParcelNumbers

String[]

No

The list of all external carrier parcel numbers associated with the parcel.

operations

TrackedParcelOperation[]

Yes

The list of operations (scans).

externalCarrierParcelNumbersDetails

Map<String, ExternalCarrierParcelNumberDetails>

No

Map of external carrier parcel details. Keys in the map are external carrier parcel numbers.

error

Error

No

Error for this parcel.

3.9.1 Tracked Parcel Operation (TrackedParcelOperation)

TrackedParcelOperation

Name

Type

Mandatory

Data

Constraints

dateTime

Date (datetime)

Yes

Operation date time.

operationCode

int

Yes

Operation code. See Appendix1 for reference.

place

String

No

Place of operation.

description

String

Yes

Operation description.

comment

String

No

Operation comment.

exceptionCodes

String[]

No

List of exception codes for this operation. See Appendix2 for references.

returnShipmentId

String

No

If operation leads to return - the return shipment id is in this field.

redirectShipmentId

String

No

If operation leads to redirect - the redirected shipment id is in this field.

consignee

String

No

If operation leads to delivery - the recipient name is in this field.

podImageURL

String

No

If operation leads to pod capture - the pod image URL is in this field.

additionalInfo

TrackedParcelOperationAdditionalInfo

No

Additional information for operation

3.9.1.1 Tracked Parcel Operation Additional Info(TrackedParcelOperationAdditionalInfo)

TrackedParcelOperationAdditionalInfo

Name

Type

Mandatory

Data

Constraints

officeURL

String

No

Pickup office URL (applicable for operation 134)

geoPUDOId

String

No

Pickup office PUDO id in case pickup office is a DPD office (applicable for operation 134)

predict

TrackedParcelOperationAdditionalInfoPredict

For operation with code 175 (Predict)

Predict details

3.9.1.1.1 Tracked Parcel Predict Operation Additional Info(TrackedParcelOperationAdditionalInfoPredict)

TrackedParcelOperationAdditionalInfoPredict

Name

Type

Mandatory

Data

Constraints

predictedVisitDateTimeFrom

Datetime

(fromat: yyyy-MM-dd'T'HH:mm:ssZ)

Yes

Start of expected time window for delivery

predictedVisitDateTimeTo

Datetime

(fromat: yyyy-MM-dd'T'HH:mm:ssZ)

Yes

End of expected time window for delivery

includedDelayInMinutes

Integer

No

Expected delivery time delay in minutes (if any). The expected time window for delivery is adjusted with this delay

canceled

boolean

Yes

The value is true in case the predict is cancelled

3.9.2 External Carrier Parcel Number Details(ExternalCarrierParcelNumberDetails)

ExternalCarrierParcelNumberDetails

Name

Type

Mandatory

Data

Constraints

externalCarrierId

int

Yes

Id of the external carrier

externalCarrierName

String

Yes

Name of the external carrier

trackAndTraceUrl

String

No

Track and trace URL of the external carrier

 3.10 Pickup order (PickupOrder)

Pickup order data.

PickupOrder

Name

Type

Mandatory

Data

Constraints

id

long

Yes

Order id.

shipmentIds

String[]

Yes

The list of all shipments associated with the order.

pickupPeriodFrom

Datetime

(fromat: yyyy-MM-dd'T'HH:mm:ssZ)

No

Estimated period start for courier pickup visit

pickupPeriodTo

Datetime

(fromat: yyyy-MM-dd'T'HH:mm:ssZ)

No

Estimated period end for courier pickup visit

 3.11 Country

Country data

Country

Name

Type

Data

id

integer

Country ISO

name

String

Country name in requested language

nameEn

String

Country name in English

isoAlpha2

String

Country ISO alpha 2 code

isoAlpha3

String

Country ISO alpha 3 code

postCodeFormats

String[]

Allowed postcode format patterns.

If empty string presents in allowed patterns this means - postcode format is not restricted and post code validation is not applied on addresses in this country.

For non-empty patterns, the following characters are placeholders for:

  • N - digit
  • A - letter
  • ? - digit or letter
  • B - letter
  • O - digit

requireState

String

Require state flag

addressType

integer

Address type for this country (1 or 2 - see ShipmentAddress)

currencyCode

String

Currency code used for COD in this country

defaultOfficeId

Integer

Default office id

streetTypes

AddressNomenclatureType[]

Valid street types for country (applicable if addressType is equal to 1)

complexTypes

AddressNomenclatureType[]

Valid complex types for country (applicable if addressType is equal to 1)

siteNomen

integer

Specifies site nomenclature (sites) for this country. Values can be:

  • 0 - No site nomenclature for this country.
  • 1 - Full site nomenclature for this country.
  • 2 - Partial site nomenclature for this country.

3.11.1 Address Nomenclature Type (AddressNomenclatureType)

Used for address type 1 street types and complex types

AddressNomenclatureType

Name

Type

Data

name

String

Address nomenclature type name in requested language

nameEn

String

Address nomenclature type name in English

 3.12 State

State data

State

Name

Type

Data

id

String

State id

name

String

State name in requested language

nameEn

String

State name in English

stateAlpha

String

State ISO alpha code

countryId

integer

State country id

 3.13 Site

Site data

Site

Name

Type

Data

id

long

Site id

countryId

integer

Site country id

mainSiteId

Long

Here we have reference to main site if this site is a "satellite" one.

A satellite site is considered equal (to their main site) in context of "same city" service allowance

type

String

Site type in requested language

typeEn

String

Site type in English

name

String

Site name in requested language

nameEn

String

Site name in English

municipality

String

Municipality name in requested language

municipalityEn

String

Municipality name in English

region

String

Region name in requested language

regionEn

String

Region name in English

postCode

String

Default post code for this site (if any)

addressNomenclature

integer

Code for address nomenclature (streets, complexes, blocks, poi) support.

  • 0 - no address nomenclature
  • 1 - full address nomenclature
  • 2 - partial address nomenclature

x

Double

Site center GPS X (longitude) coordinate

y

Double

Site center GPS Y (latitude) coordinate

servingDays

String

Serving days for this site.

Format: 7 serial digits (0 or 1) where each digit corresponds to a day in week (the first digit corresponds to Monday, the second to Tuesday and so on).

Value of '0' (zero) means that the site is not served on this day while '1' (one) means that it is served.

(Example: the text "0100100" means that the site is served on Tuesday and Friday only)

servingOfficeId

Integer

Site's serving office

servingHubOfficeId

Integer

The hub office ID to which serving office is connected

 3.14 Street

Street data

Street

Name

Type

Data

id

long

Street id

siteId

long

Street site id

type

String

Street type in requested language

typeEn

String

Street type in English

name

String

Street name in requested language

nameEn

String

Street name in English

actualId

Long

Actual street id (if this street is old and renamed)

actualType

String

Actual street type in requested language (if this street is old and renamed)

actualTypeEn

String

Actual street type in English (if this street is old and renamed)

actualName

String

Actual street name in local language

actualNameEn

String

Actual street name in English

 3.15 Complex

Complex data

Complex

Name

Type

Data

id

long

Complex id

siteId

long

Complex site id

type

String

Complex type in requested language

typeEn

String

Complex type in English

name

String

Complex name in requested language

nameEn

String

Complex name in English

actualId

Long

Actual complex id (if this complex is old and renamed)

actualType

String

Actual complex type in requested language (if this complex is old and renamed)

actualTypeEn

String

Actual complex type in English (if this complex is old and renamed)

actualName

String

Actual complex name in requested language (if this complex is old and renamed)

actualNameEn

String

Actual complex name in English (if this complex is old and renamed)

 3.16 Block

Block data

Block

Name

Type

Data

siteId

long

Block site id

name

String

Block name in requested language

nameEn

String

Block name in English

 3.17 Point of interest (PointOfInterest)

Point of interest data

PointOfInterest

Name

Type

Data

id

long

POI id

siteId

long

POI site id

name

String

POI name in requested language

nameEn

String

POI name in English

type

String

POI type in requested language

typeEn

String

POI type in English

address

String

POI address in requested language

addressEn

String

POI address in English

x

Double

POI GPS X (longitude) coordinate

y

Double

POI GPS Y (latitude) coordinate

 3.18 Office (Office)

Office data

Office

Name

Type

Data

id

Integer

Office id

name

String

Office name in requested language

nameEn

String

Office name in English

siteId

long

Office site id

address

Address

Office address in requested language

workingTimeFrom

String ("HH:mm")

Office work time start for days with standard (FULL) working schedule

workingTimeTo

String ("HH:mm")

Office work time end for days with standard (FULL) working schedule

workingTimeHalfFrom

String ("HH:mm")

Office work time start for days with saturday (HALF) working schedule

workingTimeHalfTo

String ("HH:mm")

Office work time end for days with saturday (HALF) working schedule

workingTimeDayOffFrom

String ("HH:mm")

Office work time start for non-working days (DAY OFF)

workingTimeDayOffTo

String ("HH:mm")

Office work time end for non-working days (DAY OFF)

sameDayDepartureCutoff

String ("HH:mm")

Office same day departure cutoff for days with standard (FULL) working schedule (departure of parcels delivered to office after the cutoff time is next working day)

sameDayDepartureCutoffHalf

String ("HH:mm")

Office same day departure cutoff for days with saturday (HALF) working schedule (departure of parcels delivered to office after the cutoff time is next working day)

sameDayDepartureCutoffDayOff

String ("HH:mm")

Office same day departure cutoff for non-working days (DAY OFF) working schedule (departure of parcels delivered to office after the cutoff time is next working day)

maxParcelDimensions

ShipmentParcelSize

Max parcels dimensions for this office

maxParcelWeight

double

Max parcel weight

type

enum ["OFFICE", "APT"]

Office type

nearbyOfficeId

Integer

Nearby office id

workingTimeSchedule

OfficeWorkingTimeSchedule[]

Office work time schedule for next days

palletOffice

boolean

Pallet office flag

cardPaymentAllowed

boolean

Flag, indicating this office allows card payments

cashPaymentAllowed

boolean

Flag, indicating this office allows cash payments

validFrom

Date (yyyy-MM-dd)

Valid from date

validTo

Date (yyyy-MM-dd)

Valid to date

cargoTypesAllowed

enum[]

(array with values from enum:

[“PARCEL”, “PALLET”, “TYRE”])

(Same as enum in field cargoType in CourierService)

Allowed cargo types

pickUpAllowed

boolean

Flag, indicating whether parcels can be picked up from office

dropOffAllowed

boolean

Flag, indicating whether parcels can be dropped-off in office

3.18.1 Office Working Time Schedule (OfficeWorkingTimeSchedule)

OfficeWorkingTimeSchedule

Name

Type

Data

date

Date (format: ""yyyy-MM-dd"")

Date this schedule is applicable for

workingTimeFrom

String ("HH:mm")

Office working time start for this date

workingTimeTo

String ("HH:mm")

Office working time end for this date

sameDayDepartureCutoff

String ("HH:mm")

Office same day departure cutoff for this day (departure of parcels delivered to office after the cutoff time is next working day)

standardSchedule

boolean

If true - it is from standard schedule, otherwise office working time is overridden for this specific day

 3.19 Calculation Service

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

Calculation Service

Name

Type

Required

Data

Constraints

pickupDate

Date
(Example: 2017-11-12)

No (default value is today)

The date for shipment pickup.

Could be today or a future date

autoAdjustPickupDate

Boolean

No (default value is false)

To find first available date for pickup starting from pickupDate according to pickup schedule for services

serviceIds

integer[]

Yes

Services for which calculation is requested

Each service id (code) should be valid for the destination.

additionalServices

ShipmentAdditionalServices

No

Defines sub-services (like COD, Declared value, etc.) associated with the shipment.

Sub-services may be allowed or forbidden for selected service and/or destination.

deferredDays

Integer

No (default value is 0)

This parameter allows users to specify by how many (business) days they would like to postpone the shipment delivery from the standard term.

Allowed values are 0, 1 and 2

saturdayDelivery

Boolean

No

This parameter may adjust delivery date to the first business day, if the standard calculated delivery day is a half-working day. If not specified, system will determine this flag based on configured delivery customer working schedule

Example JSON:

    {

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

        "serviceIds":[2113, 2002],

        "autoAdjustPickupDate":true,

        "additionalServices":{

            "cod":{

                "amount":100.00

                "currencyCode":"RON"

            },

            "declaredValue":{

                "amount":100.00

                "fragile":false

            },

            "fixedTimeDelivery":1130,

        },

        "deferredDays":2,

        "saturdayDelivery":true

    }

 3.20 Calculation Sender

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

Calculation Sender

Name

Type

Required

Data

Constraints

clientId

Long

No

Client id to refer serving client

Validate for existence.

privatePerson

Boolean

If clientId is provided, it is forbidden. Otherwise, it is mandatory.

Private person flag.

addressLocation

AddressLocation

Required if office id and clientId are missing. Otherwise it is forbidden

Address location, implies pickup at client address

dropoffOfficeId

Integer

Required if address location and clientId are missing. If address location presents it is forbidden

Drop-off office id

Validated for valid office.

dropoffGeoPUDOId

String

No. Must be empty if dropoffOfficeId is provided

DPD drop off office PUDO id

Should refer to a valid accessible DPD office.

Example JSON:

    {

        "addressLocation":{

            "countryId": 100

            "siteId":68314

        }

    }

or:

    {

        "dropoffOfficeId": 2

    }

 3.21 Calculation Recipient

Calculation Recipient

Name

Type

Required

Data

Constraints

clientId

Long

No

Client id to refer serving client

Validate for existence.

privatePerson

Boolean

If clientId is provided, it is forbidden. Otherwise, it is mandatory.

Private person flag.

addressLocation

AddressLocation

Required if office id and clientId are missing. Otherwise it is forbidden

Address location, implies delivery at client address

pickupOfficeId

Integer

Required if address location and clientId are missing. If address location presents it is forbidden

Pickup office id

Validated for valid office.

pickupGeoPUDOId

String

No. Must be empty if pickupOfficeId is provided

DPD pickup office PUDO id

Should refer to a valid accessible DPD office.

 3.22 Calculation Address Location

Calculation Address Location

Name

Type

Required

Data

Constraints

countryId

Integer

No

Country ISO code. If not provided, local country is assumed. Used for all address types.

Validated for valid country code.

stateId

String

Required, if country supports states

Country state. Used for addresses of type 2 (foreign address).

Validated for valid country state.

siteId

Long

Required, if country has full site nomenclature and pair (siteType, siteName) is not provided.

Site id. Used for all address types.

Validated for valid site

siteType

String

Forbidden, if siteId is provided. Otherwise, is not mandatory

Site type can be used in conjunction with countryId and siteName to find unique site. Used for addresses of type 1 (local address).

Max 20 characters

siteName

String

Forbidden, if siteId is provided. Otherwise, is not mandatory

Site type can be used in conjunction with countryId and siteName to find unique site. Used for all address types.

Max 50 characters

postCode

String

Required if country requires postcode for addresses

Can be used in conjunction with countryId to find unique site. Used for all address types.

Validated for valid postcode in site and country. Max 10 characters

 3.23 Calculation Content

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

Calculation Content

Name

Type

Required

Data

Constraints

parcelsCount

Integer

Required when parcels list is empty

Total shipment parcels count. Ignored, if parcels list is not empty.

Validated against the minimum and maximum allowed for the service.

totalWeight

Double

Required when parcels list is empty

Total weight declared for the shipment. Ignored, if parcels list is not empty. The total weight is the sum of all parcels declaredWeight in that case.

Validated against the minimum and maximum allowed for the service.

documents

Boolean

No

Documents flag of the shipment

palletized

Boolean

No

Palletized flag of the shipment.

parcels

ShipmentParcel[]

Required for pallet and postal services.

List of parcels

Validated against the service configuration and pickup and delivery capacity of the depots and couriers.

 3.24 Calculation Result

Calculation Result

Name

Type

Data

serviceId

integer

Service id

additionalServices

ShipmentAdditionalServices

Additional services included in calculation

price

ShipmentPrice

Returned, if customer has access to view the amounts of the shipment.

pickupDate

Date

Pickup date.

deliveryDeadline

DateTime

Deadline for delivery. Returned, if available

error

Error

Response error.

 3.25 Client

Client

Name

Type

Data

clientId

Long

Client id

clientName

String

Client name

objectName

String

Object name

contactName

String

Contact name

address

Address

Client address

email

String

Client email

privatePerson

Boolean

Private person flag.

 3.26 Shipment

Shipment

Name

Type

Data

id

String

Shipment id

sender

Sender

Shipment sender.

recipient

Recipient

Shipment recipient.

service

ShipmentService

Shipment service level agreement.

content

Content

Shipment content.

payment

Payment

Shipment payment.

shipmentNote

String

Customer’s note associated with the shipment.

ref1

String

Reference number or text.

ref2

String

Reference number or text.

price

ShipmentPrice

Shipment payment.

delivery

ShipmentDelivery

Shipment delivery.

primaryShipment

PrimaryShipment

Primary shipment.

returnShipmentId

String

Return shipment id (in case this shipment is returned to sender)

redirectShipmentId

String

Redirect shipment id (in case this shipment is redirected to new delivery location)

pendingShipment

Boolean

If this flag is true, the shipment is created in pending shipment state.

Shipments in pending shipment state can have incomplete data that defines logisitics (without complete addresses, only sites)

Pending shipment state is closed with updateShipment method that makes shipments complete.

3.26.1 Sender (Sender)

This structure extends Client structure with additional fields.

Sender

Name

Type

Data

Client fields are here

dropoffOfficeId

Integer

Drop-off office id

dropoffGeoPUDOId

String

DPD PUDO Id

3.26.2 Recipient (Recipient)

This structure extends Client structure with additional fields.

Recipient

Name

Type

Data

Client fields are here

pickupOfficeId

Integer

Pickup office id

pickupGeoPUDOId

String

DPD PUDO Id

3.26.3 Content (Content)

Content

Name

Type

Data

parcelsCount

Integer

Total shipment parcels count.

declaredWeight

Double

Shipment declared weight

measuredWeight

Double

Shipment measrued weight

calculationWeight

Double

Shipment calculation weight

contents

String

Shipment content’s description.

package

String

Shipment package.

documents

Boolean

Documents flag of the shipment (shipment content is documents)

palletized

Boolean

Palletized flag of the shipment.

parcels

Parcel[]

Shipment parcels

pendingParcels

Boolean

If this flag is true, the shipment is created in pending parcels state.

Shipments in pending parcels state allows adding parcels with addParcel method.

Pending parcels state is closed with finalizePendingShipment method.

3.26.3.1 Parcel (Parcel)

Shipment parcel details

Parcel

Name

Type

Data

id

String

Parcel id

seqNo

Integer

Parcel sequence nomber within the shipment

packageUniqueNumber

Long

Package number associated with parcel.

declaredSize

ShipmentParcelSize

Parcel declared size

measuredSize

ShipmentParcelSize

Parcel measured size

calculationSize

ShipmentParcelSize

Parcel calculation size

declaredWeight

Double

Parcel declared weight

measuredWeight

Double

Parcel measured weight

calculationWeight

Double

Parcel calculation weight

externalCarrierParcelNumbers

String[]

External carrier parcel numbers associated with this parcel

baseType

String

Base type name

size

String

Size name

3.26.4 Payment (Payment)

Payment

Name

Type

Data

courierServicePayer

enum

[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]

Courier service payer.

declaredValuePayer

enum

[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]

Declared value payer

packagePayer

enum

[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]

Package payer

thirdPartyClientId

Long

Third party payer client id in case one of the payers is THIRD_PARTY

discountCardId

ShipmentDiscountCardId

Discount card used in calculation.

codPayment

CODPayment

COD Payment details

3.26.4.1 CODPayment (CODPayment)

COD payment details

CODPayment

Name

Type

Data

date

Datetime (format yyyy-MM-dd'T'HH:mm:ssZ)

Pay out date

totalPayedOutAmount

double

Total paid out COD amount

3.26.5 Shipment Delivery (ShipmentDelivery)

ShipmentDelivery

Name

Type

Data

deadline

Datetime

(fromat: yyyy-MM-dd'T'HH:mm:ssZ)

Deadline for this shipment

deliveryDateTime

Datetime

(fromat: yyyy-MM-dd'T'HH:mm:ssZ)

Datetime of actual delivery (if schipment is delivered)

consignee

String

Shipment consignee (if schipment is delivered)

deliveryNote

String

Shipment delivery note (if schipment is delivered)

3.26.6 PrimaryShipment (PrimaryShipment)

PrimaryShipment

Name

Type

Data

id

String

Primary shipment id

type

enum

[“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”]

Primary shipment type - how this secondary shipment is realted to primary one

  • RETURN_SHIPMENT - if this shipment is one of return of documents (rod) / returnReceipt / swap / return of pallets (rop) for a primary one
  • STORAGE_PAYMENT - if this shipment is for warehouse charges for a primary one
  • REDIRECT - if this shipment redirects primary one
  • SEND_BACK - if this shipment returns primary one to sender
  • MONEY_TRANSFER - if this shipment is a money transfer for a primary one
  • TRANSPORT_DAMAGED - if this shipment is for damaged primary shipment transport
  • VOUCHER_RETURN - if this shipment is a voucher return for a primary one

3.26.7 Secondary Shipment(SecondaryShipment)

SecondaryShipment

Name

Type

Data

id

String

Secondary shipment id

type

enum

[“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”, “MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”]

(Same as enum in field type in PrimaryShipment)

Primary shipment type - how this secondary shipment is realted to primary one

  • RETURN_SHIPMENT - if this shipment is one of return of documents (rod) / returnReceipt / swap / return of pallets (rop) for a primary one
  • STORAGE_PAYMENT - if this shipment is for warehouse charges for a primary one
  • REDIRECT - if this shipment redirects primary one
  • SEND_BACK - if this shipment returns primary one to sender
  • MONEY_TRANSFER - if this shipment is a money transfer for a primary one
  • TRANSPORT_DAMAGED - if this shipment is for damaged primary shipment transport
  • VOUCHER_RETURN - if this shipment is a voucher return for a primary one

parcels

ShipmentParcelNumber[]

Shipment parcels

pickupDate

Date (yyyy-MM-dd)

Secondary shipment pickup date

serviceId

int

Secondary shipment service id

hasScans

boolean

Flag that shows whether the secondary shipment is scanned

3.26.8 Shipment Parcel Number(ShipmentParcelNumber)

ShipmentParcelNumber

Name

Type

Data

id

String

Parcel id

seqNo

int

Parcel sequence number in the shipment.

 3.27 Courier Service

CourierService

Name

Type

Data

id

int

Courier service id

name

String

Courier service name in local language

nameEn

String

Courier service name in English

additionalServices

AdditionalCourierServices

Additional services options

cargoType

enum

[“PARCEL”, “PALLET”, “TYRE”]

Cargo type

requireParcelWeight

boolean

Require weight for each parcel on create shipment

requireParcelSize

boolean

Require size for each parcel on create shipment

3.27.1 Additional Courier Services

AdditionalCourierServices

Name

Type

Data

cod

AdditionalCourierService

COD configuration

obpd

AdditionalCourierService

Options Before Payment or Delivery configuration

declaredValue

AdditionalCourierService

Declared value configuration

fixedTimeDelivery

AdditionalCourierService

Fixed time configuration

specialDelivery

AdditionalCourierService

Special delivery configuration

deliveryToFloor

AdditionalCourierService

Delivery to floor configuration

rod

AdditionalCourierService

Return of documents configuration

returnReceipt

AdditionalCourierService

Return receipt configuration

swap

AdditionalCourierService

SWAP configuration

rop

AdditionalCourierService

Return of pallets configuration

returnVoucher

AdditionalCourierService

Return voucher configuration

3.27.1.1 Additional Courier Service

AdditionalCourierService

Name

Type

Data

allowance

enum

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

Allowance value

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

 3.28 Extended Courier Service

ExtendedCourierService

Name

Type

Data

CourierService fields are here

deadline

Date (yyyy-MM-dd'T'HH:mm:ssZ)

Deadline for delivery

 3.29 Bulk Tracking Data File

BulkTrackingDataFile

Name

Type

Data

id

long

File id

url

String

File url

 3.30 Payout

Payout

Name

Type

Data

date

Date (yyyy-MM-dd)

Payout date

docId

Long

Payout document id

docType

enum

[“CASH”, “POSTAL_MONEY_TRANSFER”]

Payout document type

paymentType

enum

[“CASH”, “BANK”]

Payout payment type

payee

String

Payee

currency

String

Payout currency

amount

double

Payout amount

details

PayoutDetails[]

List of payout details

3.30.1 Payout Details

PayoutDetails

Name

Type

Data

lineNo

int

Payout line number

shipmentId

String

Payout shipment id

pickupDate

Date (yyyy-MM-dd)

Date of shipment pickup

primaryShipmentPickupDate

Date (yyyy-MM-dd)

Date of primary shipment pickup in case this shipment is a secondary one

deliveryDate

Date (yyyy-MM-dd)

Shipment delivery date

sender

String

Shipment sender

recipient

String

Shipment recipient

note

String

Shipment note

ref1

String

Shipment ref1 (reference)

ref2

String

Shipment ref2 (reference)

currency

String

Payout currency

order

Long

Order id

amount

Double

Payout amount

 3.31 SpecialDeliveryRequirements

SpecialDeliveryRequirements

Name

Type

Data

requiredForAllShipments

boolean

Indicates whether special delivery requirements are mandatory for each shipment

requirements

Requirement[]

List of requirements

3.31.1 Requirement

Requirement

Name

Type

Data

id

int

Special delivery requirement id

text

String

Requirement text

3.32 OfficeResult

This structure extends Office structure with additional fields.

OfficeResult

Name

Type

Data

distance

Integer

Distance from searched location

Office fields are here

4 Appendixes

4.1 Appendix 1 - Track And Trace Operation Codes

Track And Trace Operation Codes

Id

Description

1

Arrival Scan

2

Departure Scan

11

Received in Office

12

Out for Delivery

-14

Delivered

21

Processed in Office

38

Returned to Office

39

Courier Pick-up

44

Unsuccessful Delivery

69

Deferred delivery

111

Return to Sender

112

Processed to the Insurance dept.

114

Processed for Destruction

115

Redirected

116

Forwarded

121

Stopped by Sender

123

Refused by recipient

124

Delivered Back to Sender

125

Destroyed

127

Theft/Burglary

128

Canceled

129

Administrative Closure

134

Prepared for Self-collecting Consignee

144

Handover for contents check/test

148

Shipment data received

164

Unsuccessful shipment pickup

169

Delivery capacity reached (tour/office)

175

Predict

176

Export to foreign provider

181

Unexpected delay

190

Postponed delivery due to inaccurate/incomplete address

195

Refuse contents check/test

217

Handover to midway carrier

4.2 Appendix 2 - Track And Trace Operation Exception Codes

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

Track And Trace Operation Codes

Id

Description

11

Wrong address

12

Refused by recipient - damaged

14

Refused by recipient - not ordered

15

Refused by recipient

16

Refused by recipient - contents checked, found to be damaged

17

Return (pick-up) after wrong delivery

19

Recipient not present - informed first time

20

Self-collecting recipient

22

Broken in sub-contractor's custody

25

Closed (e.g. department store)

27

Lack of space

29

Shipment incomplete

32

Lack of time

35

Recipient not present, informed, on holiday

37

Recipient not present - third time

41

Force majeure

42

Recipient not present, informed 2nd time

46

Amount not paid

49

Customer's return

61

Delay due to unknown reason

66

ID check failed

67

Signature refused

80

Appointment scheduled

81

Regional holiday

84

Delivery note / order reference missing

1002

Incomplete address

1003

Does not answer the phone

1004

In office - not claimed

1005

Redirected

1006

Refused after content’s check/test

1007

New date scheduled

1008

Without delivery attempt

1020

Consignee not reachable - routed to office

4.3 Appendix 3 - Error Codes

Error codes returned in Error structure.

Error Codes

Id

Name

Description

1

General Error

Returned when there is an error in request processing and it doesn't match any of recongizable errors described in this table

100

Invalid client data

Returned when there is invalid client data provided in request. Relevant for Shipment, Calculation and Client service methods

120

Invalid address

Returned when there is an error in address provided in request. Relevant for Shipment, Calculation and Client service methods

160

Invalid drop-off office

Returned when the selected sender drop-off office in request is not valid. Relevant for Shipment and Calculation service methods

180

Invalid pickup office

Returned when the selected recipient pickup office in request is not valid. Relevant for Shipment and Calculation service methods

300

Invalid third party

Returned when the selected third party payer in request is invalid. Relevant for Shipment and Calculation service methods

400

Invalid courier service

Returned when the courier service in request is invalid. Relevant for Shipment and Calculation service methods

410

Invalid COD additional service

Returned when COD additional service data in request is invalid. Relevant for Shipment and Calculation service methods

415

Invalid Declared Value additional service

Returned when Declared Value additional service data in request is invalid. Relevant for Shipment and Calculation service methods

420

Invalid OBPD additional service

Returned when Options Before Payment and Delivery additional service data in request is invalid. Relevant for Shipment and Calculation service methods

425

Invalid Delivery To Floor additional service

Returned when Delivery To Floor additional service data in request is invalid. Relevant for Shipment and Calculation service methods

430

Invalid Special Deliery additional service

Returned when Special Deliery additional service data in request is invalid. Relevant for Shipment and Calculation service methods

435

Invalid ROD additional service

Returned when Return of Documents additional service data in request is invalid. Relevant for Shipment and Calculation service methods

440

Invalid Return Receipt additional service

Returned when Return Receipt additional service data in request is invalid. Relevant for Shipment and Calculation service methods

445

Invalid SWAP additional service

Returned when SWAP additional service data in request is invalid. Relevant for Shipment and Calculation service methods

450

Invalid ROP additional service

Returned when Return of Pallets additional service data in request is invalid. Relevant for Shipment and Calculation service methods

455

Invalid Return Voucher additional service

Returned when Return Voucher additional service data in request is invalid. Relevant for Shipment and Calculation service methods

460

Invalid Fixed Time Delivery additional service

Returned when Fixed Time Delivery additional service data in request is invalid. Relevant for Shipment and Calculation service methods

500

Invalid pickup date

Returned when pickup date is not valid. Relevant for Shipment and Calculation service methods

510

Invalid deferred days

Returned when deferred days provided in request is not valid. Relevant for Shipment and Calculation service methods

515

Invalid discount card

Returned when discount card provided in request is not valid. Relevant for Shipment service methods

520

Invalid saturday delivery flag

Returned when saturday delivery flag provided in request is not valid. Relevant for Shipment and Calculation service methods

600

Invalid shipment contents

Returned when shipment contents provided in request is not valid. Relevant for Shipment service methods

605

Invalid shipment package

Returned when shipment package provided in request is not valid. Relevant for Shipment service methods

610

Invalid documents flag

Returned when documents flag provided in request is not valid. Relevant for Shipment and Calculation service methods

615

Invalid palletized flag

Returned when palletized flag provided in request is not valid. Relevant for Shipment and Calculation service methods

620

Invalid weight

Returned when total weight or parcel weight in request is not valid. Relevant for Shipment and Calculation service methods

630

Invalid parcels

Returned when there is an error in parcels data provided in request. Relevant for Shipment and Calculation service methods

700

Invalid courier service payment

Returned when there is an error in courier service payment data provided in request. Relevant for Shipment and Calculation service methods

710

Invalid packings payment

Returned when there is an error in packings payment data provided in request. Relevant for Shipment and Calculation service methods

800

Invalid ref1

Returned when shipment reference 1 provided in request. Relevant for Shipment service methods

805

Invalid ref2

Returned when shipment reference 2 provided in request. Relevant for Shipment service methods

810

Invalid shipment note

Returned when shipment note provided in request. Relevant for Shipment service methods

Logo Footer