API-referentie v1.0

Koppel je applicaties aan het KPI-dataplatform van Normly.

Snel aan de slag

1. Vraag je API-token aan

API-toegang wordt per bedrijf aangezet, op verzoek. Vraag Matso om die voor je bedrijf aan te zetten; daarna krijg je een persoonlijk API-token. Tot dan antwoordt elke aanroep met 403.

2. Basis-URL

https://matso.nl/api/

3. Authenticatie

Zet je token in de Authorization-header:

Authorization: Token your_token_here

4. Test de verbinding

curl https://matso.nl/api/tables/ \
  -H "Authorization: Token your_token_here"

Belangrijkste endpoints

KPI-tabellen

Alle tabellen opvragen

GET /api/tables/

Haal een lijst op van de KPI-tabellen waar je toegang toe hebt.

Tabeldetails

GET /api/tables/{id}/

Haal gedetailleerde informatie op over een specifieke tabel.

Tabeldata (aanbevolen)

GET /api/tables/{id}/data/

Haal platgeslagen data uit een tabel op voor Power BI, Excel en rapportagetools.

Rijen in afwachting van goedkeuring

GET /api/tables/{id}/pending/

Haal de data van een tabel op die in afwachting is van goedkeuring.

Beschikbare filters

search - zoeken op naam of omschrijving
ordering - resultaten sorteren (bijv. -created_at)
page - paginering

Voorbeeld

/api/tables/?search=sales&ordering=-created_at

Datarijen

Alle rijen opvragen

GET /api/rows/

Haal alle datarijen op, met geneste celstructuur.

Rijdetails

GET /api/rows/{id}/

Haal gedetailleerde informatie op over een specifieke rij.

Beschikbare filters

ordering - sorteren op created_at of approved_at (bijv. -approved_at)
page, page_size - paginering

Voor de goedgekeurde rijen van één tabel gebruik je /api/tables/{id}/data/.

Voorbeeld

/api/rows/?ordering=-approved_at

Een rij aanmaken

POST /api/rows/

Stuur het tabel-ID en de values (waarden) van de rij, per kolomnaam. De waarden worden gecontroleerd met dezelfde regels als het invoerformulier (vereiste velden, minimum en maximum, toegestane waarden, uniek, ...). Je hebt invoerrechten op de tabel nodig. De rij wordt een concept, of meteen goedgekeurd als de tabel je je eigen rijen laat goedkeuren. Waarden zijn daarna niet via de API te wijzigen.

curl -X POST \
  https://matso.nl/api/rows/ \
  -H "Authorization: Token your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"table": 1, "values": {"Omzet": 1200, "Regio": "Noord"}}'

Antwoordt 201 Created met de rij en haar cellen. Een waarde die alleen een waarschuwingsregel breekt, maakt de rij ook aan en krijgt “Controle nodig”; rule_warnings somt die op:

{
  "rule_warnings": [
    {"column": "Omzet", "rule": "Zorg ervoor dat deze waarde kleiner dan of gelijk is aan 10000.00."}
  ]
}

Waarden die een regel breken geven 400 Bad Request met de fouten per kolom; er wordt geen rij aangemaakt:

{
  "values": {
    "Omzet": ["Zorg ervoor dat deze waarde groter of gelijk is aan 0.00."],
    "Winst": ["Unknown column."]
  }
}

Een rij verwijderen

DELETE /api/rows/{id}/

Je hebt aanmaakrechten op de tabel nodig, of je hebt de rij zelf ingevoerd. De API antwoordt 204 No Content en zet de rij op inactief: ze blijft in de historie, er wordt niets gewist. Staat het vier-ogenprincipe aan voor de tabel, dan antwoordt het verwijderen van een goedgekeurde rij met 202 Accepted: de verwijdering wacht tot een andere goedkeurder van de tabel die in de app bevestigt.

curl -X DELETE   https://matso.nl/api/rows/1/   -H "Authorization: Token your_token_here"

Data goedkeuren en afwijzen

Breng een rij in afwachting door het goedkeuringsproces. Voor deze acties heb je goedkeurdersrechten op de tabel nodig. Staat het vier-ogenprincipe aan voor de tabel, dan kun je een rij die je zelf hebt ingediend niet goedkeuren. Staat het uit, dan worden rijen die je via de API aanmaakt direct goedgekeurd als je in die tabel ook mag goedkeuren.

Een rij goedkeuren

POST /api/rows/{id}/approve/

curl -X POST \
  https://matso.nl/api/rows/1/approve/ \
  -H "Authorization: Token your_token_here"

Een rij afwijzen

POST /api/rows/{id}/reject/

curl -X POST \
  https://matso.nl/api/rows/1/reject/ \
  -H "Authorization: Token your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Numbers do not match source"}'

Een reason (reden) is optioneel; die wordt bij de rij bewaard en aan de invoerder getoond.

Voorbeeldantwoorden

Antwoord met tabeldata

GET /api/tables/1/data/

[
  {
    "id": 1,
    "table_name": "Sales Data",
    "status": "approved",
    "created_at": "2025-01-28T10:30:00Z",
    "created_by_email": "[email protected]",
    "Employee Name": "John Doe",
    "Monthly Sales": "50000",
    "Target Met": "true",
    "Region": "North"
  },
  {
    "id": 2,
    "table_name": "Sales Data", 
    "status": "approved",
    "created_at": "2025-01-28T11:15:00Z",
    "created_by_email": "[email protected]",
    "Employee Name": "Jane Smith",
    "Monthly Sales": "75000",
    "Target Met": "true",
    "Region": "South"
  }
]

Antwoord met lijst van tabellen

GET /api/tables/

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Sales Data",
      "description": "Monthly sales figures",
      "version_name": "Q1 2025",
      "version_number": 1,
      "created_at": "2025-01-01T00:00:00Z",
      "company_name": "Your Company",
      "columns": [
        {
          "id": 1,
          "name": "Employee Name",
          "data_type": "text",
          "required": true
        },
        {
          "id": 2,
          "name": "Monthly Sales",
          "data_type": "number",
          "required": true
        }
      ]
    }
  ]
}

Voorbeelden van koppelingen

Power BI

Gegevens ophalen → Web
URL: /api/tables/1/data/
Authorization-header toevoegen
Verbinden en transformeren

Uitgebreide handleiding

Excel

Gegevens → Gegevens ophalen → Van web
API-URL invullen
Authenticatie instellen
Laden en vernieuwen

Gebruik het /data/-endpoint voor het beste resultaat

Python

import requests

headers = {
    'Authorization': 'Token your_token'
}

response = requests.get(
    'https://matso.nl/api/tables/1/data/',
    headers=headers
)

data = response.json()

cURL

# Tabellen opvragen waar je toegang toe hebt
curl https://matso.nl/api/tables/ \
  -H "Authorization: Token your_token"

# Platgeslagen data van één tabel ophalen
curl https://matso.nl/api/tables/1/data/ \
  -H "Authorization: Token your_token"

JavaScript

const res = await fetch(
  "https://matso.nl/api/tables/1/data/",
  { headers: { Authorization: "Token your_token" } }
);

const data = await res.json();
console.log(data);

Authenticatie

Tokenauthenticatie

Elke API-aanroep authenticeert met een persoonlijk API-token in de Authorization-header.

De API accepteert geen gebruikersnaam en wachtwoord: een verzoek met een wachtwoord wordt geweigerd.

Authorization: Token abc123def456

Limieten

Per token kun je tot 300 verzoeken per minuut doen; niet-ingelogde aanroepers tot 30 per IP. Daarboven antwoordt de API met 429 Too Many Requests en een Retry-After-header.

Foutafhandeling

Statuscode	Betekenis
200	Success - verzoek is uitgevoerd
400	Bad Request - controleer de parameters
401	Unauthorized - controleer de authenticatie
403	Forbidden - geen toestemming
404	Not Found - de resource bestaat niet

Veelvoorkomende problemen

401 Unauthorized: controleer het formaat en de geldigheid van je token
403 Forbidden: je hebt geen toegang tot deze tabel
404 Not Found: controleer of het tabel-/rij-ID bestaat
429 Too Many Requests: boven de limiet; wacht het aantal seconden uit Retry-After

Hulp nodig?

Neem contact op met Matso voor:

Het aanzetten van API-toegang voor je bedrijf
Problemen met rechten
Ondersteuning bij koppelingen

Rate limits en best practices

Gebruik het /data/-endpoint voor rapportagetools
Cache antwoorden waar mogelijk
Filter data in de API (niet aan de clientkant)
Gebruik paginering voor grote datasets

Gebruik exponential backoff bij nieuwe pogingen
Houd je API-gebruik in de gaten
Bewaar tokens veilig en vervang ze regelmatig
Test eerst met kleine datasets

Ondersteuning nodig?

Ons team helpt je graag om de koppeling met de Normly-API goed werkend te krijgen.

Neem contact op met support

Power BI-handleiding