# Referencia de la API

URL base `https://api.mapit.me/v1`. Cada petición envía `Authorization: Bearer` con una [clave personal](https://developers.mapit.me/es/keys.md) o un token de acceso de [OAuth](https://developers.mapit.me/es/oauth.md). La descripción para máquinas es [openapi.json](https://developers.mapit.me/openapi.json). Los resúmenes y las descripciones de campos vienen de esa descripción y están en inglés.

## Respuestas y errores

| Estado | Significa |
| --- | --- |
| `200` | Cuerpo JSON como se describe abajo, con un `ETag` débil. |
| `204` | Hecho, sin cuerpo (`DELETE`). |
| `304` | Nada ha cambiado desde el `ETag` que enviaste en `If-None-Match`; sin cuerpo. Sigue contando para el límite. |
| `400` | Un parámetro de la consulta no es válido; `detail` dice cuál. |
| `401` | No hay token, o caducó o se revocó. `WWW-Authenticate` apunta a los metadatos de OAuth. |
| `403` | A la clave o la conexión le falta el scope que necesita este endpoint (`insufficient_scope`). Gestionar conexiones necesita una clave personal creada con Gestionar conexiones. |
| `404` | No disponible para esta cuenta. Un id desconocido y el id de otro cliente responden igual. |
| `429` | Más de 30 peticiones por minuto para la clave o el token de acceso; espera los segundos que indica `Retry-After`. |
| `503` | No disponible temporalmente; vuelve a intentarlo más tarde. |

Los errores son `application/problem+json` con `title`, `status` y, cuando sirve de algo, `detail`. Los ids y los cursores son opacos: guárdalos, nunca los construyas. Las páginas tienen 25 vehículos; sigue `nextCursor` hasta que sea `null`.

Para consultar sin gastar, guarda el último cuerpo y su `ETag`, y envía `If-None-Match` con él: `304` significa que nada ha cambiado. `fetchedAt` y `generatedAt` no cuentan para la etiqueta, así que un estado conserva su etiqueta hasta que el vehículo informa algo nuevo. Las respuestas nunca se guardan en caché (`Cache-Control: no-store`).

## Endpoints

### GET `/v1/me`

Signed-in account.

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devuelve Account.

### GET `/v1/me/connections` (necesita una clave personal con Gestionar conexiones)

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 | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devuelve un objeto con `connections` (Connection\[\]).

### DELETE `/v1/me/connections/{connectionId}` (necesita una clave personal con Gestionar conexiones)

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 | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `connectionId` (obligatorio) | path | string | Connection id from /v1/me/connections. |

### GET `/v1/summary`

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

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `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. |

Devuelve un objeto.

### GET `/v1/vehicles`

Vehicles the Mapit app shows, 25 per page.

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devuelve un objeto con `vehicles` (Vehicle\[\]), `nextCursor` (string o null).

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

One vehicle.

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `vehicleId` (obligatorio) | 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. |

Devuelve Vehicle.

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

Stored subscription status.

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `vehicleId` (obligatorio) | 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. |

Devuelve un objeto con `subscription` (Subscription o null).

### GET `/v1/status` (necesita 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 | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Devuelve un objeto con `vehicles` (Status\[\]), `nextCursor` (string o null).

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

Last reported status of one vehicle.

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `vehicleId` (obligatorio) | 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. |

Devuelve Status.

### GET `/v1/vehicles/{vehicleId}/routes` (necesita 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 | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `vehicleId` (obligatorio) | 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. |

Devuelve un objeto con `routes` (Route\[\]), `nextCursor` (string o null), `filter` (object).

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

One route, optionally with its GeoJSON line.

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `vehicleId` (obligatorio) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `routeId` (obligatorio) | 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. |

Devuelve un objeto con `route` (Route).

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

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

| Parámetro | En | Tipo | Descripción |
| --- | --- | --- | --- |
| `vehicleId` (obligatorio) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `from` (obligatorio) | query | string (date) | First local day. |
| `to` (obligatorio) | 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. |

Devuelve un 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 o null (date-time) |  |
| `cancelAtEnd` | boolean |  |

### `Status`

| Campo | Tipo | Notas |
| --- | --- | --- |
| `vehicleId` | string |  |
| `state` | object o null |  |
| `reason` | string o 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 o null (date-time) |  |
| `distanceMeters` | number o null |  |
| `durationSeconds` | number o null |  |
| `avgSpeedKmh` | number o null |  |
| `maxSpeedKmh` | number o null |  |
| `startTimezone` | string o null |  |
