Explorar a referência
Documentação para programadores
A API do vokse
Tudo no vokse está à distância de uma chamada à API. A aplicação web, os clientes externos e a nossa IA usam todos a mesma superfície REST, e pode fazer o mesmo. Autentique-se com uma chave Bearer, restrinja-a exatamente àquilo de que precisa e integre em minutos.
Autenticação
Todos os pedidos levam um token Bearer no cabeçalho Authorization. Crie uma chave de API em Definições → Chaves de API, escolha os âmbitos e pode começar.
URL base
https://api.vokse.aiUm primeiro pedido
bash
curl -H "Authorization: Bearer vokse_sk_…" \ https://api.vokse.ai/households/current/accountsRecursos
188 endpoints em 28 recursos. Escolha um recurso para ver todas as operações, o âmbito de cada uma, os parâmetros e um exemplo pronto a copiar.
Contas14 endpoints
Assistente de IA12 endpoints
- GETList pending AI actions awaiting user confirmation. Paginated with opaque cursor.
- POSTCancel a pending destructive action.
- POSTConfirm and execute a pending assistant action.
- POSTStream a chat turn (SSE). Returns text/event-stream. 403 AI_CONSENT_REQUIRED until the ai_processing consent is granted.
- +8
Análises de IA2 endpoints
Ligações bancárias15 endpoints
- GETList bank accounts in the household
- PATCHPause / resume sync for one bank account
- DELETEUnlink a bank account from its vokse account (the account and imported transactions stay; new movements stop arriving until mapped again)
- POSTMap a bank account to an existing financial_account or create a new one
- +11
Orçamentos9 endpoints
Categorias7 endpoints
Grupos de categorias4 endpoints
Taxas de câmbio2 endpoints
Previsões1 endpoint
Objetivos4 endpoints
Histórico (anular / refazer)3 endpoints
- GETChange history, newest first: every recorded change with its performer; filter by member, family, kind, time window, group or explicit ids
- POSTRedo an undone change: reverts its active reversal so the change is in force again (409 HISTORY_NOT_UNDONE when it is not undone, HISTORY_STALE when the data moved on)
- POSTUndo a recorded change: applies its exact inverse, writes the reversal to the history and marks the change undone (409 HISTORY_STALE when the data moved on, HISTORY_ALREADY_UNDONE when another client got there first)
Membros1 endpoint
Notificações6 endpoints
Beneficiários13 endpoints
Recibos (OCR)16 endpoints
- GETLine items read from receipts, newest purchase first; unit prices are also given per base unit (kg, l, unit).
- GETUnit price of a product over time (per base unit, quantity-weighted per bucket) with the merchants it was bought at.
- GETPer-product summary across receipts: purchases, total spend, quantity-weighted average / min / max / latest unit price over the base unit, where it was bought.
- GETList receipts in this household; filter by link state, extraction status, kind, day, amount, merchant, tags or free text; sort by date, amount or merchant.
- +12
Recorrências13 endpoints
Relatórios9 endpoints
- GETPlan vs reality: per-month assigned vs spent totals, adherence share of budgeted categories, and the biggest overruns of the range. Max 5-year range.
- GETPer-month income vs expense vs net (in base currency) over the range. Optional accountIds CSV (only these accounts). Max 5-year range.
- GETMonth-over-month spend per category (dense, zero-filled series in base currency). Optional accountIds CSV (only these accounts) and categoryIds CSV filters. Max 5-year range.
- GETIncome by source over the range (ADR 0107): unlabelled inflows plus every income category, month by month in the base currency. Optional accountIds CSV. Max 5-year range.
- +5
Regras8 endpoints
Pesquisa1 endpoint
Etiquetas4 endpoints
Marcadores de movimentos2 endpoints
Movimentos20 endpoints
Importação de movimentos1 endpoint
Utilizadores3 endpoints
Voz6 endpoints
Guias
Explicações passo a passo, escritas à mão, para os temas transversais: autenticação, erros, paginação, idempotência e webhooks.
AutenticaçãoA API do vokse autentica cada pedido com uma chave de API Bearer. As chaves têm âmbitos definidos, podem ser revogadas e nunca expiram em silêncio. Mantém o controlo exato daquilo a que cada integração pode aceder.AgregadosO agregado é a unidade de isolamento dos dados, o tenant do sistema: contas, movimentos, orçamentos, categorias, regras e chaves pertencem todos a exatamente um. A sua chave também pertence a um, eis o que isso lhe permite fazer, e o que não permite.ErrosTodos os erros da API do vokse devolvem um envelope JSON consistente, com um código estável legível por máquina, uma mensagem legível por pessoas e detalhes estruturados opcionais. Programe contra o código, mostre a mensagem.PaginaçãoOs endpoints de listagem paginam com um cursor opaco. Nunca calcula deslocamentos: segue o nextCursor até ele ser null. Os cursores mantêm-se estáveis perante escritas simultâneas, por isso nunca salta nem lê a mesma linha duas vezes.IdempotênciaOs pedidos que alteram dados podem tornar-se seguros de repetir com uma Idempotency-Key. Se um pedido se perder num timeout, repeti-lo com a mesma chave devolve o resultado original em vez de criar um duplicado.Limites de pedidosCada pedido é contado numa janela fixa de 60 segundos. O contador que se aplica depende da forma como se autentica: as chaves de API têm o limite mais alto, quem tem sessão iniciada um limite generoso e o tráfego anónimo um limite pequeno. Quando o limite se esgota, a API responde 429 e diz quanto tempo esperar.Receber webhooksOs webhooks enviam-lhe os eventos em tempo real, em vez de andar a sondar a API. Subscreva um URL, escolha os eventos que lhe interessam e verifique cada entrega com a respetiva assinatura HMAC.Histórico, anular e refazer na APIO vokse mantém um livro de alterações por agregado: uma linha por alteração atómica com a carga exata para a reverter, quem a fez e quando. A API expõe as linhas produzidas por uma escrita, lista o histórico com os autores e reverte qualquer alteração registada, com precisão, a partir de qualquer cliente.MCPO vokse tem um servidor MCP remoto: o mesmo conjunto de ferramentas auditadas que o assistente e a aplicação chamam, agora em Model Context Protocol. Um URL, OAuth padrão, sem binários e sem chaves de API.
OpenAPI em bruto
Prefere um explorador interativo? O documento OpenAPI completo é servido em direto, apresentado com o Scalar.
Abrir a referência OpenAPI