API v1
REST API para Factuur.software. Parte da assinatura Pro. JSON para dentro e para fora, autenticação Bearer.
Autenticação
Envie sua chave API no cabeçalho Authorization:
Authorization: Bearer JOUW_SLEUTEL
Gere sua chave em Perfil, sob Acesso à API. A chave é visível uma vez - depois guardamos apenas um hash. Perdeu? Revogue-a e gere uma nova.
Limite de taxa
1000 requisições por hora por usuário. Acima disso, segue HTTP 429.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /api/v1/me | perfil, assinatura, recursos e consumo |
| GET | /api/v1/invoices | faturas (não arquivadas); consulta: de, para (YYYY-MM-DD), limite (máx 1000), offset |
| GET | /api/v1/invoices/{id} | uma fatura com linhas e cliente |
| POST | /api/v1/invoices | criar fatura; invoice_number vazio = numeração automática, linhas opcionais |
| PUT | /api/v1/invoices/{id} | alterar status, invoice_number, issue_date, due_date, notes ou customer_id |
| DELETE | /api/v1/invoices/{id} | arquiva a fatura (obrigação fiscal de armazenamento, nenhuma remoção definitiva) |
| GET | /api/v1/customers | clientes; consulta: limite, deslocamento |
| GET | /api/v1/customers/{id} | um cliente |
| POST | /api/v1/customers | criar cliente; nome é obrigatório |
| PUT | /api/v1/customers/{id} | alterar campos do cliente |
| DELETE | /api/v1/customers/{id} | remover cliente; 409 enquanto houver faturas associadas |
| GET | /api/v1/expenses | despesas; consulta: de, para (AAAA-MM-DD), limite, deslocamento |
| GET | /api/v1/expenses/{id} | uma despesa |
| POST | /api/v1/expenses | criar despesa |
| PUT | /api/v1/expenses/{id} | alterar despesa; valores e IVA serão recalculados |
| DELETE | /api/v1/expenses/{id} | remover despesa |
Códigos de status
200/201sucesso401Token Bearer ausente ou inválido403assinatura não fornece acesso à API404não encontrado409conflito, por exemplo, remover cliente com faturas422payload inválido429limite de taxa excedido
Exemplos
curl -H "Authorization: Bearer JOUW_SLEUTEL" https://factuur.software/api/v1/me
curl "https://factuur.software/api/v1/invoices?from=2026-01-01&limit=50" -H "Authorization: Bearer JOUW_SLEUTEL"
curl -X POST -H "Authorization: Bearer JOUW_SLEUTEL" -H "Content-Type: application/json" -d '{"customer_id":1,"lines":[{"description":"Consultancy","quantity":8,"unit_price":95,"tax_rate":21}]}' https://factuur.software/api/v1/invoices
curl -X PUT -H "Authorization: Bearer JOUW_SLEUTEL" -H "Content-Type: application/json" -d '{"status":"betaald"}' https://factuur.software/api/v1/invoices/123