Құжаттама мәтіні әзірге орыс тілінде. Қазақша аудармасы дайындалып жатыр — мәзір мен түймелер қазақша.

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`