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

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

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.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.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.6 Shipment Price (ShipmentPrice)

3.6.1 Shipment Price Amount (ShipmentPriceAmount)

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

3.27.1 AdditionalCourierServices

3.27.1.1 AdditionalCourierService

3.28 Extended Courier Service

4 Appendixes

4.1 Appendix 1 - Track And Trace Operation Codes

4.2 Appendix 2 - Track And Trace Operation Exception 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

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":"a@b.c",

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

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.

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.

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 and ROP, 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 and ROP, 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.

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 and ROP, 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>,

<externalCarrierParcelNumber>

<ref1>

<ref2>

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

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

declaredValueAmount

Double

No

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

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

Example JSON:

{

   "userName":"testUser",

   "password":"password",

   "shipmentId":"80002589418",

   "parcel": {

       "weight":3,

       "size": {

           "width":5,

           "height":5,

           "depth":5

       }

   },

   "codAmount":5.0

}

2.1.8 Add Parcel Response (AddParcelResponse)

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

CancelShipmentResponse

Name

Type

Data

parcel

CreatedShipmentParcel

Created shipment parcel (with generated id and sequence number)

error

Error

Response error

Example JSON:

{}

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

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

Web service URL:  BASE_URL/shipment/add_parcel

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

AddParcelRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentId | shipment_id

String

Yes

Shipment id

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

weight

Double

Yes

Parcel weight

size

String

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

No

(Required for pallet and postal services)

Parcel size

packageUniqueNumber | package_unique_number

Long

No

Parcel package unique number

externalCarrierParcelNumber | external_carrier_parcel_number

String

No

External carrier parcel id

codAmount | cod_amount

Double

No

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

declaredValueAmount | declared_value_amount

Double

No

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

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

Example request:

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

2.1.10 Finalize Pending Shipment Request (FinalizePendingShipmentRequest)

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

Web service URL:  BASE_URL/shipment/finalize

Method: POST

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

FinalizePendingShipmentRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

shipmentId

String

Yes

Shipment id

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

Example JSON:

{

   "userName":"testUser",

   "password":"password",

   "shipmentId":"80002589418"

}

2.1.11 Finalize Pending Shipment Response (FinalizePendingShipmentResponse)

The response is the same as CreateShipmentResponse.

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

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

Web service URL:  BASE_URL/shipment/finalize

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

FinalizePendingShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentId | shipment_id

String

Yes

Shipment id

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

Example request:

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

2.1.13 Shipment Information Request (ShipmentInformationRequest)

This method provides shipment information

Web service URL:  BASE_URL/shipment/info

Method: POST

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

ShipmentInformationRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

shipmentIds

String[]

Yes

Shipment ids

2.1.14 Shipment Information Response (ShipmentInformationResponse)

ShipmentInformationResponse

Name

Type

Data

shipments

Shipment[]

Shipment information

error

Error

Response error

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

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

Web service URL:  BASE_URL/shipment/info

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

ShipmentInformationRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

shipmentIds | shipment_ids

String[]

Yes

Comma separated list of shipment ids

2.1.16 Secondary Shipments Request (SecondaryShipmentsRequest)

This method provides secodary shipments information

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

Method: POST

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

SecondaryShipmentsRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

types

enum[] (array with values from enum:

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

(Same as enum in field type in PrimaryShipment)

Yes

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

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

2.1.17 Secondary Shipments Response (SecondaryShipmentsResponse)

SecondaryShipmentsResponse

Name

Type

Data

shipments

SecondaryShipment[]

List of secondary shipments

error

Error

Response error

2.1.18 Secondary Shipments Request - URL (GET) schema

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

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

Method: GET

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

The response is the same as method using JSON schema.

URL parameters:

SecondaryShipmentsRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

userName | username | user_name

String

Yes

User name

password

String

Yes

Password

language | lang

String

No

clientSystemId | client_system_id

Long

No

Client system id

Validated against system register for external customers.

types

enum[] (array with values from enum:

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

(Same as enum in field type in PrimaryShipment)

Yes

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

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

2.1.19 Update Shipment Request (UpdateShipmentRequest)

Web service URL: BASE_URL/shipment/update

Method: POST

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

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

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

Input parameters:

UpdateShipmentRequest

Name

Type

Required

Data

Constraints

CreateShipmentRequest fields are here

id

String

Yes

Shipment id

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

2.1.20 Update Shipment Response (UpdateShipmentResponse)

Response is CreateShipmentResponse - same returned in createShipment method

Output parameters:

UpdateShipmentResponse

Name

Type

Data

CreateShipmentResponse fields are here

2.1.21 Update Shipment - URL (GET) Schema

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

 

Web service URL:  BASE_URL/shipment/update

Method: GET

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

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

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

The response is the same as method using JSON schema.

URL parameters:

UpdateShipmentRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

CreateShipmentRequest params are here

id

String

Yes

Shipment id

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

2.1.22 Update Shipment Properties Request (UpdateShipmentPropertiesRequest)

Web service URL: BASE_URL/shipment/update/properties

Method: POST

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

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

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

Input parameters:

UpdateShipmentPropertiesRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

id

String

Yes

Shipment id

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

properties

Map<String, String>

Yes

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

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

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

Example Request:

{

   "userName":"testUser",

   "password":"password",

   "id":"89988881389",

   "properties":{

      "total_weight":13,

      "pickup_date":"2020-04-15"

   }

}

2.1.23 Update Shipment Propeties Response (UpdateShipmentPropertiesResponse)

Response is UpdateShipmentResponse - same returned in updateShipment method

Output parameters:

UpdateShipmentPropertiesResponse

Name

Type

Data

UpdateShipmentResponse fields are here

2.1.24 Update Shipment Properties - URL (GET) Schema

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

 

Web service URL:  BASE_URL/shipment/update/properties

Method: GET

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

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

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

The response is the same as method using JSON schema.

URL parameters:

UpdateShipmentPropertiesRequest

URL Parameter Name

(synonyms are separated with |)

Type

Required

Data

Constraints

CreateShipmentRequest params are here

id

String

Yes

Shipment id

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

2.1.25 Find Parcels By Reference Request (FindParcelsByRefRequest)

This method returns parcels by reference number

Web service URL:  BASE_URL/shipment/search

Method: POST

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

FindParcelsByRefRequest

Name

Type

Required

Data

Constraints

userName

String

Yes

User name

password

String

Yes

Password

language

String

No

clientSystemId

Long

No

Client system id

Validated against system register for external customers.

ref

String

Yes

Client reference

searchInRef

int

Yes

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

shipmentsOnly

boolean

No

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

includeReturns

boolean

No

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

fromDateTime

Date

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

No

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

toDateTime

Date

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

No

Pick-up date - to

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

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

ShipmentParcelRef[]

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

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.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": 1820

}

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

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

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

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

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.