Usar a API REST

A API REST do MoneyLights permite que os teus próprios sistemas leiam e mantenham os dados da tua organização: movimentos, fornecedores, clientes, projetos, categorias e fluxo de caixa. Autenticas-te com uma chave de API.

Chamar a API

Envia a tua chave no cabeçalho X-API-Key:

GET /api/transactions HTTP/1.1
Host: api.moneylights.app
X-API-Key: ml_sk_<key-id>_<secret>

Authorization: ApiKey <key> também funciona. Authorization: Bearer <key> não funciona — o Bearer pertence à sessão do navegador. Nunca coloques a chave no URL: esses pedidos são recusados antes de chegarem a qualquer lado.

A referência legível por máquina

A lista completa e sempre atualizada daquilo a que a tua chave pode aceder é o documento OpenAPI público:

GET https://api.moneylights.app/api/public/openapi.json

É gerado a partir da aplicação em execução e lista exatamente os endpoints publicados, cada um anotado com o scope que exige (x-required-scope). Se este guia e esse documento disserem coisas diferentes, confia no documento. Podes usá-lo num gerador de clientes ou importá-lo para uma ferramenta de API.

O que é acessível — e o que não é

Só os endpoints publicados explicitamente fazem parte da API pública. A regra orientadora é enriquecer e manter, nunca destruir:

Podes listar e filtrar movimentos, atribuir-lhes uma categoria, um fornecedor, um cliente ou um projeto, dividi-los entre pessoas (alocações), e criar ou atualizar fornecedores, clientes, projetos e categorias.
Não podes eliminar um fornecedor, cliente, projeto ou categoria através da API. Remover um registo para o qual outros registos apontam é uma decisão que um script não deve tomar sem supervisão — essas ações ficam na aplicação.

As ligações bancárias, a faturação, a gestão da equipa e a gestão de chaves de API nunca são acessíveis com uma chave, sejam quais forem os scopes que ela tenha.

Limites de pedidos

Aplicam-se três limites, e um pedido tem de cumprir todos:

Plano	Leituras/min por chave	Escritas/min por chave	Pedidos/min por organização	Por dia, por organização
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

O limite por minuto ao nível da organização é aquele em função do qual deves planear. É o mesmo valor que o limite por chave, pelo que uma única chave a trabalhar no máximo pode consumir o minuto de toda a organização — acrescentar chaves não aumenta a capacidade. Se tiveres várias integrações, distribui os pedidos delas ao longo do tempo.

Todas as respostas trazem X-RateLimit-Limit e X-RateLimit-Remaining. Um 429 traz Retry-After em segundos — respeita-o; repetir o pedido de imediato pode transformar um limite de pedidos breve numa indisponibilidade.

Erros

As recusas trazem um code estável com base no qual a tua integração pode agir. Os que vais realmente encontrar:

Código	Significado
`api_key_invalid`	A chave está mal formada ou é desconhecida, ou o seu segredo está errado
`api_key_expired`	Ultrapassou a data de expiração — cria uma nova chave
`api_key_revoked`	A chave foi revogada, ou o segredo antigo foi usado depois de fechada a janela de rotação
`api_key_scope_missing`	A chave não tem o scope de que este endpoint precisa
`api_key_endpoint_not_published`	O endpoint não faz parte da API pública
`api_key_rate_limited`	Acima de um limite — respeita o `Retry-After`

Um pedido que não envia nenhuma chave recebe um 401 simples, com o corpo vazio e sem código de erro. Se vires isso, o cabeçalho da chave não foi enviado.

Intervalos de datas

GET /api/cashflow/overview aceita dateFrom e dateTo, ambos opcionais. Se forem omitidos, dateFrom assume por omissão 1 de janeiro do ano corrente e dateTo assume hoje (ambos em UTC). Devolve 400, e não uma visão geral vazia, quando:

uma data não pode ser interpretada (por exemplo 2026-13-01);
dateFrom é posterior a dateTo;
só é enviado dateTo e é anterior ao início por omissão (1 de janeiro do ano corrente, em UTC) — envia também um dateFrom;
só é enviado dateFrom e é posterior a hoje — envia também um dateTo.

É bom saber

A tua chave dá acesso a exatamente uma organização — aquela para a qual foi emitida. Não pode ser apontada para mais nenhuma.
Os valores de utilização são aproximados. Usa o “Último uso” e a contagem de pedidos para verificar se uma chave ainda está a ser usada, não para faturação.
Prefere a API para fluxos de dados, e o servidor MCP quando é um assistente de IA a fazer os pedidos — a mesma credencial, os mesmos scopes.