Fetch list of available destinations

It is possible to fetch various types of destinations to use for integrations.

Field NameDescriptionData type
Country Country Code (EE or FI) String
Type Destination Type:
APT = parcel terminal (default)
PO = post office
String
Filter Additional filtering:
Express = parcel terminals in Estonia with Express delivery option
String

GET REQUEST

EE parcel terminals

http://iseteenindus.smartpost.ee/api/?request=destinations&country=EE&type=APT

EE parcel terminals with Express delivery enabled

http://iseteenindus.smartpost.ee/api/?request=destinations&country=EE&type=APT&filter=express

FI parcel terminals

http://iseteenindus.smartpost.ee/api/?request=destinations&country=FI&type=APT

FI post offices

http://iseteenindus.smartpost.ee/api/?request=destinations&country=FI&type=PO

RESPONSE

Field NameDescriptionData type
Place_Id Parcel terminal ID – Use for EE destinations only! Number
Name Destination name String
City Destination city String
Address Destination address String
Country Destination country code String
PostalCode Destination postal code String
RoutingCode Destination routing code String
Availability Time frame when location is open String
Description A short description of the location String
Lat Latitude Number
Lng Longitude Number
<destinations>
	<item>
		<place_id>number</place_id>
		<name>string</name>
		<city>string</city>
		<address>string</address>
		<country>string</country>
		<postalcode>string</postalcode>
		<routingcode>string</routingcode>
		<availability>string</availability>
		<description>string</description>
		<lat>number</lat>
		<lng>number</lng>
	</item>
	<item>
 		…
	</item>
</destinations>

Fetch list of courier visit times (EE parcel terminals only)

GET REQUEST

Courier visit times for all EE parcel terminals

http://iseteenindus.smartpost.ee/api/?request=courier 

Courier visit times for EE parcel terminals with Express service enabled

http://iseteenindus.smartpost.ee/api/?request=courier&type=express 

RESPONSE

Field NameDescriptionData type
Place_Id Parcel terminal ID Number
Day Day number (1= Monday) Number
In   Time
Out   Time
Express_in   Time
express_out   Time
<destinations>
	<item>
		<place_id>Number</place_id>
		<day>Number</day>
		<in>Time</in>
		<out>Time</out>
		<express_in>Time</express_in>
		<express_out>Time</express_out>
	</item>
	<item>
		…
	</item>
</destinations>

Save shipment data

AUTHENTICATION

Business customer authentication information – all of the requests (except for destinations) require authentication information to be included in the POST data.

Field NameDescriptionData typeErrors on
User User name String Unknown user
Password User password String User name and password do not match

GENERAL

Information about the shipment. If “Barcode” field is left blank, one will be assigned automatically. When sending with door code service is not used then the locker size will not be taken into account because sorting station will add the corresponding size for each parcel. Locker size must be added only when the door code service is used.

Field NameDescriptionData typeErrors on
Barcode Shipments bar code String Duplicate; Wrong format
Reference Customers reference number String  
Content Shipment content String  
OrderParent Barcode of parent order (in case of multipleparcel shipment) String Unknown bar code (parent order needs to be created before children)
Weight Weight of the shipment Number Unknown user
Size Locker size (numbers 5-8 or 11)
11 – XS size
5 – S size
6 – M size
7 – L size
8 – XL size
Number Unknown size

SENDER

Following fields need to be filled if “sending with door code” service is used.

Field NameDescriptionData typeErrors on
Name Senders name String  
Phone Senders phone number String  
Email Senders e-mail address String Wrong format
Cash Amount of money the sender has to pay before sending the parcel Number Wrong format
Account Business customer’s account identificator Number  

RECIPIENT

Info related to the recipient.

Field NameDescriptionData typeErrors on
Name Recipients name String  
Phone Recipients phone number String  
Email Recipients e-mail address String Wrong format
Cash Amount of money the recipient has to pay before receiving the parcel Number Service not available; Wrong format
IdCode ID code of the recipient; needed if ID validation is required. Number Wrong format

DESTINATION

You can send parcels using 3 different configurations:

- When sending parcel to EE parcel terminal, fill “Place_id”.
- When sending parcel to FI parcel terminal or post office, fill “PostalCode” and “RoutingCode”.
- When sending parcel using courier service, fill “Street”, “House”, “Apartment”, “City”, “Country”, “PostalCode”, “Details” and “TimeWindow”. Courier service is currently available only in Estonia.
- When the whole address is sent on “Street” field then house number and/or apartment number are separated into specific fields “House” and “Apartment” if those are empty. When “House” and/or “Apartment” fields are not empty then value of those fields will be added into the database, regardless of the value on “Street” field.

Field NameDescriptionData typeErrors on
Place_id Estonian parcel terminal ID Number Unknown destination
PostalCode Destination postal code String (15)  
RoutingCode Destination routing code String  
Street Destination street String (50)  
House Destination house number String (5)  
Apartment Destination apartment String (50)  
City Destination city String  
Country Destination country String  
Details Extra details about the destination (e.g. third floor) String  
TimeWindow When will recipient be available for courier pick up: 
1 = Any time
2 = 09:00 – 17:00
3 = 17:00 – 21:00
Number; Default 1  

LIMITED QUANTITY (LQ)

This section describes how to forward parcel information about limited quantity items

Field NameDescriptionData typeErrors on
product Product name String  
unnumber UN-number of the dangerous substance Integer  
name Proper shipping name (ADR) String  
class Class number of the dangerous substance String  
labelmode Model number of the labels String  
packinggroup Packing group number assigned to the dangerous substance Enumeration: I, II, III  
transportcategory Transport category to which the substance or article is assigned Enumeration: 0, 1, 2, 3, 4  
value Amount of the dangerous substance in one product item Integer  
unit Unit of the amount value g or ml  
containerweight Weight of an empty container of a single unit (g) Integer  
count Total quantity of items Integer  

XML example of LQ item(s):

…
<lqitems>
	<lqitem>
		<product>String</product>
		<unnumber>Integer</unnumber>
		<name>String</name>
		<class>String</class>
		<labelmodel>String</labelmodel>
		<packinggroup>Enumeration:I,II,III</packinggroup>
		<transportcategory>Enumeration:0,1,2,3,4</transportcategory>
		<amount>
		<value>Integer</value>
		<unit>g or ml</unit>
		</amount>
		<containerweight>Integer</containerweight>
		<count>Integer</count>
	</lqitem>
	<lqitem>
		…
	</lqitem>
	<lqitem>
		…
	</lqitem>
</lqitems>
…

ADDITIONAL SERVICES

Additional services that can be used with SmartPOST

Field NameDescriptionData typeErrors on
Express Express service Boolean Service not available
IdCheck Recipient identity check Boolean Service not available; “IdCode” in recipient data not filled
AgeCheck Recipient age check Boolean Service not available
NotifyEmail Delivery notification (sent to sender) e-mail address String Service not available; Wrong format
NotifyPhone Delivery notification (sent to sender) phone (gsm) number String Service not available
PaidByRecipient Recipient will pay for shipping Boolean Service not available

POST REQUEST

URL: http://iseteenindus.smartpost.ee/api/?request=shipment

Report is an optional field and can have up to 5 email fields inside. When present, a report will be sent to the specified emails. When there are more than 5 email fields the system will still only send out 5 emails and ignore the rest

<orders>
	<authentication>
		<user>string</user>
		<password>string</password>
	</authentication>
	<report>
		<email>string</email>
		<email>…</email>
	</report>
	<item>
		<barcode>string</barcode>
		<reference>string</reference>
		<content>string</content>
		<orderparent>string</orderparent>
		<weight>number</weight>
		<size>number</size>
		<sender>
			<name>string</name>
			<phone>string</phone>
			<email>string</email>
			<cash>number</cash>
			<account>number</account>
		</sender>
		<recipient>
			<name>string</name>
			<phone>string</phone>
			<email>string</email>
			<cash>number</cash>
			<idcode>number</idcode>
		</recipient>
		<destination>
			<place_id>number</place_id>
			<postalcode>string</postalcode>
			<routingcode>number</routingcode>
			<street>string</street>
			<house>string</house>
			<apartment>string</apartment>
			<city>string</city>
			<country>string</country>
			<details>string</details>
			<timewindow>number</timewindow>
		</destination>
		<lqitems>
			<lqitem>
				<product>String</product>
				<unnumber>Integer</unnumber>
				<name>String</name>
				<class>String</class>
				<labelmodel>String</labelmodel>
				<packinggroup>I,II,III</packinggroup>
				<transportcategory>0,1,2,3,4</transportcategory>
				<amount>
					<value>Integer</value>
					<unit>g or ml</unit>
				</amount>
				<containerweight>Integer</containerweight>
				<count>Integer</count>
			</lqitem>
			<lqitem>
				…
			</lqitem>
		</lqitems>
		<additionalservices>
			<express>boolean</express>
			<idcheck>boolean</idcheck>
			<agecheck>boolean</agecheck>
			<notifyemail>string</notifyemail>
			<notifyphone>string</notifyphone>
			<paidbyrecipient>boolean</paidbyrecipient>
		</additionalservices>
	</item>
	<item>
		…
	</item>
</orders>

SUCCESS RESPONSE

If the request is successfully processed, you will be returned the items bar code, reference number associated and sender door code (if sending with door code service is used). In order to receive the door code, the sender data needs to be supplied.

Response status code: 200

<orders>
	<item>
		<barcode>string</barcode>
		<reference>string</reference>
		<sender>
			<doorcode>number</doorcode>
		</sender>
	</item>
	<item>
		…
	</item>
</orders>

ERROR RESPONSE

Failing to fill the mandatory fields (or filling some field with wrong type of data) will result in an error. If the problematic shipment is part of a larger batch, none of the shipments are processed. Returned XML will contain info about the errors.

Response status code: 400

<error>
	<item>
		<barcode>string</barcode>
		<reference>string</reference>
		<error>
			<code>number</code>
			<text>string</text>
			<input>string</input>
		</error>
	</item>
	<item>
		…
	</item>
</error>

Labels

There are several options available (A5, A6, A6/4 per page, A7, A7/8 on page).

GENERAL

Field NameDescriptionData type
Format A5
A6
A6-4
A7
A7-8
String
Barcode Shipment bar codes String

POST REQUEST

URL: http://iseteenindus.smartpost.ee/api/?request=labels

<labels>
	<authentication>
		<user>string</user>
		<password>string</password>
	</authentication>
	<format>String</format>
	<barcode>string</barcode>
	<barcode>…</barcode>
</labels>

Track & Trace

Tracking your shipments movements can be done one by one or in bulk; you can use shipments bar code or reference number to query the tracking info.

POST REQUEST

URL: http://iseteenindus.smartpost.ee/api/?request=tracking

<orders>
	<authentication>
		<user>string</user>
		<password>string</password>
	</authentication>
	<item>
		<barcode>string</barcode>
		<reference>string</reference>
	</item>
	<item>
		…
	</item>
</orders>

RESPONSE

<orders>
	<item>
		<barcode>string</barcode>
		<reference>string</reference>
		<generated>timestamp</generated>
		<doorsize>number</doorsize>
		<sourcein>timestamp</sourcein>
		<sourceout>timestamp</sourceout>
		<termin>timestamp</termin>
		<termout>timestamp</termout>
		<destinationin>timestamp</destinationin>
		<destinationout>timestamp</destinationout>
		<returnin>timestamp</returnin>
		<returnout>timestamp</returnout>
		<returntermin>timestamp</returntermin>
		<returntermout>timestamp</returntermout>
	</item>
	<item>
		…
	</item>
</orders>

Error Codes

000 = destination info missing
001 = required input missing (generic, field name included in )
002 = barcode already exists
003 = not a phone number
004 = not an e-mail address
005 = not numeric
006 = unknown destination (place_id)
007 = express checked but destination is not a express APT
008 = multiple destinations set
009 = courier service timeframe missing
010 = courier service city missing
011 = courier service postal code missing
012 = Courier address missing
013 = COD used but service not available
014 = Invalid door size
015 = String too long (LQ items)
016 = Integer out of bounds (LQ items)
017 = Value not in enum list (LQ items)
018 = Sending with door code service not activated