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 | |
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 | |
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 | Errors 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 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