Speedy Web Service

Contents

  1. Introduction
  2. Special terms
  3. Methods description
  4. Custom types description
  5. Validation Errors
  6. Special validation rules for creating BOL
  7. Creating partial BOL
  8. Best practices
  9. Code samples and client libraries
  10. Change history

1. Introduction

This document provides a description of Speedy's SOAP web service (called EPS) which is intended for use by its clients. The web service provides methods for creating Bills of Lading, requesting pick up by courier and many more.

The web service is published at:

https://www.speedy.bg/eps/main01.wsdl

One of the most important service methods is createBillOfLading. It is used to create a Bill of Lading (BOL). Other methods could be used to create a PDF document about BOL, request shipments pick up, track shipment's state etc. The service exposes a variety of "helper" methods that could be used to calculate the price of a shipment in advance, check the available courier services, search for addresses etc.

The web service requires user authentication via the login method. The login method (when successful) returns a unique session ID that should be used as a parameter for every subsequent method call. If no method calls are made for a period of 20 minutes, the session expires (becomes invalid) and new session needs to be created (via the login method). It is highly recommended to avoid excessive usage of the login method. The best practise involves a simple check whether the current session is still active using the isSessionActive method.

All users in Speedy 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.

For better compatibility with clients written in different languages and platforms, the following rules are applied to all input parameters marked as "nullable" in this document:

All arguments and parameters of type "datetime" in SOAP XSD are converted to Local Speedy Time Zone when date and time fragments are evaluated. Local Speedy Time Zone is "Europe/Sofia", therefore it is recommended clients to work with the same time zone to avoid related errors and miscalculations.

To get a test account please send us an e-mail to techsupport@speedy.bg and provide the following info:

Subscribe to EPS to track updates on web services.

2. Special terms

Term Description
Site City/town/village
Common Object Also known as "Point of interest" (POI). Examples: hotels, cinemas, schools, National Palace of Culture etc.
Picking A shipment. It consists of 1 or more parcels.
To Be Called Also known as "On request". It means that the shipment is to be delivered to a Speedy office (and the receiver is expected to come to this office in order to collect the shipment by himself/herself).
From Address The shipment is to be taken from sender's address
From Office The sender should deliver the shiplment to a Speedy office
To Address The shipment is to be delivered to receiver's address
To Office The receiver is expected to come to this office in order to collect the shipment by himself/herself
Nomenclature This term is used to describe the database subset of tables which contain relatively "static" data like Sites, Streets, Clients, Contracts, Annexes, Offices etc.

3. Methods description

Method name Input parameters Output parameters (result) Exceptions Description
login
  • username (string);
  • password (string);
ResultLogin
  • InvalidUsernameOrPasswordException – Invalid username or password;
  • NoUserPermissionsException – This user has no permissions to access the service;
Login.
isSessionActive
  • sessionId (string) – The session ID to be tested;
  • refreshSession (boolean) – In case the session is active, this parameter specifies if the session should be automatically refreshed;
boolean - Returns whether the session is active.
listServices
  • sessionId (string);
  • date (date) – Some courier services are available on specific days only, so this parameter is needed to filter the active services by date;
List of ResultCourierService
  • InvalidSessionException – The session is invalid;
Returns the list of courier services valid on this date.
listServicesForSites
  • sessionId (string);
  • date (date);
  • senderSiteId (signed 64-bit integer) – Sender's site ID;
  • receiverSiteId (signed 64-bit integer) – Receiver's site ID;
List of ResultCourierServiceExt
  • InvalidSessionException – The session is invalid;
Returns the list of courier services valid on this date and sites.
getWeightInterval
  • sessionId (string);
  • serviceTypeId (signed 64-bit integer) – ID of the courier service;
  • senderSiteId (signed 64-bit integer) – Sender's site ID;
  • receiverSiteId (signed 64-bit integer) – Receiver's site ID;
  • date (date);
  • documents (boolean) - Specifies if the shipment consists of documents;
ResultMinMaxReal
  • InvalidSessionException – The session is invalid;
Returns the min/max weight allowed for the given shipment parameters.
listSites
  • sessionId (string);
  • type (string) – Type of site;
  • name (string) – Name of site (or part of it);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultSite. The list is limited to 10 records.
  • InvalidSessionException – The session is invalid;
Returns a list of sites matching the search criteria.
listSitesEx
  • sessionId (string);
  • filter (ParamFilterSite) - Contains the fields to use as a filter.
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultSiteEx. The list is limited to 10 records.
  • InvalidSessionException – The session is invalid;
Returns a list of sites. The algorithm aims to find the closest matches.
getAddressNomenclature
  • sessionId (string);
  • nomenType (signed 32-bit integer) – The type of address nomenclature;
string
  • InvalidSessionException – The session is invalid;
Returns CSV-formatted data (depending on the nomenType value). Column numbers can change in the future so it's recommended to address the data using the column names in the header row. The data for some nomenTypes requires a payed license (additional licensing contract) and permissions (access rights). To obtain such license please contact our IT department or your Speedy key account manager.


Type 100 - returns a list of all sites.

Fields description:
  • SiteID - Site ID
  • SiteType - Site type
  • SiteName - Site name
  • MunicipalityName - Municipality name
  • RegionName - Region name
  • PostCode - Post code
  • AddrNomen - Specifies if Speedy have (or have not) address nomenclature (streets, quarters etc.) for this site. Values can be:
    • 0 - Speedy has no address nomenclature (streets, quarters etc.) for this site.
    • 1 - Speedy has full address nomenclature for this site.
    • 2 - Speedy has partial address nomenclature for this site.
  • ServingOfficeID - Serving office's ID
  • ServingHubOfficeID - The hub office ID to which serving office is connected
  • 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.)

Type 300 - returns a list of all streets (requires a license).

Fields description:
  • StreetID - Street ID
  • StreetType - Street type (in Bulgarian)
  • StreetType_EN - Street type (in English)
  • StreetName - Street name (in Bulgarian)
  • StreetName_EN - Street name (in English)
  • ActualID - Actual ID (used for old street names, refers to the actual street)
  • SiteID - Site ID

Type 400 - returns a list of all quarters (requires a license).

Fields description:
  • QuarterID - Quarter ID
  • QuarterType - Quarter type (in Bulgarian)
  • QuarterType_EN - Quarter type (in English)
  • QuarterName - Quarter name (in Bulgarian)
  • QuarterName_EN - Quarter name (in English)
  • ActualID -Actual ID (used for old quarter names, refers to the actual quarter)
  • SiteID - Site ID

Type 500 - returns a list of all common objects (requires a license).

Fields description:
  • CommonObjectID - Common object ID
  • CommonObjectType - Common object type (in Bulgarian)
  • CommonObjectName -Common object name (in Bulgarian)
  • Address - Address (text description of the address)
  • SiteID - Site ID

Type 700 - returns a list of all block names (requires a license).

Fields description:
  • BlockName - Block name (in Bulgarian)
  • SiteID - Site ID

Note: This method is relatively slow (because of the size of its response). You shouldn't call it more than several times a day. The methods is designed to provide data which should be locally stored/cached by client apps.

The address-related nomenclature data is updated only several times a year.
listAllSites
  • sessionId (string);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultSite
  • InvalidSessionException – The session is invalid;
Returns a list of all sites.

Note: This method is relatively slow (because of the size of its response). You shouldn't call it more than several times a day. The methods is designed to provide data which should be locally stored/cached by client apps.

The address-related nomenclature data is updated only several times a year.
getSiteById
  • sessionId (string);
  • siteId (signed 64-bit integer nullable) – Site ID;
ResultSite
  • InvalidSessionException – The session is invalid;
Returns a site by ID.
getSitesByAddrNomenType
  • sessionId (string);
  • addrNomen (AddrNomen) – Only values FULL and PARTIAL are allowed;
ResultSite
  • InvalidSessionException – The session is invalid;
Returns sites having either full or partial address nomenclature (streets, quarters etc.).
listStreetTypes
  • sessionId (string);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List<string>
  • InvalidSessionException – The session is invalid;
Returns a list of the most common types of streets.
listQuarterTypes
  • sessionId (string);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List<string>
  • InvalidSessionException – The session is invalid;
Returns a list of the most common types of quarters (districts).
listStreets
  • sessionId (string);
  • name (string) – Street name (or part of it);
  • siteId (signed 64-bit integer) – Site ID;
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultStreet. The list is limited to 10 records.
  • InvalidSessionException – The session is invalid;
Returns a list of streets matching the search criteria.
listQuarters
  • sessionId (string);
  • name (string) – Quarter name (or part of it);
  • siteId (signed 64-bit integer) – Site ID;
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultQuarter. The list is limited to 10 records.
  • InvalidSessionException – The session is invalid;
Returns a list of quarters matching the search criteria.
listCommonObjects
  • sessionId (string);
  • name (string) – Common object name (or part of it);
  • siteId (signed 64-bit integer) – Site ID;
List of ResultCommonObject. The list is limited to 10 records.
  • InvalidSessionException – The session is invalid;
Returns a list of common objects matching the search criteria.
listBlocks
  • sessionId (string);
  • name (string) – Block name (or part of it);
  • siteId (signed 64-bit integer) – Site ID;
List<string>. The list is limited to 10 records.
  • InvalidSessionException – The session is invalid;
Returns a list of blocks matching the search criteria.
listOffices
  • sessionId (string);
  • name (string) – Office name (or part of it);
  • siteId (signed 64-bit integer nullable) – Site ID;
List of ResultOffice
  • InvalidSessionException – The session is invalid;
Returns a list of Speedy offices matching the search criteria. The method is deprecated. Use "listOfficesEx" instead
listOfficesEx
  • sessionId (string);
  • name (string) – Office name (or part of it);
  • siteId (signed 64-bit integer nullable) – Site ID;
List of ResultOfficeEx
  • InvalidSessionException – The session is invalid;
Returns a list of Speedy offices matching the search criteria. The difference with "listOffice" method is in returning data structure
getClientById
  • sessionId (string);
  • clientId (signed 64-bit integer) – Client/Partner ID;
ResultClientData
  • InvalidSessionException – The session is invalid;
Returns data for client by ID. Allowed values for clientId are only the ones of members of the user's contract and the predefined partners in the WebClients application.
searchClients List of ResultClientData
  • InvalidSessionException – The session is invalid;
Returns data for clients by specified client id or other search criteria.

If client id is specified the behaviour of this method is the same as getClientById.

Otherwise, the search returns results that satisfy search criteria.

NOTE: Currently only search by clientId or userDefTag is supported. Search by clientName, objectName, phone and siteId is not implemented yet and hence the values provided in these fields are ignored

listContractClients
  • sessionId (string);
List of ResultClientData
  • InvalidSessionException – The session is invalid;
Returns all client objects ( including logged user's ) having the same contract as logged client's contract.
getAllowedDaysForTaking
  • sessionId (string);
  • serviceTypeId (signed 64-bit integer) – Courier service ID.
  • senderSiteId (signed 64-bit integer nullable) – Sender's site ID.
  • senderOfficeId (signed 64-bit integer nullable) – If the sender intends to deliver the shipment to a Speedy office, the office ID could be set as a filter;
  • minDate (date) – When the "time" component is set then this date is to be included in the result list only if the time is not after the working time of Speedy;
Note: Either senderSiteId or senderOfficeId should be set, or neither of them. Both parameters having "not null" values is not allowed.
A list of dates.
  • InvalidSessionException – The session is invalid;
Returns the dates when the shipment can be ordered for pick-up.
The "time" component represents the deadline for creating an order (or the deadline for delivering the shipment to a Speedy office when senderOfficeId is set).

(This method could be used for the "takingDate" property of ParamPicking or ParamCalculation.)
addressSearch List of ResultAddressSearch
  • InvalidSessionException – The session is invalid;
Returns a list of addresses matching the search criteria.
calculate ResultCalculation
  • InvalidSessionException – The session is invalid;
  • PickingValidationException – Validation error during an attempt for calculation. The object contains information about the error type as well as additional text description of the error.
This method could be used for preliminary check-up of shipment's price.
calculateMultipleServices
  • sessionId (string);
  • calculation (ParamCalculation) – Data needed to perform the calculation; The serviceTypeId property must be set to 0 (zero)!
  • serviceTypeIds (List<signed 64-bit integer nullable>) – A list of courier service IDs for which price needs to be calculated.
List of ResultCalculationMS
  • InvalidSessionException – The session is invalid;
  • PickingValidationException – Validation error during an attempt for calculation. The object contains information about the error type as well as additional text description of the error. Note that some of the validation errors would not lead to this exception, but the errorDescription property of the corresponding ResultCalculationMS object will be set instead!
This method could be used for preliminary check-up of shipment's price for a range of courier services.
calculatePicking ResultCalculation
  • InvalidSessionException – The session is invalid;
  • PickingValidationException – Validation error during an attempt for calculation. The object contains information about the error type as well as additional text description of the error.
This is an alternative method for shipment price calculation where the parameter is of type ParamPicking. Clients are encouraged to use the method that best fits their needs.
createBillOfLading
  • sessionId (string);
  • picking (ParamPicking) – Data for the shipment (BOL);
ResultBOL
  • InvalidSessionException – The session is invalid;
  • PickingValidationException – Validation error during an attempt for creating BOL. The object contains information about the error type as well as additional text description of the error.
The method used to create BOL.
createPDF
  • sessionId (string);
  • params (ParamPDF);
Array of bytes
  • InvalidSessionException – The session is invalid;
Used for creating PDF documents to be printed (BOLs, labels etc.)

Examples:
createBillOfLadingPDF
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
  • includeAutoPrintJS (boolean) - Specifies if embedded JavaScript code for direct printing to be generated;
Array of bytes
  • InvalidSessionException – The session is invalid;
Creates PDF document for BOL. The method is deprecated, "createPDF" should be used instead.
createCustomTravelLabelPDFType1
  • sessionId (string);
  • parcelId (signed 64-bit integer) – Parcel ID;
Array of bytes
  • InvalidSessionException – The session is invalid;
Creates PDF document of "type I". The method is deprecated, "createPDF" should be used instead.
invalidatePicking
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
-
  • InvalidSessionException – The session is invalid;
Used to cancel BOL. Only allowed when the shipment is neither ordered nor picked up by Speedy.
updateBillOfLading
  • sessionId (string);
  • picking (ParamPicking) – Data for the shipment (BOL);
ResultBOL
  • InvalidSessionException – The session is invalid;
  • PickingValidationException - Validation error during an attempt for updating BOL. The object contains information about the error type as well as additional text description of the error.
This method is used to update BOL (only allowed if BOL was created with pendingShipmentDescription = true).
addParcel
  • sessionId (string);
  • parcel (ParamParcel) – Parcel data;
The parcel's ID (signed 64-bit integer)
  • InvalidSessionException – The session is invalid;
This method is used to add parcel to an existing BOL (only allowed if BOL was created with pendingParcelsDescription = true).
finalizeBillOfLadingCreation
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
ResultBOL
  • InvalidSessionException – The session is invalid;
Makes BOL "fully created" (only applies to BOLs created with pendingParcelsDescription = true).
createOrder
  • sessionId (string);
  • order (ParamOrder) – Order details;
List of ResultOrderPickingInfo.
The list contains objects corresponding to each BOL (one object per BOL). When the validation errors list of at least one of the objects is not empty, that means the order has not been created.
  • InvalidSessionException – The session is invalid;
Creates an order for shipments pick-up (i.e. a visit by courier of Speedy).
getPickingParcels
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
List of ResultParcelInfo
  • InvalidSessionException – The session is invalid;
Returns a list with all parcels of a shipment.
trackPicking
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
List of ResultTrackPicking
  • InvalidSessionException – The session is invalid;
This method is deprecated. Use trackPickingEx instead.
trackPickingEx
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultTrackPickingEx
  • InvalidSessionException – The session is invalid;
This method can be used to track the state/history of a shipment.
The history contains a chronological list of the following operations:
  • 1-Arrival Scan
  • 2-Departure Scan
  • 11-Received in Office
  • 12-Out for Delivery
  • 21-Processed in Office
  • 38-Returned to Office
  • 39-Courier Pick-up
  • 44-Unsuccessful Delivery
  • -14-Delivered
  • 111-Return to Sender
  • 112-Processed to the Insurance dept.
  • 114-Processed for Destruction
  • 115-Redirected
  • 125-Destroyed
  • 127-Theft/Burglary
  • 128-Canceled
  • 129-Administrative Closure
trackParcel
  • sessionId (string);
  • parcelId (signed 64-bit integer);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultTrackPickingEx
  • InvalidSessionException – The session is invalid;
This method can be used to track the state/history of a shipment.
The history contains a chronological list of the following operations:
  • 1-Arrival Scan
  • 2-Departure Scan
  • 11-Received in Office
  • 12-Out for Delivery
  • 21-Processed in Office
  • 38-Returned to Office
  • 39-Courier Pick-up
  • 44-Unsuccessful Delivery
  • -14-Delivered
  • 111-Return to Sender
  • 112-Processed to the Insurance dept.
  • 114-Processed for Destruction
  • 115-Redirected
  • 125-Destroyed
  • 127-Theft/Burglary
  • 128-Canceled
  • 129-Administrative Closure
searchPickingsByRefNumber List of BOLs found (signed 64-bit integers)
  • InvalidSessionException – The session is invalid;
Search BOLs by reference codes (ref1 and/or ref2).
getMicroregionId
  • sessionId (string);
  • coordX (signed 64-bit real);
  • coordY (signed 64-bit real);
Microregion id (signed 64-bit integer)
  • InvalidSessionException – The session is invalid;
Returns the microregion id for provided GPS coordinates.
listSpecialDeliveryRequirements
  • sessionId (string);
List of ResultSpecialDeliveryRequirement
  • InvalidSessionException – The session is invalid;
Returns list with available special delivery requirements for logged user.
validateAddress
  • sessionId (string);
  • address (ParamAddress);
  • validationMode (signed 32-bit integer not required);
    • validationMode = 0 (default) - Extended validation w/o GIS info (address uniqueness is not verified);
    • validationMode = 2 - basic validation (the same as address validation in createBillOfLading);
Validation result flag (boolean)
  • InvalidSessionException – The session is invalid;
  • PickingValidationException – Validation error during address validation. The object contains information about the error type as well as additional text description of the error.
Validates address and returns result flag.
serializeAddress JSON representation of specified address object
  • InvalidSessionException – The session is invalid;
  • PickingValidationException – Validation error during address validation. The object contains information about the error type as well as additional text description of the error.
Returns JSON representation of specified address object
deserializeAddress
  • sessionId (string);
  • address (string);
ParamAddress
  • InvalidSessionException – The session is invalid;
Returns ParamAddress constructed from specified JSON address string
makeAddressString ResultAddressString
  • InvalidSessionException – The session is invalid;
  • PickingValidationException – Validation error during address validation. The object contains information about the error type as well as additional text description of the error.
Returns ResultAddressString, providing information about specified address parameter.

4. Custom types description

ParamPicking
Property name Type Description Required Limit
billOfLading signed 64-bit integer (nullable) BOL number Only for updateBillOfLading.
takingDate date The date for shipment pick-up (the "time" component is ignored). Default value is "today". no
serviceTypeId signed 64-bit integer Courier service type ID yes
officeToBeCalledId signed 64-bit integer (nullable) ID of an office "to be called". Non-null and non-zero value indicates this picking as "to office". Otherwise "to address" is considered. Only for "to be called".
fixedTimeDelivery signed 16-bit integer (nullable) Fixed time for delivery ("HHmm" format, i.e., the number "1315" means "13:15", "830" means "8:30" etc.) Depending on the courier service, this property could be required, allowed or banned
deferredDeliveryWorkDays signed 32-bit integer (nullable) In some rare cases users might prefer the delivery to be deferred by a day or two. This parameter allows users to specify by how many (working) days they would like to postpone the shipment delivery. no 2
backDocumentsRequest boolean Specifies if the shipment has a "request for return documents" yes
backReceiptRequest boolean Specifies if the shipment has a "request for return receipt" yes
willBringToOffice boolean Specifies if the sender intends to deliver the shipment to a Speedy office by him/herself instead of ordering a visit by courier. If this flag is true, the picking is considired "from office". Otherwise "from address" is considered. yes
willBringToOfficeId long Specifies the specific Speedy office, where the sender intends to deliver the shipment by him/herself. If willBringToOfficeId is provided, willBringToOffice flag is considered "true" and the picking "from office", regardless the value provided. If willBringToOfficeId is not provied (0 or null) and willBringToOffice flag is "true", willBringToOfficeId is automatically set with default value configured for caller user profile. The default willBringToOfficeId value could be managed using profile configuration page in client's Speedy web site. no
amountInsuranceBase signed 64-bit real (nullable) Shipment insurance value (if the shipment is insured) no Depends on user's permissions and Speedy's current policy
amountCodBase signed 64-bit real (nullable) Cash-on-Delivery (COD) amount no Depends on user's permissions and Speedy's current policy
payCodToThirdParty boolean Specifies if the COD value is to be paid to a third party. Allowed only if the shipment has payerType = 2 (third party). no
retMoneyTransferReqAmount signed 64-bit real (nullable) Return money-transfer request amount no Depends on user's permissions and Speedy's current policy
parcelsCount signed 32-bit integer Parcels count yes 500
size Size Size of shipment no
weightDeclared signed 64-bit real Declared weight (the greater of "volume" and "real" weight values) yes
contents string Contents yes 100
packing string Packing yes 50
packId signed 64-bit integer (nullable) Packing ID (number) no
documents boolean Specifies whether the shipment consists of documents yes
fragile boolean Specifies whether the shipment is fragile - necessary when the price of insurance is being calculated yes
palletized boolean Specifies whether the shipment is palletized yes
sender ParamClientData Data for the sender yes
receiver ParamClientData Data for the receiver yes
payerType signed 32-bit integer Payer type (0=sender, 1=receiver or 2=third party) yes
payerRefId signed 64-bit integer (nullable) Payer ID Must be set <=> payer is "third party".
payerTypeInsurance signed 32-bit integer (nullable) Insurance payer type (0=sender, 1=reciever or 2=third party) Must be set <=> shipment is insured (i.e. amountInsuranceBase > 0).
payerRefInsuranceId signed 64-bit integer (nullable) Insurance payer ID Must be set <=> shipment has insurance (i.e. amountInsuranceBase > 0) and it is payed by a "third party".
payerTypePackings signed 32-bit integer (nullable) Packings payer type (0=sender, 1=reciever or 2=third party) No.If not set, the payer of the packings' surcharge will be the same as the one indicated by payerType.
payerRefPackingsId signed 64-bit integer (nullable) Packings payer ID Must be set <=> payerTypePackings is "third party".
noteClient string Client's note no 200
discCalc FixedDiscountCardId Card/Coupon/Voucher number for fixed discount no
retToClientId signed 64-bit integer (nullable) ID of the client who is to receive the return receipt and/or the return documents. If payer is "third party" then this client has to be payer's contract member. Otherwise the client has to be sender's contract member. no
ref1 string An optional reference code no 30
ref2 string An optional reference code no 30
clientSystemId signed 64-bit integer (nullable) An optional value used to identify user's client software. Please verify the allowed values with Speedy's IT Department. no 30
parcels List<ParamParcelInfo> Data for parcels. yes, if pallet service is used. 500
skipAutomaticParcelsCreation boolean When parcelsCount > 1 and non-pallet service is used and no explicit data has been set in the parcels property during the creation, then parcels will be created automatically by default. This parameter allows users to control this behaviour. no
pendingParcelsDescription boolean Specifies if the service/system should allow parcels to be added to the shipment at a later stage. For more information click here. no
pendingShipmentDescription boolean Specifies if the service/system should allow BOL's modification at a later stage. For more information click here. no
specialDeliveryId signed 32-bit integer (nullable) A special delivery ID no
ParamCalculation
Property name Type Description Required Limit
takingDate date The date for shipment pick-up (the "time" component is ignored). Default value is "today". no
autoAdjustTakingDate boolean If set to true, the "takingDate" field is not just to be validated, but the first allowed (following) date will be used instead (in compliance with the pick-up schedule etc.). no
serviceTypeId signed 64-bit integer Courier service type ID yes
broughtToOffice boolean Specifies if the sender intends to deliver the shipment to a Speedy office by him/herself instead of ordering a visit by courier. If this flag is true the shipment is considered "from office". Otherwise "from address" is considered. yes
toBeCalled boolean Specifies if the shipment is "to be called". If this flag is true the shipment is considered "to office". Otherwise "to address" is considered. yes
fixedTimeDelivery signed 16-bit integer (nullable) Fixed time for delivery ("HHmm" format, i.e., the number "1315" means "13:15", "830" means "8:30" etc.) Depending on the courier service, this property could be required, allowed or banned
deferredDeliveryWorkDays signed 32-bit integer (nullable) In some rare cases users might prefer the delivery to be deferred by a day or two. This parameter allows users to specify by how many (working) days they would like to postpone the shipment delivery. no 2
amountInsuranceBase signed 64-bit real (nullable) Shipment insurance value (if the shipment is insured) no Depends on user's permissions and Speedy's current policy
amountCodBase signed 64-bit real (nullable) Cash-on-Delivery (COD) amount no Depends on user's permissions and Speedy's current policy
payCodToThirdParty boolean Specifies if the COD value is to be paid to a third party. Allowed only if the shipment has payerType = 2 (third party). no
parcelsCount signed 32-bit integer Parcels count yes 500
weightDeclared signed 64-bit real Declared weight (the greater of "volume" and "real" weight values) yes 100
documents boolean Specifies whether the shipment consists of documents yes
fragile boolean Specifies whether the shipment is fragile - necessary when the price of insurance is being calculated yes
palletized boolean Specifies whether the shipment is palletized yes
senderId signed 64-bit integer (nullable) Sender's ID Either senderId or senderSiteId must be set
senderSiteId signed 64-bit integer (nullable) Sender's site ID
receiverId signed 64-bit integer (nullable) Receiver's ID Either receiverId or receiverSiteId must be set
receiverSiteId signed 64-bit integer (nullable) Receiver's site ID
payerType signed 32-bit integer Payer type (0=sender, 1=receiver or 2=third party) yes
payerRefId signed 64-bit integer (nullable) Payer ID Must be set <=> payer is "third party".
payerTypeInsurance signed 32-bit integer (nullable) Insurance payer type (0=sender, 1=reciever or 2=third party) Must be set <=> shipment is insured (i.e. amountInsuranceBase > 0).
payerRefInsuranceId signed 64-bit integer (nullable) Insurance payer ID Must be set <=> shipment has insurance (i.e. amountInsuranceBase > 0) and it is payed by a "third party".
payerTypePackings signed 32-bit integer (nullable) Packings payer type (0=sender, 1=reciever or 2=third party) No. If not set, the payer of the packings' surcharge will be the same as the one indicated by payerType.
payerRefPackingsId signed 64-bit integer (nullable) Packings payer ID Must be set <=> payerTypePackings is "third party".
parcels List<ParamParcelInfo> Information about parcles yes, if pallet service is used
specialDeliveryId signed 32-bit integer (nullable) A special delivery ID no
ParamClientData
Property name Type Description Required Limit
clientId signed 64-bit integer (nullable) Client/Partner ID no
partnerName string Name of the client (company or private person) Must be set <=> clientId is null. 60
objectName string Company department/office Allowed <=> clientId is null. 60
address ParamAddress Address details Required when clientId is null
contactName string Contact name no 60
phones List<ParamPhoneNumber> Phone numbers Sender's phone number is always required. Receiver's phone number is required if the shipment is to be delivered on a half-working day or the shipment needs to be delivered the day it has been picked up. ("Required" means at least one valid phone number must be set.) 3
email string Email address no 255
ParamAddress
Property name Type Description Required Limit
siteId signed 64-bit integer Site ID yes
streetName string Street name When address is required (i.e. when clientId is null), at least one of the following rules must be met:
  • not empty street (ID or Type&Name) and (streetNo or blockNo);
  • not empty quarter (ID or Type&Name) and (streetNo or blockNo);
  • not empty common object;
  • not empty addressNote.
50
streetType string Street type 15
streetId signed 64-bit integer (nullable) Street ID (one way to get it is via the listStreets method)
quarterName string Quarter name 50
quarterType string Quarter type 15
quarterId signed 64-bit integer (nullable) Quarter ID (one way to get it is via the listQuarters method)
streetNo string Street No 10
blockNo string Block No/name (one way to get it is via the listBlocks method) 32
entranceNo string Entrance 10
floorNo string Floor 10
apartmentNo string Apartment 10
addressNote string Address note 200
commonObjectId signed 64-bit integer (nullable) Common object ID (one way to get it is via the listCommonObjects method)
coordX signed 64-bit real (nullable) GIS coordinates - X no
coordY signed 64-bit real (nullable) GIS coordinates - Y no
serializedAddress string JSON representation of this address
ParamPhoneNumber
Property name Type Description Required Limit
number string Phone number (for example: "088 8123 456", "032112233", "+359888123456", "00359888123456", "+359 2 9441234" etc.) yes 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.
internal string An extension number no 10
Size
Property name Type Description Required Limit
width signed 32-bit integer (nullable) Width (cm) no 9999
height signed 32-bit integer (nullable) Height (cm) no 9999
depth signed 32-bit integer (nullable) Depth (cm) no 9999
ParamParcelInfo
Property name Type Description Required Limit
seqNo signed 32-bit integer Parcel's serial number (2, 3, ...) yes
parcelId signed 64-bit integer If specified courrier service is of pallet type, -1 could be used to indicate automatic barcode generation to be used. Otherwise valid parcel barcode is required yes
packId signed 64-bit integer (nullable) Packing ID no
size Size Pallet size if pallet service is used. if pallet service is specified
weight signed 64-bit real Pallet weight if pallet service is used. if pallet service is specified
ParamPDF
Property name Type Description Required Limit
type signed 32-bit integer The document type (10 - BOL; 20 - labels; 25 - labels with additional barcode) yes
ids List<signed 64-bit integer> List of IDs. For type 10 only the BOL number is needed; for types 20 and 25 one or more parcel IDs are expected (parcels must be of a single BOL). yes
includeAutoPrintJS boolean Specifies if embedded JavaScript code for direct printing to be generated (works for Adobe Acrobat Reader only) yes
printerName string The printer name. If empty, the default printer is to be used.
Only applicable if includeAutoPrintJS = true.
no
additionalBarcodes List<ParamBarcodeInfo> Only allowed for type 25.
A list of additional (second) barcodes to be printed on the bottom of each label in the PDF document. Note that the additional barcodes take some extra space so the label height for type 25 is greater than the label height for type 20.
Each element in the list corresponds to the element of 'ids' with the same index (position).
no
additionalBarcodesFormat string Only allowed for type 25.
Specifies the barcode format to be used for additionalBarcodes. Accepts the following values: 'CODE128', 'EAN13', 'EAN8', 'UPC-A', 'UPC-E'
no
ParamBarcodeInfo
Property name Type Description Required Limit
barcodeValue string Barcode value. For barcode formats other than 'CODE128' it must contain digits only. yes
barcodeLabel string Barcode label. It is printed just below the barcode image. For barcode formats other than 'CODE128' barcodeLabel must be equal to barcodeValue. no
ParamFilterSite
Property name Type Description Required Limit
postCode string Post code no
name string Site name no
type string Site type no
municipality string Municipality name no
region string Region name no
ParamSearchByRefNum
Property name Type Description Required Limit
referenceNumber string The reference code to be searched (exact match, case sensitive) yes
searchInField signed 32-bit integer Specifies where to search: 0 means [Ref1 or Ref2], 1 means [Ref1], 2 means [Ref2] yes
dateFrom date Pick-up date - from no
dateTo date Pick-up date - to no
ParamParcel
Property name Type Description Required Limit
billOfLading signed 64-bit integer The BOL to which the parcel is to be added yes
parcelId signed 64-bit integer (nullable) Parcel ID (if empty, the server will generate one) no
packId signed 64-bit integer (nullable) Packing ID no
weight signed 64-bit real Real weight (kg) yes
size Size Parcel size no
ParamOrder
Property name Type Description Required Limit
billOfLadingsToIncludeType signed 32-bit integer Specifies the set of shipments/BOLs to be ordered:
  • [10] Explicit numbers (in billOfLadingsList)
  • [20] All not-ordered-yet BOLs created by the logged client
  • [30] All not-ordered-yet BOLs created by the logged client or members of his/her contract (taking into account user's permissions)
yes
billOfLadingsList List<signed 64-bit integer> List of BOL numbers. Must be set <=> billOfLadingsToIncludeType = 10.
pickupDate date The date for shipments pick-up (the "time" component is ignored). The default value is "today". no
readinessTime signed 16-bit integer (nullable) Specifies when all the shipments/parcels will be ready for pickup. The default value is "now". Only if pickupDate > today
workingEndTime signed 16-bit integer (nullable) The sender's working time end yes
contactName string Contact name yes 60
phoneNumber ParamPhoneNumber Phone number yes
ParamAddressSearch
Property name Type Description Required Limit
siteId signed 64-bit integer Site ID yes
quarterId signed 64-bit integer (nullable) Quarter ID no
streetId signed 64-bit integer (nullable) Street ID no
commonObjectId signed 64-bit integer (nullable) Common object ID no
blockNo string Block No/name no
streetNo string Street No no
entranceNo string Entrance no
FixedDiscountCardId
Property name Type Description Required Limit
agreementId signed 32-bit integer (nullable) Agreement (contract) ID
cardId signed 32-bit integer (nullable) Card ID
ParamLanguage
Enumeration
Possible values:
  • BG
  • EN
ParamClientSearch
Property name Type Description Required
clientId signed 64-bit integer Client identifier no
userDefTag string User defined tag no
clientName (future-use) string Client name no
objectName (future-use) string Object name no
phone (future-use) string Phone no
siteId (future-use) signed 64-bit integer Site ID no
ResultLogin
Property name Type Description
clientId signed 64-bit integer The logged client's ID (in Speedy's nomenclature)
sessionId string The session ID to be used as a parameter in subsequent method calls.
serverTime Date Session created timestamp
ResultCourierService
Property name Type Description
typeId signed 64-bit integer Courier service type ID
name string Courier service name
allowanceFixedTimeDelivery ComplementaryServiceAllowance Specifies if the complementary service "Fixed time for delivery" is banned, allowed or required
allowanceCashOnDelivery ComplementaryServiceAllowance Specifies if the complementary service "COD" is banned, allowed or required
allowanceInsurance ComplementaryServiceAllowance Specifies if the complementary service "Insurance" is banned, allowed or required
allowanceBackDocumentsRequest ComplementaryServiceAllowance Specifies if the complementary service "Return documents" is banned, allowed or required
allowanceBackReceiptRequest ComplementaryServiceAllowance Specifies if the complementary service "Return receipt" is banned, allowed or required
allowanceToBeCalled ComplementaryServiceAllowance Specifies if the complementary service "To be called" is banned, allowed or required
ResultCourierServiceExt
Property name Type Description
extends ResultCourierService
deliveryDeadline datetime The deadline for shipment delivery
ResultSite
Property name Type Description
id signed 64-bit integer Site ID
type string Site type
name string Site name
municipality string Municipality name
region string Region name
postCode string Post code
addrNomen AddrNomen
Specifies if Speedy have (or have not) address nomenclature (streets, quarters etc.) for this site
ResultSiteEx
Property name Type Description
site ResultSite Site data
exactMatch boolean Specifies if there is an exact match
ResultCommonObject
Property name Type Description
id signed 64-bit integer Common object ID
type string Common object type
name string Common object name
address string Common object address
ResultStreet
Property name Type Description
id signed 64-bit integer Street ID
type string Street type
name string Street name
actualName string Actual name (in case "name" is an old name)
ResultQuarter
Property name Type Description
id signed 64-bit integer Quarter ID
type string Quarter type
name string Quarter name
actualName string Actual name (in case "name" is an old name)
ResultOffice
Obsolete, use ResultOfficeEx instead
Property name Type Description
id signed 64-bit integer Office ID
name string Name
siteId signed 64-bit integer (nullable) Serving site ID
address ValueAddress Office address
workingTimeFrom signed 16-bit integer (nullable)
("HHmm" format, i.e., the number "1315" means "13:15", "830" means "8:30" etc.)
Working time for FULL working days - FROM
workingTimeTo Working time for FULL working days - TO
workingTimeHalfFrom Working time for HALF working days - FROM
workingTimeHalfTo Working time for HALF working days - TO
ResultOfficeEx
Property name Type Description
id signed 64-bit integer Office ID
name string Name
siteId signed 64-bit integer (nullable) Serving site ID
address ResultAddressEx Office address
workingTimeFrom signed 16-bit integer (nullable)
("HHmm" format, i.e., the number "1315" means "13:15", "830" means "8:30" etc.)
Working time for FULL working days - FROM
workingTimeTo Working time for FULL working days - TO
workingTimeHalfFrom Working time for HALF working days - FROM
workingTimeHalfTo Working time for HALF working days - TO
ResultBOL
Property name Type Description
generatedParcels List<ResultParcelInfo> List of parcels data
amounts ResultAmounts Amounts
deadlineDelivery date Deadline for delivery
ResultParcelInfo
Property name Type Description
seqNo signed 32-bit integer Parcel's serial number (1, 2, 3, ...)
parcelId signed 64-bit integer Parcel ID. First parcel's ID is always the same as the BOL number.
ResultCalculation
Property name Type Description
amounts ResultAmounts Shipment's price
takingDate date The pick-up date
deadlineDelivery date Deadline for delivery
partialDiscount boolean Specifies if the discounts are potentially partial (the final discounts might be bigger depending on the other participants' contracts).
ResultCalculationMS
Property name Type Description
serviceTypeId signed 64-bit integer Courier service type ID
errorDescription string Validation error during calculation attempt
resultInfo ResultCalculation The result of calculation (in case no error has occurred)
ResultAmounts
Property name Type Description
insuranceBase signed 64-bit real The real value of the shipment
insurancePremium signed 64-bit real The insurance premium (i.e. the price of the "Insurance" complementary service)
net signed 64-bit real The net price (of the courier service only; w/o discounts, complementary services, VAT etc.)
discountFixed signed 64-bit real (NEGATIVE value) Fixed discount value
discountToOffice signed 64-bit real (NEGATIVE value) Discount for shipments delivered to a Speedy office by the sender
discountToBeCalled signed 64-bit real (NEGATIVE value) Discount for the "To be called" complementary service
discountAdditional signed 64-bit real (NEGATIVE value) Additional discount
packings signed 64-bit real Packings value
tro signed 64-bit real The amount of the "Additional charges for loading/unloading operations" complementary service
fixedTimeDelivery signed 64-bit real The amount of the "Fixed time for delivery" complementary service
fuelSurcharge signed 64-bit real Fuel surcharge
islandSurcharge signed 64-bit real Island surcharge (international shipments)
codBase signed 64-bit real The "Cash on delivery" amount to be paid to the sender
codPremium signed 64-bit real The price of the "Cash on delivery" complementary service
vat signed 64-bit real VAT (Value added tax)
total signed 64-bit real The total amount
discPcntFixed signed 64-bit real The PERCENTAGE of fixed discount
discPcntToOffice signed 64-bit real The PERCENTAGE of the "brought to office" complementary service
discPcntToBeCalled signed 64-bit real The PERCENTAGE of the "To be called" complementary service
discPcntAdditional signed 64-bit real The PERCENTAGE of additional discount
pcntFuelSurcharge signed 64-bit real The PERCENTAGE of fuel surcharge
ResultTrackPicking
Obsolete, use ResultTrackPickingEx instead
Property name Type Description
moment date Date and time
operationCode signed 32-bit integer Operation code
operationDescription string Text description of the operation
operationComment string Additional note/comment
siteType string Site type
siteName string Site name
consignee string The name of the person who received the shipment
ResultTrackPickingEx
Property name Type Description
moment date Date and time
operationCode signed 32-bit integer Operation code
operationDescription string Text description of the operation
operationComment string Additional note/comment
siteType string Site type
siteName string Site name
consignee string The name of the person who received the shipment
returnBillOfLading signed 64-bit integer Returning bill of lading
redirectBillOfLading signed 64-bit integer Redirecting bill of lading
ResultClientData
Property name Type Description
clientId signed 64-bit integer Client ID
partnerName string Name of the client (company or private person)
objectName string Company department/office
address ResultAddress Address
contactName string Contact name
phones List<ResultPhoneNumber> Phone numbers
ResultAddress
Property name Type Description
siteId signed 64-bit integer Site ID
siteName string Site name
siteType string Site type
municipalityName string Municipality name
regionName string Region name
postCode string Post code
streetName string Street name
streetType string Street type
streetId signed 64-bit integer (nullable) Street ID
quarterName string Quarter name
quarterType string Quarter type
quarterId signed 64-bit integer (nullable) Quarter ID
streetNo string Street No
blockNo string Block No/name
entranceNo string Entrance
floorNo string Floor
apartmentNo string Apartment
addressNote string Address note
commonObjectId signed 64-bit integer (nullable) Common object ID
commonObjectName string Common object name
ResultAddressEx
Property name Type Description
resultSite ResultSite Site
postCode string Post code
streetName string Street name
streetType string Street type
streetId signed 64-bit integer (nullable) Street ID
quarterName string Quarter name
quarterType string Quarter type
quarterId signed 64-bit integer (nullable) Quarter ID
streetNo string Street No
blockNo string Block No/name
entranceNo string Entrance
floorNo string Floor
apartmentNo string Apartment
addressNote string Address note
coordX signed 64-bit real GPS X coordinate
coordY signed 64-bit real GPS Y coordinate
coordTypeId signed 32-bit integer GPS coordinates type id
commonObjectId signed 64-bit integer (nullable) Common object ID
commonObjectName string Common object name
fullAddressString string Concatenated full address string
ResultPhoneNumber
Property name Type Description
number string Phone number (example: "0888123456", "+35932261020" etc.)
internal string An extension number
ResultMinMaxReal
Property name Type Description
minValue signed 64-bit real Min value
maxValue signed 64-bit real Max value
ResultOrderPickingInfo
Property name Type Description
billOfLading signed 64-bit integer BOL number
errorDescriptions List<string> A list of validation errors (empty list means there is no problem with this BOL)
ResultAddressSearch
Property name Type Description
text string Text description of the address found
coordX signed 64-bit real GIS coordinates - X
coordY signed 64-bit real GIS coordinates - Y
microregionId signed 64-bit integer (nullable) Microregion ID
distanceToSiteCenter signed 64-bit real (nullable) Distance to site's center in kilometers (straight line)
actual boolean Specifies if the address is actual now
coordType signed 32-bit integer GIS coordinates type
additionalAddressProcessing signed 32-bit integer Internal/debug info
ComplementaryServiceAllowance (enum)
Enum value Description
BANNED The complementary service is not allowed.
ALLOWED The complementary service is allowed (but not required).
REQUIRED The complementary service is required.
AddrNomen (enum)
Enum value Description
NO Speedy has no address nomenclature (streets, quarters etc.) for this site.
FULL Speedy has full address nomenclature (streets, quarters etc.) for this site.
PARTIAL Speedy has partial address nomenclature (streets, quarters etc.) for this site.
ResultSpecialDeliveryRequirement
Property name Type Description
specialDeliveryId signed 32-bit integer A special delivery ID.
specialDeliveryText string A special delivery description.
specialDeliveryPrice signed 64-bit real (nullable) A special delivery price.
ResultAddressString
Property name Type Description
siteAddress string Site address information
localAddress string Local address information
fullAddress string Combination of siteAddress and localAddress

5. Validation errors description

PickingValidationErrorType
Enum value Description
COMMON_ERROR A common validation error (additional information could be found in "errorDescription")
AMOUNT_INSURANCE_OUT_OF_RANGE The insurance value is outside the allowed limits
AMOUNT_CASH_ON_DELIVERY_OUT_OF_RANGE The cash-on-delivery value is outside the allowed limits
AMOUNT_MONEY_TRANSFER_REQ_OUT_OF_RANGE The money-transfer request amount is outside the allowed limits
SENDER_HAS_NO_ANNEX_FOR_CASH_ON_DELIVERY DEPRECATED! The sender has no contract/annex for COD
INSURANCE_CANNOT_BE_LESS_THAN_CASH_ON_DELIVERY DEPRECATED! The insurance value may not be less than COD
WEIGHT_NOT_IN_RANGE The weight is outside the allowed limits
DOCUMENTS_NOT_ALLOWED_FOR_THIS_SERVICE_AND_SITES Shipment of documents is not allowed for the courier service and sites
DOCUMENT_PICKINGS_CAN_CONSIST_OF_ONLY_ONE_PARCEL Document shipments may contain one parcel only
DOCUMENT_PICKINGS_ARE_NOT_ALLOWED_TO_HAVE_INSURANCE Document shipments may not be insured
DOCUMENT_PICKINGS_CANNOT_BE_PALLETIZED Document shipments may not be palletized
FIXED_TIME_DELIVERY_NOT_ALLOWED_FOR_RECEIVER_SITE The "Fixed time for delivery" additional service is not allowed for these receiver's site
FIXED_TIME_DELIVERY_NOT_ALLOWED_FOR_SERVICE The "Fixed time for delivery" additional service is not allowed for this courier service
INVALID_FIXED_TIME_FOR_DELIVERY Invalide value for the "Fixed time for delivery"
NO_MORE_THAN_3_PHONE_NUMBERS_EXPECTED More than three phone numbers per client are not allowed
INVALID_EMAIL Invalid e-mail
INVALID_PHONE_NUMBER Invalid phone number
LOGGED_CLIENT_OBJECT_MUST_BE_PAYER_OR_SENDER The company object of the logged user must be either a payer or a sender
INVALID_PARCELS_INFO Invalid "parcelsInfo"
INVALID_PALLET_SIZE Invalid size for specified parcel when pallet courrier service is used
INVALID_PALLET_WEIGHT Invalid weight for specified parcel when pallet courrier service is used
INVALID_PARCEL_ID When invalid parcel id is specified
INVALID_TAKING_DATE Invalid "takingDate"
INVALID_RET_TO_CLIENT_ID Invalid /not allowed/ client (client that is expected to receive the return documents and/or return receipt)
REQUIRED_BRINGING_TO_OFFICE The service requires that the sender has to deliver the shipment to a Speedy office (i.e., the flag "willBringToOffice" must be set to true)
DELIVERY_FROM_ADDRESS_TO_ADDRESS_NOT_ALLOWED The courier service does not allow address to address shipment. See Service modes details.
DELIVERY_FROM_ADDRESS_TO_OFFICE_NOT_ALLOWED The courier service does not allow address to office shipment. See Service modes details.
DELIVERY_FROM_OFFICE_TO_ADDRESS_NOT_ALLOWED The courier service does not allow office to address shipment. See Service modes details.
DELIVERY_FROM_OFFICE_TO_OFFICE_NOT_ALLOWED The courier service does not allow office to office shipment. See Service modes details.
MISSING_REQUIRED_VALUE_FIXED_TIME_FOR_DELIVERY Missing required value: Fixed time for delivery
MISSING_REQUIRED_VALUE_CONTENTS Missing required value: Content
MISSING_REQUIRED_VALUE_PACKING Missing required value: Packing
MISSING_REQUIRED_VALUE_PARTNER_NAME Missing required value: Partner name
MISSING_REQUIRED_VALUE_ADDRESS Missing required value: Address
MISSING_REQUIRED_VALUE_PHONE_SENDER Missing required value: Phone number of sender
MISSING_REQUIRED_VALUE_PHONE_RECEIVER Missing required value: Phone number of reciever
MISSING_REQUIRED_VALUE_BOL Missing required value: Bill-of-lading number
MISSING_REQUIRED_VALUE_WEIGHT_DECLARED Missing required value: Declared weight
VALUE_OUT_OF_RANGE_PARCEL_COUNT Value out of range: Number of parcels
VALUE_OUT_OF_RANGE_SIZE Value out of range: Size of shipment
VALUE_OUT_OF_RANGE_PACK_ID Value out of range: Packing ID
VALUE_OUT_OF_RANGE_CONTENTS Value out of range: Content
VALUE_OUT_OF_RANGE_PACKING Value out of range: Packing
VALUE_OUT_OF_RANGE_NOTE_CLIENT Value out of range: Client note
VALUE_OUT_OF_RANGE_CLIENT_FIELD Value out of range: Client field ("errorDescription" contains the concrete field)
VALUE_OUT_OF_RANGE_ADDRESS_FIELD Value out of range: Address field ("errorDescription" contains the concrete field)
VALUE_OUT_OF_RANGE_REF1 Value out of range: Ref 1
VALUE_OUT_OF_RANGE_REF2 Value out of range: Ref 2
VALUE_OUT_OF_RANGE_DEFERRED_DELIVERY_WORK_DAYS Value out of range: deferredDeliveryWorkDays
NON_WORKING_DAY_FOR_SELECTED_OFFICE_TBC Non working day for selected office to be called.
NON_WORKING_DAY_FOR_SELECTED_OFFICE_BTO Non working day for selected will bring to office.
NON_ACTIVE_OFFICE_TBC Non active office to be called.
NON_ACTIVE_OFFICE_BTO Non active will bring to office.

6. Special validation rules for creating BOL

There are two basic ways to set client's (i.e. sender's or receiver's) data for a shipment:

  1. The client is part of Speedy's nomenclature: in this case the client's ID needs to be set as well as: The remaining fields must not be set (they are part of the nomenclature's client data).
    The client could have a contract with Speedy for discounts, insurance etc.
  2. The client is not part of Speedy's nomenclature: in this case the client ID field is left empty (null) and the rest of the fields should be used to set the client's data. Of course this client would be "unknown" for Speedy's nomenclature so no special preferences should be expected.

If a shipment is "to be called" then the receiver's address should be left empty since the address is actually Speedy's office address (and Speedy's software already "knows" the addresses of its offices).

Document shipments are allowed to consist of only 1 parcel. They cannot be palletized and cannot be insured.

Sender's phone number is always required. Receiver's phone number is required if the shipment is to be delivered on a half-working day or the shipment needs to be delivered the day it has been picked up. ("Required" means at least one valid phone number must be set.)

Phone numbers must contain digits only. The "+" sign is also permitted as a leading symbol. Only spaces are allowed as separators. (Examples of valid phone numbers: "088 8123 456", "032112233", "+359888123456", "00359888123456", "+359 2 9441234" etc.)

If we assume that Х means "the client to which the logged user is assigned, or any other client member of his/her contract (in case the user has the relevant rights)", then the following rule applies:

(This rule applies to both the courier service and the insurance.)

Courier service modes

There are four types of modes which a courier service could or could not support:

Address to Adress Picking should be taken from sender's address and then delivered to receiver's address
Address to Office Picking be taken from sender's address and then received from courier office
Office to Adress Picking should be delivered to courier office and then sent to receiver's addresss
Office to Office Picking should be delivered to courier office and then received from courier office

Rules for creating or updating pickings:

Rules for calculation:

If the specified combination sender-receiver is not supported by the specified courier service, a validation error is returned.

7. Creating partial BOL

As of September 1, 2011, Bills of Lading can be "partially" created. To do this, at least one of the following boolean parameters needs to be set to true:

Their default value is false. In order to set true the user must have the necessary rights (for more information, please contact Speedy IT Department).

pendingParcelsDescription

When BOL is created with this parameter set to true then users are allowed to add more parcels to the BOL (via the addParcel method) until the BOL creation is finalized (using the finalizeBillOfLadingCreation method).

If BOL is partially open, the result of createBillOfLading will have zeroes in all amount fields. This is because at that stage the price is not final yet. The real (final) price will be returned when finalizeBillOfLadingCreation is called (except for the special case when the BOL has also been created with pendingShipmentDescription = true and it is still not updated via the updateBillOfLading method, described below).

When PDF for partial BOL is being created, some fields are left blank since the corresponding values might be still unknown or not final (parcels count, weight, price).

Partial Bills of Lading cannot be ordered until their creating is finalized.

pendingShipmentDescription

In some special cases the client might be unable to provide a complete description of their shipments at the time of BOL creation. By setting this flag to true users can create a BOL which is only partially described. Only the most important data (regarding logistics) is required: sender's data, receiver's site, courier service etc. This information makes it possible for Speedy to deliver the shipment to its destination-office. After the user provides the rest of the data about the shipment (via the updateBillOfLading method), the shipment will become ready for delivery.

The fields which are not considered as 'required' at the creation stage still follow the standard validation rules. By 'not required' we mean that their value can be modified later. For example if the user wants to fill in the field 'contents' at a later stage, he/she can set the initial value to 'STILL UNKNOWN', 'WILL BE SET LATER' or something like that.

Only the following fields are required when creating a BOL:

After the creation of the BOL these fields are considered immutable.

The value of officeToBeCalledId cannot be changed during the update, except for the case when the old value was null/0 and the new value is of an office which is located in the same receiver site.

The payerType must be 0 (sender) or 2 (third party).

The result of createBillOfLading has zeroes in all amount fields.

Updating Bills of Lading with [pendingShipmentDescription=true]

The method updateBillOfLading is used for updating Bills of Lading which were created with the property pendingShipmentDescription set to true. This method can be called only once.

There is a special validation - all properties which were required during the creation phase are expected to have the same values in the parameter of the updateBillOfLading method, with the exception of takingDate, parcelsCount and weightDeclared which must be set to null/0. The documents values is ignored.

The list of parcels must be empty (modifying parcels data is not allowed).

When updateBillOfLading is called, the pendingParcelsDescription and pendingShipmentDescription properties in the parameter will be ignored.

The result of updateBillOfLading will have the real (final) price (except for the special case when the BOL has also been created with pendingParcelsDescription = true and it is still not finalized via the finalizeBillOfLadingCreation method).

8. Best practices

Avoid excessive usage of the "login" method

Sometimes developers are tempted to make a login call just before every single service method call in order to ensure that they are having an active session as a parameter. This is a simple but inefficient approach to deal with sessions. Besides, for security reasons, it is generally not a good practice to pass your credentials all the time (although SSL/TLS is used). There is another, much more "lightweight" method which can be used for testing whether the last session is active or not. It is called isSessionActive. Here is some code example in Java on how to use it:

	
	// For the sake of simplicity the code below does not deal with concurrency issues!
	// It is aimed at showing a simple yet efficient way to avoid excessive
	// usage of "login" with just a few extra lines of code.
	
	public void someMethod() {
	    ...
	    String sessionId = getActiveSessionId();    // this is called before each service method call
	    List<ResultStreet> result = speedyService.listStreets(sessionId, name, siteId);   // some service method
	    ...
	}

	private static String lastSessionId;

	private static String getActiveSessionId() {
	    if (lastSessionId != null) {
	        boolean active = speedyService.isSessionActive(lastSessionId, true);
	        if (active) {
	            return lastSessionId;  // no need to call "login" 
	        }
	    }
	    ResultLogin result = speedyService.login(username, pwd);
	    lastSessionId = result.getSessionId();
	    return lastSessionId;
	}

When heavy usage of the service is expected, it is not a good idea to check the current session ID before every single method call (even with isSessionActive). You could store in some variable the last time the session ID proved to be active and omit any subsequent checks if [NOW - LAST_TIME < SESSION_TIMEOUT] (actually the code would be safer if a few minutes are extracted from SESSION_TIMEOUT since it is hard to predict how long would it take for the next call method to complete etc.).

Another approach is not to try to predict/check if the current session is active in advance but to call the wanted method directly and catch the InvalidSessionException.

9. Code samples and client libraries

PHP EPS Client library

Java EPS Client library

Demo address form (download zip archive)

10. Change history

April 16, 2014
March 17, 2014
February 14, 2014
February 12, 2014
February 10, 2014
January 08, 2014
January 07, 2014
December 05, 2013
November 28, 2013
October 25, 2013
August 27, 2013
August 2, 2013
June 25, 2013
June 20, 2013
March 22, 2013
March 5, 2013
February 22, 2013
January 25, 2013
January 10, 2013
October 24, 2012
September 1, 2012
August 22, 2012
July 14, 2012
July 4, 2012
May 20, 2012
May 16, 2012
Feb 18, 2012
Feb 4, 2012
Nov 18, 2011
Oct 18, 2011
Sep 3, 2011
June 25, 2011
Apr 14, 2011
Apr 8, 2011
Feb 25, 2011
Dec 29, 2010
Oct 7, 2010
Sep 25, 2010
Aug 5, 2010
Aug 4, 2010