openapi: 3.1.0
info:
  title: WalletPlus POS-API
  version: '1.0.0'
  description: |
    Integration for kassesystemer (POS): hent ordrer, menukort og
    loyalitetssaldo — og meld fysiske butikssalg ind, så kunden optjener point
    ved disken.

    Adgang kræver TO ting: en partner-nøgle (jeres) og et aktivt samtykke fra
    den enkelte restaurant. Derfor bærer hvert kald et `company_id`.

    Vejledning med eksempler: https://docs.walletplus.dk/pos-api
  contact:
    name: WalletPlus
    email: support@walletplus.dk

servers:
  - url: https://api.walletplus.dk/api/pos/v1
    description: Produktion (kræver en wp_live_-nøgle)
  - url: https://api.staging.walletplus.dk/api/pos/v1
    description: Staging (kræver en wp_test_-nøgle)

security:
  - apiKey: []

tags:
  - name: Ordrer
  - name: Menukort
  - name: Virksomhed
  - name: Loyalitet
  - name: Salg

paths:
  /orders:
    get:
      tags: [Ordrer]
      summary: Hent ordrer (delta)
      description: |
        Keyset-pagineret. Første kald bruger `updated_since`; derefter sendes
        `next_cursor` fra forrige svar som `cursor`. Lav ALDRIG et nyt
        `updated_since` ud fra kassens eget ur — ur-skævhed taber ordrer.

        Kun afregnede ordrer: kontant fra start, kort og MobilePay først når
        betalingen er gået igennem. En betalt ordre er stadig med efter en
        refundering.
      operationId: listOrders
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - name: updated_since
          in: query
          schema: { type: string, format: date-time }
          description: Kun ved første kald. Ignoreres når `cursor` er sat.
        - name: cursor
          in: query
          schema: { type: string }
          description: Opak. Behandl den som en streng — formen kan ændre sig.
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
        - name: status
          in: query
          schema: { type: string }
          description: Kommasepareret, fx `confirmed,ready`.
      responses:
        '200':
          description: Ordrer, ældste ændring først
          content:
            application/json:
              schema:
                type: object
                required: [data, next_cursor, has_more, server_time]
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Order' }
                  next_cursor: { type: [string, 'null'] }
                  has_more: { type: boolean }
                  server_time: { type: string, format: date-time }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /orders/{orderId}:
    get:
      tags: [Ordrer]
      summary: Hent én ordre
      description: |
        En ubetalt kort- eller MobilePay-ordre giver 404, indtil betalingen er
        gået igennem.
      operationId: getOrder
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Ordren
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Order' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /menu:
    get:
      tags: [Menukort]
      summary: Hent hele menukortet
      description: |
        Ét helt snapshot med en `ETag`. Send den som `If-None-Match` og få 304
        når intet er ændret. Inaktive retter og undergrupper (tilvalgsgrupper
        under et bestemt valg) er ikke med.
      operationId: getMenu
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - name: If-None-Match
          in: header
          schema: { type: string }
      responses:
        '200':
          description: Menukortet
          headers:
            ETag:
              schema: { type: string }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Menu' }
        '304': { description: Uændret siden den sendte ETag }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }

  /company:
    get:
      tags: [Virksomhed]
      summary: Stamdata og åbningstider
      operationId: getCompany
      parameters:
        - $ref: '#/components/parameters/CompanyId'
      responses:
        '200':
          description: Virksomheden
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Company' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /loyalty/balance:
    get:
      tags: [Loyalitet]
      summary: Kundens pointsaldo
      description: Slå kunden op på `customer_id`, `phone` eller `email`.
      operationId: getLoyaltyBalance
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - name: customer_id
          in: query
          schema: { type: string, format: uuid }
        - name: phone
          in: query
          schema: { type: string }
        - name: email
          in: query
          schema: { type: string, format: email }
      responses:
        '200':
          description: Saldoen
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/LoyaltyBalance' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /loyalty/redeem:
    post:
      tags: [Loyalitet]
      summary: Indløs point ved kassen
      operationId: redeemPoints
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, points, reference]
              properties:
                company_id: { type: string, format: uuid }
                customer_id: { type: string, format: uuid }
                phone: { type: string }
                email: { type: string, format: email }
                points: { type: integer, minimum: 1 }
                reference:
                  type: string
                  maxLength: 128
                  description: Jeres egen reference. Samme reference bogføres aldrig to gange.
                description: { type: string, maxLength: 200 }
      responses:
        '201':
          description: Point indløst
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      customer_id: { type: string, format: uuid }
                      points_spent: { type: integer }
                      discount_minor: { type: integer }
                      balance: { type: integer }
                      already_applied: { type: boolean }
        '200':
          description: Var allerede indløst (gentaget kald)
        '400': { $ref: '#/components/responses/BadRequest' }
        '409':
          description: For få point, eller et identisk kald er i gang
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '422': { $ref: '#/components/responses/IdempotencyReused' }

  /sales:
    post:
      tags: [Salg]
      summary: Meld et fysisk butikssalg ind
      description: |
        Giver kunden point for et køb i butikken. Opretter ingen ordre hos os.
        Kunden er valgfri — uden `phone`/`email` gemmes salget med 0 point.
      operationId: createSale
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, external_id, gross_amount_minor, occurred_at]
              properties:
                company_id: { type: string, format: uuid }
                external_id:
                  type: string
                  maxLength: 128
                  description: Jeres bon-/transaktions-id. Andet lag af dedup.
                gross_amount_minor:
                  type: integer
                  minimum: 0
                  maximum: 10000000
                  description: |
                    Bonens bruttobeløb i øre — højst 100.000 kr. pr. bon. Point gives
                    højst for 25.000 kr. køb pr. kunde pr. døgn (rullende 24 timer);
                    se `points_capped` i svaret.
                occurred_at:
                  type: string
                  format: date-time
                  description: Hvornår salget skete i butikken.
                customer_id: { type: string, format: uuid }
                phone: { type: string }
                email: { type: string, format: email }
      responses:
        '201':
          description: Salget er registreret
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Sale' }
                  already_recorded: { type: boolean }
                  points_capped:
                    type: boolean
                    description: |
                      true når døgnloftet gav kunden færre point end bonen ellers ville.
                      Salget er registreret uanset; `data.points_earned` er det faktiske tal.
        '200':
          description: Samme `external_id` var meldt ind før — den oprindelige registrering
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/IdempotencyReused' }

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        `Authorization: Bearer wp_live_<prefix>_<hemmelighed>`.
        En `wp_test_`-nøgle virker kun mod staging.

  parameters:
    CompanyId:
      name: company_id
      in: query
      required: true
      schema: { type: string, format: uuid }
      description: Hvilken restaurant kaldet gælder. Kræver et aktivt samtykke.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: { type: string, maxLength: 255 }
      description: |
        Unik pr. handling. Et gentaget kald med samme nøgle returnerer det
        oprindelige svar. Samme nøgle med en ANDEN body giver 422.

  responses:
    BadRequest:
      description: Valideringsfejl
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Manglende, ukendt eller tilbagekaldt nøgle
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: Intet samtykke fra virksomheden, manglende scope eller pauseret partner
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Findes ikke i denne virksomhed
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: |
        Kvoten er brugt (600 kald/min pr. nøgle — også afviste kald tæller, når
        nøglen er genkendt), eller IP'en har sendt for mange ukendte/forkerte
        nøgler det seneste minut.
      headers:
        Retry-After:
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    IdempotencyReused:
      description: Idempotency-Key genbrugt til en anden forespørgsel
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, request_id]
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - invalid_key
                - key_revoked
                - partner_suspended
                - forbidden
                - no_grant
                - missing_scope
                - not_found
                - invalid_request
                - invalid_cursor
                - idempotency_key_required
                - idempotency_key_reused
                - conflict
                - rate_limited
                - internal_error
            message: { type: string }
            request_id: { type: string }
            fields:
              type: object
              additionalProperties:
                type: array
                items: { type: string }

    Order:
      type: object
      description: Beløb er ØRE som heltal (`_minor`). 159,50 kr = 15950.
      properties:
        id: { type: string, format: uuid }
        order_number: { type: string }
        company_id: { type: string, format: uuid }
        status:
          type: string
          enum: [pending, confirmed, preparing, ready, out_for_delivery, delivered, cancelled]
        order_type: { type: string, enum: [delivery, pickup, dine_in] }
        currency: { type: string, enum: [DKK] }
        subtotal_minor: { type: integer }
        discount_minor: { type: integer }
        points_discount_minor: { type: integer }
        delivery_fee_minor: { type: integer }
        packaging_fee_minor: { type: integer }
        service_fee_minor: { type: integer }
        total_minor: { type: integer }
        refunded_amount_minor: { type: integer }
        payment_method: { type: [string, 'null'] }
        payment_status:
          type: [string, 'null']
          enum: [pending, paid, failed, refunded, partially_refunded, null]
        points_used: { type: integer }
        customer:
          type: object
          description: Tom uden scopet `customers:read`.
          properties:
            id: { type: [string, 'null'] }
            name: { type: [string, 'null'] }
            phone: { type: [string, 'null'] }
            email: { type: [string, 'null'] }
        note: { type: [string, 'null'] }
        allergy_note: { type: [string, 'null'] }
        delivery_note: { type: [string, 'null'] }
        delivery_address: { type: [string, 'null'] }
        scheduled_for: { type: [string, 'null'], format: date-time }
        pickup_time: { type: [string, 'null'] }
        cancel_reason: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderLine' }

    OrderLine:
      type: object
      properties:
        id: { type: string, format: uuid }
        sku:
          type: [string, 'null']
          description: Restaurantens eget varenummer.
        product_id: { type: [string, 'null'] }
        product_name: { type: string }
        variant_name: { type: [string, 'null'] }
        category_name: { type: [string, 'null'] }
        quantity: { type: integer }
        unit_price_minor: { type: integer }
        line_total_minor: { type: integer }
        options:
          type: array
          items:
            type: object
            properties:
              group: { type: string }
              name: { type: string }
              price_minor: { type: integer }
        bundle_instance_id:
          type: [string, 'null']
          description: Linjer med samme værdi hører sammen på bonen.
        bundle_role: { type: [string, 'null'], enum: [primary, menu_upgrade_child, null] }

    Menu:
      type: object
      properties:
        company_id: { type: string, format: uuid }
        currency: { type: string, enum: [DKK] }
        etag: { type: string }
        categories:
          type: array
          items:
            type: object
            properties:
              id: { type: string, format: uuid }
              name: { type: string }
              description: { type: [string, 'null'] }
              sort_order: { type: integer }
              parent_category_id: { type: [string, 'null'] }
              products:
                type: array
                items: { $ref: '#/components/schemas/MenuProduct' }

    MenuProduct:
      type: object
      properties:
        id: { type: string, format: uuid }
        sku: { type: [string, 'null'] }
        name: { type: string }
        description: { type: [string, 'null'] }
        base_price_minor: { type: [integer, 'null'] }
        image_url: { type: [string, 'null'] }
        sold_out: { type: boolean }
        is_alcohol: { type: boolean }
        dine_in_only: { type: boolean }
        sort_order: { type: integer }
        variants:
          type: array
          items:
            type: object
            properties:
              id: { type: string, format: uuid }
              name: { type: string }
              price_minor: { type: integer }
              sold_out: { type: boolean }
              option_groups:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: string, format: uuid }
                    name: { type: string }
                    required: { type: boolean }
                    selection_type: { type: string, enum: [single, multiple] }
                    free_quantity: { type: integer }
                    options:
                      type: array
                      items:
                        type: object
                        properties:
                          id: { type: string, format: uuid }
                          name: { type: string }
                          price_minor: { type: integer }

    Company:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        slug: { type: [string, 'null'] }
        address: { type: [string, 'null'] }
        postal_code: { type: [string, 'null'] }
        city: { type: [string, 'null'] }
        phone: { type: [string, 'null'] }
        email: { type: [string, 'null'] }
        currency: { type: string, enum: [DKK] }
        timezone: { type: string, enum: [Europe/Copenhagen] }
        points_per_100kr: { type: number }
        point_value_minor: { type: integer, description: Ét point i øre. 1 point = 1 kr. }
        order_types:
          type: array
          items: { type: string, enum: [delivery, pickup, dine_in] }
        opening_hours:
          type: array
          items:
            type: object
            properties:
              day_of_week: { type: integer, minimum: 0, maximum: 6, description: 0 = mandag }
              opens: { type: [string, 'null'] }
              closes: { type: [string, 'null'] }
              closed: { type: boolean }

    LoyaltyBalance:
      type: object
      properties:
        customer_id: { type: string, format: uuid }
        company_id: { type: string, format: uuid }
        member: { type: boolean }
        balance: { type: integer }
        total_earned: { type: integer }
        total_spent: { type: integer }
        point_value_minor: { type: integer }
        movements:
          type: array
          items:
            type: object
            properties:
              id: { type: string, format: uuid }
              type: { type: string, enum: [earn, spend, adjust] }
              amount: { type: integer }
              balance_after: { type: integer }
              description: { type: [string, 'null'] }
              order_id: { type: [string, 'null'] }
              reference: { type: [string, 'null'] }
              created_at: { type: string, format: date-time }

    Sale:
      type: object
      properties:
        id: { type: string, format: uuid }
        company_id: { type: string, format: uuid }
        external_id: { type: string }
        customer_id: { type: [string, 'null'] }
        gross_amount_minor: { type: integer }
        currency: { type: string, enum: [DKK] }
        points_earned: { type: integer }
        occurred_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }

    WebhookEvent:
      type: object
      description: |
        Sendes til jeres endpoint. Signatur i headeren `X-WalletPlus-Signature`
        som `t=<unix>,v1=<hmac-sha256 hex over "<t>.<body>">`.
        Levering er at-least-once — dedupliker på `event_id`.
        `order.created` sendes, når ordren bliver synlig: kontant ved
        oprettelsen, kort og MobilePay når betalingen er gået igennem.
      properties:
        event_id: { type: string, format: uuid }
        event_type:
          type: string
          enum: [order.created, order.status_changed, order.cancelled]
        created_at: { type: string, format: date-time }
        company_id: { type: string, format: uuid }
        data:
          type: object
          properties:
            order_id: { type: string, format: uuid }
            order_number: { type: [string, 'null'] }
            status: { type: [string, 'null'] }
            order_type: { type: [string, 'null'] }
