SAMO·TRANS
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 /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.
  • 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 } }.