openapi: 3.0.0
paths:
  /v1/api/customers:
    post:
      description: Creates a new customer record in the system.
      operationId: CustomerController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerDto'
      responses:
        '201':
          description: The customer has been successfully created.
        '400':
          description: Bad request.
      summary: Create a new customer
      tags:
        - Customers
    get:
      description: >-
        Retrieves a list of all customers. Supports pagination and filtering by
        companyId.
      operationId: CustomerController_findAll
      parameters:
        - name: companyId
          required: false
          in: query
          description: Filter by company ID
          schema:
            type: string
        - name: skip
          required: false
          in: query
          description: >-
            Number of records to skip (must be a multiple of limit for accurate
            page numbers)
          schema:
            type: number
        - name: limit
          required: false
          in: query
          description: Maximum number of records to return
          schema:
            type: number
      responses:
        '200':
          description: List of customers
        '400':
          description: Bad request.
      summary: Get all customers
      tags:
        - Customers
  /v1/api/customers/{id}:
    put:
      description: Updates an existing customer record.
      operationId: CustomerController_update
      parameters:
        - name: id
          required: true
          in: path
          description: Customers ID
          schema:
            type: string
        - name: companyId
          required: false
          in: query
          description: Filter by company ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerDto'
      responses:
        '200':
          description: The customer has been successfully updated.
        '404':
          description: customer not found.
      summary: Update a customer by ID
      tags:
        - Customers
    get:
      description: Retrieves a single customer by its unique identifier.
      operationId: CustomerController_findOne
      parameters:
        - name: id
          required: true
          in: path
          description: Customers ID
          schema:
            type: string
        - name: companyId
          required: false
          in: query
          description: Filter by company ID
          schema:
            type: string
      responses:
        '200':
          description: The customer has been found.
        '404':
          description: customer not found.
      summary: Get a customer by ID
      tags:
        - Customers
    delete:
      description: Soft deletes a customer by setting isDeleted flag to true.
      operationId: CustomerController_remove
      parameters:
        - name: id
          required: true
          in: path
          description: Customers ID
          schema:
            type: string
        - name: companyId
          required: false
          in: query
          description: Filter by company ID
          schema:
            type: string
      responses:
        '204':
          description: The customer has been successfully deleted.
        '404':
          description: customer not found.
      summary: Delete a customer by ID
      tags:
        - Customers
info:
  title: Final POS Public API
  description: Public API for Final POS system
  version: 1.0.0
  contact: {}
  license:
    name: UNLICENSED
    url: https://www.finalpos.com
tags: []
servers:
  - url: /
components:
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: apiKey
      description: API Key for authentication
  schemas:
    NoteDto:
      type: object
      properties:
        message:
          type: string
          description: Note message
          example: Customer prefers email communication
        createdAt:
          format: date-time
          type: string
          description: Date when the note was created
          example: '2024-01-15T10:30:00Z'
      required:
        - message
    AddressDto:
      type: object
      properties:
        firstName:
          type: string
          description: First name
          example: John
        lastName:
          type: string
          description: Last name
          example: Doe
        company:
          type: string
          description: Company name
          example: Acme Corp
        address1:
          type: string
          description: Address line 1
          example: 123 Main St
        address2:
          type: string
          description: Address line 2
          example: Apt 4B
        city:
          type: string
          description: City
          example: New York
        state:
          type: string
          description: State or province
          example: NY
        country:
          type: string
          description: Country
          example: USA
        postCode:
          type: string
          description: Postal code
          example: '10001'
    CreateCustomerDto:
      type: object
      properties:
        companyId:
          type: string
          description: Company ID associated with the customer
          example: a1b2c3d4e5f6g7h8i9j0
        externalId:
          type: string
          description: External ID from third-party system
          example: x1y2z3a4b5c6d7e8f9g0
        email:
          type: string
          description: Email address of the customer
          example: customer@example.com
        firstName:
          type: string
          description: First name of the customer
          example: John
        lastName:
          type: string
          description: Last name of the customer
          example: Doe
        phone:
          type: string
          description: Phone number of the customer
          example: '+1234567890'
        tags:
          description: Tags associated with the customer
          example:
            - vip
            - returning
          type: array
          items:
            type: string
        fromOliver:
          type: boolean
          description: Flag to indicate if the customer is from Oliver
          example: true
        metadata:
          type: object
          description: Metadata associated with the customer
          additionalProperties:
            type: string
        notes:
          description: Notes associated with the customer
          example:
            - message: Customer prefers email communication
              createdAt: '2024-01-15T10:30:00Z'
            - message: VIP customer - handle with priority
              createdAt: '2024-01-20T14:00:00Z'
          type: array
          items:
            $ref: '#/components/schemas/NoteDto'
        billing:
          description: Billing address of the customer
          example:
            firstName: John
            lastName: Doe
            company: Acme Corp
            address1: 123 Main St
            address2: Suite 100
            city: New York
            state: NY
            country: USA
            postCode: '10001'
          allOf:
            - $ref: '#/components/schemas/AddressDto'
        shipping:
          description: Shipping address of the customer
          example:
            firstName: Jane
            lastName: Smith
            address1: 456 Oak Avenue
            address2: Apt 4B
            city: Los Angeles
            state: CA
            country: USA
            postCode: '90001'
          allOf:
            - $ref: '#/components/schemas/AddressDto'
        totalSpent:
          type: string
          description: Total amount the customer has spent
          example: '500.00'
        lastAction:
          format: date-time
          type: string
          description: Date of last action
          example: '2024-06-10T08:00:00Z'
        outletId:
          type: string
          description: Outlet ID associated with the customer
          example: o1p2q3r4s5t6u7v8w9x0y1z2
      required:
        - email
        - firstName
        - lastName
    UpdateCustomerDto:
      type: object
      properties:
        companyId:
          type: string
          description: Company ID associated with the customer
          example: a1b2c3d4e5f6g7h8i9j0
        externalId:
          type: string
          description: External ID from third-party system
          example: x1y2z3a4b5c6d7e8f9g0
        email:
          type: string
          description: Email address of the customer
          example: customer@example.com
        firstName:
          type: string
          description: First name of the customer
          example: John
        lastName:
          type: string
          description: Last name of the customer
          example: Doe
        phone:
          type: string
          description: Phone number of the customer
          example: '+1234567890'
        tags:
          description: Tags associated with the customer
          example:
            - vip
            - returning
          type: array
          items:
            type: string
        fromOliver:
          type: boolean
          description: Flag to indicate if the customer is from Oliver
          example: true
        metadata:
          type: object
          description: Metadata associated with the customer
          additionalProperties:
            type: string
        notes:
          description: Notes associated with the customer
          example:
            - message: Customer prefers email communication
              createdAt: '2024-01-15T10:30:00Z'
            - message: VIP customer - handle with priority
              createdAt: '2024-01-20T14:00:00Z'
          type: array
          items:
            $ref: '#/components/schemas/NoteDto'
        billing:
          description: Billing address of the customer
          example:
            firstName: John
            lastName: Doe
            company: Acme Corp
            address1: 123 Main St
            address2: Suite 100
            city: New York
            state: NY
            country: USA
            postCode: '10001'
          allOf:
            - $ref: '#/components/schemas/AddressDto'
        shipping:
          description: Shipping address of the customer
          example:
            firstName: Jane
            lastName: Smith
            address1: 456 Oak Avenue
            address2: Apt 4B
            city: Los Angeles
            state: CA
            country: USA
            postCode: '90001'
          allOf:
            - $ref: '#/components/schemas/AddressDto'
        totalSpent:
          type: string
          description: Total amount the customer has spent
          example: '500.00'
        lastAction:
          format: date-time
          type: string
          description: Date of last action
          example: '2024-06-10T08:00:00Z'
        outletId:
          type: string
          description: Outlet ID associated with the customer
          example: o1p2q3r4s5t6u7v8w9x0y1z2
security:
  - api-key: []
