Setup guide

Deze gids is opgezet als een compacte API-referentie voor de eerste stappen van een Routix-integratie: credentials ophalen, token aanvragen en een endpoint testen.

Gebruikersniveau: Gevorderd

API root endpoint


https://api.routix.com/v1

De meeste integraties starten met deze twee URL-patronen:

OAuth token: https://api.routix.com/v1/oauth/token
API proxy: https://api.routix.com/v1/{scopeId}/{resource}

Wat je nodig hebt

Een Routix-account met admin- of ownerrechten.
Minimaal een branch binnen je organisatie.
Een server of applicatie die de API gaat gebruiken.

Waarde	Waar haal je hem op	Verplicht voor
`client_id`	`Settings -> OAuth Apps`	Token aanvragen
`client_secret`	Bij het aanmaken van de app	Token aanvragen
`organizationId`	`Settings -> Organization`	Organization-scoped API-calls
`branchId`	`Settings -> Branches`	API-calls naar branch-data
`scope`	Geconfigureerd op de OAuth-app	Toegang tot resources

Stap 1: Registreer een OAuth-app

Voordat je een API-call kunt doen, maak je eerst een OAuth-app aan in het dashboard.

Log in op Routix via app.routix.com.
Ga naar Settings -> OAuth Apps.
Klik op Create App.
Vul het formulier in.

Veld	Verplicht	Beschrijving	Voorbeeld
Name	Ja	Beschrijvende naam voor de integratie	`My ERP Sync`
Description	Nee	Wat de integratie doet	`Syncs accounts from Routix to our ERP`
Homepage URL	Nee	Website van je applicatie	`https://myerp.com`
Scopes	Ja	Benodigde permissies	`routix:accounts:read`
Branch restrictions	Nee	Beperk toegang tot specifieke branches	Leeg laten voor alle branches

Klik op Save.
Kopieer de client secret direct. Deze wordt maar een keer getoond.

Belangrijk: bewaar de client_secret in een secrets manager.

Stap 2: Zoek je scope UUID’s op

Voor elke API-call heb je de juiste scope UUID voor de doelresource nodig.

Ga in Routix naar Settings -> Organization om je organization UUID op te zoeken, bijvoorbeeld 123e4567-e89b-12d3-a456-426614174000.
Ga in Routix naar Settings -> Branches om je branch UUID op te zoeken, bijvoorbeeld 550e8400-e29b-41d4-a716-446655440000.
Gebruik de organization UUID voor branches, organizations, users en master_data.
Gebruik de branch UUID voor branch-scoped resources zoals accounts, projects en shipments.

Call 1: Vraag een access token aan

Gebruik deze call om een machine-to-machine token voor je integratie op te halen.

Eigenschap	Waarde
Method	`POST`
Endpoint	`/v1/oauth/token`
Authenticatie	Geen bearer token nodig
Content-Type	`application/json`
Flow	`client_credentials`

Gebruik voor je integratie de client credentials flow:


curl -X POST https://api.routix.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "routix_a1b2c3d4..."
  }'

Request body:

Veld	Type	Verplicht	Beschrijving
`grant_type`	string	Ja	Altijd `client_credentials`
`client_id`	string	Ja	Publieke identifier van je OAuth-app
`client_secret`	string	Ja	Secret van je OAuth-app

Voorbeeldresponse:


{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "routix:accounts:read routix:accounts:write",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "branch_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Belangrijkste responsevelden:

Veld	Beschrijving
`access_token`	Bearer token voor volgende API-calls
`expires_in`	Geldigheid in seconden, standaard `3600`
`scope`	Spaties-gescheiden lijst van toegestane scopes
`branch_ids`	UUID’s van branches die aan de app gekoppeld zijn

Veelvoorkomende fouten:

Fout	Betekenis	Actie
`invalid_client`	`client_id` of `client_secret` klopt niet	Controleer credentials
`invalid_scope`	Gevraagde scopes zijn niet toegestaan	Pas de OAuth-app aan
`429`	Te veel tokenrequests	Voeg retry met backoff toe

Call 2: Test je token met een API-request

Gebruik je nieuwe token direct op een leesendpoint om te bevestigen dat authenticatie, scope en branch-toegang correct zijn.

Eigenschap	Waarde
Method	`GET`
Endpoint	`/v1/{branchId}/accounts`
Authenticatie	`Authorization: Bearer <access_token>`
Vereiste scope	`routix:accounts:read`

Met je token en branch UUID kun je een request doen:


curl -X GET "https://api.routix.com/v1/550e8400-e29b-41d4-a716-446655440000/accounts?limit=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Queryparameters:

Parameter	Type	Default	Beschrijving
`limit`	integer	`50`	Aantal records per pagina
`offset`	integer	`0`	Paginatie-offset

Voorbeeldresponse:


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "company_name": "Acme Transport B.V.",
      "email": "[email protected]",
      "phone": "+31 20 123 4567",
      "account_type": "customer",
      "status": "active"
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 1
  },
  "version": "v1"
}

Validatiecheck:

200 OK: token, scope en branch UUID zijn correct.
401 invalid_token: vraag een nieuw token aan.
403 insufficient_scope: voeg routix:accounts:read toe aan de app.
404 branch_not_found: controleer de branch UUID.

App status beheren

Revoke

Om een app direct te blokkeren voor nieuwe tokenaanvragen:

In het dashboard: OAuth Apps -> Your App -> Revoke
Via API: update de status naar revoked op de oauth_apps resource

Een revoke voorkomt nieuwe tokenrequests, terwijl bestaande tokens geldig blijven tot expiry.

Reactivate

Om een gerevokeerde app weer te activeren:

In het dashboard: OAuth Apps -> Your App -> Activate
Via API: update de status naar active

Een revoke voorkomt nieuwe tokenrequests, terwijl bestaande tokens geldig blijven tot expiry.

Troubleshooting

Fout	Oorzaak	Oplossing
`401 invalid_token`	Token is verlopen of ongeldig	Vraag een nieuwe token aan.
`403 invalid_token_type`	Er wordt een normale gebruikerstoken gebruikt	Gebruik het OAuth-tokenendpoint.
`403 insufficient_scope`	Vereiste scope ontbreekt	Werk `allowed_scopes` bij of vraag de juiste scopes aan.
`404 branch_not_found`	Onjuiste branch UUID	Controleer de branch UUID in `Settings -> Branches`.
`403 branch access denied`	App is beperkt tot andere branches	Werk `allowed_branch_ids` bij of gebruik een toegestane branch.
`invalid_client`	Onjuiste `client_id` of secret	Controleer de gegevens.

Beschikbare scopes

Scope	Beschrijving
routix:accounts:read	Lees accounts, inclusief klanten, leveranciers en vervoerders.
routix:accounts:write	Maak accounts aan en werk ze bij.
routix:orders:read	Lees orders.
routix:orders:write	Maak orders aan en werk ze bij.
routix:projects:write	Bewerk projecten.
routix:shipments:write	Bewerk zendingen.
routix:trips:write	Bewerk ritten.
routix:vehicles:read	Lees voertuigen.
routix:vehicles:write	Maak voertuigen aan en werk ze bij.
routix:items:write	Bewerk items.
routix:tariffs:write	Bewerk tarieven.
routix:zones:write	Bewerk zones.
routix:quotations:write	Bewerk offertes.
routix:staff:read	Lees medewerkers.
routix:equipment:read	Lees equipment.
routix:planning:read	Lees planning- en routedata.
routix:invoices:read	Lees facturen.
routix:invoices:write	Maak facturen aan en werk ze bij.

Integratiechecklist

Registreer een OAuth-app in Routix.
Bewaar client_id en client_secret veilig.
Implementeer token acquisition met de client credentials flow.
Handel token expiry af door een nieuwe token op te vragen.
Gebruik de juiste branch UUID in API-URL’s.
Vraag alleen de scopes aan die je applicatie nodig heeft.
Handel foutresponses zoals 401, 403, 404 en 429 af.
Test met v1 voor stabiele veldcontracten.

Gerelateerde pagina’s

API integratie
API calls en voorbeelden