Что будет дальше

Состав API определён целиком, а реализован пока частично. Эта страница показывает, что уже работает и что появится, — чтобы вы могли оценить, закроет ли API ваш сценарий, и спланировать свою часть работы.

Сроки называем по запросу: очерёдность зависит от того, что нужно подключающимся. Напишите, чего не хватает именно вам, — info@tetrabox.ru.

Готово

Что	Методы
Постаматы и ячейки	список, карточка, ячейки
Открытие ячеек	открыть, статус команды
Ключи, права, журнал обращений	выдаются на компанию, два уровня

В работе

Люди, права и пропуска

Ведение людей у постамата из вашей системы: завести человека, выдать удостоверение, дать доступ к ячейке.

GET    /v1/people
POST   /v1/people
GET    /v1/people/{id}/credentials
POST   /v1/people/{id}/credentials
GET    /v1/people/{id}/access
POST   /v1/people/{id}/access
GET    /v1/people/{id}/pass

Последний метод — тот самый «показать QR и штрихкод в приложении». Он отдаёт готовые картинки в SVG и значение кода:

{
  "name": "Иванов Иван Иванович",
  "code": "101234567890123456",
  "qr_svg": "<svg …>",
  "barcode_svg": "<svg …>",
  "cells": [{ "terminal": "postamat-01", "number": 13 }]
}

Рисовать штрихкод самостоятельно не нужно: формат кода и генератор Code 128 уже написаны у нас, и две реализации одного формата однажды разошлись бы.

Право открыть ячейку двухчастное

Удостоверение (PersonCredential) отвечает «кто это», доступ (CellAccess) — «куда ему можно». Это не усложнение: доступ к одной ячейке может быть у нескольких человек, а одному человеку доступно несколько ячеек. Свести их в одно поле значило бы держать одно право в двух местах.

Журнал событий

Что происходило на машине: открыли, закрыли, положили, забрали.

GET /v1/events?since=2026-10-10T09:00:00Z&terminal=postamat-01

Листание по времени, а не по номеру страницы: журнал растёт во время чтения, и offset на нём пропускал бы записи. В ответе приходит next_since — подставляете его в следующий запрос.

Уведомления вебхуками

Чтобы не опрашивать журнал, мы сами дёрнем ваш адрес:

POST /v1/webhooks   { "url": "https://ваш-сервер/hook", "events": ["cell.opened"] }

Событие	Когда
cell.opened	замок сработал
cell.open_failed	замок не ответил либо дверца не двинулась
cell.closed	дверцу закрыли
parcel.placed	сработал датчик занятости
parcel.taken	ячейка опустела
stock.moved	положили или забрали товар
terminal.online / terminal.offline	машина вышла на связь или замолчала
alarm.raised	сбой контроллера, вскрытие

Каждый вызов подписывается HMAC-SHA256 — заголовок X-TetraBox-Signature. Проверяйте подпись: без неё всякий, кто узнал адрес вашего вебхука, сможет присылать вам «ячейку открыли».

При недоступности вашего сервера — пять попыток с нарастающей задержкой (10 с, 1 мин, 5 мин, 30 мин, 2 ч). Вебхук не единственный источник правды: сеть теряет пакеты, серверы уходят на обслуживание, поэтому учёт стройте на журнале, а вебхук считайте ускорением.

Товары и остаток

GET   /v1/products
POST  /v1/products/{id}/place
POST  /v1/products/{id}/withdraw
GET   /v1/moves

Остаток считается поштучно: каждый пик штрихкода у открытой ячейки — одна штука. Если человек забрал больше, чем числилось, движение помечается matched: false, а не отбрасывается: коробка уже в руках, и расхождение должно быть видно в вашей системе.

Разовые коды выдачи

Код на одну посылку, не привязанный к человеку, — для сценария доставки.

POST   /v1/cells/{id}/pickup-code
DELETE /v1/cells/{id}/pickup-code

Чего в API не будет

Не по срокам, а принципиально — чтобы вы не закладывались на это в своей архитектуре.

Чего нет	Почему
Перезагрузка и обновление машины	Кнопка перезагрузки в чужом приложении кладёт постамат до приезда человека
Адреса плат, портов и каналов	Это устройство конкретной машины; в сервере их нет вовсе
Создание администраторов нашей админки	Кто имеет доступ к машинам компании, решает оператор сети
Прямое подключение к брокеру MQTT	Туда пускают только сами постаматы по сертификатам
События ввода кода у машины	Отпечаток чужого удостоверения вам бесполезен, а подбору помогает
Доступ к данным других компаний	Ключ привязан к компании, и выборки идут по ней