openapi: 3.0.3
info:
  title: VeroPay Horeca NFC Payment API
  version: "1.0.0"
  description: >
    This API integrates the NFC payment system with resort operations. It enables the restaurant
    POS to submit orders for processing, allows the booking system to register guest check-ins (assigning NFC bracelets),
    and provides separate endpoints to retrieve a guest's spending summary and NFC details.
servers:
  - url: https://api.vero.ro/v1
tags:
  - name: Billing
    description: Endpoints for processing orders and confirming NFC payments.
  - name: Guests
    description: Endpoints for guest check-in and details retrieval.
  - name: Gaupa-BCW
    description: Endpoints for BCW event.

security:
  - ApiKeyAuth: []

paths:
  /orders:
    post:
      tags:
        - Billing
      summary: Process a new order from the restaurant POS.
      description: >
        Receives order details from the restaurant POS, processes the payment through the NFC system,
        and returns a confirmation response.
      operationId: processOrder
      requestBody:
        description: Order details including orderId and purchased items.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Order processed and acknowledged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderAckResponse'
              example:
                success: true
                message: Order received
                orderId: ABC123
        '400':
          description: Invalid input or charge not approved.
        '500':
          description: Server error while processing the order.

  /orders/{orderId}:
    get:
      tags:
        - Billing
      summary: Retrieve order details based on orderId.
      description: >
        Retrieve details of a processed order by its orderId.
      operationId: getOrderDetails
      parameters:
        - name: orderId
          in: path
          required: true
          description: The unique order identifier.
          schema:
            type: string
      responses:
        '200':
          description: Order details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
              example:
                success: true
                message: Order found
                orderId: "ABC123"
                chargeId: "12"
                status: "closed"
                txHash: "ae1bd924...deadbeef"
                chargeTime: "2025-04-01 18:00:00"
                items:
                  - itemId: "burger"
                    quantity: 1
                    price: 30
                  - itemId: "beer"
                    quantity: 2
                    price: 12
                amount: "74.00"

        '404':
          description: Order not found.
        '500':
          description: Server error while retrieving order details.
  /guests/checkin:
    post:
      tags:
        - Guests
      summary: Register a guest check-in and assign an NFC bracelet.
      description: >
        Receives guest check-in details from the booking system, registers the guest in the NFC system,
        and assigns an NFC bracelet.
      operationId: guestCheckin
      requestBody:
        description: Guest check-in information.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestCheckin'
      responses:
        '201':
          description: Guest checked in and NFC bracelet assigned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestCheckinResponse'
        '400':
          description: Invalid input.
        '500':
          description: Server error during guest check-in.
  /guests/{guestId}/spending-summary:
    get:
      tags:
        - Guests
      summary: Retrieve the spending summary for a guest.
      description: >
        Retrieves the total amount spent and a detailed list of items charged to the NFC bracelet for the specified guest.
      operationId: getSpendingSummary
      parameters:
        - name: guestId
          in: path
          description: The unique identifier of the guest.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Spending summary retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendingSummary'
        '400':
          description: Invalid guest ID supplied.
        '500':
          description: Server error while retrieving spending summary.
  /guests/{guestId}/nfc-details:
    get:
      tags:
        - Guests
      summary: Retrieve the NFC details for a guest.
      description: >
        Retrieves NFC-specific details such as the assigned bracelet ID, activation status,
        and the timestamp of the last transaction for the specified guest.
      operationId: getNFCDetails
      parameters:
        - name: guestId
          in: path
          description: The unique identifier of the guest.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: NFC details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFCDetails'
        '400':
          description: Invalid guest ID supplied.
        '500':
          description: Server error while retrieving NFC details.
  /card/{braceletId}:
    get:
      tags:
        - Guests
      summary: Retrieve card details by bracelet ID
      description: Get activation status, resort ID and wallet address for a specific NFC bracelet
      operationId: getCardDetails
      parameters:
        - name: braceletId
          in: path
          description: The unique identifier of the NFC bracelet
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Card details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  activationStatus:
                    type: string
                    description: Current activation status of the NFC bracelet
                    enum: ["active", "inactive", "suspended"]
                  resortId:
                    type: string
                    description: ID of the resort where the bracelet is registered
                  walletAddress:
                    type: string
                    description: MultiversX wallet address associated with the bracelet
                    pattern: ^erd1[a-zA-Z0-9]{58}$
                required:
                  - activationStatus
                  - resortId
                  - walletAddress
        '400':
          description: Invalid bracelet ID supplied
        '404':
          description: Bracelet not found
        '500':
          description: Server error while retrieving card details
  /gaupa-bcw/card/{UID}:
    get:
      tags:
        - Gaupa-BCW
      summary: Retrieve card details by UID
      description: Get available credit, waranty status, tx histroy and wallet address for a specific NFC card
      operationId: getCardDetailsBCW
      parameters:
        - name: UID
          in: path
          description: The unique identifier of the NFC card
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Card details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: Indicates if the request was successful
                  Wallet:
                    type: string
                    description: MultiversX wallet address associated with the card
                    pattern: ^erd1[a-zA-Z0-9]{58}$
                  "Available credit":
                    type: string
                    description: Available credit amount
                  WarrantyAmount:
                    type: string
                    description: Warranty amount temporarily blocked
                  TotalAmount:
                    type: string
                    description: Total amount after warranty deduction
                  EffectiveBalance:
                    type: string
                    description: Effective balance on the card
                  Message:
                    type: string
                    description: Additional message about the card status
                  Transactions:
                    type: array
                    description: List of recent transactions
                    items:
                      type: object
                      properties:
                        EventID:
                          type: string
                          description: Event identifier
                        EventName:
                          type: string
                          description: Name of the event
                        EventMedia:
                          type: string
                          description: Media file associated with the event
                        TransactionID:
                          type: integer
                          description: Unique transaction identifier
                        Amount:
                          type: string
                          description: Transaction amount
                        TransactionType:
                          type: string
                          enum: ["Credit", "Debit"]
                          description: Type of transaction
                        Description:
                          type: string
                          description: Transaction description
                        POSAlias:
                          type: string
                          description: POS terminal alias
                        TransactionDetails:
                          type: string
                          description: Detailed transaction information
                        TxHash:
                          type: string
                          description: Transaction hash on blockchain
                        Timestamp:
                          type: string
                          format: date-time
                          description: Transaction timestamp
                required:
                  - Success
                  - Wallet
                  - "Available credit"
                  - WarrantyAmount
                  - TotalAmount
                  - EffectiveBalance
                  - Message
                  - Transactions
              example:
                Success: true
                Wallet: "erd138dpu4y624vm6hmuqfqhvqwfh39crpc5p4fgdvtq55t5asd73p7qav3g3w"
                "Available credit": "493.00"
                WarrantyAmount: "5.00"
                TotalAmount: "488.00"
                EffectiveBalance: "493.00"
                Message: "Warranty of 5.00 RON is temporarily blocked"
                Transactions:
                  - EventID: "12"
                    EventName: "Bucharest Christmas World"
                    EventMedia: "W6dRErTeFHT19L6dEJBkOxAUhD3EBYDu.png"
                    TransactionID: 15390
                    Amount: "-1.00"
                    TransactionType: "Debit"
                    Description: "Payment to POS"
                    POSAlias: "Test2"
                    TransactionDetails: "1.0000x Test BCW Ext Vendor x 1.00"
                    TxHash: "eb5e576afcf252976f753df9150b1ae8fb5cd789b9c64cbc8f553c5c00b9b5a2"
                    Timestamp: "2025-11-03 21:07:51"
                  - EventID: "12"
                    EventName: "Bucharest Christmas World"
                    EventMedia: "W6dRErTeFHT19L6dEJBkOxAUhD3EBYDu.png"
                    TransactionID: 15382
                    Amount: "500.00"
                    TransactionType: "Credit"
                    Description: "Cash Top-Up"
                    POSAlias: ""
                    TransactionDetails: ""
                    TxHash: "bf22714bb8aca15e4dc41031c069df3b20486d5f4002a192c0e346e1ee3a7547"
                    Timestamp: "2025-11-01 16:24:58"
                  - EventID: "12"
                    EventName: "Bucharest Christmas World"
                    EventMedia: "W6dRErTeFHT19L6dEJBkOxAUhD3EBYDu.png"
                    TransactionID: 15383
                    Amount: "-5.00"
                    TransactionType: "Debit"
                    Description: "Warranty"
                    POSAlias: ""
                    TransactionDetails: ""
                    TxHash: ""
                    Timestamp: "2025-11-01 16:24:58"
        '400':
          description: Invalid card UID supplied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                example:
                  error: "Invalid card UID supplied"
        '404':
          description: Card not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: Indicates if the request was successful
                  error:
                    type: string
                    description: Error message
                  message:
                    type: string
                    description: Detailed error description
                required:
                  - Success
                  - error
                  - message
              example:
                Success: false
                error: "Card not found"
                message: "The specified card UID does not exist."
        '500':
          description: Server error while retrieving card details
  /gaupa-bcw/decrypt/{picc_data}:
    get:
      tags:
        - Gaupa-BCW
      summary: Decrypt PICC data and retrieve UID
      description: Decrypt encrypted PICC data from NFC card and return the UID
      operationId: decryptPiccData
      parameters:
        - name: picc_data
          in: path
          description: The encrypted PICC data from the NFC card
          required: true
          schema:
            type: string
      responses:
        '200':
          description: PICC data decrypted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the decryption was successful
                  uid:
                    type: string
                    description: The decrypted UID from the PICC data
                required:
                  - success
                  - uid
              example:
                success: true
                uid: "04B4E58A306880"
        '400':
          description: Invalid PICC data supplied
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                  error:
                    type: string
                    description: Error message
                required:
                  - success
                  - error
              example:
                success: false
                error: "Decryption failed"
        '500':
          description: Server error while decrypting PICC data
  /gaupa-bcw/vendors:
    get:
      tags:
        - Gaupa-BCW
      summary: Retrieve list of all vendors
      description: Get a list of all available vendors in the system
      operationId: getVendorsBCW
      responses:
        '200':
          description: Vendors list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: Indicates if the request was successful
                  # Will be updated once response format is provided
                required:
                  - Success
              example:
                Success: true
                # Will be updated once response format is provided
        '500':
          description: Server error while retrieving vendors list
  /gaupa-bcw/vendor/{vendorID}:
    get:
      tags:
        - Gaupa-BCW
      summary: Retrieve vendor details by vendor ID
      description: Get vendor information and related data for a specific vendor
      operationId: getVendorDetailsBCW
      parameters:
        - name: vendorID
          in: path
          description: The unique identifier of the vendor
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Vendor details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: Indicates if the request was successful
                  VendorDetails:
                    type: object
                    description: Detailed information about the vendor
                    properties:
                      VendorID:
                        type: string
                        description: The unique identifier of the vendor
                      EventID:
                        type: string
                        description: The event identifier associated with the vendor
                      VendorName:
                        type: string
                        description: The name of the vendor
                      VendorAlias:
                        type: string
                        description: The alias or short name of the vendor
                      VendorFee:
                        type: string
                        description: The fee percentage for the vendor
                      VatPayer:
                        type: string
                        description: Indicates if vendor is a VAT payer
                        enum: ["yes", "no"]
                      NeedPrinter:
                        type: string
                        description: Indicates if vendor needs printer
                        enum: ["yes", "no"]
                      CashRegisterType:
                        type: string
                        description: Type of cash register used
                      VeroHardware:
                        type: string
                        description: Vero hardware type assigned
                      NumPos:
                        type: integer
                        description: Number of POS terminals
                      AllowTopups:
                        type: string
                        description: Whether topups are allowed
                        enum: ["yes", "no"]
                      NumAllowTopups:
                        type: integer
                        description: Number of allowed topups
                    required:
                      - VendorID
                      - EventID
                      - VendorName
                      - VendorAlias
                      - VendorFee
                      - VatPayer
                      - NeedPrinter
                      - CashRegisterType
                      - VeroHardware
                      - NumPos
                      - AllowTopups
                      - NumAllowTopups
                required:
                  - Success
                  - VendorDetails
              example:
                Success: true
                VendorDetails:
                  VendorID: "44"
                  EventID: "12"
                  VendorName: "vat da, printer da"
                  VendorAlias: "Test1"
                  VendorFee: "10.00"
                  VatPayer: "yes"
                  NeedPrinter: "yes"
                  CashRegisterType: "gigi"
                  VeroHardware: "P1"
                  NumPos: 1
                  AllowTopups: "no"
                  NumAllowTopups: 0
        '400':
          description: Invalid vendor ID supplied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                example:
                  error: "Invalid vendor ID"
        '404':
          description: Vendor not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: Indicates if the request was successful
                  error:
                    type: string
                    description: Error message
                  message:
                    type: string
                    description: Detailed error description
                required:
                  - Success
                  - error
                  - message
              example:
                Success: false
                error: "Vendor not found"
                message: "The specified vendor ID does not exist."
        '500':
          description: Server error while retrieving vendor details
  /gaupa-bcw/vendor/{vendorID}/sales:
    get:
      tags:
        - Gaupa-BCW
      summary: Retrieve sales details by vendor ID
      description: Get comprehensive sales statistics and breakdown for a specific vendor
      operationId: getVendorSalesBCW
      parameters:
        - name: vendorID
          in: path
          description: The unique identifier of the vendor
          required: true
          schema:
            type: string
        - name: event_id
          in: query
          description: Filter by event ID (use 'all' for all events)
          required: false
          schema:
            type: string
            default: "all"
        - name: pos_name
          in: query
          description: Filter by POS name (use 'all' for all POS)
          required: false
          schema:
            type: string
            default: "all"
        - name: transaction_type
          in: query
          description: Filter by transaction type
          required: false
          schema:
            type: string
            enum: ["all", "Credit", "Debit", "Refund"]
            default: "all"
        - name: start_date
          in: query
          description: Start date for filtering transactions (YYYY-MM-DD)
          required: false
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: End date for filtering transactions (YYYY-MM-DD)
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Vendor sales details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                  totalActivated:
                    type: string
                    description: Total number of activated cards
                  totalTopups:
                    type: string
                    description: Total amount of top-ups
                  totalSales:
                    type: string
                    description: Total sales amount
                  totalSalesNFC:
                    type: string
                    description: Total sales paid with NFC
                  totalSalesCard:
                    type: string
                    description: Total sales paid with card
                  totalBaseSales:
                    type: string
                    description: Total sales without VAT
                  totalTipsAmount:
                    type: string
                    nullable: true
                    description: Total tips amount
                  totalVatAmount:
                    type: string
                    description: Total VAT amount
                  vatBreakdown:
                    type: array
                    description: Breakdown of sales by VAT rate
                    items:
                      type: object
                      properties:
                        vat_rate:
                          type: string
                          description: VAT rate percentage
                        total_with_vat:
                          type: string
                          description: Total amount with VAT
                        total_without_vat:
                          type: string
                          description: Total amount without VAT
                        vat_amount:
                          type: string
                          description: VAT amount for this rate
                  pendingCredits:
                    type: number
                    description: Pending credits (topups minus sales)
                  events:
                    type: array
                    description: List of events
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Event ID
                        name:
                          type: string
                          description: Event name
                  posOptions:
                    type: array
                    description: List of available POS terminals
                    items:
                      type: string
                  transactionTypes:
                    type: array
                    description: List of transaction types
                    items:
                      type: string
                  vendors:
                    type: array
                    description: List of vendors
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Vendor ID
                        name:
                          type: string
                          description: Vendor name
                        alias:
                          type: string
                          description: Vendor alias
                        fee:
                          type: string
                          description: Vendor fee percentage
                required:
                  - success
                  - totalActivated
                  - totalTopups
                  - totalSales
                  - totalSalesNFC
                  - totalSalesCard
                  - totalBaseSales
                  - totalVatAmount
                  - vatBreakdown
                  - pendingCredits
                  - events
                  - posOptions
                  - transactionTypes
                  - vendors
              example:
                success: true
                totalActivated: "0"
                totalTopups: "0.00"
                totalSales: "25097.00"
                totalSalesNFC: "8162.00"
                totalSalesCard: "16935.00"
                totalBaseSales: "20741.322314049572"
                totalTipsAmount: null
                totalVatAmount: "4355.677685950416"
                vatBreakdown:
                  - vat_rate: "21"
                    total_with_vat: "25097.00"
                    total_without_vat: "20741.322314049572"
                    vat_amount: "4355.677685950416"
                pendingCredits: -25097
                events:
                  - id: "12"
                    name: "Baneasa Christmas World"
                posOptions:
                  - "POS1"
                transactionTypes:
                  - "Debit"
                  - "Credit"
                  - "Refund"
                vendors: []
        '400':
          description: Invalid vendor ID supplied
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                  error:
                    type: string
                    description: Error message
                required:
                  - success
                  - error
              example:
                success: false
                error: "Invalid vendor ID"
        '404':
          description: Vendor not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                  error:
                    type: string
                    description: Error message
                  message:
                    type: string
                    description: Detailed error description
                required:
                  - success
                  - error
                  - message
              example:
                success: false
                error: "Vendor not found"
                message: "The specified vendor ID does not exist."
        '500':
          description: Server error while retrieving vendor sales details

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

  schemas:
    Order:
      type: object
      required:
        - orderId
        - items
      properties:
        orderId:
          type: string
          description: Unique identifier for the order.
        items:
          type: array
          description: List of purchased items.
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      required:
        - itemId
        - quantity
        - price
      properties:
        itemId:
          type: string
          description: Unique identifier for the purchased item.
        quantity:
          type: integer
          description: Number of units purchased.
        price:
          type: number
          format: float
          description: Price per unit.
    OrderAckResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the order was processed successfully.
        message:
          type: string
          description: Confirmation or error message.
        orderId:
          type: string
          description: Identifier for the processed order.
      required:
        - success
        - message
        - orderId
    OrderResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the order was processed successfully.
        message:
          type: string
          description: Confirmation or error message.
        orderId:
          type: string
          description: Identifier for the processed order.
        chargeId:
          type: string
          description: Identifier for the charge generated by the NFC system.
        txHash:
          type: string
          description: Transaction hash related to the NFC payment.
      required:
        - success
        - message
        - orderId
    GuestCheckin:
      type: object
      required:
        - guestId
        - guestName
        - roomNumber
        - buildingName
      properties:
        guestId:
          type: string
          description: Unique identifier for the guest.
        guestName:
          type: string
          description: Name of the guest.
        roomNumber:
          type: string
          description: Room number or booking reference.
        buildingName:
          type: string
          description: Name of the building or resort area.
    GuestCheckinResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the check-in was successful.
        message:
          type: string
          description: Confirmation or error message.
        braceletId:
          type: string
          description: Assigned NFC bracelet identifier.
    SpendingSummary:
      type: object
      properties:
        totalSpent:
          type: number
          format: float
          description: Total amount spent.
        items:
          type: array
          description: Detailed list of items charged.
          items:
            $ref: '#/components/schemas/OrderItem'
    NFCDetails:
      type: object
      properties:
        braceletId:
          type: string
          description: The NFC bracelet identifier.
        activationStatus:
          type: string
          description: Current activation status of the NFC bracelet.
        lastTransactionTime:
          type: string
          format: date-time
          description: Timestamp of the last transaction made with the NFC bracelet.
