Speedy Web Service

Contents

1. Introduction
2. Special terms and conditions
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:

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:

• Zeroes (0) are treated as null for all numeric data types;
• Values smaller than 01.01.2000 are treated as null for the "date" type;
• Values greater than 01.01.3000 are not allowed.

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 [email protected] and provide the following info:

• Name
• Company name
• Direct Phone number
• Skype Name (if available)

To get technical support for the integration please send us an e-mail to [email protected] and provide the following info:

• UserName
• SessionId (if relevant)
• ErrorDescription (if relevant)
• ErrorId (if relevant)
• ErrorType (if relevant)
• ErrorMessage (if relevant)

Subscribe to EPS to track updates on web services.

2. Special terms and conditions

3. Methods description

4. Custom types description

5. Validation errors description

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:
   • contactName (ParamClientData)
   • phones (ParamClientData)
   • addressNote (ParamAddress) - optional
   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. Only phone numbers starting with "0" (zero) or "+" sign are allowed. (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:

• If the payer is "third party" then it can only be Х.
• If the payer is Х then everyone is allowed to be sender or receiver.
• If the payer is not Х then the sender must be Х.

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:

• pendingParcelsDescription
• pendingShipmentDescription

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:

• takingDate
• serviceTypeId
• parcelsCount
• weightDeclared
• documents
• deferredDeliveryWorkDays
• sender (only siteId); if willBringToOfficeId is set, then siteId must be null/0
• receiver (only siteId); if officeToBeCalledId is set, then siteId must be null/0

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

• New property additionalDeliverySurcharge added to ResultAmounts.

• New property externalReturnVoucherId added to ParamReturnVoucher.

• New property exciseGoods added to ParamPicking.

• New properties tollSurcharge, protectiveMeasuresSurcharge and addrNormSurcharge added to ResultAmounts.

• New property validityPeriod added to ParamReturnVoucher.

• New properties broughtToAllowed and toBeCalledAllowed added to ResultOfficeEx.

• Added new method: mapForeignBarcode().

• Added new structure ResultReturnAmounts to ResultAmounts with moneyTransferPremium property included.

• New property requireUnsuccessfulDeliveryStickerImage added to ParamPicking.

• New property payCodToLoggedInClient added to ParamPicking.

• New property addressTypeParamsCurrent added to ResultCountry.
• ResultCountry's addressTypeParams property has been deprecated.

• New property retMoneyTransferReqAmount added to ParamCalculation.

• New property additionalInfo added to ResultTrackPickingEx.

• New properties ref1 and ref2 added to ResultParcelInfoEx.
• New property consolidationRef added to ResultPickingExtendedInfo.

• New properties ref1 and ref2 added to ParamParcel.
• New properties ref1 and ref2 added to ParamParcelInfo.
• New property consolidationRef added to ParamPicking.
• New PickingValidationException.errorType VALUE_OUT_OF_RANGE_CONSOLIDATION_REF added.

• New property additionalCopyForSender added to ParamPDF.

• New property infoURL has been added to ResultTrackPickingEx.

• The validation of ParamPhoneNumber has been fixed. Only phone numbers starting with "0" (zero) or "+" sign are allowed.

• New property addressTypeParams added to ResultCountry.

• New property automaticConvertionToWin1251 (boolean) added to ParamPicking which is used for transliterate texts from Unicode to Windows-1251 code table. Acceptable characters which are not transliterated are ANSI (Latin) characters (a-z, A-Z), Cyrillic characters (а-я, А-Я), digits (0-9), №, €, §. API supports only printable ANSI (Latin) and Cyrillic characters. False is the default value.

• New method convertToWin1251 introduced. It is used to transliterate texts from Unicode to Windows-1251 code table. Acceptable characters which are not transliterated are ANSI (Latin) characters (a-z, A-Z), Cyrillic characters (а-я, А-Я), digits (0-9), №, €, §. API supports only printable ANSI (Latin) and Cyrillic characters.

• New property nearbyOfficeId added to ResultOfficeEx.

• New property requireParcelsData added for ResultCourierServiceExt.

• New property ignoreAmountInsuranceBaseIfNotApplicable added for ParamCalculation.

• New property allowanceOptionsBeforePayment added for ResultCourierServiceExt.
• New property allowanceReturnVoucher added for ResultCourierServiceExt.

• Added new structure MoneyTransferPayment with totalPayedOutAmount and date properties included.

• New property heavyPackageFee added to ResultAmounts.

• New request property workingTimeDayOffFrom added to ResultOfficeEx.
• New request property workingTimeDayOffTo added to ResultOfficeEx.

• New request property halfWorkDayDelivery added to ParamPicking and ParamCalculation.

• New request parameter 'siteId' added for validatePostCode.

• New properties returnServiceTypeId and returnPayerType added for ParamOptionsBeforePayment.
• New properties returnServiceTypeId and returnPayerType added for ResultOptionsBeforePayment.
• New PickingValidationException.errorType INVALID_OPTIONS_BEFORE_PAYMENT added.
• New PickingValidationException.errorType INVALID_OPTIONS_BEFORE_PAYMENT_DETAILS added.

• New property foreignParcelNumbersList added for ResultTrackPickingEx.
• New property foreignParcelNumbersList added for ResultParcelInfoEx.

• New property privatePersonType added for ParamClientData.
• New PickingValidationException.errorType CONTACT_NAME_REQUIRED added.
• New PickingValidationException.errorType CONTACT_NAME_AND_PARTNER_NAME_CANNOT_BE_EQUALS added.
• New PickingValidationException.errorType CONTACT_NAME_MUST_BE_EMPTY added.

• New property officeType added for ResultOfficeEx.
• New property allowanceDeliveryToFloor added for ResultCourierServiceExt.

• New properties pendingParcelsDescription and pendingShipmentDescription added for ResultPickingExtendedInfo.
• New PickingValidationException.errorType PARCEL_SIZE_MUST_BE_DEFINED_FOR_OFFICE_OF_TYPE_APT added.

• Method getAddressNomenclature() returns additional column MainSiteId for nomenType 100 - Sites.

• Added new method: getRoutingLabelInfo(), which returns important routing information for a parcel.

• New PickingValidationException.errorType INVALID_PARCEL_SIZE added.
• New PickingValidationException.errorType INVALID_PARCEL_WEIGHT added.

• New property checkTBCOfficeWorkDay for ParamCalculation added.

• New validation error type - INVALID_DECLARED_PARCELS_COUNT has been added, specifying that the declared parcels count does not match the described parcels one.
• ParamPicking's Size property has been deprecated.

• New properties primaryPickingBOL and pickingType added for ResultPickingExtendedInfo.

• New property packId is added for ResultParcelInfoEx.

• New argument countryId is added for method listOfficesEx.

• New property cargoType introduced in ResultCourierService and ResultCourierServiceExt structures.

• New property includeShippingPriceInCod introduced in ParamPicking and ParamCalculation structures, indicating whether the shipping price should be included into the cash on delivery price.

• New property exceptionCode in ResultTrackPicking and ResultTrackPickingEx introduced.

• New method getPickingExtendedInfo introduced.

• New property deliveryToFloorNo introduced in ParamPicking structure, used for pointing that the shipment should be delivered to the specified floor.

• New arguments senderId, receiverId, senderOfficeId, receiverOfficeId are added for method getWeightInterval.

• New parameter "returnOnlyLastOperation" (boolean) added to methods trackPickingEx(), trackParcel(), trackParcelMultiple(), which specifies whether only the last barcode operation to be returned or the full list.
• New arguments senderId, receiverId, senderOfficeId, receiverOfficeId are added for method listServicesForSites.

• New type ParamReturnVoucher is introduced to specify return voucher details.
• New field "returnVoucher" of type ParamReturnVoucher is added in structure ParamPicking
• The methods createPDF() and method createPDFEx() are extended so that they can be used to create return voucher (new document type added: 30). See ParamPDF for more details.
• Added new validation error INVALID_RETURN_VOUCHER_REQUEST - Invalid /not allowed/ return voucher request.

• Added new validation error NOT_ALLOWED_ADDITIONAL_TAKING_TIME - Additional taking time is not allowed.

• Added new argument senderId in method getAllowedDaysForTaking

• Added new validation error BOL_CREATION_TIME_INTERVAL_LIMIT_REACHED - BOL creation limit for not-taken pickings in current time interval is reached.
• Added new validation error BOL_CREATION_TIME_INTERVAL_SERVICE_LIMIT_REACHED - BOL creation limit for not-taken pickings in current time interval for service is reached.
• Added new validation error BOL_CREATION_DAILY_ADDRESS_LIMIT_REACHED - BOL creation limit for courier delivery addresses is reached.

• Type of argument billOfLading in trackPicking() method is changed from signed 64-bit integer to string
• Type of argument billOfLading in trackPickingEx() method is changed from signed 64-bit integer to string
• Type of argument parcelId in trackParcel() method is changed from signed 64-bit integer to string
• Type of argument barcodes in trackParcelMultiple() method is changed from List<signed 64-bit integer> to List<string>
• New property foreignParcelNumber is added in class ResultTrackPicking
• New property foreignParcelNumber is added in class ResultTrackPickingEx

• Added new validation error BOL_CREATION_DAILY_LIMIT_VIOLATED - BOL creation limit for the day is violated.

• Added new fields siteAddressString, localAddressString to ResultAddressEx.

• Added new field retToOfficeId to ParamPicking.

• Added new fields willBringToOfficeId, officeToBeCalledId to ParamCalculation.

• Added new field "workingTimeException" to result structure ResultWorkingTime showing whether office working time is overriden.

• Added new field "barcode" to result structure ResultTrackPickingEx and ResultTrackPicking, representing picking's BOL or parcel's parcelId.
• New method trackParcelMultiple() is available.

• Added new field "signatureImage" to result structure ResultTrackPickingEx and ResultTrackPicking

• Added new method: createPDFEx(), extending the current createPDF() with a new result structure, containing more detailed information.

• Added field servingDays to ResultSite.

• Added new method: searchSecondaryPickings().

• New argument "cancelComment" is added for method invalidatePicking().

• Added new properties coordX, coordY, coordType to ResultSite
• Method getAddressNomenclature() returns additional columns CoordX, CoordY, CoordType for nomenType 100 - Sites

• Added new property returnCityCenterIfNoAddress to ParamAddressSearch

• Method getAddressNomenclature() returns additional column Address_EN for nomenType 500 - Common Objects

• New property "servingOfficeId" is added in class ResultSite
• New type ResultWorkingTime introduced to specify office working time
• New properties "maxParcelDimensions", "maxParcelWeight" and "workingTimeSchedule" are added in class ResultOfficeEx
• Method getAddressNomenclature() returns additional columns. For nomenType 100: SiteType_EN, SiteName_EN, MunicipalityName_EN, RegionName_EN. For nomenType 500: CommonObjectType_EN, CommonObjectName_EN. For nomenType 700: BlockName_EN.
• New method getPickingDeliveryInfo() is available.

• New argument "countryId" is added for method getAddressNomenclature
• Method getAddressNomenclature() is extended with nomenclature types for postcodes.
• Method listSites() is now deprecated in favor of listSitesEx().

• Parameter language is added in methods listServices and listServicesForSites

• New type ParamReturnServiceRequest is introduced to specify return service details
• New field "retServicesRequest" of type List<ParamReturnServiceRequest> is added in structure ParamPicking

• New fields "discPcntRetShipment", "discountRetShipment", "specialDelivery" are added in structure ResultAmounts
• New fields "countryId", "stateId", "frnAddressLine1" and "frnAddressLine2" are added in structure ResultAddress
• New fields "countryId", "stateId", "frnAddressLine1" and "frnAddressLine2" are added in structure ResultAddressEx
• New argument "countryId" is added in method listAllSites
• New arguments "senderCountryId" and "senderPostCode" are added in method getAllowedDaysForTaking
• New arguments "senderCountryId", "senderPostCode", "receiverCountryId", "receiverPostCode" are added in method getWeightInterval
• New arguments "senderCountryId", "senderPostCode", "receiverCountryId", "receiverPostCode" are added in method listServicesForSites
• New fields "siteName", "postCode", "countryId", "stateId", "frnAddressLine1", "frnAddressLine2" are added in structure ParamAddress
• New fields "senderCountryId", "senderPostCode", "receiverCountryId", "receiverPostCode" are added in structure ParamCalculation
• New type ParamReturnShipmentRequest is introduced to specify return shipment details
• New field "retShipmentRequest" of type ParamReturnShipmentRequest is added in structure ParamPicking
• New fields "countryId" and "searchString" are added in structure ParamFilterSite
• New type ParamFilterCountry is introduced to specify country search criteria
• New type ResultCountry provided as a result for country search queries
• New type ResultState provided as a result for country state search queries
• New method listCountries is introduced to search for supported countries
• New method listCountriesEx is introduced to search for supported countries using filter
• New method listStates is introduced to search for supported country states
• New method getStateById is introduced to get country state by id
• New method validatePostCode is introduced to verify post code is valid for country

• New property foreignParcelNumber is added in class ParamParcel
• New property foreignParcelNumber is added in class ParamParcelInfo
• Providing data for first parcel (seqNo = 1) is now possible for non-pallet shipments. However, the parcel number must be equal to -1 to be auto-generated.

• Parameter language is added in methods listOfficesEx, listCommonObjects, listBlocks,

• New method getAdditionalUserParams is available.

• New methods listCountries() and listCountriesEx() are available.
• New methods listStates() and getStateById() are available.
• New method validatePostCode() is available.
• Method getAddressNomenclature() is extended is extended with nomenclature types for countries and states.

• New property retThirdPartyPayer is added in ParamPicking class.
• New property optionsBeforePayment is added in ParamPicking class.

• Parameter language is added in methods listQuarterTypes , listQuarters, listStreetTypes , listStreets, listAllSites , listSites and listSitesEx
• Methods listQuarters and listStreets are modified to accept latin characters in search criteria

• New properties payerTypePackings and payerRefPackingsId are available in ParamPicking class.
• New properties payerTypePackings and payerRefPackingsId are available in ParamCalculation class.

• New property specialDeliveryId is available in ParamPicking class.
• New property specialDeliveryId is available in ParamCalculation class.

• New method makeAddressString() is available.

• New method serializeAddress() is available.
• New method deserializeAddress() is available.

• New method listOfficesEx() is available.

• New method listContractClients() is available.
• New method validateAddress() is available.

• New method listSpecialDeliveryRequirements() is available.
• New property email is available in ParamClientData class.

• Method listSitesEx() is modified to accept latin characters in search criteria

• New properties size and weight added to ParamParcelInfo type.

• New method searchClients() is available.

• New method getMicroregionId() is available.

• New method trackParcel() is available.
• Method getAllowedDaysForTaking() returns 10 next available days for taking.

• New property willBringToOfficeId is added in ParamPicking type.

• Service modes description and validation errors related to it added.

• Method getAllowedDaysForTaking() is fixed to accept "minDate" values before current server time. In this case the server assumes the value is current time.

• Method getAddressNomenclature() returns additional column ServingHubOfficeID in result csv for nomenType 100

• Parameter language is added in method trackPickingEx()

• Added new method trackPickingEx() as a replacement for trackPicking()

• Added new property to ParamPicking: retMoneyTransferReqAmount.

• Added new property to ParamOrder: pickupDate.
• From now on, the method getAllowedDaysForTaking() can be used to determine the deadline for creating an order (or the deadline for delivering the shipment to a Speedy office when senderOfficeId is set).

• Added new method: listBlocks().

• The method createPDF() is extended so that it can be used to create labels with an additional custom barcode (new document type added: 25). See ParamPDF for more details.

• The method getAddressNomenclature() is extended. Now it supports new nomenclature types for streets, quarters, common objects, block names. The access to those new nomenclature types requires a special permission.

• Added new method: getAddressNomenclature(). It allows users to downloading nomenclature data in CSV format. For now only data about sites is returned.

• Added new property to ParamPicking and ParamCalculation: deferredDeliveryWorkDays.
• The value of officeToBeCalledId now can be set when invoking the updateBillOfLading method (only when the old value was null/0 and the office being set during the update is located in the same receiver's site).

• Added new property to ParamPicking: clientSystemId.

• Added new property to ParamPicking: skipAutomaticParcelsCreation.

• Added new properties to ParamPicking: ref1 and ref2.

• Added new method for ordering shipments: createOrder().
• Added new method for searching addresses: addressSearch().

• From now on, users can create partial Bills of Lading. Changes include:
  • Added new properties to ParamPicking: pendingParcelsDescription and pendingShipmentDescription.
  • Added new method: updateBillOfLading().
  • Added new method: addParcel().
  • Added new method: finalizeBillOfLadingCreation().

• Added new method for calculating the minimum and maximum shipment weight: getWeightInterval().

• Added new method for canceling shipments: invalidatePicking().
• From now on, users can also set IDs of personal partners to ParamClientData.clientId.

• The getClientById method can now be used to get information about personal partners (not just own company departments/offices).
• Added new properties to ParamAddress: coordX and coordY. They are not required but setting them could help Speedy in serving its clients.

• Added new method: searchPickingsByRefNumber().

• Added new PickingValidationErrorType value - REQUIRED_BRINGING_TO_OFFICE.

• Added new property to ResultAmounts: pcntFuelSurcharge.

• Added new properties to ResultAmounts: fuelSurcharge and islandSurcharge.

• Added new method: getPickingParcels().

• Added new method: createPDF().
• The methods createBillOfLadingPDF() and createCustomTravelLabelPDFType1() are deprecated.
• New exemplary PDF documents were added.