# abilioo API — Referência

O abilioo é um contabilista digital (demo) para pequenos negócios em Portugal.
Esta API dá acesso programático à contabilidade de uma empresa: calendário fiscal,
relatórios, faturação, documentos de despesa, banco e e-Fatura.

> **Demo**: todos os dados são fictícios; faturas com ATCUD/QR simulados, sem valor fiscal.

## Autenticação

Cria uma chave em **Integrações** dentro da app (`/app/{empresa}/integracoes`) e envia-a em cada pedido:

```
Authorization: Bearer ab_live_…
```

Cada chave está ligada a **uma empresa** — não é preciso indicar IDs de empresa nos pedidos.
As chaves têm **scopes** (permissões):

| Scope | Dá acesso a |
|---|---|
| `read` | Todos os GET: relatórios, calendário, clientes, faturas, documentos, banco, e-Fatura, lacunas |
| `documents:write` | Enviar documentos de despesa para extração automática |
| `invoices:write` | Emitir faturas e criar/atualizar clientes |
| `banks:write` | Importar extratos e aceitar sugestões de reconciliação |
| `chat` | Conversar com o assistente abilioo |

## Convenções

- Base: `https://abilioo.com/api/v1`
- Envelope de resposta: `{ "success": true, "data": … }` ou `{ "success": false, "error": { "code", "message" } }`
- Códigos de erro: `unauthorized`, `invalid_api_key`, `expired_api_key`, `revoked_api_key`, `insufficient_scope`, `rate_limited`, `validation_error`, `not_found`, `internal_error`
- **Dinheiro em cêntimos** (`totalCents: 147600` = 1 476,00 €); campos formatados em euros quando o nome não acaba em `Cents`
- Datas `YYYY-MM-DD`; nomes de campos frequentemente em português (`fornecedor`, `clientes`, `movimentos`)
- Rate limit: 60 pedidos/min por chave (429 + headers `X-RateLimit-*`)
- OpenAPI 3.1: `https://abilioo.com/api/v1/openapi.json`

## Endpoints

### GET /company — dados da empresa `(read)`
Nome, NIF, forma legal, CAE, regime de IVA.

### GET /fiscal-calendar — obrigações fiscais `(read)`
Obrigações dos próximos 120 dias (IVA, Segurança Social, retenções, IRC/IRS, IES) com `dueDate`, `daysLeft` e `done`.

### GET /reports/financial — relatório financeiro do ano `(read)`
Receitas/despesas líquidas, resultado, balanço de IVA, por cobrar, evolução mês a mês, top categorias de despesa.

### GET /clients · POST /clients `(read · invoices:write)`
Lista clientes com totais faturados. POST cria/atualiza (match por NIF ou nome):
```json
{ "name": "Junta de Freguesia", "nif": "501234567", "email": "geral@jf.pt" }
```

### GET /invoices · POST /invoices `(read · invoices:write)`
GET: últimas 50 faturas. POST emite uma fatura — cria o cliente se não existir, numeração sequencial, IVA default 23%:
```json
{
  "clientName": "Junta de Freguesia",
  "type": "FT",
  "dueDays": 30,
  "lines": [{ "description": "Coffee break reunião", "quantity": 1, "unitEuros": 120, "vatRate": 23 }]
}
```
Devolve 201 com `{ display: "FT 2026/13", total: "147,60 €" }`.

### GET /documents · POST /documents `(read · documents:write)`
GET: últimos 50 documentos de despesa (filtro `?status=processing|needs_review|archived|error`).
POST envia um documento para extração automática (fornecedor, valores, categoria) — multipart `file` **ou** JSON:
```json
{ "fileName": "fatura.pdf", "mimeType": "application/pdf", "dataBase64": "…" }
```
PDF/JPG/PNG/WebP, máx. 12 MB. Devolve 201 com o documento ingerido.

### GET /bank/overview `(read)`
Saldo e últimos 25 movimentos com estado de reconciliação (filtro `?status=unmatched|suggested|matched|ignored`).

### POST /bank/import `(banks:write)`
Importa extrato CSV (multipart `file` ou JSON `{ "csv": "...", "fileName?" }`). Formato por linha: `data;descrição;montante`. Faz auto-matching e devolve `{ imported, matched, suggested, unmatched }`.

### POST /bank/suggestions/accept `(banks:write)`
Aceita todas as sugestões de reconciliação pendentes. Devolve `{ conciliadas }`.

### GET /efatura `(read)`
Movimentos e-Fatura (simulado): despesas comunicadas à AT com flag `registadoNoAbilioo`.

### GET /compliance/gaps `(read)`
Cruza e-Fatura ↔ documentos ↔ faturas ↔ banco: `efaturaSemRegisto`, `despesasSemMovimentoBancario`, `faturasVencidasPorReceber`, `movimentosBancariosPorClassificar`.

### POST /tax-expert `(read)`
`{ "question": "Posso deduzir IVA de refeições com clientes?" }` → resposta de um especialista de legislação fiscal PT.

### POST /chat `(chat)`
Conversa com o assistente abilioo (não-streaming). `{ "message": "...", "history?": [{role, content}] }` → `{ reply, card, engine }`. O assistente pode consultar tudo e emitir faturas.

## Servidor MCP

Endpoint **Streamable HTTP**: `https://abilioo.com/api/mcp` com o mesmo header `Authorization`.
As tools registadas refletem os scopes da chave (uma chave só-`read` não expõe `create_invoice`).

```bash
claude mcp add --transport http abilioo https://abilioo.com/api/mcp \
  --header "Authorization: Bearer ab_live_…"
```

Claude Desktop / Cursor:
```json
{
  "mcpServers": {
    "abilioo": {
      "url": "https://abilioo.com/api/mcp",
      "headers": { "Authorization": "Bearer ab_live_…" }
    }
  }
}
```

Tools: `get_company_briefing`, `get_fiscal_calendar`, `get_financial_report`, `list_clients`, `upsert_client`, `create_invoice`, `get_bank_overview`, `accept_bank_suggestions`, `get_efatura_movements`, `find_compliance_gaps`, `ask_tax_expert`, `upload_document`.

## Skill para agentes

Skill instalável (Claude Code ou outro agente que leia `SKILL.md`):

```bash
mkdir -p ~/.claude/skills/abilioo && cd ~/.claude/skills/abilioo && \
curl -fsSO https://abilioo.com/ai/skill/abilioo/SKILL.md && \
curl -fsSO https://abilioo.com/ai/skill/abilioo/reference.md
```

Contexto para LLMs: `https://abilioo.com/llms.txt` (índice) e `https://abilioo.com/llms-full.txt` (referência completa).