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

sandbox: https://api-staging.eatmachine.io
prod: https://api.eatmachine.io

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:

the type of notification
the fridge
the associated command if any
additional data based on the type of notification

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:

message: human-readable message
data: either an object for single resource or an array for a resource collection

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

2022-09-30 propriété fridge.doorOpened (true, false) remplacée par fridge.doorStatus ('unlocked', 'opened', 'closed'). 'unlocked' signifie que la porte peut être ouverte.
2022-10-05 définition de command.status: (null, "ack", "success", "failed") pour toute les commandes sauf la commande open ou le status sera (null, "ack", "unlocked", "opened", "closed", "inventory", "failed")