API referentie

De Peil API is een REST API. Alle endpoints vereisen authenticatie via een API-sleutel met de juiste rechten. Gebruik de API om gegevens te exporteren, uren te loggen, conceptfacturen te maken of Peil te koppelen aan eigen scripts en AI-assistenten (MCP).

Authenticatie

Alle API-verzoeken moeten een geldige API-sleutel meesturen als Bearer token in de Authorization-header:

Authorization: Bearer peil_xxxxxxxxxxxxxxxxxxxxxxxx

Verzoeken zonder geldige sleutel retourneren een 401 Unauthorized-respons. API-sleutels zijn persoonlijk en gekoppeld aan jouw account — deel ze niet.

API-sleutel aanmaken

Je maakt een API-sleutel aan via Instellingen → Developer settings in de Peil-app (Pro). Geef je sleutel een herkenbare naam (bijv. "Mijn boekhouder" of "Claude") zodat je hem later kunt herkennen en intrekken, en kies optioneel een vervaldatum — voor sleutels die je aan een AI-assistent geeft is een korte looptijd verstandig.

Een sleutel wordt slechts eenmalig volledig getoond direct na aanmaken — sla hem daarna op in een wachtwoordmanager of beveiligde omgevingsvariabele.

Rechten (scopes)

Elke sleutel heeft een eigen set rechten. Lezen is altijd inbegrepen; schrijfrechten kies je expliciet bij het aanmaken. Zo geef je een script of assistent nooit meer toegang dan nodig.

Recht	Wat het toestaat
`read`	Klanten, projecten, uren, facturen en het orientatie‑overzicht lezen (altijd actief)
`timesheet:write`	Urenregels aanmaken, bewerken en verwijderen
`invoices:write`	Facturen aanmaken, bewerken, verwijderen en archiveren en herinneringsteksten schrijven — verzendt nooit zelf
`clients:write`	Klanten aanmaken, bewerken en verwijderen
`invoices:send`	Alle klantgerichte e-mail: facturen versturen, inplannen en handmatige herinneringen — onomkeerbaar, bewust een apart recht

Ontbreekt een recht, dan antwoordt de API met 403 en {"code": "INSUFFICIENT_SCOPE"} inclusief het ontbrekende recht. Concept-eerst: zonder invoices:send kan een sleutel alleen concepten maken — nooit iets naar je klanten sturen. Elke schrijfactie van een sleutel wordt gelogd; je vindt het activiteitenlogboek per sleutel in Developer settings.

Base URL

https://api.peil.app/api/v1

Voorbeeld

Een verzoek met curl:

curl -H "Authorization: Bearer peil_xxxxxx" \
  https://api.peil.app/api/v1/export/clients?format=csv

De format-parameter accepteert csv of json voor de meeste exportendpoints. Voor archiefexports retourneert het endpoint altijd een ZIP-bestand.

Kernendpoints

Naast de exports hieronder bereikt een sleutel met de juiste rechten deze endpoints. De volledige parameters en responsschema's staan in de interactieve referentie onderaan deze pagina.

Endpoint	Recht	Wat het doet
`GET /clients`	`read`	Klantenlijst (voor naam → id)
`GET /projects`	`read`	Projectenlijst
`GET·POST·PUT·DELETE /time_entries`	`read` · `timesheet:write`	Uren lezen, loggen, bewerken en verwijderen
`POST·PUT·DELETE /clients`	`read` · `clients:write`	Klanten lezen en beheren
`GET /invoices` · `GET /invoices/unbilled-entries`	`read`	Facturen en ongefactureerde uren
`POST·PUT·DELETE /invoices` · `/archive`	`invoices:write`	Factuur aanmaken, bewerken, status wijzigen, verwijderen, archiveren (concept-eerst zonder `invoices:send`)
`POST /invoices/from-hours`	`invoices:write`	Conceptfactuur uit ongefactureerde uren (zie hieronder)
`PUT /invoices/reminder-settings`	`invoices:write`	Herinneringsteksten en -schema schrijven
`POST /invoices/{id}/send-email` · `/schedule-send` · `/send-reminder`	`invoices:send`	Factuur versturen, inplannen of een herinnering mailen
`GET /orientation/snapshot`	`read`	Compacte financiële stand (zie hieronder)

Conceptfactuur uit uren

POST /invoices/from-hours is het samengestelde werkwoord van de API: het verzamelt ongefactureerde declarabele uren van een klant in een periode, bouwt de factuurregels en maakt een concept aan — genummerd wordt er pas bij verzenden. grouping bepaalt de regelindeling: summary (één regel per omschrijving, gemengd tarief), by_project of per_day.

curl -X POST https://api.peil.app/api/v1/invoices/from-hours \
  -H "Authorization: Bearer peil_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12,
    "period_start": "2026-06-01",
    "period_end": "2026-06-30",
    "grouping": "summary"
  }'

De respons bevat de volledige conceptfactuur plus entry_count en total_hours; de gebruikte uren worden aan het concept gekoppeld. Is er niets te factureren, dan krijg je 422 met {"code": "NO_UNBILLED_ENTRIES"}.

Orientatie-overzicht

GET /orientation/snapshot beantwoordt "waar sta ik?" in één verzoek: openstaand, vervallen (afgeleid van de vervaldatum), concepten, gefactureerd dit jaar en ongefactureerde uren.

{
  "outstanding": { "count": 2, "total": 2420.0 },
  "overdue":     { "count": 1, "total": 1210.0 },
  "drafts":      { "count": 1, "total": 500.0 },
  "invoiced_ytd": 24000.0,
  "uninvoiced":  { "hours": 12.5, "value": 1125.0 },
  "billable_hours_ytd": 800.0,
  "as_of": "2026-07-14"
}

Limieten

Schrijfendpoints zijn gelimiteerd per minuut: uren loggen 60/min, facturen aanmaken 20/min, versturen 10/min. Daarboven antwoordt de API met 429. Maximaal 10 sleutels per account.

Exportformaten

De Peil API biedt de volgende exportendpoints. Alle endpoints zijn GET-verzoeken en vereisen authenticatie.

Endpoint	Formaat	Inhoud
`/export/clients`	CSV / JSON	Klantnaam, contactgegevens, aangemaakt
`/export/time-entries`	CSV / JSON	Datum, uren, tarief, klant, project
`/export/invoices`	CSV / JSON	Factuurnummer, bedrag, status, klant
`/export/invoices/archive`	ZIP	Alle PDF-facturen
`/export/full`	ZIP	Alle bovenstaande exports gecombineerd

De volledige interactieve endpoint-referentie staat hieronder. Alle routes, parameters en responsschema's worden automatisch gegenereerd vanuit de live OpenAPI-specificatie.