orders:
  get:
    tags: [Shared Orders]
    summary: List my orders or return requests (client or provider)
    description: |
      Shared list for **both** Client and Provider tokens.

      - `type=order`: normal orders scoped by the bearer token.
        - Client → orders where the client is the buyer.
        - Provider → orders where the provider is the seller (`clientName` exposed).
        - `status` is **required**: `new` | `current` | `finished` | `cancelled`.
        - `new` = awaiting provider decision / unpaid.
        - `current` = paid / in progress (provider list also includes paid `new` rows).
        - `finished` = client confirmed receipt.
        - `cancelled` = cancelled or rejected orders.
      - `type=return`: return requests scoped by the same actor.
        - `status` is **required**: `new` | `current` | `finished` only.
        - Mapping: created → `new`, accepted/handed → `current`,
          completed/rejected → `finished`.
        - Response uses the same list card shape as normal orders.
      - Pagination uses `page` and `limit` query params.
      - Swagger UI: choose **Client token** or **Provider token** before Execute.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87048&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Header Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25218&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Header Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87048&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Header Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25218&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Header Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79148&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Order New Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9410-1619&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order New Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87118&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Order New Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25260&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order New Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79920&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Order Current Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9415-1705&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order Current Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79148&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Order Current Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25300&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order Current Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-80590&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Order Finished Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1446&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order Finished Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87354&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Order Finished Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25340&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order Finished Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1658&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order Cancelled Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1658&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order Cancelled Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87472&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Order Cancelled Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25380&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Order Cancelled Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89367&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Return New Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3925&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Return New Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87178&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Return New Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25281&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Return New Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89401&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Return Current Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3946&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Return Current Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87296&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Return Current Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25321&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Return Current Provider Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89435&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Return Finished Client Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3967&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Return Finished Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87414&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Return Finished Provider Web</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25361&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Return Finished Provider Mobile</a></div>
    operationId: listOrders
    x-figma:
      headerClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87048&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      headerClientWebNodeId: "10760:87048"
      headerClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25218&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      headerClientMobileNodeId: "9967:25218"
      headerProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87048&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      headerProviderWebNodeId: "10760:87048"
      headerProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25218&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      headerProviderMobileNodeId: "9967:25218"
      orderNewClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79148&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      orderNewClientWebNodeId: "10245:79148"
      orderNewClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9410-1619&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderNewClientMobileNodeId: "9410:1619"
      orderNewProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87118&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      orderNewProviderWebNodeId: "10760:87118"
      orderNewProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25260&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderNewProviderMobileNodeId: "9967:25260"
      orderCurrentClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79920&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      orderCurrentClientWebNodeId: "10245:79920"
      orderCurrentClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9415-1705&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderCurrentClientMobileNodeId: "9415:1705"
      orderCurrentProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79148&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      orderCurrentProviderWebNodeId: "10245:79148"
      orderCurrentProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25300&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderCurrentProviderMobileNodeId: "9967:25300"
      orderFinishedClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-80590&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      orderFinishedClientWebNodeId: "10245:80590"
      orderFinishedClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1446&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderFinishedClientMobileNodeId: "9419:1446"
      orderFinishedProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87354&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      orderFinishedProviderWebNodeId: "10760:87354"
      orderFinishedProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25340&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderFinishedProviderMobileNodeId: "9967:25340"
      orderCancelledClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1658&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderCancelledClientWebNodeId: "9419:1658"
      orderCancelledClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1658&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderCancelledClientMobileNodeId: "9419:1658"
      orderCancelledProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87472&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      orderCancelledProviderWebNodeId: "10760:87472"
      orderCancelledProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25380&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      orderCancelledProviderMobileNodeId: "9967:25380"
      returnNewClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89367&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnNewClientWebNodeId: "10245:89367"
      returnNewClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3925&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnNewClientMobileNodeId: "9440:3925"
      returnNewProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87178&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnNewProviderWebNodeId: "10760:87178"
      returnNewProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25281&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnNewProviderMobileNodeId: "9967:25281"
      returnCurrentClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89401&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnCurrentClientWebNodeId: "10245:89401"
      returnCurrentClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3946&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnCurrentClientMobileNodeId: "9440:3946"
      returnCurrentProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87296&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnCurrentProviderWebNodeId: "10760:87296"
      returnCurrentProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25321&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnCurrentProviderMobileNodeId: "9967:25321"
      returnFinishedClientWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89435&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnFinishedClientWebNodeId: "10245:89435"
      returnFinishedClientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3967&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnFinishedClientMobileNodeId: "9440:3967"
      returnFinishedProviderWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87414&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnFinishedProviderWebNodeId: "10760:87414"
      returnFinishedProviderMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25361&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnFinishedProviderMobileNodeId: "9967:25361"
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum: [order, return]
        description: |
          Which list to load:
          - `order`: normal orders.
          - `return`: return requests for the same actor.
      - name: status
        in: query
        required: true
        schema:
          type: string
          enum: [new, current, finished, cancelled]
        description: |
          List tab filter.
          - `type=order`: `new` | `current` | `finished` | `cancelled`.
          - `type=return`: `new` | `current` | `finished` only
            (`cancelled` is rejected).
      - name: page
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 1 }
      - name: limit
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 15 }
    responses:
      '200':
        description: Orders list for the authenticated actor.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/OrderListResponse'
            examples:
              ordersList:
                summary: Normal orders list (type=order)
                value:
                  key: success
                  message: الطلبات العادية
                  status: 200
                  data:
                    - id: "6a6f0ab91af1d34b05615dc5"
                      orderNumber: 27
                      orderNumberText: "#رقم الطلب: 27"
                      clientName: ""
                      status: new
                      statusText: جديد
                      productName: سماعات سوني
                      productImage: "https://dashboard.kam-teswa.4hoste.com/assets/uploads/products/6a69c9117b182fb0ce4bfcdf/image741785317649159.png"
                      date: "٢٠٢٦/٠٨/٠٢"
                      totalPrice: 264
                      totalPriceText: "264 ﷼"
                      currency: "﷼"
                      actions:
                        detailsButton: true
                  paginate:
                    currentPage: 1
                    lastPage: 1
                    perPage: 15
                    total: 1
              returnRequestsList:
                summary: Return requests list (type=return)
                value:
                  key: success
                  message: طلبات الإرجاع
                  status: 200
                  data:
                    - id: "665f1c2a9b4e1d0012ab34e1"
                      orderNumber: 1042
                      orderNumberText: "#رقم الطلب: 1042"
                      clientName: ""
                      status: new
                      statusText: جديد
                      productName: جرار زراعي
                      productImage: "https://example.com/product.jpg"
                      date: "٢٠٢٦/٠٧/٣٠"
                      totalPrice: 1150
                      totalPriceText: "1150 ﷼"
                      currency: "﷼"
                      actions:
                        detailsButton: true
                  paginate:
                    currentPage: 1
                    lastPage: 1
                    perPage: 15
                    total: 1
      '400':
        description: Validation error (e.g. missing/invalid `status`).
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: fail, message: "الحالة يجب أن تكون جديد أو حالي أو منتهي", status: 400 }
      '419':
        description: Missing/invalid token or unrecognized actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

order:
  get:
    tags: [Shared Orders]
    summary: Get order or return-request details
    x-figma:
      # Action designs shown on the order-details screen (links already registered on each action endpoint).
      paymentButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      paymentButtonMobileNodeId: "9432:2781"
      paymentButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      paymentButtonWebNodeId: "10245:82266"
      cancelButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      cancelButtonMobileNodeId: "9432:2781"
      cancelButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      cancelButtonWebNodeId: "10245:82266"
      receivedButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-3240&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      receivedButtonMobileNodeId: "9432:3240"
      receivedButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-85714&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      receivedButtonWebNodeId: "10245:85714"
      acceptButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      acceptButtonMobileNodeId: "9967:25401"
      acceptButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      acceptButtonWebNodeId: "10760:87532"
      rejectButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      rejectButtonMobileNodeId: "9967:25401"
      rejectButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      rejectButtonWebNodeId: "10760:87532"
      deliveredToCustomerButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25493&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      deliveredToCustomerButtonMobileNodeId: "9967:25493"
      deliveredToCustomerButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87896&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      deliveredToCustomerButtonWebNodeId: "10760:87896"
      returnRequestButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9442-3771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnRequestButtonMobileNodeId: "9442:3771"
      returnRequestButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-88314&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnRequestButtonWebNodeId: "10245:88314"
      rateButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9435-3220&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      rateButtonMobileNodeId: "9435:3220"
      rateButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-86686&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      rateButtonWebNodeId: "10245:86686"
      # Return-details action designs (same button keys; links already registered on return-request endpoints).
      returnAcceptButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnAcceptButtonMobileNodeId: "9967:25429"
      returnAcceptButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnAcceptButtonWebNodeId: "10760:87591"
      returnRejectButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnRejectButtonMobileNodeId: "9967:25429"
      returnRejectButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnRejectButtonWebNodeId: "10760:87591"
      returnDeliveredButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-5037&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnDeliveredButtonMobileNodeId: "9449:5037"
      returnDeliveredButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-93482&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnDeliveredButtonWebNodeId: "10245:93482"
      returnReceivedButtonMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25473&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      returnReceivedButtonMobileNodeId: "9967:25473"
      returnReceivedButtonWeb: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87638&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      returnReceivedButtonWebNodeId: "10760:87638"
    description: |
      <div class="figma-links"><span>Design (order-details actions, type=order):</span>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">paymentButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">paymentButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">cancelButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">cancelButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-3240&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">receivedButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-85714&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">receivedButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">acceptButton / rejectButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">acceptButton / rejectButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25493&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">deliveredToCustomerButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87896&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">deliveredToCustomerButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9442-3771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">returnRequestButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-88314&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">returnRequestButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9435-3220&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">rateButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-86686&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">rateButton Web</a>
      </div>

      <div class="figma-links"><span>Design (return-details actions, type=return — same button keys):</span>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">acceptButton / rejectButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">acceptButton / rejectButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-5037&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">deliveredToCustomerButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-93482&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">deliveredToCustomerButton Web</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25473&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">receivedButton Mobile</a>
      <a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87638&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">receivedButton Web</a>
      </div>

      Shared details for **both** Client and Provider tokens.

      - `type=order`: a single owned order with product line, lifecycle
        flags, and action buttons for the current actor.
      - `type=return`: a single owned return request (same OrderDetails DTO shape +
        action flags remapped to return-request endpoints). `id` is the return-request ObjectId.
      - Ownership is enforced by the bearer token.
      - Swagger UI: choose **Client token** or **Provider token** before Execute.

      ### Action buttons (`data.actions.*` — true only for the current actor's turn)
      Same keys for both `type=order` and `type=return`; endpoint target depends on `type`.

      | Button | type=order | type=return | When true |
      |---|---|---|---|
      | `actions.paymentButton` | `POST /order/payment` | always `false` | Client + accepted + unpaid |
      | `actions.cancelButton` | `PATCH /order/cancel` | always `false` | Client + awaiting approval |
      | `actions.receivedButton` | `PATCH /order/received` | `PATCH /return-request/received` | Order: client + paid + delivered_to_customer. Return: provider + client_delivered |
      | `actions.acceptButton` | `PATCH /order/accept` | `PATCH /return-request/accept` | Order: provider + awaiting approval. Return: provider + pending_review |
      | `actions.rejectButton` | `PATCH /order/reject` | `PATCH /return-request/reject` | Order: provider + unpaid NEW. Return: provider + pending_review |
      | `actions.deliveredToCustomerButton` | `PATCH /order/delivered` | `PATCH /return-request/delivered` | Order: provider + paid current + deliverable. Return: client + accepted |
      | `actions.returnRequestButton` | `POST /return-request` | always `false` | Client + finished received + no return yet + still inside the dashboard return window |
      | `actions.chatButton` | chat room | chat room | Order/return not cancelled/rejected |
      | `actions.rateButton` | `POST /rate` | always `false` | Client + finished paid received + not rated |
    operationId: getOrderDetails
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum: [order, return]
        description: |
          Which resource to load:
          - `order`: normal order details.
          - `return`: return-request details.
      - name: id
        in: query
        required: true
        schema:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
          example: "665f1c2a9b4e1d0012ab34d0"
        description: |
          When `type=order`: Order ObjectId owned by the authenticated actor.
          When `type=return`: ReturnRequest ObjectId owned by the authenticated actor.
    responses:
      '200':
        description: |
          Order details when `type=order`, or return-request details when `type=return`.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/OrderDetailsResponse'
            examples:
              orderDetails:
                summary: Provider — awaiting approval (Figma details screen)
                value:
                  key: success
                  message: تفاصيل الطلب
                  status: 200
                  data:
                    id: "665f1c2a9b4e1d0012ab34d0"
                    warningText: يجب تأكيد قبول الطلب خلال 5 ساعات حتى لا يعتبر الطلب ملغى
                    statusSteps:
                      - key: awaiting_approval
                        title: في انتظار الموافقة
                        description: في انتظار الموافقة على الطلب
                        isCompleted: false
                        isActive: true
                      - key: awaiting_payment
                        title: قيد الدفع
                        description: بانتظار تأكيد الدفع من العميل
                        isCompleted: false
                        isActive: false
                      - key: delivering
                        title: جاري التسليم
                        description: تم تسليم الطلب للمندوب وفي الطريق إلى العميل
                        isCompleted: false
                        isActive: false
                      - key: finished
                        title: منتهي
                        description: تم تسليم الطلب للعميل
                        isCompleted: false
                        isActive: false
                    orderNumber: 12315
                    orderNumberText: "#رقم الطلب: 12315"
                    date: "٢٠٢٥/٠١/٢٥"
                    time: "08:00 مساء"
                    reasonTitle: ""
                    reason: ""
                    status: new
                    statusText: قيد المراجعة
                    product:
                      id: "665f1c2a9b4e1d0012ab34ce"
                      image: "https://example.com/product.jpg"
                      name: سماعات سوني
                      description: وصف المنتج
                      condition: used
                      conditionText: مستعمل
                      count: 1
                      price: 1400
                      priceText: "1400 ﷼"
                      attributes:
                        - name: الماركة
                          value: لايكا
                        - name: الموديل
                          value: M3
                    aiPrice:
                      aiSuggestedPrice: 0
                      aiSuggestedPriceText: "0 ﷼"
                      currency: "﷼"
                      repriceButton: false
                    totalPrice:
                      totalPrice: 264
                      totalPriceText: "264 ﷼"
                      currency: "﷼"
                    provider:
                      image: "https://example.com/store.png"
                      name: متجر الأنتيكات الفاخرة
                      address: "الرياض، السعودية"
                      lat: 24.7136
                      lng: 46.6753
                    deliveryAddress:
                      title: عنوان التوصيل
                      name: أحمد محمد
                      phone: "+966 50 123 4567"
                      address: "شارع الملك فهد، حي النخيل"
                      lat: 24.7136
                      lng: 46.6753
                    chatId: "665f1c2a9b4e1d0012ab34d0"
                    returnReason: null
                    attachments: []
                    actions:
                      canClientConfirmReceived: false
                      paymentButton: false
                      cancelButton: false
                      receivedButton: false
                      acceptButton: true
                      rejectButton: true
                      deliveredToCustomerButton: false
                      returnRequestButton: false
                      chatButton: true
                      rateButton: false
                    rate:
                      product: null
                      provider: null
              returnRequestDetails:
                summary: Return-request details (type=return)
                value:
                  key: success
                  message: تفاصيل طلب الإرجاع
                  status: 200
                  data:
                    id: "665f1c2a9b4e1d0012ab34e1"
                    warningText: ""
                    statusSteps:
                      - key: awaiting_approval
                        title: في انتظار الموافقة
                        description: في انتظار الموافقة على طلب الإرجاع الخاص بك
                        isCompleted: true
                        isActive: true
                      - key: collecting_from_client
                        title: جاري الإستلام من العميل
                        description: المندوب في الطريق إليك لإستلام طلبك
                        isCompleted: false
                        isActive: false
                      - key: delivered_to_merchant
                        title: تم التسليم للمعلن
                        description: تم تسليم الطلب للمعلن
                        isCompleted: false
                        isActive: false
                    orderNumber: 1042
                    orderNumberText: "#رقم الطلب: 1042"
                    date: "٢٠٢٦/٠٧/٣٠"
                    time: "01:00 مساء"
                    reasonTitle: ""
                    reason: المنتج تالف
                    status: new
                    statusText: جديد
                    product:
                      id: "665f1c2a9b4e1d0012ab34ce"
                      image: "https://example.com/product.jpg"
                      name: جرار زراعي
                      description: وصف المنتج
                      condition: used
                      conditionText: مستعمل
                      count: 1
                      price: 1150
                      priceText: "1150 ﷼"
                      attributes: null
                    aiPrice:
                      aiSuggestedPrice: 0
                      aiSuggestedPriceText: "0 ﷼"
                      currency: "﷼"
                      repriceButton: false
                    totalPrice:
                      totalPrice: 1150
                      totalPriceText: "1150 ﷼"
                      currency: "﷼"
                    provider:
                      image: "https://example.com/store.png"
                      name: متجر تجريبي
                      address: "الرياض، السعودية"
                      lat: 24.7136
                      lng: 46.6753
                    deliveryAddress:
                      title: عنوان التوصيل
                      name: أحمد محمد
                      phone: "+966 50 123 4567"
                      address: "شارع الملك فهد، حي النخيل"
                      lat: 24.7136
                      lng: 46.6753
                    chatId: "665f1c2a9b4e1d0012ab34d0"
                    returnReason:
                      title: سبب الإرجاع
                      reason: المنتج تالف
                      attachments:
                        - "https://example.com/uploads/return-requests/665f1c2a9b4e1d0012ab34e1/evidence.jpg"
                    attachments:
                      - "https://example.com/uploads/return-requests/665f1c2a9b4e1d0012ab34e1/evidence.jpg"
                    actions:
                      canClientConfirmReceived: false
                      paymentButton: false
                      cancelButton: false
                      receivedButton: false
                      acceptButton: true
                      rejectButton: true
                      deliveredToCustomerButton: false
                      returnRequestButton: false
                      chatButton: true
                      rateButton: false
                    rate:
                      product:
                        id: "665f1c2a9b4e1d0012ab34e2"
                        name: أحمد الدوسري
                        date: "٢٠٢٤/٠١/٠٨"
                        rate: 5
                        comment: كاميرا تحفة فنية! تعمل بشكل مثالي والصور التي تنتجها رائعة.
                      provider:
                        id: "665f1c2a9b4e1d0012ab34e2"
                        name: أحمد الدوسري
                        date: "٢٠٢٤/٠١/٠٨"
                        rate: 5
                        comment: تعامل ممتاز وخدمة سريعة واحترافية.
      '400':
        description: Missing/invalid id or order not owned by the actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: fail, message: "الطلب غير موجود", status: 400 }
      '419':
        description: Missing/invalid token.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

  post:
    tags: [Client Order]
    summary: Confirm a direct-buy order
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9509-8480&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9509:8480"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10242-54434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10242:54434"
    description: |
      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9509-8480&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10242-54434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>

      Creates a purchase order for a single product (direct buy).

      - Client bearer token only; provider tokens are rejected.
      - `count` must not exceed the available stock; stock is reserved atomically
        on creation.
      - The order starts as `new`, awaiting provider approval, with a
        purchase-time product snapshot stored on it.
      - Creates a private order chat with `_id` equal to the order id
        (`orderRef=Order`) between the client and store.
    operationId: confirmOrder
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [productId, count]
            properties:
              productId:
                type: string
                pattern: '^[a-fA-F0-9]{24}$'
                example: "665f1c2a9b4e1d0012ab34ce"
              count:
                type: integer
                minimum: 1
                example: 2
    responses:
      '200':
        description: Order created and sent to the store for review.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ConfirmOrderResponse'
            example:
              key: success
              message: تم ارسال الطلب بنجاح
              status: 200
      '400':
        description: Validation failed, out of stock, product/store unavailable, or non-client actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            examples:
              onlyClient:
                value: { key: fail, message: "لا يمكن تأكيد الطلب إلا بواسطة العميل.", status: 400 }
              outOfStock:
                value: { key: fail, message: "هذه الكمية اكبر من الكمية المتوفره للمنتج", status: 400 }
      '419':
        description: Missing/invalid token or provider token used.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

order-payment:
  post:
    tags: [Client Order]
    summary: Pay for an accepted order
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9432:2781"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10245:82266"
    description: |
      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>

      Pays for an order the provider has already accepted.

      - Client bearer token only.
      - Payable only while the order is `new`, accepted, unpaid, and inside the
        payment window.
      - `wallet` requires sufficient balance; `online` uses the online strategy.
      - On success the order moves to `current` / `processing`.
      - Creates a platform `Profit` record only (no provider FinancialTransaction yet).
    operationId: payOrder
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [orderId, paymentMethod]
            properties:
              orderId:
                type: string
                pattern: '^[a-fA-F0-9]{24}$'
                example: "665f1c2a9b4e1d0012ab34d0"
              paymentMethod:
                type: string
                enum: [wallet, online]
                example: wallet
    responses:
      '200':
        description: Payment completed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/OrderActionResponse' }
            example: { key: success, message: "تم دفع الطلب بنجاح", status: 200 }
      '400':
        description: Not payable, already paid, window expired, insufficient balance, or invalid method.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            examples:
              notAccepted:
                value: { key: fail, message: "لا توجد منتجات مقبولة للدفع", status: 400 }
              lowBalance:
                value: { key: fail, message: "رصيدك غير كافي", status: 400 }
      '419':
        description: Missing/invalid token or non-client actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

order-cancel:
  patch:
    tags: [Client Order]
    summary: Cancel an order awaiting approval
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9432:2781"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10245:82266"
    description: |
      Cancels an order that is still `new` and has not been accepted or paid.

      - Client bearer token only.
      - Reserved stock is restored on cancellation.
      - `reason` must be a Reason ObjectId taken from `GET /reasons`, not free text.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    operationId: cancelOrder
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [orderId, reason]
            properties:
              orderId:
                type: string
                pattern: '^[a-fA-F0-9]{24}$'
                example: "665f1c2a9b4e1d0012ab34d0"
              reason:
                type: string
                pattern: '^[a-fA-F0-9]{24}$'
                description: Reason ObjectId from the shared reasons catalogue.
                example: "665f1c2a9b4e1d0012ab34aa"
    responses:
      '200':
        description: Order cancelled.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/OrderActionResponse' }
            example: { key: success, message: "تم إلغاء الطلب", status: 200 }
      '400':
        description: Order already acted on, invalid reason, or non-client actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: fail, message: "تم اتخاذ إجراء على الطلب بالفعل", status: 400 }
      '419':
        description: Missing/invalid token or non-client actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

client-confirm-received:
  patch:
    tags: [Client Order]
    summary: Confirm receipt (complete order)
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-3240&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9432:3240"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-85714&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10245:85714"
    description: |
      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-3240&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-85714&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>

      Client confirms that they received the product/order.

      - Client bearer token only.
      - Allowed only when the order is paid (`isPayment=true`), `current`,
        and `currentStep=delivered_to_customer`.
      - Provider delivery alone does **not** complete the order; this is the
        final step that sets `status=finished`, `receivedAt`, and `completedAt`.
      - Creates the provider pending `FinancialTransaction` on successful receipt.
      - Unpaid, cancelled, already-finished, or not-yet-delivered orders are rejected.
    operationId: confirmOrderReceived
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: orderId
        in: query
        required: true
        schema:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
          example: "665f1c2a9b4e1d0012ab34d0"
    responses:
      '200':
        description: Order completed after client receipt confirmation.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/OrderActionResponse' }
            example:
              key: success
              message: تم استلام الطلب بنجاح
              status: 200
      '400':
        description: Not delivered yet, unpaid, already completed, cancelled, or non-client actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: fail, message: "لا يمكن إنهاء الطلب قبل أن تكون حالة المنتجات تم التسليم للعميل.", status: 400 }
      '419':
        description: Missing/invalid token or non-client actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

order-accept:
  patch:
    tags: [Provider Order]
    summary: Accept an order
    x-figma: &provider-order-action-figma
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:25401"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10760:87532"
    description: |
      Provider accepts a `new`, unpaid, not-yet-accepted order. A payment timeout
      is scheduled for the client.

      - Provider bearer token only.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    operationId: acceptOrder
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [orderId]
            properties:
              orderId:
                type: string
                pattern: '^[a-fA-F0-9]{24}$'
                example: "665f1c2a9b4e1d0012ab34d0"
    responses:
      '200':
        description: Order accepted.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/OrderActionResponse' }
            example: { key: success, message: "تم القبول بنجاح", status: 200 }
      '400':
        description: Order already acted on, or non-provider actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: fail, message: "تم اتخاذ إجراء على الطلب بالفعل", status: 400 }
      '419':
        description: Missing/invalid token or non-provider actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

order-reject:
  patch:
    tags: [Provider Order]
    summary: Reject an order
    x-figma: *provider-order-action-figma
    description: |
      Provider rejects a `new`, unpaid order (including an already-accepted but
      unpaid one). Reserved stock is restored and any scheduled payment timeout
      is cleared.

      - Provider bearer token only.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    operationId: rejectOrder
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [orderId, reason]
            properties:
              orderId:
                type: string
                pattern: '^[a-fA-F0-9]{24}$'
                example: "665f1c2a9b4e1d0012ab34d0"
              reason:
                type: string
                pattern: '^[a-fA-F0-9]{24}$'
                description: Reason ObjectId from the shared reasons catalogue.
                example: "665f1c2a9b4e1d0012ab34aa"
    responses:
      '200':
        description: Order rejected.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/OrderActionResponse' }
            example: { key: success, message: "تم رفض المنتج بنجاح", status: 200 }
      '400':
        description: Order already paid/acted on, invalid reason, or non-provider actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: fail, message: "تم اتخاذ إجراء على الطلب بالفعل", status: 400 }
      '419':
        description: Missing/invalid token or non-provider actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }

provider-mark-delivered:
  patch:
    tags: [Provider Order]
    summary: Mark order delivered to customer
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25493&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9967:25493"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87896&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
      webNodeId: "10760:87896"
    description: |
      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25493&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87896&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>

      Provider confirms that the product/order was delivered to the client.

      - Provider bearer token only.
      - Allowed when the order is paid, `current`, and deliverable
        (`processing` or legacy `delivered_to_shipping`).
      - Sets `currentStep=delivered_to_customer` and `deliveredAt`.
      - Does **not** complete/finish the order. Client confirmation is required.
      - Unpaid, cancelled, finished, or already-delivered orders are rejected.
    operationId: markOrderDelivered
    security:
      - SecretKeyAuth: []
        ProviderBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: orderId
        in: query
        required: true
        schema:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
          example: "665f1c2a9b4e1d0012ab34d0"
    responses:
      '200':
        description: Order marked delivered; awaiting client receipt confirmation.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/OrderActionResponse' }
            example:
              key: success
              message: تم التسليم للعميل بنجاح
              status: 200
      '400':
        description: Unpaid, not deliverable, already delivered/completed, cancelled, or non-provider actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: fail, message: "الطلب غير جاهز للتسليم", status: 400 }
      '419':
        description: Missing/invalid token or non-provider actor.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: unauthorized, message: "غير مسموح لك بتنفيذ هذا الإجراء", status: 419 }
      '500':
        description: Server error.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example: { key: exception, message: "حدث خطأ، برجاء التواصل مع الدعم", status: 500 }
