API do AI Budget para programadores
O AI Budget tem uma API REST pública com autorização OAuth 2.0 – «Ligar ao AI Budget». Com o consentimento do utilizador, a sua aplicação pode ler e escrever as despesas dele e obter os talões e as categorias. O utilizador escolhe o que partilha e pode revogar o acesso a qualquer momento.
Referência da APIRegistar uma aplicaçãoComo a construímos
O que a API já faz hoje
- Ler, criar, alterar e eliminar despesas (
/public/v1/expenses). - Sincronizar através do feed de alterações
/public/v1/expenses/changes: consulte-o periodicamente e receba as despesas novas, alteradas e eliminadas – as eliminações chegam como entradasdelete(tombstones). - Transferir as imagens dos talões anexados às despesas.
- Ler as categorias de despesa da conta.
- Abranger várias contas numa só ligação: o utilizador assinala as contas que partilha (pessoal, empresa, família…) e cada pedido indica a conta no cabeçalho
X-Account-Id.GET /public/v1/accountsdevolve as contas partilhadas com o respetivo tipo. - Ler, adicionar, alterar e eliminar receitas (
/public/v1/incomes), com um feed de alterações próprio; as receitas criadas por uma transferência entre contas são só de leitura. - Ler orçamentos com o progresso do período atual, e criá-los, alterá-los e eliminá-los (
/public/v1/budgets). - Ler totais de análise (
/public/v1/analytics/summary,by-category,monthly) convertidos para a moeda de apresentação do utilizador. - Permissões (scopes):
expenses:read,expenses:write,receipts:read,categories:read,incomes:read,incomes:write,budgets:read,budgets:write,analytics:read.
Por agora, a API abrange despesas, talões, categorias, receitas, orçamentos e totais de análise. Objetivos e outros recursos poderão chegar mais tarde.
Gratuita e sem revisão
O acesso à API é gratuito. Qualquer programador regista a aplicação no AI Budget (Definições → Programadores) – sem revisão manual nem esperas. Os limites de pedidos aplicam-se por ligação e por aplicação.
A privacidade do utilizador
É o utilizador que decide que contas partilha, e pode desligar a sua aplicação a qualquer momento em Definições → Aplicações ligadas (como funciona). As contas com encriptação ponta a ponta continuam protegidas: uma conta com encriptação de texto só pode ser ligada em modo de leitura, e uma conta totalmente encriptada não pode ser ligada.
Comece em 3 passos
- Registe uma aplicação em Definições → Programadores: indique um nome e um redirect URI e recebe um
client_ide umclient_secret. - Envie o utilizador para o URL de autorização
https://app.ai-budget.pl/authorizecom PKCE. O utilizador inicia sessão, assinala as contas e aprova as permissões. - Troque o código por um token em
POST /oauth/tokene chamehttps://api.ai-budget.pl/public/v1com o cabeçalhoAuthorization: Bearer ….
# 1. Send the user to the consent page (PKCE S256)
https://app.ai-budget.pl/authorize?response_type=code&client_id=aba_ci_...
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
&scope=expenses%3Aread+categories%3Aread&state=...
&code_challenge=...&code_challenge_method=S256
# 2. Exchange the code for tokens
curl -X POST https://api.ai-budget.pl/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=authorization_code -d code="$CODE" \
-d redirect_uri=https://example.com/callback -d code_verifier="$CODE_VERIFIER"
# 3. Call the API for one of the connected accounts
curl https://api.ai-budget.pl/public/v1/accounts -H "Authorization: Bearer $ACCESS_TOKEN"
curl https://api.ai-budget.pl/public/v1/expenses -H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Account-Id: $ACCOUNT_ID"Primeira integração: eKsięgowy AI
eKsięgowy AI liga, através da API, a conta da empresa e a conta pessoal de um utilizador e mantém-nas estritamente separadas.
Documentação
Todos os endpoints (Swagger), com um guia passo a passo: