API Reference

Базовый путь: {host}/api/v1/integration/company, где {host} — https://postomat-api-1.inlog.ai (продакшн) или http://api.test.postomat.inlog.ai (тест).

Авторизация: Authorization: Bearer YOUR_API_KEY во всех запросах, кроме публичных эндпоинтов.

Общие правила:

• Query-параметры передаются строками и приводятся к типам: true/false — boolean, числа — number.
• Массивы в query передаются повторением параметра: ids=A&ids=B.
• Неизвестные параметры и поля тела игнорируются.
• Идентификаторы сущностей — строки в формате cuid2 (например, tz4a98xxat96iws9zmbrgj3a); неверный формат — 400.
• Ошибки: 400 — валидация (code: FST_ERR_VALIDATION), 401 — авторизация. Формат ошибок — Ошибки и ретраи.

Сводка

Метод	Путь	Назначение
POST	/order/create	Создать заявку
GET	/order/list	Список заявок компании
GET	/order/{id}	Заявка по ID
GET	/order/{id}/down-code	Код закладки
GET	/order/{id}/up-code	Код получения
GET	/order/{id}/subtract-code	Код изъятия
GET	/postomat/list	Список постоматов
GET	/postomat/{id}	Постомат по ID
GET	/cell/{postomatId}/free-cells	Свободные ячейки постомата
GET	/country	Страны
GET	/city	Города
GET	/city/{id}	Город по ID
GET	/district/list	Районы
GET	/api/v1/open-api/postomat/list	Публичный список постоматов (без авторизации)
GET	/api/v1/public/postomat/{shortId}	Публичная карточка постомата (без авторизации)
GET	/api/v1/public/postomat/map/{shortId}	Редирект на карту (без авторизации)

Заявки

POST /order/create

Создать заявку. Тело — JSON.

Поле	Тип	Обязательное	Ограничения	По умолчанию	Описание
toUserPhone	string	да	+ и цифры, до 20 символов; пробелы по краям обрезаются	—	Телефон получателя
postomatId	string	да	cuid2	—	ID постомата
sendMessage	boolean	да	—	—	Отправить получателю SMS с кодом получения после закладки
days	integer	нет	≥ 1	из настроек компании	Срок хранения в днях
weight	number	нет	≥ 0	0	Вес
customData	string	нет	—	—	Произвольные данные партнёра
pay	boolean	нет	—	—	Оплатить с баланса компании

Ответ 200 — объект заявки (см. Заявки → Ответ).

Ошибки: 400, 401. Несуществующий postomatId приводит к ошибке сервера.

GET /order/list

Параметр	Тип	Ограничения	По умолчанию	Описание
page	integer	≥ 1	1	Страница
pageSize	integer	≥ 1	10	Размер страницы
status	enum	CREATED, DELIVERED, COMPLETED, SUBTRACTED	—	Фильтр по текущему статусу
withToUser	boolean	—	—	Добавить toUser
withCell	boolean	—	—	Добавить cell (с постоматом)
withPostomat	boolean	—	—	Добавить postomat
withCurrentStatus	boolean	—	—	Добавить currentStatus
withStatuses	boolean	—	—	Добавить statuses
withRent	boolean	—	—	Добавить rent
withPasswords	boolean	—	—	Поле passwords с кодом закладки (DOWN) присутствует всегда

Ответ 200: { total, data: Order[], aggregate, expiredAggregate }. Возвращаются только активные заявки компании, новые первыми.

Ошибки: 400, 401.

GET /order/{id}

Параметр	Где	Тип	Описание
id	path	string (cuid2)	ID заявки
withToUser, withCell, withPostomat, withCurrentStatus, withStatuses, withRent, withPasswords	query	boolean	Как в GET /order/list

Ответ 200 — объект заявки. Ошибки: 400, 401, 404 ORDER_NOT_FOUND (не найдена или принадлежит другой компании).

GET /order/{id}/down-code, /up-code, /subtract-code

Параметр	Где	Тип	Описание
id	path	string (cuid2)	ID заявки

Ответ 200:

Поле	Тип	Описание
id	string	ID кода
type	DOWN | UP | SUBTRACT	Тип: закладка, получение, изъятие
password	string	Код — четыре цифры
orderId	string	ID заявки
createdAt, updatedAt	string (ISO 8601)	Время создания и изменения

Ошибки: 400, 401, 404 ORDER_NOT_FOUND.

Постоматы и ячейки

GET /postomat/list

Параметр	Тип	Ограничения	По умолчанию	Описание
page	integer	≥ 1	—	Страница; пагинация только вместе с pageSize
pageSize	integer	≥ 1	—	Размер страницы
ids	string[]	cuid2	—	Отбор по ID
cityId	string	cuid2	—	Город
districtId	string	cuid2	—	Район
withCity	boolean	—	false	Добавить city
withDistrict	boolean	—	false	Добавить district
latitude	number	—	—	Широта; вместе с longitude включает сортировку по расстоянию
longitude	number	—	—	Долгота
withFreeCells	boolean	—	—	Добавить cells с ячейками без действующей закладки; игнорируется при поиске по координатам

Ответ 200: { total, data: Postomat[] }. Только активные постоматы. Без координат — сортировка по названию; с координатами — по расстоянию, у элементов есть поле distance (км).

Поля постомата: id, incrementalid, title, address, description, imgUrl, lat, lng, schedule, shortId, isActive, isConnected, cityId, districtId, createdAt, updatedAt.

Ошибки: 400, 401.

GET /postomat/{id}

Параметр	Где	Тип	По умолчанию	Описание
id	path	string (cuid2)	—	ID постомата
withCity	query	boolean	false	Добавить city
withCells	query	boolean	false	Добавить cells (каждая с board)
withBoards	query	boolean	false	Добавить boards (каждый с cells)

Ответ 200 — объект постомата или null, если постомат не найден. Ошибки: 400, 401.

GET /cell/{postomatId}/free-cells

Параметр	Где	Тип	Описание
postomatId	path	string (cuid2)	ID постомата

Ответ 200 — массив ячеек: id, title, number, size (S, M, L, XL), isActive, isOpen, forRentAvailable, postomatId, boardId, createdAt, updatedAt. Возвращаются активные ячейки без посылки по действующей заявке. Ошибки: 400, 401.

Справочники

GET /country

Параметр	Тип	По умолчанию	Описание
withCities	boolean	false	Добавить активные города в cities

Ответ 200: { total, data: Country[] } — все активные страны. Поля страны: id, title, isActive, createdAt, updatedAt.

GET /city

Параметр	Тип	Ограничения	По умолчанию	Описание
page	integer	≥ 1	—	Страница; пагинация только вместе с pageSize
pageSize	integer	≥ 1	—	Размер страницы
withCountry	boolean	—	false	Добавить country

Ответ 200: { total, data: City[] } — активные города. Поля города: id, title, isActive, countryId, createdAt, updatedAt.

GET /city/{id}

Параметр	Где	Тип	По умолчанию	Описание
id	path	string (cuid2)	—	ID города
withCountry	query	boolean	false	Добавить country

Ответ 200 — объект города или null, если не найден.

GET /district/list

Параметр	Тип	Ограничения	По умолчанию	Описание
cityId	string	cuid2	—	Районы города
page	integer	≥ 1	—	Страница; пагинация только вместе с pageSize
pageSize	integer	≥ 1	—	Размер страницы

Ответ 200: { total, data: District[] } — активные районы. Поля района: id, title, isActive, cityId, createdAt, updatedAt.

Публичные эндпоинты

Без авторизации. Пути указаны от хоста.

GET /api/v1/open-api/postomat/list

Параметры: page, pageSize, cityId, districtId, withCity, withDistrict, latitude, longitude — с теми же типами и поведением, что у GET /postomat/list. Ответ: { total, data: Postomat[] }.

GET /api/v1/public/postomat/{shortId}

Параметр	Где	Тип	Описание
shortId	path	string, не пустая	Короткий ID постомата

Ответ 200 — объект постомата. Ошибки: 404 POSTOMAT_NOT_FOUND.

GET /api/v1/public/postomat/map/{shortId}

Параметр	Где	Тип	Описание
shortId	path	string, не пустая	Короткий ID постомата

Ответ 302 — редирект на карту 2ГИС с координатами постомата. Ошибки: 404 POSTOMAT_NOT_FOUND — постомат не найден или у него нет координат.