NAV
shell php python

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

  1. The final user of your website order a pizza from restaurant “X”
  2. 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.
  3. Imprimo will then ask the printer to print the order and will wait for the restaurant worker to accept or refuse it
  4. 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"
}
shell php python