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 eps.registration@speedy.bg and provide the following info:

To get technical support for the integration please send us an e-mail to eps.support@speedy.bg and provide the following info:

and detailed explanation of the situation you need support for.

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;
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
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;
  • senderCountryId (signed 64-bit integer) – Sender's country ID;
  • senderPostCode (string) – Sender's post code;
  • receiverCountryId (signed 64-bit integer) – Receiver's country ID;
  • receiverPostCode (string) – Receiver's post code;
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
  • senderId (signed 64-bit integer nullable) – Sender ID;
  • receiverId (signed 64-bit integer nullable) – Receiver ID;
  • senderOfficeId (signed 64-bit integer nullable) – Sender office ID;
  • receiverOfficeId (signed 64-bit integer nullable) – Receiver office ID;
Note: At least one of the three parameters - senderId, senderSiteId (or as an alternative senderCountryId and senderPostCode for countries without site nomenclature), senderOfficeId, must be specified, but pairing them is also possible. Not allowed pairs are:
  - senderId & senderSiteId;
  - senderSiteId & senderOfficeId;

At least one of the three parameters - receiverId, receiverSiteId (or as an alternative receiverCountryId and receiverPostCode for countries without site nomenclature), receiverOfficeId, must be specified, but pairing them is also possible. Not allowed pairs are:
  - receiverId & receiverSiteId;
  - receiverSiteId & receiverOfficeId;
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;
  • senderCountryId (signed 64-bit integer) – Sender's country ID;
  • senderPostCode (string) – Sender's post code;
  • receiverCountryId (signed 64-bit integer) – Receiver's country ID;
  • receiverPostCode (string) – Receiver's post code;
  • senderId (signed 64-bit integer nullable) – Sender's ID;
  • receiverId (signed 64-bit integer nullable) – Receiver's ID;
  • senderOfficeId (signed 64-bit integer nullable) – Sender office ID;
  • receiverOfficeId (signed 64-bit integer nullable) – Receiver office ID;
Note: At least one of the three parameters - senderId, senderSiteId, senderOfficeId, must be specified, but pairing them is also possible. Not allowed pairs are:
  - senderId & senderSiteId;
  - senderSiteId & senderOfficeId;

At least one of the three parameters - receiverId, receiverSiteId, receiverOfficeId, must be specified, but pairing them is also possible. Not allowed pairs are:
  - receiverId & receiverSiteId;
  - receiverSiteId & receiverOfficeId;
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. The method is deprecated. Use "listSitesEx" instead
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;
  • countryId (signed 64-bit integer) – nomenclature country ID; Defaults to Bulgaria.
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 1 - returns a list of all countries.

Fields description:
  • CountryId - ISO country id
  • CountryName - Country name in Bulgarian
  • CountryName _EN - Country name in English
  • CountryIsoAlpha2 - ISO alpha 2 code
  • CountryIsoAlpha3 - ISO alpha 3 code
  • RequirePostCode - Flag whether post code is required for the country
  • PostCodeFormat - Post code format
  • RequireState - Flag whether country requires state
  • SiteNomen - Specifies if Speedy have (or have not) site nomenclature (sites) for this country. Values can be:
    • 0 - Speedy has no site nomenclature for this country.
    • 1 - Speedy has full site nomenclature for this country.
    • 2 - Speedy has partial site nomenclature for this country.
  • ActiveCurrencyCode - Current active currency code
  • DefaultOfficeId - Default office id

Type 50 - returns a list of all states.

Fields description:
  • StateId - State id
  • StateCountryId - State country id
  • StateName - State name in Bulgarian
  • StateName_EN - State name in English
  • StateAlpha - State alpha code

Type 100 - returns a list of all sites.

Fields description:
  • SiteID - Site ID
  • SiteType - Site type in Bulgarian
  • SiteType_EN - Site type in English
  • SiteName - Site name in English
  • SiteName_EN - Site name in English
  • MunicipalityName - Municipality name in Bulgarian
  • MunicipalityName_EN - Municipality name in English
  • RegionName - Region name in Bulgarian
  • RegionName_EN - Region name in English
  • CountryId - ISO country id
  • 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.)
  • CoordX - GPS X coordinate
  • CoordY - GPS Y coordinate
  • CoordType - GPS coordinates type id
  • MainSiteId - Main Site ID

Type 300 - returns a list of all streets (requires a license). Without a license service returns only 10 rows.

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). Without a license service returns only 10 rows.

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). Without a license service returns only 10 rows.

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

Type 700 - returns a list of all block names (requires a license). Without a license service returns only 10 rows.

Fields description:
  • BlockName - Block name (in Bulgarian)
  • BlockName_EN - Block name (in English)
  • 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.

Type 800 - returns a list of all site postcodes for specified country.

Fields description:
  • PostCode - Site PostCode
  • 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.
getPickingDeliveryInfo
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
ResultTrackPickingEx
  • InvalidSessionException – The session is invalid;
This method can be used to get delivery information of a shipment. If picking is not delivered "null" is returned
listAllSites
  • sessionId (string);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
  • countryId (signed 64-bit integer); Country id
List of ResultSite
  • InvalidSessionException – The session is invalid;
Returns a list of all sites for country. In case no country is specified, the method defaults to sites in Bulgaria

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;
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
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;
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
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;
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
  • countryId (signed 64-bit integer nullable) – Country 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
getAdditionalUserParams
  • sessionId (string);
  • date (date) – effective date. If null is provided then current date is applied;
List<signed 32-bit integer>. The list of additional user parameters.
  • InvalidSessionException – The session is invalid;
Returns the list of additional user parameters
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;
  • senderCountryId (signed 64-bit integer nullable) – Sender's country ID.
  • senderPostCode (string nullable) – Sender's post code.
  • senderId (signed 64-bit integer nullable) – Sender's ID.
Note: At least one of the three parameters - senderId, senderSiteId, senderOfficeId, must be specified, but pairing them is also possible. Not allowed pairs are:
  - senderId & senderSiteId;
  - senderSiteId & senderOfficeId;
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>) – 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:
createPDFEx
  • sessionId (string);
  • params (ParamPDF);
CreatePDFExResponse
  • InvalidSessionException – The session is invalid;
Used for creating PDF documents to be printed (BOLs, labels etc.).
Extension method for createPDF returning more detailed information.

Examples:
getRoutingLabelInfo
  • sessionId (string);
  • parcelId (signed 64-bit integer);
ResultRoutingLabelInfo
  • InvalidSessionException – The session is invalid;
Returns routing information for specified parcel number.
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);
  • cancelComment (string);
-
  • 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 (string);
List of ResultTrackPicking
  • InvalidSessionException – The session is invalid;
This method is deprecated. Use trackPickingEx instead.
trackPickingEx
  • sessionId (string);
  • billOfLading (string);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
  • returnOnlyLastOperation (boolean); false is the default value
List of ResultTrackPickingEx
  • InvalidSessionException – The session is invalid;
This method can be used to track the state/history of a shipment.
trackParcel
  • sessionId (string);
  • parcelId (string);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
  • returnOnlyLastOperation (boolean); false is the default value
List of ResultTrackPickingEx
  • InvalidSessionException – The session is invalid;
This method can be used to track the state/history of a shipment.
trackParcelMultiple
  • sessionId (string);
  • barcodes (List<string>);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
  • returnOnlyLastOperation (boolean); false is the default value
List of ResultTrackPickingEx
  • InvalidSessionException – The session is invalid;
This method can be used to track the state/history of a shipment or a number of shipments.
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.
listCountries
  • sessionId (string);
  • name (string);
  • language (ParamLanguage); Bulgarian language is used by default if language is not specified
List of ResultCountry. The result is limited to 10 records
  • InvalidSessionException – The session is invalid;
Returns a list of countries matching the search criteria.
listCountriesEx List of ResultCountry. The result is limited to 10 records
  • InvalidSessionException – The session is invalid;
Returns a list of countries matching the search criteria.
listStates
  • sessionId (string);
  • countryId (signed 64-bit integer);
  • name (string);
List of ResultState. The result is limited to 10 records
  • InvalidSessionException – The session is invalid;
Returns list of states for a country that match search criteria
getStateById
  • sessionId (string);
  • stateId (string);
ResultState
  • InvalidSessionException – The session is invalid;
Returns state by id
validatePostCode
  • sessionId (string);
  • countryId (signed 64-bit integer);
  • postCode (string);
boolean flag for validation result
  • InvalidSessionException – The session is invalid;
Validates post code for specific country
searchSecondaryPickings List of ResultPickingInfo
  • InvalidSessionException – The session is invalid;
Returns a list with all not canceled pickings, which are secondary to the picking with the specified billOfLading.
getPickingExtendedInfo
  • sessionId (string);
  • billOfLading (signed 64-bit integer);
ResultPickingExtendedInfo
  • InvalidSessionException – The session is invalid;
Returns extended information about the picking with the specified billOfLading.

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 if it is allready passed or is overriden with 09:01). 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 (must be equal to the number of parcels described in List parcels) yes Depends on the used serviceTypeId
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
retToOfficeId signed 64-bit integer (nullable) ID of the office which is to receive the return receipt and/or the return documents. 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. Pallet shipments require full list of parcels (pallets) in this property. For non-pallet shipments the server will automatically generate parcels according to the value specified in parcelsCount property if no data for parcels is provided. If data for parcels is available, the number of provided parcels (including first parcel) should be equal to the value of parcelsCount property. For non-pallet shipments, the first parcel could be omitted (list of parcels could start from seqNo = 2) and server will create automatically first parcel for you. For all shipments the number of the first parcel is always auto-generated and is equal to the BOL number. yes - if pallet service is used, otherwise no Depends on the used serviceTypeId
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
optionsBeforePayment ParamOptionsBeforePayment Optional services, allowed before payment, when cash on delivery or money transfer is enabled for the picking. no
retServicesRequest List<ParamReturnServiceRequest> Specifies the list of return services request no
retShipmentRequest ParamReturnShipmentRequest Specifies the return shipment request no
retThirdPartyPayer boolean Specifies if the payer of the return receipt and/or the return documents is the same third party, which is also the payer of the courier service. no
packings List<ParamPackings> Packings details. no
returnVoucher ParamReturnVoucher Specifies details for return voucher. no
deliveryToFloorNo signed 32-bit integer (nullable) Indicates the floor, which the shipment should be delivered to. no
includeShippingPriceInCod boolean Flag indicating whether the shipping price should be included into the cash on delivery price. no
ParamCalculation
Property name Type Description Required Limit
takingDate date The date for shipment pick-up (the "time" component is ignored if it is allready passed or is overriden with 09:01). 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
willBringToOfficeId signed 64-bit real (nullable) 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 (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. If willBringToOfficeId is set to 0, broughtToOffice flag is considered "false". no
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
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. If officeToBeCalledId is provided (non-null and non-zero), toBeCalled flag is considered "true". If officeToBeCalledId is set to 0, toBeCalled flag is considered "false". no
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 (must be equal to the number of parcels described in List parcels) yes Depends on the used serviceTypeId
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 sender country, post code or site must be set
senderCountryId signed 64-bit integer (nullable) Sender's country ID no. Defaults to Bulgaria when not specified
senderPostCode string Sender's post code According to internal nomenclature support
senderSiteId signed 64-bit integer (nullable) Sender's site ID Only if the country has full site nomenclature and neither senderId nor willBringToOfficeId is set.
receiverId signed 64-bit integer (nullable) Receiver's ID Either receiverId or receiver country, post code or site must be set
receiverCountryId signed 64-bit integer (nullable) Receiver's country ID no. Defaults to Bulgaria when not specified
receiverPostCode string Receiver's post code According to internal nomenclature support
receiverSiteId signed 64-bit integer (nullable) Receiver's site ID Only if the country has full site nomenclature and neither receiverId nor officeToBeCalledId is set.
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
includeShippingPriceInCod boolean Flag indicating whether the shipping price should be included into the cash on delivery price. no
checkTBCOfficeWorkDay boolean Check if specified office to be called is working. Default value - true 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 or receiver country is different from Bulgaria. ("Required" means at least one valid phone number must be set.) 3
email string Email address no 255
privatePersonType signed 32-bit integer (nullable) Private Person Type (0/null=no specified type, 1=private person or 2=company) no
ParamAddress
Property name Type Description Required Limit
siteId signed 64-bit integer Site ID Depends on country definition ResultCountry.siteNomen
siteName string Site name siteName must be set <=> siteId is null 50
postCode string Post code Depends on country definition ResultCountry.requirePostcode 10
streetName string Street name When address is required (i.e. when clientId is null), the following rule must be met:
  • not empty street (ID or Type&Name) and (streetNo or blockNo)
  • or
  • not empty quarter (ID or Type&Name) and (streetNo or blockNo)
  • or
  • not empty common object
  • or
  • all components of the address within the site stored in 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 no
countryId signed 64-bit integer (nullable) Country id. Defaults to Bulgaria if not specified no
stateId string State id According to internal nomenclature support 50
frnAddressLine1 string Address line 1 In case the country is not Bulgaria 40
frnAddressLine1 string Address line 2 no 40
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 sequential number (1, 2, 3, ...). First parcel (seqNo = 1) could be omitted for non-pallet shipments. In this case it will be auto-generated. yes
parcelId signed 64-bit integer Special value of -1 could be used to request server side automatic parcel number (barcode) generation. Otherwise valid parcel number (barcode) is required. For the first parcel (the one with seqNo equal to 1) automatic barcode generation is required. Actually, the first parcel will take the auto-generated BOL number as its parcel number. yes
packId signed 64-bit integer (nullable) Packing ID no
size Size Pallet or Parcel size. no
weight signed 64-bit real Pallet or Parcel weight. no
foreignParcelNumber string Foreign parcel number associated with this parcel no 30
predefinedSize string Applicable to 500 - Speedy Postal service only
Name of the predefined size. If such is found, its dimensions will be set for the given parcel, this said neither Size dimension must be set! Also, if no weight parameter is provided, it will be extracted from the predefined size as well. Accepts the following values: XS, S, M, L.
no
ParamPDF
Property name Type Description Required Limit
type signed 32-bit integer The document type (10 - BOL; 20 - labels; 25 - labels with additional barcode; 30 - return voucher) yes
ids List<signed 64-bit integer> List of IDs. For types 10 and 30 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
countryId signed 64-bit integer (nullable) Country id no
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
searchString string Search string 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
foreignParcelNumber string Foreign parcel number associated with this parcel no 30
predefinedSize string Applicable to 500 - Speedy Postal service only
Name of the predefined size. If such is found, its dimensions will be set for the given parcel, this said neither Size dimension must be set! Also, if no weight parameter is provided, it will be extracted from the predefined size as well.
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
returnCityCenterIfNoAddress boolean Return city center coordinates when only siteId is specified 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 string Client name (future-use) no
objectName string Object name (future-use) no
phone string Phone (future-use) no
siteId signed 64-bit integer Site ID (future-use) no
ParamOptionsBeforePayment
Property name Type Description Required Limit
open boolean Specifies if the client is allowed to open the package before payment. no
test boolean Specifies if the client is allowed to test the package before payment. no
ParamPackings
Property name Type Description
packingId signed 64-bit integer Reserved for internal use
count signed 32-bit integer Reserved for internal use
ParamFilterCountry
Property name Type Description Required Limit
countryId signed 64-bit integer Country id no 999
name string Country name or part of it no  
isoAlhpa2 string ISO alpha2 code no 2
isoAlpha3 string ISO alpha3 code no 3
ParamReturnServiceRequest
Property name Type Description Required Limit
serviceTypeId signed 64-bit integer Service type id yes
parcelsCount signed 32-bit integer Number of parcels yes According to return service configuraton and limited to the number of parcels of original bill of lading. Minimum 1
ParamReturnShipmentRequest
Property name Type Description Required Limit
amountInsuranceBase signed 64-bit integer (nullable) Insurance base amount no
fragile boolean (nullable) Fragile flag no. Should be always false if insurance base amount is not specified
parcelsCount signed 32-bit integer Number of parcels yes Min 1
serviceTypeId signed 64-bit integer Service type id yes
ParamSearchSecondaryPickings
Property name Type Description Required
billOfLading signed 64-bit integer BOL of the primary shipment yes
secondaryPickingType signed 32-bit integer (nullable) Filters the list for shipments of the specified type only. Not used if null.
1 = PICKING_TYPE_RETURN_SHIPMENT - return documents/receipt/service/shipment
2 = PICKING_TYPE_STORAGE_PAYMENT - warehouse charges
3 = PICKING_TYPE_REDIRECT - redirect shipment
4 = PICKING_TYPE_SEND_BACK - return to sender
5 = PICKING_TYPE_MONEY_TRANSFER - money transfer
6 = PICKING_TYPE_TRANSPORT_DAMAGED - damaged shipment transport
7 = PICKING_TYPE_RETURN_WITH_VOUCHER - return with voucher
no
ParamReturnVoucher
Property name Type Description Required
serviceTypeId signed 64-bit integer Service type id yes
payerType signed 32-bit integer Payer type of the new bill of lading (0=sender, 1=receiver or 2=third party). yes
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
cargoType signed 32-bit integer Cargo type (1 - CARGO_TYPE_PARCEL, 2 - CARGO_TYPE_PALLET)
ResultCourierServiceExt
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
deliveryDeadline datetime The deadline for shipment delivery
cargoType signed 32-bit integer Cargo type (1 - CARGO_TYPE_PARCEL, 2 - CARGO_TYPE_PALLET)
allowanceDeliveryToFloor ComplementaryServiceAllowance Specifies if the complementary service "Delivery to floor" is banned, allowed or required
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
countryId signed 64-bite integer Site country id
servingOfficeId signed 64-bite integer Serving office id
coordX signed 64-bit real GPS X coordinate
coordY signed 64-bit real GPS Y coordinate
coordType signed 32-bit integer GPS coordinates type id
servingDays String 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.)
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
maxParcelDimensions Size Max parcel size for office
maxParcelWeight signed 64 bit real Max parcel weight for office
workingTimeSchedule List<ResultWorkingTime> Working time schedule for office
officeType signed 16-bit integer (nullable) Office type
0 - Speedy office 3 - APT
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
barcode signed 64-bit integer (nullable) BOL number or ParcelId
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
signatureImage string Image URL for proof of delivery
foreignParcelNumber string Foreign parcel number associated with this parcel
exceptionCodes List of signed 32-bit integer (nullable) List of exception codes.
ResultTrackPickingEx
Property name Type Description
barcode signed 64-bit integer (nullable) BOL number or ParcelId
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
signatureImage string Image URL for proof of delivery
foreignParcelNumber string Foreign parcel number associated with this parcel
exceptionCodes List of signed 32-bit integer (nullable) List of exception codes.
foreignParcelNumbersList List<string> Foreign parcel numbers list associated with this parcel
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
countryId signed 64-bit integer Country ID
frnAddressLine1 string Foreign address line 1
frnAddressLine2 string Foreign address line 2
stateId string Country state id
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
siteAddressString string Site address string
localAddressString string Concatenated local address string
countryId signed 64-bit integer Country ID
frnAddressLine1 string Foreign address line 1
frnAddressLine2 string Foreign address line 2
stateId string Country state id
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
ResultCountry
Property name Type Description
countryId signed 64-bit integer Country id
name string Country name in specified langage in request
isoAlpha2 string ISO alpha 2 code
isoAlpha3 string ISO alpha 3 code
requirePostCode boolean Flag whether post code is required for the country
postCodeFormat string Post code format
requireState boolean Flag whether country requires state
siteNomen signed 32-bit integer 0 - Speedy has no site nomenclature for this country.
1 - Speedy has full site nomenclature for this country.
2 - Speedy has partial site nomenclature for this country.
activeCurrencyCode string Current active currency code
ResultState
Property name Type Description
stateId string State id
name string State name
stateAlpha string ISO alpha code
countryId signed 64-bit integer Country id (ISO code)
ResultWorkingTime
Property name Type Description
date Date Working time date
workingTimeException boolean Shows whether office working time is overriden
workingTimeFrom signed 16-bit integer (nullable) Working time - FROM
workingTimeTo signed 16-bit integer (nullable) Working time - TO
ResultPickingInfo
Property name Type Description
billOfLading signed 64-bit integer BOL of the secondary shipment.
secondaryPickingType signed 32-bit integer (nullable) tr>
1 = PICKING_TYPE_RETURN_SHIPMENT - return documents/receipt/service/shipment
2 = PICKING_TYPE_STORAGE_PAYMENT - warehouse charges
3 = PICKING_TYPE_REDIRECT - redirect shipment
4 = PICKING_TYPE_SEND_BACK - return to sender
5 = PICKING_TYPE_MONEY_TRANSFER - money transfer
6 = PICKING_TYPE_TRANSPORT_DAMAGED - damaged shipment transport
7 = PICKING_TYPE_RETURN_WITH_VOUCHER - return with voucher
takingDate date The date for shipment pick-up (the "time" component is ignored if it is allready passed or is overriden with 09:01). Default value is "today".
serviceTypeId signed 64-bit integer Courier service type ID.
hasScans boolean Shows whether the secondary shipment has any barcode history operations.
ResultPickingExtendedInfo
Property name Type Description
billOfLading signed 64-bit integer BOL number
takingDate date The date for shipment pick-up (the "time" component is ignored if it is allready passed or is overriden with 09:01). Default value is "today".
serviceTypeId signed 64-bit integer Courier service type ID
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.
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.)
deferredDeliveryWorkDays signed 32-bit integer (nullable) Deferred delivery work days
backDocumentsRequest boolean Indicates if the shipment has a "request for return documents"
backReceiptRequest boolean Indicates if the shipment has a "request for return receipt"
willBringToOfficeId long ID of an office where the sender intends to deliver the shipment by him/herself. Non-null and non-zero value indicates this picking as "to office". Otherwise "from address" is considered.
payCodToThirdParty boolean COD value is to be paid to a third party
retMoneyTransferReqAmount signed 64-bit real (nullable) Return money-transfer request amount
parcelsCount signed 32-bit integer Parcels count
weightDeclared signed 64-bit real Declared weight (the greater of "volume" and "real" weight values)
weightMeasured signed 64-bit real (nullable) Measured weight
weightCalculation signed 64-bit real (nullable) Calculation weight
contents string Contents
packing string Packing
documents boolean Indicates whether the shipment consists of documents
fragile boolean Indicates whether the shipment is fragile
palletized boolean Indicates whether the shipment is palletized
sender ResultClientInfo Data for the sender
receiver ResultClientInfo Data for the receiver
payerType signed 32-bit integer Payer type (0=sender, 1=receiver or 2=third party)
payerRefId signed 64-bit integer (nullable) Payer ID
payerTypeInsurance signed 32-bit integer (nullable) Insurance payer type (0=sender, 1=reciever or 2=third party)
payerRefInsuranceId signed 64-bit integer (nullable) Insurance payer ID
payerTypePackings signed 32-bit integer (nullable) Packings payer type (0=sender, 1=reciever or 2=third party)
payerRefPackingsId signed 64-bit integer (nullable) Packings payer ID
noteClient string Client's note
discCalc FixedDiscountCardId Card/Coupon/Voucher number for fixed discount
retToClientId signed 64-bit integer (nullable) ID of the client who is to receive the return receipt and/or the return documents.
retToOfficeId signed 64-bit integer (nullable) ID of the office which is to receive the return receipt and/or the return documents.
ref1 string An optional reference code
ref2 string An optional reference code
parcels List<ResultParcelInfoEx> Data for parcels.
palletsListDeclared string List of declared pallet details
palletsListMeasured string List of measured pallet details
palletsListCalculation string List of calculation pallet details
specialDeliveryId signed 32-bit integer (nullable) A special delivery ID
optionsBeforePayment ResultOptionsBeforePayment Optional services, allowed before payment, when cash on delivery or money transfer is enabled for the picking.
retServicesRequest List<ResultReturnServiceRequest> List of return services request
retShipmentRequest ResultReturnShipmentRequest Return shipment request
retThirdPartyPayer boolean Specifies if the payer of the return receipt and/or the return documents is the same third party, which is also the payer of the courier service.
packings List<ResultPackings> Packings details.
returnVoucher ResultReturnVoucher Details for return voucher
deliveryToFloorNo signed 32-bit integer (nullable) Indicates the floor, which the shipment should be delivered to.
amounts ResultAmounts Amounts
deadlineDelivery date Deadline for delivery
deliveryInfo ResultDeliveryInfo Delivery information
codPayment CODPayment COD payment information
redirectBillOfLading signed 64-bit integer (nullable) BOL number of redirect picking
returnBillOfLading signed 64-bit integer (nullable) BOL number of return picking
primaryPickingBOL signed 64-bit integer (nullable) Primary picking BOL
pickingType signed 32-bit integer (nullable) Picking type
1 = PICKING_TYPE_RETURN_SHIPMENT - return documents/receipt/service/shipment
2 = PICKING_TYPE_STORAGE_PAYMENT - warehouse charges
3 = PICKING_TYPE_REDIRECT - redirect shipment
4 = PICKING_TYPE_SEND_BACK - return to sender
5 = PICKING_TYPE_MONEY_TRANSFER - money transfer
6 = PICKING_TYPE_TRANSPORT_DAMAGED - damaged shipment transport
7 = PICKING_TYPE_RETURN_WITH_VOUCHER - return with voucher
pendingParcelsDescription boolean (nullable) Value of pendingParcelsDescription flag
pendingShipmentDescription boolean (nullable) Value of pendingShipmentDescription flag
ResultClientInfo
Property name Type Description
clientId signed 64-bit integer (nullable) Client ID
partnerName string Name of the client (company or private person)
objectName string Company department/office
address ResultAddressInfo Address
contactName string Contact name
phones List<ResultPhoneNumber> Phone numbers
ResultAddressInfo
Property name Type Description
siteId signed 64-bit integer (nullable) 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
countryId signed 64-bit integer Country ID
frnAddressLine1 string Foreign address line 1
frnAddressLine2 string Foreign address line 2
stateId string Country state id
ResultReturnServiceRequest
Property name Type Description
serviceTypeId signed 64-bit integer Service type id
parcelsCount signed 32-bit integer Number of parcels
ResultPackings
Property name Type Description
packingId signed 64-bit integer Packing id
count signed 32-bit integer Packings count
ResultParcelInfoEx
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.
weightMeasured signed 64 bit real (nullable) Measured weight
weightDeclared signed 64 bit real (nullable) Declared weight
sizeMeasured Size Measured size
sizeDeclared Size Declared size
foreignParcelNumber string (nullable) Foreign parcel number associated with this parcel
packId signed 64-bit integer (nullable) Packing ID (number)
foreignParcelNumbersList List<string> Foreign parcel numbers list associated with this parcel
ResultOptionsBeforePayment
Property name Type Description
open boolean (nullable) Indicates if the client is allowed to open the package before payment.
test boolean (nullable) Indicates if the client is allowed to test the package before payment.
ResultReturnShipmentRequest
Property name Type Description
amountInsuranceBase signed 64-bit integer (nullable) Insurance base amount
fragile boolean (nullable) Fragile flag
parcelsCount signed 32-bit integer Number of parcels
serviceTypeId signed 64-bit integer Service type id
ResultReturnVoucher
Property name Type Description
serviceTypeId signed 64-bit integer Service type id
payerType signed 32-bit integer Payer type (0=sender, 1=receiver or 2=third party)
ResultDeliveryInfo
Property name Type Description
deliveryDate Date Delivery date
consignee string The name of the person who received the shipment
deliveryNote string Delivery note
CODPayment
Property name Type Description
date Date Date of payment
totalPayedOutAmount signed 32-bit real Total payed out amount
CreatePDFExResponse
Property name Type Description
pdfBytes byteArray PDF content data
hubId signed 64-bit integer (nullable) Delivery hub id
officeId signed 64-bit integer (nullable) Delivery office id
deadlineDay signed 32-bit integer (nullable) Delivery deadline day of month
deadlineMonth signed 32-bit integer (nullable) The delivery deadline month;
tourId signed 64-bit integer (nullable) Tour Id.
fullBarcode String Barcode containing the parcel number and important routing information.
ResultRoutingLabelInfo
Property name Type Description
hubId signed 64-bit integer (nullable) Delivery hub id
officeId signed 64-bit integer (nullable) Delivery office id
deadlineDay signed 32-bit integer (nullable) Delivery deadline day of month
deadlineMonth signed 32-bit integer (nullable) The delivery deadline month;
tourId signed 64-bit integer (nullable) Tour Id.
fullBarcode String Barcode containing the parcel number and important routing information.

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
INSURANCE_NOT_ALLOWED_FOR_SERVICE The insurance value is not allowed for the specified service
INSURANCE_REQUIRED_FOR_SERVICE The insurance value is required for the specified service
AMOUNT_CASH_ON_DELIVERY_OUT_OF_RANGE The cash-on-delivery value is outside the allowed limits
AMOUNT_CASH_ON_DELIVERY_NOT_ALLOWED_FOR_SERVICE The cash-on-delivery value is not allowed for the specified service
AMOUNT_CASH_ON_DELIVERY_REQUIRED_FOR_SERVICE The cash-on-delivery value is required for the specified service
AMOUNT_MONEY_TRANSFER_REQ_OUT_OF_RANGE The money-transfer request amount is outside the allowed limits
MONEY_TRANSFER_NOT_ALLOWED The money-transfer request is not allowed
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_WEIGHT_OR_SIZE Invalid weight or size
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_PARCEL_SIZE Invalid size for specified parcel when parcel courier service is used
INVALID_PARCEL_WEIGHT Invalid weight for specified parcel when parcel courier service is used
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)
INVALID_RETURN_SHIPMENT_REQUEST Invalid /not allowed/ return shipment request
INVALID_RETURN_SERVICE_REQUEST Invalid /not allowed/ return service request
INVALID_BACK_DOCUMENT_REQUEST Invalid /not allowed/ back document request
INVALID_BACK_RECEIPT_REQUEST Invalid /not allowed/ back receipt request
INVALID_MONEY_TRANSFER_REQUEST Invalid /not allowed/ money transfer request
INVALID_VALUE_PARTNER_NAME Partner name should be minimum 3 symbols, having at least one letter.
SERVICE_NOT_ALLOWED_FOR_OFFICE_BTO Service is not allowed for specified office brought to
SERVICE_NOT_ALLOWED_FOR_OFFICE_TBC Service is not allowed for specified office to be called
FOREIGN_PARCEL_NUMBER_ERROR Error in providing foreign parcel number
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
MISSING_REQUIRED_VALUE_PARCELS Missing required value: Parcels
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
OFFICE_BTO_NOT_ALLOWED_FOR_SHIPMENT Specified office brought to is not allowed for the shipment
OFFICE_TBC_NOT_ALLOWED_FOR_SHIPMENT Specified office to be called is not allowed for the shipment
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.
BOL_CREATION_LIMIT_VIOLATED BOL creation limit for a period is violated
BOL_CREATION_DAILY_LIMIT_VIOLATED BOL creation limit for the day is violated
INVALID_DEADLINE_FOR_DELIVERY Calculated delivery date is a working day for Speedy offices only. Pick-ups from and deliveries to address are not served. Please, specify drop-off office or change the courier service
BOL_CREATION_TIME_INTERVAL_LIMIT_REACHED BOL creation limit for not-taken pickings in current time interval is reached
BOL_CREATION_TIME_INTERVAL_SERVICE_LIMIT_REACHED BOL creation limit for not-taken pickings in current time interval for service is reached
BOL_CREATION_DAILY_ADDRESS_LIMIT_REACHED BOL creation limit for courier delivery addresses is reached
NOT_ALLOWED_ADDITIONAL_TAKING_TIME Additional taking time is not allowed
INVALID_RETURN_VOUCHER_REQUEST Invalid /not allowed/ return voucher request
INVALID_FLOOR_TO_DELIVER_TO The specified floor to deliver the shipment to is not valid
DELIVERY_TO_FLOOR_NOT_ALLOWED_FOR_SERVICE Delivery to floor option is not allowed for the selected service
DELIVERY_TO_FLOOR_NOT_ALLOWED_WITHOUT_ANNEX Delivery to floor is not allowed without annex for delivery to floor
DELIVERY_TO_FLOOR_NOT_ALLOWED_WITHOUT_CONTRACT Delivery to floor is not allowed without contract
INVALID_DECLARED_PARCELS_COUNT Declared parcels count does not match the described parcels count
INVALID_RECEIVER_MOBILE_PHONE_NUMBER_FOR_APT_TBC Receiver MOBILE phone is required when office to be called is of type APT
PARCEL_SIZE_MUST_BE_DEFINED_FOR_OFFICE_OF_TYPE_APT Parcel size must be defined for officeToBeCalled/willBringToOffice of type APT
PARCEL_PREDEFINED_SIZE_DOES_NOT_EXIST Provided predefinedSize does not exist
PARCEL_PREDEFINED_SIZE_NOT_ALLOWED Specifying predefinedSize is allowed only if no size dimensions are described.
CONTACT_NAME_REQUIRED Required value: contact name
CONTACT_NAME_AND_PARTNER_NAME_CANNOT_BE_EQUAL Specified contact name and partner name cannot be equal
CONTACT_NAME_MUST_BE_EMPTY Required empty value: contact name
SOAP fault error codes (XXX codes found in prefix [ERR_XXX] in SOAP fault message)
Value Description
001 Picking is locked for editing by another user
002 Picking is changed by someone else
003 Partial picking state prevents editing
004 Weight is out of range or missing
005 Calculation error
006 Invalid BOL/parcel number or unsufficient priviledges
007 Invalid number of parcels
008 Invalid Speedy office
009 Courier service error
010 Invalid COD parameters
011 Invalid insurance parameters
012 Invalid location
013 Invalid client details
014 Invalid address
015 Not enough priviledges
050 Temporarily unavailable
500 Illegal argument
900 Common error
999 Unexpected error
Operation codes
Value Description
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
124 Delivered Back to Sender
125 Destroyed
127 Theft/Burglary
128 Canceled
129 Administrative Closure
134 Prepared for Self-collecting Consignee
148 Shipment data received
Tracking exception codes (codes found in ResultTrackPicking and ResultTrackPickingEx)
Value Description
11 Wrong address
12 Refused by consignee - damaged
14 Refused by consignee - not ordered
15 Refused by consignee
16 Refused by consignee - contents checked, found to be damaged
17 Return (pick-up) after wrong delivery
19 Consignee not present - informed first time
20 Self-collecting consignee
22 Broken in sub-contractor's custody
25 Closed (e.g. department store)
27 Lack of space
29 Consignment incomplete
32 Lack of time
35 Consignee not present, informed, on holiday
37 Consignee not present - third time
42 Consignee 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 contents check/test

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 willBringToOfficeId 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 sender site.

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

Demo address form

10. Change history

Nov 28, 2016
Nov 28, 2016
Sep 8, 2016
Aug 16, 2016
July 06, 2016
June 13, 2016
June 03, 2016
May 25, 2016
Apr 24, 2016
Apr 13, 2016
Apr 06, 2016
Mar 28, 2016
Mar 15, 2016
Mar 11, 2016
Mar 08, 2016
Feb 24, 2016
Feb 8, 2016
Feb 4, 2016
Feb 2, 2016
Jan 21, 2016
Dec 21, 2015
Dec 02, 2015
Nov 26, 2015
Oct 16, 2015
Oct 12, 2015
Sep 17, 2015
Sep 14, 2015
Jul 17, 2015
Jun 16, 2015
Jun 15, 2015
Jun 12, 2015
Apr 9, 2015
Mar 13, 2015
Feb 2, 2015
Jan 24, 2015
Dec 10, 2014
Dec 5, 2014
Dec 3, 2014
Oct 22, 2014
Sep 17, 2014
Aug 27, 2014
Jul 14, 2014
Jul 04, 2014
Jun 26, 2014
May 14, 2014
May 12, 2014
May 10, 2014
May 09, 2014
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