Installatiehandleiding

Deze handleiding begeleidt je bij het maken van je eerste API-koppeling met Routix — van het registreren van een OAuth-app tot het maken van je eerste API-call.

Vereisten

• Een Routix-account met admin of eigenaar toegang
• Minimaal één vestiging aangemaakt in je organisatie
• Een server of applicatie die de API gaat consumeren

Stap 1: Registreer een OAuth App

Optie A: Via het Routix Dashboard

1. Log in bij Routix op app.routix.nl 
2. Ga naar Instellingen → OAuth Apps
3. Klik op App Aanmaken
4. Vul het formulier in:

5. Klik op Opslaan
6. Kopieer het client secret direct — het wordt maar één keer getoond!

Optie B: Via de API

curl -X POST https://api.routix.nl/functions/v1/register-oauth-app \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JOUW_GEBRUIKERS_TOKEN" \
  -d '{
    "name": "Mijn ERP Sync",
    "description": "Synchroniseert accounts van Routix naar ons ERP",
    "redirect_uris": ["https://mijn-erp.nl/callback"],
    "allowed_scopes": ["routix:accounts:read", "routix:accounts:write"],
    "allowed_branch_ids": []
  }'

Response:

{
  "success": true,
  "app": {
    "id": "a1b2c3d4-...",
    "name": "Mijn ERP Sync",
    "client_id": "e5f6g7h8-...",
    "client_secret": "routix_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "redirect_uris": ["https://mijn-erp.nl/callback"],
    "allowed_scopes": ["routix:accounts:read", "routix:accounts:write"],
    "allowed_branch_ids": [],
    "status": "active",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "warning": "Bewaar het client_secret veilig — het wordt niet opnieuw getoond."
}

Belangrijk: Het client_secret heeft het formaat routix_<40 hex tekens> (47 tekens totaal). Bewaar het in een secrets manager. Bij verlies moet je het secret roteren.

Stap 2: Zoek je Vestiging-ID

Elke API-call vereist een publiek vestiging-ID (8-teken code).

1. Ga naar Instellingen → Vestigingen in Routix
2. Elke vestiging toont haar Publiek ID (bijv. RS2RDH3B)
3. Dit korte ID wordt gebruikt in de API URL in plaats van de interne UUID

Stap 3: Haal een Access Token op

Voor backend-integraties (Client Credentials)

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

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "routix:accounts:read routix:accounts:write",
  "organization_id": "org-uuid",
  "branch_ids": ["branch-uuid"]
}

Voor gebruikersgerichte apps (Authorization Code + PKCE)

Zie de volledige OAuth Flow documentatie.

Stap 4: Maak je Eerste API-Call

Met je token en vestiging-ID, maak een request:

curl -X GET "https://api.routix.nl/functions/v1/api/v1/RS2RDH3B/accounts?limit=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Verwachte response:

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

🎉 Gefeliciteerd — je API-koppeling werkt!

Stap 5: Secrets Roteren

Als je client secret gecompromitteerd is, of als onderdeel van reguliere beveiligingshygiëne:

Via het Dashboard

1. Ga naar Instellingen → OAuth Apps → Jouw App
2. Klik op Secret Roteren
3. Kopieer het nieuwe secret direct
4. Werk je applicatieconfiguratie bij
5. Het oude secret wordt direct ongeldig

Via de API

curl -X POST https://api.routix.nl/functions/v1/rotate-oauth-secret \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JOUW_GEBRUIKERS_TOKEN" \
  -d '{
    "oauth_app_id": "JOUW_APP_UUID"
  }'

Response:

{
  "success": true,
  "client_secret": "routix_nieuw_secret_hier...",
  "client_secret_last4": "s9t0",
  "warning": "Bewaar het client_secret veilig — het wordt niet opnieuw getoond."
}

Let op: Bestaande tokens blijven geldig tot ze verlopen (max 1 uur). Alleen nieuwe tokenverzoeken hebben het nieuwe secret nodig.

Stap 6: App Intrekken of Heractiveren

Intrekken

Om direct te blokkeren dat een app nieuwe tokens aanvraagt:

• In het dashboard: OAuth Apps → Jouw App → Intrekken
• Via API: Update status naar "revoked" op de oauth_apps resource

Intrekken van een app:

• Voorkomt nieuwe tokenverzoeken
• Bestaande tokens blijven geldig tot expiry (max 1 uur)
• De API proxy controleert app-status bij elk request

Heractiveren

Om een ingetrokken app weer in te schakelen:

• In het dashboard: OAuth Apps → Jouw App → Activeren
• Via API: Update status naar "active"

Probleemoplossing

Beschikbare Scopes Referentie

Checklist

• Registreer een OAuth-app in Routix (dashboard of API)
• Bewaar client_id en client_secret veilig
• Implementeer token-verkrijging (Client Credentials of Authorization Code + PKCE)
• Handel token-expiry en vernieuwing af
• Gebruik het juiste 8-teken publiek vestiging-ID in API URLs
• Vraag alleen de scopes aan die je app nodig heeft
• Handel foutresponses af (401, 403, 404, 429)
• Plan een schema voor secret-rotatie
• Test met v1 voor stabiele veldcontracten