Довідник ендпоінтів

List countries served by the exchange

List regions/oblasts for a country

Car body types (grouped) — valid `carTypes` codes for a proposal

Vehicle composition types — valid optional `vehicleType` codes

Loading/unloading types — valid `loadUnloadTypes` codes

Transport permit/document types — valid `carPermits` codes

Supported currencies — valid `currencyType` values

Payment forms — valid `paymentType` values

Autocomplete search across countries, regions, and localities

Create a CARGO proposal

companyId is always resolved from the API key — never from the request body. type is fixed by this route. contactPersonId is optional: if given, it must be the company owner or an ACTIVE employee of the key's company; if omitted, it defaults to the key's owner.

Create a TRANSPORT proposal

companyId is always resolved from the API key — never from the request body. type is fixed by this route. contactPersonId is optional: if given, it must be the company owner or an ACTIVE employee of the key's company; if omitted, it defaults to the key's owner.

Create up to 25 proposals in one request

Each item is validated and created independently — the response carries a per-item result ({index, status:"created", proposal} or {index, status:"error", error}). The whole batch consumes N of the daily write quota (not 1); if it would exceed the quota the request is rejected with 429 before creating anything. Combine with an Idempotency-Key for safe retries.

List the calling key’s own proposals

Scoped via ProposalsService.getMyProposals — never leaks other companies’ proposals.

Update a proposal

Delete a proposal permanently

Bump a proposal to the top of search results

Ownership matches update/delete/archive: the proposal’s author, its contact person, or an owner/manager of the owning company may bump it. May fail with BUMP_NOT_OWNER, BUMP_TOO_SOON, or BUMP_LIMIT_REACHED. These are internal { code, message } exceptions, not public-API error codes — PublicApiExceptionFilter remaps them onto the stable public set: BUMP_NOT_OWNER (ForbiddenException) becomes 403 { error: { code: 'forbidden' } }; BUMP_TOO_SOON and BUMP_LIMIT_REACHED (both BadRequestException) become 400 { error: { code: 'validation_error' } }. The specific reason is always preserved in the envelope’s `message`, never in `code`.

Archive (deactivate) a proposal — idempotent

There is no dedicated archive() in ProposalsService, only toggleStatus() which flips ACTIVE⇄INACTIVE. This route calls ProposalsService.setProposalStatus(id, actorUserId, 'INACTIVE'), which verifies ownership FIRST and only then no-ops if the proposal is already INACTIVE — so a key with no rights over the proposal gets 403 even when it is already in the target state, instead of silently succeeding.

Restore (reactivate) a proposal — idempotent

Mirror of /archive: calls ProposalsService.setProposalStatus(id, actorUserId, 'ACTIVE'), which verifies ownership FIRST and only then no-ops if already ACTIVE. Reactivating is a real ProposalsService side effect — it RESETS createdAt and viewCount to 0 (proposals.service.ts toggleStatus/setProposalStatus), the same behavior the web app has today. Bringing a proposal back online consumes an active-proposal slot from the company plan exactly as creating one does, so this returns 400 when the company is at its maxActiveProposals cap. The already-ACTIVE no-op never consumes a slot and stays 200 even at the cap.

Get a single proposal by id

Search the whole exchange for cargo/transport proposals

Exchange-wide search (not scoped to the calling key's own company) — filters mirror the web app's search (type, geo, dates, capacity, car types, etc). Contact info is only present when the calling key's plan grants canViewContacts. `limit` is capped at 100 regardless of the requested value.

Get a company profile (name, legal form, rating + reviews summary, contacts)

Paginated APPROVED reviews of a company (counterparty reputation)

List the key's company staff

Returns every membership of the company the key belongs to, including PENDING invitations. Use `userId` (not `id`) as a proposal `contactPersonId`.

Count the listings an employee is contact person for

Useful before deactivating someone — those listings keep pointing at them.

Activate or deactivate an employee

DEACTIVATED removes the person's access to the company dashboard — they land on the suspended screen — but only if they have no other ACTIVE employment; it does not block signing in to the platform and does not end an existing session. Their listings stay published and keep pointing at them as contact person — check /employees/{id}/proposals-count first. Idempotent: setting the status an employee already has succeeds and changes nothing.

Change an employee's role or display name

The OWNER role cannot be assigned — ownership is not transferable through this API.