Fleet & trips

Partner fleet positions and passenger trip sharing.

POST/v1/fleet/positionsЗапланировано

Publish vehicle positions (HTTP alternative to the stream `pub` op)

Хост: https://api.atasumaps.com · publishFleetPositions
Доступ: API-ключ с областью: fleet
Учёт: realtime_msg (за message)
Idempotency-Key: Обязателен: один ключ на команду, повтор возвращает первый результат

Server key only. Positions go to the organization's fleet channel and to subscribers of active trips of that vehicle; never to public channels. Snap to roads first (/v1/snap) for smooth display. Precise positions are not logged and are kept only as long as the trip needs.

Параметры

Имя	Где	Тип	Обязательно	Описание
`Idempotency-Key`	header	`string`	да	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Тело запроса `FleetPositionBatch`

Имя	Тип	Обязательно	Описание
`positions`	`FleetPosition[]`	да

Ответы

Статус	Описание	Тип
`202`	Accepted
`400`	Invalid request (`invalid_request`, `idempotency_key_required`, `limit_exceeded`, `future_departure_not_supported`, `observation_in_future`)	`Problem`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`402`	A budget cap is reached and no degraded answer exists (`budget_exhausted`; `context.level` is `organization` or `product`, `context.product` the product)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`
`429`	Rate limit (`rate_limited`) or monthly plan quota (`quota_exceeded`: `reject` plans only; `Retry-After` = seconds until the next Asia/Almaty month; `context` = `product`, `included`, `used`, `period_end`)	`Problem`

POST/v1/tripsЗапланировано

Start sharing a trip (vehicle ↔ passenger)

Хост: https://api.atasumaps.com · createTrip
Доступ: API-ключ с областью: fleet
Учёт: Не учитывается
Idempotency-Key: Обязателен: один ключ на команду, повтор возвращает первый результат

Server key with fleet scope. The trip belongs to the key's organization; only that organization and the trip's passenger (with a ticket) can see it.

Параметры

Имя	Где	Тип	Обязательно	Описание
`Idempotency-Key`	header	`string`	да	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Тело запроса `TripCreate`

Имя	Тип	Обязательно	Описание
`fleet_id`	`string`
`vehicle_id`	`string`	да
`passenger_ref`	`string`	да	Partner's opaque passenger ID (no personal data)
`external_ref`	`string`		Partner's order ID
`pickup`	`Waypoint`		Exactly one of `lnglat`, `place_id`, `entrance_id`. A `place_id` destination resolves to an evidence-backed entrance / pickup point for the costing, else the building or street.
`dropoff`	`Waypoint`		Exactly one of `lnglat`, `place_id`, `entrance_id`. A `place_id` destination resolves to an evidence-backed entrance / pickup point for the costing, else the building or street.
`expires_at`	`string (date-time)`		Hard end; default 6 hours after creation

Ответы

Статус	Описание	Тип
`201`	Trip	`Trip`
`400`	Invalid request (`invalid_request`, `idempotency_key_required`, `limit_exceeded`, `future_departure_not_supported`, `observation_in_future`)	`Problem`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`

POST/v1/trips/{trip_id}/ticketsЗапланировано

Issue a short-lived passenger ticket for a trip

Хост: https://api.atasumaps.com · createTripTicket
Доступ: API-ключ с областью: fleet
Учёт: Не учитывается
Idempotency-Key: Обязателен: один ключ на команду, повтор возвращает первый результат

The partner backend issues a ticket bound to (passenger, trip) and hands it to its app; the app presents it on the stream to subscribe to trip (WEBSOCKET.md). Tickets expire with the trip or after ttl_s, whichever comes first.

Параметры

Имя	Где	Тип	Обязательно	Описание
`trip_id`	path	`string`	да
`Idempotency-Key`	header	`string`	да	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Тело запроса `TripTicketCreate`

Имя	Тип	Обязательно	Описание
`passenger_ref`	`string`	да	Must equal the trip's passenger
`ttl_s`	`integer`

Ответы

Статус	Описание	Тип
`201`	Ticket (shown once)	`TripTicket`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`404`	No such resource, or not visible to the caller (`not_found`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`

POST/v1/trips/{trip_id}/endЗапланировано

End a trip; tickets stop working and subscribers get a tombstone

Хост: https://api.atasumaps.com · endTrip
Доступ: API-ключ с областью: fleet
Учёт: Не учитывается
Idempotency-Key: Обязателен: один ключ на команду, повтор возвращает первый результат

Параметры

Имя	Где	Тип	Обязательно	Описание
`trip_id`	path	`string`	да
`Idempotency-Key`	header	`string`	да	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Ответы

Статус	Описание	Тип
`200`	Ended trip	`Trip`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`404`	No such resource, or not visible to the caller (`not_found`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`

Fleet & trips

Publish vehicle positions (HTTP alternative to the stream `pub` op)

Параметры

Тело запроса FleetPositionBatch

Ответы

Start sharing a trip (vehicle ↔ passenger)

Параметры

Тело запроса TripCreate

Ответы

Issue a short-lived passenger ticket for a trip

Параметры

Тело запроса TripTicketCreate

Ответы

End a trip; tickets stop working and subscribers get a tombstone

Параметры

Ответы

Тело запроса `FleetPositionBatch`

Тело запроса `TripCreate`

Тело запроса `TripTicketCreate`