Please update your browser

It looks like your browser isn't supported any more. Please update your browser to get secure and more responsive browsing experience.


Please use one of these browsers:

ItellaItella

Automatic Data Interchange Tutorial (ENG)

Info & help
Automatic Data Interchange Tutorial (ENG)
Category: Tutorials

Fetch list of available destinations

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

Field NameDescriptionData type
CountryCountry Code (EE or FI)String
TypeDestination Type:
APT = parcel terminal (default)
PO = post office
String
FilterAdditional 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_IdParcel terminal ID – Use for EE destinations only!Number
NameDestination nameString
CityDestination cityString
AddressDestination addressString
CountryDestination country codeString
PostalCodeDestination postal codeString
RoutingCodeDestination routing codeString
AvailabilityTime frame when location is openString
DescriptionA short description of the locationString
LatLatitudeNumber
LngLongitudeNumber
<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_IdParcel terminal IDNumber
DayDay 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
UserUser nameStringUnknown user
PasswordUser passwordStringUser 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
BarcodeShipments bar codeStringDuplicate; Wrong format
ReferenceCustomers reference numberString 
ContentShipment contentString 
OrderParentBarcode of parent order (in case of multipleparcel shipment)StringUnknown bar code (parent order needs to be created before children)
WeightWeight of the shipmentNumberUnknown user
SizeLocker size (numbers 5-8 or 11)
11 – XS size
5 – S size
6 – M size
7 – L size
8 – XL size
NumberUnknown size

SENDER

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

Field NameDescriptionData typeErrors on
NameSenders nameString 
PhoneSenders phone numberString 
EmailSenders e-mail addressStringWrong format
CashAmount of money the sender has to pay before sending the parcelNumberWrong format
AccountBusiness customer’s account identificatorNumber 

RECIPIENT

Info related to the recipient.

Field NameDescriptionData typeErrors on
NameRecipients nameString 
PhoneRecipients phone numberString 
EmailRecipients e-mail addressStringWrong format
CashAmount of money the recipient has to pay before receiving the parcelNumberService not available; Wrong format
IdCodeID code of the recipient; needed if ID validation is required.NumberWrong 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_idEstonian parcel terminal IDNumberUnknown destination
PostalCodeDestination postal codeString (15) 
RoutingCodeDestination routing codeString 
StreetDestination streetString (50) 
HouseDestination house numberString (5) 
ApartmentDestination apartmentString (50) 
CityDestination cityString 
CountryDestination countryString 
DetailsExtra details about the destination (e.g. third floor)String 
TimeWindowWhen 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
productProduct nameString 
unnumberUN-number of the dangerous substanceInteger 
nameProper shipping name (ADR)String 
classClass number of the dangerous substanceString 
labelmodeModel number of the labelsString 
packinggroupPacking group number assigned to the dangerous substanceEnumeration: I, II, III 
transportcategoryTransport category to which the substance or article is assignedEnumeration: 0, 1, 2, 3, 4 
valueAmount of the dangerous substance in one product itemInteger 
unitUnit of the amount valueg or ml 
containerweightWeight of an empty container of a single unit (g)Integer 
countTotal quantity of itemsInteger 

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
ExpressExpress serviceBooleanService not available
IdCheckRecipient identity checkBooleanService not available; “IdCode” in recipient data not filled
AgeCheckRecipient age checkBooleanService not available
NotifyEmailDelivery notification (sent to sender) e-mail addressStringService not available; Wrong format
NotifyPhoneDelivery notification (sent to sender) phone (gsm) numberStringService not available
PaidByRecipientRecipient will pay for shippingBooleanService 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
FormatA5
A6
A6-4
A7
A7-8
String
BarcodeShipment bar codesString

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