Огляд і швидкий старт

SAMO-TRANS API дозволяє працювати з біржею напряму з вашої TMS, CRM або власної системи: шукати вантажі й транспорт, публікувати та оновлювати власні заявки, отримувати події про нові пропозиції під ваш напрямок.

Це той самий рушій, що й на сайті: заявка, створена через API, з'являється в пошуку так само, як створена вручну.

Кому доступний

API входить у тариф PREMIUM. Ключі видає власник компанії в кабінеті — Налаштування → API. Якщо тариф змінюється на нижчий, ключі перестають працювати, а вебхуки компанії автоматично вимикаються; після повернення на PREMIUM усе відновлюється.

Базова адреса

https://api.samo-trans.com/api/public/v1

Публічний API живе поза версіонованим /api/v1, яким користується сам сайт. Точну адресу для вашого середовища завжди показано в кабінеті на сторінці API.

Перший запит

Відкрийте Налаштування → API і натисніть «Створити ключ».
Скопіюйте ключ одразу — він показується один раз і більше не відновлюється.
Передавайте його в заголовку Authorization:

export SAMO_KEY="samo_live_XXXXXXXXXXXXXXXXXXXXXXXX"

curl "https://api.samo-trans.com/api/public/v1/reference/countries" \
  -H "Authorization: Bearer $SAMO_KEY"

Відповідь:

[
  { "code": "UA", "name": "Україна" },
  { "code": "PL", "name": "Польща" }
]

Якщо у відповідь прийшов 401, перевірте, що ключ скопійовано повністю разом із префіксом samo_live_, а перед ним стоїть слово Bearer.

Що читати далі

Аутентифікація — ключі, області доступу, обмеження за IP.
Ліміти — скільки запитів на хвилину й на добу, як реагувати на 429.
Пагінація та синхронізація — курсор і правильний спосіб тримати свою базу в актуальному стані.
Ідемпотентність — безпечні повтори запитів на запис.
Вебхуки — події замість опитування, зокрема нові заявки під ваш пошук.
Приклади запитів — готові curl для кожної групи ендпоінтів.
Помилки — конверт відповіді та повний перелік кодів.
Довідник ендпоінтів — усі методи, параметри й схеми.

Загальні правила

Формат — JSON, кодування UTF-8. Тіло запиту передавайте з Content-Type: application/json.
Дати — рядки ISO 8601 (2026-08-12T00:00:00.000Z).
Грошові суми — рядки ("price": "24500"), щоб не втрачати точність при перетворенні в число з плаваючою комою.
Кожна помилка приходить у сталому конверті з полем requestId — саме його вказуйте у зверненні до підтримки.