openapi: 3.0.3
info:
  title: VoordeMensen Ticketing API - filmfestival
  description: |
    REST API voor het VoordeMensen ticketplatform.
    
    Deze API is geconfigureerd voor client: **filmfestival**
    
    ## Tickets bestellen via API
    1. `GET /events` - Bekijk evenementen
    2. `GET /tickettypes/{event_id}` - Bekijk kaartsoorten
    3. `POST /cart` - Maak winkelwagen
    4. `POST /cart/{cart_id}` - Voeg tickets toe
    5. `GET /paymentmethods` - Bekijk betaalmethodes
    6. `POST /order/create` - Plaats bestelling → ontvang Mollie checkout URL
    
    ## Server Architectuur
    VoordeMensen gebruikt twee servers:
    - **API Server** (`api.voordemensen.nl`): Alle API endpoints
    - **Tickets Server** (`tickets.voordemensen.nl`): Order verwerking
    
    Sommige GET endpoints redirecten. Gebruik `curl -L` of volg redirects.
    
    ## Betalingen
    Orders retourneren een Mollie checkout URL. Redirect gebruikers daarheen.
    
  version: "1.0.0"
  contact:
    name: VoordeMensen Support
    url: https://voordemensen.nl/contact

servers:
  - url: https://api.voordemensen.nl/v1/filmfestival
    description: API Server voor filmfestival
  - url: https://tickets.voordemensen.nl/api/filmfestival
    description: Tickets Server (redirects)

tags:
  - name: Events
    description: Evenementen en beschikbaarheid
  - name: Cart
    description: Winkelwagen beheer
  - name: Orders
    description: Bestellingen en Mollie betalingen
  - name: Reference
    description: Referentiedata

paths:
  /events:
    get:
      summary: Lijst van evenementen
      operationId: getEvents
      tags: [Events]
      responses:
        '200':
          description: Evenementen array
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'

  /events/{id}:
    get:
      summary: Evenement details
      operationId: getEvent
      tags: [Events]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Evenement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'

  /events/{id}/avail:
    get:
      summary: Beschikbaarheid per kaartsoort
      operationId: getAvailability
      tags: [Events]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Beschikbaarheid
          content:
            application/json:
              schema:
                type: object

  /tickettypes/{event_id}:
    get:
      summary: Kaartsoorten voor evenement
      operationId: getTicketTypes
      tags: [Reference]
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Kaartsoorten array
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TicketType'

  /paymentmethods:
    get:
      summary: Beschikbare betaalmethodes
      operationId: getPaymentMethods
      tags: [Reference]
      responses:
        '200':
          description: Betaalmethodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentMethod'

  /cart:
    post:
      summary: Nieuwe winkelwagen aanmaken
      operationId: createCart
      tags: [Cart]
      responses:
        '201':
          description: Cart aangemaakt
          content:
            application/json:
              schema:
                type: object
                properties:
                  cart_id:
                    type: string
                    example: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

  /cart/{cart_id}:
    get:
      summary: Winkelwagen bekijken
      operationId: getCart
      tags: [Cart]
      parameters:
        - name: cart_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Cart inhoud

    post:
      summary: Tickets toevoegen aan cart
      operationId: addToCart
      tags: [Cart]
      parameters:
        - name: cart_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [event_id, numberoftickets, discount_id]
              properties:
                event_id:
                  type: integer
                numberoftickets:
                  type: integer
                  minimum: 1
                discount_id:
                  type: string
                  description: Encoded kaartsoort ID (hashid)
      responses:
        '200':
          description: Tickets toegevoegd
        '410':
          description: Geen tickets beschikbaar

  /order/create:
    post:
      summary: Bestelling plaatsen
      description: Retourneert Mollie checkout URL
      operationId: createOrder
      tags: [Orders]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [cart_id, payment_id, email]
              properties:
                cart_id:
                  type: string
                payment_id:
                  type: integer
                email:
                  type: string
                  format: email
                firstname:
                  type: string
                lastname:
                  type: string
      responses:
        '200':
          description: Order geplaatst
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'

  /order/{order_key}:
    get:
      summary: Bestellingstatus ophalen
      operationId: getOrder
      tags: [Orders]
      parameters:
        - name: order_key
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Order details

components:
  schemas:
    Event:
      type: object
      properties:
        event_id:
          type: integer
        event_name:
          type: string
        event_date:
          type: string
        event_time:
          type: string
        event_free:
          type: integer
          description: Beschikbare tickets
        location_name:
          type: string

    TicketType:
      type: object
      properties:
        discount_id:
          type: string
          description: Encoded hashid
        discount_name:
          type: string
        base_price:
          type: string
        discounted_price:
          type: string

    PaymentMethod:
      type: object
      properties:
        payment_id:
          type: integer
        payment_desc:
          type: string
        payment_cost:
          type: string

    OrderResponse:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Mollie checkout URL
          example: "https://www.mollie.com/checkout/select-issuer/ideal/abc123"
        order_key:
          type: string
          format: uuid