openapi: 3.1.0
info:
  title: FuelU2 Supplier API
  description: >-
    API for managing supplier accounts, configurations, and markups across the
    FuelU2 ecosystem.
  version: 1.0.0
  contact:
    name: FuelU2 API Support
    email: support@fuelu2.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.fuelu2.com
    description: Production server
security:
  - bearerAuth: []
paths:
  /Users/login:
    post:
      operationId: userLogin
      summary: User Login
      description: >-
        Authenticates a user and returns a token that must be included in the
        Authorization header for subsequent requests.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                Email:
                  type: string
                  example: user@example.com
                Method:
                  type: string
                  example: API Call
                Password:
                  type: string
                  example: password123
                UserAgent:
                  type: string
                  example: web
              required:
                - Email
                - Password
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT token to be used in Authorization header.
                  userId:
                    type: string
                    description: ID of the authenticated user
  /Users/logout:
    post:
      summary: User Logout
      operationId: userLogout
      description: >-
        Logs out the currently authenticated user by invalidating their session
        token.
      tags:
        - Authentication
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                UserAgent:
                  type: string
                  example: web
              required:
                - UserAgent
      responses:
        '200':
          description: Successfully logged out
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Successfully logged out
  /SupplierDepots:
    post:
      summary: Create/Edit A Depot
      operationId: createOrEditSupplierDepot
      description: Create or update a depot.
      tags:
        - Depots
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                supplierId:
                  type: string
                  format: uuid
                name:
                  type: string
                address:
                  type: string
                contactNumber:
                  type: string
      responses:
        '200':
          description: Depot created or updated
  /SupplierDepots/paged:
    get:
      summary: Get A Paged Depot List
      operationId: getSupplierDepotsPaged
      description: Retrieve depots in a paginated format.
      tags:
        - Depots
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: pageSize
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successfully retrieved paged depots
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully retrieved depots
  /Orders:
    get:
      summary: List Orders
      operationId: getSupplierOrders
      description: Returns a list of orders.
      tags:
        - Orders
      security:
        - bearerAuth: []
      parameters:
        - name: query
          in: query
          schema:
            type: object
            properties:
              Page:
                type: integer
              PageSize:
                type: integer
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        Id:
                          type: string
                          example: 123e4567-e89b-12d3-a456-426614174000
                        Status:
                          type: string
                          example: InProgress
                        CustomerName:
                          type: string
                          example: Acme Corp
                  total:
                    type: integer
                    example: 42
  /Orders/{id}:
    get:
      summary: Get Orders By ID
      operationId: getSupplierOrderById
      description: Fetch a single order by ID.
      tags:
        - Orders
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order full details
          content:
            application/json:
              schema:
                type: object
                properties:
                  Id:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  Status:
                    type: string
                    example: InProgress
                  CustomerName:
                    type: string
                    example: Acme Corp
                  DeliveryNote:
                    type: string
                    example: DN-00123
  /Orders/verify:
    post:
      summary: Verify Orders
      operationId: verifySupplierOrder
      description: Verifies an order using OTP or registration.
      tags:
        - Orders
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                OrderId:
                  type: string
                  example: 123e4567-e89b-12d3-a456-426614174000
                OTP:
                  type: string
                  example: '456789'
      responses:
        '200':
          description: Verification successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  Id:
                    type: integer
                    example: 1
                  Status:
                    type: string
                    example: Verified
        '403':
          description: Forbidden or credit/processing error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Customer credit limit exceeded
        '404':
          description: OTP or registration incorrect
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OTP code or registration is incorrect
        '428':
          description: OTP expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OTP expired
  /Orders/fulfill:
    post:
      summary: Fulfill Orders
      operationId: fulfillSupplierOrder
      description: Fulfills an order and optionally uploads a POS/proof-of-sale file.
      tags:
        - Orders
      security:
        - bearerAuth: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                OrderId:
                  type: string
                  example: 123e4567-e89b-12d3-a456-426614174000
                File:
                  type: string
                  format: binary
      responses:
        '200':
          description: Order fulfilled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Order fulfilled successfully
        '404':
          description: Order fulfillment failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Order fulfillment failed
  /Orders/cancel:
    post:
      summary: Cancel Orders
      operationId: cancelOrder
      description: Allows users to cancel orders.
      tags:
        - Orders
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                OrderId:
                  type: string
                  format: uuid
                  example: d290f1ee-6c54-4b01-90e6-d701748f0851
                Reason:
                  type: string
                  example: Customer requested cancellation
              required:
                - OrderId
      responses:
        '200':
          description: Order cancelled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Order cancelled successfully
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No order found for user role
  /SupplierInvoices/submitinvoice:
    post:
      summary: Add An Order To An Invoice
      description: Submits a new supplier invoice and links related orders.
      operationId: submitSupplierInvoice
      security:
        - bearerAuth: []
      tags:
        - Orders
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                supplierInvoice:
                  type: string
                  description: JSON stringfiels supplier invoice submission command.
                  example: >-
                    {"SupplierId": "guid", "Orders": [{"Id": "guid",
                    "ActualFillAmount": 100}]}
                file:
                  type: string
                  format: binary
                  description: PDF or document file of the supplier invoice.
      responses:
        '200':
          description: Supplier invoice submitted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Supplier invoice submitted successfully.
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: You do not have appropriate access to this supplier.
  /Orders/removeOrderFromInvoice:
    post:
      summary: Remove Orders From Invoices
      operationId: removeOrderFromInvoice
      description: Removes an order from an invoice.
      tags:
        - Orders
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                OrderId:
                  type: string
                  example: 123e4567-e89b-12d3-a456-426614174000
                InvoiceId:
                  type: string
                  example: INV-00123
      responses:
        '200':
          description: Order removed from invoice successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Order removed from invoice successfully
  /SupplierInvoices:
    post:
      summary: Create/Edit An Invoice
      description: >-
        Creates a new or updates an existing supplier invoice for the
        authenticated SupplierAdmin.
      operationId: createOrEditSupplierInvoice
      security:
        - bearerAuth: []
      tags:
        - Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                SupplierId:
                  type: string
                  example: 4b0b2dcd-58b5-41a9-b8b9-202b67a828ae
                InvoiceNumber:
                  type: string
                  example: INV-2025-001
                Amount:
                  type: number
                  example: 10000
                DueDate:
                  type: string
                  format: date
                  example: '2025-11-01'
      responses:
        '200':
          description: Invoice created or updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Invoice created successfully.
        '401':
          description: Unauthorized access to supplier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: You do not have appropriate access to this supplier.
    get:
      summary: Get Invoices
      description: >-
        Retrieves a list of supplier invoices for the authenticated
        SupplierAdmin user.
      operationId: getSupplierInvoices
      security:
        - bearerAuth: []
      tags:
        - Invoices
      parameters:
        - name: SupplierId
          in: query
          required: true
          schema:
            type: string
          description: The supplier ID associated with the authenticated user.
        - name: Status
          in: query
          schema:
            type: string
            example: Pending
          description: Optional filter for invoice status.
      responses:
        '200':
          description: List of invoices retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: 3a7b5c12-8e1a-4f9a-b2a1-4d9b65d8e9af
                    invoiceNumber:
                      type: string
                      example: INV-001
                    status:
                      type: string
                      example: Pending
                    amount:
                      type: number
                      example: 12500.75
                    createdDate:
                      type: string
                      format: date-time
                      example: '2025-10-20T09:32:00Z'
        '401':
          description: Unauthorized access to supplier invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: You do not have appropriate access to this supplier.
  /pricechangerequest:
    post:
      summary: Request A Price Change
      description: |
        Allows a user to request a price change for a supplier depot.
      operationId: requestPriceChange
      security:
        - bearerAuth: []
      tags:
        - Price Change
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                SupplierDepotId:
                  type: string
                  description: >-
                    The unique ID of the supplier depot for which the price
                    change is being requested.
                  example: c5f3d11e-2a1d-42a7-9b2a-6e04b2a4f68a
                ProductId:
                  type: string
                  description: The product ID related to the price change.
                  example: a9b3fcd7-4b56-4a6b-8c0d-f2b145dd65f0
                NewPrice:
                  type: number
                  format: decimal
                  description: The new price being requested for the product.
                  example: 22.45
                EffectiveDate:
                  type: string
                  format: date
                  description: The date the new price should take effect.
                  example: '2025-11-01'
                Comments:
                  type: string
                  description: Optional comments or justification for the price change.
                  example: Increased supplier costs due to transport adjustments.
      responses:
        '200':
          description: Price change request submitted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Price change request submitted successfully.
        '400':
          description: Invalid or missing request data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid SupplierDepotId or missing required fields.
        '401':
          description: Unauthorized access to supplier depot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: You do not have appropriate access to this supplier depot.
        '500':
          description: Server error while processing the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      An unexpected error occurred while processing the price
                      change request.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
