# Provider Features Documentation

Complete reference for provider-side contract management including listing, viewing, accepting, and rejecting contracts with full API specifications, validation rules, and response formats.

---

## Table of Contents

1. [Overview](#overview)
2. [Contract Listing](#contract-listing)
3. [View Contract Details](#view-contract-details)
4. [Accept Contract](#accept-contract)
5. [Reject Contract](#reject-contract)
6. [Contract Workflow](#contract-workflow)
7. [Contract States](#contract-states)
8. [Important Notes](#important-notes)
9. [Error Handling](#error-handling)
10. [Best Practices](#best-practices)

---

## Overview

Providers receive contracts from the admin that define the terms of their engagement with the platform. Providers can view, accept, or reject these contracts. The system ensures only one active contract exists per provider at any time.

### Key Features

- ✅ **Automatic Contract Creation:** First access creates contract from master template
- ✅ **Simple Accept/Reject:** Clear endpoints for responding to contracts
- ✅ **Required Rejection Reason:** Must provide detailed explanation (min 5 characters)
- ✅ **Date Calculation:** Start and end dates calculated upon acceptance
- ✅ **Negotiation Possible:** Can reject and request better terms
- ✅ **One Active Contract:** System ensures single active contract per provider
- ✅ **Full Clause Details:** All contract terms in structured format
- ✅ **Secure Access:** Can only view and act on own contracts

---

## Contract Listing

### Endpoint

`GET /provider/contracts`

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filter` | string | No | Filter contracts by status |
| `per_page` | integer | No | Results per page (default: 15) |

### Filter Options

| Filter Value | Description |
|--------------|-------------|
| `active` | Returns current active contract or creates one if none exists |
| `pending` | Returns only contracts with SENT status (awaiting action) |
| `accepted` | Returns only accepted contracts |
| `rejected` | Returns only rejected contracts |
| `expired` | Returns only expired contracts |
| `all` or omitted | Returns all contracts (paginated) |

### Request Examples

**Get Active Contract:**
```
GET /provider/contracts?filter=active
```

**Get All Pending Contracts:**
```
GET /provider/contracts?filter=pending
```

**Get All Contracts (Paginated):**
```
GET /provider/contracts?per_page=20
```

### Response Format

#### For filter=active (Single Contract)

**Success Response (200):**
```json
{
  "success": true,
  "message": "Contract retrieved successfully",
  "data": {
    "id": 123,
    "contract_number": "CNT-2026-0045",
    "title": "Provider Service Agreement",
    "duration": 12,
    "duration_unit": "month",
    "start_date": "2026-10-28",
    "end_date": "2027-10-28",
    "status": "sent",
    "accepted_at": null,
    "rejected_at": null,
    "rejection_reason": null,
    "created_at": 1730102400,
    "clauses_data": [
      {
        "order": 1,
        "title": "Service Obligations",
        "content": "The provider agrees to deliver high-quality services according to platform standards and client requirements."
      },
      {
        "order": 2,
        "title": "Payment Terms",
        "content": "Payments shall be processed within 48 hours of order completion. Provider receives payment minus platform fees."
      },
      {
        "order": 3,
        "title": "Quality Standards",
        "content": "Provider must maintain minimum 4.0 rating and respond to orders within 2 hours."
      },
      {
        "order": 4,
        "title": "Termination",
        "content": "Either party may terminate this agreement with 30 days notice."
      }
    ]
  }
}
```

**No Contract Found (200):**
```json
{
  "success": true,
  "message": "No active or pending contract found",
  "data": null
}
```

#### For Other Filters (Paginated List)

**Success Response (200):**
```json
{
  "success": true,
  "message": "Contracts retrieved successfully",
  "data": [
    {
      "id": 123,
      "contract_number": "CNT-2026-0045",
      "title": "Provider Service Agreement",
      "duration": 12,
      "duration_unit": "month",
      "start_date": "2026-10-28",
      "end_date": "2027-10-28",
      "status": "accepted",
      "accepted_at": 1730102400,
      "rejected_at": null,
      "rejection_reason": null,
      "created_at": 1730102400,
      "clauses_data": [
        {
          "order": 1,
          "title": "Service Obligations",
          "content": "Provider agrees to..."
        }
      ]
    },
    {
      "id": 122,
      "contract_number": "CNT-2026-0044",
      "title": "Provider Service Agreement",
      "duration": 12,
      "duration_unit": "month",
      "start_date": null,
      "end_date": null,
      "status": "rejected",
      "accepted_at": null,
      "rejected_at": 1730009600,
      "rejection_reason": "I need better payment terms",
      "created_at": 1730002400,
      "clauses_data": [...]
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "per_page": 15,
    "to": 15,
    "total": 25
  }
}
```

### Active Contract Auto-Dispatch

When using `filter=active`, the system follows this logic:

1. **Check for Active Contract:** Looks for existing ACCEPTED contract
2. **Check for Pending Contract:** If none active, looks for SENT or REJECTED contract
3. **Auto-Create:** If no contracts exist:
   - Creates new contract from master template
   - Status set to SENT
   - Contract number auto-generated
   - Provider notified
   - Ready for immediate review

**This ensures providers always have a contract available when needed.**

### Contract Fields Explained

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique contract identifier |
| `contract_number` | string | Human-readable contract number (CNT-YYYY-####) |
| `title` | string | Contract title |
| `duration` | integer | Contract length (number) |
| `duration_unit` | string | Time unit (day, month, year) |
| `start_date` | string/null | Contract start date (YYYY-MM-DD), set on acceptance |
| `end_date` | string/null | Contract end date (YYYY-MM-DD), calculated on acceptance |
| `status` | string | Current status (sent, accepted, rejected, expired) |
| `accepted_at` | integer/null | Unix timestamp of acceptance |
| `rejected_at` | integer/null | Unix timestamp of rejection |
| `rejection_reason` | string/null | Provider's rejection reason |
| `created_at` | integer | Unix timestamp of creation |
| `clauses_data` | array | Array of contract clauses |

### Clause Structure

Each clause in `clauses_data` contains:

| Field | Type | Description |
|-------|------|-------------|
| `order` | integer | Sequence number for display order |
| `title` | string | Clause heading/title |
| `content` | string | Full clause text/terms |

---

## View Contract Details

### Endpoint

`GET /provider/contracts/{id}`

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Contract ID |

### Request Example

```
GET /provider/contracts/123
```

### Response

**Success Response (200):**
```json
{
  "success": true,
  "message": "Contract retrieved successfully",
  "data": {
    "id": 123,
    "contract_number": "CNT-2026-0045",
    "title": "Provider Service Agreement",
    "duration": 12,
    "duration_unit": "month",
    "start_date": "2026-10-28",
    "end_date": "2027-10-28",
    "status": "sent",
    "accepted_at": null,
    "rejected_at": null,
    "rejection_reason": null,
    "created_at": 1730102400,
    "clauses_data": [
      {
        "order": 1,
        "title": "Service Obligations",
        "content": "The provider agrees to deliver high-quality services according to platform standards and client requirements. This includes timely response to orders, professional conduct, and adherence to safety standards."
      },
      {
        "order": 2,
        "title": "Payment Terms",
        "content": "Payments shall be processed within 48 hours of successful order completion and client approval. Provider receives payment amount minus applicable platform fees and taxes."
      },
      {
        "order": 3,
        "title": "Quality Standards",
        "content": "Provider must maintain a minimum average rating of 4.0 stars and respond to new orders within 2 hours during active hours."
      },
      {
        "order": 4,
        "title": "Liability and Insurance",
        "content": "Provider is responsible for maintaining appropriate insurance coverage and assumes liability for work performed."
      },
      {
        "order": 5,
        "title": "Termination",
        "content": "Either party may terminate this agreement with 30 days written notice. Platform reserves right to immediate termination for policy violations."
      }
    ]
  }
}
```

**Error Responses:**

*Not Found or Unauthorized (404):*
```json
{
  "success": false,
  "message": "Resource not found"
}
```

### Security

- Providers can **only view their own contracts**
- Attempting to view another provider's contract returns 404
- Authentication required via Bearer token

---

## Accept Contract

### Endpoint

`POST /provider/contracts/{id}/accept`

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Contract ID to accept |

### Request Example

```
POST /provider/contracts/123/accept
```

**No request body required.**

### Validation Rules

The system validates:

1. ✅ Contract must have status SENT
2. ✅ Contract cannot already be accepted
3. ✅ Contract must belong to authenticated provider
4. ✅ Provider cannot have another active contract

### What Happens on Acceptance

When you accept a contract, the system:

1. **Updates Status:** Changes status to ACCEPTED
2. **Sets Timestamp:** Records `accepted_at` as current time
3. **Calculates Dates:**
   - `start_date`: Set to current date
   - `end_date`: Calculated based on duration and unit:
     - **day:** start_date + duration days
     - **month:** start_date + duration months
     - **year:** start_date + duration years
4. **Clears Rejection Data:** Removes any previous rejection information
5. **Activates Provider:** Provider can now perform services on platform
6. **Notifies Admin:** Admin receives notification of acceptance

### Response

**Success Response (200):**
```json
{
  "success": true,
  "message": "Contract accepted successfully",
  "data": {
    "id": 123,
    "contract_number": "CNT-2026-0045",
    "title": "Provider Service Agreement",
    "duration": 12,
    "duration_unit": "month",
    "start_date": "2026-10-28",
    "end_date": "2027-10-28",
    "status": "accepted",
    "accepted_at": 1730102400,
    "rejected_at": null,
    "rejection_reason": null,
    "created_at": 1730002400,
    "clauses_data": [...]
  }
}
```

**Error Responses:**

*Contract Already Accepted (400):*
```json
{
  "success": false,
  "message": "This contract has already been accepted."
}
```

*Contract Not Awaiting Action (400):*
```json
{
  "success": false,
  "message": "This contract is not in a state awaiting your action."
}
```

*Not Found or Unauthorized (404):*
```json
{
  "success": false,
  "message": "Resource not found"
}
```

### Duration Calculation Examples

**Example 1: 12 Months**
- Start Date: October 28, 2026
- Duration: 12 months
- End Date: October 28, 2027

**Example 2: 1 Year**
- Start Date: October 28, 2026
- Duration: 1 year
- End Date: October 28, 2027

**Example 3: 90 Days**
- Start Date: October 28, 2026
- Duration: 90 days
- End Date: January 26, 2027

**Example 4: 18 Months**
- Start Date: October 28, 2026
- Duration: 18 months
- End Date: April 28, 2028

### Important Notes

- ⚠️ **Acceptance is final** - Cannot undo once accepted
- ⚠️ **Terms become binding** - All clauses are legally binding
- ⚠️ **Provider activation** - Can immediately start receiving orders
- ⚠️ **Contract duration** - Active until end_date, then requires renewal

---

## Reject Contract

### Endpoint

`POST /provider/contracts/{id}/reject`

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Contract ID to reject |

### Request Body

```json
{
  "rejection_reason": "I need better payment terms. The current platform fee percentage is too high for the services I provide."
}
```

### Validation Rules

| Field | Rules | Description |
|-------|-------|-------------|
| `rejection_reason` | required, string, min: 5, max: 2000 | Detailed explanation required |

**Additional Validation:**
- Contract must have status SENT
- Cannot reject already accepted contract
- Contract must belong to authenticated provider

### Request Example

```
POST /provider/contracts/123/reject
Content-Type: application/json

{
  "rejection_reason": "I need more flexible payment terms and better support for complex projects."
}
```

### What Happens on Rejection

When you reject a contract:

1. **Updates Status:** Changes status to REJECTED
2. **Sets Timestamp:** Records `rejected_at` as current time
3. **Stores Reason:** Saves detailed rejection reason
4. **Notifies Admin:** Admin receives notification with reason
5. **Blocks Services:** Cannot perform services until contract accepted
6. **Enables Negotiation:** Admin can update terms and resend

### Response

**Success Response (200):**
```json
{
  "success": true,
  "message": "Contract rejected successfully",
  "data": {
    "id": 123,
    "contract_number": "CNT-2026-0045",
    "title": "Provider Service Agreement",
    "duration": 12,
    "duration_unit": "month",
    "start_date": null,
    "end_date": null,
    "status": "rejected",
    "accepted_at": null,
    "rejected_at": 1730102400,
    "rejection_reason": "I need more flexible payment terms and better support for complex projects.",
    "created_at": 1730002400,
    "clauses_data": [...]
  }
}
```

**Error Responses:**

*Missing Rejection Reason (422):*
```json
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "rejection_reason": [
      "Please provide a reason for rejecting the contract."
    ]
  }
}
```

*Rejection Reason Too Short (422):*
```json
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "rejection_reason": [
      "The rejection reason must be at least 5 characters."
    ]
  }
}
```

*Cannot Reject Accepted Contract (400):*
```json
{
  "success": false,
  "message": "Cannot reject an already accepted contract."
}
```

*Contract Not Awaiting Action (400):*
```json
{
  "success": false,
  "message": "This contract is not in a state awaiting your action."
}
```

*Not Found or Unauthorized (404):*
```json
{
  "success": false,
  "message": "Resource not found"
}
```

### After Rejection

Following rejection:

1. **Provider Status:** Cannot perform services on platform
2. **Admin Review:** Admin reviews rejection reason
3. **Term Negotiation:** Admin may modify contract terms
4. **Contract Resend:** Admin resends contract with updated terms
5. **Status Reset:** When resent, status returns to SENT
6. **Provider Action:** Provider reviews updated terms
7. **Repeat Cycle:** Can accept or reject again

### Writing Effective Rejection Reasons

**Good Examples:**

✅ "The platform fee of 15% is too high for plumbing services in this market. I would need 10% to be competitive."

✅ "The 2-hour response requirement is unrealistic for my service area. I need at least 4 hours to accommodate travel time."

✅ "The payment terms specify 48-hour processing, but I need same-day payment for emergency services."

✅ "The liability clause places too much risk on providers. I need the platform to share liability for technical issues."

**Poor Examples:**

❌ "No" - Too short, not helpful

❌ "Bad terms" - Not specific

❌ "I don't like it" - Doesn't explain what to change

❌ "Maybe later" - Not a rejection reason

### Rejection Reason Requirements

- **Minimum Length:** 5 characters
- **Maximum Length:** 2000 characters
- **Content:** Should be specific and constructive
- **Purpose:** Help admin understand concerns
- **Tone:** Professional and clear

---

## Contract Workflow

### Complete Provider Journey

```
┌─────────────────────────────────────────────────────────────┐
│ 1. New Provider Registration                                 │
│    → Submits application with credentials and documentation  │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Admin Reviews & Approves Provider                         │
│    → Verifies credentials, documents, and qualifications     │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Provider Accesses Contracts (filter=active)               │
│    → First time accessing contract section                   │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. System Auto-Creates Contract                              │
│    → Uses master template                                    │
│    → Status: SENT                                            │
│    → Provider notified                                       │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. Provider Reviews Contract Clauses                         │
│    → Reads all terms and conditions                          │
│    → Understands obligations and rights                      │
│    → Checks payment terms and duration                       │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
        ┌────────┴────────┐
        │                 │
        ▼                 ▼
┌──────────────┐  ┌──────────────────────────────────────────┐
│ 6a. ACCEPT   │  │ 6b. REJECT (with reason)                 │
│              │  │                                          │
│ Dates Set    │  │ Rejection Reason: Required              │
│ ↓            │  │ ↓                                        │
│ Active       │  │ Admin Notified                          │
│ ↓            │  │ ↓                                        │
│ Can Perform  │  │ Cannot Perform Services                 │
│ Services     │  │ ↓                                        │
│              │  │ ┌────────────────────────────────────┐  │
│              │  │ │ 7. Admin Updates Terms             │  │
│              │  │ │    → Modifies clauses              │  │
│              │  │ │    → Adjusts payment terms         │  │
│              │  │ │    → Changes duration if needed    │  │
│              │  │ └────────┬───────────────────────────┘  │
│              │  │          │                               │
│              │  │          ▼                               │
│              │  │ ┌────────────────────────────────────┐  │
│              │  │ │ 8. Contract Resent                 │  │
│              │  │ │    → Status: SENT                  │  │
│              │  │ │    → Provider notified             │  │
│              │  │ └────────┬───────────────────────────┘  │
│              │  │          │                               │
│              │  │          ▼                               │
│              │  │ ┌────────────────────────────────────┐  │
│              │  │ │ 9. Provider Reviews Again          │  │
│              │  │ │    → Can Accept or Reject          │  │
│              │  │ │    → Cycle repeats if needed       │  │
│              │  │ └────────────────────────────────────┘  │
└──────────────┘  └──────────────────────────────────────────┘
```

### Status Transition Diagram

```
     ┌────────┐
     │ SENT   │ ◄──────────────────┐
     └───┬────┘                     │
         │                          │
    ┌────┴────┐                     │
    │         │                     │
    ▼         ▼                     │
┌─────────┐ ┌──────────┐           │
│ACCEPTED │ │ REJECTED │ ──────────┘
└────┬────┘ └──────────┘  (Admin Resends)
     │
     ▼
┌─────────┐
│ EXPIRED │ (After end_date)
└─────────┘
```

---

## Contract States

### SENT

**Description:** Contract has been sent to provider and is awaiting action.

**Provider Can:**
- ✅ View contract details
- ✅ Accept contract
- ✅ Reject contract with reason

**Provider Cannot:**
- ❌ Perform services on platform
- ❌ Receive client orders
- ❌ Modify contract terms

**Next Steps:**
- Accept → Status becomes ACCEPTED
- Reject → Status becomes REJECTED

---

### ACCEPTED

**Description:** Provider has accepted the contract and it is now active.

**Features:**
- ✅ Start and end dates are set
- ✅ Provider can perform services
- ✅ Provider receives client orders
- ✅ Contract terms are binding

**Provider Cannot:**
- ❌ Modify contract
- ❌ Reject contract
- ❌ Undo acceptance

**Duration:**
- Active from `start_date` to `end_date`
- Contract expires automatically at end date
- Renewal required after expiration

---

### REJECTED

**Description:** Provider has declined the contract with a detailed reason.

**Features:**
- ✅ Rejection reason stored and visible to admin
- ✅ Admin can review concerns
- ✅ Admin can modify terms
- ✅ Admin can resend updated contract

**Provider Cannot:**
- ❌ Perform services on platform
- ❌ Receive client orders
- ❌ Access provider features

**Next Steps:**
- Wait for admin to review rejection reason
- Admin may resend with updated terms
- Provider can then accept or reject again

---

### EXPIRED

**Description:** Contract has passed its end date and is no longer active.

**Features:**
- ✅ Contract period completed
- ✅ Historical record maintained
- ✅ New contract required for continued service

**Provider Cannot:**
- ❌ Perform services (unless new contract accepted)
- ❌ Receive new orders
- ❌ Reactivate expired contract

**Next Steps:**
- Admin sends new contract
- Provider reviews and accepts new terms
- Service continues with new contract

---

## Important Notes

### Only One Active Contract

**Rule:** A provider can only have **ONE ACCEPTED** contract at a time.

**Why:**
- Ensures clear, consistent terms
- Prevents conflicting obligations
- Simplifies compliance tracking
- Reduces confusion

**Implications:**
- Cannot accept new contract while one is active
- Must wait for expiration or termination
- Admin cannot create duplicate active contracts

---

### Only One Pending Contract

**Rule:** A provider can only have **ONE SENT or REJECTED** contract at a time.

**Why:**
- Prevents confusion about current terms
- Ensures latest terms are clear
- Simplifies negotiation process

**Implications:**
- Admin must update existing contract vs. creating new
- Provider always reviews most recent terms
- No multiple parallel negotiations

---

### Contract Duration

**Display Format:**
- Duration shown as simple number with unit
- Example: "12 months", "1 year", "90 days"

**Date Calculation:**
- Start date set on acceptance (current date)
- End date calculated automatically based on:
  - Duration (integer)
  - Duration unit (day/month/year)
- Both dates stored and displayed

**Provider View:**
- Sees duration before acceptance
- Sees exact date range after acceptance
- Can calculate expiration in advance

---

### Rejection Reasons Matter

**Purpose:**
- Help admin understand concerns
- Enable meaningful negotiation
- Improve contract terms for all
- Build better provider relationships

**Best Practices:**
- Be specific about issues
- Suggest alternatives if possible
- Remain professional
- Focus on business needs

**Examples of Good Feedback:**
- Payment timing concerns
- Fee percentage issues
- Response time requirements
- Liability concerns
- Duration preferences

---

### Reading the Contract

**Clause Structure:**
Each contract has multiple clauses in `clauses_data` array:

```json
{
  "order": 1,
  "title": "Section Heading",
  "content": "Full detailed terms and conditions for this section..."
}
```

**What to Review:**
1. **Service Obligations** - What you must deliver
2. **Payment Terms** - How and when you get paid
3. **Quality Standards** - Performance requirements
4. **Liability** - Who is responsible for what
5. **Termination** - How to end agreement
6. **Duration** - How long contract lasts

**Reading Tips:**
- Read every clause carefully
- Note any unclear terms
- Calculate financial impact
- Consider operational requirements
- Assess time commitments

---

### After Acceptance

**Immediate Effects:**
- ✅ Provider profile becomes active
- ✅ Can receive client orders
- ✅ Appears in client searches (if approved)
- ✅ Contract terms are binding
- ✅ All clauses take effect

**Cannot:**
- ❌ Change mind about acceptance
- ❌ Modify contract terms
- ❌ Negotiate after acceptance

**Long Term:**
- Contract active until `end_date`
- Must comply with all terms
- Subject to performance monitoring
- Renewal required before expiration

---

### Contract Modifications

**If You Need Different Terms:**

1. **Before Acceptance:**
   - Reject current contract
   - Provide detailed reason
   - Wait for admin review
   - Review updated contract
   - Accept if satisfactory

2. **After Acceptance:**
   - Cannot modify current contract
   - Must wait for expiration
   - Discuss concerns with admin
   - New terms apply to next contract

**Modification Process:**
```
Current Contract (SENT)
    ↓
Provider Rejects with Reason
    ↓
Admin Reviews Feedback
    ↓
Admin Updates Terms
    ↓
Contract Resent (SENT status)
    ↓
Provider Reviews Updated Terms
    ↓
Accept or Reject Again
```

---

## Error Handling

### Common Error Scenarios

#### 1. Contract Already Accepted

**Scenario:** Trying to accept an already accepted contract

**Error Response (400):**
```json
{
  "success": false,
  "message": "This contract has already been accepted."
}
```

**Solution:** Contract is already active. Check contract status.

---

#### 2. Contract Not Awaiting Action

**Scenario:** Trying to accept/reject contract in wrong state

**Error Response (400):**
```json
{
  "success": false,
  "message": "This contract is not in a state awaiting your action."
}
```

**Solution:** Check contract status. Only SENT contracts can be acted upon.

---

#### 3. Cannot Reject Accepted Contract

**Scenario:** Trying to reject an already accepted contract

**Error Response (400):**
```json
{
  "success": false,
  "message": "Cannot reject an already accepted contract."
}
```

**Solution:** Accepted contracts cannot be rejected. Contact admin if you have concerns.

---

#### 4. Missing Rejection Reason

**Scenario:** Rejecting without providing a reason

**Error Response (422):**
```json
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "rejection_reason": [
      "Please provide a reason for rejecting the contract."
    ]
  }
}
```

**Solution:** Include `rejection_reason` in request body with at least 5 characters.

---

#### 5. Rejection Reason Too Short

**Scenario:** Rejection reason less than 5 characters

**Error Response (422):**
```json
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "rejection_reason": [
      "The rejection reason must be at least 5 characters."
    ]
  }
}
```

**Solution:** Provide more detailed explanation (minimum 5 characters).

---

#### 6. Contract Not Found

**Scenario:** Accessing non-existent contract or another provider's contract

**Error Response (404):**
```json
{
  "success": false,
  "message": "Resource not found"
}
```

**Solution:** Verify contract ID. Ensure you're accessing your own contract.

---

#### 7. Unauthorized Access

**Scenario:** Missing or invalid authentication token

**Error Response (401):**
```json
{
  "success": false,
  "message": "Unauthenticated"
}
```

**Solution:** Include valid Bearer token in Authorization header.

---

## Best Practices

### 1. Review Carefully

**Before Accepting:**
- ✅ Read every clause thoroughly
- ✅ Understand all obligations
- ✅ Calculate financial impact
- ✅ Note duration and end date
- ✅ Review termination terms

**Questions to Ask:**
- Can I meet the response time requirements?
- Are the payment terms acceptable?
- Is the contract duration appropriate?
- Do I understand the liability terms?
- What are the performance standards?

---

### 2. Provide Detailed Feedback

**When Rejecting:**
- ✅ Be specific about concerns
- ✅ Suggest alternative terms
- ✅ Explain business impact
- ✅ Remain professional
- ✅ Focus on solutions

**Good Example:**
```json
{
  "rejection_reason": "The platform fee of 15% is too high for plumbing services in my service area. Market rates support a maximum fee of 10%. Additionally, the 2-hour response requirement is challenging given traffic conditions. I would need 4 hours to maintain quality service."
}
```

**Poor Example:**
```json
{
  "rejection_reason": "Don't like it"
}
```

---

### 3. Respond Promptly

**Why It Matters:**
- Delayed response prevents earning
- Admin may have time limits
- Affects provider onboarding
- Impacts client service availability

**Best Practice:**
- Review contracts within 24 hours
- Accept or reject promptly
- Ask questions if unclear
- Don't delay without reason

---

### 4. Keep Records

**What to Save:**
- ✅ Contract numbers
- ✅ Acceptance dates
- ✅ End dates
- ✅ Key terms and clauses
- ✅ Rejection reasons (if any)

**Why:**
- Reference during disputes
- Track contract history
- Plan for renewal
- Monitor obligations

---

### 5. Contact Support

**When to Reach Out:**
- ❓ Contract terms are unclear
- ❓ Found errors in contract
- ❓ Need clarification on clauses
- ❓ Have questions about obligations
- ❓ Technical issues accepting/rejecting

**How to Contact:**
- Use platform support system
- Reference contract number
- Be specific about questions
- Provide relevant details

---

### 6. Plan for Renewal

**Before Contract Expires:**
- Review current contract performance
- Note any desired changes
- Prepare feedback for admin
- Ensure smooth transition

**At Expiration:**
- Watch for new contract
- Review updated terms
- Accept promptly to avoid service interruption
- Negotiate if needed before accepting

---

### 7. Understand Financial Terms

**Calculate:**
- Net earnings after platform fees
- Impact of different service prices
- Break-even points
- Competitive pricing

**Example Calculation:**
```
Service Price: 500 SAR
Platform Fee: 15% = 75 SAR
VAT: 15% = 75 SAR (paid by client)
Net Earnings: 425 SAR
```

---

### 8. Maintain Compliance

**After Acceptance:**
- Meet response time requirements
- Maintain quality standards
- Follow payment procedures
- Adhere to all contract terms
- Track performance metrics

**Monitoring:**
- Check ratings regularly
- Monitor response times
- Review client feedback
- Address issues promptly

---

## Summary

### Key Takeaways

| Feature | Description |
|---------|-------------|
| **Auto-Creation** | Contract created automatically on first access |
| **Accept** | Immediate activation, dates calculated, binding terms |
| **Reject** | Detailed reason required (min 5 chars), enables negotiation |
| **Duration** | Shown as number + unit, dates calculated on acceptance |
| **One Active** | Only one ACCEPTED contract at a time per provider |
| **One Pending** | Only one SENT/REJECTED contract at a time |
| **Secure** | Can only view and act on own contracts |
| **Detailed** | All clauses provided in structured format |

### API Endpoints Quick Reference

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/provider/contracts?filter=active` | Get active contract |
| GET | `/provider/contracts?filter=pending` | List pending contracts |
| GET | `/provider/contracts/{id}` | View contract details |
| POST | `/provider/contracts/{id}/accept` | Accept contract |
| POST | `/provider/contracts/{id}/reject` | Reject contract |

### Status Flow

```
SENT → ACCEPTED → EXPIRED
  ↓
REJECTED → (Admin Updates) → SENT
```

### Remember

- ⚠️ **Acceptance is binding** - Read carefully before accepting
- ⚠️ **Rejection needs detail** - Help admin understand your concerns
- ⚠️ **One active contract** - System enforces this automatically
- ⚠️ **Dates calculated** - Start/end dates set upon acceptance
- ⚠️ **Negotiation possible** - Can reject and request better terms

---

**Last Updated:** October 28, 2026