V7 Kassa API — documentatie

Basis Authenticatie Rate-limiting Fouten Endpoints Voorbeeld

Basis

Basis-URL	`https://api.v7.nl/v1`
Formaat	JSON (UTF-8). Bedragen in hele centen (bijv. `250` = € 2,50).
Methoden	`GET` om te lezen; `POST` om te schrijven (voorraad & orders) — schrijven vereist een token met schrijfrecht.
Scope	Een token hoort bij één kassa en ziet alleen die kassa.

Authenticatie

Elk verzoek (behalve /ping) vereist een token in de Authorization-header:

Authorization: Bearer v7k_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token aanmaken: in BEHEER → API-koppelingen maak je per kassa een token aan. Het token is maar één keer zichtbaar — bewaar het veilig. Kwijt of gelekt? Trek het in en maak een nieuw token aan.

Rate-limiting

Per token gelden limieten, zodat de kassa-server nooit overvraagd wordt. Bij overschrijding krijg je 429 Too Many Requests met een Retry-After-header.

Standaard	Waarde
Per minuut	`120` verzoeken
Per dag	`20.000` verzoeken

Elke respons bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Het verbruik per token wordt geteld en is zichtbaar in BEHEER.

Fouten

Fouten zijn JSON met een vaste vorm en een passende HTTP-status:

{ "error": "ongeldig_token", "bericht": "Onbekend token." }

Status	Betekenis
`401`	Geen of ongeldig token
`403`	Token ingetrokken
`404`	Onbekend endpoint of niet gevonden
`429`	Te veel verzoeken (rate-limit)

Endpoints

GET/v1/ping

Health check zonder token. Handig om connectiviteit te testen.

GET/v1/kassa

Basisinfo over de kassa achter dit token (naam, plaats).

GET/v1/categorieen

Alle categorieën van de kassa (id, naam, kleur, volgorde).

GET/v1/artikelen

De menukaart / artikelen. Parameters: zichtbaar=1 (alleen zichtbare), limit (max 1000), offset. Elke regel bevat o.a. prijsCent, plu, ean, categorieId, voorraad en de kanalen (online/bezorg/afhaal/zuil).

GET/v1/voorraad

Artikelen met een voorraadstand + minimum, en of ze onder het minimum zitten.

GET/v1/omzet

Omzet over een periode. Parameters: van=YYYY-MM-DD, tot=YYYY-MM-DD (standaard laatste 30 dagen). Geeft omzet per dag, gesplitst per btw-tarief en per betaalwijze.

GET/v1/bonnen

Afgerekende bonnen (samenvatting) over een periode. Parameters: van, tot, limit (max 500), offset. Elke bon heeft een bon-sleutel voor het detail.

GET/v1/bon

Eén bon met regels en betalingen. Parameter: key= (de bonsleutel uit /v1/bonnen).

Schrijven — vereist een token met schrijfrecht (aan te zetten in BEHEER)

POST/v1/voorraad

Voorraad van een artikel bijwerken. JSON-body met artikelId (of ean/plu) en óf voorraad (absoluut zetten) óf mutatie (erbij/eraf, bijv. -2).

curl -X POST -H "Authorization: Bearer v7k_..." -H "Content-Type: application/json" \
     -d '{"artikelId":207474,"voorraad":25}' https://api.v7.nl/v1/voorraad

POST/v1/order

Een order "inschieten" als open bon in de kassa. JSON-body: tafel (bijv. "12", "afhaal" of "*"), items (lijst van {artikelId, aantal}), en optioneel naam / referentie. Btw en omzetgroep worden net als in de kassa afgeleid; de bon verschijnt open in de kassa.

curl -X POST -H "Authorization: Bearer v7k_..." -H "Content-Type: application/json" \
     -d '{"tafel":"12","items":[{"artikelId":207416,"aantal":2}]}' https://api.v7.nl/v1/order

Voorbeeld

Verzoek

curl -H "Authorization: Bearer v7k_JOUW_TOKEN" \
     "https://api.v7.nl/v1/omzet?van=2026-07-01&tot=2026-07-07"

Antwoord

{
  "kassaId": 547,
  "periode": { "van": "2026-07-01", "tot": "2026-07-07" },
  "omzetCent": 184230,
  "perDag": [
    { "datum": "2026-07-01", "omzetCent": 24310, "items": 92 }
  ],
  "perBtw": [
    { "btw": 9,  "omzetCent": 120400 },
    { "btw": 21, "omzetCent": 63830 }
  ],
  "perBetaalwijze": [
    { "betaalwijze": "Pin",     "bedragCent": 150200, "aantal": 61 },
    { "betaalwijze": "Contant", "bedragCent": 34030,  "aantal": 22 }
  ]
}

Ook beschikbaar: de machine-leesbare spec op /openapi.json — te importeren in Postman, Insomnia of een Swagger-viewer.