Начало работы

Что это такое

TetraBox — сеть постаматов для помещений: офисы, склады, бизнес-центры, жилые комплексы. API даёт вашему приложению делать то же, что делает наша админка: смотреть состояние машин и открывать ячейки.

Адрес: https://api.tetrabox.ru

Версия в пути — /v1/. Она видна в вашем коде и в журнале, а не спрятана в заголовке, который легко забыть.

Как получить ключ

Ключ выдаём мы, на вашу компанию. Напишите на info@tetrabox.ru и укажите:

• название компании и постаматы, с которыми работаете;
• что должно делать приложение — только смотреть или ещё и открывать ячейки;
• для чего интеграция: портал сотрудников, учётная система, доставка.

В ответ придёт строка вида tbx_live_…. Она показывается один раз. У нас хранится только её отпечаток, восстановить ключ нельзя — потеряли, выдадим новый, старый отзовём.

Ключ — это пароль

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

Первый запрос

curl 'https://api.tetrabox.ru/v1/terminals' \
  -H 'Authorization: Bearer tbx_live_ваш_ключ'

В ответ придёт список ваших машин:

{
  "terminals": [
    {
      "code": "postamat-01",
      "title": "Склад на Примерной",
      "online": true,
      "facade": { "cabinets": 4, "rows": 6 },
      "cells_total": 24
    }
  ]
}

Увидели свои постаматы — ключ работает, можно писать интеграцию.

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

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

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

Дверца в этот момент ещё не открылась. Ответ говорит, что команда ушла на машину. Через секунду спросите статус команды: acked означает, что замок сработал.

Это главная вещь, которую стоит понять до начала работы, — подробнее в разделе Как это устроено.

Попробовать без кода

На https://api.tetrabox.ru/v1/openapi живёт интерактивная песочница: нажмите «Authorize», вставьте ключ — и запросы на чтение можно выполнять прямо в браузере, не написав ни строки.

Открытие ячейки оттуда не выполняется намеренно: это физическое действие, и кнопка рядом с описанием слишком легко нажимается. Для него возьмите готовый curl со страницы метода.

Машинное описание для генератора клиентов — https://api.tetrabox.ru/v1/openapi.json (OpenAPI 3.0). Из него openapi-generator соберёт клиента под ваш язык, и обёртки писать руками не придётся.

Что дальше

• Как это устроено — компания, права ключа, частота запросов
• Коды ошибок — единый формат отказов
• Методы — все пять с примерами
• Что будет дальше — люди, пропуска, вебхуки