API Временных окон

Временные окна — сервис для организации работы склада и планирования времени загрузки и разгрузки.

API позволяет связать вашу систему с Временными окнами ATI.SU: управлять складами и площадками, создавать и изменять бронирования, получать расписание, загрузку площадок и историю изменений брони.

Подробнее о сервисе

Вопросы и предложения по поводу API Временных окон присылайте на rnd@ati.su

Используемые термины

Склад — объект с адресом, часовым поясом, контактами и настройками бронирования. Принадлежит фирме — владельцу склада.

Площадка склада — место погрузки или разгрузки, например ворота или рампа. У склада может быть несколько площадок со своими расписаниями. Площадка склада не связана с торговыми Площадками ATI.SU, на которых публикуют грузы.

Бронирование (бронь) — запись о планируемом прибытии машины на склад для погрузки или разгрузки. Содержит даты, время, статус подтверждения и, если назначена, площадку склада. Бронь может существовать самостоятельно или быть связана с точкой заказа.

Точка заказа — место погрузки или разгрузки в маршруте Заказа, связанное со складом. Для создания брони по заказу используется ID этой точки во Временных окнах, а не ID заказа или груза.

Возможности API

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

Грузовладелец и перевозчик могут получать бронирования и точки без брони по заказам, в которых участвуют, а также создавать и изменять доступные им брони. Через список «Мои бронирования» также доступны брони, созданные фирмой на чужих складах.

Доступ определяется фирмой авторизованного пользователя и её отношением к складу или заказу. Владение складом не означает, что все его брони появятся в «Моих бронированиях»: для своего склада используйте метод получения расписания. Подробные условия изменения и подтверждения приведены в описаниях методов.

Методы

• Для работы со складами
• Для работы с площадками погрузки-выгрузки
• Для работы с бронированиями

Быстрый старт: склад → площадка → бронь

Сценарий выполняется от имени одной фирмы — владельца создаваемого склада. Базовый адрес API — https://ati.su.

Для проверки создавайте отдельный склад и удаляйте только его.

Для вызовов вне консоли Panda используйте свой API-токен: Authorization: Bearer <token>. Для JSON-тела нужен Content-Type: application/json. См. авторизацию.

1. Выбрать город

Выполните POST /gw/gis-dict/v1/autocomplete/suggestions:

{ "prefix": "Санкт-Петербург", "suggestion_types": 1, "limit": 5 }

Выберите нужный населённый пункт и сохраните suggestions[].city.id как CITY_ID. Это ID геословаря ATI, не ФИАС, КЛАДР или код региона. Если ID уже известен, проверьте его через POST /gw/gis-dict/v1/cities/by-ids с телом {"ids":[CITY_ID]}. Геословарь.

2. Создать склад

В консоли создания склада выберите пример CreateWarehouse. Выполните POST /gw/timeslots/api/v1/warehouse, заменив city_id: 1 на CITY_ID из шага 1:

{
  "name": "Тест интеграции — отдельный склад",
  "address": "Тестовый адрес",
  "city_id": 1,
  "contacts": [],
  "schedule": [{ "day_of_week": "1", "time_from": "08:00", "time_to": "18:00" }]
}

Сохраните result.warehouse.id как WAREHOUSE_ID, а result.terminals[0].id как TERMINAL_ID. Переданное расписание создаёт площадку автоматически. 1 в day_of_week означает понедельник; время локальное для склада.

3. При необходимости создать ещё одну площадку

Для следующего шага достаточно площадки из шага 2. Если нужна отдельная, выполните POST /gw/timeslots/api/v1/terminal, используя пример CreateTerminal в консоли площадок:

{
  "warehouse": 101,
  "name": "Ворота № 2",
  "schedule": [
    { "day_of_week": "1", "time_from": "08:00:00", "time_to": "18:00:00" }
  ],
  "contacts": []
}

Замените warehouse: 101 на WAREHOUSE_ID. Сохраните result.terminal.id как новый TERMINAL_ID.

Для существующих объектов источники ID — GET /gw/timeslots/api/v1/warehouse (result.warehouses[].id) и GET /gw/timeslots/api/v1/terminal (result.terminals[].id). У площадки проверяйте warehouse == WAREHOUSE_ID и deleted == false. Партнёрские объекты находятся в partners_warehouses и partners_terminals и доступны с учётом прав операции.

4. Создать бронь

Выполните POST /gw/timeslots/api/v1/timeslots, используя пример CreateTimeslot в консоли бронирований:

{
  "timeslot": {
    "warehouse": 101,
    "terminal": 201,
    "approve_status": "await_reaction",
    "action_type": "loading",
    "date_from": "2030-01-07",
    "date_to": "2030-01-07",
    "time_from": "10:00",
    "time_to": "11:00"
  }
}

Замените warehouse: 101 и terminal: 201 на ID из предыдущих ответов. Выберите подходящую будущую дату: в примере 7 января 2030 года — понедельник, соответствующий расписанию из шагов 2 и 3. Сохраните result.timeslot.id как TIMESLOT_ID.

approve_status обязателен. await_reaction означает ожидание подтверждения владельцем склада; успешный HTTP 200 сам по себе не означает подтверждение брони. Пользователь, не владеющий складом, не может самостоятельно указать approved.

5. Прочитать и изменить бронь

Для склада своей фирмы выполните:

GET /gw/timeslots/api/v1/timeslots/schedule?warehouse_id=WAREHOUSE_ID&timeslot_id=TIMESLOT_ID

Подставьте числовые ID. В result.time_slots найдите созданную бронь. GET /timeslots/my предназначен для броней по заказам и броней фирмы на чужих складах; собственная бронь на собственном складе туда не попадает только на основании владения складом.

Не передавайте ненужные фильтры. В частности, одновременные only_timeslots=true и only_order_points_without_slots=true дают пустые списки в /timeslots/my; is_expired=true оставляет только истёкшие брони.

Для изменения используйте пример UpdateTimeslot: передайте id: TIMESLOT_ID, прежние warehouse и terminal, обязательный approve_status и новые значения времени. Если не передать terminal, привязка к площадке снимется. Склад и точку заказа существующей брони менять нельзя. Даты — YYYY-MM-DD, время брони — строго ЧЧ:ММ, без секунд и UTC-суффикса, в локальном времени склада.

При работе с типами груза warehouse_cargo_types принимает UUID типов из справочника склада. Уже назначенные площадкам значения возвращаются в result.terminals[].warehouse_cargo_types[].id у GET /terminal. Это не числовые ID общего словаря грузов и не полный справочник склада. Для минимального сценария поле не требуется.

6. Удалить тестовые данные

Выполните DELETE /gw/timeslots/api/v1/warehouse с JSON-телом, заменив 101 только на созданный на шаге 2 WAREHOUSE_ID:

{ "warehouse_ids": [101] }

Удаление склада также помечает удалёнными его площадки и брони. Проверьте, что result["200"] содержит WAREHOUSE_ID, а result["400"] и result["500"] пусты: HTTP 200 возможен и при частичном отказе. Повторный запрос списка складов не должен содержать тестовый склад в result.warehouses.

Отдельно удалить последнюю площадку склада нельзя. Передача deleted=true при обновлении брони через POST /timeslots не удаляет бронь: это поле игнорируется. Для очистки этого сценария используйте удаление специально созданного склада.