openapi: 3.0.3
info:
  title: PlusOV Mobiliteits Events API
  description: |
    Deze REST API vervangt de SOAP-interfaces voor het realtime uitwisselen van status- en planningsgegevens tussen vervoerders (BCT) en PlusOV.
    
    **Beveiliging:** Deze API is beveiligd met OAuth2 (Client Credentials flow). Systemen moeten via het token-eindpunt een Bearer token opvragen met hun `client_id` en `client_secret`.
  version: 1.0.0
servers:
  - url: https://url.de.m.mimecastprotect.com/s/mf4RCY7jp9UqJ9Jc9iZfxaWZM?domain=vervoer.regieportaal.nl 
    description: Productieomgeving
  - url: https://url.de.m.mimecastprotect.com/s/07-aCZ8kO9ILVjVSysNfBUb9P?domain=vervoer.def.regieportaal.nl 
    description: Acceptatieomgeving

# Globaal toepassen van de OAuth2 beveiliging op alle paden
security:
  - OAuth2ClientCredentials:
      - write:events

paths:
  /voertuig-events:
    post:
      summary: Meld een actuele voertuigstatus (Voertuigevent)
      description: Ontvangt realtime status- en locatiegegevens van de BCT uit het voertuig (minimaal eens per minuut).
      operationId: postVoertuigEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoertuigEvent'
      responses:
        '201':
          description: Voertuigevent succesvol ontvangen en verwerkt.
        '400':
          description: Ongeldige JSON of ontbrekende verplichte velden.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /rit-events:
    post:
      summary: Meld een actuele ritstatus (Ritstatus event)
      description: Geeft realtime door wanneer een passagier instapt, uitstapt of wordt loosgemeld.
      operationId: postRitStatusEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RitStatusEvent'
      responses:
        '201':
          description: Ritstatus event succesvol ontvangen en verwerkt.
        '400':
          description: Ongeldige JSON of ontbrekende verplichte velden.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /planningen:
    post:
      summary: Ken een chauffeur/voertuig toe aan een route (PlanEvent)
      description: Wordt gebruikt om planningswijzigingen (chauffeurs- en voertuigkoppelingen) door te geven.
      operationId: postPlanEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanEvent'
      responses:
        '201':
          description: Planning succesvol verwerkt.
        '400':
          description: Ongeldige JSON of ontbrekende verplichte velden.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /absenties:
    post:
      summary: Meld een afwezige reiziger (AbsentEvent)
      description: Wordt gebruikt om te melden wanneer een reiziger niet deelneemt aan het vervoer.
      operationId: postAbsentEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AbsentEvent'
      responses:
        '201':
          description: Absentie succesvol geregistreerd.
        '400':
          description: Ongeldige JSON of ontbrekende verplichte velden.
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  # --- Beveiligingsdefinities ---
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth2 Client Credentials Flow voor Machine-to-Machine (M2M) authenticatie.
      flows:
        clientCredentials:
          tokenUrl: https://url.de.m.mimecastprotect.com/s/h97hC16g1vsoDZDsYtkfVJS61?domain=plusov.nl
          scopes:
            write:events: Toegang tot het aanmaken en versturen van mobiliteitsevents.

  responses:
    Unauthorized:
      description: Ongeldig, verlopen of ontbrekend OAuth2 Bearer token.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            example: 'Bearer error="invalid_token"'

  schemas:
    # --- 1. Voertuigevent Componenten ---
    VoertuigStatus:
      type: string
      enum: [WS, WE, P, X, ND]
      description: |
        De actuele status van het voertuig:
        * `WS` - DienstGeopend (Dienst gestart)
        * `WE` - DienstGesloten (Dienst gestopt)
        * `P` - Pauze (Niet ingepland)
        * `X` - Status onbekend
        * `ND` - Geen data (Al geruime tijd geen data)
    VoertuigEvent:
      type: object
      required: [contractId, voertuigNr, kenteken, chauffeurNr, gpsX, gpsY]
      properties:
        contractId:
          type: integer
          example: 12345
        voertuigNr:
          type: integer
          example: 987
        kenteken:
          type: string
          example: "AB-123-C"
        chauffeurNr:
          type: string
          example: "CH-4567"
        voertuigStatus:
          $ref: '#/components/schemas/VoertuigStatus'
        eventDatumTijd:
          type: string
          format: date-time
          example: "2026-05-20T10:57:00Z"
        gpsX:
          type: number
          format: float
          example: 51.92442
        gpsY:
          type: number
          format: float
          example: 4.47773

    # --- 2. Ritstatus Event Componenten ---
    RitStatus:
      type: integer
      enum: [8, 10, 11, 12, 13]
      description: |
        De actuele status van de rit:
        * `8` - Ingestapt (inVehicle)
        * `10` - Uitgestapt (outOfVehicle)
        * `11` - Loos (notThere)
        * `12` - Verwijderd (removed)
        * `13` - Foute ritgegevens (inError)
    RitStatusEvent:
      type: object
      required: [contractId, ritId, ritStatus, voertuigNr, kenteken]
      properties:
        contractId:
          type: integer
          example: 12345
        ritId:
          type: integer
          example: 987654
        ritStatus:
          $ref: '#/components/schemas/RitStatus'
        eventDatumTijd:
          type: string
          format: date-time
          example: "2026-05-20T10:58:00Z"
        routeNr:
          type: string
          example: "R-102-A"
        voertuigNr:
          type: integer
          example: 987
        kenteken:
          type: string
          example: "AB-123-C"

    # --- 3. PlanEvent Componenten ---
    PlanEvent:
      type: object
      required: [contractId, ritId, routeIdExt, instap, uitstap, driverIdExt]
      properties:
        contractId:
          type: integer
          example: 12345
        ritId:
          type: integer
          example: 987654
        routeIdExt:
          type: string
          example: "RT-LL-44"
        instap:
          type: integer
          example: 1
        uitstap:
          type: integer
          example: 4
        driverIdExt:
          type: string
          example: "CHAF-9921"
        vehicleIdExt:
          type: string
          example: "VTRG-883"

    # --- 4. AbsentEvent Componenten ---
    AbsentEvent:
      type: object
      required: [contractId, ritIdExt, datumVanaf, datumTijdMelding]
      properties:
        contractId:
          type: integer
          example: 12345
        ritIdExt:
          type: string
          example: "PAS-992831"
        routeIdExt:
          type: string
          example: "RT-LL-44"
        datumVanaf:
          type: string
          format: date
          example: "2026-05-21"
        datumTotEnMet:
          type: string
          format: date
          example: "2026-05-28"
        datumTijdMelding:
          type: string
          format: date-time
          example: "2026-05-20T10:58:34Z"
        opmerking:
          type: string
          example: "Reiziger is wegens ziekte afgemeld."