# Usar a Mapit com IA

Duas formas de usar a Mapit com IA: perguntar a um assistente pela própria mota, ou pôr um agente de programação a escrever o código que a consulta.

> **Beta, gratuita por agora.** O meu Mapit e o serviço por trás dele são uma beta: podem mudar ou deixar de funcionar, não têm garantia de disponibilidade e, por agora, a Mapit não os cobra. Não depender deles para emergências nem para recuperar uma mota roubada: para isso, usar a aplicação Mapit. Ver as [condições da beta](https://developers.mapit.me/pt/terms.md).

## Perguntar a um assistente pela mota

**O meu Mapit** liga um assistente de IA à conta Mapit. Perguntar «Onde está a minha mota?», «Que trajetos fiz ontem?» ou «Quando termina a minha subscrição?». Iniciar sessão com a conta Mapit na página da Mapit e escolher o que o assistente pode ver. Ele nunca recebe a palavra-passe.

### Plugin ou conector

O meu Mapit existe de duas formas. O **plugin** reúne o conector O meu Mapit e duas skills. O marketplace `mapit-iot/ai-plugin` (um repositório do GitHub) é adicionado no Claude Code e no Codex, mais abaixo. No claude.ai, um administrador da organização adiciona-o em Definições da organização > Plugins e skills > Marketplaces, a partir de uma cópia privada (ver claude.ai mais abaixo). Se o assistente não tiver plugins, adicionar antes o **conector** pelo respetivo URL, como no claude.ai e no ChatGPT mais abaixo.

### claude.ai

Nas Definições, abrir Conectores e adicionar um conector personalizado chamado **O meu Mapit** com o URL `https://api.mapit.me/mcp`. Depois ligá-lo e iniciar sessão com a conta Mapit.

**Os proprietários dos planos Team e Enterprise** podem dar o plugin a toda a organização: nas Definições da organização, abrir Plugins e skills, depois Marketplaces, e adicionar o repositório do GitHub que contém uma cópia de `mapit-iot/ai-plugin`. A Anthropic só aceita aí repositórios privados ou internos, pelo que é preciso copiá-lo primeiro para um repositório privado da organização. Os restantes adicionam o conector como acima.

### ChatGPT

Adicionar um conector personalizado (uma aplicação que usa MCP) chamado **O meu Mapit** com o URL `https://api.mapit.me/mcp` e iniciar sessão com a conta Mapit. O sítio onde estão os conectores personalizados no ChatGPT depende do plano e da versão da aplicação.

### Claude Code

Instalar o plugin da Mapit a partir do marketplace [mapit-iot/ai-plugin](https://github.com/mapit-iot/ai-plugin):

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

Depois executar `/mcp`, escolher **plugin:mapit:my-mapit** e iniciar sessão. O plugin também adiciona duas skills que ajudam o assistente a responder a perguntas sobre a mota e a calcular totais dos trajetos.

### OpenAI Codex

Instalar o plugin a partir do mesmo 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
```

Depois, iniciar sessão com a conta Mapit na primeira utilização.

### Qualquer outro cliente MCP

Adicionar um servidor MCP remoto com o URL `https://api.mapit.me/mcp`. Usar o transporte Streamable HTTP e início de sessão com OAuth: o cliente abre a página de início de sessão da Mapit, autoriza-o e ele guarda um token, nunca a palavra-passe.

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

### O que o assistente pode e não pode fazer

- **Só leitura.** Pode consultar a conta, os veículos, a subscrição, onde cada veículo comunicou pela última vez, e os trajetos e estatísticas de condução. Não pode alterar nada nem enviar comandos à mota.
- **Localização e trajetos só se forem marcados.** Na página de início de sessão escolhe-se se a localização e o histórico de trajetos são partilhados. Se não forem marcados, o assistente não os pode ver.
- **Último dado comunicado, não em direto.** Uma posição é o que o localizador enviou por último, e o assistente diz quando. Não pode seguir a mota em direto.
- **Só a conta do cliente.** Vê os veículos do cliente, tal como a aplicação Mapit os mostra.
- **O controlo é do cliente.** Ver e terminar cada ligação em [login.mapit.me/connections](https://login.mapit.me/connections). Aplica-se no pedido seguinte.

O Claude, o ChatGPT e os outros assistentes ligados desta forma estão na lista de [aplicações aprovadas](https://developers.mapit.me/pt/approved-apps.md). A utilização é para fins pessoais e não comerciais, nos termos das [condições de utilização da API](https://developers.mapit.me/pt/terms.md) e do [aviso de privacidade da API](https://developers.mapit.me/pt/privacy.md).

## Programar com um agente de IA

Dar estes endereços ao agente de programação. Cada página da documentação também está disponível em Markdown: acrescentar `.md` ao endereço. Os três ficheiros abaixo estão em inglês, tal como as instruções para o agente; as cópias em Markdown destas páginas estão em português.

- [`https://developers.mapit.me/llms.txt`](https://developers.mapit.me/llms.txt): um índice de todas as páginas, com uma linha sobre cada uma.
- [`https://developers.mapit.me/llms-full.txt`](https://developers.mapit.me/llms-full.txt): toda a documentação num só ficheiro Markdown.
- [`https://developers.mapit.me/openapi.json`](https://developers.mapit.me/openapi.json): a descrição OpenAPI, com todos os endpoints, parâmetros e campos.

### Instruções para o agente

Colar isto nas instruções do agente (por exemplo, `AGENTS.md` ou `CLAUDE.md`) ou no início de uma tarefa:

```
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

Em Python, o caminho mais rápido é o [aiomapit](https://pypi.org/project/aiomapit/), o cliente assíncrono oficial da Mapit (Python 3.12 ou mais recente). Tem tipos, trata da paginação e é o que a integração do [Home Assistant](https://developers.mapit.me/pt/home-assistant.md) usa. Criar primeiro uma [chave pessoal](https://developers.mapit.me/pt/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())
```

Noutras linguagens, é possível gerar um cliente a partir da [referência](https://developers.mapit.me/pt/reference.md) ou do ficheiro OpenAPI.
