SAMO·TRANS
Log in
Telegram
API documentation

Integrate the SAMO-TRANS exchange into your TMS or CRM

API documentation

Events

Changelog

History of changes to the SAMO-TRANS public API.

Newest entries on top. Every change to the public contract lands here.

For the compatibility rules, see Versioning.

v1.1

  • GET /proposals/search accepts startLocalityCountries and endLocalityCountries — the country of each entry in startLocalities / endLocalities, in the same order. With them the results also include listings posted for that whole country ("any direction"), not only the ones tied to the city itself. Both are optional — without them search behaves as before.
  • GET /employees — list company staff.
  • GET /employees/{id}/proposals-count — how many listings name the employee as contact.
  • PATCH /employees/{id}/status — activate or temporarily deactivate an employee.
  • PATCH /employees/{id} — change role or display name.
  • New scopes employees:read and employees:write. Previously issued keys do not carry them — create a new key.
  • contactPersonId is now accepted when creating and updating a listing (batch included). Only the company owner and employees with status ACTIVE are allowed.
  • Changed: GET /localities/search now also returns regions (type: "region") — the response used to carry countries and localities only, so a region could not be found by name. Order is countries → regions → localities. No new fields, one more kind of array entry — if you expect an osmId on every record, filter by type === "locality".
  • Changed: GET /proposals/search returns closed listings after every open one, newest first within each group. Ordering used to be by createdAt alone, so with includeInactive=true closed listings were mixed in among the open ones. The response is unchanged — only its order; if you relied on a purely chronological sequence, sort by createdAt on your side.
  • Fixed: GET /employees now always returns the company owner, with role OWNER. Companies carried over from the previous platform had no such record, so their staff list started with hired people. No field changed — the array simply has one more element. If you size your staff by the length of the response, count the owner in.
  • Fixed: avatar (on employees and on a listing's contact person) is always an absolute URL. Some records used to carry a bare storage key (avatars/….jpeg), which a client resolved against its own address and got a 404 for. The field's type is unchanged — it is the same URL string.
  • Fixed: includeInactive on GET /proposals/search used to read any non-empty value as true, so even includeInactive=false returned closed listings. It is now read as written: true/1/yes/on enable it, false/0/no/off disable it, and an unrecognised value behaves as if the parameter were absent. If your integration sent false and relied on getting closed listings back, it will now receive a different set — send true explicitly.

v1.0

The first public release of the API.

Dictionaries

  • GET /reference/countries, /reference/regions — geography.
  • GET /reference/car-types, /load-types, /permits, /currencies, /payment-types — code dictionaries with labels in five languages.
  • GET /localities/search — locality search, the source of route osmIds.

Exchange

  • GET /proposals/search — search the whole exchange with the web app's filters, plus updatedSince for incremental sync.
  • GET /proposals/{id} — listing detail.
  • GET /companies/{id}, GET /companies/{id}/reviews — counterparty profile and approved reviews.

Your own listings

  • POST /proposals/cargo, POST /proposals/transport — creation.
  • POST /proposals/batch — up to 25 listings per request with a per-item result.
  • GET /proposals/my — listings of the company the key belongs to.
  • PATCH /proposals/{id}, POST /proposals/{id}/bump, /archive, /restore, DELETE /proposals/{id}.

Platform

  • Authentication with samo_live_ keys carrying reference:read, proposals:read and proposals:write scopes plus an optional IP allowlist.
  • Per-key rate limits with X-RateLimit-* headers and the stable rate_limited / quota_exceeded codes.
  • Idempotency-Key support for safe write retries.
  • Webhooks for proposal.created / updated / deleted and proposal.matched, signed with X-Samo-Signature.
  • The stable error envelope { error: { code, message, requestId } }.