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):

{ "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%:

{
  "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:

{ "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).

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

Claude Desktop / Cursor:

{
  "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):

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).