Process flow

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
    participant Fairmarkit_APP as Fairmarkit System

    rect rgb(125,125,125,.2)
      note over Business_User,Fairmarkit_APP: Awarding the Request
        note right of Business_User: User reviews bids in the FM UI,<br>selects the most relevant bid,<br>and fills in the award reason if needed.
        Business_User ->> Fairmarkit_APP: Award Request
        Fairmarkit_APP-->>Fairmarkit_APP: -
        note over Fairmarkit_APP: Application updates the Request and quotation status,<br>and sends a webhook notification.
        Fairmarkit_APP ->> Fairmarkit_API: **WEBHOOK** event **REQUEST_COMPLETED**
        Fairmarkit_API ->> ERP_Middleware: **WEBHOOK** event **REQUEST_COMPLETED**
        ERP_Middleware-->>ERP_Middleware: -
        note over ERP_Middleware: Middleware: parses the payload,<br>logs the data, and optionally<br>updates information about the Request<br>status change.
        ERP_Middleware ->> ERP_System: Optional: Update info on Request status change
        ERP_Middleware ->> Fairmarkit_API: **GET** /self-service/api/v3/responses/request/{request_id}/?status=SELECTED
        Fairmarkit_API ->> Fairmarkit_APP: Internal API call to get Selected Responses
        Fairmarkit_APP -->> Fairmarkit_API: List of Selected Responses<br>
        Fairmarkit_API -->> ERP_Middleware: List of Selected Responses<br>
        ERP_Middleware-->>ERP_Middleware: -
        note over ERP_Middleware: Middleware: parses the payload,<br>logs the data, and identifies<br>selected responses.
        ERP_Middleware ->> Fairmarkit_API: **GET** /self-service/api/v3/responses/request/{request_id}/awarded-items/?response_id={response_id}&status=AWARDED
        Fairmarkit_API ->> Fairmarkit_APP: Internal API call to get Awarded Items
        Fairmarkit_APP -->> Fairmarkit_API: List of Awarded Items<br>(with quantities and award reasons)
        Fairmarkit_API -->> ERP_Middleware: List of Awarded Items<br>(with quantities and award reasons)
        ERP_Middleware ->> ERP_System: Update PR with awarded items
        ERP_System -->> Business_User: Display updated PR status
    end

Awarding the Request Process:

ERP Middleware receives the Request Completed webhook This webhook indicates that the event has been closed and awarded. Example Structure: REQUEST_COMPLETED
ERP Middleware retrieves selected responses: The ERP Middleware sends a GET request to the Fairmarkit API to retrieve the responses that were selected and contain awarded items for the request
```
GET /self-service/api/v3/responses/request/{request_id}/?status=SELECTED
```
where:
- {request_id} is the unique identifier of the Request.
- status=SELECTED filter only responses with awarded items
Example Response Structure (ResponseListRetrieve)
ERP Middleware retrieves awarded items: The ERP Middleware makes a GET request to retrieve only the awarded response items:
```
GET /self-service/api/v3/responses/request/{request_id}/awarded-items/?response_id={response_id}&status=AWARDED
```
where:
- {request_id} is the unique identifier of the Request.
- {response_id} filter awarded items by specific response IDs (can be multiple)
- status=AWARDED filter only responses with awarded items
Example Response Structure (AwardedItemListRetrieve)
ERP Middleware processes and enriches data: The ERP Middleware logs the data, identifies awarded quotations and lines, and updates the Request status change information.
ERP System confirms update: The confirmation flows back through the ERP system to notify the business user that the Request award has been processed and the PR has been updated.

Note: This process ensures that all awarded items are properly tracked and synchronized between Fairmarkit and the ERP system, with complete information about suppliers, pricing, quantities, and award reasons.

Additional: The ERP Middleware makes a GET request to retrieve response items that were not awarded, which contain additional metadata:

GET /self-service/api/v3/responses/request/{request_id}/response-items/

where {request_id} is the unique identifier of the Request.

Query Parameters:

response_id (optional): Filter response items by specific response IDs (can be multiple)
offset (optional): Pagination offset (default: 0)
limit (optional): Number of results per page (default: 10, max: 101)

Example Response Structure (ResponseItemListRetrieve)

Key Point: This endpoint returns response items that were NOT awarded. These items contain detailed metadata in the schema_data field that may be useful for analysis, reporting, or future reference.