REST API gebruiken in Mijn Boekhoudapp (developer handleiding)

REST API van Mijn Boekhoudapp

Met de REST API van Mijn Boekhoudapp kun je je administratie koppelen aan eigen software, scripts of automatiseringen. De API biedt 49 endpoints voor het volledig beheren van je boekhouding.

Je kunt bijvoorbeeld:

• Klanten aanmaken, bijwerken en verwijderen
• Facturen genereren, versturen en PDF's downloaden
• Betalingen registreren bij facturen
• Offertes maken en omzetten naar facturen
• Uren registreren per project
• Producten en diensten beheren
• Uitgaven en terugkerende kosten bijhouden
• Bedrijfsinstellingen en BTW-tarieven ophalen

Alle endpoints staan onder:

https://mijn-boekhoudapp.nl/api/v1/

API Key aanmaken

Ga naar Instellingen → API Keys in je dashboard en maak een nieuwe API key aan.

Scopes (permissies)

Bij het aanmaken kies je welke permissies de key krijgt:

Tip: Geef elke key alleen de permissies die nodig zijn. Maak aparte keys voor verschillende integraties.

Authenticatie

Alle requests gebruiken een Bearer token in de Authorization header.

Authorization: Bearer JOUW_API_KEY
Accept: application/json
Content-Type: application/json

Voorbeeld:

curl https://mijn-boekhoudapp.nl/api/v1/clients \
  -H "Authorization: Bearer JOUW_API_KEY" \
  -H "Accept: application/json"

Paginering, sortering en filtering

Paginering

Alle lijstendpoints retourneren standaard 15 resultaten per pagina (max 100). Je kunt dit aanpassen met de per_page parameter.

GET /api/v1/invoices?per_page=50&page=2

De response bevat paginering-metadata:

{
  "data": [...],
  "links": {
    "first": "...?page=1",
    "last": "...?page=5",
    "prev": null,
    "next": "...?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73
  }
}

Sortering

Gebruik de sort parameter om resultaten te sorteren. Prefix met - voor aflopend.

# Nieuwste facturen eerst
GET /api/v1/invoices?sort=-issue_date

# Klanten op naam (A-Z)
GET /api/v1/clients?sort=name

# Oudste uren eerst
GET /api/v1/time-entries?sort=date

Filtering

Gebruik filter.* parameters om resultaten te filteren.

# Alleen openstaande facturen
GET /api/v1/invoices?filter[status]=sent

# Facturen van een specifieke klant
GET /api/v1/invoices?filter[client_id]=12

# Facturen binnen een datumbereik
GET /api/v1/invoices?filter[date_from]=2026-01-01&filter[date_to]=2026-03-31

# Actieve klanten zoeken op naam
GET /api/v1/clients?filter[name]=Hofstack&filter[active]=1

HTTP Statuscodes

Foutresponse

Bij een validatiefout (422) krijg je een gedetailleerd antwoord:

{
  "message": "The client id field is required.",
  "errors": {
    "client_id": ["The client id field is required."]
  }
}

Vergrendeling (locking)

Sommige resources kunnen niet meer worden gewijzigd of verwijderd:

• Facturen: vergrendeld na versturen of betalen
• Offertes: vergrendeld na versturen
• Uren: vergrendeld na factureren
• Uitgaven: vergrendeld als het boekjaar is afgesloten

Bij een poging om een vergrendelde resource te wijzigen krijg je een 409 Conflict response.

Endpoints per resource

Klanten (Clients)

Aanmaken / bijwerken:

{
  "name": "Hofstack B.V.",
  "email": "info@hofstack.nl",
  "address": "Keizersgracht 100",
  "postcode": "1015 AA",
  "city": "Amsterdam",
  "country": "NL",
  "vat_number": "NL123456789B01",
  "contact_name": "Jan de Vries",
  "phone": "+31 20 1234567",
  "payment_period": 30,
  "category": "Zakelijk"
}

Verplicht: name. Overige velden zijn optioneel.

Filteren: filter[name], filter[email], filter[active], filter[category] Sorteren: name, email, created_at, client_number

Response:

{
  "data": {
    "id": 1,
    "name": "Hofstack B.V.",
    "email": "info@hofstack.nl",
    "address": "Keizersgracht 100",
    "postcode": "1015 AA",
    "city": "Amsterdam",
    "country": "NL",
    "vat_number": "NL123456789B01",
    "client_number": "KL-2026-001",
    "contact_name": "Jan de Vries",
    "phone": "+31 20 1234567",
    "mobile": null,
    "iban": null,
    "bic": null,
    "bank_name": null,
    "active": true,
    "notes": null,
    "payment_method": null,
    "payment_period": 30,
    "category": "Zakelijk",
    "tags": [],
    "created_at": "2026-01-15T10:30:00.000000Z",
    "updated_at": "2026-01-15T10:30:00.000000Z"
  }
}

Facturen (Invoices)

Factuur aanmaken:

{
  "client_id": 1,
  "issue_date": "2026-03-14",
  "due_date": "2026-03-28",
  "currency": "EUR",
  "notes": "Bedankt voor uw vertrouwen.",
  "is_credit": false,
  "items": [
    {
      "description": "Website ontwikkeling",
      "quantity": 10,
      "unit_price": 75.00,
      "tax_percent": 21,
      "unit": "uur"
    },
    {
      "description": "Hosting setup",
      "quantity": 1,
      "unit_price": 150.00,
      "tax_percent": 21,
      "unit": "stuk"
    }
  ]
}

Verplicht: client_id, issue_date, due_date, items (min. 1 regel met description, quantity, unit_price, tax_percent).

Let op: Bij een PUT request met items worden alle bestaande regels vervangen door de nieuwe set.

Filteren: filter[status] (draft, sent, paid, overdue, cancelled), filter[client_id], filter[date_from], filter[date_to] Sorteren: number, issue_date, due_date, total, status, created_at

Factuur versturen (POST /send):

Geen request body nodig. Verstuurt de factuur per e-mail naar de klant. Retourneert de bijgewerkte factuur. Geeft 409 als de factuur al betaald of geannuleerd is.

PDF downloaden (GET /pdf):

Retourneert het PDF-bestand direct (Content-Type: application/pdf). Sla op met de header Content-Disposition.

Betaling registreren:

{
  "amount": 750.00,
  "method": "bank",
  "paid_at": "2026-03-20"
}

Verplicht: amount (min. 0.01). method en paid_at zijn optioneel (paid_at valt terug op vandaag).

Factuur response:

{
  "data": {
    "id": 42,
    "client_id": 1,
    "number": "FACT-2026-042",
    "issue_date": "2026-03-14",
    "due_date": "2026-03-28",
    "status": "draft",
    "currency": "EUR",
    "subtotal": "900.00",
    "tax_total": "189.00",
    "total": "1089.00",
    "total_ex_vat": "900.00",
    "total_vat": "189.00",
    "total_inc_vat": "1089.00",
    "paid_amount": "0.00",
    "open_amount": "1089.00",
    "discount_amount": "0.00",
    "notes": "Bedankt voor uw vertrouwen.",
    "sent_at": null,
    "paid_at": null,
    "is_credit": false,
    "is_reverse_charged": false,
    "created_at": "2026-03-14T12:00:00.000000Z",
    "updated_at": "2026-03-14T12:00:00.000000Z",
    "client": { "id": 1, "name": "Hofstack B.V.", "..." : "..." },
    "items": [
      {
        "id": 101,
        "description": "Website ontwikkeling",
        "quantity": "10.000",
        "unit_price": "75.00",
        "tax_percent": "21.00",
        "line_total_excl": "750.00",
        "tax_amount": "157.50",
        "line_total_incl": "907.50",
        "unit": "uur"
      }
    ]
  }
}

Offertes (Quotes)

Offerte aanmaken:

{
  "client_id": 1,
  "issue_date": "2026-03-10",
  "valid_until": "2026-04-10",
  "notes": "Offerte geldig tot genoemde datum.",
  "items": [
    {
      "description": "Webdesign pakket",
      "quantity": 1,
      "unit_price": 2500.00,
      "tax_percent": 21
    }
  ]
}

Verplicht: client_id, issue_date, valid_until, items (min. 1 regel).

Omzetten naar factuur (POST /convert):

Geen request body nodig. Maakt een nieuwe conceptfactuur aan met alle gegevens uit de offerte. Retourneert de nieuwe factuur (201). Geeft 409 als de offerte niet de status accepted heeft.

Filteren: filter[status] (draft, sent, accepted, rejected, converted), filter[client_id], filter[date_from], filter[date_to] Sorteren: number, issue_date, valid_until, total, status, created_at

Producten (Products)

Product aanmaken:

{
  "name": "Website ontwikkeling",
  "description": "Maatwerk website op basis van Laravel",
  "unit_price": 75.00,
  "unit": "uur",
  "tax_rate_id": 1,
  "is_active": true
}

Verplicht: name, unit_price.

Filteren: filter[name], filter[is_active] Sorteren: name, unit_price, created_at, sort_order

Uitgaven (Expenses)

Uitgave registreren:

{
  "date": "2026-03-01",
  "supplier": "Adobe",
  "reference": "INV-2026-0312",
  "category": "Software",
  "amount_excl": 49.99,
  "tax_percent": 21,
  "notes": "Creative Cloud maandabonnement",
  "client_id": null,
  "project_id": null
}

Verplicht: date, supplier, amount_excl, tax_percent.

Let op: Uitgaven in een afgesloten boekjaar kunnen niet worden gewijzigd of verwijderd (409).

Filteren: filter[category], filter[supplier], filter[client_id], filter[project_id], filter[date_from], filter[date_to] Sorteren: date, amount_incl, supplier, category, created_at

Projecten (Projects)

Project aanmaken:

{
  "client_id": 1,
  "name": "Website redesign",
  "default_rate": 85.00,
  "description": "Volledig nieuw ontwerp van de website"
}

Verplicht: client_id, name.

Filteren: filter[name], filter[client_id] Sorteren: name, created_at

Urenregistratie (Time Entries)

Uren registreren:

{
  "project_id": 5,
  "date": "2026-03-14",
  "hours": 3.5,
  "rate": 85.00,
  "description": "Frontend development homepage"
}

Verplicht: project_id, date, hours (min. 0.01). Als rate niet wordt meegegeven, wordt het standaardtarief van het project gebruikt.

Let op: Gefactureerde uren kunnen niet worden gewijzigd of verwijderd (409).

Filteren: filter[project_id], filter[date_from], filter[date_to], filter[invoiced] (boolean) Sorteren: date, hours, rate, created_at

Terugkerende kosten (Recurring Expenses)

Aanmaken:

{
  "start_date": "2026-01-01",
  "end_date": "2026-12-31",
  "frequency": "monthly",
  "supplier": "Adobe",
  "category": "Software",
  "amount_excl": 49.99,
  "tax_percent": 21,
  "notes": "Creative Cloud"
}

Verplicht: start_date, frequency (weekly, monthly, quarterly, yearly), supplier, amount_excl, tax_percent.

Filteren: filter[category], filter[supplier], filter[frequency] Sorteren: start_date, end_date, amount_incl, supplier, frequency, created_at

Instellingen (Settings) — alleen lezen

Retourneert je bedrijfsgegevens, branding-instellingen en betaalinstellingen.

Response:

{
  "data": {
    "company_name": "Mijn Bedrijf",
    "company_email": "info@mijnbedrijf.nl",
    "company_phone": "+31 6 12345678",
    "company_address": "Keizersgracht 100",
    "company_postcode": "1015 AA",
    "company_city": "Amsterdam",
    "company_country": "NL",
    "kvk": "12345678",
    "vat_number": "NL123456789B01",
    "iban": "NL91ABNA0417164300",
    "payment_link_enabled": true,
    "payment_qr_enabled": true,
    "logo_path": "/media/logos/logo.png",
    "invoice_footer": "Betaling binnen 30 dagen.",
    "primary_color": "#4f46e5",
    "secondary_color": "#7c3aed",
    "font_family": "Inter"
  }
}

BTW-tarieven (Tax Rates) — alleen lezen

Filteren: filter[year] (bijv. filter[year]=2026)

Response:

{
  "data": [
    {
      "id": 1,
      "year": 2026,
      "name": "Hoog tarief",
      "rate": "21.00",
      "reverse_charge": false,
      "is_default": true
    },
    {
      "id": 2,
      "year": 2026,
      "name": "Laag tarief",
      "rate": "9.00",
      "reverse_charge": false,
      "is_default": false
    }
  ]
}

Huidige gebruiker (User)

Voorbeelden

Volledige workflow: klant → project → uren → factuur

# 1. Maak een klant aan
curl -X POST https://mijn-boekhoudapp.nl/api/v1/clients \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hofstack B.V.", "email": "info@hofstack.nl"}'

# 2. Maak een project aan (gebruik client_id uit stap 1)
curl -X POST https://mijn-boekhoudapp.nl/api/v1/projects \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": 1, "name": "Website redesign", "default_rate": 85}'

# 3. Registreer uren (gebruik project_id uit stap 2)
curl -X POST https://mijn-boekhoudapp.nl/api/v1/time-entries \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 1, "date": "2026-03-14", "hours": 8, "description": "Homepage design"}'

# 4. Maak een factuur aan
curl -X POST https://mijn-boekhoudapp.nl/api/v1/invoices \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 1,
    "issue_date": "2026-03-15",
    "due_date": "2026-03-29",
    "items": [
      {"description": "Homepage design - 8 uur", "quantity": 8, "unit_price": 85, "tax_percent": 21, "unit": "uur"}
    ]
  }'

# 5. Verstuur de factuur
curl -X POST https://mijn-boekhoudapp.nl/api/v1/invoices/1/send \
  -H "Authorization: Bearer API_KEY"

# 6. Download de PDF
curl https://mijn-boekhoudapp.nl/api/v1/invoices/1/pdf \
  -H "Authorization: Bearer API_KEY" \
  -o factuur.pdf

# 7. Registreer een betaling
curl -X POST https://mijn-boekhoudapp.nl/api/v1/invoices/1/payments \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 822.80, "method": "bank", "paid_at": "2026-03-20"}'

Offerte maken en omzetten naar factuur

# 1. Maak een offerte
curl -X POST https://mijn-boekhoudapp.nl/api/v1/quotes \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 1,
    "issue_date": "2026-03-10",
    "valid_until": "2026-04-10",
    "items": [
      {"description": "Webdesign pakket", "quantity": 1, "unit_price": 2500, "tax_percent": 21}
    ]
  }'

# 2. Zet de geaccepteerde offerte om naar een factuur
curl -X POST https://mijn-boekhoudapp.nl/api/v1/quotes/1/convert \
  -H "Authorization: Bearer API_KEY"

Alle openstaande facturen ophalen

curl "https://mijn-boekhoudapp.nl/api/v1/invoices?filter[status]=sent&sort=-due_date&per_page=50" \
  -H "Authorization: Bearer API_KEY" \
  -H "Accept: application/json"

Veelgestelde vragen

Heb ik een abonnement nodig voor de API?

Ja, voor gebruik van de API heb je een actief abonnement of credits nodig.

Hoeveel requests mag ik doen?

Er is geen hard rate limit, maar gebruik de API redelijk. Bij excessief gebruik kan je key worden geblokkeerd.

Kan ik facturen wijzigen na versturen?

Nee. Verstuurde en betaalde facturen zijn vergrendeld en geven een 409 Conflict bij wijziging. Maak in plaats daarvan een creditnota aan ("is_credit": true).

Zijn mijn gegevens veilig?

Ja. Authenticatie gebeurt via Bearer tokens met scoped API keys. Alle communicatie verloopt over HTTPS.

Kan ik meerdere API keys aanmaken?

Ja. Je kunt per integratie een aparte key aanmaken met alleen de benodigde permissies.

Waar vind ik mijn API key?

Ga naar Instellingen → API Keys in je dashboard. Kopieer de key direct na het aanmaken — hij wordt daarna niet meer volledig getoond.