sequenceDiagram
    actor Business_User as Business User
    participant ERP_System as ERP/P2P System
    participant ERP_Middleware as ERP Middleware
    participant Fairmarkit_API as Fairmarkit Public API

    rect rgb(125,125,125,.2)
      note over Business_User,Fairmarkit_API: Approval Status Check
        note right of Business_User: Business user needs to check<br>current approval status.
        Business_User ->> ERP_System: Request approval status
        ERP_System ->> ERP_Middleware: Check RFQ approval status
        ERP_Middleware ->> Fairmarkit_API: **GET** /self-service/api/v3/rfq/{uuid}/approvals
        Fairmarkit_API -->> ERP_Middleware: List of approval stages and steps
        ERP_Middleware -->> ERP_System: Current approval status
        ERP_System -->> Business_User: Display approval status
    end

    rect rgb(125,125,125,.2)
      note over Business_User,Fairmarkit_API: Approval Decision Process
        note right of Business_User: Business user makes approval<br>decisions (approve/reject).
        Business_User ->> ERP_System: Submit approval decision
        ERP_System ->> ERP_Middleware: Process approval decision

        loop For each approval step decision
            ERP_Middleware ->> Fairmarkit_API: **POST** /self-service/api/v3/rfq/{uuid}/approvals/{approval_id}/approve-step<br>or<br>**POST** /self-service/api/v3/rfq/{uuid}/approvals/{approval_id}/reject-step
            Fairmarkit_API -->> ERP_Middleware: Approval decision recorded
            ERP_Middleware -->> ERP_System: Step approval/rejection confirmed
            ERP_System -->> Business_User: Decision confirmation
        end
    end

Process flow

Approval Status Check Process:

Business User initiates request: The business user needs to check the current approval status of an RFQ and requests this information through their ERP system.
ERP System forwards request: The ERP system receives the request and forwards it to the ERP Middleware to check the RFQ approval status.
ERP Middleware calls Fairmarkit API: The ERP Middleware makes a GET request to Fairmarkit API endpoint:
```
GET /self-service/api/v3/rfq/{uuid}/approvals
```
where {uuid} is the unique identifier of the RFQ.

Fairmarkit API returns approval data: Fairmarkit API responds with an array of RFQApproval objects. Each approval contains:

id: Unique approval identifier (this is the approval_id needed for subsequent API calls)
status: Current approval status
stages: Array of approval stages, each containing steps

Example Response Structure:

[
  {
    "id": "fc4aba2d-a4e7-4e75-afa2-49106dce3322",
    "status": "in_progress",
    "target": "rfq",
    "target_id": "8b56aacd-bc19-4285-a9d0-a1da8e821123",
    "stages": [
      {
        "id": "3cb31506-ece1-4fc8-b4cd-7429b328d213",
        "status": "in_progress",
        "sequence": "sequential",
        "steps": [
          {
            "id": "2c9bf36a-9d3a-419e-a226-631ce51b1123",
            "approver": {
              "id": "b3e472e7-b111-499f-b6a1-23307be21232",
              "email": "[email protected]"
            },
            "status": "in_progress",
            "response": {
              "note": null,
              "reacted_at": null
            },
            "reassigned_at": null
          }
        ],
        "min_approved_steps_count": 1,
        "due_date": "2025-09-18T16:27:25.680989+00:00"
      }
    ],
    "created_at": "2025-09-15T16:27:25.691572+00:00",
    "updated_at": null
  }
]

Key Point: Extract the id field from the approval object - this becomes the approval_id for approve/reject operations.

ERP Middleware processes response: The ERP Middleware receives and processes the approval data from Fairmarkit API.
ERP System displays status: The processed approval status information flows back through the ERP system to be displayed to the business user.

Approval Decision Process:

Business User submits decision: The business user reviews the approval status and makes a decision to either approve or reject specific approval steps through the ERP system.
ERP System forwards decision: The ERP system receives the approval decision and forwards it to the ERP Middleware for processing.

ERP Middleware processes decisions: For each approval step that needs a decision, the ERP Middleware calls the appropriate Fairmarkit API endpoint:

For Approval:

POST /self-service/api/v3/rfq/{uuid}/approvals/{approval_id}/approve-step

Request Body (ApprovalStepRequest):

{
  "approver_email": "[email protected]",  // Required: Email of the approver making the decision
  "note": "Approved for Q4 procurement budget"  // Optional: Note explaining the approval
}

For Rejection:

POST /self-service/api/v3/rfq/{uuid}/approvals/{approval_id}/reject-step

Request Body (ApprovalStepRejectRequest):

{
  "approver_email": "[email protected]",  // Required: Email of the approver making the decision
  "note": "Rejected due to budget constraints"  // Required: Note explaining the rejection
}

Response (ApprovalIdResponse):

{
  "id": "approval-123-abc-456"  // Confirmation of the approval ID that was processed
}

ERP Middleware receives confirmation: The ERP Middleware receives confirmation that the approval decision has been successfully recorded.
ERP System confirms to user: The confirmation flows back through the ERP system to notify the business user that their decision has been processed successfully.

Note: This process repeats for each approvals that requires a decision, with the loop continuing until all necessary approvals/rejections are completed. If any step is rejected, the entire approval workflow may fail depending on the business rules configured.

Additional: Check Available Quotations for Awarding

During the approval process, users can retrieve all quotations (supplier responses) for the RFQ to understand which quotes are available for awarding:

GET /self-service/api/v3/rfq/{uuid}/quotations/

Key Fields for Awarding Process:

is_awarding: Boolean flag indicating whether the specific quotation item is currently in the awarding process
awarding_quantity: Numeric value showing the quantity being awarded for this item

This information is crucial for the approval process as it shows exactly which items and quantities are being awarded to which suppliers during the decision-making phase.