{"openapi":"3.1.0","info":{"title":"abilioo API","version":"1.0.0","description":"API pública do abilioo — o contabilista digital para pequenos negócios em Portugal. Autenticação via chave de API (`Authorization: Bearer ab_live_…`), criada em Integrações. Cada chave está ligada a uma empresa e a um conjunto de scopes. Valores monetários em cêntimos (Int). Demo: dados fictícios, sem valor fiscal."},"servers":[{"url":"https://abilioo.com/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ab_live_…"}}},"paths":{"/company":{"get":{"summary":"Dados da empresa da chave","description":"Scope: read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Empresa","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"id":"cmp_x","name":"Café Central Lda","nif":"509876543","vatRegime":"trimestral"}}}}},"401":{"description":"Chave em falta ou inválida","content":{"application/json":{"schema":{"type":"object"},"example":{"success":false,"error":{"code":"invalid_api_key","message":"Chave de API inválida."}}}}}}}},"/fiscal-calendar":{"get":{"summary":"Obrigações fiscais dos próximos 120 dias","description":"Scope: read — IVA, SS, retenções, IRC/IRS, IES conforme regime e forma legal.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Calendário","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"vatRegime":"trimestral","obligations":[{"key":"iva-2026T2","title":"IVA 2.º trimestre","kind":"iva","dueDate":"2026-08-20","daysLeft":38,"done":false}]}}}}}}}},"/reports/financial":{"get":{"summary":"Relatório financeiro do ano","description":"Scope: read — receitas, despesas, IVA, por cobrar, mês a mês, top categorias.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Relatório","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"ano":2026,"receitasLiquidas":"24 300,00 €","porCobrar":"3 200,00 €"}}}}}}}},"/clients":{"get":{"summary":"Lista de clientes","description":"Scope: read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Clientes","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"clientes":[{"nome":"Junta de Freguesia","nif":"501234567","faturas":3}]}}}}}}},"post":{"summary":"Criar ou atualizar cliente","description":"Scope: invoices:write — faz match por NIF ou nome.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"nif":{"type":"string"},"email":{"type":"string"},"address":{"type":"string"}}}}}},"responses":{"200":{"description":"Cliente criado/atualizado","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"acao":"criado","nome":"Junta de Freguesia"}}}}}}}},"/invoices":{"get":{"summary":"Últimas 50 faturas emitidas","description":"Scope: read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Faturas","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"faturas":[{"display":"FT 2026/12","cliente":"Junta de Freguesia","totalCents":147600}]}}}}}}},"post":{"summary":"Emitir fatura","description":"Scope: invoices:write — cria o cliente se não existir; numeração sequencial por série. IVA default 23%.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientName","lines"],"properties":{"clientName":{"type":"string"},"clientNif":{"type":"string"},"type":{"type":"string","enum":["FT","FR"]},"dueDays":{"type":"integer"},"lines":{"type":"array","items":{"type":"object","required":["description","unitEuros"],"properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unitEuros":{"type":"number"},"vatRate":{"type":"number","enum":[0,6,13,23]}}}}}},"example":{"clientName":"Junta de Freguesia","lines":[{"description":"Coffee break reunião","unitEuros":120}]}}}},"responses":{"201":{"description":"Fatura emitida","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"display":"FT 2026/13","total":"147,60 €"}}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"type":"object"},"example":{"success":false,"error":{"code":"insufficient_scope","message":"Esta chave não tem o scope \"invoices:write\" necessário para esta operação."}}}}}}}},"/documents":{"get":{"summary":"Últimos 50 documentos de despesa","description":"Scope: read — filtro opcional ?status=processing|needs_review|archived|error","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Documentos","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"documentos":[{"fileName":"fatura-edp.pdf","status":"archived","totalCents":8934}]}}}}}}},"post":{"summary":"Enviar documento de despesa (extração automática)","description":"Scope: documents:write — multipart 'file' OU JSON {fileName, mimeType, dataBase64}. PDF/JPG/PNG/WebP, máx. 12 MB.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","required":["fileName","mimeType","dataBase64"],"properties":{"fileName":{"type":"string"},"mimeType":{"type":"string"},"dataBase64":{"type":"string"}}}}}},"responses":{"201":{"description":"Documento ingerido","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"id":"doc_x","status":"archived","supplierName":"EDP Comercial"}}}}}}}},"/bank/overview":{"get":{"summary":"Saldo e últimos 25 movimentos bancários","description":"Scope: read — filtro opcional ?status=unmatched|suggested|matched|ignored","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Visão bancária","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"banco":"Millennium BCP","saldo":"12 430,00 €","movimentos":[]}}}}}}}},"/bank/import":{"post":{"summary":"Importar extrato CSV","description":"Scope: banks:write — multipart 'file' OU JSON {csv, fileName?}. Formato por linha: data;descrição;montante. Faz auto-matching.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Resultado da importação","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"imported":12,"matched":7,"suggested":3,"unmatched":2}}}}}}}},"/bank/suggestions/accept":{"post":{"summary":"Aceitar todas as sugestões de reconciliação","description":"Scope: banks:write","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Conciliadas","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"conciliadas":3}}}}}}}},"/efatura":{"get":{"summary":"Movimentos e-Fatura (simulado)","description":"Scope: read — despesas comunicadas à AT, com flag registadoNoAbilioo.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Movimentos","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"movimentos":[{"fornecedor":"Via Verde Portugal","total":"41,00 €","registadoNoAbilioo":false}]}}}}}}}},"/compliance/gaps":{"get":{"summary":"Lacunas de conformidade","description":"Scope: read — e-Fatura sem registo, despesas sem movimento bancário, faturas vencidas, movimentos por classificar.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lacunas","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"efaturaSemRegisto":[],"faturasVencidasPorReceber":[]}}}}}}}},"/tax-expert":{"post":{"summary":"Pergunta ao especialista de legislação fiscal","description":"Scope: read","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"type":"string"}}},"example":{"question":"Posso deduzir IVA de refeições com clientes?"}}}},"responses":{"200":{"description":"Resposta","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"resposta":"…"}}}}}}}},"/chat":{"post":{"summary":"Conversar com o assistente abilioo","description":"Scope: chat — o assistente tem acesso aos dados da empresa e pode emitir faturas, consultar relatórios, etc. Não-streaming.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}}}}}},"example":{"message":"Que obrigações fiscais tenho este mês?"}}}},"responses":{"200":{"description":"Resposta do assistente","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"data":{"reply":"Tens o IVA do 2.º trimestre até 20 de agosto…","card":null}}}}}}}}}}