Introduction
Welcome to the Imprimo API! You can use our API to remotely and automatically interact with IoT orders printers such as TCS-III.
You can view code examples in the dark area to the right.
Workflow example
- The final user of your website order a pizza from restaurant “X”
- Your website knows that restaurant “X” has got the printer ID “abc12345…..” so it will make a HTTP request to imprimo.altercodex.com passing the text of the order and the printer ID on which to print it.
- Imprimo will then ask the printer to print the order and will wait for the restaurant worker to accept or refuse it
- As soon as imprimo knows the response it will make a HTTP request to your website and communicate it.
PHP code examples use GuzzleHttp
You can install it through composer with the following command:
composer require "guzzlehttp/guzzle"
"""
Python code examples use requests
You can install it through PIP with the following command:
pip install requests
"""
Setup
Base URL
The base URL of every API call is
https://imprimo.altercodex.com/api/dev/
Authentication
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: Bearer {api-key}"
<?php
$API_KEY = '{api-key}';
$client = new \GuzzleHttp\Client([
'timeout' => 5, // NEVER FORGET to set a timeout
'base_uri' => 'https://imprimo.altercodex.com/api/dev/',
'headers' => [
'Authorization' => "Bearer $API_KEY"
]
]);
API_KEY = "{api-key}"
client = requests.Session()
client.headers.update({
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json"
})
client.timeout = 5 # NEVER FORGET to set a timeout
Make sure to replace
{api-key}
with your API key.
Imprimo expects for the API key to be included in all API requests to the server in the following header:
Authorization: Bearer {api-key}
Devices
Get list of devices
curl "https://imprimo.altercodex.com/api/dev/devices/"
-H "Authorization: Bearer {api-key}"
<?php
$response = $client->get('devices/');
echo $response->getBody();
response = client.get("https://imprimo.altercodex.com/api/dev/devices/")
print(response.text)
The above code returns JSON structured like this:
{
"success": true,
"devices": {
"next": "uri to get the next *limit* devices",
"count": 2,
"items": [
{
"id": "abc12345",
"status": "idle",
"isOnline": true,
"...": "excetera"
},
{
"id": "abc12346",
"status": "idle",
"isOnline": true,
"...": "excetera"
}
]
}
}
This endpoint retrieves the list of registered devices.
HTTP request
GET /devices/
Query parameters
Parameter | Default | Description |
---|---|---|
limit | 100 | Number of devices to retrieve. Capped at 100. |
offset | 0 | Skip first N devices |
Response
Property | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
success | boolean | If the request succeeded | ||
devices | Object | ✓ | The requested collection of devices. Present if the request succeeded. | |
devices.next | string | Url to get the next limit devices | ||
devices.count | number | Number of retrieved devices | ||
devices.items | Array | Array of Devices |
Get a specific device
curl "https://imprimo.altercodex.com/api/dev/devices/{device-id}"
-H "Authorization Bearer: {api-key}"
<?php
$response = $client->get('devices/{device-id}');
echo $response->getBody();
response = client.get("https://imprimo.altercodex.com/api/dev/devices/{device-id}")
print(response.text)
The above command returns JSON structured like this:
{
"success": true,
"device": {
"id": "abcabc1212334455",
"dateCreated": 1478979511,
"status": "idle",
"statusDate": 1478979511,
"isOnline": true,
"dateLastSeen": 1478979511,
"password": "password",
"phoneNumber": null
}
}
This endpoint retrieves a specific Device.
HTTP request
GET /devices/{device-id}
URL path parameters
Parameter | Description |
---|---|
device-id | The ID of the device to retrieve |
Response
Parameter | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
success | boolean | If the request succeeded | ||
device | Object | ✓ | Device. Present if the request succeeded. |
Device Requests
Submit a request
You can submit requests in any order if you specify the deadline. Requests will be executed in order of deadline: from sooner to later.
Be careful not to set too strict deadlines because network latency, printing times and the time it takes to the restaurant worker to evaluate the order must be taken in account.
curl
-X POST
"https://imprimo.altercodex.com/api/dev/devices/{device-id}/requests/"
-d '{"data":"Text to print"}'
-H "Content-type: application/json"
-H "Authorization: Bearer {api-key}"
<?php
$response = $client->post('devices/{device-id}/requests/', ['json' => [
'data' => 'Text to print'
]]);
echo $response->getBody();
response = client.post("https://imprimo.altercodex.com/api/dev/devices/{device-id}/requests/", json = {
"data": "Text to print"
})
print(response.text)
The above command returns JSON structured like this:
{
"success": true,
"request": {
"id": "xyz001",
"...": "excetera.. See Models / Request"
}
}
HTTP request
POST /devices/{device-id}/requests/
URL path parameters
Parameter | Description |
---|---|
device-id | The ID of the device |
Request body (in JSON format)
Parameter | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
command | string | ✓ | Defaults to “print-text”. | |
data | string | ? | ? | Depends on the command |
deadline | number | ✓ | Unix date format. Any request which cannot be fulfilled before this date, will be canceled. Defaults to 5 minutes from the date of creation of the request. | |
reserved | string | ✓ | ✓ | 60 ASCII characters max. Reserved data for your personal use. |
Response
Parameter | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
success | boolean | If the request succeeded | ||
request | Object | ✓ | Request. Present if the request succeeded. |
Get list of printing requests for the given printer
curl "https://imprimo.altercodex.com/api/dev/devices/{device-id}/requests/"
-H "Authorization: Bearer {api-key}"
<?php
$response = $client->get('devices/{device-id}/requests/');
echo $response->getBody();
response = client.get("https://imprimo.altercodex.com/api/dev/devices/{device-id}/requests/")
print(response.text)
The above command returns JSON structured like this:
{
"success": true,
"requests": {
"next": "uri to get the next *limit* requests",
"count": 2,
"items": [
{
"id": "xyz001",
"...": "excetera"
},
{
"id": "xyz002",
"...": "excetera"
}
]
}
}
HTTP request
GET /devices/{device-id}/requests/
URL path parameters
Parameter | Description |
---|---|
device-id | The ID of the request |
Query parameters
Parameter | Default | Description |
---|---|---|
limit | 100 | Number of requests to retrieve. Capped at 100. |
offset | 0 | Skip first N requests |
Response
Property | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
success | boolean | If the request succeeded | ||
requests | Object | ✓ | The requested collection of requests. Present if the request succeeded. | |
requests.next | string | Url to get the next limit requests | ||
requests.count | number | Number of retrieved requests | ||
requests.items | Array | Array of Requests |
Get status of a printer request
curl "https://imprimo.altercodex.com/api/dev/devices/{device-id}/requests/{request-id}"
-H "Authorization: Bearer {api-key}"
<?php
$response = $client->get('devices/{device-id}/requests/{request-id}');
echo $response->getBody();
response = client.get("https://imprimo.altercodex.com/api/dev/devices/{device-id}/requests/{request-id}")
print(response.text)
The above command returns JSON structured like this:
{
"success": true,
"request": {
"id": "xyz001",
"...": "excetera"
}
}
HTTP request
GET /devices/{device-id}/requests/{request-id}
URL path parameters
Parameter | Description |
---|---|
device-id | The ID of the device |
request-id | The ID of the request |
Response
Property | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
success | boolean | If the request succeeded | ||
request | Object | ✓ | The request. Present if the request succeeded. |
Automatic Reports
To receive automatic reports (also called callbacks or webhooks in some cases) you must supply us with a URL of your choice.
Reports will be transmitted to your URL via a HTTP POST.
Example report:
{
"devices": [
{
"id": "device1...",
"status": "idle",
"...": "excetera. See Models / Device"
},
{
"id": "device2...",
"status": "out-of-paper",
"...": "excetera"
}
],
"requests": [
{
"id": "aabbcc...",
"output": {
"data": {
"accepted": true,
"time": 10
}
},
"...": "excetera. See Models / Device Request"
}
]
}
Property | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
devices | Array | ✓ | Array of Devices. Present and not null when Imprimo wants to notify you about the status of 1 or more devices. | |
requests | Array | ✓ | Array of Requests. Present and not null when Imprimo wants to notify you about the status of 1 or more requests. |
Each device request object will show an additional property:
Property | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
deviceId | string | Id of the device |
Models
Device
{
"id": "{device-id}",
"dateCreated": 1478979500,
"status": "{status-code}",
"statusDate": 1478979500,
"isOnline": true,
"dateLastSeen": 1478979500,
"password": "password",
"phoneNumber": null
}
Properties
Property | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
id | string | The ID of the device (16 bytes ASCII) | ||
dateCreated | number | Unix date format | ||
status | string | ✓ | Status of the device. Can be null if unknown | |
statusDate | number | ✓ | Updated everytime the status changes | |
isOnline | boolean | Whether the device connection is alive | ||
dateLastSeen | number | ✓ | Updated everytime there’s communication with the device | |
password | string | ✓ | ✓ | The device may have a password system |
phoneNumber | string | ✓ | ✓ | The device may have a SIM card with a phone number |
Status codes
Name | Description |
---|---|
unknown | Unknown status |
out-of-paper | The device is out of paper and cannot print anymore |
idle | The device is idle, waiting for orders to print |
printing | |
waiting-order-response | Waiting for the restaurant worker to accept or refuse the order |
Device Request
{
"id": "90021daaa90f11e6956760e327002198",
"dateCreated": 1478979498,
"deadline": 1478979898,
"reserved": null,
"process": {
"status": "archived",
"statusDate": 1478979511
},
"input": {
"command": "print",
"data": "This is a printer Test\nQuesta è una prova di stampa\nEsta es una prueba de impresion\n",
"dateSent": 1478979500
},
"output": {
"data":{
"accepted": true,
"time": 15
},
"dateReceived": 1478979511
},
"error": null,
"report": {
"enabled": true,
"attemps": 0,
"status": "queueing",
"statusDate": 1478979511,
"error": null
}
}
Properties
Property | Type | Optional | Null-able | Description and notes |
---|---|---|---|---|
id | string | The ID of the device (32 bytes) | ||
dateCreated | number | Unix date format | ||
deadline | number | Unix date format. Any request which cannot be fulfilled before this date, will be canceled. | ||
reserved | string | ✓ | ✓ | Specified by the client and reserved for its personal use |
process.status | string | Current processing status | ||
process.statusDate | number | Updated when the status changes | ||
input.command | string | Request command | ||
input.data | depends on the command | ✓ | ||
input.dateSent | number | ✓ | ✓ | Present and not null when the input is sent to the printer |
output.data | depends on the command | ✓ | ||
output.dateReceived | number | ✓ | ✓ | Present and not null when the printer output is received |
error | Object | ✓ | ✓ | Present and not null when there’s a error |
error.processStatus | string | status of the process at the time the error happened | ||
error.code | string | |||
error.message | string | ✓ | ✓ | Additional information about the error |
error.dateCreated | number | Unix date format | ||
report.enabled | boolean | Whether the report is enabled | ||
report.attemps | number | Number of times the report is attempted | ||
report.status | string | |||
report.statusDate | number | Updated when the status changes | ||
report.error | Object | ✓ | ✓ | Present and not null when there’s a error in the report process |
report.error.code | string | |||
report.error.message | string | ✓ | ✓ | Additional information about the error |
report.error.dateCreated | number | Unix date format |
Process status codes
Name | Description |
---|---|
queueing | Probably the majority of devices cannot process more than one request at a time |
sending-input | |
waiting-ack | Waiting for the device acknowledgement of the input |
waiting-output | Waiting for the device output |
archived | Means the request is completed and no further processing is needed |
Report status codes
Name | Description |
---|---|
queueing | Callback scheduled |
sending | |
archived | Callback process finished |
Error codes
Name | Description |
---|---|
unknown | |
network-timeout | |
incompatible-device-state | E.g. if trying to print a order when the device is out of paper |
invalid-url | Invalid url (happens with invalid reportUrls) |
max-retries | Maximum number of retries exceeded |
deadline | The request was not completed before its deadline |
Errors
Errors are marked with a HTTP status code greater or equal to 400.
Example error:
{
"success": false,
"error": "error description"
}