SAMO·TRANS
Telegram
Документація API

Інтеграція біржі SAMO-TRANS у вашу TMS або CRM

Документація API

Події

Приклади запитів

Готові curl для довідників, пошуку, створення заявок, пакетів і синхронізації.

Усі приклади припускають дві змінні оточення:

export SAMO_API="https://api.samo-trans.com/api/public/v1"
export SAMO_KEY="samo_live_XXXXXXXXXXXXXXXXXXXXXXXX"

Довідники

Перед першим створенням заявки заберіть словники — саме ці коди приймає API. Вони змінюються рідко, тож кешуйте їх у себе.

curl "$SAMO_API/reference/car-types"     -H "Authorization: Bearer $SAMO_KEY"
curl "$SAMO_API/reference/load-types"    -H "Authorization: Bearer $SAMO_KEY"
curl "$SAMO_API/reference/permits"       -H "Authorization: Bearer $SAMO_KEY"
curl "$SAMO_API/reference/currencies"    -H "Authorization: Bearer $SAMO_KEY"
curl "$SAMO_API/reference/payment-types" -H "Authorization: Bearer $SAMO_KEY"

Кожен елемент має код і назви п'ятьма мовами:

{ "code": "tent", "labels": { "uk": "Тент", "en": "Tent", "ru": "Тент", "de": "Plane", "pl": "Plandeka" } }

Географія:

curl "$SAMO_API/reference/countries?locale=uk" -H "Authorization: Bearer $SAMO_KEY"
curl "$SAMO_API/reference/regions?country=UA&locale=uk" -H "Authorization: Bearer $SAMO_KEY"

# пошук населеного пункту → звідси беруться osmId для маршруту
curl "$SAMO_API/localities/search?q=Ковель&country=UA&locale=uk" \
  -H "Authorization: Bearer $SAMO_KEY"

Пошук по біржі

curl -G "$SAMO_API/proposals/search" \
  -H "Authorization: Bearer $SAMO_KEY" \
  --data-urlencode "type=CARGO" \
  --data-urlencode "startCountries=UA" \
  --data-urlencode "endCountries=PL" \
  --data-urlencode "minCapacity=15" \
  --data-urlencode "dateFrom=2026-08-10" \
  --data-urlencode "limit=50"

Гео-фільтри — масиви, тому параметр повторюється:

curl -G "$SAMO_API/proposals/search" \
  -H "Authorization: Bearer $SAMO_KEY" \
  --data-urlencode "startRegions=UA-07" \
  --data-urlencode "startRegions=UA-05" \
  --data-urlencode "carTypes=tent" \
  --data-urlencode "carTypes=ref"

Картка однієї заявки:

curl "$SAMO_API/proposals/clx7k2n9p0001/?locale=uk" -H "Authorization: Bearer $SAMO_KEY"

Контакти у відповіді присутні лише якщо ваш тариф дозволяє їх бачити — інакше "contact": null.

Створення заявки

Вантаж:

curl -X POST "$SAMO_API/proposals/cargo" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tms-order-88213" \
  -d '{
    "startLocations": [{ "type": "locality", "osmId": "3678531", "countryCode": "UA" }],
    "endLocations":   [{ "type": "country",  "countryCode": "PL" }],
    "dataLoadStart": "2026-08-12T00:00:00.000Z",
    "dataLoadEnd":   "2026-08-14T00:00:00.000Z",
    "capacity": 20,
    "volume": 86,
    "description": "Піддони, 20 т, розтентовка збоку",
    "carTypes": ["tent"],
    "loadUnloadTypes": ["side", "back"],
    "carPermits": ["cmr", "t1"],
    "price": 24500,
    "currencyType": "UAH",
    "paymentType": "CASHLESS"
  }'

Транспорт — той самий формат тіла, інший шлях:

curl -X POST "$SAMO_API/proposals/transport" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "startLocations": [ … ], "endLocations": [ … ], "dataLoadStart": "…", "dataLoadEnd": "…", "capacity": 22, "description": "Тент 92 м³, вільний з понеділка", "carTypes": ["tent"] }'

Обов'язкові поля: startLocations, endLocations, dataLoadStart, dataLoadEnd, capacity, description, carTypes.

companyId передавати не потрібно — він завжди береться з ключа; поле companyId у тілі не ігнорується, а роняє запит у 400 validation_error. Контактну особу (contactPersonId) передавати не обов'язково — якщо не вказати, контактом стане користувач, який випустив ключ. Детальніше — розділ «Заявка на конкретного працівника» нижче.

Пакетне створення

До 25 заявок одним запитом. Відповідь завжди 200, результат — по кожній позиції окремо.

curl -X POST "$SAMO_API/proposals/batch" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tms-batch-2026-08-05-01" \
  -d '{
    "items": [
      { "type": "CARGO",     "startLocations": [ … ], "endLocations": [ … ], "…": "…" },
      { "type": "TRANSPORT", "startLocations": [ … ], "endLocations": [ … ], "…": "…" }
    ]
  }'

{
  "created": 1,
  "failed": 1,
  "results": [
    { "index": 0, "status": "created", "proposal": { "id": "clx…", "…": "…" } },
    { "index": 1, "status": "error", "error": { "code": "validation_error", "message": "capacity must be a number" } }
  ]
}

Пакет списує стільки одиниць добової квоти, скільки в ньому позицій. Якщо квоти не вистачить, увесь запит відхиляється з 429 quota_exceeded — жодної заявки при цьому не створюється.

Власні заявки

# перелік (лише заявки компанії, до якої прив'язаний ключ)
curl -G "$SAMO_API/proposals/my" \
  -H "Authorization: Bearer $SAMO_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "limit=100"

# редагування — часткове, надсилайте лише змінені поля
curl -X PATCH "$SAMO_API/proposals/clx7k2n9p0001" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price": 26000, "description": "Оновлено: можливе довантаження" }'

# підняти в пошуку
curl -X POST "$SAMO_API/proposals/clx7k2n9p0001/bump" -H "Authorization: Bearer $SAMO_KEY"

# зняти з публікації / повернути
curl -X POST "$SAMO_API/proposals/clx7k2n9p0001/archive" -H "Authorization: Bearer $SAMO_KEY"
curl -X POST "$SAMO_API/proposals/clx7k2n9p0001/restore" -H "Authorization: Bearer $SAMO_KEY"

# видалити остаточно
curl -X DELETE "$SAMO_API/proposals/clx7k2n9p0001" -H "Authorization: Bearer $SAMO_KEY"

Що варто знати про ці дії:

  • bump доступний авторові заявки або її контактній особі. Власника компанії самого по собі недостатньо. Занадто раннє підняття або вичерпаний ліміт піднять повертають 400 validation_error з поясненням у message.
  • archive і restore ідемпотентні: повторний виклик для заявки, яка вже в потрібному стані, поверне 200 і нічого не змінить.
  • restore не безкоштовний: повернення заявки в ефір скидає її createdAt і лічильник переглядів, а також займає слот активних заявок вашого тарифу. Якщо ліміт вичерпано, прийде 400.
  • Спроба звернутися до заявки іншої компанії дає 404, а не 403.

Працівники

# перелік працівників компанії, до якої прив'язаний ключ
curl "$SAMO_API/employees" -H "Authorization: Bearer $SAMO_KEY"

# скільки заявок висить на конкретному працівникові — варто перевірити перед вимкненням
curl "$SAMO_API/employees/clx9f4k7r0004/proposals-count" -H "Authorization: Bearer $SAMO_KEY"

# тимчасово заблокувати доступ
curl -X PATCH "$SAMO_API/employees/clx9f4k7r0004/status" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "DEACTIVATED" }'

# повернути доступ
curl -X PATCH "$SAMO_API/employees/clx9f4k7r0004/status" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ACTIVE" }'

# змінити роль
curl -X PATCH "$SAMO_API/employees/clx9f4k7r0004" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "DISPATCHER" }'

Відповідь на перелік:

[
  {
    "id": "clx9f4k7r0004",
    "userId": "clx2h6m3t0005",
    "email": "[email protected]",
    "name": "Оксана Ковальчук",
    "role": "DISPATCHER",
    "status": "ACTIVE",
    "invitedAt": "2026-01-02T10:00:00.000Z",
    "joinedAt": "2026-01-03T09:30:00.000Z",
    "avatar": null,
    "phones": [{ "phone": "+380501234567", "isPrimary": true, "hasTelegram": true, "hasWhatsApp": false, "hasViber": false }]
  }
]

Зверніть увагу на два різні ідентифікатори: id — це членство в компанії, він іде у шляху цих ендпоінтів; userId — це користувач, і саме він передається як contactPersonId у заявці.

Вимкнення працівника не знімає його заявки з публікації — вони залишаються в ефірі й далі показують його контактом. Спочатку подивіться proposals-count, за потреби перевісьте заявки через PATCH /proposals/{id}.

Створення й видалення працівників через API не передбачені — це робиться в кабінеті.

Заявка на конкретного працівника

curl -X POST "$SAMO_API/proposals/cargo" \
  -H "Authorization: Bearer $SAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startLocations": [{ "type": "country", "countryCode": "UA" }],
    "endLocations":   [{ "type": "country", "countryCode": "PL" }],
    "dataLoadStart": "2026-08-12T00:00:00.000Z",
    "dataLoadEnd":   "2026-08-14T00:00:00.000Z",
    "capacity": 20,
    "description": "Піддони",
    "carTypes": ["tent"],
    "contactPersonId": "clx2h6m3t0005"
  }'

contactPersonId — це userId із переліку працівників. Дозволені лише власник компанії та працівники зі статусом ACTIVE; будь-хто інший дасть 400 validation_error. Якщо поле не передати, контактом стане користувач, який випустив ключ.

Компанія-контрагент

curl "$SAMO_API/companies/clx4a1b2c0001" -H "Authorization: Bearer $SAMO_KEY"
curl "$SAMO_API/companies/clx4a1b2c0001/reviews?page=1&limit=20" -H "Authorization: Bearer $SAMO_KEY"

Повертаються лише схвалені відгуки; limit обмежений 50.

Інкрементальна синхронізація

Замість повного обходу біржі забирайте дельту:

curl -G "$SAMO_API/proposals/search" \
  -H "Authorization: Bearer $SAMO_KEY" \
  --data-urlencode "updatedSince=2026-08-05T09:00:00.000Z" \
  --data-urlencode "limit=100"

Далі йдіть сторінками через nextCursor, дедуплікуючи за id. Подробиці й підводні камені — у розділі Пагінація та синхронізація.