Журнал змін

Нові записи — згори. Кожна зміна публічного контракту потрапляє сюди.

Про принципи сумісності — Версіонування.

v1.1

GET /proposals/search приймає startLocalityCountries і endLocalityCountries — країна кожного населеного пункту з startLocalities / endLocalities, у тому самому порядку. Разом із ними у видачу потрапляють і заявки, виставлені на всю цю країну («будь-який напрямок»), а не лише привʼязані до самого міста. Параметри необовʼязкові — без них пошук працює як раніше.
GET /employees — перелік працівників компанії.
GET /employees/{id}/proposals-count — кількість заявок, де працівник є контактною особою.
PATCH /employees/{id}/status — увімкнути або тимчасово вимкнути працівника.
PATCH /employees/{id} — змінити роль або відображуване ім'я.
Нові області доступу employees:read та employees:write. Раніше випущені ключі їх не мають — потрібен новий ключ.
Поле contactPersonId тепер приймається при створенні та редагуванні заявки (зокрема в пакетному створенні). Допускаються лише власник компанії та працівники зі статусом ACTIVE.
Змінено: GET /localities/search тепер повертає ще й області (type: "region") — раніше у відповіді були лише країни та населені пункти, тож знайти область за назвою було неможливо. Порядок: країни → області → населені пункти. Нових полів немає, з'явився ще один тип елемента масиву — якщо ви очікуєте в кожному записі osmId, фільтруйте за type === "locality".
Змінено: GET /proposals/search віддає закриті заявки після всіх відкритих, а всередині кожної групи — від найновіших. Раніше сортування було лише за createdAt, тож із includeInactive=true закриті заявки перемішувалися з відкритими. Склад відповіді не змінився — лише порядок; якщо ви покладалися на суто хронологічний порядок, сортуйте за createdAt у себе.
Виправлено: GET /employees тепер завжди повертає власника компанії з роллю OWNER. Для компаній, перенесених із попередньої платформи, цього запису не існувало, тож перелік працівників починався з найманих людей. Склад полів не змінився — з'явився ще один елемент масиву. Якщо ви рахуєте працівників за довжиною відповіді, врахуйте власника.
Виправлено: avatar (у працівників і в контактній особі заявки) завжди повертається абсолютним URL. Раніше для частини записів у полі лежав «голий» ключ сховища (avatars/….jpeg) — такий рядок клієнт розвʼязував відносно власної адреси й отримував 404. Формат поля не змінився, це той самий рядок з URL.
Виправлено: includeInactive у GET /proposals/search раніше сприймав будь-яке непорожнє значення як true — зокрема includeInactive=false повертав і закриті заявки. Тепер параметр читається як записано: true/1/yes/on вмикають, false/0/no/off вимикають, нерозпізнане значення дорівнює відсутньому. Якщо ваша інтеграція надсилала false і розраховувала на закриті заявки, вона отримає інший набір — надсилайте true явно.

v1.0

Перший публічний випуск API.

Довідники

GET /reference/countries, /reference/regions — географія.
GET /reference/car-types, /load-types, /permits, /currencies, /payment-types — словники кодів із назвами п'ятьма мовами.
GET /localities/search — пошук населених пунктів, джерело osmId для маршрутів.

Біржа

GET /proposals/search — пошук по всій біржі з фільтрами веб-версії, параметр updatedSince для інкрементальної синхронізації.
GET /proposals/{id} — картка заявки.
GET /companies/{id}, GET /companies/{id}/reviews — картка контрагента й схвалені відгуки.

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

POST /proposals/cargo, POST /proposals/transport — створення.
POST /proposals/batch — до 25 заявок одним запитом із результатом по кожній позиції.
GET /proposals/my — перелік заявок компанії, до якої прив'язаний ключ.
PATCH /proposals/{id}, POST /proposals/{id}/bump, /archive, /restore, DELETE /proposals/{id}.

Платформа

Аутентифікація ключами samo_live_ з областями доступу reference:read, proposals:read, proposals:write та необов'язковим переліком дозволених IP.
Ліміти на ключ із заголовками X-RateLimit-* і сталими кодами rate_limited / quota_exceeded.
Заголовок Idempotency-Key для безпечних повторів запитів на запис.
Вебхуки proposal.created / updated / deleted та proposal.matched із підписом X-Samo-Signature.
Сталий конверт помилки { error: { code, message, requestId } }.