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

Пути указаны относительно {host}/api/v1/integration/company, запросы требуют Authorization: Bearer YOUR_API_KEY. Публичные эндпоинты без авторизации описаны в конце страницы.

Список постоматов

GET /postomat/list

Возвращает только активные постоматы.

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

Поиск по координатам

Если переданы и latitude, и longitude (оба отличны от нуля), постоматы сортируются по расстоянию до точки — ближайшие первыми, а у каждого постомата появляется поле distance — расстояние в километрах. Без координат список сортируется по названию.

curl

curl "https://postomat-api-1.inlog.ai/api/v1/integration/company/postomat/list?latitude=42.8746&longitude=74.5698&page=1&pageSize=5&withCity=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const nearest = await client.postomats.list({
  latitude: 42.8746,
  longitude: 74.5698,
  page: 1,
  pageSize: 5,
  withCity: true,
})
nearest.data.forEach((p) => console.log(p.title, p.distance))

Java

PageResponse<JsonNode> nearest = client.postomats().list(
    GetPostomatListQuery.builder()
        .latitude(42.8746)
        .longitude(74.5698)
        .page(1)
        .pageSize(5)
        .withCity(true)
        .build()
);
for (JsonNode p : nearest.getResults()) {
    System.out.println(p.get("title").asText() + " " + p.get("distance").asDouble());
}

Ответ

{
  "total": 2,
  "data": [
    {
      "id": "tz4a98xxat96iws9zmbrgj3a",
      "incrementalid": 12,
      "title": "Постомат №1",
      "address": "ул. Примерная, 1",
      "description": "Вход со двора",
      "lat": 42.8751,
      "lng": 74.5702,
      "schedule": null,
      "shortId": "a1b2c3",
      "isConnected": true,
      "cityId": "pfh0haxfpzowht3oi213cqos",
      "districtId": "c9m2k1z0q8w7e6r5t4y3u2i1",
      "distance": 0.07,
      "city": { "id": "pfh0haxfpzowht3oi213cqos", "title": "Бишкек" }
    }
  ]
}

Поле	Описание
id	ID постомата — используйте в postomatId при создании заявки
incrementalid	Порядковый номер постомата
title, address, description	Название, адрес и описание
lat, lng	Координаты
schedule	Режим работы (произвольная структура или null)
shortId	Короткий идентификатор для публичных ссылок
isConnected	Постомат на связи с сервером InLog
cityId, districtId	Город и район
distance	Расстояние в км — только в режиме поиска по координатам

Карточка постомата

GET /postomat/{id}

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

Если постомат с таким ID не найден, API возвращает 200 с телом null — проверяйте ответ на null.

curl

curl "https://postomat-api-1.inlog.ai/api/v1/integration/company/postomat/tz4a98xxat96iws9zmbrgj3a?withCity=true&withCells=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const postomat = await client.postomats.getById('tz4a98xxat96iws9zmbrgj3a', { withCity: true, withCells: true })
if (!postomat) throw new Error('Постомат не найден')

Java

JsonNode postomat = client.postomats().getById(
    "tz4a98xxat96iws9zmbrgj3a",
    GetPostomatByIdQuery.builder().withCity(true).withCells(true).build()
);
if (postomat == null || postomat.isNull()) {
    throw new IllegalStateException("Постомат не найден");
}

Свободные ячейки

GET /cell/{postomatId}/free-cells

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

curl

curl "https://postomat-api-1.inlog.ai/api/v1/integration/company/cell/tz4a98xxat96iws9zmbrgj3a/free-cells" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const cells = await client.cells.getFreeCells('tz4a98xxat96iws9zmbrgj3a')
const hasLarge = cells.some((c) => c.size === 'L' || c.size === 'XL')

Java

import ai.inlog.sdk.postomat.model.Cell;
import ai.inlog.sdk.postomat.model.CellSize;
import java.util.List;

List<Cell> cells = client.cells().getFreeCells("tz4a98xxat96iws9zmbrgj3a");
boolean hasLarge = cells.stream().anyMatch(c -> c.getSize() == CellSize.L || c.getSize() == CellSize.XL);

Поле ячейки	Тип	Описание
id	string	ID ячейки
title	string	Название
number	integer	Номер ячейки
size	S | M | L | XL	Размер
isActive	boolean	Ячейка активна
isOpen	boolean	Дверца открыта
forRentAvailable	boolean	Ячейка доступна для аренды
postomatId	string	ID постомата
boardId	string	ID блока ячеек

Для чего нужен список

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

Публичные эндпоинты без авторизации

Без авторизации

Эти эндпоинты не требуют токена и не относятся к интеграционному API компании. Их пути начинаются сразу от {host}/api/v1. Используйте их для публичных сценариев — например, для карты постоматов на вашем сайте.

Список постоматов

GET {host}/api/v1/open-api/postomat/list

Параметры и ответ такие же, как у GET /postomat/list, кроме ids и withFreeCells — эти параметры здесь не поддерживаются: page, pageSize, cityId, districtId, withCity, withDistrict, latitude, longitude.

curl "https://postomat-api-1.inlog.ai/api/v1/open-api/postomat/list?withCity=true"

Постомат по короткому ID

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

Возвращает постомат по shortId. Если постомат не найден — 404 с кодом POSTOMAT_NOT_FOUND.

curl "https://postomat-api-1.inlog.ai/api/v1/public/postomat/a1b2c3"

Переход на карту

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

Отвечает редиректом 302 на карту 2ГИС с координатами постомата. Если постомат не найден или у него нет координат — 404 с кодом POSTOMAT_NOT_FOUND. Удобно для ссылки «Показать на карте».