API Koppeling

Routix biedt een versioned REST API waarmee externe applicaties — zoals ERP-systemen, WMS-platformen, BI-tools en AI-agents — veilig toegang krijgen tot je transportmanagementdata.

De API is gebouwd op OAuth 2.1 en gebruikt een proxy-laag voor stabiliteit, versiebeheer en fijnmazige toegangscontrole.

Architectuur

Het koppelingssysteem bestaat uit drie lagen:

Laag	Beschrijving
OAuth Server	Authenticeert externe apps en geeft JWT-tokens uit met organisatie-, scope- en vestigingsclaims
API Proxy	Versioned REST-endpoint (`/functions/v1/api/...`) dat tokens valideert, scopes afdwingt, vestigingen oplost en gefilterde data retourneert
App Beheer	Dashboard in Routix om OAuth-apps te registreren, configureren en beheren

Hoe het samenwerkt


Externe App
    │
    ├─► POST /functions/v1/oauth-token        (token ophalen)
    │       └─► JWT met org_id, scopes, vestigingen
    │
    └─► GET /functions/v1/api/v1/{vestiging}/accounts  (token gebruiken)
            └─► Verifieer JWT → Check scope → Vestiging oplossen → DB query → Gefilterde velden retourneren

Twee Authenticatieflows

Flow	Use Case	Gebruikersinteractie
Authorization Code + PKCE	Externe apps die namens een gebruiker handelen	Ja — gebruiker geeft toestemming en selecteert organisatie
Client Credentials	Server-to-server / machine-to-machine	Nee — app authenticeert direct met client_id + secret

Belangrijke Concepten

Scopes

Elke API-actie is beschermd door een scope met het patroon:


routix:<resource>:<actie>

Scope	Beschrijving
`routix:accounts:read`	Lees klanten, leveranciers, vervoerders
`routix:accounts:write`	Maak accounts aan of werk ze bij
`routix:orders:read`	Lees orders
`routix:orders:write`	Maak orders aan of werk ze bij
`routix:vehicles:read`	Lees voertuigen
`routix:vehicles:write`	Maak voertuigen aan of werk ze bij
`routix:staff:read`	Lees medewerkers
`routix:equipment:read`	Lees materieel
`routix:planning:read`	Lees planning/routedata
`routix:invoices:read`	Lees facturen
`routix:invoices:write`	Maak facturen aan of werk ze bij

Vestiging-scoping

De API is gescoped per vestiging met een kort publiek ID (8 tekens, bijv. RS2RDH3B). Dit betekent:

Elke API-call richt zich op precies één vestiging
Apps kunnen bij registratie beperkt worden tot specifieke vestigingen
Vestigingsdata is volledig geïsoleerd

API Versiebeheer

Versie	Gedrag
v1	Stabiele, onveranderlijke veldenset — veilig voor productie-integraties
v2	Superset van v1 met extra velden — kan in de loop der tijd nieuwe velden krijgen

Beide versies draaien gelijktijdig. Gebruik v1 voor stabiele contracten, v2 als je extra data nodig hebt.

Volgende Stappen

OAuth Flow — Hoe beide authenticatieflows in detail werken
API Calls & Voorbeelden — Endpoints, velden, paginatie en codevoorbeelden
Installatiehandleiding — Stap voor stap: app registreren en je eerste API-call maken