Підключення системи бронювання до ERP, WMS або застосунку прохідної не обов’язково має починатися як великий інтеграційний проєкт. Для практичного сценарію в’їзду достатньо чотирьох API-викликів: отримати Bearer-токен, знайти бронювання за його номером, зафіксувати прибуття, а згодом — виїзд.

Працівнику служби охорони не потрібно знати внутрішній ідентифікатор бронювання в Time Slot Control. Він працює зі значенням, яке водій уже має в підтвердженні або QR-коді: ReservationNumber. TSC повертає відповідний запис та його ідентифікатор Id через OData; той самий ідентифікатор Id потім використовується для зміни статусу.

OData та API: дві частини одного інтерфейсу

Time Slot Control поєднує стандарт OData v4 зі звичайними API-ендпоінтами. Їхні ролі чітко розділені:

ендпоінт автентифікації видає JWT Bearer-токен,
OData фільтрує дані та повертає лише потрібні поля,
прив’язані дії OData виконують конкретний крок процесу, наприклад GateArrival або GateDeparture.

Отже, токен отримується не через «OData-запит». Його видає ендпоінт автентифікації того самого API TSC, після чого токен передається в заголовку кожного OData-запиту. Через OData системам ERP і WMS також доступні компанії, замовлення та рядки замовлень; поле IntegrationId пов’язує ідентифікатори TSC із ключами у вихідній системі.

П’ять кроків підключення прохідної до Time Slot Control: номер бронювання, Bearer-токен, OData-запит, прибуття та виїзд

Практичний сценарій: прохідна фіксує в’їзд і виїзд

Водій прибуває на прохідну та надає номер бронювання. Працівник сканує його або вводить у наявному застосунку. Застосунок перевіряє бронювання в TSC, може звірити номерний знак, перевізника та запланований час і після дозволу на в’їзд фіксує, що перевізник перебуває на території підприємства. Під час виїзду він використовує той самий ідентифікатор Id і позначає, що перевізник залишив територію.

У наведених прикладах використовується тестове середовище за адресою https://api.tscsandbox.com. Замініть заповнювач {tenant} назвою свого середовища. Продуктивний API має таку саму структуру за адресою https://api.timeslotcontrol.com.

Перед початком

Створіть у TSC окремий обліковий запис API. Він має отримати роль доступу до API й лише ті дозволи, які справді потрібні інтеграції, зокрема дозвіл читати бронювання та викликати дії прибуття й виїзду. Не зберігайте пароль безпосередньо у вихідному коді; використовуйте сховище секретів або захищену конфігурацію інтеграційної платформи.

1. Отримайте Bearer-токен

curl -X POST "https://api.tscsandbox.com/v1/{tenant}/Token" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "api-gatehouse@example.com",
    "Password": "<secret-from-vault>"
  }'

Відповідь містить токен:

{
  "token": "eyJhbGciOi..."
}

Використовуйте це значення в наступних викликах як Authorization: Bearer <token>. Не потрібно створювати окремий токен для кожного автомобіля. Інтеграція може безпечно зберігати його в пам’яті та поновлювати після завершення строку дії або після відповіді 401 Unauthorized.

2. Отримайте бронювання за ReservationNumber

Фільтр OData знаходить бронювання за його номером. Завдяки $select застосунок прохідної отримує лише потрібні поля:

curl --get "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation" \
  -H "Authorization: Bearer ${TOKEN}" \
  --data-urlencode "\$filter=ReservationNumber eq 'R-2026-00421'" \
  --data-urlencode "\$select=Id,ReservationNumber,VehicleNumberPlate,Carrier,Start,End,RealGateVehicleArrival,RealGateVehicleDeparture" \
  --data-urlencode "\$top=2"

Типова відповідь містить оболонку OData та масив value:

{
  "@odata.context": "https://api.tscsandbox.com/odata/v1/{tenant}/$metadata#Reservation(...)" ,
  "value": [
    {
      "Id": "37efcb13-f1cb-4a61-baea-adfb4337036f",
      "ReservationNumber": "R-2026-00421",
      "VehicleNumberPlate": "1AB2345",
      "Carrier": "Example Carrier",
      "Start": "2026-09-01T12:30:00Z",
      "End": "2026-09-01T13:30:00Z",
      "RealGateVehicleArrival": null,
      "RealGateVehicleDeparture": null
    }
  ]
}

У продуктивному середовищі продовжуйте лише тоді, коли запит повернув рівно один запис і він відповідає операційним правилам. Якщо збігу немає, передайте випадок на ручну перевірку. Якщо повернуто кілька записів, інтеграція не повинна автоматично обирати перший. Завдяки $top=2 таку ситуацію можна виявити з мінімальними витратами.

3. Позначте, що перевізник перебуває на території

Після перевірки бронювання використайте отриманий ідентифікатор Id у прив’язаній дії GateArrival:

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateArrival" \
  -H "Authorization: Bearer ${TOKEN}"

Успішний виклик повертає 204 No Content. TSC зберігає фактичний час прибуття, а зміна одразу відображається в бронюванні. Подальші процеси, сповіщення та інтеграції можуть працювати відповідно до звичайної конфігурації середовища клієнта.

4. Під час виїзду позначте, що перевізник залишив територію

На виїзді застосунок використовує той самий ідентифікатор Id. Значення null вказує TSC використати поточний серверний час:

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateDeparture" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "GateDepartureDateTime": null }'

Якщо інтеграційний пристрій має власний надійний час події, замість null можна передати значення UTC у форматі ISO 8601, наприклад 2026-09-01T14:32:00Z. Успішний виклик знову повертає 204 No Content.

Повний мінімальний приклад PowerShell

Ту саму процедуру можна записати коротким сценарієм. На практиці виклики прибуття й виїзду виконуються в різний час, але обидва використовують той самий ідентифікатор бронювання Id:

$baseUri = 'https://api.tscsandbox.com'
$tenant = '<tenant>'
$reservationNumber = 'R-2026-00421'

$tokenResponse = Invoke-RestMethod `
  -Method Post `
  -Uri "$baseUri/v1/$tenant/Token" `
  -ContentType 'application/json' `
  -Body (@{
    Username = 'api-gatehouse@example.com'
    Password = '<secret-from-vault>'
  } | ConvertTo-Json)

$headers = @{
  Authorization = "Bearer $($tokenResponse.token)"
}

$safeNumber = $reservationNumber.Replace("'", "''")
$filter = [Uri]::EscapeDataString("ReservationNumber eq '$safeNumber'")
$select = 'Id,ReservationNumber,VehicleNumberPlate,Carrier,RealGateVehicleArrival,RealGateVehicleDeparture'
$queryUri = "$baseUri/odata/v1/$tenant/Reservation?`$filter=$filter&`$select=$select&`$top=2"
$result = Invoke-RestMethod -Method Get -Uri $queryUri -Headers $headers
$reservations = @($result.value)

if ($reservations.Count -ne 1) {
  throw "Expected exactly one reservation, returned: $($reservations.Count)."
}

$reservationId = $reservations[0].Id

# When entry is permitted
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateArrival" `
  -Headers $headers

# Later, at the exit
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateDeparture" `
  -Headers $headers `
  -ContentType 'application/json' `
  -Body (@{ GateDepartureDateTime = $null } | ConvertTo-Json)

Приклад навмисно не містить справжнього пароля, тенанта чи даних клієнта. Продуктивний застосунок також має передбачати захищене зберігання секретів, тайм-аути, контрольовані повторні спроби, журналювання correlation ID та обробку відповідей 401, 403, 404, 429 й інших помилок.

Чому той самий підхід працює для ERP і WMS

Прохідна є наочним прикладом, адже результат видно відразу. Той самий принцип працює й усередині ERP або WMS:

ERP може синхронізувати компанії, замовлення та рядки замовлень через OData,
WMS може отримати актуальне бронювання та підготувати рампу або складську операцію,
прохідна може фіксувати прибуття й виїзд без переходу до іншого застосунку,
BI-інструменти можуть читати плановий і фактичний час для оцінювання очікування та пропускної здатності території,
вихідні вебхуки можуть повідомляти наступні системи про зміни без регулярного опитування.

Отже, інтеграції не потрібно копіювати всю модель даних. Кожна система отримує лише ті дані, які потрібні для її кроку, а TSC залишається єдиним достовірним джерелом інформації про бронювання та його логістичні етапи.

Від прототипу до безпечного продуктивного рішення

Перевірте першу версію в тестовому середовищі. Інтерактивна документація API за адресою api.tscsandbox.com дає змогу переглядати ендпоінти, вводити Bearer-токен і відразу отримувати приклади викликів. Точну процедуру входу описано в довідці з автентифікації, а посібник з OData пояснює можливості фільтрації.

Для продуктивного розгортання дотримуйтеся кількох правил: використовуйте окремий обліковий запис для кожної інтеграції, надавайте мінімально потрібні дозволи, зберігайте пароль у захищеному сховищі, повторно використовуйте чинний токен, вимагайте рівно один результат запиту та явно обробляйте кожну помилку. Побудуйте виклики прибуття й виїзду так, щоб їх можна було безпечно повторити: після успіху збережіть ідентифікатор Id; якщо результат невідомий, перед повторною спробою отримайте поточний стан бронювання.

Один номер бронювання, один актуальний статус для всього процесу

Головна перевага полягає не в самих чотирьох HTTP-запитах. Важливо, що прохідна, склад, диспетчерська служба та ERP працюють з одним бронюванням і тими самими часовими мітками. Зникають ручне повторне введення, телефонні перевірки та затримки в оновленні статусу.

Дізнайтеся більше на сторінці API та інтеграції Time Slot Control. Щоб перевірити подібний сценарій для своєї ERP, WMS, сканера або прохідної, почніть з одного конкретного процесу в тестовому середовищі. Для першого робочого підключення часто достатньо лише кількох точно визначених API-викликів.