api.speedy.bg
Open in
urlscan Pro
104.16.90.21
Public Scan
Submitted URL: http://api.speedy.bg/
Effective URL: https://api.speedy.bg/web-api.html
Submission Tags: @phish_report
Submission: On April 26 via api from FI — Scanned from FI
Effective URL: https://api.speedy.bg/web-api.html
Submission Tags: @phish_report
Submission: On April 26 via api from FI — Scanned from FI
Form analysis 0 forms found in the DOM
Text Content
Please, wait
Your delivery experts
Web API Integration
Table of Contents
1 Introduction
1.1 Scope
1.2 Terms And Conditions
1.3 Overview
1.4 JSON Schema
1.5 Examples
2 Overall Description
2.1 Shipment Service
2.1.1 Create Shipment Request (CreateShipmentRequest)
2.1.2 Create Shipment Response (CreateShipmentResponse)
2.1.3 Create Shipment - URL (GET) Schema
2.1.4 Cancel Shipment Request (CancelShipmentRequest)
2.1.5 Cancel Shipment Response (CancelShipmentResponse)
2.1.6 Cancel Shipment - URL (GET) schema
2.1.7 Add parcel Request (AddParcelRequest)
2.1.8 Add parcel Response (AddParcelResponse)
2.1.9 Add parcel Request (AddParcelRequest) - URL (GET) schema
2.1.10 Finalize Pending Shipment Request (FinalizePendingShipmentRequest)
2.1.11 Finalize Pending Shipment Response (FinalizePendingShipmentResponse)
2.1.12 Finalize Pending Shipment Request (FinalizePendingShipmentRequest) - URL
(GET) schema
2.1.13 Shipment Information Request (ShipmentInformationRequest)
2.1.14 Shipment Information Response (ShipmentInformationResponse)
2.1.15 Shipment Information Request (ShipmentInformationRequest) - URL (GET)
schema
2.1.16 Secondary Shipments Request (SecondaryShipmentsRequest)
2.1.17 Secondary Shipments Response (SecondaryShipmentsResponse)
2.1.18 Secondary Shipments Request (SecondaryShipmentsRequest) - URL (GET)
schema
2.1.19 Update Shipment Request (UpdateShipmentRequest)
2.1.20 Update Shipment Response (UpdateShipmentResponse)
2.1.21 Update Shipment Request (UpdateShipmentRequest) - URL (GET) schema
2.1.22 Update Shipment Properties Request (UpdateShipmentPropertiesRequest)
2.1.23 Update Shipment Properties Response (UpdateShipmentPropertiesRequest)
2.1.24 Update Shipment Properties Request (UpdateShipmentPropertiesRequest) -
URL (GET) schema
2.1.25 Find Parcels By Reference Request (FindParcelsByRefRequest)
2.1.26 Find Parcels By Reference Response (FindParcelsByRefResponse)
2.1.27 Find Parcels By Reference Request (FindParcelsByRefRequest) - URL (GET)
schema
2.1.28 Handover To Courier Request (HandoverToCourierRequest)
2.1.29 Handover To Courier Response (HandoverToCourierResponse)
2.1.30 Handover To Courier Request (HandoverToCourierRequest) - URL (GET) schema
2.1.31 Handover To Midway Carrier Request (HandoverToMidwayCarrierRequest)
2.1.32 Handover To Midway Carrier Response (HandoverToMidwayCarrierResponse)
2.1.33 Handover To Midway Carrier Request (HandoverToMidwayCarrierRequest) - URL
(GET) schema
2.1.34 Barcode Information Request (BarcodeInformationRequest)
2.1.35 Barcode Information Response (BarcodeInformationResponse)
2.1.36 Barcode Information Request (BarcodeInformationResponse) - URL (GET)
schema
2.2 Print Service
2.2.1 Print Request (PrintRequest)
2.2.2 Print Response (PrintResponse)
2.2.3 Print Request - URL (GET) schema
2.2.4 Extended Print Request
2.2.5 Extended Print Response (ExtendedPrintResponse)
2.2.6 Extended Print Request - URL (GET) schema
2.2.7 Label Info Request (LabelInfoRequest)
2.2.8 Label Info Response (LabelInfoResponse)
2.2.9 Label Info Request - URL (GET) schema
2.2.10 Print Voucher Request (PrintVoucherRequest)
2.2.11 Print Voucher Response (PrintVoucherResponse)
2.2.12 Print Voucher Request - URL (GET) schema
2.3 Track And Trace Service
2.3.1 Track Request (TrackRequest)
2.3.2 Track Response (TrackResponse)
2.3.3 Track Request - URL (GET) schema
2.3.4 Bulk Tracking Data Files Request (BulkTrackingDataFielsRequest)
2.3.5 Bulk Tracking Data Files Response (BulkTrackingDataFielsResponse)
2.3.6 Bulk Tracking Data Files Request - URL (GET) schema
2.4 Pickup
2.4.1 Pickup Request (PickupRequest)
2.4.2 Pickup Response (PickupResponse)
2.4.3 Pickup Request - URL (GET) schema
2.4.4 Pickup Terms Request (PickupTermsRequest)
2.4.5 Pickup Terms Response (PickupTermsResponse)
2.4.6 Pickup Terms Request - URL (GET) schema
2.5 Location Service
2.5.1 Country
2.5.1.1 Get Country Request (GetCountryRequest)
2.5.1.2 Get Country Response (GetCountryResponse)
2.5.1.3 Get Country Request - URL (GET) schema
2.5.1.4 Find Country Request (FindCountryRequest)
2.5.1.5 Find Country Response (FindCountryResponse)
2.5.1.6 Find Country Request - URL (GET) schema
2.5.1.7 Get All Countries Request (GetAllCountriesRequest)
2.5.1.8 Get All Countries Response (GetAllCountriesResponse)
2.5.1.9 Get All Countries Request - URL (GET) schema
2.5.2 State
2.5.2.1 Get State Request (GetStateRequest)
2.5.2.2 Get State Response (GetStateResponse)
2.5.2.3 Get State Request - URL (GET) schema
2.5.2.4 Find State Request (FindStateRequest)
2.5.2.5 Find State Response (FindStateResponse)
2.5.2.6 Find State Request - URL (GET) schema
2.5.2.7 Get All States Request (GetAllStatesRequest)
2.5.2.8 Get All States Response (GetAllStatesResponse)
2.5.2.9 Get All States Request - URL (GET) schema
2.5.3 Site
2.5.3.1 Get Site Request (GetSiteRequest)
2.5.3.2 Get Site Response (GetSiteResponse)
2.5.3.3 Get Site Request - URL (GET) schema
2.5.3.4 Find Site Request (FindSiteRequest)
2.5.3.5 Find Site Response (FindSiteResponse)
2.5.3.6 Find Site Request - URL (GET) schema
2.5.3.7 Get All Sites Request (GetAllSitesRequest)
2.5.3.8 Get All Sites Response (GetAllSitesResponse)
2.5.3.9 Get All Sites Request - URL (GET) schema
2.5.4 Street
2.5.4.1 Get Street Request (GetStreetRequest)
2.5.4.2 Get Street Response (GetStreetResponse)
2.5.4.3 Get Street Request - URL (GET) schema
2.5.4.4 Find Street Request (FindStreetRequest)
2.5.4.5 Find Street Response (FindStreetResponse)
2.5.4.6 Find Street Request - URL (GET) schema
2.5.4.7 Get All Streets Request (GetAllStreetsRequest)
2.5.4.8 Get All Streets Response (GetAllStreetsResponse)
2.5.4.9 Get All Streets Request - URL (GET) schema
2.5.5 Complex
2.5.5.1 Get Complex Request (GetComplexRequest)
2.5.5.2 Get Complex Response (GetComplexResponse)
2.5.5.3 Get Complex Request - URL (GET) schema
2.5.5.4 Find Complex Request (FindComplexRequest)
2.5.5.5 Find Complex Response (FindComplexResponse)
2.5.5.6 Find Complex Request - URL (GET) schema
2.5.5.7 Get All Complexes Request (GetAllComplexesRequest)
2.5.5.8 Get All Complexes Response (GetAllComplexesResponse)
2.5.5.9 Get All Complexes Request - URL (GET) schema
2.5.6 Block
2.5.6.1 Find Block Request (FindBlockRequest)
2.5.6.2 Find Block Response (FindBlockResponse)
2.5.6.3 Find Block Request - URL (GET) schema
2.5.6.4 Get All Blocks Request (GetAllBlocksRequest)
2.5.6.5 Get All Blocks Response (GetAllBlocksResponse)
2.5.6.6 Get All Blocks Request - URL (GET) schema
2.5.7 Point of Interest (POI)
2.5.7.1 Get POI Request (GetPOIRequest)
2.5.7.2 Get POI Response (GetPOIResponse)
2.5.7.3 Get POI Request - URL (GET) schema
2.5.7.4 Find POI Request (FindPOIRequest)
2.5.7.5 Find POI Response (FindPOIResponse)
2.5.7.6 Find POI Request - URL (GET) schema
2.5.7.7 Get All Points of Interest Request (GetAllPOIRequest)
2.5.7.8 Get All Points of Interest Response (GetAllPOIResponse)
2.5.7.9 Get All Points of Interest Request - URL (GET) schema
2.5.8 Postcodes
2.5.8.1 Get All Postcodes Request (GetAllPostcodesRequest)
2.5.8.2 Get All Postcodes Response (GetAllPostcodesResponse)
2.5.8.3 Get All Postcodes Request - URL (GET) schema
2.5.9 Office
2.5.9.1 Get Office Request (GetOfficeRequest)
2.5.9.2 Get Office Response (GetOfficeResponse)
2.5.9.3 Get Office Request - URL (GET) schema
2.5.9.4 Find Office Request (FindOfficeRequest)
2.5.9.5 Find Office Response (FindOfficeResponse)
2.5.9.6 Find Office Request - URL (GET) schema
2.5.9.7 Find Nearest Offices Request (FindNearestOfficesRequest)
2.5.9.8 Find Nearest Offices Response (FindNearestOfficesResponse)
2.5.9.9 Find Nearest Offices Request - URL (GET) schema
2.6 Calculation Service
2.6.1 Calculation Request (CalculationRequest)
2.6.2 Calculation Response (CalculationResponse)
2.6.3 Calculation Request - URL (GET) schema
2.7 Client Service
2.7.1 Get Client Request (GetClientRequest)
2.7.2 Get Client Response (GetClientResponse)
2.7.3 Get Client Request - URL (GET) schema
2.7.4 Get Contract Clients Request (GetContractClientsRequest)
2.7.5 Get Contract Clients Response (GetContractClientsResponse)
2.7.6 Get Contract Clients Request - URL (GET) schema
2.7.7 Create Contact Request (CreateContactRequest)
2.7.8 Create Contact Response (CreateContactResponse)
2.7.9 Create Contact Request - URL (GET) schema
2.7.10 Get Contact By External Id Request (GetContactByExternalIdRequest)
2.7.11 Get Contact By External Id Response (GetContactByExternalIdResponse)
2.7.12 Get Contact By External Id Request - URL (GET) schema
2.7.13 Get Own Client Id Request (GetOwnClientIdRequest)
2.7.14 Get Own Client Id Response (GetOwnClientIdResponse)
2.7.15 Get Own Client Id Request - URL (GET) schema
2.7.16 Contract Info Request (ContractInfoRequest)
2.7.17 Contract Info Response (ContractInfoResponse)
2.7.18 Contract Info Request - URL (GET) schema
2.8 Validation Service
2.8.1 Validate Address Request (ValidateAddressRequest)
2.8.2 Validate Address Response (ValidationResponse)
2.8.3 Validate Address Request - URL (GET) schema
2.8.4 Validate Post Code Request (ValidatePostCodeRequest)
2.8.5 Validate Post Code Response (ValidationResponse)
2.8.6 Validate Post Code Request - URL (GET) schema
2.8.7 Validate Phone Request (ValidatePhoneRequest)
2.8.8 Validate Phone Response (ValidationResponse)
2.8.9 Validate Phone Request - URL (GET) schema
2.8.10 Validate Shipment Request (ValidateShipmentRequest)
2.8.11 Validate Shipment Response (ValidationResponse)
2.8.12 Validate Shipment Request - URL (GET) schema
2.9 Services Service
2.9.1 Services Request (ServicesRequest)
2.9.2 Services Response (ServicesResponse)
2.9.3 Services Request - URL (GET) schema
2.9.4 Destination Services Request (DestinationServicesRequest)
2.9.5 Destination Services Response (DestinationServicesResponse)
2.9.6 Destination Services Request - URL (GET) schema
2.10 Payments Service
2.10.1 Payout Request (PayoutRequest)
2.10.2 Payout Response (PayoutResponse)
2.10.3 Payout Request - URL (GET) schema
3 Data Structures
3.1 Shipment Service (ShipmentService)
3.1.1 Shipment Additional Services (ShipmentAdditionalServices)
3.1.1.1 COD Additional Service (ShipmentCODAdditionalService)
3.1.1.1.1 Shipment COD Fiscal Receipt Item (ShipmentCODFiscalReceiptItem)
3.1.1.2 Declared Value (Extended liability) Additional
Service(ShipmentDeclaredValueAdditionalService)
3.1.1.2 Shipment Return Additional services (ShipmentReturnAdditionalServices)
3.1.1.2.1 Return of Documents (ROD) Additional service
(ShipmentRODAdditionalService)
3.1.1.2.2 Return Receipt Additional Service
(ShipmentReturnReceiptAdditionalService)
3.1.1.2.3 SWAP Additional Service (ShipmentSWAPAdditionalService)
3.1.1.2.4 Return of Pallets (ROP) Additional Service
(ShipmentROPAdditionalService)
3.1.1.2.4.1 ROP Additional Service Lines (ShipmentROPAdditionalServiceLine)
3.1.1.2.5 Return Voucher Additional Service
(ShipmentReturnVoucherAdditionalService)
3.1.1.3 Options before payment details Additional Service (ShipmentOBPD)
3.2 Shipment Content (ShipmentContent)
3.2.1 Shipment Parcel (ShipmentParcel)
3.2.1.1 Shipment Parcel Size (ShipmentParcelSize)
3.2.1.2 External carrier parcel number (ExternalCarrierParcelNumber)
3.3 Shipment Payment (ShipmentPayment)
3.3.1 Shipment Discount Card (ShipmentDiscountCardId)
3.3.2 Bank Account (BankAccount)
3.4 Shipment Sender And Recipient
3.4.1 Shipment Sender (ShipmentSender)
3.4.2 Shipment Recipient (ShipmentRecipient)
3.4.3 Shipment Address (ShipmentAddress)
3.4.3.1 Address (Address)
3.4.4 Shipment Phone Number (ShipmentPhoneNumber)
3.5 Shipment Parcels
3.5.1 Created Shipment Parcel (CreatedShipmentParcel)
3.5.2 Shipment Parcel Reference (ShipmentParcelRef)
3.5.3 Parcel Handover (ParcelHandover)
3.5.4 Track Shipment Parcel Reference (TrackShipmentParcelRef)
3.5.5 Midway Carrier Parcel Handover (MidwayCarrierParcelHandover)
3.6 Shipment Price (ShipmentPrice)
3.6.1 Shipment Price Amount (ShipmentPriceAmount)
3.6.2 Return Amounts (ReturnAmounts)
3.6.2.1 Money Transfer Premium (MoneyTransferPremium)
3.7 Errors (Error)
3.8 Parcel to Print (ParcelToPrint)
3.8.1 Parcel to Print Additional Barcode (ParcelToPrintAdditionalBarcode)
3.8.2 Label Info (LabelInfo)
3.9 TrackedParcel (TrackedParcel)
3.9.1 Tracked Parcel Operation (TrackedParcelOperation)
3.9.1.1 Tracked Parcel Operation Additional Info
(TrackedParcelOperationAdditionalInfo)
3.9.1.1.1 Tracked Parcel Operation Predict Additional Info
(TrackedParcelOperationAdditionalInfoPredict)
3.9.2 External Carrier Parcel Number Details
(ExternalCarrierParcelNumberDetails)
3.10 Pickup order (PickupOrder)
3.11 Country
3.11.1 Address Nomenclature Type (AddressNomenclatureType)
3.12 State
3.13 Site
3.14 Street
3.15 Complex
3.16 Block
3.17 Point of interest (PointOfInterest)
3.18 Office (Office)
3.18.1 Office working time schedule (OfficeWorkingTimeSchedule)
3.19 Calculation Service (CalculationService)
3.20 Calculation Sender (CalculationSender)
3.21 Calculation Recipient (CalculationRecipient)
3.22 Calculation Address Location (AddressLocation)
3.23 Calculation Content (CalculationContent)
3.24 Calculation Result (CalculationResult)
3.25 Client (Client)
3.26 Shipment (Shipment)
3.26.1 Sender (Sender)
3.26.2 Recipient (Recipient)
3.26.3 Content (Content)
3.26.3.1 Parcel (Parcel)
3.26.4 Payment (Payment)
3.26.4.1 CODPayment (CODPayment)
3.26.5 Shipment Delivery (ShipmentDelivery)
3.26.6 Primary Shipment (PrimaryShipment)
3.26.7 Secondary Shipment (SecondaryShipment)
3.26.8 Shipment Parcel Number (ShipmentParcelNumber)
3.27 Courier Service
3.27.1 AdditionalCourierServices
3.27.1.1 AdditionalCourierService
3.28 Extended Courier Service
3.29 Bulk Tracking Data File
3.30 Payout
3.30.1 Payout Details
3.31 SpecialDeliveryRequirements
3.31.1 Requirement
3.32 OfficeResult
4 Appendixes
4.1 Appendix 1 - Track And Trace Operation Codes
4.2 Appendix 2 - Track And Trace Operation Exception Codes
4.3 Appendix 3 - Error Codes
--------------------------------------------------------------------------------
1 INTRODUCTION
This document is a specification for web service API integration for external
clients. The web service API provides methods for creating shipments, printing
parcels, pickup requests, tracking and etc.
To get a test account please send us an e-mail to api.registration@speedy.bg and
provide the following info:
* Name
* Company name
* Direct Phone number
* Skype Name (if available)
To get technical support for the integration please send us an e-mail to
api.support@speedy.bg and provide the following info:
* UserName
* Error context (if relevant)
* Error message (if relevant)
and detailed explanation of the situation you need support for.
1.1 SCOPE
This document specifies Web Service API used to connect external customers to
the core system functionality to create, print or track shipments and parcels,
using available courier services with their limitations, additional services and
options.
1.2 TERMS AND CONDITIONS
* Date data types referred in this document that contains actual dates (without
time) should be passed as “yyyy-MM-dd” formatted string in the request. Date
responses are in the same format.
* Date data types referred in this document as datetime should be passed as
“yyyy-MM-ddTHH:mm:ssZ” formatted string in the request. Datetime responses
are in the same format.
* Boolean data types referred in this document in url based requests could be
passed as “true/false, 1/0, y/n, yes/no” case insensitive values. In JSON
fields boolean values allowed are only “true/false”.
* Response data structures may be changed in the future adding additional
fields. Therefore, client applications should be able to accept unknown
fields in responses for backward compatibility
* Letters in text fields which are not in Windows-1251 encoding (ANSI (Latin) +
Cyrillic + some special characters) are transliterated to Latin alphabet in
Windows-1251 character encoding table. For more details visit
https://en.wikipedia.org/wiki/Windows-1251.
1.3 OVERVIEW
The document specifies communication protocol for integration, which is
request/response based over HTTP. Each method provides REST/JSON schema to send
requests to the server and receive response in JSON (but not in any case)
format.
In addition, each method supports URL GET schema to simplify integrations. This
approach is a deviation from standard REST patterns for implementation, but
however is identified as easy for integration, well accepted and requested by
customers.
The web service API requires user password authentication for each method. All
users have a reference to a single client. Some clients may have contracts which
include more than one member (different departments/offices etc). Depending on
his/her permissions, a user is either allowed to work with shipments of these
members or not.
1.4 JSON SCHEMA
API JSON schema is available for download here
1.5 EXAMPLES
Examples can be found here
2 OVERALL DESCRIPTION
BASE_URL=https://api.speedy.bg/v1
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
id
String
No
Shipment id
Shipment ID from provided range. If shipment ID is empty the system will
generate and return it in response
sender
ShipmentSender
No
Defines the sender of the shipment and shipment's pickup place. If not
specified, the logged user is considered as a sender.
recipient
ShipmentRecipient
Yes
Defines the recipient of the shipment and shipment’s delivery place.
service
ShipmentService
Yes
Defines shipment service level agreement.
content
ShipmentContent
Yes
Defines shipment’s content - number of parcels, weight, size, etc.
payment
ShipmentPayment
Yes
Defines who-pays-what in shipment and other payment parameters.
shipmentNote
String
No
Customer’s note associated with the shipment.
200 characters
ref1
String
No
Reference number or text.
30
ref2
String
No
Reference number or text.
30
consolidationRef
String
No
Consolidation reference number or text.
30
requireUnsuccessfulDeliveryStickerImage
Boolean
No
Require unsuccessful delivery sticker image flag.
Example Request:
{
"userName":"testUser",
"password":"password",
"service":{
"serviceId":2002,
"additionalServices":{
"declaredValue":{
"amount":100.0
},
"returns":{
"rod":{
"enabled":true
},
"returnReceipt":{
"enabled":true
},
"swap":{
"serviceId":2002,
"parcelsCount":1
}
}
}
},
"content":{
"parcelsCount":1,
"totalWeight":20.0,
"contents":"FURNITURE",
"package":"BOX"
},
"payment":{
"courierServicePayer":"SENDER"
},
"recipient":{
"phone1":{
"number":"0999123321"
},
"privatePerson": true,
"clientName":"TEST",
"contactName":"TEST",
"email":"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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
id
String
No
Shipment id
Shipment ID from provided range. If shipment ID is empty the system will
generate and return it in response
Sender details
If the logged user is the sender, you may skip providing sender details at all.
If you refer an existing customer, provide client’s id in sender_id parameter
and other sender parameters may be skipped at all also. However, in these cases,
if the user needs to change the defaults stored in the system, the following
parameters could be provided in addition:
* sender phone(s)
* sender contact in case the referred customer is a company (not a private
person), otherwise should be skipped
* sender email
* sender address note
If you provide information in other sender parameters, you’ll receive an error
that data is not expected in that field.
Otherwise, sender_id should stay empty and it is required to provide as a
minimum:
* sender phone
* sender name
* sender privatePerson flag
* sender contact in case privatePerson is false, otherwise should be skipped
* sender address or dropoffOfficeId
senderId | sender_id
Long
No.
Client id to refer а sender.
Validated for existence.
senderPhone | sender_phone
String
Mandatory in case sender_id is empty and sender_name is not. Otherwise, it is
allowed but not mandatory.
Sender phone number.
senderPhoneExt | sender_phone_ext
String
No
Sender phone number extension.
senderPhone2 | sender_phone2
String
No
Sender phone number 2.
senderPhone2Ext | sender_phone2_ext
String
No
Sender phone number 2 extension.
senderPhone3 | sender_phone3
String
No
Sender phone number extension.
senderPhone3Ext | sender_phone3_ext
String
No
Sender phone number 3 extension.
senderName | sender_name
String
If sender_id is provided, it is forbidden. If the sender is the logged user,
should be omitted too. Otherwise, it is mandatory.
Sender name.
Minimum 3 symbols, maximum 60
senderContact | sender_contact
String
No
Required, if privatePerson flag is false.
Sender contact name.
Maximum 60 symbols.
senderEmail | sender_email
String
No
Sender email.
Maximum 255 symbols.
senderPrivatePerson | sender_private_person
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
If sender_id is provided, it is forbidden. If the sender is the logged user,
should be omitted too. Otherwise, it is mandatory.
Sender private person flag.
Sender Address
See ShipmentAddress for more details.
The sender address is expected when sender_id is empty and sender_name is not
and sender_dropoff_office_id is empty and not required. In other words, the
sender address is required when the sender is not a referred customer or logged
user and pickup at sender’s address is expected.
senderAddressCountryId | sender_address_country_id
Integer
No
Country ISO code. If not provided, the local country is assumed.
Used for all address types.
senderAddressStateId | sender_address_state_id
String
Required, if country supports states.
Country state.
Used for addresses of type 2 (foreign address).
senderAddressSiteId | sender_address_site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided.
Site id.
Used for all address types. If not provided, but site type and name or post code
is provided - the system will try to find unique match by them in country
senderAddressSiteType | sender_address_site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for addresses of type 1 (local address).
Max 20
senderAddressSiteName | sender_address_site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for all address types.
Max 50
senderAddressPostcode | senderAddressPostCode | sender_address_postcode
String
No
Can be used in conjunction with countryId to find unique site.
Used for all address types.
Validated for valid postcode in site and country.
Max 10
senderAddressStreetId | sender_address_street_id
Long
No
Street identifier. If not provided, but street type and street name are provided
- the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
senderAddressStreetType | sender_address_street_type
String
No
Forbidden, if street_id is provided.
Street type.
Used for addresses of type 1 (local address).
Max 15
senderAddressStreetName | sender_address_street_name
String
No
Forbidden, if street_id is provided.
Street name.
Used for addresses of type 1 (local address).
Max 50
senderAddressStreetNumber | sender_address_street_number
String
No
Street number.
Used for addresses of type 1 (local address).
Max 10
senderAddressComplexId | sender_address_complex_id
Long
No
Complex identifier. If not provided, but complex type and complex name are
provided - the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
senderAddressComplexType | sender_address_complex_type
String
No
Forbidden, if complex_id is provided.
Complex type.
Used for addresses of type 1 (local address).
Max 15
senderAddressComplexName | sender_address_complex_name
String
No
Forbidden, if complex_id is provided.
Complex name.
Used for addresses of type 1 (local address).
Max 50
senderAddressBlock | senderAddressBlockNo | sender_address_block
String
No
Block No.
Used for addresses of type 1 (local address).
Max 32
senderAddressEntrance | senderAddressEntranceNo | sender_address_entrance
String
No
Entrance.
Used for addresses of type 1 (local address).
Max 10
senderAddressFloor | senderAddressFloorNo | sender_address_floor
String
No
Floor.
Used for addresses of type 1 (local address).
Max 10
senderAddressApartment | senderAddressApartmentNo | sender_address_apartment
String
No
Apartment.
Used for addresses of type 1 (local address).
Max 10
senderAddressPoiId | sender_address_poi_id
Long
No
Point of interest identifier.
Used for addresses of type 1 (local address).
senderAddressNote | sender_address_note
String
No
Address note.
Used for addresses of type 1 (local address).
200
senderAddressLine1 | sender_address_line1
String
Required for address type 2.
Address line 1. Used for addresses of type 2 (foreign address).
Max 35
senderAddressLine2 | sender_address_line2
String
No
Address line 2. Used for addresses of type 2 (foreign address).
Max 35
senderAddressX | sender_address_x
Double
No
GIS coordinates - X.
Used for all address types.
senderAddressY | sender_address_y
Double
No
GIS coordinates - Y.
Used for all address types.
dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId |
senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id
Integer
Required, if the sender is an internal Speedy customer. If sender address is
provided, it is forbidden.
Drop off office id.
Should refer to a valid accessible office.
sender_geo_pudo_id | senderGeoPUDOId | senderDropoffGeoPUDOId |
senderDropOffGeoPUDOId | dropoff_geo_pudo_id | dropoff_geo_pudo_id |
dropoffGeoPUDOId | dropOffGeoPUDOId
String
No. Must be empty if dropoffOfficeId is provided
DPD drop off office PUDO id
Should refer to a valid accessible DPD office.
Shipment Recipient
If you refer an existing customer, provide client’s id in recipient_id parameter
and other recipient parameters may be skipped at all. However, if the user needs
to change the defaults stored in the system, the following parameters could be
provided in addition:
* recipient phone(s)
* recipient contact in case the referred customer is a company (not a private
person), otherwise should be skipped
* recipient email
* recipient address note
If you provide information in other recipient parameters, you’ll receive error
that data is not expected in that field.
Otherwise, recipient_id should stay empty and it is required to provide as a
minimum:
* recipient phone - could be omitted but is required for the same day delivery
services, saturday delivery and delivery abroad
* recipient name
* recipient privatePerson flag
* recipient contact in case privatePerson is false otherwise should be skipped
* recipient address or pickupOfficeId
recipientId | recipient_id
Long
No.
Client id to refer a recipient.
Validated for existence.
recipientPhone | recipient_phone
String
Mandatory in case recipient_id is empty and recipient_name is not. Otherwise, it
is allowed but not mandatory.
Recipient phone number.
recipientPhoneExt | recipient_phone_ext
String
No
Recipient phone number extension.
recipientPhone2 | recipient_phone2
String
No
Recipient phone number 2.
recipientPhone2Ext | recipient_phone2_ext
String
No
Recipient phone number 2 extension.
recipientPhone3 | recipient_phone3
String
No
Recipient phone number extension.
recipientPhone3Ext | recipient_phone3_ext
String
No
Recipient phone number 3 extension.
recipientName | recipient_name
String
If recipient_id is provided, it is forbidden. Otherwise, it is mandatory.
Recipient name.
Minimum 3 symbols, maximum 60
recipientContact | recipient_contact
String
No
Required, if privatePerson flag is false.
Recipient contact name.
Maximum 60.
recipientEmail | recipient_email
String
No
Recipient email.
Maximum 255. Mandatory for international shipments
recipientPrivatePerson | recipient_private_person
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
If recipient_id is provided, it is forbidden. Otherwise, it is mandatory.
Recipient private person flag.
recipient_auto_select_nearest_office | recipientAutoSelectNearestOffice
boolean
No
Not supported for every destination country
Must be supported for destination country
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 Speedy client. If recipient address is
provided, it is forbidden
Pickup office id.
Should refer to valid accessible office.
recipient_geo_pudo_id | recipientGeoPUDOId | recipientPickupGeoPUDOId |
recipientPickUpGeoPUDOId | pickup_geo_pudo_id | pickupGeoPUDOId |
pickUpGeoPUDOId
String
No. Must be empty if pickupOfficeId is provided
DPD pickup office PUDO id
Should refer to a valid accessible DPD office.
Shipment Service
See ShipmentService for more details.
Shipment service defines agreement with customer for courier service. This
includes:
* Pickup date
* Service id (code)
* Optional defer days or saturday delivery
* Additional services (like COD, Declared value, SWAP, ROD and etc.)
pickupDate | pickup_date
Date (date)
Example: “2017-12-11"
No
(default value is today)
The date for shipment pick-up.
Could be today or a future date.
autoAdjustPickupDate | auto_adjust_pickup_date | autoadjust_pickup_date
Boolean
No (default is false)
To find first available date for pickup starting from pickupDate according to
pickup schedule for services
serviceId | service_id
int
Yes
Service to be used for shipment.
Service id (code) should be valid for destination.
deferredDays | deferred_days
Integer
No
(default value is 0)
This parameter allows users to specify by how many (business)
days they would like to postpone the shipment delivery from the standard term.
Allowed values are 0, 1 and 2.
saturdayDelivery | saturday_delivery
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
This parameter may adjust the delivery date to the first business day, if the
standard calculated delivery day is a half-working day. If not specified, system
will determine this flag based on configured recipient working schedule.
COD Additional Service
For more information see ShipmentCODAdditionalService.
codAmount | cod_amount
double
No
Defines shipment COD base amount.
Validated against maximum allowed amounts for destination.
codCurrency | cod_currency
String
No
(default is the currency code of the destination country)
Defines shipment COD currency code.
Validated against allowed currency code of destination country.
codProcessingType | cod_processing_type
enum
[“CASH”, “POSTAL_MONEY_TRANSFER”]
No
(default is “CASH”)
Defines COD processing type.
Appropriate contract and annexes may be required.
codPayoutThirdParty | cod_payout_third_party
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
If this flag is set, the COD is paid to a third party (not to the sender).
Requires the third party to be the payer of the courier service.
codPayoutLoggedClient | cod_payout_logged_client
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
If this flag is set, the COD is paid to a logged client.
codWithShippingPrice | cod_with_shipping_price
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Flag indicating whether the shipping price should be included in the COD.
codCardPaymentForbidden | cod_card_payment_forbidden
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Flag indicating that COD/PMT card payment is forbidden.
cod_fiscal_receipt_items
String
Format for fiscal report item is:
<description>,<vatGroup>,
<amount>,<amountWithVat>
Multiple fiscal report should be separated with %7C (‘|’) character.
See ShipmentCODFiscalReceiptItem
No
List of items in COD fiscal receipt to issue receipt on behalf of client.If
shipment has fiscal receipt items, the COD amount is the total amount with VAT
of all fiscal receipt items.
This feature depends on country regulations and must be enabled for client
contract.The value in cod amount field is ignored if fiscal receipt items are
provided.
Options before payment details Additional Service
For more information see ShipmentOBPD.
obpd_option
enum
[“OPEN”, “TEST”]
No
(For certain destinations could be required.)
Defines option to be used.
Open parcels before payment or open and test parcels before payment.
Return shipment is validated for destination.
obpd_return_service_id
Integer
No
(For certain destinations could be required.)
Defines service id to be used on return, if COD payment is refused.
Return shipment is validated for destination.
obpd_return_payer
enum
[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]
No
(For certain destinations could be required.)
Defines who pays the return shipment, if COD payment is refused.
Return shipment is validated for destination.
Declared Value (Extended Liability) Additional Service
For more information see ShipmentDeclaredVaueAdditionalService.
Declared value payer is required when declared value amount is provided and is
set in payment section.
declaredValueAmount | declared_value_amount
double
No
Defines shipment Declared Value (extended liability) base amount. Declared value
amount is always in local system currency.
Validated against maximum allowed amounts.
fragile | declaredValueFragile | declared_value_fragile
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Defines fragile flag for shipment content.
Fragile shipments requires declared value sub service.
Fixed Time Delivery Additional Service
Fixed time delivery is an additional service that provides instruction to
deliver shipment at a certain time on the delivery date.
fixedTimeDelivery | fixed_time_delivery
Integer
No
This option fixes the time of delivery on the delivery date. 1130 - means 11:30
920 - means 09:20
This option is checked against configured allowed time frame for the service.
Return of Documents (ROD) Additional Service
For more information see ShipmentRODAdditionalService.
Return documents is an additional service that provides instruction to collect
documents on shipment delivery in return.
rodEnabled | rod_enabled
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Enabled flag
rodComment | rod_comment
String
No
Return documents comment.
Max size 512
rodReturnToClientId | rod_return_to_client_id
Long
No
Defines customer - recipient for the ROD shipment. If not specified and
rod_return_to_office_id is not specified also, the reverse shipment is returned
to the primary shipment sender.
Cannot be specified together with rod_return_to_office_id. The same value should
be set for ROD and Return Receipt, if the sub-service presents. Cannot be
specified if SWAP presents
rodReturnToOfficeId | rod_return_to_office_id
Integer
No
Defines delivery pickup depot for ROD shipment. If not specified and
rod_return_to_client_id is not specified also, the return shipment is returned
to primary shipment sender.
Cannot be specified together with rod_return_to_client_id. The same value should
be set for ROD, Return Receipt and SWAP, if the sub-service presents.
rodThirdPartyPayer | rod_third_party_payer
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Defines a third party payer for ROD shipment. Otherwise, payer is the primary
shipment sender.
Requires a third party payer of the primary shipment. The same value should be
set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents.
Return Receipt Additional Service
For more information see ShipmentReturnReceiptAdditionalService.
Return receipt is an additional service that provides instruction to collect a
receipt on shipment delivery in return.
receiptEnabled | receipt_enabled
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Enabled flag
receiptReturnToClientId | receipt_return_to_client_id
Long
No
Defines customer - recipient for the Return Receipt shipment. If not specified
and receipt_return_to_office_id is not specified also, the return shipment is
returned to the primary shipment sender.
Cannot be specified together with receipt_return_to_office_id. The same values
should be set for ROD and Return Receipt, if the sub service presents. Cannot be
specified if SWAP presents
receiptReturnToOfficeId | receipt_return_to_office_id
Integer
No
Defines delivery pickup depot for the Return Receipt shipment. If not specified
and receipt_return_to_client_id is not specified also, the return shipment is
returned to the primary shipment sender.
Cannot be specified together with receipt_return_to_client_id. The same values
should be set for ROD, Return Receipt and SWAP, if the sub service presents.
receiptThirdPartyPayer | receipt_third_party_payer
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Defines a third party payer for the Return Receipt shipment. Otherwise, payer is
the primary shipment sender.
Requires a third party payer of the primary shipment. The same values should be
set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
SWAP Additional Service
For more information see ShipmentSWAPAdditionalService.
SWAP is an additional service that provides instruction to collect a reverse
shipment with predefined parameters on shipment delivery in return.
swapServiceId | swap_service_id
int
No
Service to be used in return.
Validated for allowance and destination.
swapParcelsCount | swap_parcels_count
int
No
Number of parcels to return.
Validated against maximum allowed parcels.
swapDeclaredValueAmount | swap_declared_value_amount
Double
No
Declared value for the reverse shipment.
Validated for allowance and maximum amount.
swapDeclaredValueFragile | swap_declared_value_fragile
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Fragile content flag for the reverse shipment.
Fragile shipments requires declared value.
swapReturnToOfficeId | swap_return_to_office_id
Integer
No
Defines delivery pickup depot for the SWAP shipment. If not specified, the
return shipment is returned to the primary shipment sender.
The same value should be set for ROD, Return Receipt and SWAP, if sub-service
presents.
swapThirdPartyPayer | swap_third_party_payer
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Defines a third party payer for the SWAP shipment. Otherwise, payer is the
primary shipment sender.
Requires a third party payer of the primary shipment. The same values should be
set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
Return of Pallets (ROP) Additional Service
For more information see ShipmentROPAdditionalService.
Return of pallets is an additional service that provides instruction to collect
pallets (used to wrap parcels for transport) in return.
ropPallets | rop_pallets
String
Format for single pair is:
“<serviceId>,<parcelsCount>”
Multiple pairs are separated with %7C (‘|’) character.
See ShipmentROPAdditionalServiceLine
No
Defines pallets to return grouped by service id.
Total number of returned pallets should not exceed parcels count of the primary
shipment.
ropThirdPartyPayer | rop_third_party_payer
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Defines a third party payer for the returned pallets. Otherwise, payer is the
primary shipment sender.
Requires a third party payer of the primary shipment. The same values should be
set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
Return Voucher Additional Service
For more information see ShipmentReturnVoucherAdditionalService.
Return voucher provides an option for the recipient to initiate a return, based
on the delivered shipment, within predefined voucher validity period.
voucherServiceId | voucher_service_id
int
No
Service id of the return voucher shipment.
voucherPayer | voucher_payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
No
Defines the return voucher payer.
Allowed payers are validated against service configuration and destination.
voucherValidityPeriod | voucher_validy_period
Integer
Required if caller client has no annex for return voucher.
Return voucher validity period in days. The annex return voucher period is used
by default in case caller client has such in his contract and value is omitted
Verified to not exceed the configured internal maximum in the system
Special Delivery Additional Service
Special delivery is an additional service that provides instruction to the
courier to do additional (special) checks and actions on delivery. These checks
and actions are negotiated and contracted in a special delivery annex. For
example, the courier could be instructed to check IDs of recipient party at
delivery.
specialDeliveryId | special_delivery_id
Integer
No
Specifies special delivery identifier for the shipments. Identifiers are
determined in a special delivery annex.
Requires annex for special delivery.
Delivery to Floor Additional Service
Delivery to floor is an additional service that provides instruction to the
courier that the shipment should not be delivered to the entrance of a multi
floor building, but should be moved to a certain floor before delivery.
deliveryToFloor | delivery_to_floor
Integer
No
Specifies the floor number in the building where to deliver shipment.
This additional service requires annex.
Shipment Content
For more information see ShipmentContent.
Defines what is to be delivered with the shipment.
parcelsCount | parcels_count
Integer
Required when parcels list is empty and pending_parcels is false.
Total shipment’s parcels count. Ignored, if parcels list is not empty. The
parcels count is the number of parcels in the lits in that case.
Validated against minimum and maximum allowed for the service.
totalWeight | total_weight
Double
Required when parcels list is empty and pending_parcels is false.
Total weight declared for the shipment. Ignored, if parcels list is not empty.
The total weight is the sum of all parcel’s weight in that case.
Validated against minimum and maximum allowed for the service.
contents
String
Yes
Shipment’s contents description.
100
package
String
Yes
Shipment’s package.
50
documents
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Documents flag of the shipment.
palletized
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Palletized flag of the shipment.
parcels
String
Format for single parcel is:
<seqNo>,<weight>,
<width>x<depth>x<height>,
<packageUniqueNumber>,
<id>,
<ignored, kept for backward compatibility>,
<ref1>,
<ref2>,
<Pickup External Carrier Parcel number in format carrier name-parcelnumber>,
<Delivery External Carrier Parcel number in format carrier name-parcelnumber>
Multiple parcels should be separated with %7C (‘|’) character.
See ShipmentParcel
Required for pallet and postal services. For multiple parcels add the same url
parameter again. The parameters are parsed in the order of their occurrence. If
the sequence is incomplete, the missing parameters are considered empty.
Parcels. If omitted, a single default (first) parcel will be created for
non-pallet and non-postal services.
Validated against service configuration and pickup and delivery capacity of the
depots and the couriers.
pendingParcels | pending_parcels
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Partial shipment flag indicating parcels are not complete and new parcels are
expected.
exciseGoods | excise_goods
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Flag shipment contains excise goods.
Shipment Payment
For more information see ShipmentPayment.
Defines who-pays-what in shipment and other payment parameters.
courierServicePayer | courier_service_payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
Yes
Courier service payer.
Validated against the service, destination, contracts and annexes.
declaredValuePayer | declared_value_payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
No
Declared value payer. If not provided, the courier service payer is assumed. Not
expected, if the declared value amount is empty.
Validated against the service, destination, contracts and annexes.
packagePayer | package_payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
No
Package payer. If not provided, the courier service payer is assumed.
Validated against the service, destination, contracts and annexes.
thirdPartyClientId | third_party_client_id
Long
No
Defines shipment third party - used as a payer of any of shipment payable
components.
Third party customer should be registered customer with valid contract and annex
for delayed payment at pickup date. Third party customer should be
customer(object) in the same contract as the logged user.
Discount card
For more information see ShipmentDiscountCardId.
Discount cards provide promotional discounts.
discountCardContractId | discount_card_contract_id
Long
No
Discount card contract id.
Validated against a referred contract.
discountCardId | discount_card_id
Long
No
Discount card id for contract.
Validated against a referred discount card.
Sender Bank account
For more information see BankAccount.
Sender COD payout bank account.
senderBankAccountIban | sender_bank_account_iban
String
No
Sender bank account iban
IBAN format validation is applied
senderBankAccountHolder | sender_bank_account_holder
String
No
Sender bank account holder
Max 60 characters
administrativeFee | administrative_fee
Boolean
No
Flag to apply administrative fee on price calculations
Usage of administrative fee is enabled and configured in client contract.
Ignored if not applicable for user.
Common parameters
shipmentNote | shipment_note
String
No
Customer note associated with the shipment.
200 characters
ref1
String
No
Reference number or text.
30
ref2
String
No
Reference number or text.
30
consolidation_ref | consolidationRef
String
No
Consolidation reference number or text.
30
require_unsuccessful_delivery_sticker_image |
requireUnsuccessfulDeliveryStickerImage
Boolean
No
Require unsuccessful delivery sticker image flag.
Examples:
BASE_URL/shipment?username=test&password=test&language=EN&sender_id=34993782000&recipient_id=34993782000&service_id=2113&parcels_count=1&total_weight=3&courier_service_payer=SENDER&contents=FURNITURE&package=BOX
or
BASE_URL/shipment?username=test&password=test&language=EN&sender_id=34993782000&service_id=2002&courier_service_payer=SENDER&contents=FURNITURE&package=BOX&recipient_address_site_name=SIBISEL&recipient_name=Mr.%20Name&recipient_address_postcode=337083&recipient_address_street_name=STREET%20NAME&recipient_address_country_id=642&recipient_private_person=y&parcels=1,5,8x8x8%7C2,3,8x8x8&recipient_phone=423234&recipient_phone_ext=33&pickup_date=2017-12-06&cod_amount=33&cod_currency=RON&swap_service_id=2002&swap_parcels_count=2&swap_declared_value_amount=33
2.1.4 CANCEL SHIPMENT REQUEST (CANCELSHIPMENTREQUEST)
Web service URL: BASE_URL/shipment/cancel
Method: POST
Content-type: application/json; charset=utf-8
Or
Web service URL: BASE_URL/shipment
Method: DELETE
Content-type: application/json; charset=utf-8
Cancel shipment. Shipment can be cancelled, it is not ordered yet.
CancelShipmentRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
shipmentId
String
Yes
Shipment id
Should refer shipment in pending parcels state (not finalized yet with
finalizePendingShipment method).
parcel
ShipmentParcel
Yes
Parcel to add. Parcel id and sequence number are auto-generated and therefore
ignored if present in request
codAmount
Double
No
COD amount to add with this parcel to increase total COD amount
codFiscalReceiptItems
ShipmentCODFiscalReceiptItem[]
This feature depends on country regulations and must be enabled for client
contract.
The value in codAmount is ignored if fiscal receipt items are provided.
To use fiscal receipt items in this method the shipment must have COD defined
with fiscal receipt already or COD must be emty
List of items to add in current fiscal receipt items list to issue receipt on
behalf of client
If shipment has fiscal receipt items, the COD amount is the total amount with
VAT of all fiscal receipt items.
declaredValueAmount
Double
No
Declared value (extended liability) amount to add with this parcel to increase
total amount
If this parcel increases the amount of declared value, the shipment should be
opened with Declared value (extended liability) additional service
Example JSON:
{
"userName":"testUser",
"password":"password",
"shipmentId":"80002589418",
"parcel": {
"weight":3,
"size": {
"width":5,
"height":5,
"depth":5
}
},
"codAmount":5.0
}
2.1.8 ADD PARCEL RESPONSE (ADDPARCELRESPONSE)
Add parcel response returns generated parcel. Otherwise, an error is included.
CancelShipmentResponse
Name
Type
Data
parcel
CreatedShipmentParcel
Created shipment parcel (with generated id and sequence number)
error
Error
Response error
Example JSON:
{}
2.1.9 ADD PARCEL REQUEST (ADDPARCELREQUEST) - URL (GET) SCHEMA
This approach is used to add parcels, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/shipment/add_parcel
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
AddParcelRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
shipmentId | shipment_id
String
Yes
Shipment id
Should refer shipment in pending parcels state (not finalized yet with
finalizePendingShipment method).
weight
Double
Yes
Parcel weight
size
String
Format is <width>x<depth>x<height>
No
(Required for pallet and postal services)
Parcel size
packageUniqueNumber | package_unique_number
Long
No
Parcel package unique number
externalCarrierParcelNumber | external_carrier_parcel_number
String
No
External carrier parcel id
codAmount | cod_amount
Double
No
COD amount to add with this parcel to increase total COD amount
cod_fiscal_receipt_items
String
Format for fiscal report item is:
<description>,<vatGroup>,
<amount>,<amountWithVat>
Multiple fiscal report should be separated with %7C (‘|’) character.
See ShipmentCODFiscalReceiptItem
No
List of items to add in current fiscal receipt items list to issue receipt on
behalf of client. If shipment has fiscal receipt items, the COD amount is the
total amount with VAT of all fiscal receipt items.
This feature depends on country regulations and must be enabled for client
contract. The value in codAmount is ignored if fiscal receipt items are
provided. To use fiscal receipt items in this method the shipment must have COD
defined with fiscal receipt already or COD must be emty
declaredValueAmount | declared_value_amount
Double
No
Declared value (extended liability) amount to add with this parcel to increase
total amount
If this parcel increases the amount of declared value, the shipment should be
opened with Declared value (extended liability) additional service
Example request:
BASE_URL/shipment/add_parcel?username=test&password=test&language=EN&shipment_id=89981002110&size=10x15x20&weight=13.5&cod_amount=5
2.1.10 FINALIZE PENDING SHIPMENT REQUEST (FINALIZEPENDINGSHIPMENTREQUEST)
Pending shipments (opended with pendingParcels flag equal to true) should be
finalized with this method
Web service URL: BASE_URL/shipment/finalize
Method: POST
Content-type: application/json; charset=utf-8
FinalizePendingShipmentRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
ref
String
Yes
Client reference
searchInRef
int
Yes
Specifies where to search: 0 means [Ref1 or Ref2], 1 means [Ref1], 2 means
[Ref2]
shipmentsOnly
boolean
No
If true - search in shipments only, otherwise in shipment and parcels. Default
is true
includeReturns
boolean
No
If true - search in return shipments also. Default is false
fromDateTime
Date
(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)
No
Pick-up date - from. Up to 6 months before
toDateTime
Date
(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)
No
Pick-up date - to
Example JSON:
{
"userName":"testUser",
"password":"password",
"ref":"634",
"fromDateTime":"2020-10-01T00:00:00+0300",
"toDateTime":"2020-10-15T00:00:00+0300",
}
2.1.26 FIND PARCELS BY REFERENCE RESPONSE (FINDPARCELSBYREFRESPONSE)
FindParcelsByRefResponse
Name
Type
Data
barcodes
String[]
List of barcodes found
error
Error
Response error
2.1.27 FIND PARCELS BY REFERENCE REQUEST (FINDPARCELSBYREFREQUEST) - URL (GET)
SCHEMA
This approach is used to find parcels by reference providing data in an URL
instead of JSON data in the content.
Web service URL: BASE_URL/shipment/search
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindParcelsByRefRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
parcels
String
Format:
<id>,<dateTime>
Multiple items are separated with %7C (‘|’) character. Datetime is in format
dd.MM.yyyy HH:mm:ss
No
Parcel ids
Should refer accessible shipment parcels
externalCarrierParcels | external_carrier_parcels
String
Format:
<externalCarrierParcelId>,<dateTime>
Multiple items are separated with %7C (‘|’) character. Datetime is in format
dd.MM.yyyy HH:mm:ss
No
External carrier parcel ids
Should refer accessible shipment parcels
2.1.31 HANDOVER TO MIDWAY CARRIER REQUEST (HANDOVERTOMIDWAYCARRIERREQUEST)
Register handover to midway carrier barcode operations
Web service URL: BASE_URL/shipment/handover-to-midway-carrier
Method: POST
Content-type: application/json; charset=utf-8
HandoverToMidwayCarrierRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
parcels
MidwayCarrierParcelHandover[]
Yes
Parcel barcodes with datetime, country and site name to register handover to
midway carrier operations
Should refer accessible shipment parcels
2.1.32 HANDOVER TO MIDWAY CARRIER RESPONSE (HANDOVERTOMIDWAYCARRIERRESPONSE)
Response is empty on success. Otherwise, an error is included.
HandoverToMidwayCarrierResponse
Name
Type
Data
error
Error
Response error
2.1.33 HANDOVER TO MIDWAY CARRIER REQUEST (HANDOVERTOCOURIERREQUEST) - URL (GET)
SCHEMA
This approach is used to handover parcels to midway carrier, providing data in
an URL instead of JSON data in the content.
Web service URL: BASE_URL/shipment/handover-to-midway-carrier
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
HandoverToMidwayCarrierRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
parcels
String
Format:
<id>,<countryId>,<dateTime>,<siteName>
or
<id>,<countryId>,<dateTime>
Multiple items are separated with %7C (‘|’) character. Datetime is in format
dd.MM.yyyy HH:mm:ss
No
Parcel ids
Should refer accessible shipment parcels
2.1.34 BARCODE INFORMATION REQUEST (BARCODEINFORMATIONREQUEST)
Get parcel information by parcel barcode
Web service URL: BASE_URL/shipment/barcode-information
Method: POST
Content-type: application/json; charset=utf-8
BarcodeInformationRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
parcel
ShipmentParcelRef
Yes
Parcel to get info for
Validated for allowed access.
Example JSON:
{
"userName":"testUser",
"password":"password",
"parcel": {
"fullBarcode":"1000509431237540020002030017"
}
}
2.1.35 BARCODE INFORMATION RESPONSE (BARCODEINFORMATIONRESPONSE)
Barcode information response
BarcodeInformationResponse
Name
Type
Data
labelInfo
LabelInfo
Label info
primaryShipment
PrimaryShipment
Primary shipment.
primaryParcelId
String
Primary parcel id.
returnShipmentId
String
Return shipment id.
returnParcelId
String
Return parcel id.
redirectShipmentId
String
Redirect shipment id.
redirectParcelId
String
Redirect parcel id.
initialShipmentId
String
Initial shipment id.
initialParcelId
String
Initial parcel id.
error
Error
Response error
Example JSON:
{
"labelsInfo”: {
"hubId": 2,
"officeId": 2,
"deadlineDay": 18,
"deadlineMonth": 2,
"tourId": 2203,
"fullBarcode": "1000509431237540020002030017"
},
"initialShipmentId": "50943123000"
}
2.1.36 BARCODE INFORMATION REQUEST (BARCODEINFOMATIONREQUEST) - URL (GET) SCHEMA
This approach is used to get barcode information providing data in an URL
instead of JSON data in the content.
Web service URL: BASE_URL/shipment/barcode-information
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
BarcodeInformationRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
fullBarcode | full_barcode
String
Yes if no id or externalCarrierParcelNumber is provided
Full barcode
Validated for allowed access.
id
String
Yes if no fullBarcode or externalCarrierParcelNumber is provided
Parcel id
Validated for allowed access.
externalCarrierParcelNumber | external_carrier_parcel_number
String
Yes if no id or fullBarcode is provided
External carrier parcel number
Validated for allowed access.
Example request:
BASE_URL/shipment/barcode-information?username=test&password=test&fullBarocde=1000899999993951420001320013
2.2 PRINT SERVICE
Web service URL: BASE_URL/print
Used to create labels (waybills, stickers and etc.)
PDF Examples:
* Waybill (A4)
* Waybill (A4) with "cash on delivery"
* Parcel sticker (A6)
* Parcel sticker (A6) with "cash on delivery"
* Return voucher
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
shipmentIds
String[]
Yes
Shipment ids
Validated for allowed access. All shipments must have voucher request
printerName
String
No
Printer name to be used for direct printing. Includes javascript in pdf to print
document directly to the provided printer on document opening.
format
enum
[“pdf”, “zpl”]
No
(default is pdf)
Output format
dpi
enum
[“dpi203”, “dpi300”]
No
(default is dpi203)
Dpi used for rendering. Makes sense for zpl format, otherwise ignored
Example JSON:
{
"userName":"testUser",
"password":"password",
"shipmentIds": ["80002338331"]
}
2.2.11 PRINT VOUCHER RESPONSE (PRINTVOUCHERRESPONSE)
The result content type is application/pdf.
Content-type: application/pdf
And content contains pdf bytes.
In case of an error, the content type is application/json.
Content-type:application/json
And content is a JSON with Error structure.
2.2.12 PRINT VOUCHER REQUEST - URL (GET) SCHEMA
This approach is used to print vouchers, providing data in an URL instead of
JSON data in the content.
Web service URL: BASE_URL/print/voucher
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
PrintVoucherRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
parcels
TrackShipmentParcelRef[]
Yes
Parcels to track
lastOperationOnly
Boolean
No
Flag to return last operation only’
2.3.2 TRACK RESPONSE (TRACKRESPONSE)
TrackResponse
Name
Type
Mandatory
Data
parcels
TrackedParcel[]
Yes
Parcel track information
error
Error
No
Response error
2.3.3 TRACK REQUEST - URL (GET) SCHEMA
This approach is used to track parcels, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/track
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
TrackRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
parcels
String
Format:
<id>
Multiple parcels are separated with %7C (‘|’) character.
No
Parcel ids to track
externalCarrierParcels | external_carrier_parcels
String
Format:
<externalCarrierParcelId>
Multiple parcels are separated with %7C (‘|’) character.
No
External carrier parcel ids to track
refs
String
Format:
<ref>
Multiple parcels are separated with %7C (‘|’) character.
No
Parcel references to search and track referred parcels
lastOperationOnly | last_opeartion_only
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Flag to return last operation only.
Example:
BASE_URL/track?username=test&password=test&language=EN&client_system_id=9&parcels=89981001249%7C89981001254&last_opeartion_only=n
2.3.4 BULK TRACKING DATA FILES REQUEST (BULKTRACKINGDATAFILESREQUEST)
Bulk tracking data files are json files with file id assigned and contain data
in format: TrackedParcel[]
A greater file id corresponds to a later file publishing.
This method is used to provide links for downloading published data files with
tracking information.
This method requires bulk tracking service enrolment, for which you may contact
your key account manager.
Web service URL: BASE_URL/track/bulk
Method: POST
Content-type: application/json; charset=utf-8
BulkTrackingDataFilesRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
lastProcessedFileId
Long
Yes
The greatest data file id processed in client system. To get all published data
files during last 10 days use 0 as lastProcessedFileId
The last processed file id must refer to a file published during last 10 days.
Otherwise, error is returned.
2.3.5 BULK TRACKING DATA FILES RESPONSE (BULKTRACKINGDATAFILESRESPONSE)
BulkTrackingDataFilesResponse
Name
Type
Mandatory
Data
files
BulkTrackingDataFile[]
Yes
Bulk traking data files ordered by file id in ascending order. The geratest file
id returned in this response is expected to be passed in next request for
incremental processing
error
Error
No
Response error
2.3.6 BULK TRACKING DATA FILES REQUEST - URL (GET) SCHEMA
This approach is used to get published bulk tracking file links, providing data
in an URL instead of JSON data in the content.
Bulk tracking data files are json files with file id assigned and contain data
in format: TrackedParcel[]
A greater file id corresponds to a later file publishing.
This method is used to provide links for downloading published data files with
tracking information.
This method requires bulk tracking service enrolment, for which you may contact
your key account manager.
Web service URL: BASE_URL/track/bulk
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
BulkTrackingDataFilesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
last_processed_file_id
Long
Yes
The greatest data file id processed in client system. To get all published data
files during last 10 days use 0 as lastProcessedFileId
The last processed file id must refer to a file published during last 10 days.
Otherwise, error is returned.
2.4 PICKUP
Web service URL: BASE_URL/pickup
2.4.1 PICKUP REQUEST (PICKUPREQUEST)
Web service URL: BASE_URL/pickup
Method: POST
Content-type: application/json; charset=utf-8
PickupRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
pickupDateTime
Date
(String in format “yyyy-MM-dd'T'HH:mm:ssZ”)
No
Pickup datetime. If not provided, it is assumed now. Seconds and milliseconds
are ignored.
autoAdjustPickupDate
Boolean
No (default value is false)
To find first available date for pickup starting from pickupDate according to
pickup schedule for services
pickupScope
enum
[“EXPLICIT_SHIPMENT_ID_LIST”,
“ALL_CREATED_BY_LOGGED_USER”,
“ALL_CREATED_BY_SAME_CLIENT”]
“ALL_CREATED_BY_SAME_CONTRACT_USERS”]
No
Default is EXPLICIT_SHIPMENT_ID_LIST
Scope of shipments to order.
ALL_CREATED_BY_SAME_CONTRACT_USERS can be used in case a logged user have the
access rights to access shipments created by other users in the same contract.
explicitShipmentIdList
String[]
No
Required when pickup scope is EXPLICIT_SHIPMENT_ID_LIST
visitEndTime
String (format HH:ss)
Yes
Example 9:30, or 11:35
The last possible time when the address could be visited on the pickup date.
contactName
String
No
Contact name.
phoneNumber
ShipmentPhoneNumber
No
Customer’s phone number.
Example JSON:
{
"userName":"testUser",
"password":"password",
"pickupDateTime":"2017-12-05T14:30:00+0200",
"explicitShipmentIdList":["80002338331", "80002338159"],
"visitEndTime": 18:20
}
2.4.2 PICKUP RESPONSE (PICKUPRESPONSE)
PickupResponse
Name
Type
Mandatory
Data
orders
PickupOrder[]
Yes
Pickup orders created
error
Error
No
Response error
2.4.3 PICKUP REQUEST - URL (GET) SCHEMA
This approach is used to request a pickup, providing data in an URL instead of
JSON data in the content.
Web service URL: BASE_URL/pickup
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
PickupRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
name
String
No
Country search term. Filters the results by country name prefix or part of
country name
isoAlpha2
String
No
Country iso alpha 2. Filters result by exact match if presents. ISO alpha 2
value uniquely identifies country and other criterias are not needed if this one
presents
isoAlpha3
String
No
Country iso alpha 3. Filters result by exact match if presents. ISO alpha 3
value uniquely identifies country and other criterias are not needed if this one
presents
Example JSON:
{
"userName":"testUser",
"password":"password",
"name":"ROMA"
}
2.5.1.5 FIND COUNTRY RESPONSE (FINDCOUNTRYRESPONSE)
The countries in return are these that match search criteria in request and
ordered by:
* Exact match is on top, followed by
* Country name prefix matches, followed by
* Country name contains matches (search term is in the name but not a prefix)
The result is limited to 10 records.
FindCountryResponse
Name
Type
Mandatory
Data
countries
Country[]
No
Array of countries
error
Error
No
Response error
2.5.1.6 FIND COUNTRY REQUEST - URL (GET) SCHEMA
This approach is used to find country, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/location/country
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindCountryRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.1.8 GET ALL COUNTRIES RESPONSE (GETALLCOUNTRIESRESPONSE)
See Country data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* id - ISO country id
* name - Country name in local language
* nameEn - Country name in English
* isoAlpha2 - ISO alpha 2 code
* isoAlpha3 - ISO alpha 3 code
* postCodeFormats - all allowed postcode patterns are separated with comma and
the whole value is escaped with quotation marks
* requireState - flag whether country requires state
* addressType - address type (1 or 2 - see ShipmentAddress) for this country
* currencyCode - current active currency code used for COD
* defaultOfficeId - default office id
* streetTypes - comma separated list of all street types escaped with quotation
marks in local language. This value is applicable for addressType 1 only
* streetTypesEn - comma separated list of all street types escaped with
quotation marks in English. This value is applicable for addressType 1 only
* complexTypes - comma separated list of all complex types escaped with
quotation marks in local language. This value is applicable for addressType 1
only
* complexTypesEn - comma separated list of all complex types escaped with
quotation marks in English. This value is applicable for addressType 1 only
* siteNomen - site nomenclature (0, 1 ,2)
2.5.1.9 GET ALL COUNTRIES REQUEST - URL (GET) SCHEMA
This approach is used to get all countries as CSV file (UTF8 encoded), providing
data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/country
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
GetAllCountriesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
countryId
integer
Yes
Country id
name
String
No
Search term for state name. Filters the results by state name prefix or part of
state name.
Example JSON:
{
"userName":"testUser",
"password":"password",
"countryId":840,
"name":"A"
}
2.5.2.5 FIND STATE RESPONSE (FINDSTATERESPONSE)
The states in return are these that match search criteria in request and ordered
by:
* Exact match is on top, followed by
* State name prefix matches, followed by
* State name contains matches (search term is in the name but not a prefix)
The result is limited to 10 records.
FindStateResponse
Name
Type
Mandatory
Data
states
State[]
No
Array of sites
error
Error
No
Response error
2.5.2.6 FIND STATE REQUEST - URL (GET) SCHEMA
This approach is used to find site, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/location/state
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindStateRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.2.8 GET ALL STATES RESPONSE (GETALLSTATESRESPONSE)
See State data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* id - state id
* name - state name in local language
* nameEn - state name in English
* isoAlpha - ISO alpha code
* countryId - country id (ISO code)
2.5.2.9 GET ALL STATES REQUEST - URL (GET) SCHEMA
This approach is used to get all states as CSV file (UTF8 encoded), providing
data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/state/{countryId}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Country id is is specified as a path parameter. The response is the same as
method using JSON schema.
URL parameters:
GetAllStatesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
countryId
integer
Yes
Country id
name
String
No
Search term for site name. Filters the results by site name prefix or part of
site name.
postCode
String
No
Filter results by postcode - valid postcode for site
type
String
No
Filter results by site type (exact match)
municipality
String
No
Filter by municipality (prefix match)
region
String
No
Filter by region (prefix match)
Example JSON:
{
"userName":"testUser",
"password":"password",
"countryId":642,
"name":"A"
}
2.5.3.5 FIND SITE RESPONSE (FINDSITERESPONSE)
The sites in return are these that match search criteria in request and ordered
by:
* Exact match is on top, followed by
* Site name prefix matches, followed by
* Site name contains matches (search term is in the name but not a prefix)
The result is limited to 10 records.
FindSiteResponse
Name
Type
Mandatory
Data
sites
Site[]
No
Array of sites
error
Error
No
Response error
2.5.3.6 FIND SITE REQUEST - URL (GET) SCHEMA
This approach is used to find site, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/location/site
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindSiteRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.3.8 GET ALL SITES RESPONSE (GETALLSITESRESPONSE)
See Site data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* id - site id
* countryId - country id (ISO code)
* mainSiteId - reference to main site if this site is a "satellite" one
* type - site type in local language
* typeEn - site type in English
* name - site name in local language
* nameEn - site name in English
* municipality - municipality in local language
* municipalityEn - municipality in English
* region - region in local language
* regionEn - region in English
* postCode - default post code for this site (if any)
* addressNomenclature - code for address nomenclature (streets, complexes,
blocks, poi) support. Values are: 0 - no address nomenclature, 1 - partial
address nomenclature, 2 - full address nomenclature
* x - X (longitude) coordinate of site center
* y - Y (latitude) coordinate of site center
* servingDays - serving days for this site. Format: 7 serial digits (0 or 1)
where each digit corresponds to a day in week (the first digit corresponds to
Monday, the second to Tuesday and so on). Value of '0' (zero) means that the
site is not served by Speedy on this day while '1' (one) means that it is
served. (Example: the text "0100100" means that the site is served on Tuesday
and Friday only.)
* servingOfficeId - Site's serving office
* servingHubOfficeId - The hub office ID to which serving office is connected
2.5.3.9 GET ALL SITES REQUEST - URL (GET) SCHEMA
This approach is used to get all sites as CSV file (UTF8 encoded), providing
data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/site/{countryId}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Country id is is specified as a path parameter. The response is the same as
method using JSON schema.
URL parameters:
GetAllSitesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
siteId
integer
Yes
Site id
name
String
No
Search term for street name. Filters the results by street name prefix or part
of street name.
type
String
No
Filter results by street type (exact match)
Example JSON:
{
"userName":"testUser",
"password":"password",
"siteId":642279132,
"name":"A"
}
2.5.4.5 FIND STREET RESPONSE (FINDSTREETRESPONSE)
The streets in return are these that match search criteria in request and
ordered by:
* Exact match is on top, followed by
* Street name prefix matches, followed by
* Street name contains matches (search term is in the name but not a prefix)
The result is limited to 10 records.
FindStreetResponse
Name
Type
Mandatory
Data
streets
Street[]
No
Array of streets
error
Error
No
Response error
2.5.4.6 FIND STREET REQUEST - URL (GET) SCHEMA
This approach is used to find street, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/location/street
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindStreetRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.4.8 GET ALL STREETS RESPONSE (GETALLSTREETSRESPONSE)
See Street data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* id - street id
* siteId - site id
* type - street type in local language
* typeEn - street type in English
* name - street name in local language
* nameEn - street name in English
* actualId - actual street id (in case this street is renamed)
2.5.4.9 GET ALL STREETS REQUEST - URL (GET) SCHEMA
This approach is used to get all streets as CSV file (UTF8 encoded), providing
data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/street/{countryId}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Country id is is specified as a path parameter. The response is the same as
method using JSON schema.
This method requires a license (additional licensing contract) and permissions
(access rights).
To obtain such license please contact your key account manager.
URL parameters:
GetAllStreetsRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
siteId
integer
Yes
Site id
name
String
No
Search term for complex name. Filters the results by complex name prefix or part
of complex name.
type
String
No
Filter results by complex type (exact match)
Example JSON:
{
"userName":"testUser",
"password":"password",
"siteId":100,
"name":"A"
}
2.5.5.5 FIND COMPLEX RESPONSE (FINDCOMPLEXRESPONSE)
The complexes in return are these that match search criteria in request and
ordered by:
* Exact match is on top, followed by
* Complex name prefix matches, followed by
* Complex name contains matches (search term is in the name but not a prefix)
The result is limited to 10 records.
FindComplexResponse
Name
Type
Mandatory
Data
complexes
Complex[]
No
Array of complexes
error
Error
No
Response error
2.5.5.6 FIND COMPLEX REQUEST - URL (GET) SCHEMA
This approach is used to find complex, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/location/complex
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindComplexRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.5.8 GET ALL COMPLEXES RESPONSE (GETALLCOMPLEXESRESPONSE)
See Complex data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* id - street id
* siteId - site id
* type - street type in local language
* typeEn - street type in English
* name - street name in local language
* nameEn - street name in English
* actualId - actual street id (in case this street is renamed)
2.5.5.9 GET ALL COMPLEXES REQUEST - URL (GET) SCHEMA
This approach is used to get all complexes as CSV file (UTF8 encoded), providing
data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/complex/{countryId}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Country id is is specified as a path parameter. The response is the same as
method using JSON schema.
This method requires a license (additional licensing contract) and permissions
(access rights).
To obtain such license please contact your key account manager.
URL parameters:
GetAllComplexesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
siteId
integer
Yes
Site id
name
String
No
Search term for block name. Filters the results by block name prefix or part of
block name.
Example JSON:
{
"userName":"testUser",
"password":"password",
"siteId":10135,
"name":"A"
}
2.5.6.2 FIND BLOCK RESPONSE (FINDBLOCKRESPONSE)
The blocks in return are these that match search criteria in request and ordered
by:
* Exact match is on top, followed by
* Block name prefix matches, followed by
* Block name contains matches (search term is in the name but not a prefix)
The result is limited to 10 records.
FindBlockResponse
Name
Type
Mandatory
Data
blocks
Block[]
No
Array of blocks
error
Error
No
Response error
2.5.6.3 FIND BLOCK REQUEST - URL (GET) SCHEMA
This approach is used to find block, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/location/block
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindBlockRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.6.5 GET ALL BLOCKS RESPONSE (GETALLBLOCKSRESPONSE)
See Block data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* siteId - site id
* name - block name in local language
* nameEn - block name in English
2.5.6.6 GET ALL BLOCKS REQUEST - URL (GET) SCHEMA
This approach is used to get all blocks as CSV file (UTF8 encoded), providing
data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/block/{countryId}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Country id is is specified as a path parameter. The response is the same as
method using JSON schema.
This method requires a license (additional licensing contract) and permissions
(access rights).
To obtain such license please contact your key account manager.
URL parameters:
GetAllBlocksRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
siteId
integer
Yes
Site id
name
String
No
Search term for POI name. Filters the results by POI name prefix or part of POI
name.
Example JSON:
{
"userName":"testUser",
"password":"password",
"siteId":100,
"name":"A"
}
2.5.7.5 FIND POI RESPONSE (FINDPOIRESPONSE)
The points of interest in return are these that match search criteria in request
and ordered by:
* Exact match is on top, followed by
* POI name prefix matches, followed by
* POI name contains matches (search term is in the name but not a prefix)
The result is limited to 10 records.
FindPOIResponse
Name
Type
Mandatory
Data
pois
PointOfInterest[]
No
Array of points of interest
error
Error
No
Response error
2.5.7.6 FIND POI REQUEST - URL (GET) SCHEMA
This approach is used to find POI, providing data in an URL instead of JSON data
in the content.
Web service URL: BASE_URL/location/poi
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindPOIRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.7.8 GET ALL POINTS OF INTEREST RESPONSE (GETALLPOIRESPONSE)
See PointOfInterest data structure for additional information.
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* id - POI id
* siteId - site id
* name - POI name in local language
* nameEn - POI name in English
* address - POI address in local language
* addressEn - POI address in English
* x - X coordinate
* y - Y coordinate
* type - POI type in local language
* typeEn - POI type in English
2.5.7.9 GET ALL POINTS OF INTEREST REQUEST - URL (GET) SCHEMA
This approach is used to get all Points of Interest as CSV file (UTF8 encoded),
providing data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/poi/{countryId}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Country id is is specified as a path parameter. The response is the same as
method using JSON schema.
This method requires a license (additional licensing contract) and permissions
(access rights).
To obtain such license please contact your key account manager.
URL parameters:
GetAllPOIRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
Example JSON:
{
"userName":"testUser",
"password":"password",
}
2.5.8.2 GET ALL POSTCODES RESPONSE (GETALLPOSTCODESRESPONSE)
Response is CSV (comma separated) file int UTF8 encoding. The format is:
* postcode - Postcode
* siteId - site id
2.5.8.3 GET ALL POSTCODES REQUEST - URL (GET) SCHEMA
This approach is used to get all postcodes as CSV file (UTF8 encoded), providing
data in an URL instead of JSON data in the content.
Web service URL: BASE_URL/location/postcode/csv/{countryId}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
Country id is is specified as a path parameter. The response is the same as
method using JSON schema.
URL parameters:
GetAllPostcodesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
countryId
Integer
No
Country id ISO. Limits the search scope in the set of offices for specified
country. System default country is used if country id is omitted. If -1 is
specified - offices in all countires are searched
siteId
Long
No
Site id. Limits the search scope in the set of offices for specified site. If
omitted - all country offices are searched
siteName
String
No
Filters the results by office site name prefix or part of it.
name
String
No
Search term for office name. Filters the results by office name prefix or part
of site name.
limit
Long
No
The number of records to return in response. All records are returned if this
parameter is ommited
Example JSON:
{
"userName":"testUser",
"password":"password",
"countryId":642,
"name":"A"
}
2.5.9.5 FIND OFFICE RESPONSE (FINDOFFICERESPONSE)
The offices in return are these that match search criteria in request and
ordered by:
* Exact match is on top, followed by
* Office name prefix matches, followed by
* Office name contains matches (search term is in the name but not a prefix)
FindOfficeResponse
Name
Type
Mandatory
Data
offices
Office[]
No
Array of offices
error
Error
No
Response error
2.5.9.6 FIND OFFICE REQUEST - URL (GET) SCHEMA
This approach is used to find office, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/location/office
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindOfficeRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
countryId | country_id
Integer
No
Country id ISO. Limits the search scope in the set of offices for specified
country. System default country is used if country id is omitted. If -1 is
specified - offices in all countires are searched.
siteId | site_id
Long
No
Site id.Limits the search scope in the set of offices for specified site. If
omitted - all country offices are searched
siteName | site_name
String
No
Filters the results by office site name prefix or part of it
name
String
No
Search term for office name. Filters the results by office name prefix or part
of office name.
limit
Long
No
The number of records to return in response. All records are returned if this
parameter is ommited
Example:
BASE_URL/location/office/?username=test&password=test&country_id=642&name=a
2.5.9.7 FIND NEAREST OFFICES REQUEST (FINDNEARESTOFFICESREQUEST)
Web service URL: BASE_URL/location/office/nearest-offices
Method: POST
Content-type: application/json; charset=utf-8
Find nearest offices using search criteria
FindNearestOfficesRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
address
ShipmentAddress
Yes
Address to which the nearest offices are searched
Only country id is mandatory
distance
Integer
No
Maximum office distance ( in meters ) from provided address
limit
Integer
No
The number of records to return in response.
officeType
enum ["OFFICE", "APT"]
No
Filter offices by type.
officeFeatures
enum ["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP",
"CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][]
No
Supported office features
Example JSON:
{
"userName":"testUser",
"password":"password",
"address" {
"countryId":100,
"siteName":"Sofia"
}
"distance":1500,
"officeFeatures" [
"CARD_PAYMENT"
]
}
2.5.9.8 FIND NEAREST OFFICES RESPONSE (FINDNEARESTOFFICESRESPONSE)
The offices in return are these that match search criteria in request and
ordered by distance
FindNearestOfficesResponse
Name
Type
Mandatory
Data
offices
OfficeResult[]
No
Array of offices
x
Double
No
Provided address X coord
y
Double
No
Provided address Y coord
error
Error
No
Response error
2.5.9.9 FIND NEAREST OFFICES - URL (GET) SCHEMA
This approach is used search nearest offices, providing data in an URL instead
of JSON data in the content.
Web service URL: BASE_URL/location/office/nearest-offices
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
FindNearestOfficesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
Shipment Address
See ShipmentAddress for more details.
countryId | country_id
Integer
No
Country ISO code. If not provided, the local country is assumed.
Used for all address types.
stateId | state_id
String
Required, if country supports states.
Country state.
Used for addresses of type 2 (foreign address).
siteId | site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided.
Site id.
Used for all address types. If not provided, but site type and name or post code
is provided - the system will try to find unique match by them in country
siteType | site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for addresses of type 1 (local address).
Max 20
siteName | site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for all address types.
Max 50
postcode | postCode | post_code
String
No
Can be used in conjunction with countryId to find unique site.
Used for all address types.
Validated for valid postcode in site and country.
Max 10
streetId | street_id
Long
No
Street identifier. If not provided, but street type and street name are provided
- the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
streetType | street_type
String
No
Forbidden, if street_id is provided.
Street type.
Used for addresses of type 1 (local address).
Max 15
streetName | street_name
String
No
Forbidden, if street_id is provided.
Street name.
Used for addresses of type 1 (local address).
Max 50
streetNumber | street_number
String
No
Street number.
Used for addresses of type 1 (local address).
Max 10
complexId | complex_id
Long
No
Complex identifier. If not provided, but complex type and complex name are
provided - the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
complexType | complex_type
String
No
Forbidden, if complex_id is provided.
Complex type.
Used for addresses of type 1 (local address).
Max 15
complexName | complex_name
String
No
Forbidden, if complex_id is provided.
Complex name.
Used for addresses of type 1 (local address).
Max 50
block | blockNo | block_no
String
No
Block No.
Used for addresses of type 1 (local address).
Max 32
entrance | entranceNo | entrance_no
String
No
Entrance.
Used for addresses of type 1 (local address).
Max 10
floor | floorNo | floor_no
String
No
Floor.
Used for addresses of type 1 (local address).
Max 10
apartment | apartmentNo | apartment_no
String
No
Apartment.
Used for addresses of type 1 (local address).
Max 10
poiId | poi_id
Long
No
Point of interest identifier.
Used for addresses of type 1 (local address).
addressNote | address_note | note
String
No
Address note.
Used for addresses of type 1 (local address).
200
addressLine1 | address_line1 | line1
String
Required for address type 2.
Address line 1. Used for addresses of type 2 (foreign address).
Max 35
addressLine2 | address_line2 | line2
String
No
Address line 2. Used for addresses of type 2 (foreign address).
Max 35
X | x
Double
No
GIS coordinates - X.
Used for all address types.
Y | y
Double
No
GIS coordinates - Y.
Used for all address types.
limit
Integer
No
The number of records to return in response.
distance
Integer
No
Maximum office distance ( in meters ) from the provided address
type
Integer
No
enum["CASH", "POSTAL_MONEY_TRANSFER"]
office_features | officeFeatures
Integer
No
enum["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL",
"CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][]
Multiple values are separated with %7C ( '|' ) character.
2.6 CALCULATION SERVICE
Web service URL: BASE_URL/calculate
2.6.1 CALCULATION REQUEST (CALCULATIONREQUEST)
Web service URL: BASE_URL/calculate
Method: POST
Content-type: application/json; charset=utf-8
CalculationRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
Calculation sender details
If logged user is the sender, you may skip providing sender details at all.
If you refer an existing customer, provide client’s id in sender_id parameter
and other sender parameters may be skipped at all also.
Otherwise, sender_id should stay empty and it is required to provide as a
minimum:
* sender privatePerson flag
* sender address location or dropoffOfficeId
senderId | sender_id
Long
No
Client id to refer а sender
Validate for existence.
senderPrivatePerson | sender_private_person
Boolean
(true/false, y/n, âyes/noâ - all case insensitive)
If sender_id is provided, it is forbidden. If the sender is the logged user,
should be omitted too. Otherwise, it is mandatory
Sender private person flag.
Sender Address Location Details
See AddressLocation for more details.
The sender address location is expected when sender_id is empty and
sender_dropoff_office_id is empty and not required. In other words, the sender
address location is required when the sender is not a referred customer or
logged user and pickup at senderâs address is expected.
senderAddressCountryId | sender_address_country_id
Integer
No
Country ISO code. If not provided, the local country is assumed. Used for all
address types.
Validate for valid country code
senderAddressStateId | sender_address_state_id
String
Required if country requires state
Country state. Used for addresses of type 2 (foreign address).
Validate for valid country state.
senderAddressSiteId | sender_address_site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided
Site id. Used for all address types
Validate for valid site and value is required
senderAddressSiteType | sender_address_site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for addresses of type 1 (local address)
Max 20 characters
senderAddressSiteName | sender_address_site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for all address types.
Max 50 characters
senderAddressPostcode | senderAddressPostCode | sender_address_postcode
String
Required if country requires post code
Can be used in conjunction with countryId to find unique site. Used for all
address types
Max 10 characters
dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId |
senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id
Integer
Required, if the sender is an internal customer. If sender address is provided,
it is forbidden.
Drop off office id.
Should refer to a valid accessible office
sender_geo_pudo_id | senderGeoPUDOId | dropoff_geo_pudo_id | dropoffGeoPUDOId
String
No. Must be empty if dropoffOfficeId is provided
DPD drop off office PUDO id
Should refer to a valid accessible DPD office.
Calculation recipient details
If you refer an existing customer, provide client's id in recipient_id
parameter and other recipient parameters may be skipped at all
Otherwise, recipient_id should stay empty and it is required to provide as a
minimum:.
* recipient privatePerson flag
* recipient address location or pickupOfficeId
recipientId | recipient_id
Long
No
Client id to refer а recipient
Validate for existence.
recipientPrivatePerson | recipient_private_person
Boolean
(true/false, y/n, âyes/noâ - all case insensitive)
If recipient_id is provided, it is forbidden. Otherwise, it is mandatory
Recipient private person flag.
Recipient Address Location Details
See AddressLocation for more details.
The recipient address location is expected when recipient_id is empty and
recipient_pickup_office_id is empty and not required. In other words, the
recipient address location is required when the recipient is not a referred
customer and delivery at recipientâs address is expected.
recipientAddressCountryId | recipient_address_country_id
Integer
No
Country ISO code. If not provided, the local country is assumed. Used for all
address types.
Validate for valid country code
recipientAddressStateId | recipient_address_state_id
String
Required if country requires state
Country state. Used for addresses of type 2 (foreign address).
Validate for valid country state.
recipientAddressSiteId | recipient_address_site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided
Site id. Used for all address types
Validate for valid site and value is required
recipientAddressSiteType | recipient_address_site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for addresses of type 1 (local address)
Max 20 characters
recipientAddressSiteName | recipient_address_site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for all address types.
Max 50 characters
recipientAddressPostcode | recipientAddressPostCode | recipient_address_postcode
String
Required if country requires post code
Can be used in conjunction with countryId to find unique site. Used for all
address types
Max 10 characters
pickupOfficeId | pickUpOfficeId | recipientPickupOfficeId |
recipientPickUpOfficeId | pickup_office_id | recipient_pickup_office_id
Integer
Required, if the recipient is an internal customer. If recipient address is
provided, it is forbidden.
Pickup office id.
Should refer to a valid accessible office
recipient_geo_pudo_id | recipientGeoPUDOId | pickup_geo_pudo_id |
pickupGeoPUDOId
String
No. Must be empty if pickupOfficeId is provided
DPD pickup office PUDO id
Should refer to a valid accessible DPD office.
Calculation Service Details
See CalculationService for more details.
Shipment service defines agreement with customer for courier service. This
includes:
* Pickup date
* Service ids (codes)
* Optional defer days or saturday delivery
* Additional services (like COD, Declared value,and etc.)
pickupDate | pickup_date
Date (date) Example: â2018-01-22"
No (default value is today)
The date for shipment pick-up
Could be today or a future date.
autoAdjustPickupDate | auto_adjust_pickup_date | autoadjust_pickup_date
Boolean
No (default is false)
To find first available date for pickup starting from pickupDate according to
pickup schedule for services
serviceIds | service_ids
String (comma separated service ids)
Yes
Service ids to get calculation for.
Each service id (code) should be valid for destination
deferredDays | deferred_days
Integer
No (default value is 0)
This parameter allowscusers to specify by how many (business) days they would
like to postpone the shipment delivery from the standard term..
Allowed values are 0, 1 and 2
saturdayDelivery | saturday_delivery
Boolean
No)
This parameter may adjust the delivery date to the first business day, if the
standard calculated delivery day is a half-working day. If not specified, system
will determine this flag based on configured recipient working schedule.
COD Additional Service
For more information see ShipmentCODAdditionalService.
codAmount | cod_amount
double
No
Defines shipment COD base amount.
Validated against maximum allowed amounts for destination.
codCurrency | cod_currency
String
No
(default is the currency code of the destination country)
Defines shipment COD currency code.
Validated against allowed currency code of destination country.
codProcessingType | cod_processing_type
enum
[“CASH”, “POSTAL_MONEY_TRANSFER”]
No
(default is “CASH”)
Defines COD processing type.
Appropriate contract and annexes may be required.
codPayoutThirdParty | cod_payout_third_party
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
If this flag is set, the COD is paid to a third party (not to the sender).
Requires the third party to be the payer of the courier service.
codWithShippingPrice | cod_with_shipping_price
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Flag indicating whether the shipping price should be included in the COD.
Options before payment details Additional Service
For more information see ShipmentOBPD.
obpd_option
enum
[“OPEN”, “TEST”]
No
(For certain destinations could be required.)
Defines option to be used.
Open parcels before payment or open and test parcels before payment.
Return shipment is validated for destination.
obpd_return_service_id
Integer
No
(For certain destinations could be required.)
Defines service id to be used on return, if COD payment is refused.
Return shipment is validated for destination.
obpd_return_payer
enum
[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]
No
(For certain destinations could be required.)
Defines who pays the return shipment, if COD payment is refused.
Return shipment is validated for destination.
Declared Value (Extended Liability) Additional Service
For more information see ShipmentDeclaredVaueAdditionalService.
Declared value payer is required when declared value amount is provided and is
set in payment section.
declaredValueAmount | declared_value_amount
double
No
Defines shipment Declared Value (extended liability) base amount. Declared value
amount is always in local system currency.
Validated against maximum allowed amounts.
fragile | declaredValueFragile | declared_value_fragile
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Defines fragile flag for shipment content.
Fragile shipments requires declared value sub service.
declaredValueIgnoreIfNotApplicable | declared_value_ignore_if_not_applicable
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
No
Flag to ignore declared value additional service in case it is not applicable
for shipment on calculation
E-shops usually configure declared value (extended liability) by default for
their shipments, However there are some certain internal rules when this option
is not available. The flag is used in calculation service to provide price to
end clients without repeating the calculation request with removed additional
service
Fixed Time Delivery Additional Service
Fixed time delivery is an additional service that provides instruction to
deliver shipment at a certain time on the delivery date.
fixedTimeDelivery | fixed_time_delivery
Integer
No
This option fixes the time of delivery on the delivery date. 1130 - means 11:30
920 - means 09:20
This option is checked against configured allowed time frame for the service.
Special Delivery Additional Service
Special delivery is an additional service that provides instruction to the
courier to do additional (special) checks and actions on delivery. These checks
and actions are negotiated and contracted in a special delivery annex. For
example, the courier could be instructed to check IDs of recipient party at
delivery.
specialDeliveryId | special_delivery_id
Integer
No
Specifies special delivery identifier for the shipments. Identifiers are
determined in a special delivery annex.
Requires annex for special delivery.
Delivery to Floor Additional Service
Delivery to floor is an additional service that provides instruction to the
courier that the shipment should not be delivered to the entrance of a multi
floor building, but should be moved to a certain floor before delivery.
deliveryToFloor | delivery_to_floor
Integer
No
Specifies the floor number in the building where to deliver shipment.
This additional service requires annex.
Calculation Content
For more information see CalculationContent.
Defines what is to be delivered with the shipment.
parcelsCount | parcels_count
Integer
Required when parcels list is empty
Total shipmentâs parcels count. Ignored, if parcels list is not empty. The
parcels count is the number of parcels in the lits in that case
Validated against minimum and maximum allowed for the service
totalWeight | total_weight
Double
Required when parcels list is empty
Total weight declared for the shipment. Ignored, if parcels list is not empty.
The total weight is the sum of all parcelâs weight in that case.
Validated against minimum and maximum allowed for the service
documents
Boolean (true/false, y/n, âyes/noâ - all case insensitive)
No
Documents flag of the shipment
palletized
Boolean (true/false, y/n, âyes/noâ - all case insensitive)
No
Palletized flag of the shipment
parcels
String
Format for single parcel is:
<seqNo>,<weight>,
<width>x<depth>x<height>,
<packageUniqueNumber>,
<id>,
<externalCarrierParcelNumber>
Multiple parcels should be separated with %7C (‘|’) character.
See ShipmentParcel
Required for pallet and postal services. For multiple parcels add the same url
parameter again. The parameters are parsed in the order of their occurrence. If
the sequence is incomplete, the missing parameters are considered empty.
List of parcels. If provided, parcel_count and total_weight are ignored
Validated against service configuration and pickup and delivery capacity of the
depots and the couriers.
Shipment Payment
For more information see ShipmentPayment.
Defines who-pays-what in shipment and other payment parameters.
courierServicePayer | courier_service_payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
Yes
Courier service payer.
Validated against the service, destination, contracts and annexes.
declaredValuePayer | declared_value_payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
No
Declared value payer. If not provided, the courier service payer is assumed. Not
expected, if the declared value amount is empty.
Validated against the service, destination, contracts and annexes.
packagePayer | package_payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
No
Package payer. If not provided, the courier service payer is assumed.
Validated against the service, destination, contracts and annexes.
thirdPartyClientId | third_party_client_id
Long
No
Defines shipment third party - used as a payer of any of shipment payable
components.
Third party customer should be registered customer with valid contract and annex
for delayed payment at pickup date. Third party customer should be
customer(object) in the same contract as the logged user.
Discount card
For more information see ShipmentDiscountCardId.
Discount cards provide promotional discounts.
discountCardContractId | discount_card_contract_id
Long
No
Discount card contract id.
Validated against a referred contract.
discountCardId | discount_card_id
Long
No
Discount card id for contract.
Validated against a referred discount card.
2.7 CLIENT SERVICE
Web service URL: BASE_URL/client
2.7.1 GET CLIENT REQUEST (GETCLIENTREQUEST)
Web service URL: BASE_URL/client/{id}
Method: POST
Content-type: application/json; charset=utf-8
Get client by id. Client id is provided as parameter in URL path
GetClientRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
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
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
externalContactId | external_contact_id
String
Yes
External contact id (caller client Id unique reference)
Max 30 characters. Unique for caller
secretKey | secret_key
String
No
External contact secret key
Max 36 characters
phone1
String
Yes
First phone number.
phone1Ext | phone1_ext
String
No
First phone number extension.
phone2
String
No
Second phone number.
phone2Ext | phone2_ext
String
No
Second phone number extension.
clientName | client_name
String
Yes
Conact customer name.
Minimum 3 symbols, maximum 60
objectName | object_name
String
Forbidden for private persons. Not mandatory for companies
Conact customer object name.
Minimum 3 symbols, maximum 60
contactName | contact_name
String
No
Forbidden for private persons. Required for companies.
Contact name of contact.
Maximum 60.
email
String
No
Contact email.
Maximum 255
privatePerson | private_person
Boolean
(true/false, y/n, “yes/no” - all case insensitive)
Yes
Contact private person flag.
Contact Address
See ShipmentAddress for more details.
addressCountryId | address_country_id
Integer
No
Country ISO code. If not provided, local country is assumed.
Used for all address types.
addressStateId | address_state_id
String
Required, if country supports states.
Country state.
Used for addresses of type 2 (foreign address).
addressSiteId | address_site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided.
Site id.
Used for all address types. If not provided, but site type and name or post code
is provided - the system will try to find unique match by them in country
addressSiteType | address_site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for addresses of type 1 (local address).
Max 20
addressSiteName | address_site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for all address types.
Max 50
addressPostcode | addressPostCode | address_postcode
String
No
Can be used in conjunction with countryId to find unique site.
Used for all address types.
Validated for valid postcode in site and country.
Max 10
addressStreetId | address_street_id
Long
No
Street identifier. If not provided, but street type and street name are provided
- the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
addressStreetType | address_street_type
String
No
Forbidden, if street_id is provided.
Street type.
Used for addresses of type 1 (local address).
Max 15
addressStreetName | address_street_name
String
No
Forbidden, if street_id is provided.
Street name.
Used for addresses of type 1 (local address).
Max 50
addressStreetNumber | address_street_number
String
No
Street number.
Used for addresses of type 1 (local address).
Max 10
addressComplexId | address_complex_id
Long
No
Complex identifier. If not provided, but complex type and complex name are
provided - the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
addressComplexType | address_complex_type
String
No
Forbidden, if complex_id is provided.
Complex type.
Used for addresses of type 1 (local address).
Max 15
addressComplexName | address_complex_name
String
No
Forbidden, if complex_id is provided.
Complex name.
Used for addresses of type 1 (local address).
Max 50
addressBlock | addressBlockNo | address_block
String
No
Block No.
Used for addresses of type 1 (local address).
Max 32
addressEntrance | addressEntranceNo | address_entrance
String
No
Entrance.
Used for addresses of type 1 (local address).
Max 10
addressFloor | addressFloorNo | address_floor
String
No
Floor.
Used for addresses of type 1 (local address).
Max 10
addressApartment | addressApartmentNo | address_apartment
String
No
Apartment.
Used for addresses of type 1 (local address).
Max 10
addressPoiId | address_poi_id
Long
No
Point of interest identifier.
Used for addresses of type 1 (local address).
addressNote | address_note
String
No
Address note.
Used for addresses of type 1 (local address).
200
addressLine1 | address_line1
String
Required for address type 2
Address line 1. Used for addresses of type 2 (foreign address).
Max 35
addressLine2 | address_line2
String
No
Address line 2. Used for addresses of type 2 (foreign address).
Max 35
addressX | address_x
Double
No
GIS coordinates - X.
Used for all address types.
addressY | address_y
Double
No
GIS coordinates - Y.
Used for all address types.
2.7.10 GET CONTACT BY EXTERNAL ID REQUEST (GETCONTACTBYEXTERNALIDREQUEST)
Web service URL: BASE_URL/client/contact/external/{id}
Method: POST
Content-type: application/json; charset=utf-8
Get contact by external id. External client id is provided as parameter in URL
path
GetContactByExternalIdRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
secretKey
String
No
Secret key
Max 36 characters
2.7.11 GET CONTACT BY EXTERNAL ID RESPONSE (GETCONTACTBYEXTERNALIDRESPONSE)
GetContactByExternalIdResponse
Name
Type
Mandatory
Data
client
Client
No
Client data
error
Error
No
Response error
2.7.12 GET CONTACT BY EXTERNAL ID REQUEST - URL (GET) SCHEMA
This approach is used to get contact by external id, providing data in an URL
instead of JSON data in the content.
Web service URL: BASE_URL/client/contact/external/{id}
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
External contact id is provided as URL path parameter. The response is the same
as method using JSON schema.
URL parameters:
GetContactByExternalIdRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
secretKey | secret_key
String
No
Secret key
Max 36 characters
2.7.13 GET OWN CLIENT ID REQUEST (GETOWNCLIENTIDREQUEST)
Web service URL: BASE_URL/client
Method: POST
Content-type: application/json; charset=utf-8
Get own client id
GetOwnClientIdRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
2.7.14 GET OWN CLIENT ID RESPONSE (GETOWNCLIENTIDRESPONSE)
GetOwnClientIdResponse
Name
Type
Mandatory
Data
clientId
Long
Yes
Own client id
error
Error
No
Response error
2.7.15 GET OWN CLIENT ID REQUEST - URL (GET) SCHEMA
This approach is used to get own client id, providing data in an URL instead of
JSON data in the content.
Web service URL: BASE_URL/client
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
GetOwnClientIdRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
2.7.16 CONTRACT INFO REQUEST (CONTRACTINFOREQUEST)
Web service URL: BASE_URL/client/contract/info
Method: POST
Content-type: application/json; charset=utf-8
Get information about logged user contract
ContractInfoRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
2.7.17 CONTRACT INFO RESPONSE (CONTRACTINFORESPONSE)
ContractInfoResponse
Name
Type
Mandatory
Data
id
Long
Yes
Contract id
specialDeliveryRequirements
SpecialDeliveryRequirements
No
Special delivery requirements
error
Error
No
Response error
moneyTransferAllowed
boolean
Yes
COD as money transfer allowed
codCashReceiptAllowed
boolean
Yes
COD cash receipt allowed
administrativeFeeAllowed
boolean
Yes
Administrative fee allowed
2.7.18 CONTRACT INFO REQUEST - URL (GET) SCHEMA
This approach is used to get contract information, providing data in an URL
instead of JSON data in the content.
Web service URL: BASE_URL/client/contract/info
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ContractInfoRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
2.8 VALIDATION SERVICE
Web service URL: BASE_URL/validation
2.8.1 VALIDATE ADDRESS REQUEST (VALIDATEADDRESSREQUEST)
Web service URL: BASE_URL/validation/address
Method: POST
Content-type: application/json; charset=utf-8
This method validates shipment address
ValidateAddressRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
address
ShipmentAddress
No
Shipment address to validate
2.8.2 VALIDATE ADDRESS RESPONSE (VALIDATIONRESPONSE)
ValidationResponse
Name
Type
Mandatory
Data
valid
Boolean
No
Validation result flag
error
Error
No
Response error
2.8.3 VALIDATE ADDRESS REQUEST - URL (GET) SCHEMA
This approach is used to validate address, providing data in an URL instead of
JSON data in the content.
Web service URL: BASE_URL/validation/address
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ValidateAddressRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
Shipment Address
See ShipmentAddress for more details.
countryId | country_id
Integer
No
Country ISO code. If not provided, the local country is assumed.
Used for all address types.
stateId | state_id
String
Required, if country supports states.
Country state.
Used for addresses of type 2 (foreign address).
siteId | site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided.
Site id.
Used for all address types. If not provided, but site type and name or post code
is provided - the system will try to find unique match by them in country
siteType | site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for addresses of type 1 (local address).
Max 20
siteName | site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site.
Used for all address types.
Max 50
postcode | postCode | post_code
String
No
Can be used in conjunction with countryId to find unique site.
Used for all address types.
Validated for valid postcode in site and country.
Max 10
streetId | street_id
Long
No
Street identifier. If not provided, but street type and street name are provided
- the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
streetType | street_type
String
No
Forbidden, if street_id is provided.
Street type.
Used for addresses of type 1 (local address).
Max 15
streetName | street_name
String
No
Forbidden, if street_id is provided.
Street name.
Used for addresses of type 1 (local address).
Max 50
streetNumber | street_number
String
No
Street number.
Used for addresses of type 1 (local address).
Max 10
complexId | complex_id
Long
No
Complex identifier. If not provided, but complex type and complex name are
provided - the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
complexType | complex_type
String
No
Forbidden, if complex_id is provided.
Complex type.
Used for addresses of type 1 (local address).
Max 15
complexName | complex_name
String
No
Forbidden, if complex_id is provided.
Complex name.
Used for addresses of type 1 (local address).
Max 50
block | blockNo | block_no
String
No
Block No.
Used for addresses of type 1 (local address).
Max 32
entrance | entranceNo | entrance_no
String
No
Entrance.
Used for addresses of type 1 (local address).
Max 10
floor | floorNo | floor_no
String
No
Floor.
Used for addresses of type 1 (local address).
Max 10
apartment | apartmentNo | apartment_no
String
No
Apartment.
Used for addresses of type 1 (local address).
Max 10
poiId | poi_id
Long
No
Point of interest identifier.
Used for addresses of type 1 (local address).
addressNote | address_note | note
String
No
Address note.
Used for addresses of type 1 (local address).
200
addressLine1 | address_line1 | line1
String
Required for address type 2.
Address line 1. Used for addresses of type 2 (foreign address).
Max 35
addressLine2 | address_line2 | line2
String
No
Address line 2. Used for addresses of type 2 (foreign address).
Max 35
X | x
Double
No
GIS coordinates - X.
Used for all address types.
Y | y
Double
No
GIS coordinates - Y.
Used for all address types.
2.8.4 VALIDATE POSTCODE REQUEST (VALIDATEPOSTCODEREQUEST)
Web service URL: BASE_URL/validation/postcode
Method: POST
Content-type: application/json; charset=utf-8
This method validates post code
ValidatePostCodeRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
countryId
Integer
Yes - if siteId is not specified
Country id
siteId
Long
Yes - if countryId is not specified
Site id
postCode
String
Yes
Postcode to validate
2.8.5 VALIDATE POSTCODE RESPONSE (VALIDATIONRESPONSE)
Same as 2.8.2 ValidationResponse
2.8.6 VALIDATE POSTCODE REQUEST - URL (GET) SCHEMA
This approach is used to validate post code, providing data in an URL instead of
JSON data in the content.
Web service URL: BASE_URL/validation/postcode
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ValidatePostCodeRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
countryId | country_id
Integer
Yes - if siteId is not specified
Country id
siteId | site_id
Long
Yes - if countryId is not specified
Site id
postcode | postCode | post_code
String
Yes
Postcode to validate
2.8.7 VALIDATE PHONE REQUEST (VALIDATEPHONEREQUEST)
Web service URL: BASE_URL/validation/phone
Method: POST
Content-type: application/json; charset=utf-8
This method validates phone number
ValidatePhoneRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
number
String
Yes
Phone number
ext
String
No
Phone number extension
2.8.8 VALIDATE PHONE RESPONSE (VALIDATIONRESPONSE)
Same as 2.8.2 ValidationResponse
2.8.9 VALIDATE PHONE REQUEST - URL (GET) SCHEMA
This approach is used to validate phone, providing data in an URL instead of
JSON data in the content.
Web service URL: BASE_URL/validation/phone
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ValidatePhoneRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
number
String
Yes
Phone number
ext
String
No
Phone number extension
2.8.10 VALIDATE SHIPMENT REQUEST (VALIDATESHIPMENTREQUEST)
Web service URL: BASE_URL/validation/shipment
Method: POST
Content-type: application/json; charset=utf-8
This method applies validation on shipment request
Input parameters:
ValidateShipmentRequest
Name
Type
Required
Data
Constraints
CreateShipmentRequest fields are here
2.8.11 VALIDATE SHIPMENT RESPONSE (VALIDATESHIPMENTRESPONSE)
Same as 2.8.2 ValidationResponse
2.8.12 VALIDATE SHIPMENT - URL (GET) SCHEMA
This approach is used to validate shipments, providing data in an URL instead of
JSON data in the content.
Web service URL: BASE_URL/validation/shipment
Method: GET
Content-type: “application/x-www-form-urlencoded; charset=utf-8”
The response is the same as method using JSON schema.
URL parameters:
ValidateShipmentRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
CreateShipmentRequest params are here
2.9 SERVICES SERVICE
Web service URL: BASE_URL/services
2.9.1 SERVICES REQUEST (SERVICESREQUEST)
Web service URL: BASE_URL/services
Method: POST
Content-type: application/json; charset=utf-8
Get available services for date
ServicesRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
date
Date (yyyy-MM-dd)
No
Date. Current date is assumed if not provided
2.9.2 SERVICES RESPONSE (SERVICESRESPONSE)
ServicesResponse
Name
Type
Mandatory
Data
services
CourierService[]
Yes
Available courier services
error
Error
No
Response error
2.9.3 SERVICES REQUEST - URL (GET) SCHEMA
This approach is used to get services, providing data in an URL instead of JSON
data in the content.
Web service URL: BASE_URL/services
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
ServicesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
date
Date (yyyy-MM-dd)
No
Date. Current date is assumed if not provided
2.9.4 DESTINATION SERVICES REQUEST (DESTINATIONSERVICESREQUEST)
Web service URL: BASE_URL/services/destination
Method: POST
Content-type: application/json; charset=utf-8
Get available services for date and destination
DestinationServicesRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
date
Date (yyyy-MM-dd)
No
Date. Current date is assumed if not provided
sender
CalculationSender
No
Defines the pickup place. If not specified, the logged user client location is
considered as a sender location.
recipient
CalculationRecipient
Yes
Defines the recipient delivery place.
2.9.5 DESTINATION SERVICES RESPONSE (DESTINATIONSERVICESRESPONSE)
DestinationServicesResponse
Name
Type
Mandatory
Data
services
ExtendedCourierService[]
Yes
Available courier services for destination
error
Error
No
Response error
2.9.6 DESTINATION SERVICES REQUEST - URL (GET) SCHEMA
This approach is used to get services for date and destination, providing data
in an URL instead of JSON data in the content.
Web service URL: BASE_URL/services/destination
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
DestinationServicesRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
date
Date (yyyy-MM-dd)
No
Date. Current date is assumed if not provided
Calculation sender details
If logged user is the sender, you may skip providing sender details at all.
If you refer an existing customer, provide client’s id in sender_id parameter
and other sender parameters may be skipped at all also.
Otherwise, sender_id should stay empty and it is required to provide as a
minimum:
* sender privatePerson flag
* sender address location or dropoffOfficeId
senderId | sender_id
Long
No
Client id to refer а sender
Validate for existence.
senderPrivatePerson | sender_private_person
Boolean
(true/false, y/n, âyes/noâ - all case insensitive)
If sender_id is provided, it is forbidden. If the sender is the logged user,
should be omitted too. Otherwise, it is mandatory
Sender private person flag.
Sender Address Location Details
See AddressLocation for more details.
The sender address location is expected when sender_id is empty and
sender_dropoff_office_id is empty and not required. In other words, the sender
address location is required when the sender is not a referred customer or
logged user and pickup at senderâs address is expected.
senderAddressCountryId | sender_address_country_id
Integer
No
Country ISO code. If not provided, the local country is assumed. Used for all
address types.
Validate for valid country code
senderAddressStateId | sender_address_state_id
String
Required if country requires state
Country state. Used for addresses of type 2 (foreign address).
Validate for valid country state.
senderAddressSiteId | sender_address_site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided
Site id. Used for all address types
Validate for valid site and value is required
senderAddressSiteType | sender_address_site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for addresses of type 1 (local address)
Max 20 characters
senderAddressSiteName | sender_address_site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for all address types.
Max 50 characters
senderAddressPostcode | senderAddressPostCode | sender_address_postcode
String
Required if country requires post code
Can be used in conjunction with countryId to find unique site. Used for all
address types
Max 10 characters
dropoffOfficeId | dropOffOfficeId | senderDropoffOfficeId |
senderDropOffOfficeId | dropoff_office_id | sender_dropoff_office_id
Integer
Required, if the sender is an internal customer. If sender address is provided,
it is forbidden.
Drop off office id.
Should refer to a valid accessible office
Calculation recipient details
If you refer an existing customer, provide client's id in recipient_id parameter
and other recipient parameters may be skipped at all
Otherwise, recipient_id should stay empty and it is required to provide as a
minimum:.
* recipient privatePerson flag
* recipient address location or pickupOfficeId
recipientId | recipient_id
Long
No
Client id to refer а recipient
Validate for existence.
recipientPrivatePerson | recipient_private_person
Boolean
(true/false, y/n, âyes/noâ - all case insensitive)
If recipient_id is provided, it is forbidden. Otherwise, it is mandatory
Recipient private person flag.
Recipient Address Location Details
See AddressLocation for more details.
The recipient address location is expected when recipient_id is empty and
recipient_pickup_office_id is empty and not required. In other words, the
recipient address location is required when the recipient is not a referred
customer and delivery at recipientâs address is expected.
recipientAddressCountryId | recipient_address_country_id
Integer
No
Country ISO code. If not provided, the local country is assumed. Used for all
address types.
Validate for valid country code
recipientAddressStateId | recipient_address_state_id
String
Required if country requires state
Country state. Used for addresses of type 2 (foreign address).
Validate for valid country state.
recipientAddressSiteId | recipient_address_site_id
Long
Required, if country has full site nomenclature and pair (site_type, site_name)
not provided
Site id. Used for all address types
Validate for valid site and value is required
recipientAddressSiteType | recipient_address_site_type
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for addresses of type 1 (local address)
Max 20 characters
recipientAddressSiteName | recipient_address_site_name
String
Forbidden, if site id is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with country_id and site_name to find
unique site. Used for all address types.
Max 50 characters
recipientAddressPostcode | recipientAddressPostCode | recipient_address_postcode
String
Required if country requires post code
Can be used in conjunction with countryId to find unique site. Used for all
address types
Max 10 characters
pickupOfficeId | pickUpOfficeId | recipientPickupOfficeId |
recipientPickUpOfficeId | pickup_office_id | recipient_pickup_office_id
Integer
Required, if the recipient is an internal customer. If recipient address is
provided, it is forbidden.
Pickup office id.
Should refer to a valid accessible office
2.10 PAYMENTS SERVICE
Web service URL: BASE_URL/payments
2.10.1 PAYOUT REQUEST (PAYOUTREQUEST)
Web service URL: BASE_URL/payments
Method: POST
Content-type: application/json; charset=utf-8
Get shipment payout details for a period
PayoutRequest
Name
Type
Required
Data
Constraints
userName
String
Yes
User name
password
String
Yes
Password
language
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId
Long
No
Client system id
Validated against system register for external customers.
fromDate
DateTime (yyyy-MM-dd'T'HH:mm:ssZ)
Yes
Start of period date time.
toDate
DateTime (yyyy-MM-dd'T'HH:mm:ssZ)
Yes
End of period date time.
includeDetails
boolean
No (default value is false)
Include payout details flag
2.10.2 PAYOUT RESPONSE (PAYOUTRESPONSE)
PayoutResponse
Name
Type
Mandatory
Data
payouts
Payout[]
Yes
Shipment payouts for a period
error
Error
No
Response error
2.10.3 PAYOUT REQUEST - URL (GET) SCHEMA
This approach is used to get shipment payouts, providing data in an URL instead
of JSON data in the content.
Web service URL: BASE_URL/payments
Method: GET
Content-type: application/x-www-form-urlencoded; charset=utf-8
The response is the same as method using JSON schema.
URL parameters:
PayoutRequest
URL Parameter Name
(synonyms are separated with |)
Type
Required
Data
Constraints
userName | username | user_name
String
Yes
User name
password
String
Yes
Password
language | lang
String
No
Language ( “EN”, “BG” ). Default is the default system language (BG).
clientSystemId | client_system_id
Long
No
Client system id
Validated against system register for external customers.
date_from
Date (yyyy-MM-dd'T'HH:mm:ssZ)
Yes
Start of period date time.
date_to
Date (yyyy-MM-dd'T'HH:mm:ssZ)
Yes
End of period date time.
include_details
boolean
(true/false, y/n, “yes/no” - all case insensitive)
No (Default value is false)
Flag to include payout details.
3 DATA STRUCTURES
3.1 SHIPMENT SERVICE (SHIPMENTSERVICE)
Shipment service defines service level agreement for the shipment - when
shipment should be picked up, service code to be used, sub-services, etc.
ShipmentService
Name
Type
Required
Data
Constraints
pickupDate
Date
Example: “2017-11-21"
No
(default value is today)
The date for shipment pickup.
Could be today or a future date.
autoAdjustPickupDate
Boolean
No (default value is false)
To find first available date for pickup starting from pickupDate according to
pickup schedule for services
serviceId
int
Yes
Service to be used for the shipment.
Service id (code) should be valid for the destination.
additionalServices
ShipmentAdditionalServices
No
Defines sub-services (like COD, Declared value, etc.) associated with the
shipment.
Sub-services may be allowed or forbidden for selected service and/or
destination.
deferredDays
Integer
No
(default value is 0)
This parameter allows users to specify by how many (business) days they would
like to postpone the shipment delivery from the standard term.
Allowed values are 0, 1 and 2.
saturdayDelivery
Boolean
No
This parameter may adjust delivery date to the first business day, if the
standard calculated delivery day is a half-working day. If not specified, system
will determine this flag based on configured delivery customer working schedule.
Example:
{
"pickupDate":"2017-11-21",
"serviceId":2,
"additionalServices":{
"cod":{
"amount":100.0,
"currencyCode":"RON",
"payoutToThirdParty":false,
"processingType":"CASH",
"includeShippingPrice":false
},
"declaredValue":{
"amount":100.0,
"fragile":false
},
"fixedTimeDelivery": 1130,
"returns":{
"rod":{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"returnReceipt":{
"enabled":true,
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"swap":{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":1234567
},
"rop":{
"pallets":[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":602,
"parcelsCount":2
}
]
},
"returnVoucher":{
"serviceId":3,
"payer":"RECIPIENT"
}
},
"specialDeliveryId":2,
"deliveryToFloor":3
},
"deferredDays":2,
"saturdayDelivery":true
}
3.1.1 SHIPMENT ADDITIONAL SERVICES (SHIPMENTADDITIONALSERVICES)
Allowance of additional services usage in the shipments is controlled and
determined by the courier service configuration. All shipment additional
services could be either:
* forbidden for usage with selected courier service
* allowed for usage with selected courier service
* required for usage with selected courier service
Some of the additional services may require additional prerequisites (like valid
contracts and annexes or serving offices in pickup or delivery site) to be
available for usage.
ShipmentSubServices
Name
Type
Required
Data
Constraints
cod
ShipmentCODAdditionalService
No
Defines shipment COD sub-service.
Seller could be required to have a valid contract and annex for COD for the
destination.
obpd
ShipmentOBPD
No
Defines shipment options before payment details.
declaredValue
ShipmentDeclaredValueAdditionalService
No
Defines shipment declared value (extended liability) sub-service.
fixedTimeDelivery
Integer
No
This option fixes the time of delivery on the delivery date. 1130 - means 11:30
920 - means 09:20
This option is checked against the configured allowed time frame for the
service.
returns
ShipmentReturnAdditionalServices
No
Defines a return sub-services.
Return shipments are verified for a return destination.
specialDeliveryId
Integer
No
Specifies special delivery identifier for the shipments. Identifiers are
determined in a special delivery annex.
Requires an annex for special delivery.
deliveryToFloor
Integer
No
Specifies the floor number in the building where to deliver the shipment.
This sub-service requires an annex.
Example JSON:
{
"cod":{
"amount":100.0,
"currencyCode":"RON",
"payoutToThirdParty":false,
"processingType":"CASH",
"includeShippingPrice":false
},
"declaredValue":{
"amount":100.0,
"fragile":false
},
"fixedTimeDelivery": 1130,
"returns":{
"rod":{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":66666666,
"thirdPartyPayer":false
},
"returnReceipt":{
"enabled":true,
"returnToClientId":66666666,
"thirdPartyPayer":false
},
"swap":{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":66666666
},
"rop":{
"pallets":[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":602,
"parcelsCount":2
}
]
},
"returnVoucher":{
"serviceId":3,
"payer":"RECIPIENT"
}
},
"specialDeliveryId":2,
"deliveryToFloor":3
},
"deferredDays":2,
"saturdayDelivery":true
}
Or simplest case (COD, with SWAP and ROD and disabled saturday delivery):
{
"cod":{
"amount":100.0,
},
"returns":{
"rod":{
"enabled":true,
},
"swap":{
"serviceId":3,
"parcelsCount":2,
},
}
},
"saturdayDelivery":false
}
3.1.1.1 COD ADDITIONAL SERVICE (SHIPMENTCODADDITIONALSERVICE)
ShipmentCODAdditionalService
Name
Type
Required
Data
Constraints
amount
double
Yes
Defines shipment COD base amount.
Validated against the maximum allowed amounts for the destination.
currencyCode
String
No
(default is the currency code for destination country)
Defines shipment COD currency code.
Validated against the allowed currency code for destination country.
processingType
enum
[“CASH”, “POSTAL_MONEY_TRANSFER”]
No
(default is “CASH”)
Defines COD processing type.
Appropriate contract and annexes may be required.
payoutToThirdParty
Boolean
No
If this flag is set, the COD is paid to third party (not to the sender).
Requires a third party to be the payer of the courier service.
payoutToLoggedClient
Boolean
No
If this flag is set, the COD is paid to the logged client.
includeShippingPrice
Boolean
No
Flag indicating whether the shipping price should be included in the COD.
cardPaymentForbidden
Boolean
No
Flag indicating that COD/PMT card payment is forbidden.
fiscalReceiptItems
ShipmentCODFiscalReceiptItem[]
This feature depends on country regulations and must be enabled for client
contract
The value in amount field is ignored if fiscal receipt items are provided.
List of items to issue fiscal receipt on behalf of client
If shipment has fiscal receipt items, the COD amount is the total amount with
VAT of all fiscal receipt items.
Example full JSON:
{
"amount":100.0,
"currencyCode":"RON",
"payoutToThirdParty":false,
"processingType":"CASH",
"includeShippingPrice":false
"cardPaymentForbidden":false
}
Or the simplest case:
{
"amount":100.0
}
3.1.1.1.1 SHIPMENT COD FISCAL RECEIPT ITEM (SHIPMENTCODFISCALRECEIPTITEM)
COD fiscal receipt item is used to form COD fiscal receipt to be issued on
behalf of client
ShipmentCODFiscalReceiptItem
Name
Type
Required
Data
Constraints
description
String
Yes
Fiscal receipt item description
Max 50 characters
vatGroup
String
Yes
VAT group
Must match one of available VAT groups (for example "А" - 0% VAT, "Б" - 20%VAT,
...).
amount
double
Yes
Item amount before VAT.
Must be positive value
amountWithVat
double
Yes
Item amount with VAT included
Must not be lower that amount before VAT
3.1.1.2 DECLARED VALUE (EXTENDED LIABILITY) ADDITIONAL
SERVICE(SHIPMENTDECLAREDVALUEADDITIONALSERVICE)
ShipmentDeclaredValueAdditionalService
Name
Type
Required
Data
Constraints
amount
double
Yes
Defines shipment Declared Value base amount. Declared value amount is always in
local system currency.
Validated against the maximum allowed amounts.
fragile
Boolean
No
Defines fragile flag for shipment content.
Fragile shipments require a declared value sub service.
ignoreIfNotApplicable
Boolean
No (Used in calculation service only, ignored in create shipment service)
Flag to ignore declared value additional service in case it is not applicable
for shipment on calculation
E-shops usually configure declared value (extended liability) by default for
their shipments, However there are some certain internal rules when this option
is not available. The flag is used in calculation service to provide price to
end clients without repeating the calculation request with removed additional
service
Example JSON:
{
"amount":100.0,
"fragile":false
}
Or using defaults you can specify 100.00 base amount non-fragile shipment with
courier service payer with just:
{
"amount":100.0
}
3.1.1.2 SHIPMENT RETURN ADDITIONAL SERVICES (SHIPMENTRETURNADDITIONALSERVICES)
Defines series of return sub-services, which require a reverse shipment to be
generated at primary shipment delivery. All the reverse shipments are validated
for allowance and for destination.
ShipmentReturnAdditionalServices
Name
Type
Required
Data
Constraints
rod
ShipmentRODAdditionalService
No
Defines Return Of Documents (ROD) sub-service.
The reverse shipment is validated for service and destination.
returnReceipt
ShipmentReturnReceiptAdditionalService
No
Defines Return Receipt sub-service.
The reverse shipment is validated for service and destination.
swap
ShipmentSWAPAdditionalService
No
Defines SWAP sub-service.
The reverse shipment is validated for service and destination.
rop
ShipmentROPAdditionalService
No
Defines Return Of Pallets (ROP) sub-service.
The reverse shipment is validated for service and destination.
returnVoucher
ShipmentReturnVoucherAdditionalService
No
Defines Return Voucher associated with the shipment.
The reverse shipment is validated for service and destination.
sendBackClientId
Long
No
Client id to specify send back address in case of a shipment return. Used in
shipment returns after Check/Test or in case recipient is not found. If not
specified the shipment is returned to the primary shipment sender.
Should be a customer address (object) in the same contract as the sender of the
shipment.
Example JSON:
{
"rod":{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"returnReceipt":{
"enabled":true,
"returnToClientId":1234567,
"thirdPartyPayer":false
},
"swap":{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":1234567
},
"rop":{
"pallets":[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":602,
"parcelsCount":2
}
]
},
"returnVoucher":{
"serviceId":3,
"payer":"RECIPIENT"
}
}
Or a simpler scenario (ROD, Return Receipt and SWAP):
{
"rod":{
"enabled":true
},
"returnReceipt":{
"enabled":true
},
"swap":{
"serviceId":3,
"parcelsCount":2
}
}
3.1.1.2.1 RETURN OF DOCUMENTS (ROD) ADDITIONAL SERVICE
(SHIPMENTRODADDITIONALSERVICE)
Return of Documents (ROD) additional service requires documents to be returned
upon the delivery of the primary shipment.
ShipmentRODAdditionalService
Name
Type
Required
Data
Constraints
enabled
boolean
Yes
Enabled flag
comment
String
No
Return documents comment.
Max size 512
returnToClientId
Long
No
Defines the recipient for the ROD shipment. If not specified and
returnToOfficeId is not specified also, the reverse shipment is returned to the
primary shipment sender.
Cannot be specified together with returnToOfficeId. The same value should be set
for ROD and Return Receipt, if the sub-service presents. Cannot be specified if
SWAP presents
returnToOfficeId
Integer
No
Defines delivery pickup depot for the ROD shipment. If not specified and
returnToClientId is not specified also, the reverse shipment is returned to the
primary shipment sender.
Cannot be specified together with returnToClientId. The same value should be set
for ROD, Return Receipt and SWAP, if the sub-service presents.
thirdPartyPayer
Boolean
No
Defines a third party payer for the ROD shipment. Otherwise the payer is the
primary shipment sender.
Requires a third party payer of the primary shipment. The same value should be
set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents.
Example JSON:
{
"enabled":true,
"comment":"Ret doc comment",
"returnToClientId":12345678,
"thirdPartyPayer": false
}
Or with default values:
{
"enabled":true
}
3.1.1.2.2 RETURN RECEIPT ADDITIONAL SERVICE
(SHIPMENTRETURNRECEIPTADDITIONALSERVICE)
Return Receipt additional service requires receipt to be returned upon the
delivery of the primary shipment.
ShipmentReturnReceiptAdditionalService
Name
Type
Required
Data
Constraints
enabled
boolean
Yes
Enabled flag
returnToClientId
Long
No
Defines the recipient for the Return Receipt shipment. If not specified and
returnToOfficeId is not specified also, the reverse shipment is returned to the
primary shipment sender.
Cannot be specified together with returnToOfficeId. The same values should be
set for ROD and Return Receipt, if the sub service presents. Cannot be specified
if SWAP presents
returnToOfficeId
Integer
No
Defines delivery pickup depot for the Return Receipt shipment. If not specified
and returnToClientId is not specified also, the reverse shipment is returned to
the primary shipment sender.
Cannot be specified together with returnToClientId. The same values should be
set for ROD, Return Receipt and SWAP, if the sub service presents.
thirdPartyPayer
Boolean
No
Defines a third party payer for the Return Receipt. Otherwise the payer is the
primary shipment sender.
Requires a third party payer of the primary shipment. The same values should be
set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
Example JSON:
{
"enabled":true,
"returnToClientId":12345678,
"thirdPartyPayer": false
}
Or with default values:
{
"enabled":true
}
3.1.1.2.3 SWAP ADDITIONAL SERVICE (SHIPMENTSWAPADDITIONALSERVICE)
SWAP additional service requires shipment with predefined parameters to be
returned upon the delivery of the primary shipment.
ShipmentSWAPAdditionalService
Name
Type
Required
Data
Constraints
serviceId
int
Yes
Service to be used in return.
Validated for allowance and destination.
parcelsCount
int
Yes
Number of parcels to return.
Validated against maximum allowed parcels.
declaredValue
Double
No
Declared value (extended liability) for the reverse shipment.
Validated for allowance and maximum amount.
fragile
Boolean
No
Fragile content flag for the reverse shipment.
Fragile shipments require declared value.
returnToOfficeId
Integer
No
Defines delivery pickup depot for the SWAP shipment. If not specified, the
reverse shipment is returned to the primary shipment sender.
The same values should be set for ROD, Return Receipt and SWAP, if the
sub-service presents.
thirdPartyPayer
Boolean
No
Defines a third party payer for the SWAP shipment. Otherwise the payer is the
primary shipment recipient.
Requires a third party payer of the primary shipment. The same value should be
set for ROD, Return Receipt, ROP and SWAP, if the sub-service presents.
Example JSON:
{
"serviceId":3,
"parcelsCount":2,
"declaredValue":13.0,
"fragile":false,
"returnToClientId":12345678
}
Or with default values:
{
"serviceId":3,
"parcelsCount":2
}
3.1.1.2.4 RETURN OF PALLETS (ROP) ADDITIONAL SERVICE
(SHIPMENTROPADDITIONALSERVICE)
Return Of Pallets additional service requires shipment with predefined
parameters to be returned upon the delivery of the primary shipment.
ShipmentROPAdditionalService
Name
Type
Required
Data
Constraints
pallets
ShipmentROPAdditionalServiceLine[]
Yes
Defines pallets to return grouped by service id.
Total number of returned pallets should not exceed the parcel count of the
primary shipment.
thirdPartyPayer
Boolean
No
Defines a third party payer for the returned pallets. Otherwise the payer is the
primary shipment sender.
Requires a third party payer of the primary shipment. The same values should be
set for ROD, Return Receipt, ROP and SWAP, if the sub service presents.
Example JSON:
[
{
"serviceId":601,
"parcelsCount":3
},
{
"serviceId":2605,
"parcelsCount":2
}
]
3.1.1.2.4.1 ROP ADDITIONAL SERVICE LINES (SHIPMENTROPADDITIONALSERVICELINE)
Return Of Pallet (ROP) sub service lines define for each return of pallet
service how many parcels (pallets) should be returned.
ShipmentROPAdditionalServiceLine
Name
Type
Required
Data
Constraints
serviceId
int
Yes
ROP service to be used.
Validated against destination.
parcelsCount
int
Yes
Number of parcels to return.
Example JSON:
{
"serviceId":601,
"parcelsCount":3
}
3.1.1.2.5 RETURN VOUCHER ADDITIONAL SERVICE
(SHIPMENTRETURNVOUCHERADDITIONALSERVICE)
Return Voucher sub service provides an option to the recipient to initiate a
return within predefined voucher validity period, using the voucher preferences.
ShipmentReturnVoucherSubService
Name
Type
Required
Data
Constraints
serviceId
int
Yes
Service id of the return shipment.
payer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
Yes
Defines a return voucher payer.
Allowed payers are validated against the service configuration and destination.
validityPeriod
Integer
Required if caller client has no annex for return voucher.
Return voucher validity period in days. The annex return voucher period is used
by default in case caller client has such in his contract and value is omitted
Verified to not exceed the configured internal maximum in the system
Example JSON:
{
"serviceId":3,
"payer":"RECIPIENT"
}
3.1.1.3 OPTIONS BEFORE PAYMENT DETAILS ADDITIONAL SERVICE (SHIPMENTOBPD)
Options before payment are needed to define what options recipient has on
delivery before the payment of the COD. User can open parcels or open and test
the content of the parcels. Recipient may accept parcels and pay the COD or
refuse to pay and return the parcels. The return shipment details are specified
in the options also.
ShipmentOBPD
Name
Type
Required
Data
Constraints
option
enum
[“OPEN”, “TEST”]
Yes
Defines the option to be used.
Open parcels on payment or open and test parcels before payment.
returnShipmentServiceId
Integer
Yes
Defines service id to be used on return.
returnShipmentPayer
enum
[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]
Yes
Defines who pays the return shipment.
Example JSON:
{
"option":"TEST",
"returnShipmentServiceId":2,
"returnShipmentPayer":"SENDER"
}
3.2 SHIPMENT CONTENT (SHIPMENTCONTENT)
Shipment content is used to describe what is to be delivered with the shipment.
ShipmentContent
Name
Type
Required
Data
Constraints
parcelsCount
Integer
Required when parcels list is empty.
Total shipment parcels count. Ignored, if parcels list is not empty. The parcels
count is the number of parcels in the lits in that case.
Validated against the minimum and maximum allowed for the service.
totalWeight
Double
Required when parcels list is empty.
Total weight declared for the shipment. Ignored, if parcels list is not empty.
The total weight is the sum of all parcels declaredWeight in that case.
Validated against the minimum and maximum allowed for the service.
contents
String
Yes
Shipment content’s description.
100
package
String
Yes
Shipment package.
50
documents
Boolean
No
Documents flag of the shipment.
palletized
Boolean
No
Palletized flag of the shipment.
parcels
ShipmentParcel[]
Required for pallet and postal services.
Parcels. If omitted a single default (first) parcel will be created for
non-pallet and non-postal services.
Validated against the service configuration and pickup and delivery capacity of
the depots and couriers.
pendingParcels
Boolean
No
If this flag is true, the shipment is created in pending parcels state.
Shipments in pending parcels state allows adding parcels with addParcel method.
Pending parcels state is closed with finalizePendingShipment method.
exciseGoods
Boolean
No
Flag shipment contains excise goods.
Example JSON:
{
"contents":"FURNITURE",
"package":"BOX",
"documents":false,
"palletized":false,
"parcels":[
{
"seqNo":1,
"size":{
"width":80,
"depth":120,
"height":110
},
"weight":80.0,
"externalCarrierParcelNumber":"1726912312312313"
},
{
"seqNo":2,
"size":{
"width":80,
"depth":122,
"height":100
},
"weight":83.0,
"externalCarrierParcelNumber":"1726912312312315"
},
{
"seqNo":3,
"size":{
"width":83,
"depth":125,
"height":116
},
"weight":85.0,
"externalCarrierParcelNumber":"1726912312312314"
}
],
"pendingParcels":false
}
Or:
{
"contents":"FURNITURE",
"package":"BOX",
"parcels":[
{
"seqNo":1,
"weight":80.0
},
{
"seqNo":2,
"weight":83.0
},
{
"seqNo":3,
"weight":85.0
}
]
}
Or (for non-pallet and non-postal services):
{
"parcelsCount":3,
"totalWeight":248.0,
"contents":"FURNITURE",
"package":"BOX"
}
3.2.1 SHIPMENT PARCEL (SHIPMENTPARCEL)
Shipment parcel data structure.
ShipmentParcel
Name
Type
Required
Data
Constraints
id
String
No
Parcel identifier - barcode (if it is known).
seqNo
Integer
Required in createShipment method. Ignored in addParcel (auto-generated in this
case)
Parcel sequence number in the shipment.
Should be unique for the shipment.
packageUniqueNumber
Long
No
Package number associated with parcel.
size
ShipmentParcelSize
Required for pallet and postal services.
Parcel size (width, height, depth) in cm.
Validated against the capacity of the couriers and depots. Used to calculate the
volume weight, if applicable.
weight
double
Yes
Parcel weight in kg.
Validated against the capacity of the couriers and depots and service
configuration.
ref1
String
No
Reference number or text.
20
ref2
String
No
Reference number or text.
20
pickupExternalCarrierParcelNumber
ExternalCarrierParcelNumber
No
External carrier parcel id for pickup
deliveryExternalCarrierParcelNumber
ExternalCarrierParcelNumber
No
External carrier parcel id for delivery
The declared weight of a parcel (used for price calculation) is the maximum of
the weight and the volume weight (calculated from size). Volume weight in some
cases is not calculated (for example for pallets).
Example JSON:
{
"seqNo":1,
"size":{
"width":80,
"depth":120,
"height":110
},
"weight":80.0
}
Or:
{
"seqNo":1,
"weight":80.0
}
3.2.1.1 SHIPMENT PARCEL SIZE (SHIPMENTPARCELSIZE)
Shipment parcel size structure defines parcel size in the shipment.
ShipmentParcelSize
Name
Type
Required
Data
Constraints
width
int
Yes
Parcel width
depth
int
Yes
Parcel depth
height
int
Yes
Parcel height
Example JSON:
{
"width":80,
"depth":120,
"height":100
}
3.2.1.2 EXTERNAL CARRIER PARCEL NUMBER (EXTERNALCARRIERPARCELNUMBER)
Parcel number from external carrier linked to local shipment parcel
ExternalCarrierParcelNumber
Name
Type
Required
Data
Constraints
externalCarrier
enum
[“ACS”]
Yes
External carrier reference name
parcelNumber
String
Yes
External carrier parcel number
3.3 SHIPMENT PAYMENT (SHIPMENTPAYMENT)
Shipment payment structure defines who-pays-what in the shipment.
ShipmentPayment
Name
Type
Required
Data
Constraints
courierServicePayer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
Yes
Courier service payer.
Validated against the service, destination, contracts and annexes.
declaredValuePayer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
No
Declared value (extended liability) payer. If not provided, the courier service
payer is assumed.
Validated against the service, destination, contracts and annexes.
packagePayer
enum
[ "SENDER", "RECIPIENT", "THIRD_PARTY" ]
No
Package payer. If not provided, the courier service payer is assumed.
Validated against the service, destination, contracts and annexes.
thirdPartyClientId
Long
No
Defines shipment third party - used as a payer of any of shipment payable
components.
Third party customer should be a registered customer with valid contract and
annex for delayed payment at pickup date. The third party customer should be a
customer (object) in the same contract as the logged user.
discountCardId
ShipmentDiscountCardId
No
Discount card to be used for discount calculation.
Validated against a referred contract.
senderBankAccount
BankAccount
No
Sender COD payout account information.
Valid IBAN should be present if bank account is provided.
administrativeFee
Boolean
No
Flag to apply administrative fee on price calculations
Usage of administrative fee is enabled and configured in client contract.
Ignored if not applicable for user
Example JSON:
{
"courierServicePayer":"SENDER",
"declaredValuePayer":"THIRD_PARTY",
"packagePayer":"RECIPIENT",
"thirdPartyClientId":1234567,
"discountCardId":{
"contractId":666666,
"cardId":3
}
}
Or, if the sender pays everything, then the JSON below is enough:
{
"courierServicePayer":"SENDER"
}
3.3.1 SHIPMENT DISCOUNT CARD (SHIPMENTDISCOUNTCARDID)
Discount cards provide promotional discounts.
ShipmentDiscountCardId
Name
Type
Required
Data
Constraints
contractId
long
Yes
Fixed discount card contract id.
Validated against the accessible contract.
cardId
long
Yes
Fixed discount card id.
Validated against the fixed discount card register.
Example JSON:
{
"contractId":12345678,
"cardId":3
}
3.3.2 BANK ACCOUNT (BANKACCOUNT)
Bank account information.
BankAccount
Name
Type
Required
Data
Constraints
iban
String
Yes
IBAN.
Validated according to IBAN standards.
accountHolder
String
Yes
Bank account holder.
Example JSON:
{
"iban":"BG80BNBG96611020345678",
"accountHolder":"Todor Penev"
}
3.4 SHIPMENT SENDER AND RECIPIENT
3.4.1 SHIPMENT SENDER (SHIPMENTSENDER)
Shipment sender is not mandatory. If not specified, for the sender is considered
the logged user.
ShipmentSender
Name
Type
Required
Data
Constraints
clientId
Long
No
Client id to refer a sender.
Validate for existence.
phone1
ShipmentPhoneNumber
Yes
Sender phone number (for example: +40799123456, 0040799123456, +359999123456 -
international format numbers or 0799123456, 0999123456 - local numers).
Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is
also permitted as a leading symbol. Only spaces are allowed as separators. Only
phone numbers starting with "0" (zero) or "+" sign are allowed.
phone2
ShipmentPhoneNumber
No
Sender phone number 2.
Validate for valid phone number, if presents.
phone3
ShipmentPhoneNumber
No
Sender phone number 3.
Validate for valid phone number, if presents.
clientName
String
If clientId is provided, it is forbidden. Otherwise, it is mandatory.
Sender customer name.
Validate for valid name (minimum 3 symbols, maximum 60).
contactName
String
No
Forbidden for private persons. Required for companies.
Sender contact name.
Maximum 60
email
String
No
Sender email.
Maximum 255
privatePerson
Boolean
If clientId is provided, it is forbidden. Otherwise, it is mandatory.
Sender private person flag.
address
ShipmentAddress
If clientId is provided or dropoff office is provided, it is forbidden.
Otherwise, it is mandatory.
Sender address.
Validated for valid values.
dropoffOfficeId
Integer
Required, if the sender is an internal Speedy customer. If the address is
provided, it is forbidden.
Drop off office id.
Should refer to a valid accessible office.
dropoffGeoPUDOId
String
No. Must be empty if dropoffOfficeId is provided
DPD drop off office PUDO id
Should refer to a valid accessible DPD office.
Example JSON:
{
"clientId":90909090909,
"phone1":{
"number":"08888123123"
},
"phone2":{
"number":"08888123153",
"extension":"321"
},
"clientName":"CLIENT NAME",
"objectName":"OBJECT NAME",
"contactName":"CONTACT NAME",
"email":"a@b.c",
"privatePerson":false,
"address":{
"countryId":100,
"siteId":68314,
"streetType":"bul.",
"streetName":"VITOSKA",
"streetNo":"55"
}
}
Or:
{
"clientId":90909090909,
"phone1":{
"number":"08888123123"
},
"contactName":"CONTACT NAME",
"email":"a@b.c"
}
3.4.2 SHIPMENT RECIPIENT (SHIPMENTRECIPIENT)
ShipmentRecipient
Name
Type
Required
Data
Constraints
clientId
Long
No
Client id to refer recipient.
Validate for existence.
phone1
ShipmentPhoneNumber
Required, if shipment is with the same day delivery or delivery date is a
half-working day or delivery country is abroad.
Recipient phone number (for example: +40799123456, 0040799123456, +359999123456
- international format numbers or 0799123456, 0999123456 - local numers).
Max size is 20 chars. Phone numbers must contain digits only. The "+" sign is
also permitted as a leading symbol. Only spaces are allowed as separators. Only
phone numbers starting with "0" (zero) or "+" sign are allowed.
phone2
ShipmentPhoneNumber
No
Recipient phone number 2.
Validate for valid phone number, if presents.
phone3
ShipmentPhoneNumber
No
Recipient phone number 3.
Validate for valid phone number, if presents.
clientName
String
If clientId is provided, it is forbidden. Otherwise, it is mandatory.
Recipient customer name.
Validate for valid name (minmum 3 simbols, maximum 60).
objectName
String
If clientId is provided, it is forbidden. Otherwise, it is not mandatory.
Recipient customer object.
Validate for valid name (maximum 60 symbols).
contactName
String
No.
Forbidden for private persons. Required for companies.
Recipient contact name.
Maximum 60
email
String
No
Recipient email
Maximum 255. Mandatory for international shipments
privatePerson
Boolean
If clientId is provided, it is forbidden. Otherwise, it is mandatory.
Recipient private person flag.
address
ShipmentAddress
If clientId is provided or pickup office is provided, it is forbidden.
Otherwise, it is mandatory.
Recipient address.
Validated for valid values.
pickupOfficeId
Integer
Required, if the recipient is an internal Speedy customer. If address is
provided, it is forbidden.
Pickup office id.
Should refer to a valid accessible office.
pickupGeoPUDOId
String
No. Must be empty if pickupOfficeId is provided
DPD pickup office PUDO id
Should refer to a valid accessible DPD office.
autoSelectNearestOffice
boolean
No
Not supported for every destination country
Must be supported for destination country
Example JSON:
{
"phone1":{
"number":"0888813323"
},
"clientName":"RCPT NAME",
"objectName":"RCPT OBJ NAME",
"contactName":"RCPT CONTACT NAME",
"email":"a@b.c",
"privatePerson":true,
"pickupOfficeId":33
}
Or:
{
"clientId":90909090909,
"phone1":{
"number":"0888813323"
},
"contactName":"RCPT CONTACT NAME",
"pickupOfficeId":33
}
3.4.3 SHIPMENT ADDRESS (SHIPMENTADDRESS)
This structure is used to provide addresses. Addresses are two types:
* Address type 1 (local addresses - currently supported by Romania and
Bulgaria)
* Address type 2 (foreign addresses - all non-local countries)
Address type 1 supports the following requisites:
* countryId
* siteId
* siteType
* siteName
* postCode
* complexId
* complexType
* complexName
* streetId
* streetType
* streetName
* streetNo
* blockNo
* entranceNo
* floorNo
* apartmentNo
* poiId
* addressNote
* x
* y
Address type 2 supports the following requisites:
* countryId
* stateId
* siteId
* siteName
* postCode
* addressLine1
* addressLine2
* x
* y
ShipmentAddress
Name
Type
Required
Data
Constraints
countryId
Integer
No
Country ISO code. If not provided, local country is assumed.
Used for all address types.
Validate for valid country code.
stateId
String
Required, if country supports states.
Country state.
Used for addresses of type 2 (foreign address).
Validate for valid country state.
siteId
Long
Required, if country has full site nomenclature and pair (siteType, siteName) is
not provided.
Site id.
Used for all address types.
Validate for valid site and value is required.
siteType
String
Forbidden, if siteId is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with countryId and siteName to find unique
site.
Used for addresses of type 1 (local address).
Max 20
siteName
String
Forbidden, if siteId is provided. Otherwise, is not mandatory.
Site type can be used in conjunction with countryId and siteName to find unique
site.
Used for all address types.
Max 50
postCode
String
No
Can be used in conjunction with countryId to find unique site
Used for all address types.
Validated for valid postcode in site and country.
Max 10
streetId
Long
No
Street identifier. If not provided, but street type and street name are provided
- the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
Validate for valid street.
streetType
String
No. Forbidden, if streetId is provided.
Street type.
Used for addresses of type 1 (local address).
Max 15
streetName
String
No. Forbidden, if streetId is provided.
Street name.
Used for addresses of type 1 (local address).
Max 50
streetNo
String
No
Street number.
Used for addresses of type 1 (local address).
Max 10
complexId
Long
No
Complex identifier. If not provided, but complex type and complex name are
provided - the system will try to find unique match by them in site.
Used for addresses of type 1 (local address).
Validate for valid complex.
complexType
String
No. Forbidden, if complexId is provided.
Complex type.
Used for addresses of type 1 (local address).
Max 15
complexName
String
No. Forbidden, if complexId is provided.
Complex name.
Used for addresses of type 1 (local address).
Max 50
blockNo
String
No
Block No.
Used for addresses of type 1 (local address).
Max 32
entranceNo
String
No
Entrance.
Used for addresses of type 1 (local address).
Max 10
floorNo
String
No
Floor.
Used for addresses of type 1 (local address).
Max 10
apartmentNo
String
No
Apartment.
Used for addresses of type 1 (local address).
Max 10
poiId
Long
No
Point of interest identifier.
Used for addresses of type 1 (local address).
Validate for valid point of interest.
addressNote
String
No
Address note.
Used for addresses of type 1 (local address).
200
addressLine1
String
Required for address type 2.
Address line 1.
Used for addresses of type 2 (foreign address).
Max 35
addressLine2
String
No
Address line 2.
Used for addresses of type 2 (foreign address).
Max 35
x
Double
No
GIS coordinates - X.
Used for all address types.
y
Double
No
GIS coordinates - Y.
Used for all address types.
For address type 1, special validation rule is applied:
* not empty street (ID or Type&Name) and (streetNo or blockNo) or
* not empty complex (ID or Type&Name) and (streetNo or blockNo) or
* not empty poiId or
* all components of the address within the site stored in addressNote
Example JSON address:
{
"countryId":100,
"siteId":68314,
"streetType":"bul.",
"streetName":"VITOSHA",
"streetNo":"55"
}
3.4.3.1 ADDRESS (ADDRESS)
This structure extends Shipment Address structure with additional fields for
address represntation.
This structure is returned in responses.
Address
Name
Type
Required
Data
Constraints
ShipmentAddress fields are here
fullAddressString
String
Yes
Full address in a single text field
siteAddressString
String
Yes
The address site description in a single text
localAddressString
String
Yes
The address within the site in a single text
3.4.4 SHIPMENT PHONE NUMBER (SHIPMENTPHONENUMBER)
This structure is used to provide phone numbers.
ShipmentPhoneNumber
Name
Type
Required
Data
Constraints
number
String
Yes
Phone number.
Validate for valid phone number.
extension
String
No
Extension.
Validate for valid extension, if presents.
Example JSON:
{
"number":"0888813323",
"extension":"123"
}
Or just:
{
"number":"0888813323"
}
3.5 SHIPMENT PARCELS
Shipment parcel reference is returned in response of the create shipment
request, it describes the generated parcel and references to it.
3.5.1 CREATED SHIPMENT PARCEL (CREATEDSHIPMENTPARCEL)
CreatedShipmentParcel
Name
Type
Mandatory
Data
seqNo
int
Yes
Sequence number within the shipment.
id
String
Yes
Generated parcel id.
externalCarrierId
Integer
No
External carrier id in case this parcel is mapped to an external carrier system
externalCarrierParcelNumber
String
No
External carrier parcel number in case this parcel is mapped to an external
carrier system
Example JSON:
{
"id":"80002188603",
"seqNo":1
}
3.5.2 SHIPMENT PARCEL REFERENCE (SHIPMENTPARCELREF)
ShipmentParcelRef
Name
Type
Mandatory
Data
Constraint
id
String
No
If externalCarrierParcelNumber is not provided, it is mandatory.
Parcel id
externalCarrierParcelNumber
String
No
External carrier parcel number used to create parcels.
fullBarcode
String
No
No
If id or externalCarrierParcelNumber is not provided, it is mandatory.
Example JSON:
{
"id":"80002188603"
}
Or:
{
"externalCarrierParcelNumber":"7125912312312312313"
}
Or:
{
"fullBarcode":"1000509431237540020002030017"
}
3.5.3 PARCEL HANDOVER (PARCELHANDOVER)
This structure extends ShipmentParcelRef structure with additional fields.
ParcelHandover
Name
Type
Mandatory
Data
Constraint
dateTime
DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ)
Yes
Datetime for hadover operation
ShipmentParcelRef fields are here
3.5.4 TRACK SHIPMENT PARCEL REFERENCE (TRACKSHIPMENTPARCELREF)
TrackShipmentParcelRef
Name
Type
Mandatory
Data
Constraint
ref
String
No
Reference to parcel or shipment.
The reference is searched in ref1 and ref2 fields in parcels or in ref1 and ref2
fields in shipment. A parcel is included in tracking if reference is found in
parcel references. Otherwise, only first shipment parcel (this one with the same
number as shipment id) is included in tracking in case reference is found in
shipment references.
If externalCarrierParcelNumber or parcelId is provided, it is ignored.
Since the reference is not unique, the maximum barcodes to include for tracking
is limited to 10 per reference in request.
ShipmentParcelRef fields are here
3.5.5 MIDWAY CARRIER PARCEL HANDOVER (MIDWAYCARRIERPARCELHANDOVER)
MidwayCarrierParcelHandover
Name
Type
Mandatory
Data
Constraint
id
String
Yes
Parcel id
countryId
Long
Yes
Country ISO id
dateTime
DateTime in format(yyyy-MM-dd'T'HH:mm:ssZ)
Yes
Datetime for hadover operation
siteName
String
No
Site name
3.6 SHIPMENT PRICE (SHIPMENTPRICE)
Shipment price structure is returned in response of the calculations or create
shipment requests.
ShipmentPrice
Name
Type
Mandatory
Data
amount
double
Yes
Total amount (before VAT) in customer’s currency.
vat
double
Yes
VAT amount in customer’s currency.
total
double
Yes
Total amount (amount + vat) in customer’s currency.
currency
String
Yes
Customer currency code.
details
Map<String, ShipmentPriceAmount>
Yes
Amounts that form totals in customer’s currency (including net, discounts,
surcharges). Keys in the map are the titles of the items included in the
receipt.
amountLocal
double
Yes
Total amount before VAT in local system currency.
vatLocal
double
Yes
VAT in local system currency.
totalLocal
double
Yes
Total amount in local system currency (amountLocal + vatLocal).
currencyLocal
String
Yes
Local system currency code.
detailsLocal
Map<String, ShipmentPriceAmount>
Yes
Amounts that form totals in local system currency (including net, discounts,
surcharges). Keys in the map are the titles of the items included in the
receipt.
currencyExchangeRateUnit
int
Yes
Currency exchange rate unit for customer currency (1 unit of local system
currency is equal to exchangeRateUnit / exchangeRate).
currencyExchangeRate
double
Yes
Currency exchange rate used for customer currency conversion.
returnAmounts
ReturnAmounts
No
Shipment returns amounts due
Example JSON:
{
"amount":37.81,
"vat":7.18,
"total":44.99,
"currency":"RON",
"receipt":{
"netAmount":{
"amount":37.81,
"vatPercent":19.0
},
"fixedDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"dropoffDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"pickupDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"additionalDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"fuelSurcharge":{
"amount":0.0,
"percent":0.0,
"vatPercent":19.0
},
"zoneSurcharge":{
"amount":0.0,
"vatPercent":19.0
},
"codCommission":{
"amount":0.0,
"vatPercent":19.0
},
"declaredValueSurcharge":{
"amount":0.0,
"vatPercent":19.0
}
},
"amountLocal":37.81,
"vatLocal":7.18,
"totalLocal":44.99,
"currencyLocal":"RON",
"receiptLocal":{
"netAmount":{
"amount":37.81,
"vatPercent":19.0
},
"fixedDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"dropoffDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"pickupDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"additionalDiscount":{
"amount":-0.0,
"percent":0.0,
"vatPercent":19.0
},
"fuelSurcharge":{
"amount":0.0,
"percent":0.0,
"vatPercent":19.0
},
"zoneSurcharge":{
"amount":0.0,
"vatPercent":19.0
},
"codCommission":{
"amount":0.0,
"vatPercent":19.0
},
"declaredValueSurcharge":{
"amount":0.0,
"vatPercent":19.0
}
},
"currencyExchangeRateUnit":1,
"currencyExchangeRate":1.0
}
3.6.1 SHIPMENT PRICE AMOUNT (SHIPMENTPRICEAMOUNT)
Shipment price amount is returned as a part of receipts in calculation
responses.
ShipmentPriceAmount
Name
Type
Mandatory
Data
amount
double
Yes
Shipment price amount. Discounts are negative. Surcharges and net amount are
positive.
percent
Double
No
Percent field is returned, if there is a percent associated with the amount.
Fixed price amounts do not have a percent value. 20% is returned as 0.2.
vatPercent
double
Yes
VAT percent applicable to the amount. Amounts without VAT have 0.0 value in that
field. Amounts with 20% VAT have 0.2 value in that field.
Example JSON:
{
"amount":13.45,
"percent":0.4,
"vatPercent":0.19
}
Or for fixed amount:
{
"amount":12.00,
"vatPercent":0.20
}
3.6.2 RETURN AMOUNTS (RETURNAMOUNTS)
Shipment price return amounts represents return services due amounts.
ReturnAmounts
Name
Type
Mandatory
Data
moneyTransfer
MoneyTransferPremium
No
Shipment money transfer premium.
3.6.2.1 MONEY TRANSFER PREMIUM (MONEYTRANSFERPREMIUM)
Money transfer premium amount due.
MoneyTransferPremium
Name
Type
Mandatory
Data
amount
Double
No
Amount due in client currency
amountLocal
Double
No
Amount due in local currency
payer
enum
[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]
No
The payer of money transfer premium
3.7 ERRORS (ERROR)
Errors are returned in responses.
Error
Name
Type
Mandatory
Data
context
String
No
Message context, if associated. This refers to an item that is wrong and should
be corrected.
message
String
Yes
Error message in language specified in the request.
id
String
Yes
System generated unique error id to be used as this error reference.
code
int
Yes
Error code. See Appendix 3 - Error Codes for more details.
component
String
No
The request component, if applicable, relevant to this error in JSONPath format
with dot notation.
(For example $.sender.address.siteId refers to siteId property in sender
address.)
Example JSON:
{
"context":”sender.address.siteId”,
"message":”Value is required”
}
3.8 PARCEL TO PRINT (PARCELTOPRINT)
ParcelToPrint
Name
Type
Mandatory
Data
Constraints
parcel
ShipmentParcelRef
Yes
Parcel reference.
additionalBarcode
ParcelToPrintAdditionalBarcode
No
Additional barcode to be added in the label.
Available for A6 paper size only. Otherwise, ignored.
Example JSON:
{
"parcel": {
"Id":"80002188603"
},
"additionalBarcode": {
"value":"123456789104",
"label":"123456789104",
"format":"CODE128"
}
}
Or just:
{
"parcel": {
"Id":"80002188603"
}
}
3.8.1 PARCEL TO PRINT ADDITIONAL BARCODE (PARCELTOPRINTADDITIONALBARCODE)
Additional barcode information to print in the label is provided in this
structure.
ParcelToPrintAdditionalBarcode
Name
Type
Mandatory
Data
Constraints
value
String
.Yes
Barcode value.
For barcode formats other than 'CODE128' it must contain digits only.
label
String
No
It is printed just below the barcode image.
For barcode formats other than 'CODE128' label must be equal to the value.
format
enum
[“CODE128”, “EAN13”, “EAN8”, “UPCA”, “UPCE”]
Yes
Additional barcode format.
Example JSON:
{
"value":"123456789104",
"label":"123456789104",
"format":"CODE128"
}
3.8.2 LABEL INFO (LABELINFO)
Print label information.
LabelInfo
Name
Type
Mandatory
Data
Constraints
parcelId
String
Yes
Parcel id.
hubId
Integer
No
Delivery Hub id.
officeId
Integer
No
Delivery Office id.
officeName
String
No
Delivery Office name.
deadlineDay
Integer
No
Delivery deadline day of month.
deadlineMonth
Integer
No
Delivery deadline month .
tourId
Integer
No
Tour Id.
fullBarcode
String
Yes
Barcode containing the parcel number and important routing information.
exportPriority
Integer
Yes
Export priority
Example JSON:
{
"parcelId": "50943123754",
"hubId": 2,
"officeId": 2,
"deadlineDay": 18,
"deadlineMonth": 2,
"tourId": 2203,
"fullBarcode": "1000509431237540020002030017"
}
3.9 TRACKEDPARCEL (TRACKEDPARCEL)
Track parcel information.
TrackedParcel
Name
Type
Mandatory
Data
Constraints
parcelId
String
Yes
Parcel id.
externalCarrierParcelNumbers
String[]
No
The list of all external carrier parcel numbers associated with the parcel.
operations
TrackedParcelOperation[]
Yes
The list of operations (scans).
externalCarrierParcelNumbersDetails
Map<String, ExternalCarrierParcelNumberDetails>
No
Map of external carrier parcel details. Keys in the map are external carrier
parcel numbers.
error
Error
No
Error for this parcel.
3.9.1 TRACKED PARCEL OPERATION (TRACKEDPARCELOPERATION)
TrackedParcelOperation
Name
Type
Mandatory
Data
Constraints
dateTime
Date (datetime)
Yes
Operation date time.
operationCode
int
Yes
Operation code. See Appendix1 for reference.
place
String
No
Place of operation.
description
String
Yes
Operation description.
comment
String
No
Operation comment.
exceptionCodes
String[]
No
List of exception codes for this operation. See Appendix2 for references.
returnShipmentId
String
No
If operation leads to return - the return shipment id is in this field.
redirectShipmentId
String
No
If operation leads to redirect - the redirected shipment id is in this field.
consignee
String
No
If operation leads to delivery - the recipient name is in this field.
podImageURL
String
No
If operation leads to pod capture - the pod image URL is in this field.
additionalInfo
TrackedParcelOperationAdditionalInfo
No
Additional information for operation
3.9.1.1 TRACKED PARCEL OPERATION ADDITIONAL
INFO(TRACKEDPARCELOPERATIONADDITIONALINFO)
TrackedParcelOperationAdditionalInfo
Name
Type
Mandatory
Data
Constraints
officeURL
String
No
Pickup office URL (applicable for operation 134)
geoPUDOId
String
No
Pickup office PUDO id in case pickup office is a DPD office (applicable for
operation 134)
predict
TrackedParcelOperationAdditionalInfoPredict
For operation with code 175 (Predict)
Predict details
3.9.1.1.1 TRACKED PARCEL PREDICT OPERATION ADDITIONAL
INFO(TRACKEDPARCELOPERATIONADDITIONALINFOPREDICT)
TrackedParcelOperationAdditionalInfoPredict
Name
Type
Mandatory
Data
Constraints
predictedVisitDateTimeFrom
Datetime
(fromat: yyyy-MM-dd'T'HH:mm:ssZ)
Yes
Start of expected time window for delivery
predictedVisitDateTimeTo
Datetime
(fromat: yyyy-MM-dd'T'HH:mm:ssZ)
Yes
End of expected time window for delivery
includedDelayInMinutes
Integer
No
Expected delivery time delay in minutes (if any). The expected time window for
delivery is adjusted with this delay
canceled
boolean
Yes
The value is true in case the predict is cancelled
3.9.2 EXTERNAL CARRIER PARCEL NUMBER DETAILS(EXTERNALCARRIERPARCELNUMBERDETAILS)
ExternalCarrierParcelNumberDetails
Name
Type
Mandatory
Data
Constraints
externalCarrierId
int
Yes
Id of the external carrier
externalCarrierName
String
Yes
Name of the external carrier
trackAndTraceUrl
String
No
Track and trace URL of the external carrier
3.10 PICKUP ORDER (PICKUPORDER)
Pickup order data.
PickupOrder
Name
Type
Mandatory
Data
Constraints
id
long
Yes
Order id.
shipmentIds
String[]
Yes
The list of all shipments associated with the order.
pickupPeriodFrom
Datetime
(fromat: yyyy-MM-dd'T'HH:mm:ssZ)
No
Estimated period start for courier pickup visit
pickupPeriodTo
Datetime
(fromat: yyyy-MM-dd'T'HH:mm:ssZ)
No
Estimated period end for courier pickup visit
3.11 COUNTRY
Country data
Country
Name
Type
Data
id
integer
Country ISO
name
String
Country name in requested language
nameEn
String
Country name in English
isoAlpha2
String
Country ISO alpha 2 code
isoAlpha3
String
Country ISO alpha 3 code
postCodeFormats
String[]
Allowed postcode format patterns.
If empty string presents in allowed patterns this means - postcode format is not
restricted and post code validation is not applied on addresses in this country.
For non-empty patterns, the following characters are placeholders for:
* N - digit
* A - letter
* ? - digit or letter
* B - letter
* O - digit
requireState
String
Require state flag
addressType
integer
Address type for this country (1 or 2 - see ShipmentAddress)
currencyCode
String
Currency code used for COD in this country
defaultOfficeId
Integer
Default office id
streetTypes
AddressNomenclatureType[]
Valid street types for country (applicable if addressType is equal to 1)
complexTypes
AddressNomenclatureType[]
Valid complex types for country (applicable if addressType is equal to 1)
siteNomen
integer
Specifies site nomenclature (sites) for this country. Values can be:
* 0 - No site nomenclature for this country.
* 1 - Full site nomenclature for this country.
* 2 - Partial site nomenclature for this country.
3.11.1 ADDRESS NOMENCLATURE TYPE (ADDRESSNOMENCLATURETYPE)
Used for address type 1 street types and complex types
AddressNomenclatureType
Name
Type
Data
name
String
Address nomenclature type name in requested language
nameEn
String
Address nomenclature type name in English
3.12 STATE
State data
State
Name
Type
Data
id
String
State id
name
String
State name in requested language
nameEn
String
State name in English
stateAlpha
String
State ISO alpha code
countryId
integer
State country id
3.13 SITE
Site data
Site
Name
Type
Data
id
long
Site id
countryId
integer
Site country id
mainSiteId
Long
Here we have reference to main site if this site is a "satellite" one.
A satellite site is considered equal (to their main site) in context of "same
city" service allowance
type
String
Site type in requested language
typeEn
String
Site type in English
name
String
Site name in requested language
nameEn
String
Site name in English
municipality
String
Municipality name in requested language
municipalityEn
String
Municipality name in English
region
String
Region name in requested language
regionEn
String
Region name in English
postCode
String
Default post code for this site (if any)
addressNomenclature
integer
Code for address nomenclature (streets, complexes, blocks, poi) support.
* 0 - no address nomenclature
* 1 - full address nomenclature
* 2 - partial address nomenclature
x
Double
Site center GPS X (longitude) coordinate
y
Double
Site center GPS Y (latitude) coordinate
servingDays
String
Serving days for this site.
Format: 7 serial digits (0 or 1) where each digit corresponds to a day in week
(the first digit corresponds to Monday, the second to Tuesday and so on).
Value of '0' (zero) means that the site is not served on this day while '1'
(one) means that it is served.
(Example: the text "0100100" means that the site is served on Tuesday and Friday
only)
servingOfficeId
Integer
Site's serving office
servingHubOfficeId
Integer
The hub office ID to which serving office is connected
3.14 STREET
Street data
Street
Name
Type
Data
id
long
Street id
siteId
long
Street site id
type
String
Street type in requested language
typeEn
String
Street type in English
name
String
Street name in requested language
nameEn
String
Street name in English
actualId
Long
Actual street id (if this street is old and renamed)
actualType
String
Actual street type in requested language (if this street is old and renamed)
actualTypeEn
String
Actual street type in English (if this street is old and renamed)
actualName
String
Actual street name in local language
actualNameEn
String
Actual street name in English
3.15 COMPLEX
Complex data
Complex
Name
Type
Data
id
long
Complex id
siteId
long
Complex site id
type
String
Complex type in requested language
typeEn
String
Complex type in English
name
String
Complex name in requested language
nameEn
String
Complex name in English
actualId
Long
Actual complex id (if this complex is old and renamed)
actualType
String
Actual complex type in requested language (if this complex is old and renamed)
actualTypeEn
String
Actual complex type in English (if this complex is old and renamed)
actualName
String
Actual complex name in requested language (if this complex is old and renamed)
actualNameEn
String
Actual complex name in English (if this complex is old and renamed)
3.16 BLOCK
Block data
Block
Name
Type
Data
siteId
long
Block site id
name
String
Block name in requested language
nameEn
String
Block name in English
3.17 POINT OF INTEREST (POINTOFINTEREST)
Point of interest data
PointOfInterest
Name
Type
Data
id
long
POI id
siteId
long
POI site id
name
String
POI name in requested language
nameEn
String
POI name in English
type
String
POI type in requested language
typeEn
String
POI type in English
address
String
POI address in requested language
addressEn
String
POI address in English
x
Double
POI GPS X (longitude) coordinate
y
Double
POI GPS Y (latitude) coordinate
3.18 OFFICE (OFFICE)
Office data
Office
Name
Type
Data
id
Integer
Office id
name
String
Office name in requested language
nameEn
String
Office name in English
siteId
long
Office site id
address
Address
Office address in requested language
workingTimeFrom
String ("HH:mm")
Office work time start for days with standard (FULL) working schedule
workingTimeTo
String ("HH:mm")
Office work time end for days with standard (FULL) working schedule
workingTimeHalfFrom
String ("HH:mm")
Office work time start for days with saturday (HALF) working schedule
workingTimeHalfTo
String ("HH:mm")
Office work time end for days with saturday (HALF) working schedule
workingTimeDayOffFrom
String ("HH:mm")
Office work time start for non-working days (DAY OFF)
workingTimeDayOffTo
String ("HH:mm")
Office work time end for non-working days (DAY OFF)
sameDayDepartureCutoff
String ("HH:mm")
Office same day departure cutoff for days with standard (FULL) working schedule
(departure of parcels delivered to office after the cutoff time is next working
day)
sameDayDepartureCutoffHalf
String ("HH:mm")
Office same day departure cutoff for days with saturday (HALF) working schedule
(departure of parcels delivered to office after the cutoff time is next working
day)
sameDayDepartureCutoffDayOff
String ("HH:mm")
Office same day departure cutoff for non-working days (DAY OFF) working schedule
(departure of parcels delivered to office after the cutoff time is next working
day)
maxParcelDimensions
ShipmentParcelSize
Max parcels dimensions for this office
maxParcelWeight
double
Max parcel weight
type
enum ["OFFICE", "APT"]
Office type
nearbyOfficeId
Integer
Nearby office id
workingTimeSchedule
OfficeWorkingTimeSchedule[]
Office work time schedule for next days
palletOffice
boolean
Pallet office flag
cardPaymentAllowed
boolean
Flag, indicating this office allows card payments
cashPaymentAllowed
boolean
Flag, indicating this office allows cash payments
validFrom
Date (yyyy-MM-dd)
Valid from date
validTo
Date (yyyy-MM-dd)
Valid to date
cargoTypesAllowed
enum[]
(array with values from enum:
[“PARCEL”, “PALLET”, “TYRE”])
(Same as enum in field cargoType in CourierService)
Allowed cargo types
pickUpAllowed
boolean
Flag, indicating whether parcels can be picked up from office
dropOffAllowed
boolean
Flag, indicating whether parcels can be dropped-off in office
3.18.1 OFFICE WORKING TIME SCHEDULE (OFFICEWORKINGTIMESCHEDULE)
OfficeWorkingTimeSchedule
Name
Type
Data
date
Date (format: ""yyyy-MM-dd"")
Date this schedule is applicable for
workingTimeFrom
String ("HH:mm")
Office working time start for this date
workingTimeTo
String ("HH:mm")
Office working time end for this date
sameDayDepartureCutoff
String ("HH:mm")
Office same day departure cutoff for this day (departure of parcels delivered to
office after the cutoff time is next working day)
standardSchedule
boolean
If true - it is from standard schedule, otherwise office working time is
overridden for this specific day
3.19 CALCULATION SERVICE
Calculation service defines service level agreement for the shipment - when
shipment should be picked up, service code to be used, sub-services, etc
Calculation Service
Name
Type
Required
Data
Constraints
pickupDate
Date
(Example: 2017-11-12)
No (default value is today)
The date for shipment pickup.
Could be today or a future date
autoAdjustPickupDate
Boolean
No (default value is false)
To find first available date for pickup starting from pickupDate according to
pickup schedule for services
serviceIds
integer[]
Yes
Services for which calculation is requested
Each service id (code) should be valid for the destination.
additionalServices
ShipmentAdditionalServices
No
Defines sub-services (like COD, Declared value, etc.) associated with the
shipment.
Sub-services may be allowed or forbidden for selected service and/or
destination.
deferredDays
Integer
No (default value is 0)
This parameter allows users to specify by how many (business) days they would
like to postpone the shipment delivery from the standard term.
Allowed values are 0, 1 and 2
saturdayDelivery
Boolean
No
This parameter may adjust delivery date to the first business day, if the
standard calculated delivery day is a half-working day. If not specified, system
will determine this flag based on configured delivery customer working schedule
Example JSON:
{
"pickupDate":"2018-01-31",
"serviceIds":[2113, 2002],
"autoAdjustPickupDate":true,
"additionalServices":{
"cod":{
"amount":100.00
"currencyCode":"RON"
},
"declaredValue":{
"amount":100.00
"fragile":false
},
"fixedTimeDelivery":1130,
},
"deferredDays":2,
"saturdayDelivery":true
}
3.20 CALCULATION SENDER
Calculation sender is not mandatory. If not specified logged user is the sender.
Calculation Sender
Name
Type
Required
Data
Constraints
clientId
Long
No
Client id to refer serving client
Validate for existence.
privatePerson
Boolean
If clientId is provided, it is forbidden. Otherwise, it is mandatory.
Private person flag.
addressLocation
AddressLocation
Required if office id and clientId are missing. Otherwise it is forbidden
Address location, implies pickup at client address
dropoffOfficeId
Integer
Required if address location and clientId are missing. If address location
presents it is forbidden
Drop-off office id
Validated for valid office.
dropoffGeoPUDOId
String
No. Must be empty if dropoffOfficeId is provided
DPD drop off office PUDO id
Should refer to a valid accessible DPD office.
Example JSON:
{
"addressLocation":{
"countryId": 100
"siteId":68314
}
}
or:
{
"dropoffOfficeId": 2
}
3.21 CALCULATION RECIPIENT
Calculation Recipient
Name
Type
Required
Data
Constraints
clientId
Long
No
Client id to refer serving client
Validate for existence.
privatePerson
Boolean
If clientId is provided, it is forbidden. Otherwise, it is mandatory.
Private person flag.
addressLocation
AddressLocation
Required if office id and clientId are missing. Otherwise it is forbidden
Address location, implies delivery at client address
pickupOfficeId
Integer
Required if address location and clientId are missing. If address location
presents it is forbidden
Pickup office id
Validated for valid office.
pickupGeoPUDOId
String
No. Must be empty if pickupOfficeId is provided
DPD pickup office PUDO id
Should refer to a valid accessible DPD office.
3.22 CALCULATION ADDRESS LOCATION
Calculation Address Location
Name
Type
Required
Data
Constraints
countryId
Integer
No
Country ISO code. If not provided, local country is assumed. Used for all
address types.
Validated for valid country code.
stateId
String
Required, if country supports states
Country state. Used for addresses of type 2 (foreign address).
Validated for valid country state.
siteId
Long
Required, if country has full site nomenclature and pair (siteType, siteName) is
not provided.
Site id. Used for all address types.
Validated for valid site
siteType
String
Forbidden, if siteId is provided. Otherwise, is not mandatory
Site type can be used in conjunction with countryId and siteName to find unique
site. Used for addresses of type 1 (local address).
Max 20 characters
siteName
String
Forbidden, if siteId is provided. Otherwise, is not mandatory
Site type can be used in conjunction with countryId and siteName to find unique
site. Used for all address types.
Max 50 characters
postCode
String
Required if country requires postcode for addresses
Can be used in conjunction with countryId to find unique site. Used for all
address types.
Validated for valid postcode in site and country. Max 10 characters
3.23 CALCULATION CONTENT
Calculation content is used to describe what is to be delivered with the
shipment for calculation purposes.
Calculation Content
Name
Type
Required
Data
Constraints
parcelsCount
Integer
Required when parcels list is empty
Total shipment parcels count. Ignored, if parcels list is not empty.
Validated against the minimum and maximum allowed for the service.
totalWeight
Double
Required when parcels list is empty
Total weight declared for the shipment. Ignored, if parcels list is not empty.
The total weight is the sum of all parcels declaredWeight in that case.
Validated against the minimum and maximum allowed for the service.
documents
Boolean
No
Documents flag of the shipment
palletized
Boolean
No
Palletized flag of the shipment.
parcels
ShipmentParcel[]
Required for pallet and postal services.
List of parcels
Validated against the service configuration and pickup and delivery capacity of
the depots and couriers.
3.24 CALCULATION RESULT
Calculation Result
Name
Type
Data
serviceId
integer
Service id
additionalServices
ShipmentAdditionalServices
Additional services included in calculation
price
ShipmentPrice
Returned, if customer has access to view the amounts of the shipment.
pickupDate
Date
Pickup date.
deliveryDeadline
DateTime
Deadline for delivery. Returned, if available
error
Error
Response error.
3.25 CLIENT
Client
Name
Type
Data
clientId
Long
Client id
clientName
String
Client name
objectName
String
Object name
contactName
String
Contact name
address
Address
Client address
email
String
Client email
privatePerson
Boolean
Private person flag.
3.26 SHIPMENT
Shipment
Name
Type
Data
id
String
Shipment id
sender
Sender
Shipment sender.
recipient
Recipient
Shipment recipient.
service
ShipmentService
Shipment service level agreement.
content
Content
Shipment content.
payment
Payment
Shipment payment.
shipmentNote
String
Customer’s note associated with the shipment.
ref1
String
Reference number or text.
ref2
String
Reference number or text.
price
ShipmentPrice
Shipment payment.
delivery
ShipmentDelivery
Shipment delivery.
primaryShipment
PrimaryShipment
Primary shipment.
returnShipmentId
String
Return shipment id (in case this shipment is returned to sender)
redirectShipmentId
String
Redirect shipment id (in case this shipment is redirected to new delivery
location)
pendingShipment
Boolean
If this flag is true, the shipment is created in pending shipment state.
Shipments in pending shipment state can have incomplete data that defines
logisitics (without complete addresses, only sites)
Pending shipment state is closed with updateShipment method that makes shipments
complete.
3.26.1 SENDER (SENDER)
This structure extends Client structure with additional fields.
Sender
Name
Type
Data
Client fields are here
dropoffOfficeId
Integer
Drop-off office id
dropoffGeoPUDOId
String
DPD PUDO Id
3.26.2 RECIPIENT (RECIPIENT)
This structure extends Client structure with additional fields.
Recipient
Name
Type
Data
Client fields are here
pickupOfficeId
Integer
Pickup office id
pickupGeoPUDOId
String
DPD PUDO Id
3.26.3 CONTENT (CONTENT)
Content
Name
Type
Data
parcelsCount
Integer
Total shipment parcels count.
declaredWeight
Double
Shipment declared weight
measuredWeight
Double
Shipment measrued weight
calculationWeight
Double
Shipment calculation weight
contents
String
Shipment content’s description.
package
String
Shipment package.
documents
Boolean
Documents flag of the shipment (shipment content is documents)
palletized
Boolean
Palletized flag of the shipment.
parcels
Parcel[]
Shipment parcels
pendingParcels
Boolean
If this flag is true, the shipment is created in pending parcels state.
Shipments in pending parcels state allows adding parcels with addParcel method.
Pending parcels state is closed with finalizePendingShipment method.
3.26.3.1 PARCEL (PARCEL)
Shipment parcel details
Parcel
Name
Type
Data
id
String
Parcel id
seqNo
Integer
Parcel sequence nomber within the shipment
packageUniqueNumber
Long
Package number associated with parcel.
declaredSize
ShipmentParcelSize
Parcel declared size
measuredSize
ShipmentParcelSize
Parcel measured size
calculationSize
ShipmentParcelSize
Parcel calculation size
declaredWeight
Double
Parcel declared weight
measuredWeight
Double
Parcel measured weight
calculationWeight
Double
Parcel calculation weight
externalCarrierParcelNumbers
String[]
External carrier parcel numbers associated with this parcel
baseType
String
Base type name
size
String
Size name
3.26.4 PAYMENT (PAYMENT)
Payment
Name
Type
Data
courierServicePayer
enum
[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]
Courier service payer.
declaredValuePayer
enum
[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]
Declared value payer
packagePayer
enum
[“SENDER”, “RECIPIENT”, “THIRD_PARTY”]
Package payer
thirdPartyClientId
Long
Third party payer client id in case one of the payers is THIRD_PARTY
discountCardId
ShipmentDiscountCardId
Discount card used in calculation.
codPayment
CODPayment
COD Payment details
3.26.4.1 CODPAYMENT (CODPAYMENT)
COD payment details
CODPayment
Name
Type
Data
date
Datetime (format yyyy-MM-dd'T'HH:mm:ssZ)
Pay out date
totalPayedOutAmount
double
Total paid out COD amount
3.26.5 SHIPMENT DELIVERY (SHIPMENTDELIVERY)
ShipmentDelivery
Name
Type
Data
deadline
Datetime
(fromat: yyyy-MM-dd'T'HH:mm:ssZ)
Deadline for this shipment
deliveryDateTime
Datetime
(fromat: yyyy-MM-dd'T'HH:mm:ssZ)
Datetime of actual delivery (if schipment is delivered)
consignee
String
Shipment consignee (if schipment is delivered)
deliveryNote
String
Shipment delivery note (if schipment is delivered)
3.26.6 PRIMARYSHIPMENT (PRIMARYSHIPMENT)
PrimaryShipment
Name
Type
Data
id
String
Primary shipment id
type
enum
[“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”,
“MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”]
Primary shipment type - how this secondary shipment is realted to primary one
* RETURN_SHIPMENT - if this shipment is one of return of documents (rod) /
returnReceipt / swap / return of pallets (rop) for a primary one
* STORAGE_PAYMENT - if this shipment is for warehouse charges for a primary one
* REDIRECT - if this shipment redirects primary one
* SEND_BACK - if this shipment returns primary one to sender
* MONEY_TRANSFER - if this shipment is a money transfer for a primary one
* TRANSPORT_DAMAGED - if this shipment is for damaged primary shipment
transport
* VOUCHER_RETURN - if this shipment is a voucher return for a primary one
3.26.7 SECONDARY SHIPMENT(SECONDARYSHIPMENT)
SecondaryShipment
Name
Type
Data
id
String
Secondary shipment id
type
enum
[“RETURN_SHIPMENT”, “STORAGE_PAYMENT”, “REDIRECT”, “SEND_BACK”,
“MONEY_TRANSFER”, “TRANSPORT_DAMAGED”, “RETURN_VOUCHER”]
(Same as enum in field type in PrimaryShipment)
Primary shipment type - how this secondary shipment is realted to primary one
* RETURN_SHIPMENT - if this shipment is one of return of documents (rod) /
returnReceipt / swap / return of pallets (rop) for a primary one
* STORAGE_PAYMENT - if this shipment is for warehouse charges for a primary one
* REDIRECT - if this shipment redirects primary one
* SEND_BACK - if this shipment returns primary one to sender
* MONEY_TRANSFER - if this shipment is a money transfer for a primary one
* TRANSPORT_DAMAGED - if this shipment is for damaged primary shipment
transport
* VOUCHER_RETURN - if this shipment is a voucher return for a primary one
parcels
ShipmentParcelNumber[]
Shipment parcels
pickupDate
Date (yyyy-MM-dd)
Secondary shipment pickup date
serviceId
int
Secondary shipment service id
hasScans
boolean
Flag that shows whether the secondary shipment is scanned
3.26.8 SHIPMENT PARCEL NUMBER(SHIPMENTPARCELNUMBER)
ShipmentParcelNumber
Name
Type
Data
id
String
Parcel id
seqNo
int
Parcel sequence number in the shipment.
3.27 COURIER SERVICE
CourierService
Name
Type
Data
id
int
Courier service id
name
String
Courier service name in local language
nameEn
String
Courier service name in English
additionalServices
AdditionalCourierServices
Additional services options
cargoType
enum
[“PARCEL”, “PALLET”, “TYRE”]
Cargo type
requireParcelWeight
boolean
Require weight for each parcel on create shipment
requireParcelSize
boolean
Require size for each parcel on create shipment
3.27.1 ADDITIONAL COURIER SERVICES
AdditionalCourierServices
Name
Type
Data
cod
AdditionalCourierService
COD configuration
obpd
AdditionalCourierService
Options Before Payment or Delivery configuration
declaredValue
AdditionalCourierService
Declared value configuration
fixedTimeDelivery
AdditionalCourierService
Fixed time configuration
specialDelivery
AdditionalCourierService
Special delivery configuration
deliveryToFloor
AdditionalCourierService
Delivery to floor configuration
rod
AdditionalCourierService
Return of documents configuration
returnReceipt
AdditionalCourierService
Return receipt configuration
swap
AdditionalCourierService
SWAP configuration
rop
AdditionalCourierService
Return of pallets configuration
returnVoucher
AdditionalCourierService
Return voucher configuration
3.27.1.1 ADDITIONAL COURIER SERVICE
AdditionalCourierService
Name
Type
Data
allowance
enum
[“FORBIDDEN”, “ALLOWED”, “REQUIRED”]
Allowance value
* Forbidden - this additional service is not allowed for courier service
* Allowed - this additional service is allowed for usage for courier service.
It could be either used or skipped on create shipment
* Required - this additional service is mandatory to be used with courier
service on create shipment
3.28 EXTENDED COURIER SERVICE
ExtendedCourierService
Name
Type
Data
CourierService fields are here
deadline
Date (yyyy-MM-dd'T'HH:mm:ssZ)
Deadline for delivery
3.29 BULK TRACKING DATA FILE
BulkTrackingDataFile
Name
Type
Data
id
long
File id
url
String
File url
3.30 PAYOUT
Payout
Name
Type
Data
date
Date (yyyy-MM-dd)
Payout date
docId
Long
Payout document id
docType
enum
[“CASH”, “POSTAL_MONEY_TRANSFER”]
Payout document type
paymentType
enum
[“CASH”, “BANK”]
Payout payment type
payee
String
Payee
currency
String
Payout currency
amount
double
Payout amount
details
PayoutDetails[]
List of payout details
3.30.1 PAYOUT DETAILS
PayoutDetails
Name
Type
Data
lineNo
int
Payout line number
shipmentId
String
Payout shipment id
pickupDate
Date (yyyy-MM-dd)
Date of shipment pickup
primaryShipmentPickupDate
Date (yyyy-MM-dd)
Date of primary shipment pickup in case this shipment is a secondary one
deliveryDate
Date (yyyy-MM-dd)
Shipment delivery date
sender
String
Shipment sender
recipient
String
Shipment recipient
note
String
Shipment note
ref1
String
Shipment ref1 (reference)
ref2
String
Shipment ref2 (reference)
currency
String
Payout currency
order
Long
Order id
amount
Double
Payout amount
3.31 SPECIALDELIVERYREQUIREMENTS
SpecialDeliveryRequirements
Name
Type
Data
requiredForAllShipments
boolean
Indicates whether special delivery requirements are mandatory for each shipment
requirements
Requirement[]
List of requirements
3.31.1 REQUIREMENT
Requirement
Name
Type
Data
id
int
Special delivery requirement id
text
String
Requirement text
3.32 OFFICERESULT
This structure extends Office structure with additional fields.
OfficeResult
Name
Type
Data
distance
Integer
Distance from searched location
Office fields are here
4 APPENDIXES
4.1 APPENDIX 1 - TRACK AND TRACE OPERATION CODES
Track And Trace Operation Codes
Id
Description
1
Arrival Scan
2
Departure Scan
11
Received in Office
12
Out for Delivery
-14
Delivered
21
Processed in Office
38
Returned to Office
39
Courier Pick-up
44
Unsuccessful Delivery
69
Deferred delivery
111
Return to Sender
112
Processed to the Insurance dept.
114
Processed for Destruction
115
Redirected
116
Forwarded
121
Stopped by Sender
123
Refused by recipient
124
Delivered Back to Sender
125
Destroyed
127
Theft/Burglary
128
Canceled
129
Administrative Closure
134
Prepared for Self-collecting Consignee
144
Handover for contents check/test
148
Shipment data received
164
Unsuccessful shipment pickup
169
Delivery capacity reached (tour/office)
175
Predict
176
Export to foreign provider
181
Unexpected delay
190
Postponed delivery due to inaccurate/incomplete address
195
Refuse contents check/test
217
Handover to midway carrier
4.2 APPENDIX 2 - TRACK AND TRACE OPERATION EXCEPTION CODES
Exception codes are associated to track and trace operation codes where
relevant.
Track And Trace Operation Codes
Id
Description
11
Wrong address
12
Refused by recipient - damaged
14
Refused by recipient - not ordered
15
Refused by recipient
16
Refused by recipient - contents checked, found to be damaged
17
Return (pick-up) after wrong delivery
19
Recipient not present - informed first time
20
Self-collecting recipient
22
Broken in sub-contractor's custody
25
Closed (e.g. department store)
27
Lack of space
29
Shipment incomplete
32
Lack of time
35
Recipient not present, informed, on holiday
37
Recipient not present - third time
41
Force majeure
42
Recipient not present, informed 2nd time
46
Amount not paid
49
Customer's return
61
Delay due to unknown reason
66
ID check failed
67
Signature refused
80
Appointment scheduled
81
Regional holiday
84
Delivery note / order reference missing
1002
Incomplete address
1003
Does not answer the phone
1004
In office - not claimed
1005
Redirected
1006
Refused after content’s check/test
1007
New date scheduled
1008
Without delivery attempt
1020
Consignee not reachable - routed to office
4.3 APPENDIX 3 - ERROR CODES
Error codes returned in Error structure.
Error Codes
Id
Name
Description
1
General Error
Returned when there is an error in request processing and it doesn't match any
of recongizable errors described in this table
100
Invalid client data
Returned when there is invalid client data provided in request. Relevant for
Shipment, Calculation and Client service methods
120
Invalid address
Returned when there is an error in address provided in request. Relevant for
Shipment, Calculation and Client service methods
160
Invalid drop-off office
Returned when the selected sender drop-off office in request is not valid.
Relevant for Shipment and Calculation service methods
180
Invalid pickup office
Returned when the selected recipient pickup office in request is not valid.
Relevant for Shipment and Calculation service methods
300
Invalid third party
Returned when the selected third party payer in request is invalid. Relevant for
Shipment and Calculation service methods
400
Invalid courier service
Returned when the courier service in request is invalid. Relevant for Shipment
and Calculation service methods
410
Invalid COD additional service
Returned when COD additional service data in request is invalid. Relevant for
Shipment and Calculation service methods
415
Invalid Declared Value additional service
Returned when Declared Value additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
420
Invalid OBPD additional service
Returned when Options Before Payment and Delivery additional service data in
request is invalid. Relevant for Shipment and Calculation service methods
425
Invalid Delivery To Floor additional service
Returned when Delivery To Floor additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
430
Invalid Special Deliery additional service
Returned when Special Deliery additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
435
Invalid ROD additional service
Returned when Return of Documents additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
440
Invalid Return Receipt additional service
Returned when Return Receipt additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
445
Invalid SWAP additional service
Returned when SWAP additional service data in request is invalid. Relevant for
Shipment and Calculation service methods
450
Invalid ROP additional service
Returned when Return of Pallets additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
455
Invalid Return Voucher additional service
Returned when Return Voucher additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
460
Invalid Fixed Time Delivery additional service
Returned when Fixed Time Delivery additional service data in request is invalid.
Relevant for Shipment and Calculation service methods
500
Invalid pickup date
Returned when pickup date is not valid. Relevant for Shipment and Calculation
service methods
510
Invalid deferred days
Returned when deferred days provided in request is not valid. Relevant for
Shipment and Calculation service methods
515
Invalid discount card
Returned when discount card provided in request is not valid. Relevant for
Shipment service methods
520
Invalid saturday delivery flag
Returned when saturday delivery flag provided in request is not valid. Relevant
for Shipment and Calculation service methods
600
Invalid shipment contents
Returned when shipment contents provided in request is not valid. Relevant for
Shipment service methods
605
Invalid shipment package
Returned when shipment package provided in request is not valid. Relevant for
Shipment service methods
610
Invalid documents flag
Returned when documents flag provided in request is not valid. Relevant for
Shipment and Calculation service methods
615
Invalid palletized flag
Returned when palletized flag provided in request is not valid. Relevant for
Shipment and Calculation service methods
620
Invalid weight
Returned when total weight or parcel weight in request is not valid. Relevant
for Shipment and Calculation service methods
630
Invalid parcels
Returned when there is an error in parcels data provided in request. Relevant
for Shipment and Calculation service methods
700
Invalid courier service payment
Returned when there is an error in courier service payment data provided in
request. Relevant for Shipment and Calculation service methods
710
Invalid packings payment
Returned when there is an error in packings payment data provided in request.
Relevant for Shipment and Calculation service methods
800
Invalid ref1
Returned when shipment reference 1 provided in request. Relevant for Shipment
service methods
805
Invalid ref2
Returned when shipment reference 2 provided in request. Relevant for Shipment
service methods
810
Invalid shipment note
Returned when shipment note provided in request. Relevant for Shipment service
methods
© 2018 DPD