Partner API — connect guide

Copy the prompt, replace nothing except the host if needed, and paste it into the other chat. It points at OpenAPI, auth, scopes, and the charges endpoints.

Ready-to-paste prompt

You are integrating with the Carmasy Partner REST API.

Base URL: https://www.carmasy.com/api/v1/api/v1
Auth: every request needs header X-API-Key: apk_… (issued in the organization admin: Settings → API). Never put the key in client-side JS or git.

Machine-readable OpenAPI: https://www.carmasy.com/api/openapi (v1.10.0+)
Interactive Swagger: https://www.carmasy.com/api-docs
Human connect guide: https://www.carmasy.com/developers
Human inventory guide: docs/api-vehicles-guide.md (in the platform repo)

Important scopes:
- catalog:write → PUT /vehicles (full fleet snapshot into main fleet; required first), PATCH /vehicles/:id
- catalog:read → GET /vehicles, GET /vehicles/:id, GET /vehicles/versions
- webhooks:manage → POST/GET /partner-webhooks (complete compliance snapshots only)
- charges:fines:search → POST /charges/fines/search, GET /charges/fines/sync-status
- charges:roads:search → POST /charges/roads-parking/search, GET /charges/roads-parking/statement, GET /charges/roads-parking/sync-status

Register the fleet once (PUT /vehicles with make/model/plate/externalId), configure a signed webhook, then receive compliance.*.snapshot.completed pushes. Manual fines/roads search is for diagnostics.
See docs/api-partner-vehicle-registry.md.

Fines search body example:
{"vehicleIds":["11111111-1111-4111-8111-111111111111"]}
or legacy plates:
{"plates":[{"number":"12345","code":"B","emirate":"DUBAI"}],"dateFrom":"2026-06-01T10:00:00+04:00","dateTo":"2026-06-20T18:00:00+04:00"}
(dateFrom/dateTo optional; if both set → ISO-8601 with offset, max 90 days.)
Partial provider failures return 200 with metadata.complete=false, metadata.plates[].status, and warnings like plate_unresolved:B:12345.

Salik roads/parking — TWO methods (same scope charges:roads:search). Never send Salik username/password in the body (office vault only).

1) Line items for a rental/time window:
POST /charges/roads-parking/search
{"plates":[{"number":"89560"},{"salikTag":"13528686"}],"kinds":["roads","parking"],"dateFrom":"2026-07-01T00:00:00+04:00","dateTo":"2026-07-31T23:59:59+04:00"}
dateFrom/dateTo REQUIRED (ISO-8601 with offset, max 90 days). If both tag and number are sent, salikTag wins.
Platform pulls Salik Excel for the calendar days, then filters to requested plates/tags.

2) Monthly statement (сверка) for one calendar month — account totals + per-vehicle aggregates:
GET /charges/roads-parking/statement?period=202607
Optional filter: plates=[{"number":"87680","code":"FF"},{"salikTag":"13755923"}] (URL-encoded JSON).
Returns account payments/tolls/parking/balances plus data.vehicles[] (toll/parking counts & amounts per plate/tag).
Use this for month-end per-vehicle reconciliation — do not replace it with summing search rows.

3) Health: GET /charges/roads-parking/sync-status → salik.hasCredentials + lastCheck.

Client timeout ≥ 120s recommended for search and statement.
Errors: 401 bad/missing key, 403 missing scope, 400 bad body/query, 409 salik_not_connected, 422 salik_auth_failed (do not retry — update office vault), 429 rate limit (20 searches / 15 min per kind per org), 503 salik_unavailable (retryable — respect Retry-After).

Start by GET https://www.carmasy.com/api/v1/charges/fines/sync-status and GET https://www.carmasy.com/api/v1/charges/roads-parking/sync-status, then one short fines search, one roads search, and one statement?period=YYYYMM.

1. 01

   Get an organization API key

   In the office: Settings → API. Create a key and select only the scopes you need. The secret is shown once — store it server-side.

2. 02

   Enable product modules

   Charges scopes require the matching modules (fines, roads/parking). Without the module, key creation and calls return entitlement errors.

3. 03

   Call with X-API-Key

   Every Partner request under /api/v1/* needs header X-API-Key: apk_…. The key is bound to one organization — you only see that org’s data.

4. 04

   Use OpenAPI as source of truth

   Fetch /api/openapi for schemas and paths. Use this page for the connect story; use Swagger for exploration.

Pick scopes when creating the key. Charges search is separate from read catalog scopes.

Read-only operational data plus charges search and Salik statement. Full schemas: OpenAPI.