# Beginnen met de API

Wat de Cijfr API is, wat je nodig hebt en je eerste verzoek in drie stappen.

## Wat de API doet

De Cijfr API is een REST API op `https://api.cijfr.com`. Je maakt en leest klanten, producten, facturen, terugkerende schema's en hosted checkouts in je eigen organisatie. Alles gaat over HTTPS met JSON.

Offertes en creditnota's maak je in de app; de API meldt ze wel terug via webhooks (`quote.accepted`, `quote.declined`).

> De API vraagt om het pakket Max. Zonder Max krijgt elk verzoek een `402` met `plan_limit_api`.

## Stap 1. Maak een sleutel

Log in op finance.cijfr.com en ga naar Instellingen, dan API. Maak daar een sleutel en kies welke rechten (`scopes`) hij krijgt. De sleutel begint met `cijfr_live_` en wordt precies één keer getoond.

> Een API-sleutel is een geheim. Zet hem in een omgevingsvariabele op je server en nooit in code die naar een browser of app gaat.

## Stap 2. Doe je eerste verzoek

Elk verzoek stuurt de sleutel mee als Bearer-token. `GET /api/v1/me` is de kleinste call: hij toont jouw organisatie en bewijst dat de sleutel werkt.

```bash
curl https://api.cijfr.com/api/v1/me \
  -H "Authorization: Bearer $CIJFR_API_KEY"
```

```json
{
  "data": {
    "id": "9f1c2e…",
    "name": "Studio Voorbeeld",
    "legal_name": "Studio Voorbeeld B.V.",
    "trade_name": null,
    "organization_number": "81234567",
    "email": "hallo@studiovoorbeeld.nl",
    "profileId": null
  }
}
```

## Stap 3. Maak iets

Een typische eerste flow: maak een klant, maak daarna een factuur voor die klant. Bedragen zijn altijd hele centen, dus `7500` betekent €75,00.

```bash
# 1. Klant aanmaken
curl https://api.cijfr.com/api/v1/customers \
  -H "Authorization: Bearer $CIJFR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bakkerij De Korenaar","email":"sanne@korenaar.nl"}'
# → {"data":{"id":"c0a8…"}}

# 2. Factuur aanmaken en meteen versturen
curl https://api.cijfr.com/api/v1/invoices \
  -H "Authorization: Bearer $CIJFR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "customerId": "c0a8…",
    "send": true,
    "lines": [
      {"description":"Broodjes catering","quantity":40,"unitPriceCents":325}
    ]
  }'
```

## Voor AI-agenten

Werk je met een AI-agent of vibe-coding tool, dan hoef je deze site niet pagina voor pagina te geven. `GET /llms.txt` is de index, `GET /llms-full.txt` is de complete documentatie in één Markdown-bestand.