FleetCycle API — Koppeling Leenfietsen

1. Inleiding

Deze documentatie beschrijft de API-endpoints van FleetCycle waarmee CycleSoftware een leenfiets-selectieknop kan bouwen in de werkbon-flow (bijv. bij stap 5 van de werkbon).

De koppeling bestaat uit twee stappen:

1. Beschikbare leenfietsen ophalen voor een specifieke werkbon → GET /api/leenfiets-selectie
2. Een leenfiets toewijzen aan die werkbon → POST /api/leenfiets-selectie/assign

Bij het toewijzen schrijft FleetCycle de leenfiets automatisch terug naar de betreffende werkbon in CycleSoftware (via het borrowed_object_reference / loan_object_id-veld op de werkplaatsorder), zodat de gekozen fiets direct zichtbaar is in CycleSoftware.

2. Basis-URL en algemene afspraken

Alle datums/tijden in responses zijn in ISO 8601 formaat (UTC), bijv. 2026-09-16T08:00:00.000Z.

3. Autorisatie van de dealer

FleetCycle ondersteunt twee manieren om de dealer te identificeren. Beide werken naast elkaar, zodat bestaande koppelingen ongewijzigd blijven functioneren.

3.1 Dealer-autorisatie via API-sleutel (aanbevolen)

Elke dealer heeft in FleetCycle een unieke, intrekbare API-sleutel (bearer token). Deze sleutel begint altijd met fc_live_. CycleSoftware stuurt de sleutel mee als HTTP-header bij elk verzoek:

Authorization: Bearer fc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• De sleutel is gekoppeld aan één specifieke dealer (tenant). FleetCycle leidt de dealer af uit de sleutel; de tenant-parameter is dan niet meer nodig.
• Bij een ongeldige sleutel → HTTP 401 Unauthorized ({ "error": "Ongeldige API-sleutel" }).
• De dealer genereert en beheert de sleutel in het FleetCycle-dashboard. FleetCycle levert de sleutel per dealer aan CycleSoftware aan bij het inrichten van de koppeling. Een sleutel kan op elk moment worden ingetrokken of opnieuw gegenereerd.

Dit is de aanbevolen methode voor de native knop in CycleSoftware, omdat de dealer hiermee expliciet is geautoriseerd en de toegang per dealer kan worden ingetrokken.

3.2 Dealer-identificatie via tenant-parameter (bestaande methode)

Wordt er geen Authorization-header meegestuurd, dan identificeren de endpoints de dealer via de tenant-identifier (slug of ID) in het verzoek. Dit is de methode die de bestaande FleetCycle-popup gebruikt; die blijft hiermee ongewijzigd werken.

In beide gevallen werkt een verzoek alleen wanneer:

• de tenant actief is (isActive = true), én
• de CycleSoftware-koppeling voor die tenant is ingeschakeld en geconfigureerd (cycleSoftwareEnabled = true en een geldige API-sleutel aanwezig).

Is de koppeling niet ingeschakeld, dan geeft de API HTTP 400 terug. De dealer activeert de koppeling zelf in het FleetCycle-dashboard onder Instellingen → CycleSoftware.

4. Endpoint 1 — Beschikbare leenfietsen ophalen

GET /api/leenfiets-selectie?tenant=<slug|id>&werkbon=<workshop_order_id>

Haalt de dealergegevens en de lijst met leenfietsen op, inclusief per fiets de beschikbaarheid voor de geplande periode van de werkbon.

4.1 Query-parameters

4.2 Voorbeeldverzoek

GET https://fleetcycle.nl/api/leenfiets-selectie?tenant=grootstaltweewielers-b-v&werkbon=12345
Accept: application/json

4.3 Voorbeeldrespons (HTTP 200)

{
  "tenant": {
    "id": "9f88bc09-e574-4a9f-b4c1-84fd2c60bfd0",
    "name": "Grootstal Tweewielers B.V.",
    "slug": "grootstaltweewielers-b-v",
    "logoUrl": "https://grootstaltweewielers.nl/favicon.jpg",
    "primaryColor": "#1e7a46"
  },
  "bikes": [
    {
      "id": "clx8f2a0b0001",
      "name": "Bedrijfsfiets 15",
      "bikeNumber": "15",
      "frameNumber": "GT1234567",
      "cycleSoftwareId": "27152",
      "imageUrl": "https://i.ebayimg.com/images/g/LQoAAeSwSx9p69Sl/s-l1200.webp",
      "status": "available",
      "isLoaned": false,
      "isRented": false,
      "inMaintenance": false,
      "bikeType": "stadsfiets",
      "electricAssist": false,
      "categoryName": "Stadsfietsen",
      "locationName": "Hoofdvestiging"
    }
  ],
  "werkbonId": "12345",
  "workshopCustomerId": 88231,
  "customerName": "Jan de Vries",
  "werkbonDatesKnown": true,
  "werkbonPeriod": {
    "start": "2026-09-16T00:00:00.000Z",
    "end": "2026-09-19T00:00:00.000Z"
  },
  "availableByType": {
    "stadsfiets": 4,
    "e-bike": 2
  }
}

4.4 Veldbeschrijving respons

Per fiets (bikes[]):

5. Endpoint 2 — Leenfiets toewijzen aan werkbon

POST /api/leenfiets-selectie/assign

Wijst een gekozen leenfiets toe aan de werkbon en werkt de werkbon in CycleSoftware bij met de leenfiets-referentie.

5.1 Request body (JSON)

5.2 Voorbeeldverzoek

POST https://fleetcycle.nl/api/leenfiets-selectie/assign
Content-Type: application/json

{
  "tenantId": "9f88bc09-e574-4a9f-b4c1-84fd2c60bfd0",
  "werkbonId": "12345",
  "bikeId": "clx8f2a0b0001",
  "cycleSoftwareId": "27152",
  "customerId": "88231"
}

5.3 Voorbeeldrespons (HTTP 200)

{
  "success": true,
  "message": "Leenfiets succesvol toegewezen aan werkbon",
  "werkbonId": "12345",
  "customerName": "Jan de Vries",
  "bike": {
    "id": "clx8f2a0b0001",
    "name": "Bedrijfsfiets 15",
    "bikeNumber": "15",
    "cycleSoftwareReference": "27152-15 Bedrijfsfiets 15"
  },
  "loanPeriod": {
    "until": "2026-09-19",
    "note": "Leenfiets wordt pas geactiveerd wanneer fiets wordt binnengebracht (status 2/3/4)"
  },
  "cycleSoftwareUpdated": true,
  "warning": null
}

5.4 Veldbeschrijving respons

6. Foutafhandeling

Alle fouten worden geretourneerd als JSON met een error-veld (en bij conflicten aanvullende details).

Voorbeeld conflict (HTTP 409) bij toewijzen:

{
  "error": "Deze fiets is niet beschikbaar. De fiets is al gereserveerd als leenfiets voor werkbon #12000 (Piet Bakker) van 15-09-2026 t/m 18-09-2026.",
  "conflictType": "loan_bike",
  "conflictDetails": {
    "workshopOrderId": "12000",
    "customerName": "Piet Bakker",
    "startDate": "2026-09-15T00:00:00.000Z",
    "endDate": "2026-09-18T00:00:00.000Z"
  }
}

conflictType kan zijn: loan_bike (al als leenfiets vergeven) of rental_booking (verhuurd).

7. Voorgestelde flow bij stap 5 van de werkbon

1. Medewerker komt bij stap 5 van de werkbon in CycleSoftware en klikt op "Leenfiets kiezen".
2. CycleSoftware roept endpoint 1 aan met de dealer-identifier en het workshop_order_id van de huidige werkbon.
3. CycleSoftware toont de lijst met leenfietsen; niet-beschikbare fietsen (isLoaned/isRented/inMaintenance) worden uitgegrijsd.
4. Medewerker kiest een fiets.
5. CycleSoftware roept endpoint 2 aan met tenantId, werkbonId, bikeId en cycleSoftwareId.
6. FleetCycle registreert de reservering én schrijft de leenfiets terug naar de werkbon in CycleSoftware. De gekozen fiets is daarna direct zichtbaar op de werkbon.

8. Webhook — automatische statusverwerking

Naast de twee endpoints ondersteunt FleetCycle een webhook waarmee CycleSoftware statuswijzigingen van de werkbon terugmeldt aan FleetCycle. Dit is de tegenovergestelde richting: CycleSoftware → FleetCycle.

De webhook is niet nodig om een leenfiets te kiezen of toe te wijzen (dat doen endpoint 1 en 2), maar zorgt voor de automatische afhandeling van de leenfiets gedurende de reparatie:

Zonder webhook blijft een toegewezen leenfiets op "gereserveerd" staan en gebeuren deze vervolgstappen niet automatisch. Wij adviseren de webhook per dealer in te stellen, zodat de volledige leenfiets-workflow automatisch verloopt.

8.1 Webhook-URL

De webhook-URL is uniek per dealer en bevat de dealer-ID als parameter:

https://fleetcycle.nl/api/cyclesoftware/webhook?tenantId=<dealer-id>

De dealer vindt de exacte, kant-en-klare URL (met de juiste tenantId) in het FleetCycle-dashboard — zie §9.

CycleSoftware stuurt bij een statuswijziging een POST met een JSON-payload van de werkplaatsorder (o.a. workshop_order_id, status_id, customer_id, borrowed_object_reference). FleetCycle antwoordt met HTTP 200 bij een succesvolle verwerking.

9. Instellen in FleetCycle (per dealer)

De koppeling wordt per dealer geconfigureerd in het FleetCycle-dashboard. Ga naar een dealer bewerken → tabblad "API Koppelingen".

9.1 Autorisatie & activatie van de koppeling (stappenplan)

Een koppeling komt pas tot stand nadat de dealer deze zelf autoriseert en activeert. FleetCycle koppelt nooit automatisch of zonder toestemming van de dealer. Het proces verloopt als volgt:

1. Akkoord van de dealer. De dealer geeft opdracht/akkoord om zijn CycleSoftware-account aan FleetCycle te koppelen. Dit gebeurt in het kader van de samenwerkingsovereenkomst tussen de dealer, FleetCycle en CycleSoftware.
2. Koppeling inschakelen. De dealer (of FleetCycle-beheerder namens de dealer) schakelt de CycleSoftware-koppeling in op dealer bewerken → tabblad "API Koppelingen" (cycleSoftwareEnabled = true).
3. CycleSoftware-inloggegevens invoeren. De dealer vult de van CycleSoftware ontvangen API Key, gebruikersnaam en wachtwoord in (zie §9.2).
4. Dealer API-sleutel genereren. De dealer genereert de FleetCycle API-sleutel (fc_live_...) en deelt deze veilig met CycleSoftware (zie §9.3). Deze sleutel autoriseert CycleSoftware om namens die specifieke dealer de endpoints aan te roepen.
5. Webhook instellen. De dealer kopieert de kant-en-klare webhook-URL en stelt deze in CycleSoftware in (zie §9.4).
6. Intrekken/stoppen. De dealer kan de autorisatie op elk moment ongedaan maken door de API-sleutel in te trekken of de koppeling uit te schakelen. CycleSoftware krijgt dan HTTP 401 en de toegang stopt direct.

Kort samengevat: de dealer bepaalt zelf of, wanneer en hoelang CycleSoftware toegang heeft. De autorisatie is per dealer, expliciet en op elk moment intrekbaar.

9.2 CycleSoftware-inloggegevens (API username & wachtwoord)

Onder "CycleSoftware Koppeling" vult de dealer de gegevens in waarmee FleetCycle verbinding maakt met CycleSoftware (nodig om o.a. de werkbon bij te werken en klantgegevens op te halen):

Alle drie de velden zijn nodig voordat de synchronisatie werkt. Deze gegevens verstrekt CycleSoftware aan de dealer.

9.3 Dealer API-sleutel (Bearer token)

In hetzelfde tabblad genereert de dealer de FleetCycle API-sleutel (fc_live_...) die CycleSoftware meestuurt als Authorization: Bearer-header bij endpoint 1 en 2 (zie §3.1). Met de knoppen genereren, kopiëren en intrekken.

9.4 Webhook-URL

In hetzelfde tabblad staat, onder "URLs voor CycleSoftware configuratie", de kant-en-klare Webhook URL (met de juiste tenantId) om te kopiëren en in CycleSoftware in te stellen (zie §8).

10. Testen

Voor een test-koppeling stelt FleetCycle een dealer (tenant) beschikbaar met de CycleSoftware-integratie ingeschakeld, inclusief slug/ID en een geldig workshop_order_id. Neem hiervoor contact op via [email protected].