Журнал змін

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

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

v1.1

Додано: транспортні заявки отримали необов'язкове поле vehicleType, незалежне від carTypes. Допустимі коди віддає новий GET /reference/vehicle-types; null у PATCH очищає значення. Поле повертається у відповіді як код або null. Для вантажних заявок воно не дозволене. Зміна адитивна: старі записи та інтеграції лишаються валідними.
Додано: GET /reference/car-types тепер також повертає спеціалізовані коди кузовів box_type, walking_floor_type, coil_carrier_type, timber_truck_type, concrete_mixer_type та hooklift_type. Це адитивна зміна довідника; інтеграціям слід читати цей ендпоінт і бути готовими до нових кодів замість закритого локального enum.
Додано: заявка отримала необов'язковий температурний режим. У тілі створення та редагування — temperatureMin і temperatureMax (°C, діапазон −99…+99, будь-яку межу можна не вказувати); у відповіді — temperatureMinC і temperatureMaxC, обидва null, якщо режим не заданий. Поля приймаються лише разом із температурним кузовом (ref, ref-tushe, izoterm), інакше — 400 validation_error. PATCH, що змінює кузов на нетемпературний, обнуляє обидві межі. Зміна адитивна: наявні інтеграції нічого не втрачають і можуть просто ігнорувати нові поля.
Змінено: контакти в description вирізаються перед збереженням заявки — телефони, адреси електронної пошти, @ніки та посилання (зокрема «голі» домени та посилання на месенджери). Діє на POST /proposals/cargo, POST /proposals/transport, POST /proposals/batch і PATCH /proposals/{id}. Це не валідація: запит із телефоном в описі проходить успішно, помилки не буде — заявка зберігається з очищеним текстом. Наслідок для інтеграції: description у відповіді й при наступному GET може бути коротшим за надісланий — не звіряйте ці рядки на рівність. Текст без контактів повертається без змін: дати рейсу, ЄДРПОУ, вага та ціна телефоном не вважаються. Опис поля в довіднику оновлено.
Виправлено: нечисловий ідентифікатор населеного пункту більше не дає 500 internal. startLocalities / endLocalities у GET /proposals/search, а також startLocations[].osmId і endLocations[].osmId при створенні та редагуванні заявки приймають лише додатне ціле число — OSM ID. Будь-що інше (літери, дріб, знак, число поза діапазоном bigint) тепер повертає 400 з кодом validation_error; раніше такий запит падав із 500 internal. Коректні ідентифікатори працюють точно як раніше.
Змінено: POST /proposals/{id}/bump тепер доступний ще й власникові та менеджеру компанії, якій належить заявка, — рівно ті самі права, що вже діяли для update, archive і delete. Раніше підняти заявку міг лише її автор або контактна особа, тож власник компанії отримував 403 forbidden на заявку власного працівника, хоча редагувати чи зняти її з ефіру міг. Обмеження прав це не звужує — доступ лише розширено, наявні інтеграції нічого не втрачають.
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 у себе.
Змінено: description при створенні та редагуванні заявки (зокрема в пакетному створенні) обмежений 250 символами. Раніше довжина не перевірялася взагалі — приймався будь-який рядок. Довший текст тепер отримує 400 з кодом validation_error; обрізайте опис на своєму боці. Обмеження видно і в довіднику як maxLength поля.
Виправлено: 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 } }.