REST-API, versie 1

Productie: https://ervazo.com. Het pad is altijd /api/v1, met of zonder slash aan het eind. Een onbekend pad geeft 404 met {"error":"Onbekend pad."}.

curl -s https://ervazo.com/api/v1 \
  -H "Authorization: Bearer nal_jouw_sleutel"

Het antwoord is application/json en wordt niet gecachet. Er is geen andere versie dan 1.

Alleen de eigenaar van de plek. In de werkplek: Instellingen, Publieke API, API aanzetten. Zonder die vlag weigert een geldige sleutel met 403 en de tekst dat de publieke API uit staat.

Een gepauzeerd account krijgt ook 403, met de tekst dat het account is gepauzeerd. Intrekken van een sleutel maakt hem meteen ongeldig. De vlag uitzetten laat de sleutels staan, maar elk verzoek stopt tot je hem weer aanzet.

Maak hem op dezelfde instellingenpagina. Geef een naam van minstens twee tekens. De volledige sleutel verschijnt één keer. Daarna bewaren we alleen een hash en een prefix, zodat je hem in de lijst herkent als nal_ gevolgd door twaalf tekens.

Stuur hem als bearer-token. Geen queryparameter, geen cookie.

Authorization: Bearer nal_…

De sleutel moet met nal_ beginnen en tussen 20 en 200 tekens lang zijn. Anders 401. Een verkeerde of ingetrokken sleutel is dezelfde 401, zodat een gokker niet ziet welke van de twee het was.

Hoogstens acht sleutels die nog niet zijn ingetrokken. De negende poging faalt in de werkplek tot je er een intrekt. last_used_at wordt bij elk geslaagd verzoek bijgewerkt.

120 verzoeken per sleutel per minuut, gerekend in het proces dat het verzoek afhandelt. Daarboven 429: te veel verzoeken, wacht een minuut. De teller staat niet in de database, dus na een herstart begint hij opnieuw.

Een POST-body mag 20.000 bytes zijn. Groter is 413. De body moet JSON zijn als je hem meestuurt. Leeg is toegestaan, maar een taak of notitie heeft dan alsnog een veld nodig.

Een dossier-id in het pad is 1 tot 80 tekens: letters, cijfers, underscore of streepje. Een dossier van een ander account bestaat voor deze sleutel niet en geeft 404.

Fouten zijn JSON met één veld error. Geen stacktrace.

• 401 — Sleutel ontbreekt of is ongeldig.
• 403 — API staat uit, of het account is gepauzeerd.
• 404 — Onbekend pad, of dit dossier hoort niet bij de sleutel.
• 400 — Geen geldige JSON, titel ontbreekt, of de notitie is leeg.
• 409 — Het dossier is gesloten. Lezen mag, schrijven niet.
• 413 — De body is groter dan 20.000 bytes.
• 429 — Meer dan 120 verzoeken in een minuut.

Wie je bent voor deze sleutel, en welke paden er zijn.

{
  "name": "Ervazo",
  "version": "1",
  "account": "kantoor-id",
  "mcp": "/api/mcp",
  "endpoints": [
    "GET /api/v1/dossiers",
    "GET /api/v1/dossiers/{id}",
    "POST /api/v1/dossiers/{id}/tasks",
    "POST /api/v1/dossiers/{id}/notes"
  ]
}

De lijst in dat antwoord noemt niet elk leespad. Betrokkenen, bezittingen, schulden en de takenlijst staan hieronder en werken wel.

Alle dossiers van het account die niet in de prullenbak staan, nieuwste wijziging eerst. Gesloten dossiers zitten erbij.

{
  "dossiers": [
    {
      "id": "…",
      "reference": "2026-014",
      "line": "nalatenschap",
      "phase": "boedel",
      "status": "open",
      "name": "A. de Vries",
      "death": "2026-03-02"
    }
  ]
}

line is nalatenschap of leven. status is open of closed. death kan leeg zijn bij een levensdossier. name is voornaam en achternaam aan elkaar.

Gebruik het id uit de lijst, niet het referentienummer.

{
  "dossier": {
    "id": "…",
    "reference": "2026-014",
    "line": "nalatenschap",
    "phase": "boedel",
    "status": "open",
    "firstName": "A.",
    "lastName": "de Vries",
    "birth": "1948-11-04",
    "death": "2026-03-02",
    "residence": "Haarlem"
  }
}

Betrokkenen. portal zegt of die persoon het portaal aan heeft staan. Een privénotitie bij de persoon gaat niet mee.

{
  "parties": [
    {
      "id": "…",
      "type": "heir",
      "name": "M. de Vries",
      "email": "[email protected]",
      "relation": "kind",
      "portal": true
    }
  ]
}

Bezittingen. valueMinor is het bedrag op overlijden in centen. Een lege currency wordt EUR.

{
  "assets": [
    {
      "id": "…",
      "category": "bank",
      "description": "Betaalrekening",
      "valueMinor": 1250000,
      "currency": "EUR",
      "status": "known"
    }
  ]
}

Schulden. amountMinor is centen. creditor is de naam zoals hij in het dossier staat.

{
  "liabilities": [
    {
      "id": "…",
      "category": "lening",
      "description": "Doorlopend krediet",
      "amountMinor": 240000,
      "currency": "EUR",
      "creditor": "Bank",
      "status": "open"
    }
  ]
}

GET /api/v1/dossiers/{id}/tasks — elke taak met id, title, due en status.

POST /api/v1/dossiers/{id}/tasks

{ "title": "Bankafschriften opvragen", "due": "2026-11-01" }

title is verplicht, na trim hoogstens 200 tekens. due is optioneel en moet YYYY-MM-DD zijn. Een andere vorm wordt vandaag. De taak komt open binnen, toegewezen aan de gebruiker die de sleutel maakte, en telt niet als playbook-stap.

{ "id": "…", "title": "Bankafschriften opvragen", "due": "2026-11-01", "status": "open" }

Op een gesloten dossier is dit 409. De schrijfactie komt in het auditlog als actor API, actie api.task.

Een interne notitie. Het portaal van erfgenamen ziet hem niet. Het veld heet body, niet text.

{ "body": "Bank gebeld. Afschriften volgen per post." }

Na trim hoogstens 4000 tekens. Leeg is 400. Het antwoord is alleen het id. In het dossier staat de auteur als API en de zichtbaarheid als internal. Het auditlog krijgt api.note met de eerste 80 tekens.

{ "id": "…" }

Alle bedragen uit de API zijn integers in de kleinste munteenheid. € 12.500,00 is 1250000. Er is geen kommagetal, zodat een afronding niet per client verschilt. De munteenheid staat er apart bij.

Geen documentdownload, geen upload, geen BSN, geen privénotities van medewerkers, geen verwijderen, geen fase wijzigen, geen erfgenaam uitnodigen en geen verdeling wegschrijven. Die dingen doe je in de werkplek. MCP gebruikt dezelfde grenzen.

Verder met MCP