# API B2B SeuVolante — Skill

Documento de referência para integrar diagnósticos veiculares via API REST ou
via MCP (Model Context Protocol). Destinado às empresas parceiras e aos
agentes que elas operam sobre esta API. Cobre autenticação, os dois formatos
de acesso à mesma funcionalidade e o formato de erro.

## 1. Autenticação

Toda chamada — REST ou MCP — exige uma chave de API no header `Authorization`:

```
Authorization: Bearer sv_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

- A chave tem o prefixo `sv_live_` e é emitida por empresa parceira.
- Chave ausente, malformada, inválida ou pertencente a uma empresa inativa
  retorna `401` com o formato de erro descrito na seção 4.
- Não há escopo por endpoint: uma chave válida dá acesso a todos os
  endpoints REST e a todas as tools MCP descritos aqui.

## 2. API REST

Base: `https://seuvolante.com/api/v1`

### `POST /api/v1/diagnosticos`

Cria um diagnóstico a partir do veículo e da descrição do problema relatado
pelo cliente final, e roda o processamento de forma síncrona.

Request:

```json
{
  "veiculo": "Fiat Uno 2015",
  "descricao_problema": "Barulho de metal ao frear, mais forte em baixa velocidade.",
  "km_veiculo": 82000
}
```

| Campo                | Tipo   | Obrigatório | Restrição                          |
| --------------------- | ------ | ----------- | ----------------------------------- |
| `veiculo`             | string | sim         | 2–200 caracteres                    |
| `descricao_problema`  | string | sim         | 10–5000 caracteres                  |
| `km_veiculo`          | number | não         | inteiro positivo, até 9.999.999     |

Response `201`, quando o processamento fecha o laudo direto:

```json
{
  "id": "b1f2c3d4-...",
  "status": "done",
  "relatorio": { "vision": { }, "context": { }, "diagnostic": { }, "budget": { }, "report": { "htmlContent": "..." }, "priceSearch": null, "clarification": null },
  "relatorio_texto": "Diagnóstico: ...\n\nOrçamento estimado: ..."
}
```

Response `201`, quando falta informação para fechar o laudo:

```json
{
  "id": "b1f2c3d4-...",
  "status": "aguardando_info",
  "perguntas": [
    { "id": "q1", "question": "O barulho acontece também em ré?", "rationale": "Ajuda a isolar se é pastilha ou tambor.", "options": ["Sim", "Não"] }
  ]
}
```

`relatorio_texto` é a versão em texto simples, pronta para exibir ao cliente
final. `relatorio` é a versão estruturada (o mesmo conteúdo, quebrado em
campos) — use a que fizer sentido para a sua integração.

### `GET /api/v1/diagnosticos/{id}`

Consulta um diagnóstico criado por esta mesma empresa. `id` é o valor
retornado por `POST /api/v1/diagnosticos`; um `id` de outra empresa (ou
inexistente) responde `404`.

Response `200`:

```json
{ "id": "b1f2c3d4-...", "status": "processando" }
```

`status` é um de: `processando`, `aguardando_info`, `done`, `failed`. Os
corpos de `aguardando_info` e `done` seguem o mesmo formato do `POST`.

## 3. MCP

Endpoint: `https://seuvolante.com/api/mcp`

Transporte Streamable HTTP (stateless — cada requisição é independente, sem
sessão a manter). A autenticação é a mesma da API REST: header
`Authorization: Bearer sv_live_xxx` na requisição HTTP, não no payload MCP.

Duas tools, com o mesmo contrato de dados dos endpoints REST equivalentes:

### `criar_diagnostico`

Mesmo contrato de `POST /api/v1/diagnosticos`.

Exemplo de chamada (`tools/call`):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "criar_diagnostico",
    "arguments": {
      "veiculo": "Fiat Uno 2015",
      "descricao_problema": "Barulho de metal ao frear, mais forte em baixa velocidade.",
      "km_veiculo": 82000
    }
  }
}
```

O resultado da tool traz o mesmo corpo do `POST /api/v1/diagnosticos` em
`structuredContent`, e o mesmo JSON serializado como texto em `content`.

### `consultar_diagnostico`

Mesmo contrato de `GET /api/v1/diagnosticos/{id}`. Argumento: `id` (string,
o valor retornado por `criar_diagnostico`).

Em erro (chave inválida à parte — essa já barra a conexão com `401` antes de
qualquer tool ser chamada), o resultado da tool vem com `isError: true` e o
mesmo formato de erro da seção 4 serializado em `content`.

## 4. Formato de erro

Toda resposta de erro — REST ou MCP — segue o mesmo formato:

```json
{ "error": "Descrição do problema.", "code": "codigo_da_categoria" }
```

| `code`             | Quando acontece                                              |
| ------------------ | -------------------------------------------------------------- |
| `unauthorized`     | Chave de API ausente, malformada, inválida ou inativa (`401`)  |
| `validation_error` | Corpo da requisição fora do formato esperado (`422`)           |
| `not_found`        | `id` inexistente ou pertencente a outra empresa (`404`)        |
| `internal_error`   | Falha ao registrar o diagnóstico (`500`)                       |
| `pipeline_failed`  | Falha ao processar o diagnóstico já registrado (`500`)         |

## 5. Regra de uso do conteúdo

Nenhum texto repassado ao cliente final da empresa parceira — laudo, resposta
de esclarecimento, mensagem de erro ou qualquer outro conteúdo desta API —
deve mencionar "IA", "inteligência artificial", "robô", "algoritmo" ou termos
equivalentes. `relatorio_texto` e os campos de `relatorio` já são escritos
para chegar prontos ao cliente final nesse formato; não adicione essas
referências ao reformatar ou compor sua própria mensagem em cima deles.