NAV
cURL

Introduction

Welcome to EatMachine Fridge API! You can use our API to manage and send commands to your fridges.

Register

Contact us at at contact@eatmachine.com to get an account. We will send you a link to configure your sandbox and production accounts.

Environments

Authentication

Authenticate your requests with the API key or get a short-lived API key by login with your email/password.

Authenticate with the API key

curl 'https://api-staging.eatmachine.io/auth/me' \
  -H 'Authorization: Bearer YOUR_API_KEY'

or get a short-lived key and use it the same way

curl -X POST 'https://api-staging.eatmachine.io/auth/login' \
-H 'Content-Type: application/json' \
--data-raw '{
    "username": "restaurateur@example.com",
    "password": "pass1234"
}'

Example response

{
    "token": "SHORT_LIVED_API_KEY"
}

Create a Fleet

A Fleet is a group of fridges.

curl -X POST 'https://api-staging.eatmachine.io/fleets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": "My Fleet"
}'

Example response

{
    "message": "Fleet created",
    "data": {
        "uuid": "c127eb0f-bf0f-4b0a-a5de-bb416aaf2ce1",
        "name": "My Fleet",
        "createdAt": "2022-09-11T21:23:02+02:00",
        "updatedAt": "2022-09-11T21:23:02+02:00"
    }
}

Create a Fridge

Once you have a fleet, you can add a fridge.

curl -X POST 'https://api-staging.eatmachine.io/fridges' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "fleet_id": "c127eb0f-bf0f-4b0a-a5de-bb416aaf2ce1",
    "settings": {
        "temperatureMinAlert": -10,
        "temperatureMaxAlert": 10,
        "webhookUrl": "https://example.com/webhook-fridge-api",
        "kioskUrl": "https://kiosk.example.com",
        "heartbeatInterval": 300
    }
}'

Example response. (Store the uuid for future calls)

{
  "message": "Fridge created.",
  "data": {
    "uuid": "2ae9339e-18a1-4231-8ce1-fd9a57bdd5f3",
    "doorStatus": "closed",
    "temperature": null,
    "lastActivity": "2022-09-27T20:44:57+02:00",
    "settings": {
      "firmwareVersion": null,
      "temperatureMinAlert": -10,
      "temperatureMaxAlert": 10,
      "webhookUrl": "https://example.com/webhook-fridge-api",
      "kioskUrl": "https://kiosk.example.com",
      "heartbeatInterval": 300
    },
    "fleet": {
      "uuid": "43785993-b139-4dad-b55b-e89ee0189606",
      "name": "My Fleet",
      "createdAt": "2022-09-27T20:42:29+02:00",
      "updatedAt": "2022-09-27T20:42:29+02:00"
    },
    "initKey": "633344a9712fb",
    "createdAt": "2022-09-27T20:44:57+02:00",
    "updatedAt": "2022-09-27T20:44:57+02:00"
  }
}

Link your physical fridge

On the fridge screen, input the initKey received at the previous step. It will link it to the API fridge resource.

Post a Command

Post one of the supported command to a fridge. You will receive a webhook notification with the command result. See the next section for the webhook documentation.

Command Description Notifications
reboot Reboot the fridge shutdown, boot
open Unlock the door ack, door-status, inventory
inventory Do a RFID scan ack, inventory
temperature Mesure the temperature ack, temperature
door-status Get the door lock status ack
restart-app Restarts the app and service on fridge ack

command.status can be (null, "ack", "success" or "failed")

for the open command only the status can be (null, "ack", "unlocked", "opened", "closed", "inventory" or "failed")

"reboot" command example

curl -X POST 'https://api-staging.eatmachine.io/fridges/5699613c-0e96-470c-ba56-e520343ebc63/commands/reboot' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY'

Example response. (Store the uuid to match the webhook notification)

{
    "message": "Command created.",
    "data": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Reboot",
            "slug": "reboot"
        },
        "status": null,
        "message": null,
        "createdAt": "2022-09-11T21:39:55+02:00",
        "updatedAt": "2022-09-11T21:39:55+02:00"
    }
}

Webhooks

Notifications are sent on the fridge webhookUrl.

The notification payload contains:

Type Description Payload
heartbeat Regular heartbeat sent by the fridge -
door-status Door lock status read Door status
screen-status Screen status read Screen status
shutdown The fridge is shutting down -
inventory The fridge did a RFID scan EPC list
video A new video of is available for 24h. time limited video URL
temperature Temperature measured Temperature °C
product-linked EPC added for one of your product product and EPC list
badge-presented - -
ack Whenever you send a command, the fridge will acknowledge it -

heartbeat

Sent regularly by the fridge based on the fridge settings heartbeatInterval.

{
    "type": "heartbeat",
    "data": null,
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "lastActivity": "2022-09-11T17:20:10+02:00"
        ...
    }
}

door-status

Sent after a door-status command, open command or after boot.

data.status can be "unlocked", "opened", "closed".

{
    "type": "door-status",
    "data": {
        "status": "unlocked"
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "unlocked"
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Open",
            "slug": "open"
        },
        "status": "success"
        ...
    }
}


inventory

Sent after an inventory command, open command or after boot.

data.epcs is the list of epcs detected in the fridge. data.removed and data.added is the difference between the previous list.

{
    "type": "inventory",
    "data": {
        "epcs": [
            "e28011700000020aa7bcfc24",
            "e28011700000020a7f6964fb",
            "e28011700000020aa7be6cd3"
        ],
        "removed": [
            "e28011700000020aa7be6cd4"
        ],
        "added": []
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "closed",
        "temperature": 5.2,
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Open",
            "slug": "open"
        },
        "status": "success",
        "video": "https://example.com/video.mp4"
        ...
    }
}

video

{
    "type": "video",
    "data":
      {
        "url": "https://video.eatmachine.com/1234-123456-abcd.mp4"
    }
      ,
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "closed",
        "temperature": 5.2,
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Reboot",
            "slug": "reboot"
        },
        "status": "success"
        ...
    }
}



temperature

Sent after a temperature command or after boot.

{
    "type": "temperature",
    "data": {
        "temperature": 5.2
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "closed",
        "temperature": 5.2,
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Temperature",
            "slug": "temperature"
        },
        "status": "success"
        ...
    }
}

product-linked

Sent after an app user scanned some EPCs for one of your products.

{
    "type": "product-linked",
    "data": [
        {
            "code": "e123456abc",
            "expirationDate": "2022-09-11T17:20:10+02:00"
        },
        {
            "code": "e78910def",
            "expirationDate": null
        },
        ...
    ],
    "product": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "name": "Banana"
        ...
    },
}

badge-presented

{
    "type": "badge-presented",
    "data": {
        "badge_token": "1234"
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        ...
    },
    "command": null
}

ack

Sent each time the fridge gets a new command, to acknowledge its receipt.

{
    "type": "ack",
    "data": null,
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "lastActivity": "2022-09-11T17:20:10+02:00"
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Temperature",
            "slug": "temperature"
        },
        "status": "ack"
        ...
    }
}

Typical session

1. Open command

Post an open command and store the response uuid on your side

curl -X POST 'https://api-staging.eatmachine.io/fridges/5699613c-0e96-470c-ba56-e520343ebc63/commands/open' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
    "message": "Command created.",
    "data": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Open",
            "slug": "open"
        },
        "status": null,
        "message": null,
        "createdAt": "2022-09-11T21:39:55+02:00",
        "updatedAt": "2022-09-11T21:39:55+02:00"
    }
}

2. Door unlocked notification

Wait for the door-status notification with the status "unlocked". On your side display to the user the door can be opened.

{
    "type": "door-status",
    "data": {
        "status": "unlocked"
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "unlocked"
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Open",
            "slug": "open"
        },
        "status": "unlocked"
        ...
    }
}

3. Door opened notification

Wait for the door-status notification with the status "opened".

{
    "type": "door-status",
    "data": {
        "status": "opened"
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "opened"
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Open",
            "slug": "open"
        },
        "status": "opened"
        ...
    }
}

4. Door closed notification

Wait for the door-status notification with the status "closed".

{
    "type": "door-status",
    "data": {
        "status": "closed"
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "closed"
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Open",
            "slug": "open"
        },
        "status": "closed"
        ...
    }
}

5. Inventory notification

Wait for the inventory notification. On your side process the EPC list.

{
    "type": "inventory",
    "data": {
        "epcs": [
            "e28011700000020aa7bcfc24",
            "e28011700000020a7f6964fb",
            "e28011700000020aa7be6cd3"
        ],
        "removed": [
            "e28011700000020aa7be6cd4"
        ],
        "added": []
    },
    "fridge": {
        "uuid": "5699613c-0e96-470c-ba56-e520343ebc63",
        "doorStatus": "closed",
        "temperature": 5.2,
        ...
    },
    "command": {
        "uuid": "f8bf3f4a-8799-4dd8-bb36-a197929dc8f1",
        "author": {
            "identifier": "restaurateur@example.com",
            "createdAt": "2022-09-11T17:20:10+02:00",
            "updatedAt": "2022-09-11T17:20:10+02:00"
        },
        "type": {
            "name": "Open",
            "slug": "open"
        },
        "status": "inventory",
        "video": "https://example.com/video.mp4"
        ...
    }
}

6. Update the fridge inventory

Responses format

Responses have a wrapper:

For validation errors, data can contain a map of invalid fields

HTTP 400

{
    "message": "Validation error.",
    "data": {
        "fleet_id": [
            "This field is missing."
        ],
        "foo": [
            "This field was not expected."
        ]
    }
}

Changelog