Automatic Data Interchange Tutorial (ENG)

Fetch list of available destinations

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

Field Name	Description	Data 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 Name	Description	Data 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 Name	Description	Data 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 Name	Description	Data type	Errors 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 Name	Description	Data type	Errors 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 Name	Description	Data type	Errors 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 Name	Description	Data type	Errors 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 Name	Description	Data type	Errors 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 Name	Description	Data type
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 Name	Description	Data type	Errors 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 Name	Description	Data 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

Please update your browser

Itella

Fetch list of available destinations

GET REQUEST

RESPONSE

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

GET REQUEST

RESPONSE

Save shipment data

AUTHENTICATION

GENERAL

SENDER

RECIPIENT

DESTINATION

LIMITED QUANTITY (LQ)

ADDITIONAL SERVICES

POST REQUEST

SUCCESS RESPONSE

ERROR RESPONSE

Labels

GENERAL

POST REQUEST

Track & Trace

POST REQUEST

RESPONSE

Error Codes