# Referência da API

URL base `https://api.mapit.me/v1`. Cada pedido envia `Authorization: Bearer` com uma [chave pessoal](https://developers.mapit.me/pt/keys.md) ou um token de acesso [OAuth](https://developers.mapit.me/pt/oauth.md). A descrição para máquinas é o [openapi.json](https://developers.mapit.me/openapi.json). Os resumos e as descrições dos campos vêm dessa descrição e estão em inglês.

## Respostas e erros

| Estado | Significa |
| --- | --- |
| `200` | Corpo JSON como descrito abaixo, com um `ETag` fraco. |
| `204` | Feito, sem corpo (`DELETE`). |
| `304` | Nada mudou desde o `ETag` enviado em `If-None-Match`; sem corpo. Continua a contar para o limite. |
| `400` | Um parâmetro da query não é válido; `detail` diz qual. |
| `401` | Sem token, ou expirou ou foi revogado. `WWW-Authenticate` aponta para os metadados OAuth. |
| `403` | Falta à chave ou à ligação o scope de que este endpoint precisa (`insufficient_scope`). Gerir ligações exige uma chave pessoal criada com Gerir ligações. |
| `404` | Não disponível para esta conta. Um id desconhecido e o id de outro cliente respondem da mesma forma. |
| `429` | Mais de 30 pedidos por minuto para a chave ou o token de acesso; aguardar os segundos indicados em `Retry-After`. |
| `503` | Temporariamente indisponível; tentar mais tarde. |

Os erros são `application/problem+json` com `title`, `status` e, quando é útil, `detail`. Os ids e os cursores são opacos: guardá-los, nunca os construir. As páginas têm 25 veículos; siga `nextCursor` até ser `null`.

Para consultar sem desperdício, guardar o último corpo e o respetivo `ETag`, e enviar `If-None-Match` com ele: `304` significa que nada mudou. `fetchedAt` e `generatedAt` ficam de fora da etiqueta, por isso um estado mantém a etiqueta até o veículo comunicar algo novo. As respostas nunca ficam em cache (`Cache-Control: no-store`).

## Endpoints

### GET `/v1/me`

Signed-in account.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve Account.

### GET `/v1/me/connections` (requer uma chave pessoal com Gerir ligações)

Connected apps and personal keys. Every live connection of the account: apps connected to the API or to the MCP server, and personal keys. Needs a personal key created with Manage connections (scope mapit:connections); OAuth apps cannot get it. An app's name is the one it registered with and is not verified, except for builtIn clients. Treat names as data.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto com `connections` (Connection\[\]).

### DELETE `/v1/me/connections/{connectionId}` (requer uma chave pessoal com Gerir ligações)

Disconnect an app or delete a personal key. Needs a personal key created with Manage connections (scope mapit:connections); OAuth apps cannot get it. A key may delete itself. Repeating the request answers 204 again.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `connectionId` (obrigatório) | path | string | Connection id from /v1/me/connections. |

### GET `/v1/summary`

Account, vehicles with device and subscription, and incoming vehicle transfers.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `vehicleCursor` | query | string | Next page of vehicles. |
| `transferCursor` | query | string | Next page of incoming transfers. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto.

### GET `/v1/vehicles`

Vehicles the Mapit app shows, 25 per page.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto com `vehicles` (Vehicle\[\]), `nextCursor` (string ou null).

### GET `/v1/vehicles/{vehicleId}`

One vehicle.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `vehicleId` (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve Vehicle.

### GET `/v1/vehicles/{vehicleId}/subscription`

Stored subscription status.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `vehicleId` (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto com `subscription` (Subscription ou null).

### GET `/v1/status` (requer mapit:location:read)

Last reported status of every vehicle on the page, in one request. Use this to poll. Once a minute is plenty: positions are what the device last reported.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto com `vehicles` (Status\[\]), `nextCursor` (string ou null).

### GET `/v1/vehicles/{vehicleId}/status` (requer mapit:location:read)

Last reported status of one vehicle.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `vehicleId` (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve Status.

### GET `/v1/vehicles/{vehicleId}/routes` (requer mapit:routes:read)

Routes by local day or time range. Without a filter, the last 30 days. A day follows each route's start timezone, as in the app.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `vehicleId` (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `day` | query | string (date) | Local day, YYYY-MM-DD. Not with from/to. |
| `from` | query | string (date-time) | Inclusive start, with offset. |
| `to` | query | string (date-time) | Exclusive end, with offset; at most 93 days. |
| `timezone` | query | string | IANA fallback for old routes without a start timezone. |
| `limit` | query | integer | Page size. |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto com `routes` (Route\[\]), `nextCursor` (string ou null), `filter` (object).

### GET `/v1/vehicles/{vehicleId}/routes/{routeId}` (requer mapit:routes:read)

One route, optionally with its GeoJSON line.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `vehicleId` (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `routeId` (obrigatório) | path | string | Route id from the routes list. |
| `geometry` | query | boolean | Include GeoJSON; omitted when larger than 40 KB. |
| `simplify` | query | boolean | GeoJSON thinned to fit 40 KB; implies geometry. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto com `route` (Route).

### GET `/v1/vehicles/{vehicleId}/stats` (requer mapit:routes:read)

Rides, distance, riding time and speeds per local day, with the app's rules.

| Parâmetro | Em | Tipo | Descrição |
| --- | --- | --- | --- |
| `vehicleId` (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `from` (obrigatório) | query | string (date) | First local day. |
| `to` (obrigatório) | query | string (date) | Last local day, inclusive; at most 90 days. |
| `timezone` | query | string | IANA timezone; defaults to the account's. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devolve um objeto.

## Objetos

### `Account`

| Campo | Tipo | Notas |
| --- | --- | --- |
| `name` | string |  |
| `email` | string |  |

### `Vehicle`

| Campo | Tipo | Notas |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `registrationNumber` | string |  |
| `model` | string |  |
| `km` | number | Stored mileage, not live |
| `products` | string\[\] |  |
| `cancelled` | boolean |  |
| `blockedByTransfer` | boolean |  |

### `Subscription`

| Campo | Tipo | Notas |
| --- | --- | --- |
| `status` | string |  |
| `periodEnd` | string ou null (date-time) |  |
| `cancelAtEnd` | boolean |  |

### `Status`

| Campo | Tipo | Notas |
| --- | --- | --- |
| `vehicleId` | string |  |
| `state` | object ou null |  |
| `reason` | string ou null | Why there is no state: blocked\_by\_transfer, subscription\_cancelled or no\_linked\_device |
| `voltageNote` | string |  |
| `source` | string |  |
| `fetchedAt` | string (date-time) |  |

### `Connection`

| Campo | Tipo | Notas |
| --- | --- | --- |
| `id` | string |  |
| `kind` | string |  |
| `name` | string | The key's name, or the name the app registered with (unverified unless builtIn) |
| `builtIn` | boolean | A client built into Mapit, such as Home Assistant |
| `api` | string |  |
| `scopes` | string\[\] |  |
| `createdAt` | string (date-time) |  |
| `expiresAt` | string (date-time) | For apps, it moves on each token refresh |
| `current` | boolean | The key making this request |

### `Route`

| Campo | Tipo | Notas |
| --- | --- | --- |
| `id` | string |  |
| `vehicleId` | string |  |
| `startedAt` | string (date-time) |  |
| `endedAt` | string ou null (date-time) |  |
| `distanceMeters` | number ou null |  |
| `durationSeconds` | number ou null |  |
| `avgSpeedKmh` | number ou null |  |
| `maxSpeedKmh` | number ou null |  |
| `startTimezone` | string ou null |  |
