# Temperatures

> Fridge and cooking temperatures, taken by a person or reported by a sensor. Three collections, and what tells them apart.

Source: https://developers.backresto.com/en/docs/temperatures

Temperature is the measurement a food-safety inspection turns on, and the app
records it three ways. They look alike and mean different things, so the
distinction is worth getting right before you build on any of them.

| Collection | Scope | Who took the measurement |
| --- | --- | --- |
| `temperature-records` | `temperature-records:read` | A person, on a fridge or freezer, during a named shift. |
| `temperature-readings` | `temperature-readings:read` | A [sensor](https://developers.backresto.com/en/docs/facilities), on its own, unattended. |
| `cooking-temperature-records` | `cooking-temperature-records:read` | A person, on a cooking unit: an oven, a holding cabinet. |

All three share the [snapshot envelope](https://developers.backresto.com/en/docs/collections): `id`, `deleted`,
`capturedAt`, `receivedAt`, `sequence` and the rest sit beside the `data`
described below.

## `temperature-records`

A manual check on a piece of cold-chain equipment. One record per reading, per
piece of equipment, per shift.

| Field | Type | Meaning |
| --- | --- | --- |
| `timestamp` | string, **required** | When the reading was taken, epoch milliseconds as a string. |
| `value` | number, **required** | The temperature itself. |
| `unit` | string, **required** | `CELSIUS` in every record we have seen. Read it rather than assuming. |
| `shift` | string, **required** | The service it belongs to: `MORNING`, `EVENING`. Upper case. |
| `equipmentId` | string, **required** | The [equipment](https://developers.backresto.com/en/docs/facilities) measured. |
| `correctiveActions` | string[] | What was done when the reading was out of range. Empty when nothing was needed. |
| `userId` | string \| null | The staff member who took it, when the app recorded one. |

```json
{
  "id": "48a30f0b-ccc0-4d18-8404-525b16ecaaa6",
  "collection": "temperature-records",
  "deleted": false,
  "capturedAt": "1789772570338",
  "receivedAt": "1789772802108",
  "sequence": "1",
  "data": {
    "timestamp": "1789768800000",
    "value": -14.4,
    "unit": "CELSIUS",
    "shift": "MORNING",
    "equipmentId": "84ce5c13-3237-40d4-901a-cbba59a6406f",
    "userId": "2774953d-8d9b-4a68-8ec4-1209edd90777"
  }
}
```

**`value` is a reading, not a verdict.** Nothing in the record says whether it
was acceptable: that depends on the `min` and `max` on the
[equipment](https://developers.backresto.com/en/docs/facilities), which you have to read separately and which the
restaurant can change. A record taken at -14.4 °C is a problem in a fridge and
normal in a freezer.

**`correctiveActions` is free text**, typed during service in the language of
the restaurant. Count it if you like; do not build an enum from it.

## `temperature-readings`

The same measurement, reported by a wireless probe rather than a person. Same
shape minus the two fields that only make sense when a human was involved:
there is no `shift` and no `userId`.

| Field | Type | Meaning |
| --- | --- | --- |
| `timestamp` | string, **required** | When the sensor reported, epoch milliseconds as a string. |
| `value` | number, **required** | The temperature. |
| `unit` | string, **required** | As above. |
| `equipmentId` | string, **required** | The equipment the sensor watches. |
| `correctiveActions` | string[] | Filled in afterwards, by a person, when an alert was acted on. |

These arrive on the sensor's own schedule, so a busy restaurant produces far
more of these than of manual records. Plan your polling for the volume rather
than for the headcount.

Which sensor reported is not on the reading. The link lives on the
[`sensors`](https://developers.backresto.com/en/docs/facilities) collection, whose `sensorEquipmentId` points back
at the equipment. Mind the name: it is not `equipmentId`.

## `cooking-temperature-records`

A person measuring a cooking unit rather than a cold one. Identical to
`temperature-records` except that it points at
[cooking equipment](https://developers.backresto.com/en/docs/facilities).

| Field | Type | Meaning |
| --- | --- | --- |
| `timestamp` | string, **required** | When the reading was taken. |
| `value` | number, **required** | The temperature. |
| `unit` | string, **required** | As above. |
| `shift` | string, **required** | The service it belongs to. |
| `cookingEquipmentId` | string, **required** | The cooking unit measured, **not** `equipmentId`. |
| `correctiveActions` | string[] | What was done about an out-of-range reading. |
| `userId` | string \| null | Who took it. |

The field name is the one difference that bites: a client that reads
`equipmentId` here gets `undefined`, silently, and a chart with no equipment on
it.

## Reading all three together

A dashboard that answers "was this fridge in range today" wants
`temperature-records` and `temperature-readings` merged on `equipmentId`, with
the thresholds from `equipment`. Three walks, joined on your side. There is no
endpoint that does it for you.

Two things to build in from the start:

- **Report on `capturedAt`, sync on `receivedAt`.** A tablet in a cold room uploads
  when it finds signal, so the record of a 09:00 reading can arrive at 14:00.
  [The envelope page](https://developers.backresto.com/en/docs/collections) has the full story.
- **Absence proves nothing.** A missing reading may mean the check was skipped,
  or that the device has not uploaded it yet. Do not print a completion rate
  from this API and call it compliance. See [the caveat](https://developers.backresto.com/en/docs/support).