Статус команды

GET /v1/commands/{id}

Что стало с командой, отправленной на постамат. Второй шаг после открытия ячейки.

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

Параметр	Тип	Описание
id	строка	Идентификатор команды из ответа на открытие

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

curl -X GET 'https://api.tetrabox.ru/v1/commands/01JA7F3K9P2QWERTYUIOPASDFG' \
  -H 'Authorization: Bearer tbx_live_7f3c9a1e2b8d4c5f6a0e9d8c7b6a5f4e3d2c1b0a'

Ответ

{
  "id": "01JA7F3K9P2QWERTYUIOPASDFG",
  "type": "open_cell",
  "terminal": "postamat-01",
  "cell": 13,
  "status": "acked",
  "ttl_seconds": 60,
  "created_at": "2026-10-10T09:14:22.000Z",
  "sent_at": "2026-10-10T09:14:22.000Z",
  "acked_at": "2026-10-10T09:14:24.000Z",
  "failed_at": null,
  "expires_at": "2026-10-10T09:15:22.000Z",
  "error": null
}

Поля ответа

Поле	Описание
status	См. таблицу ниже
acked_at	Когда постамат подтвердил выполнение
error	Текст отказа, если он был

Ошибки

Код	Машинный код	Когда
401	unauthorized	ключ не передан, отозван либо неверен
404	command_not_found	команды нет либо она принадлежит другой компании

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

Значения status

Значение	Что означает
pending	команда создана, но ещё не ушла в брокер
sent	ушла на постамат, ответа пока нет
acked	постамат подтвердил: дверца открылась
failed	постамат ответил отказом, причина в error
expired	постамат не ответил за ttl_seconds

expired ставит сервер сам, сторожем: «отправлено» не висит вечно, и по статусу всегда видно, чем дело кончилось.

Как опрашивать

Дверца открывается за секунду-две. Разумный порядок: подождать секунду и спросить статус, затем ещё раз через две. Пять опросов с интервалом в секунду закрывают любой нормальный случай; если за это время статус остался sent, дальше ждать смысла мало — смотрите expires_at.

Частить не нужно: на чтение действует ограничение в 600 запросов в минуту на ключ.