Открыть ячейку

POST /v1/terminals/{code}/cells/{number}/open

Отправляет постамату команду открыть дверцу. Нужен ключ с правом записи.

Ответ приходит раньше, чем открывается дверца. Команда уходит на машину через брокер, машина получает её и отвечает событием — поэтому метод отдаёт 202 Accepted, а не 200. Говорить человеку «открыто» по этому ответу нельзя: он будет стоять перед закрытой дверцей. Что произошло на самом деле, показывает статус команды.

Параметры адреса

Параметр	Тип	Описание
`code`	строка	Код постамата — тот, что указан в договоре и на самой машине
`number`	число	Номер ячейки на фасаде

Тело запроса

Поле	Тип	Обязательное	Ограничения	Описание
`reason`	строка	нет	до 200 знаков	Зачем открыли.
`ttl_seconds`	число	нет	от 10, до 300	Сколько секунд команда действительна.

reason. Сохраняется в журнале команд и в движении товара. Поле не обязательное, но заполнять его стоит: по журналу без причины нельзя понять, была ли это выдача заказа или проверка замков.

ttl_seconds. Верхняя граница не для красоты: команда открытия, доставленная через час, — это открытая дверца в пустом помещении. Больше пяти минут ждать нечего, постамат на связи отвечает за секунды.

Пример запроса

bash

curl -X POST 'https://api.tetrabox.ru/v1/terminals/postamat-01/cells/13/open' \
  -H 'Authorization: Bearer tbx_live_7f3c9a1e2b8d4c5f6a0e9d8c7b6a5f4e3d2c1b0a' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"выдача заказа 4417","ttl_seconds":60}'

Ответ

Ответ 202 Accepted:

json

{
  "command_id": "01JA7F3K9P2QWERTYUIOPASDFG",
  "status": "sent",
  "expires_at": "2026-10-10T09:15:22.000Z"
}

Поля ответа

Поле	Описание
`command_id`	Идентификатор команды. По нему смотрят, что с ней стало
`status`	`sent` — ушла на постамат, `failed` — брокер недоступен
`expires_at`	До какого момента команда действительна

Ошибки

Код	Машинный код	Когда
400	bad_request	тело не прошло проверку: смотрите `detail`
401	unauthorized	ключ не передан, отозван либо неверен
403	insufficient_scope	ключу можно только читать — нужен ключ с правом записи
404	terminal_not_found	постамата нет либо он принадлежит другой компании
404	cell_not_found	ячейки с таким номером нет у этого постамата
409	cell_locked	ячейка заблокирована оператором: в `detail` причина
409	cell_service	ячейка служебная — открывается только нашим оператором
409	terminal_offline	постамат не на связи: в `detail` время последней связи

Формат тела отказа одинаков у всех методов — Коды ошибок.

Почему отказ при «не на связи»

Команда молчащей машине не ставится в очередь и не доставляется позже: открытая дверца в пустом помещении через час — это не «запоздалая выдача», а оставленный без присмотра ящик. Поэтому сервер отвечает 409 сразу, а не делает вид, что команда принята.

Из этого следует правило для вашего приложения: перед открытием проверяйте online у постамата и показывайте человеку состояние машины, а не кнопку, которая отдаст ошибку.

Идемпотентность

Повторный запрос создаёт новую команду: у открытия нет ключа идемпотентности, потому что «открыть ещё раз» — осмысленное действие (дверцу захлопнули, человек не успел). Если вам нужно не допустить двойного открытия, храните command_id у себя и проверяйте его статус, прежде чем слать второй запрос.

Открыть ячейку ​

Параметры адреса ​

Тело запроса ​

Пример запроса ​

Ответ ​

Поля ответа ​

Ошибки ​

Почему отказ при «не на связи» ​

Идемпотентность ​