# Usa Mapit con IA

Dos formas de usar Mapit con IA: pregúntale a un asistente por tu propia moto, o haz que un agente de programación escriba el código que la lee.

> **Beta, gratis por ahora.** Mi Mapit y el servicio que hay detrás son una beta: pueden cambiar o dejar de funcionar, no tienen garantía de disponibilidad y hoy Mapit no los cobra. No dependas de ellos para emergencias ni para recuperar una moto robada: para eso, usa la app de Mapit. Consulta las [condiciones de la beta](https://developers.mapit.me/es/terms.md).

## Pregúntale a un asistente por tu moto

**Mi Mapit** conecta un asistente de IA con tu propia cuenta de Mapit. Pregúntale «¿Dónde está mi moto?», «¿Qué rutas hice ayer?» o «¿Cuándo termina mi suscripción?». Inicias sesión con tu cuenta de Mapit en la página de Mapit y eliges qué puede ver el asistente. Nunca recibe tu contraseña.

### Plugin o conector

Mi Mapit se ofrece de dos formas. El **plugin** reúne el conector Mi Mapit y dos skills. El marketplace `mapit-iot/ai-plugin` (un repositorio de GitHub) se añade en Claude Code y Codex, más abajo. En claude.ai, un administrador de la organización lo añade en Ajustes de la organización > Plugins y skills > Marketplaces, desde una copia privada (ver claude.ai más abajo). Si tu asistente no admite plugins, añade en su lugar el **conector** con su URL, como en claude.ai y ChatGPT más abajo.

### claude.ai

En Ajustes, abre Conectores y añade un conector personalizado llamado **Mi Mapit** con la URL `https://api.mapit.me/mcp`. Después conéctalo e inicia sesión con tu cuenta de Mapit.

**Los propietarios de Team y Enterprise** pueden dar el plugin a toda la organización: en Ajustes de la organización, abre Plugins y skills, luego Marketplaces, y añade el repositorio de GitHub que contiene una copia de `mapit-iot/ai-plugin`. Anthropic solo admite ahí repositorios privados o internos, así que antes cópialo a un repositorio privado de la organización. Los demás añaden el conector como arriba.

### ChatGPT

Añade un conector personalizado (una aplicación que usa MCP) llamado **Mi Mapit** con la URL `https://api.mapit.me/mcp` e inicia sesión con tu cuenta de Mapit. Dónde están los conectores personalizados en ChatGPT depende de tu plan y de la versión de la aplicación.

### Claude Code

Instala el plugin de Mapit desde el marketplace [mapit-iot/ai-plugin](https://github.com/mapit-iot/ai-plugin):

```
/plugin marketplace add mapit-iot/ai-plugin
/plugin install mapit@mapit
```

Después ejecuta `/mcp`, elige **plugin:mapit:my-mapit** e inicia sesión. El plugin añade también dos skills que ayudan al asistente a responder preguntas sobre tu moto y a calcular totales de tus rutas.

### OpenAI Codex

Instala el plugin desde el mismo marketplace [mapit-iot/ai-plugin](https://github.com/mapit-iot/ai-plugin):

```
codex plugin marketplace add mapit-iot/ai-plugin
codex plugin add mapit@mapit
```

Después inicia sesión con tu cuenta de Mapit la primera vez que lo uses.

### Cualquier otro cliente MCP

Añade un servidor MCP remoto con la URL `https://api.mapit.me/mcp`. Usa el transporte Streamable HTTP e inicio de sesión con OAuth: el cliente abre la página de inicio de sesión de Mapit, tú lo autorizas y guarda un token, nunca tu contraseña.

```
https://api.mapit.me/mcp
```

### Qué puede y qué no puede hacer el asistente

- **Solo lectura.** Puede leer tu cuenta, tus vehículos, tu suscripción, dónde informó por última vez cada vehículo, y tus rutas y estadísticas de conducción. No puede cambiar nada ni enviar órdenes a tu moto.
- **La ubicación y las rutas, solo si las marcas.** En la página de inicio de sesión eliges si compartes la ubicación y el historial de rutas. Si no las marcas, el asistente no puede verlas.
- **Último dato recibido, no en directo.** Una posición es lo último que envió el localizador, y el asistente dice cuándo. No puede seguir tu moto en directo.
- **Solo tu cuenta.** Ve tus vehículos, tal como los muestra la app de Mapit.
- **Tú tienes el control.** Consulta y termina cada conexión en [login.mapit.me/connections](https://login.mapit.me/connections). Se aplica en la siguiente petición.

Claude, ChatGPT y los demás asistentes conectados de esta forma están en la lista de [aplicaciones aprobadas](https://developers.mapit.me/es/approved-apps.md). El uso es para tus fines personales y no comerciales, según las [condiciones de uso de la API](https://developers.mapit.me/es/terms.md) y el [aviso de privacidad de la API](https://developers.mapit.me/es/privacy.md).

## Programa con un agente de IA

Dale a tu agente de programación estas direcciones. Cada página de la documentación está también en Markdown: añade `.md` a su dirección. Los tres archivos de abajo están en inglés, como las instrucciones para el agente; las copias en Markdown de estas páginas están en español.

- [`https://developers.mapit.me/llms.txt`](https://developers.mapit.me/llms.txt): un índice de todas las páginas, con una línea sobre cada una.
- [`https://developers.mapit.me/llms-full.txt`](https://developers.mapit.me/llms-full.txt): toda la documentación en un solo archivo Markdown.
- [`https://developers.mapit.me/openapi.json`](https://developers.mapit.me/openapi.json): la descripción OpenAPI, con todos los endpoints, parámetros y campos.

### Instrucciones para el agente

Pega esto en las instrucciones de tu agente (por ejemplo, `AGENTS.md` o `CLAUDE.md`) o al principio de una tarea:

```
You are writing code against the Mapit API (beta).
Docs index: https://developers.mapit.me/llms.txt
All docs in one file: https://developers.mapit.me/llms-full.txt
OpenAPI spec: https://developers.mapit.me/openapi.json

- Base URL: https://api.mapit.me/v1
- Auth: send a personal key as "Authorization: Bearer $MAPIT_KEY". Read the key
  from an environment variable. Never hard-code it, print it or log it.
- Rate limit: 30 requests a minute per key or access token, for the REST API and the MCP connector. Bursts above it may be tolerated, never rely on them. On 429, wait Retry-After seconds.
  Poll /status at most once a minute. See https://developers.mapit.me/limits.md
- Every 200 answer has an ETag: send it back in If-None-Match. 304 means
  nothing changed.
- Version 1 only gains fields: ignore fields you do not know.
- Ids and cursors are opaque: store them, never build or parse them.
  Follow nextCursor until it is null.
- Positions are last reported, not live: show when (lastLocationAt).
- Location and routes need permission on the key: 403 means it lacks it.
- Read-only, except disconnecting apps and keys. Never call DELETE unless
  the user asks.
- Personal, non-commercial use: the user's own vehicles only.
- Python: use the aiomapit package instead of raw HTTP.
```

### Python: aiomapit

En Python, lo más rápido es [aiomapit](https://pypi.org/project/aiomapit/), el cliente asíncrono oficial de Mapit (Python 3.12 o posterior). Tiene tipos, se encarga de la paginación y es el que usa la integración de [Home Assistant](https://developers.mapit.me/es/home-assistant.md). Antes, crea una [clave personal](https://developers.mapit.me/es/keys.md).

```
pip install aiomapit
```

```
import asyncio, os
from aiomapit import MapitClient

async def main():
    async with MapitClient(os.environ["MAPIT_KEY"]) as client:
        async for status in client.iter_statuses():
            if status.state:
                print(status.vehicle_id, status.state.latitude, status.state.longitude)

asyncio.run(main())
```

Con otros lenguajes, puedes generar un cliente a partir de [la referencia](https://developers.mapit.me/es/reference.md) o del archivo OpenAPI.
