# Provider — Interactive Contract Order: Show Order Response & Acceptance Policy

> Last updated: 2026-09-30
> Relates to: `GET /v1/provider/service-orders/{id}`

---

## Overview

When the order's `service_data.service_type` is `interactive_contract`, the show-order response
includes a `stages_data` array in addition to the standard fields. This lets the provider monitor
the full confirmation progress of every stage across all parties.

---

## 1. Interactive Contract — Acceptance Policy

> **Required step before accepting an interactive-contract order**

Before a provider accepts an order of type `interactive_contract`, the frontend **must** display
the interactive contract terms page to the provider and obtain explicit consent.

### Static Page to Show

Fetch the static page content using:

```http
GET /v1/general/pages?type=interactive_contract_terms
```

This returns the `interactive_contract_terms` static page (seeded via `InteractiveContractTermsSeeder`).
It covers:
- Concept of the interactive contract and stage model
- Party and client confirmation responsibilities
- Provider obligations per stage
- Dispute resolution process

**The provider must view and accept these terms before the accept button becomes active.**

---

## 2. Show Order — Full Response Shape

```http
GET /v1/provider/service-orders/{id}
Authorization: Bearer {token}
```

```jsonc
{
  // ── Core ──────────────────────────────────────────────────────────
  "id": 42,
  "order_number": "ORD-2026-00042",
  "status": "active",
  "status_trans": "قيد التنفيذ",
  "order_type": "individual",          // "individual" | "team"
  "is_team_leader": true,              // false = hide all action buttons

  // ── Schedule ──────────────────────────────────────────────────────
  "scheduled_date": "2026-10-05",
  "scheduled_time": "10:00",

  // ── Negotiation ───────────────────────────────────────────────────
  "is_negotiated": false,
  "negotiation": null,                 // populated when is_negotiated = true

  // ── Completion ────────────────────────────────────────────────────
  "completion_note": null,

  // ── Revision ──────────────────────────────────────────────────────
  "revision": {
    "count": 0,
    "note": null,
    "requested_at": null
  },

  // ── Dynamic Form Data (client's submitted request) ─────────────────
  "form_data": [
    { "field_key": "case_number", "label": "رقم القضية", "answer": "2024/123" },
    {
      "field_key": "supporting_docs",
      "label": "المستندات",
      "answer": [
        { "id": 88, "url": "https://...", "type": "pdf", "option": "form_upload", "is_single": false }
      ]
    }
  ],

  // ── Pricing ───────────────────────────────────────────────────────
  "service_price": 1500.00,
  "total_price": 1725.00,
  "vat_amount": 225.00,

  // ── Work Files (المخرجات) ─────────────────────────────────────────
  "work_files": [],
  "has_work_files": false,

  // ── Timestamps ────────────────────────────────────────────────────
  "paid_at": 1727600000,
  "accepted_at": 1727601000,
  "completed_at": null,
  "rejected_at": null,
  "cancelled_at": null,
  "created_at": 1727500000,

  // ── Client Info ───────────────────────────────────────────────────
  "client_data": {
    "id": 7,
    "full_name": "Mohammed Al-Rashidi",
    "avatar": "https://..."
  },

  // ── Team Info ─────────────────────────────────────────────────────
  "team_data": null,

  // ── Service Info ──────────────────────────────────────────────────
  "service_data": {
    "id": 5,
    "title": "Interactive Contract",
    "service_type": "interactive_contract",   // <-- identifies this order type
    "is_integrated_case": false,
    "provider_percentage": null
  },

  // ── Chat ──────────────────────────────────────────────────────────
  "chat_id": 99,

  // ── Review ────────────────────────────────────────────────────────
  "review_data": null,

  // ── Contract Attachment ───────────────────────────────────────────
  "contract_attachment": null,

  // ── Contract Terms (free-text blob, if set) ───────────────────────
  "contract_terms": null,

  // ── Integrated Contract Parties (integrated_contract type only) ───
  "parties_data": [],

  // ── Interactive Contract Stages ───────────────────────────────────
  // Only populated when service_type = "interactive_contract"
  // Provider is READ-ONLY — cannot confirm stages, only observe.
  "stages_data": [
    {
      "id": 1,
      "order": 1,                         // sequence number (1 = first)
      "name": "Initial Review",
      "end_date": "2026-10-10",
      "amount": 500.00,

      // Stage state
      "is_active": false,                 // false = already done or not yet reached
      "is_client_confirmed": true,        // client finalised this stage
      "client_confirmed_at": 1727800000,

      // Per-party confirmation breakdown
      // Provider sees WHO confirmed and WHO hasn't yet
      "parties_data": [
        {
          "id": 101,
          "full_name": "Ahmed Ali",
          "avatar": "https://...",
          "has_confirmed": true,
          "confirmed_at": 1727780000
        },
        {
          "id": 102,
          "full_name": "Sara Hassan",
          "avatar": "https://...",
          "has_confirmed": true,
          "confirmed_at": 1727790000
        }
      ],
      "created_at": 1727500000
    },
    {
      "id": 2,
      "order": 2,
      "name": "Draft Contract Review",
      "end_date": "2026-10-20",
      "amount": 1000.00,

      "is_active": true,                  // <-- this is the current active stage
      "is_client_confirmed": false,
      "client_confirmed_at": null,

      "parties_data": [
        {
          "id": 101,
          "full_name": "Ahmed Ali",
          "avatar": "https://...",
          "has_confirmed": true,          // Ahmed confirmed ✅
          "confirmed_at": 1727820000
        },
        {
          "id": 102,
          "full_name": "Sara Hassan",
          "avatar": "https://...",
          "has_confirmed": false,         // Sara hasn't confirmed yet ❌
          "confirmed_at": null
        }
      ],
      "created_at": 1727500000
    },
    {
      "id": 3,
      "order": 3,
      "name": "Final Signing",
      "end_date": "2026-11-01",
      "amount": 500.00,

      "is_active": false,                 // locked — stage 2 not done yet
      "is_client_confirmed": false,
      "client_confirmed_at": null,

      "parties_data": [
        { "id": 101, "full_name": "Ahmed Ali",   "avatar": "https://...", "has_confirmed": false, "confirmed_at": null },
        { "id": 102, "full_name": "Sara Hassan", "avatar": "https://...", "has_confirmed": false, "confirmed_at": null }
      ],
      "created_at": 1727500000
    }
  ]
}
```

---

## 3. Reading `stages_data` — Rules for the Frontend

| Field | Meaning | UI hint |
|---|---|---|
| `is_active: true` | This is the current stage in progress | Highlight / expand |
| `is_active: false` + `is_client_confirmed: false` | Future stage — not yet reached | Grey / locked |
| `is_client_confirmed: true` | Stage fully done | Show checkmark |
| `parties_data[n].has_confirmed: false` | This party hasn't confirmed yet | Show pending badge |
| `parties_data[n].has_confirmed: true` | This party confirmed | Show confirmed badge + timestamp |

> Provider has **no confirm action** — only clients and parties confirm stages.
> The provider's job is to do the work; stage confirmations are the parties' responsibility.

---

## 4. Order Lifecycle for Interactive Contracts

The standard order lifecycle applies. Interactive contract stages run **in parallel** to the
order status — they do not change the order status themselves.

```
pending
  ├─ show interactive_contract_terms page → provider accepts → POST /accept
  └─ reject → rejected

accepted → POST /start → active

active
  ├─ Parties confirm stages via client app (provider observes via stages_data)
  ├─ upload-files (المخرجات)
  └─ finish → provider_finished

provider_finished
  ├─ client confirms → completed ✅
  ├─ Golden Guarantee → pending_admin_review
  └─ auto-complete after 24h → completed ✅
```

---

## 5. Related Settings

| Setting Key | Default | Description |
|---|---|---|
| `service_order_pending_timeout_minutes` | — | Auto-cancel if order stays pending too long |
| `service_order_auto_complete_minutes` | — | Auto-complete window after provider finishes |
| `golden_guarantee_window_minutes` | — | Window for client to file Golden Guarantee |

---

## 6. Related Docs

- [`PROVIDER_SERVICE_ORDER_FLOW.md`](./PROVIDER_SERVICE_ORDER_FLOW.md) — Full order flow
- [`SETTINGS_SYSTEM.md`](./SETTINGS_SYSTEM.md) — Settings system reference
- [`INTERACTIVE_CONTRACT_UPDATES.md`](./INTERACTIVE_CONTRACT_UPDATES.md) — Change log for this feature

---

## 7. Chat API — Updates

> Last updated: 2026-10-01

### 7.1 Chat List Response (`GET /v1/provider/chats`)

The chat list now returns two additional objects on every item:

**`order_data`** — the order linked to this chat:
```jsonc
"order_data": {
  "id": 42,
  "order_number": "NK-S0042#",
  "status": "active",
  "type": "service"     // "service" | "urgent"
}
```
`null` when no order is linked.

**`latest_message`** — unified shape (same across provider, client, and admin):
```jsonc
"latest_message": {
  "id": 10,
  "message": "Hello",
  "is_mine": true,
  "read_at": 1727601000,
  "created_at": 1727600000,
  "attachment_data": {
    "url": "https://...",
    "type": "image"     // "image" | "audio" | "video" | "file"
  }
}
```
`attachment_data` is `null` when there is no attachment. The old `attachment_type` flag is removed — use `attachment_data.type` instead.

### 7.2 Chat Message Response (`GET /v1/provider/chats/{id}` and `POST /v1/provider/chats/{id}/messages`)

Individual message objects (`ShowChatResource`) follow the same shape:
```jsonc
{
  "id": 10,
  "message": "Hello",
  "sender_data": { "id": 16, "full_name": "...", "avatar": "..." },
  "is_mine": true,
  "read_at": null,
  "created_at": 1727600000,
  "attachment_data": { "url": "https://...", "type": "audio" }
}
```

### 7.3 Search by Order Number

Provider service orders and urgent orders now support search by order number:
```
GET /v1/provider/service-orders?search=NK-S0042
GET /v1/provider/urgent-orders?search=NK-U0010
```

---

## 8. Contact Us Endpoint

> New endpoint available for providers (same as client).

```http
POST /v1/provider/contact-us
Authorization: Bearer {token}
```

**Body:**
```jsonc
{
  "full_name": "...",
  "email": "...",
  "phone": "...",
  "title": "...",
  "content": "..."
}
```

The submission is linked to the authenticated provider's account (`user_id`), so admin can filter contacts by `user_type=provider`.

---

## 9. Static Pages

> All static pages are available to the provider app via the general endpoint:

```http
GET /v1/general/pages
GET /v1/general/pages?type={page_type}
```

**Available page types relevant to providers:**

| `type` value | Content |
|---|---|
| `interactive_contract_terms` | Must be shown before accepting an `interactive_contract` order |
| `about` | About the platform |
| `privacy_policy` | Privacy policy |
| `terms_and_conditions` | General terms |
| `faq` | Frequently asked questions |

> The `interactive_contract_terms` page is fetched at: `GET /v1/general/pages?type=interactive_contract_terms`
> and must be displayed and accepted by the provider **before** the accept button becomes active on an `interactive_contract` order.