# Guia de uso

API REST em JSON do AgendAI, sistema de gestão de uma consultoria: agenda dos
consultores, horas realizadas, CRM, faturamento e cobrança. Esta documentação
cobre **só leitura**: horas dos consultores, comercial (oportunidades, metas,
comissões, dashboard) e inadimplência. Chamar rotas que não estão aqui não é
suportado.

- **URL base:** `https://api-prod.agendai.pro`
- **Especificação OpenAPI 3.1:** `/openapi.json` (deste site)
- **Tudo em um arquivo Markdown:** `/llms-full.txt`

## 1. Autenticação

1. Faça `POST /login` com `{"email": "...", "password": "..."}`. A resposta é
   **201** com `{"token": "<jwt>"}`.
2. Envie o token em toda chamada: `Authorization: Bearer <jwt>`.
3. O token vale **7 dias** e não há refresh. Guarde-o e reutilize-o. Quando
   uma chamada responder **401**, faça login de novo e repita a chamada uma
   vez; se o 401 persistir, pare e avise (credencial trocada ou usuário
   desativado).

```bash
TOKEN=$(curl -s -X POST https://api-prod.agendai.pro/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"integracao@exemplo.com.br","password":"sua-senha"}' | jq -r .token)

curl -s https://api-prod.agendai.pro/metas/dashboard \
  -H "Authorization: Bearer $TOKEN"
```

As credenciais são entregues fora desta documentação. Nunca as grave em
código versionado nem em logs.

## 2. O que o token enxerga

- **Organização:** cada usuário pertence a uma organização (tenant) e toda
  resposta já vem filtrada por ela. Não existe parâmetro de tenant.
- **Permissões:** o que cada rota devolve depende das telas e do papel do
  usuário do token, conferidos a cada chamada no banco (mudar a permissão do
  usuário vale na hora, sem novo login). Sem permissão, a rota responde 403
  ou devolve só os registros que o usuário pode ver; a descrição de cada rota
  diz qual dos dois.

## 3. Convenções dos dados

- **Datas e horas da agenda são "hora de parede":** o horário digitado no
  AgendAI é gravado como se fosse UTC. Um agendamento das 09:00 em Brasília
  chega como `2026-03-10T09:00:00.000Z`. Leia os componentes (data e hora)
  direto da string; **não converta de UTC para America/Sao_Paulo**, senão o
  horário fica 3 horas adiantado ou atrasado.
- **Datas em parâmetros:** `YYYY-MM-DD`, salvo quando a rota diz outra coisa.
- **Valores decimais** guardados como decimal no banco podem vir como
  **string** (`"1500.50"`). A descrição de cada campo indica o tipo e a
  unidade (minutos ou horas, reais ou centavos, percentual 0–100 ou 0–1).
- **Ids:** alguns recursos usam UUID e outros inteiros; use o tipo indicado
  em cada rota.
- **Campos ausentes:** campos `null` vêm como `null`; não presuma zero.

## 4. Erros

Todo erro tem o corpo:

```json
{ "status": 403, "path": "/rota", "message": "texto ou lista", "code": "OPCIONAL" }
```

| Status | Significado | O que fazer |
|---|---|---|
| 400 | Parâmetro inválido. `message` é uma lista `campo: motivo`. | Corrija a chamada; não repita igual. |
| 401 | Sem token, token inválido ou expirado, usuário desativado. | Faça login de novo e repita uma vez. |
| 403 | O usuário não tem a permissão da rota. | Não repita; peça acesso ao administrador do AgendAI. |
| 404 | Registro não existe (ou é de outra organização). | Não repita. |
| 5xx | Erro do servidor. | Repita com espera crescente (1 s, 2 s, 4 s), no máximo 3 vezes. |

Quando houver `code`, decida pelo `code`, não pelo texto da mensagem.

## 5. Boas práticas para agentes

- Para mostrar dados a uma pessoa, use os nomes que já vêm nas respostas
  (objetos `{ id, nome }`) e as rotas `filter-options` para traduzir ids.
- Prefira filtrar no servidor (parâmetros de período, vendedor, status) a
  baixar tudo e filtrar localmente.
- Respeite a paginação: siga `page`/`pageSize` (ou o que a rota indicar) até
  o total informado.
- Não faça mais de algumas requisições por segundo; os dados mudam ao longo
  do dia, não a cada segundo.