Usando a API REST

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

Chamando 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 — Bearer pertence à sessão do navegador. Nunca coloques a chave na URL: tais pedidos são recusados antes de chegarem a qualquer coisa.

A referência legível por máquina

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

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

Ele é gerado a partir da aplicação em execução e lista exatamente os endpoints publicados, cada um anotado com o scope que requer (x-required-scope). Se este guia e esse documento alguma vez discordarem, o documento está correto. Podes alimentá-lo a um gerador de cliente ou importá-lo para uma ferramenta de API.

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

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

Tu podes listar e filtrar transações, atribuir-lhes uma categoria, fornecedor, cliente, projeto ou alocações de pessoa, e criar ou atualizar fornecedores, clientes, projetos e categorias.
Tu não podes eliminar um fornecedor, cliente, projeto ou categoria através da API. Remover um registro que outros registros apontam é uma decisão que um script não deve tomar sem supervisão — essas ações vivem na aplicação.

Conexões bancárias, faturamento, gestão de equipe e gestão de chaves de API nunca são acessíveis com uma chave, independentemente dos scopes que tem.

Limites de taxa

Três limites se aplicam, e um pedido deve satisfazer todos eles:

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

O limite por minuto a nível organizacional é o que deves considerar. É o mesmo número que o limite por chave, então uma chave a funcionar a todo o vapor pode consumir o minuto de toda a organização — adicionar chaves não aumenta a capacidade. Se executares várias integrações, distribui-as.

Cada resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Um 429 traz Retry-After em segundos — respeita-o; tentar novamente imediatamente é como um limite de taxa se torna uma interrupção.

Erros

As recusas trazem um code estável que podes ativar. Os que realmente encontrarás:

Código	Significado
`api_key_invalid`	Malformada, desconhecida ou chave secreta errada
`api_key_expired`	Passou a sua data de expiração — cria uma nova chave
`api_key_revoked`	A chave foi cortada, ou um segredo rotacionado expirou
`api_key_scope_missing`	A chave não tem o scope 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 `Retry-After`

Um pedido sem chave nenhuma recebe um simples 401 sem código — trata um 401 sem corpo como “Esqueci-me do cabeçalho”.

Bom saber

A tua chave alcança exatamente uma organização — aquela para a qual foi emitida. Não pode ser direcionada a mais lado nenhum.
Os números de uso são indicativos. “Último usado” e a contagem de pedidos respondem à pergunta “isto ainda está em uso?”, não a questões de faturamento.
Prefere a API para fluxos de dados, e o MCP Server quando o chamador é um assistente de IA — mesma credencial, mesmos scopes.