# Company

Routes that **require Company authentication** (`user_type: company`) and are specific to Company functionality: session management, company profile, contracts, job-order cart/lifecycle, invoices/reports, and a home-screen/visits dashboard. Branches and the catalog (categories/services) a company books against live in `06-shared-general.md` since Admin manages the identical resources for oversight. **No employee/user-management, no direct technician management, and no wallet endpoints exist for the Company role** — flagged explicitly at the relevant section headers below, since the bullet exists conceptually but no route backs it. **Relationship:** Company → Branch (`06-shared-general.md`) → *(Admin assigns Technicians to Company orders, see `05-admin.md` §07)* → Contracts → Categories/Services (`06-shared-general.md`) → Orders.

**33 endpoints in this section.**

## 01. Authentication (Session)

#### Logout

**What this does:** Invalidates the current JWT (blacklists it) and, if `device_id` is supplied, removes that device's push-notification registration.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/auth/logout` |
| **Route name** | `company.auth.logout` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `device_id`
- **Description:** Device ID
- **Type:** `integer`
- **Required:** optional
- **Example:** `device-uuid-123`
- **Validation rules:** `nullable|string|max:255`
- `nullable` — may be null.
- `string` — must be text.
- `max:255` — must not exceed 255.

**Example Request Body:**
```json
{
    "device_id": "device-uuid-123"
}
```

**Actual Success Response(s):**

*{ 200 OK — valid token }*
```json
{
    "status": "success",
    "message": "Logged out successfully.",
    "data": null
}
```

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 Unauthenticated - no token }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** The token is no longer usable — call login again to obtain a new one.

---

## 02. Company Profile

#### Update Profile

**What this does:** Updates the company's own editable profile fields.

| | |
|---|---|
| **Method** | `PUT` |
| **Endpoint** | `{{base_url}}/api/v1/company/profile` |
| **Route name** | `company.profile.update` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `legal_name`
- **Description:** Legal Company Name
- **Type:** `string`
- **Required:** optional
- **Example:** `Example Name`
- **Validation rules:** `sometimes|string|max:200`
- `sometimes` — validated only when the field is present.
- `string` — must be text.
- `max:200` — must not exceed 200.
### `tax_number`
- **Description:** VAT Number
- **Type:** `string`
- **Required:** optional
- **Example:** `300012345600003`
- **Validation rules:** `nullable|string|max:50`
- `nullable` — may be null.
- `string` — must be text.
- `max:50` — must not exceed 50.
### `commercial_registration_no`
- **Description:** Commercial Registration Number
- **Type:** `string`
- **Required:** optional
- **Example:** `1010101010`
- **Validation rules:** `nullable|string|max:50`
- `nullable` — may be null.
- `string` — must be text.
- `max:50` — must not exceed 50.
### `commercial_register`
- **Description:** Commercial Register File
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `nullable|string|custom:MediaExists`
- `nullable` — may be null.
- `string` — must be text.
- `custom:MediaExists` — custom validation rule.
### `commercial_register_expiry_date`
- **Description:** Commercial Register Expiry Date
- **Type:** `string`
- **Required:** optional
- **Example:** `2026-08-19`
- **Validation rules:** `nullable|date`
- `nullable` — may be null.
- `date` — must be a valid date.
### `locale`
- **Description:** Locale
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `nullable|string|max:5`
- `nullable` — may be null.
- `string` — must be text.
- `max:5` — must not exceed 5.
### `image`
- **Description:** Image
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `nullable|string|custom:MediaExists`
- `nullable` — may be null.
- `string` — must be text.
- `custom:MediaExists` — custom validation rule.

**Example Request Body:**
```json
{
    "legal_name": "Profile Updated Co",
    "tax_number": "VAT-999",
    "commercial_registration_no": "CR-999"
}
```

**Actual Success Response(s):**

*{ 200 OK — valid update }*
```json
{
    "status": "success",
    "message": "Profile updated successfully",
    "data": {
        "id": 120,
        "name": "Profile Updated Co",
        "email": "profile.update.co@example.com",
        "phone": "1144433323",
        "user_type": "company",
        "user_type_label": "Company",
        "status": "active",
        "avatar": null,
        "is_email_verified": true,
        "is_phone_verified": false,
        "last_login_at": null,
        "created_at": "2026-08-20T11:20:49.000000Z",
        "legal_name": "Profile Updated Co",
        "tax_number": "VAT-999",
        "commercial_registration_no": "CR-999",
        "account_owner_phone": null,
        "commercial_register": {
            "file_url": null,
            "expiry_date": null,
            "status": null,
            "status_label": null,
            "warning": null
        }
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 Validation Error - invalid expiry date }*
```json
{
    "status": "fail",
    "message": "The Commercial Register Expiry Date is not a valid date.",
    "data": null
}
```

**What happens next:** Fetch `GET /company/profile` to see the updated record.

---

#### Change Email Profile

**What this does:** Requests an email change for the company account.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/profile/change-email` |
| **Route name** | `company.profile.change-email` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `new_email`
- **Description:** New Email
- **Type:** `string`
- **Required:** required
- **Example:** `user@example.com`
- **Validation rules:** `required|email|unique:users,email,"1",id`
- `required` — must be provided.
- `email` — must be a valid email address.
- `unique:users,email,"1",id` — must be unique (users, email, "1", id).

**Example Request Body:**
```json
{
    "new_email": "profile.new-email.co@example.com"
}
```

**Actual Success Response(s):**

*{ 200 OK — available new email }*
```json
{
    "status": "success",
    "message": "A verification code has been sent to the new email.",
    "data": {
        "verification_token": "57efd96c-f316-4273-91b4-91617df8d7ea"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 Validation Error - email already taken }*
```json
{
    "status": "fail",
    "message": "The New Email has already been taken.",
    "data": null
}
```

**What happens next:** Call `POST /company/profile/verify-email-change` with the code.

---

#### Change Password Profile

**What this does:** Changes the account password after verifying `current_password`.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/profile/change-password` |
| **Route name** | `company.profile.change-password` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `current_password`
- **Description:** Current Password
- **Type:** `string`
- **Required:** required
- **Example:** `Password123!`
- **Validation rules:** `required|string`
- `required` — must be provided.
- `string` — must be text.
### `password`
- **Description:** New Password
- **Type:** `string`
- **Required:** required
- **Example:** `Password123!`
- **Validation rules:** `required|string|min:8|confirmed`
- `required` — must be provided.
- `string` — must be text.
- `min:8` — must be at least 8.
- `confirmed` — requires a matching *_confirmation field.

**Example Request Body:**
```json
{
    "current_password": "password",
    "password": "brandnewpass123",
    "password_confirmation": "brandnewpass123"
}
```

**Actual Success Response(s):**

*{ 200 OK — correct current password }*
```json
{
    "status": "success",
    "message": "Password changed successfully.",
    "data": null
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 Error - wrong current password }*
```json
{
    "status": "fail",
    "message": "The current password is incorrect.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 Validation Error - password too short }*
```json
{
    "status": "fail",
    "message": "Password must be at least 8 characters.",
    "data": null
}
```

**What happens next:** The existing token remains valid; no re-login is required unless you also want a fresh token.

---

#### Change Phone Profile

**What this does:** Requests a phone number change for the company account.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/profile/change-phone` |
| **Route name** | `company.profile.change-phone` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `new_phone`
- **Description:** New Phone
- **Type:** `string`
- **Required:** required
- **Example:** `1234567890`
- **Validation rules:** `required|string|max:20|unique:users,phone,"1",id`
- `required` — must be provided.
- `string` — must be text.
- `max:20` — must not exceed 20.
- `unique:users,phone,"1",id` — must be unique (users, phone, "1", id).

**Example Request Body:**
```json
{
    "new_phone": "1144433398"
}
```

**Actual Success Response(s):**

*{ 200 OK — available new phone }*
```json
{
    "status": "success",
    "message": "A verification code has been sent to the new phone number.",
    "data": {
        "verification_token": "d17f158d-1751-4244-b571-022757fc9d8c"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 Validation Error - phone already taken }*
```json
{
    "status": "fail",
    "message": "The New Phone has already been taken.",
    "data": null
}
```

**What happens next:** Call `POST /company/profile/verify-phone-change` with the code.

---

#### Verify Email Change Profile

**What this does:** Confirms the new-email verification code and applies the change.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/profile/verify-email-change` |
| **Route name** | `company.profile.verify-email-change` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `token`
- **Description:** Token
- **Type:** `string`
- **Required:** required
- **Example:** `<verification-token-from-previous-response>`
- **Validation rules:** `required|string`
- `required` — must be provided.
- `string` — must be text.
### `code`
- **Description:** Verification Code
- **Type:** `string`
- **Required:** required
- **Example:** `123456`
- **Validation rules:** `required|string|size:6`
- `required` — must be provided.
- `string` — must be text.
- `size:6` — custom validation rule.

**Example Request Body:**
```json
{
    "token": "57efd96c-f316-4273-91b4-91617df8d7ea",
    "code": "123456"
}
```

**Actual Success Response(s):**

*{ 200 OK — valid code }*
```json
{
    "status": "success",
    "message": "Email changed successfully.",
    "data": {
        "id": 125,
        "name": "Shanna Altenwerth",
        "email": "profile.new-email.co@example.com",
        "phone": "1144433329",
        "user_type": "company",
        "user_type_label": "Company",
        "status": "active",
        "avatar": null,
        "is_email_verified": true,
        "is_phone_verified": false,
        "last_login_at": null,
        "created_at": "2026-08-20T11:20:49.000000Z",
        "legal_name": "Shanna Altenwerth",
        "tax_number": null,
        "commercial_registration_no": null,
        "account_owner_phone": null,
        "commercial_register": {
            "file_url": null,
            "expiry_date": null,
            "status": null,
            "status_label": null,
            "warning": null
        }
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 Error - invalid token }*
```json
{
    "status": "fail",
    "message": "Expired or invalid verification code.",
    "data": null
}
```

**What happens next:** Future logins must use the new email.

---

#### Verify Phone Change Profile

**What this does:** Confirms the new-phone verification code and applies the change.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/profile/verify-phone-change` |
| **Route name** | `company.profile.verify-phone-change` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `token`
- **Description:** Token
- **Type:** `string`
- **Required:** required
- **Example:** `<verification-token-from-previous-response>`
- **Validation rules:** `required|string`
- `required` — must be provided.
- `string` — must be text.
### `code`
- **Description:** Verification Code
- **Type:** `string`
- **Required:** required
- **Example:** `123456`
- **Validation rules:** `required|string|size:6`
- `required` — must be provided.
- `string` — must be text.
- `size:6` — custom validation rule.

**Example Request Body:**
```json
{
    "token": "d17f158d-1751-4244-b571-022757fc9d8c",
    "code": "123456"
}
```

**Actual Success Response(s):**

*{ 200 OK — valid code }*
```json
{
    "status": "success",
    "message": "Phone number changed successfully.",
    "data": {
        "id": 129,
        "name": "Mrs. Ashly Brekke",
        "email": "change.phone.co@example.com",
        "phone": "1144433398",
        "user_type": "company",
        "user_type_label": "Company",
        "status": "active",
        "avatar": null,
        "is_email_verified": true,
        "is_phone_verified": true,
        "last_login_at": null,
        "created_at": "2026-08-20T11:20:50.000000Z",
        "legal_name": "Mrs. Ashly Brekke",
        "tax_number": null,
        "commercial_registration_no": null,
        "account_owner_phone": "1144433398",
        "commercial_register": {
            "file_url": null,
            "expiry_date": null,
            "status": null,
            "status_label": null,
            "warning": null
        }
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 Error - invalid token }*
```json
{
    "status": "fail",
    "message": "Expired or invalid verification code.",
    "data": null
}
```

**What happens next:** Future logins may use the new phone as the `login` field.

---

#### Show Profile Details

**What this does:** Returns the company's own profile — base account fields plus role-specific profile data (and, for admin, `roles`/`permissions` when loaded).

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/profile` |
| **Route name** | `company.profile.view` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Authorization: Bearer {token}`

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — authenticated }*
```json
{
    "status": "success",
    "message": "Profile retrieved successfully",
    "data": {
        "id": 119,
        "name": "Profile Original Co",
        "email": "profile.co@example.com",
        "phone": "1144433322",
        "user_type": "company",
        "user_type_label": "Company",
        "status": "active",
        "avatar": null,
        "is_email_verified": true,
        "is_phone_verified": false,
        "last_login_at": null,
        "created_at": "2026-08-20T11:20:49.000000Z",
        "legal_name": "Profile Original Co",
        "tax_number": null,
        "commercial_registration_no": null,
        "account_owner_phone": null,
        "commercial_register": {
            "file_url": null,
            "expiry_date": null,
            "status": null,
            "status_label": null,
            "warning": null
        }
    }
}
```

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 Unauthenticated - no token }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Use `PUT` on the same endpoint to update editable fields.

---

## 03. Contracts

#### List All Contracts

**What this does:** Returns a paginated, filterable, searchable list of contracts.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/contracts?page=1&per_page=15&search=&sort[created_at]=desc&paginate=false&filters[is_active]=1` |
| **Route name** | `company.contracts.index` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body. Use the documented path and query parameters.

**Query parameters:**
- `page` — Page number (supported)
- `per_page` — Items per page (max: 100) (optional)
- `search` — Search term (searches across searchable fields) (optional)
- `sort[created_at]` — Sort by field: asc or desc (optional)
- `paginate` — Set to false to disable pagination (optional)
- `filters[is_active]` — Filter by active status: 1 or 0 (optional)

**Actual Success Response(s):**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Contracts retrieved successfully.",
    "data": {
        "data": [
            {
                "id": 1,
                "contract_number": "CTR-2026-000001",
                "status": "pending_signature",
                "status_label": "Pending Signature",
                "visits_allowed": 10,
                "remaining_visits": 10,
                "services": [],
                "created_at": "2026-08-20T11:20:50+00:00"
            },
            {
                "id": 2,
                "contract_number": "CTR-2026-000002",
                "status": "active",
                "status_label": "Active",
                "visits_allowed": 10,
                "remaining_visits": 10,
                "services": [],
                "created_at": "2026-08-20T11:20:50+00:00"
            }
        ],
        "links": {
            "first": "http://localhost/api/v1/company/contracts?page=1",
            "last": "http://localhost/api/v1/company/contracts?page=1",
            "prev": null,
            "next": null
        },
        "meta": {
            "current_page": 1,
            "from": 1,
            "last_page": 1,
            "links": [
                {
                    "url": null,
                    "label": "&laquo; Previous",
                    "page": null,
                    "active": false
                },
                {
                    "url": "http://localhost/api/v1/company/contracts?page=1",
                    "label": "1",
                    "page": 1,
                    "active": true
                },
                {
                    "url": null,
                    "label": "Next &raquo;",
                    "page": null,
                    "active": false
                }
            ],
            "path": "http://localhost/api/v1/company/contracts",
            "per_page": 15,
            "to": 2,
            "total": 2
        }
    }
}
```

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 Unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Use `show` on a specific id for full details.

---

#### Show Contract Details

**What this does:** Returns full details for one contract.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/contracts/:contract` |
| **Route name** | `company.contracts.show` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `contract` — Contract ID — chained from an earlier request in this flow ({{contract_id}})

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Contract retrieved successfully.",
    "data": {
        "id": 3,
        "contract_number": "CTR-2026-000001",
        "start_date": "2026-08-20",
        "end_date": "2026-09-20",
        "billing_cycle": "monthly",
        "visits_allowed": 10,
        "visits_consumed": 0,
        "remaining_visits": 10,
        "total_amount": "1000.00",
        "currency": "SAR",
        "status": "pending_signature",
        "status_label": "Pending Signature",
        "auto_renew": false,
        "pdf_path": null,
        "signed_pdf_path": null,
        "signed_at": null,
        "notes": null,
        "terminated_reason": null,
        "branches": [],
        "services": [],
        "branch_services": [],
        "visits": {
            "allowed": 10,
            "consumed": 0,
            "remaining": 10
        },
        "reports": {
            "completion_rate": 0,
            "remaining_visits": 10,
            "completed_visits": 0
        },
        "signatures": [],
        "renewal_requests": [],
        "created_at": "2026-08-20T11:20:50+00:00",
        "updated_at": "2026-08-20T11:20:50+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 404 Not Found — Not Found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

*{ 404 Not Found — Another Company's Contract }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** Use `update` to modify it, or `destroy` to remove it.

---

#### Create New Contract

**What this does:** Creates a new contract.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/contracts` |
| **Route name** | `company.contracts.store` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `201 Created`, `401 Unauthorized`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `billing_cycle`
- **Description:** Billing cycle
- **Type:** `string`
- **Required:** required
- **Example:** `monthly`
- **Validation rules:** `required|in:monthly,quarterly,annual`
- `required` — must be provided.
- `in:monthly,quarterly,annual` — must be one of: monthly, quarterly, annual.
### `start_date`
- **Description:** Start date
- **Type:** `string`
- **Required:** optional
- **Example:** `2026-08-21`
- **Validation rules:** `nullable|date|after_or_equal:today`
- `nullable` — may be null.
- `date` — must be a valid date.
- `after_or_equal:today` — custom validation rule.
### `end_date`
- **Description:** End date
- **Type:** `string`
- **Required:** optional
- **Example:** `2026-08-21`
- **Validation rules:** `nullable|date|after:start_date`
- `nullable` — may be null.
- `date` — must be a valid date.
- `after:start_date` — custom validation rule.
### `currency`
- **Description:** Currency
- **Type:** `string`
- **Required:** optional
- **Example:** `EGP`
- **Validation rules:** `sometimes|string|size:3`
- `sometimes` — validated only when the field is present.
- `string` — must be text.
- `size:3` — custom validation rule.
### `notes`
- **Description:** Notes
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `nullable|string|max:1000`
- `nullable` — may be null.
- `string` — must be text.
- `max:1000` — must not exceed 1000.
### `branches`
- **Description:** Branches
- **Type:** `array`
- **Required:** required
- **Example:** `[{"branch_id":1,"service_ids":[1],"visits_allowed":1}]`
- **Validation rules:** `required|array|min:1`
- `required` — must be provided.
- `array` — must be an array.
- `min:1` — must be at least 1.
### `branches.*.branch_id`
- **Description:** Branches item branch id
- **Type:** `integer`
- **Required:** required
- **Example:** `1`
- **Validation rules:** `required|exists:branches,id,company_id,"1"`
- `required` — must be provided.
- `exists:branches,id,company_id,"1"` — must reference an existing record (branches, id, company_id, "1").
### `branches.*.service_ids`
- **Description:** Branches item service ids
- **Type:** `array`
- **Required:** required
- **Example:** `[1]`
- **Validation rules:** `required|array|min:1`
- `required` — must be provided.
- `array` — must be an array.
- `min:1` — must be at least 1.
### `branches.*.service_ids.*`
- **Description:** Branches item service ids item
- **Type:** `integer`
- **Required:** optional
- **Example:** `2`
- **Validation rules:** `exists:categories,id`
- `exists:categories,id` — must reference an existing record (categories, id).
### `branches.*.visits_allowed`
- **Description:** Branches item visits allowed
- **Type:** `integer`
- **Required:** required
- **Example:** `1`
- **Validation rules:** `required|integer|min:1`
- `required` — must be provided.
- `integer` — must be a whole number.
- `min:1` — must be at least 1.
### `signed_media_id`
- **Description:** Signed media id
- **Type:** `integer`
- **Required:** required
- **Example:** `2`
- **Validation rules:** `required|integer|exists:media,id`
- `required` — must be provided.
- `integer` — must be a whole number.
- `exists:media,id` — must reference an existing record (media, id).

**Example Request Body:**
```json
{
    "billing_cycle": "monthly",
    "currency": "SAR",
    "notes": "Initial contract",
    "branches": [
        {
            "branch_id": 1,
            "service_ids": [
                2
            ],
            "visits_allowed": 5
        }
    ],
    "signed_media_id": 2
}
```

**Actual Success Response(s):**

*{ 201 Created — 201 - contract created (company_price used: 80 x 5 = 400) }*
```json
{
    "status": "success",
    "message": "Contract created successfully.",
    "data": {
        "id": 5,
        "contract_number": "CTR-2026-000001",
        "start_date": "2026-08-20",
        "end_date": "2026-09-20",
        "billing_cycle": "monthly",
        "visits_allowed": 5,
        "visits_consumed": 0,
        "remaining_visits": 5,
        "total_amount": "400.00",
        "currency": "SAR",
        "status": "pending_approval",
        "status_label": "Processing",
        "auto_renew": null,
        "pdf_path": null,
        "signed_pdf_path": "/storage/uploads/default/RiJQAQsKksYBUngiI6KAIZ0iRbAiqtuC9JCDQVTD.pdf",
        "signed_at": "2026-08-20T11:20:50+00:00",
        "notes": "Initial contract",
        "terminated_reason": null,
        "branches": [
            {
                "id": 6,
                "name": "Main Branch",
                "address_text": "50749 Price Causeway Apt. 364"
            }
        ],
        "services": [
            {
                "id": 32,
                "name": "AC Repair"
            }
        ],
        "branch_services": [
            {
                "branch_id": 6,
                "branch_name": "Main Branch",
                "address_text": "50749 Price Causeway Apt. 364",
                "visits_allowed": 5,
                "services": [
                    {
                        "id": 32,
                        "name": "AC Repair"
                    }
                ]
            }
        ],
        "visits": {
            "allowed": 5,
            "consumed": 0,
            "remaining": 5
        },
        "reports": {
            "completion_rate": 0,
            "remaining_visits": 5,
            "completed_visits": 0
        },
        "signatures": [
            {
                "id": 1,
                "signer_type": "company",
                "signed_at": "2026-08-20T11:20:50+00:00"
            }
        ],
        "renewal_requests": [],
        "created_at": "2026-08-20T11:20:50+00:00",
        "updated_at": "2026-08-20T11:20:50+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - validation error (missing branches, bad billing_cycle) }*
```json
{
    "status": "fail",
    "message": "The selected billing cycle is invalid. (and 2 more errors)",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 - branch_id belongs to another company (Rule::exists scoped by company_id) }*
```json
{
    "status": "fail",
    "message": "The selected branches.0.branch_id is invalid.",
    "data": null
}
```

*{ 401 Unauthorized — 401 - unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Use the returned id with `show`/`update`/`destroy` for this contract.

---

#### Renew Contract

**What this does:** Requests renewal of an `active`/`expired` contract — creates a `ContractRenewalRequest` and moves the contract to `pending_renewal`. Only one pending renewal is allowed at a time.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/contracts/:id/renew` |
| **Route name** | `company.contracts.renew` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `id` — Id ID — chained from an earlier request in this flow ({{contract_id}})

**Payload:**
Example payload is included in the request body. No FormRequest validation rules were detected.
### `key`
- **Description:** Key
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `not specified`
- `not specified` — no validation rule was declared.

**Example Request Body:**
```json
{
    "note": "Please renew for another year"
}
```

**Actual Success Response(s):**

*{ 200 OK — renewal requested }*
```json
{
    "status": "success",
    "message": "Renewal request submitted successfully.",
    "data": {
        "id": 11,
        "contract_number": "CTR-2026-000001",
        "start_date": "2026-08-20",
        "end_date": "2026-09-20",
        "billing_cycle": "monthly",
        "visits_allowed": 10,
        "visits_consumed": 0,
        "remaining_visits": 10,
        "total_amount": "1000.00",
        "currency": "SAR",
        "status": "pending_renewal",
        "status_label": "Pending Renewal",
        "auto_renew": false,
        "pdf_path": null,
        "signed_pdf_path": null,
        "signed_at": null,
        "notes": null,
        "terminated_reason": null,
        "branches": [],
        "services": [],
        "branch_services": [],
        "visits": {
            "allowed": 10,
            "consumed": 0,
            "remaining": 10
        },
        "reports": {
            "completion_rate": 0,
            "remaining_visits": 10,
            "completed_visits": 0
        },
        "signatures": [],
        "renewal_requests": [
            {
                "id": 1,
                "status": "pending",
                "note": "Please renew for another year",
                "created_at": "2026-08-20T11:20:50+00:00"
            }
        ],
        "created_at": "2026-08-20T11:20:50+00:00",
        "updated_at": "2026-08-20T11:20:50+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - draft contract cannot be renewed (only active/expired) }*
```json
{
    "status": "fail",
    "message": "Contract cannot be renewed in its current state.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 - a renewal request is already pending }*
```json
{
    "status": "fail",
    "message": "A renewal request is already pending.",
    "data": null
}
```

**What happens next:** An admin approves or rejects it via `admin.contracts.renewal`.

---

#### Sign Contract

**What this does:** Attaches a signature to a contract still awaiting one and moves it to `pending_approval`. In the normal path `POST /company/contracts` already creates the contract at `pending_approval` directly — this is a fallback for contracts that need re-signing (e.g. after rejection).

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/contracts/:id/sign` |
| **Route name** | `company.contracts.sign` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `id` — Id ID — chained from an earlier request in this flow ({{contract_id}})

**Payload:**
Send as `application/json`.

**Field documentation:**
### `signed_media_id`
- **Description:** Signed media id
- **Type:** `integer`
- **Required:** required
- **Example:** `2`
- **Validation rules:** `required|integer|exists:media,id`
- `required` — must be provided.
- `integer` — must be a whole number.
- `exists:media,id` — must reference an existing record (media, id).

**Example Request Body:**
```json
{
    "signed_media_id": 2
}
```

**Actual Success Response(s):**

*{ 200 OK — valid signature }*
```json
{
    "status": "success",
    "message": "Contract signed successfully.",
    "data": {
        "id": 8,
        "contract_number": "CTR-2026-000001",
        "start_date": "2026-08-20",
        "end_date": "2026-09-20",
        "billing_cycle": "monthly",
        "visits_allowed": 10,
        "visits_consumed": 0,
        "remaining_visits": 10,
        "total_amount": "1000.00",
        "currency": "SAR",
        "status": "pending_approval",
        "status_label": "Processing",
        "auto_renew": false,
        "pdf_path": null,
        "signed_pdf_path": "/storage/uploads/default/dYwFabxesmeaWiWFoIszKoKJRorPkkSl3ztluMUM.pdf",
        "signed_at": "2026-08-20T11:20:50+00:00",
        "notes": null,
        "terminated_reason": null,
        "branches": [],
        "services": [],
        "branch_services": [],
        "visits": {
            "allowed": 10,
            "consumed": 0,
            "remaining": 10
        },
        "reports": {
            "completion_rate": 0,
            "remaining_visits": 10,
            "completed_visits": 0
        },
        "signatures": [
            {
                "id": 2,
                "signer_type": "company",
                "signed_at": "2026-08-20T11:20:50+00:00"
            }
        ],
        "renewal_requests": [],
        "created_at": "2026-08-20T11:20:50+00:00",
        "updated_at": "2026-08-20T11:20:50+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - already signed / active contract cannot be re-signed }*
```json
{
    "status": "fail",
    "message": "The selected signed media id is invalid.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 - validation error (signed_media_id required) }*
```json
{
    "status": "fail",
    "message": "The signed media id field is required.",
    "data": null
}
```

*{ 404 Not Found — 404 - not found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** An admin reviews and approves/rejects it — see `admin.contracts.approve` / `.reject`.

---

#### Template Contract

**What this does:** Returns the current contract-template document (media id + URL) for the company to read and sign externally.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/contracts/:id/template` |
| **Route name** | `company.contracts.template` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized`, `404 Not Found` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `id` — Id ID — chained from an earlier request in this flow ({{contract_id}})

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — template media returned }*
```json
{
    "status": "success",
    "message": "Template retrieved successfully.",
    "data": {
        "media_id": 7,
        "url": "/storage/uploads/default/L8kCsmPWWEzidd0tBNjxzSvPD96JBeaitgLQQaFi.pdf",
        "name": "signed.pdf"
    }
}
```

**Actual Error Response(s):**

*{ 404 Not Found — 404 - no contract template configured }*
```json
{
    "status": "fail",
    "message": "Contract template not configured.",
    "data": null
}
```

*{ 401 Unauthorized — 401 - unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Upload the signed PDF via `POST /media`, then create the contract with `POST /company/contracts` passing that media id as `signed_media_id`.

---

#### Delete Contract

**What this does:** Permanently deletes a contract.

| | |
|---|---|
| **Method** | `DELETE` |
| **Endpoint** | `{{base_url}}/api/v1/company/contracts/:contract` |
| **Route name** | `company.contracts.destroy` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `contract` — Contract ID — chained from an earlier request in this flow ({{contract_id}})

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — draft contract deleted }*
```json
{
    "status": "success",
    "message": "Contract deleted successfully.",
    "data": null
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - active contract cannot be deleted (canBeDeleted() only allows draft/pending_signature) }*
```json
{
    "status": "fail",
    "message": "Contract cannot be deleted in its current state.",
    "data": null
}
```

*{ 404 Not Found — 404 - not found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** It no longer appears in `index`.

---

## 04. Orders & Jobs — Creating

#### Show Cart Details

**What this does:** Returns full details for one cart.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/cart` |
| **Route name** | `company.cart.show` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — empty cart }*
```json
{
    "status": "success",
    "message": "Cart retrieved",
    "data": {
        "id": null,
        "items_count": 0,
        "subtotal": 0
    }
}
```

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 - unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Use `update` to modify it, or `destroy` to remove it.

---

#### Create New Custom request

**What this does:** Company equivalent of `client.cart.custom-request` — creates a `waiting_price` order for the given `branch_id`.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/cart/custom-requests` |
| **Route name** | `company.cart.custom-requests.store` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `201 Created`, `401 Unauthorized`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `category_id`
- **Description:** Category
- **Type:** `integer`
- **Required:** optional
- **Example:** `2`
- **Validation rules:** `nullable|exists:categories,id`
- `nullable` — may be null.
- `exists:categories,id` — must reference an existing record (categories, id).
### `description`
- **Description:** Description
- **Type:** `string`
- **Required:** required
- **Example:** `Example content text`
- **Validation rules:** `required|string|max:2000`
- `required` — must be provided.
- `string` — must be text.
- `max:2000` — must not exceed 2000.
### `request_media`
- **Description:** Attachment
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `nullable|string|custom:MediaExists`
- `nullable` — may be null.
- `string` — must be text.
- `custom:MediaExists` — custom validation rule.
### `address_id`
- **Description:** Address
- **Type:** `integer`
- **Required:** required
- **Example:** `1`
- **Validation rules:** `required|exists:addresses,id`
- `required` — must be provided.
- `exists:addresses,id` — must reference an existing record (addresses, id).

**Example Request Body:**
```json
{
    "description": "Need a quote for HVAC overhaul across the branch",
    "address_id": 1,
    "branch_id": 1
}
```

**Actual Success Response(s):**

*{ 201 Created — 201 - custom request with branch_id, order_source=job_order }*
```json
{
    "status": "success",
    "message": "Custom request submitted",
    "data": {
        "order_number": "ORD-260820-STUQ",
        "customer_id": 175,
        "order_source": "job_order",
        "branch_id": 8,
        "booking_type": "instant",
        "address_id": 34,
        "status": "waiting_price",
        "subtotal_amount": "0.00",
        "vat_amount": "0.00",
        "fees_amount": "0.00",
        "total_amount": "0.00",
        "paid_amount": "0.00",
        "uuid": "f4e5adf0-3c3d-475d-83c3-2870d26498e9",
        "updated_at": "2026-08-20T11:20:51.000000Z",
        "created_at": "2026-08-20T11:20:51.000000Z",
        "id": 34,
        "items": [
            {
                "id": 30,
                "order_id": "f4e5adf0-3c3d-475d-83c3-2870d26498e9",
                "category_id": null,
                "service_name": "Custom request",
                "pricing_type": "quote",
                "unit_price": "0.00",
                "quantity": 1,
                "line_total": "0.00",
                "is_quoted": false,
                "notes": null,
                "request_description": "Need a quote for HVAC overhaul across the branch",
                "created_at": "2026-08-20T11:20:51.000000Z",
                "updated_at": "2026-08-20T11:20:51.000000Z"
            }
        ]
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - branch_id required for Company (validated separately by Company\CartController) }*
```json
{
    "status": "fail",
    "message": "The Branch field is required.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 - branch_id belongs to another company }*
```json
{
    "status": "fail",
    "message": "The selected Branch is invalid.",
    "data": null
}
```

*{ 401 Unauthorized — 401 - unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Awaits `admin.orders.quote`, same as the individual flow.

---

#### Update Item

**What this does:** Updates an existing cart.

| | |
|---|---|
| **Method** | `PATCH` |
| **Endpoint** | `{{base_url}}/api/v1/company/cart/items/:itemId` |
| **Route name** | `company.cart.items.update` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `itemId` — ItemId ID — chained from an earlier request in this flow ({{cart_item_id}})

**Payload:**
Send as `application/json`.

**Field documentation:**
### `quantity`
- **Description:** Quantity
- **Type:** `integer`
- **Required:** required
- **Example:** `1`
- **Validation rules:** `required|integer|min:1|max:100`
- `required` — must be provided.
- `integer` — must be a whole number.
- `min:1` — must be at least 1.
- `max:100` — must not exceed 100.

**Example Request Body:**
```json
{
    "quantity": 4
}
```

**Actual Success Response(s):**

*{ 200 OK — quantity updated }*
```json
{
    "status": "success",
    "message": "Cart updated",
    "data": {
        "id": 22,
        "items_count": 4,
        "subtotal": 320,
        "items": [
            {
                "id": 19,
                "quantity": 4,
                "unit_price": "80.00",
                "line_total": 320,
                "service": {
                    "id": 36,
                    "name": "AC Repair",
                    "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200"
                },
                "created_at": "2026-08-20T11:20:51.000000Z"
            }
        ]
    }
}
```

**Actual Error Response(s):**

*{ 404 Not Found — 404 - item does not exist }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** Fetch `show` to confirm the change.

---

#### Checkout Cart

**What this does:** Pays for the company's cart (wallet — immediate, all-or-nothing debit — or gateway) and, only on confirmed payment, creates the `Order` (`status: pending`) with one `OrderItem` per cart line; empties the cart. Requires an `Idempotency-Key` header (safe to retry). VAT is added on top of the cart subtotal per `settings.vat_percent`.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/cart/checkout` |
| **Route name** | `company.cart.checkout` |
| **Guard** | JWT bearer (`auth:api`); account must be `active`; requires `Idempotency-Key` header (`idempotency`) |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `201 Created`, `401 Unauthorized`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`
- `Idempotency-Key: wallet-checkout-19`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `payment_method`
- **Description:** Payment Method
- **Type:** `string`
- **Required:** required
- **Example:** `gateway`
- **Validation rules:** `required|in:"gateway","wallet"|custom:WalletCoversCartRule`
- `required` — must be provided.
- `in:"gateway","wallet"` — must be one of: "gateway", "wallet".
- `custom:WalletCoversCartRule` — custom validation rule.
### `booking_type`
- **Description:** Booking Type
- **Type:** `string`
- **Required:** required
- **Example:** `instant`
- **Validation rules:** `required|in:"instant","scheduled"`
- `required` — must be provided.
- `in:"instant","scheduled"` — must be one of: "instant", "scheduled".
### `address_id`
- **Description:** Address
- **Type:** `integer`
- **Required:** required
- **Example:** `1`
- **Validation rules:** `required|exists:addresses,id,user_id,"1"`
- `required` — must be provided.
- `exists:addresses,id,user_id,"1"` — must reference an existing record (addresses, id, user_id, "1").
### `scheduled_date`
- **Description:** Scheduled Date
- **Type:** `string`
- **Required:** conditional
- **Example:** `2026-08-21`
- **Validation rules:** `required_if:booking_type,scheduled|date|after_or_equal:today`
- `required_if:booking_type,scheduled` — required when booking_type, scheduled.
- `date` — must be a valid date.
- `after_or_equal:today` — custom validation rule.

**Example Request Body:**
```json
{
    "payment_method": "wallet",
    "booking_type": "instant",
    "address_id": 1,
    "branch_id": 1
}
```

**Actual Success Response(s):**

*{ 201 Created — 201 - wallet payment, order_source=job_order, branch_id set }*
```json
{
    "status": "success",
    "message": "Order placed successfully",
    "data": {
        "order_number": "ORD-260820-LJYB",
        "customer_id": 179,
        "order_source": "job_order",
        "branch_id": 10,
        "booking_type": "instant",
        "scheduled_date": null,
        "address_id": 37,
        "status": "pending",
        "subtotal_amount": "160.00",
        "vat_amount": "24.00",
        "fees_amount": "0.00",
        "total_amount": "184.00",
        "paid_amount": "184.00",
        "uuid": "47aa979b-0794-4bcd-929a-dfcce6b2fbf5",
        "updated_at": "2026-08-20T11:20:51.000000Z",
        "created_at": "2026-08-20T11:20:51.000000Z",
        "id": 35,
        "items": [
            {
                "id": 31,
                "order_id": "47aa979b-0794-4bcd-929a-dfcce6b2fbf5",
                "category_id": 38,
                "service_name": "AC Repair",
                "pricing_type": "fixed",
                "unit_price": "80.00",
                "quantity": 2,
                "line_total": "160.00",
                "is_quoted": false,
                "notes": null,
                "request_description": null,
                "created_at": "2026-08-20T11:20:51.000000Z",
                "updated_at": "2026-08-20T11:20:51.000000Z"
            }
        ]
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - branch_id required for Company checkout }*
```json
{
    "status": "fail",
    "message": "The Branch field is required.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 - empty cart }*
```json
{
    "status": "error",
    "message": "Your cart is empty",
    "data": {
        "error_code": "BUSINESS_RULE_VIOLATED",
        "correlation_id": "fda27705-18ff-48c0-bba2-6cbf91020d90"
    }
}
```

*{ 422 Unprocessable Entity — 422 - BUG (shared with Client): wallet (105.00) covers cart subtotal (100.00) but not VAT-inclusive total (115.00); CheckoutRequest validates against subtotal only, CheckoutCommandService rejects one layer deeper }*
```json
{
    "status": "fail",
    "message": "Wallet balance (105.00 SAR) is less than the order total (115.00 SAR). Wallet cannot be used for partial payment.",
    "data": null
}
```

*{ 401 Unauthorized — 401 - unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** The order now needs a technician — see `admin.orders.assign-technician` in Assignments. Track it via `company.orders.show` in Requests / Jobs.

---

#### Clear Cart

**What this does:** Empties the entire cart.

| | |
|---|---|
| **Method** | `DELETE` |
| **Endpoint** | `{{base_url}}/api/v1/company/cart` |
| **Route name** | `company.cart.clear` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — cart cleared }*
```json
{
    "status": "success",
    "message": "Cart cleared",
    "data": {
        "id": 20,
        "items_count": 0,
        "subtotal": 0,
        "items": []
    }
}
```

**What happens next:** Cart is now empty — add items again before checking out.

---

#### Add Item

**What this does:** Adds a bookable service (`category_id`) and `quantity` to the cart, or increments quantity if it's already in the cart.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/cart/items` |
| **Route name** | `company.cart.items.add` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `201 Created`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
Send as `application/json`.

**Field documentation:**
### `category_id`
- **Description:** Service
- **Type:** `integer`
- **Required:** required
- **Example:** `2`
- **Validation rules:** `required|exists:categories,id,is_active,"1",price,"NOT_NULL"`
- `required` — must be provided.
- `exists:categories,id,is_active,"1",price,"NOT_NULL"` — must reference an existing record (categories, id, is_active, "1", price, "NOT_NULL").
### `quantity`
- **Description:** Quantity
- **Type:** `integer`
- **Required:** optional
- **Example:** `1`
- **Validation rules:** `sometimes|integer|min:1|max:100`
- `sometimes` — validated only when the field is present.
- `integer` — must be a whole number.
- `min:1` — must be at least 1.
- `max:100` — must not exceed 100.

**Example Request Body:**
```json
{
    "category_id": 2,
    "quantity": 2
}
```

**Actual Success Response(s):**

*{ 201 Created — 201 - item added, company priced at contract_price (80.00) }*
```json
{
    "status": "success",
    "message": "Item added to cart",
    "data": {
        "id": 21,
        "items_count": 2,
        "subtotal": 160,
        "items": [
            {
                "id": 18,
                "quantity": 2,
                "unit_price": "80.00",
                "line_total": 160,
                "service": {
                    "id": 35,
                    "name": "AC Repair",
                    "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200"
                },
                "created_at": "2026-08-20T11:20:51.000000Z"
            }
        ]
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - category does not exist }*
```json
{
    "status": "fail",
    "message": "The selected category does not exist.",
    "data": null
}
```

**What happens next:** Continue adding items, or proceed to `checkout` once done.

---

#### Remove Item

**What this does:** Removes one line item from the cart by its cart-item id.

| | |
|---|---|
| **Method** | `DELETE` |
| **Endpoint** | `{{base_url}}/api/v1/company/cart/items/:itemId` |
| **Route name** | `company.cart.items.remove` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `itemId` — ItemId ID — chained from an earlier request in this flow ({{cart_item_id}})

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — item removed }*
```json
{
    "status": "success",
    "message": "Item removed from cart",
    "data": {
        "id": 24,
        "items_count": 0,
        "subtotal": 0,
        "items": []
    }
}
```

**What happens next:** Review the updated cart with `GET /company/cart`.

---

## 04. Orders & Jobs — Lifecycle

#### List All Orders

**What this does:** Returns a paginated, filterable, searchable list of orders.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/orders?page=1&per_page=15&search=&sort[created_at]=desc&paginate=false&filters[is_active]=1` |
| **Route name** | `company.orders.index` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body. Use the documented path and query parameters.

**Query parameters:**
- `page` — Page number (supported)
- `per_page` — Items per page (max: 100) (optional)
- `search` — Search term (searches across searchable fields) (optional)
- `sort[created_at]` — Sort by field: asc or desc (optional)
- `paginate` — Set to false to disable pagination (optional)
- `filters[is_active]` — Filter by active status: 1 or 0 (optional)

**Actual Success Response(s):**

*{ 200 OK — job orders only }*
```json
{
    "status": "success",
    "message": "Orders retrieved successfully.",
    "data": {
        "data": [
            {
                "id": 36,
                "uuid": "64b8becf-45bb-4925-a7c5-b10bb0608a29",
                "order_number": "ORD-260820-BDAD",
                "status": "pending",
                "scheduled_date": null,
                "total_amount": "82.58",
                "items": [
                    {
                        "id": 32,
                        "service_name": "molestias ea necessitatibus",
                        "pricing_type": "fixed",
                        "unit_price": "169.55",
                        "quantity": 1,
                        "line_total": "169.55",
                        "is_quoted": false,
                        "request_description": null,
                        "request_media_url": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
                    }
                ],
                "created_at": "2026-08-20T11:20:51+00:00"
            },
            {
                "id": 37,
                "uuid": "6ed00cfa-db8a-45cd-be3d-894fe529ac82",
                "order_number": "ORD-260820-TKVN",
                "status": "confirmed",
                "scheduled_date": null,
                "total_amount": "551.54",
                "items": [
                    {
                        "id": 33,
                        "service_name": "ea et natus",
                        "pricing_type": "fixed",
                        "unit_price": "213.77",
                        "quantity": 2,
                        "line_total": "427.54",
                        "is_quoted": false,
                        "request_description": null,
                        "request_media_url": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
                    }
                ],
                "created_at": "2026-08-20T11:20:51+00:00"
            }
        ],
        "links": {
            "first": "http://localhost/api/v1/company/orders?page=1",
            "last": "http://localhost/api/v1/company/orders?page=1",
            "prev": null,
            "next": null
        },
        "meta": {
            "current_page": 1,
            "from": 1,
            "last_page": 1,
            "links": [
                {
                    "url": null,
                    "label": "&laquo; Previous",
                    "page": null,
                    "active": false
                },
                {
                    "url": "http://localhost/api/v1/company/orders?page=1",
                    "label": "1",
                    "page": 1,
                    "active": true
                },
                {
                    "url": null,
                    "label": "Next &raquo;",
                    "page": null,
                    "active": false
                }
            ],
            "path": "http://localhost/api/v1/company/orders",
            "per_page": 15,
            "to": 2,
            "total": 2
        }
    }
}
```

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 Unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Use `show` on a specific id for full details.

---

#### Show Order Details

**What this does:** Returns full details for one order.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/orders/:order` |
| **Route name** | `company.orders.show` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `order` — Order UUID (orders.uuid) — copy the `uuid` field from a List/Show response, not the numeric id. — chained from an earlier request in this flow ({{order_id}})

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Order retrieved successfully.",
    "data": {
        "id": 38,
        "uuid": "b27c8219-c713-4492-89f4-d15351504335",
        "order_number": "ORD-260820-DEID",
        "status": "pending",
        "scheduled_date": "2026-08-24",
        "subtotal_amount": "72.48",
        "vat_amount": "10.87",
        "fees_amount": "0.00",
        "total_amount": "83.35",
        "paid_amount": "83.35",
        "address": {
            "id": 42,
            "title": "HQ"
        },
        "technician": null,
        "items": [
            {
                "id": 34,
                "service_name": "nisi et saepe",
                "pricing_type": "fixed",
                "unit_price": "235.11",
                "quantity": 1,
                "line_total": "235.11",
                "is_quoted": false,
                "request_description": null,
                "request_media_url": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
            }
        ],
        "status_history": [
            {
                "from_status": null,
                "to_status": "pending",
                "created_at": "2026-08-20T11:20:51+00:00"
            }
        ],
        "rating": null,
        "created_at": "2026-08-20T11:20:51+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 404 Not Found — Not Found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

*{ 404 Not Found — Another Company's Order }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** Use `update` to modify it, or `destroy` to remove it.

---

#### Accept Price Order

**What this does:** Accepts an admin-quoted price on a custom-price request and pays for it (wallet/gateway, same mechanics as checkout) — only valid while `status: priced`. On success the order moves to `pending`.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/orders/:id/accept-price` |
| **Route name** | `company.orders.accept-price` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized`, `404 Not Found`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `id` — Order UUID (orders.uuid) — copy the `uuid` field from a List/Show response, not the numeric id. — chained from an earlier request in this flow ({{order_id}})

**Payload:**
Example payload is included in the request body. No FormRequest validation rules were detected.
### `key`
- **Description:** Key
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `not specified`
- `not specified` — no validation rule was declared.

**Example Request Body:**
```json
{
    "payment_method": "wallet"
}
```

**Actual Success Response(s):**

*{ 200 OK — wallet }*
```json
{
    "status": "success",
    "message": "Price accepted, your order is now being processed.",
    "data": {
        "id": 40,
        "uuid": "73fa3c8c-edd2-4b72-8aa4-786d7be59ce7",
        "order_number": "ORD-260820-DTLE",
        "status": "pending",
        "scheduled_date": null,
        "subtotal_amount": "443.97",
        "vat_amount": "66.60",
        "fees_amount": "0.00",
        "total_amount": "100.00",
        "paid_amount": "100.00",
        "rating": null,
        "created_at": "2026-08-20T11:20:51+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 Wrong Status }*
```json
{
    "status": "fail",
    "message": "Insufficient wallet balance",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 Insufficient Wallet Balance - caught downstream in OrderCommandService, NOT by AcceptPriceRequest (shared bug, see report) }*
```json
{
    "status": "fail",
    "message": "Wallet balance (5.00 SAR) is less than the order total (1,000.00 SAR). Wallet cannot be used for partial payment.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 Validation Error - missing payment_method }*
```json
{
    "status": "fail",
    "message": "The Payment Method field is required.",
    "data": null
}
```

*{ 404 Not Found — Not Found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

*{ 401 Unauthorized — 401 - unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Same as a fresh checkout from here: awaits `admin.orders.assign-technician`.

---

#### Cancel Order

**What this does:** Cancels the company's own order — only allowed before the technician has started work (`pending`/`waiting_price`/`priced`/`accepted`/`on_the_way`; not once `start`/`finish`). If `paid_amount > 0` and the order is an individual (non-job-order) order, the paid amount is refunded to the customer's wallet automatically.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/orders/:id/cancel` |
| **Route name** | `company.orders.cancel` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized`, `404 Not Found`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `id` — Order UUID (orders.uuid) — copy the `uuid` field from a List/Show response, not the numeric id. — chained from an earlier request in this flow ({{order_id}})

**Payload:**
Send as `application/json`.

**Field documentation:**
### `reason`
- **Description:** Cancellation Reason
- **Type:** `string`
- **Required:** required
- **Example:** `Manual adjustment by admin.`
- **Validation rules:** `required|string|max:500`
- `required` — must be provided.
- `string` — must be text.
- `max:500` — must not exceed 500.

**Example Request Body:**
```json
{
    "reason": "Branch closed for maintenance"
}
```

**Actual Success Response(s):**

*{ 200 OK — job_order cancelled; RefundService blocks the refund because order_source != 'individual' (Company job-orders are billed to the company, not a customer wallet) — cancel still succeeds with 200, no wallet credit }*
```json
{
    "status": "success",
    "message": "Order cancelled successfully.",
    "data": {
        "id": 50,
        "uuid": "e09fbaf9-f84f-47ef-9532-0fff594cc24b",
        "order_number": "ORD-260820-KMTS",
        "status": "cancelled",
        "scheduled_date": "2026-08-24",
        "subtotal_amount": "459.20",
        "vat_amount": "68.88",
        "fees_amount": "0.00",
        "total_amount": "100.00",
        "paid_amount": "100.00",
        "rating": null,
        "created_at": "2026-08-20T11:20:52+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - technician has started the work (status=start), cannot self-cancel }*
```json
{
    "status": "fail",
    "message": "This order can no longer be cancelled.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 - reason is required }*
```json
{
    "status": "fail",
    "message": "The Cancellation Reason field is required.",
    "data": null
}
```

*{ 404 Not Found — 404 - not found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

*{ 401 Unauthorized — 401 - unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Nothing further — the order is terminal. Company job orders never auto-refund to a wallet (billed to the company/contract instead); use `admin.wallets.block-refund` if manual reconciliation is needed.

---

#### Confirm Completion Order

**What this does:** Confirms a `finish`-status order as complete — moves it to `confirmed` (terminal) and, if `stars` is given, records a rating against the technician and recalculates their aggregate stats.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/orders/:id/confirm-completion` |
| **Route name** | `company.orders.confirm-completion` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found`, `422 Unprocessable Entity`, `500 Internal Server Error` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `id` — Order UUID (orders.uuid) — copy the `uuid` field from a List/Show response, not the numeric id. — chained from an earlier request in this flow ({{order_id}})

**Payload:**
Send as `application/json`.

**Field documentation:**
### `stars`
- **Description:** Rating
- **Type:** `integer`
- **Required:** optional
- **Example:** `1`
- **Validation rules:** `nullable|integer|min:1|max:5`
- `nullable` — may be null.
- `integer` — must be a whole number.
- `min:1` — must be at least 1.
- `max:5` — must not exceed 5.
### `comment`
- **Description:** Comment
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `nullable|string|max:500`
- `nullable` — may be null.
- `string` — must be text.
- `max:500` — must not exceed 500.

**Example Request Body:**
```json
{
    "stars": 1,
    "comment": "value"
}
```

**Actual Success Response(s):**

*{ 200 OK — completion confirmed, no rating submitted }*
```json
{
    "status": "success",
    "message": "Thanks for confirming — your order is complete.",
    "data": {
        "id": 46,
        "uuid": "add6226a-1f0d-47cd-a59d-c687fc4a5c65",
        "order_number": "ORD-260820-UQSB",
        "status": "confirmed",
        "scheduled_date": "2026-08-25",
        "subtotal_amount": "396.71",
        "vat_amount": "59.51",
        "fees_amount": "0.00",
        "total_amount": "456.22",
        "paid_amount": "456.22",
        "rating": null,
        "created_at": "2026-08-20T11:20:52+00:00"
    }
}
```

> **Fixed:** an earlier pass of this doc captured a real `500` here — `ratings.technician_id` was constrained to `users.id`, but every writer (`OrderCommandService::confirmCompletion()`, `Order::technician_id`, `Technician::ratings()`, `Rating::technician()`) treats it as `technicians.id`, the same convention `orders.technician_id` uses. Rating a completed order failed its FK constraint every time `stars` was sent. Fixed by `database/migrations/2026_08_20_220000_fix_ratings_technician_id_foreign_key.php`, which re-points the constraint at `technicians.id`.

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - order is not awaiting completion confirmation (not in finish status) }*
```json
{
    "status": "fail",
    "message": "This order is not awaiting a completion confirmation.",
    "data": null
}
```

*{ 422 Unprocessable Entity — 422 - stars out of range (max 5) }*
```json
{
    "status": "fail",
    "message": "The Rating must not be greater than 5.",
    "data": null
}
```

*{ 404 Not Found — 404 - not found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** Order lifecycle is complete. The technician's `avg_rating`/`completed_orders_count` reflect the new rating immediately.

---

#### Reject Price Order

**What this does:** Rejects an admin-quoted price — cancels the order. Nothing was ever charged, so no refund is triggered.

| | |
|---|---|
| **Method** | `POST` |
| **Endpoint** | `{{base_url}}/api/v1/company/orders/:id/reject-price` |
| **Route name** | `company.orders.reject-price` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found`, `422 Unprocessable Entity` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `id` — Order UUID (orders.uuid) — copy the `uuid` field from a List/Show response, not the numeric id. — chained from an earlier request in this flow ({{order_id}})

**Payload:**
Example payload is included in the request body. No FormRequest validation rules were detected.
### `key`
- **Description:** Key
- **Type:** `string`
- **Required:** optional
- **Example:** `value`
- **Validation rules:** `not specified`
- `not specified` — no validation rule was declared.

**Example Request Body:**
```json
{
    "key": "value"
}
```

**Actual Success Response(s):**

*{ 200 OK — price rejected, order cancelled }*
```json
{
    "status": "success",
    "message": "Price rejected, your order has been cancelled.",
    "data": {
        "id": 44,
        "uuid": "7feb61a7-31fa-4241-8b0e-6a7cab227cc7",
        "order_number": "ORD-260820-YOKV",
        "status": "cancelled",
        "scheduled_date": null,
        "subtotal_amount": "85.59",
        "vat_amount": "12.84",
        "fees_amount": "0.00",
        "total_amount": "200.00",
        "paid_amount": "98.43",
        "rating": null,
        "created_at": "2026-08-20T11:20:52+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 422 Unprocessable Entity — 422 - order is not awaiting customer response }*
```json
{
    "status": "fail",
    "message": "This order has no pending price to accept or reject.",
    "data": null
}
```

*{ 404 Not Found — 404 - not found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** The custom request is over; submit a new one if still needed.

---

## 05. Invoices (Payments) & Reports

#### List All Invoices

**What this does:** Returns a paginated, filterable, searchable list of invoices.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/invoices?page=1&per_page=15&search=&sort[created_at]=desc&paginate=false&filters[is_active]=1` |
| **Route name** | `company.invoices.index` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body. Use the documented path and query parameters.

**Query parameters:**
- `page` — Page number (supported)
- `per_page` — Items per page (max: 100) (optional)
- `search` — Search term (searches across searchable fields) (optional)
- `sort[created_at]` — Sort by field: asc or desc (optional)
- `paginate` — Set to false to disable pagination (optional)
- `filters[is_active]` — Filter by active status: 1 or 0 (optional)

**Actual Success Response(s):**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Invoices retrieved successfully.",
    "data": {
        "data": [
            {
                "id": 1,
                "invoice_number": "INV-2026-000001",
                "contract_number": "CTR-2026-000001",
                "sequence_no": 1,
                "total_invoices": null,
                "amount_due": "500.00",
                "amount_paid": "0.00",
                "currency": "SAR",
                "status": "issued",
                "status_label": "Due",
                "receipt_status": null,
                "issue_date": "2026-08-20",
                "due_date": "2026-09-04"
            },
            {
                "id": 2,
                "invoice_number": "INV-2026-000002",
                "contract_number": "CTR-2026-000001",
                "sequence_no": 2,
                "total_invoices": null,
                "amount_due": "500.00",
                "amount_paid": "0.00",
                "currency": "SAR",
                "status": "paid",
                "status_label": "Paid",
                "receipt_status": null,
                "issue_date": "2026-08-20",
                "due_date": "2026-09-04"
            }
        ],
        "links": {
            "first": "http://localhost/api/v1/company/invoices?page=1",
            "last": "http://localhost/api/v1/company/invoices?page=1",
            "prev": null,
            "next": null
        },
        "meta": {
            "current_page": 1,
            "from": 1,
            "last_page": 1,
            "links": [
                {
                    "url": null,
                    "label": "&laquo; Previous",
                    "page": null,
                    "active": false
                },
                {
                    "url": "http://localhost/api/v1/company/invoices?page=1",
                    "label": "1",
                    "page": 1,
                    "active": true
                },
                {
                    "url": null,
                    "label": "Next &raquo;",
                    "page": null,
                    "active": false
                }
            ],
            "path": "http://localhost/api/v1/company/invoices",
            "per_page": 15,
            "to": 2,
            "total": 2
        }
    }
}
```

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 Unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Use `show` on a specific id for full details.

---

#### Show Invoice Details

**What this does:** Returns full details for one invoice.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/invoices/:invoice` |
| **Route name** | `company.invoices.show` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `404 Not Found` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Path Parameters:**
- `invoice` — Invoice ID — ⚠️ **no real record exists in the seeded database** (confirmed empty — see [SEED_DATA.md](SEED_DATA.md)); placeholder `3` will 404/422 until you create one

**Payload:**
No request body. Use the documented path and query parameters.

**Actual Success Response(s):**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Invoice retrieved successfully.",
    "data": {
        "id": 3,
        "invoice_number": "INV-2026-000001",
        "contract": {
            "id": 16,
            "contract_number": "CTR-2026-000001",
            "total_amount": "1000.00",
            "total_invoices_count": null
        },
        "sequence_no": 1,
        "period_start": "2026-08-01",
        "period_end": "2026-08-31",
        "visits_count": 0,
        "services": [],
        "amount_due": "500.00",
        "amount_paid": "0.00",
        "currency": "SAR",
        "status": "issued",
        "status_label": "Due",
        "issue_date": "2026-08-20",
        "due_date": "2026-09-04",
        "pdf_path": null,
        "receipt": {
            "status": null,
            "notice": null
        },
        "line_items": [
            {
                "id": 1,
                "description": "Monthly installment",
                "amount": "500.00"
            }
        ],
        "created_at": "2026-08-20T11:20:51+00:00"
    }
}
```

**Actual Error Response(s):**

*{ 404 Not Found — Not Found }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

*{ 404 Not Found — Another Company's Invoice }*
```json
{
    "status": "fail",
    "message": "Resource not found",
    "data": null
}
```

**What happens next:** Use `update` to modify it, or `destroy` to remove it.

---

#### Report Summary

**What this does:** Returns a dashboard-style summary of the company's own orders and invoice financials — order counts by status, and unpaid/paid/overdue invoice totals. Everything is scoped to the authenticated company (`customer_id`/`company_id` = the logged-in user's id).

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/reports/summary` |
| **Route name** | `company.reports.summary` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body, no query parameters.

**Field notes:**
- `orders.total` / `orders.completed` (status `confirmed`) / `orders.cancelled` (status `cancelled`) come from one query over the company's `orders`; `orders.ongoing` is computed as `total - completed - cancelled`.
- `financials.unpaid_amount` — sum of `amount_due - amount_paid` across invoices, excluding `paid`/`cancelled`/`draft` statuses.
- `financials.total_paid_amount` — sum of `amount_paid` across all of the company's invoices.
- `financials.overdue_amount` — sum of `amount_due - amount_paid` where invoice status is `overdue`.
- `financials.overdue_days` — days between the oldest overdue invoice's `due_date` and today; `0` if nothing is overdue.

**Example Response:**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Report retrieved successfully.",
    "data": {
        "orders": {
            "total": 0,
            "completed": 0,
            "cancelled": 0,
            "ongoing": 0
        },
        "financials": {
            "unpaid_amount": 0.0,
            "total_paid_amount": 0.0,
            "overdue_days": 0,
            "overdue_amount": 0.0
        }
    }
}
```

---

## 06. Home & Visits

#### Home

**What this does:** Returns the company's home-screen summary — up to 4 in-progress orders (`on_the_way`/`start`/`finish`, soonest `scheduled_date` first) and the single next upcoming order (`accepted`/`on_the_way`, `scheduled_date` in the future). "Visit" and "order" are the same entity in this domain — see `Branch::hasScheduledVisits()`, which already treats any non-terminal order as a scheduled visit.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/home` |
| **Route name** | `company.home.index` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body, no query parameters.

**Example Success Response:**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Home Reterived",
    "data": {
        "incoming_order": null,
        "company_current_orders": [
            {
                "id": 20,
                "uuid": "b84b352c-7515-41f9-9b96-cadca5b06084",
                "order_number": "ORD-260823-USIP",
                "status": "finish",
                "scheduled_date": null,
                "total_amount": "0.00",
                "items": [],
                "created_at": "2026-08-23T11:18:32+00:00"
            }
        ]
    }
}
```
`incoming_order` is `null` when there is no future-dated order in `accepted`/`on_the_way` status (as above); otherwise it's the same shape as one entry in `company_current_orders`.

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 Unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Drill into a specific order via `GET /company/orders/:id` (Orders & Jobs — Lifecycle).

---

#### List All Visits

**What this does:** Returns a paginated list of the company's own orders ("visits") — the same underlying `orders` table as the Orders & Jobs sections, filtered/scoped for a dashboard-style visits list rather than the full lifecycle actions.

| | |
|---|---|
| **Method** | `GET` |
| **Endpoint** | `{{base_url}}/api/v1/company/visits` |
| **Route name** | `company.visits.index` |
| **Guard** | JWT bearer (`auth:api`); account must be `active` |
| **Allowed roles** | Company (`user_type: company`) |
| **Status codes** | `200 OK`, `401 Unauthorized` |

**Headers:**
- `Accept: application/json`
- `Content-Type: application/json`
- `Accept-Language: {{locale}}`

**Payload:**
No request body. Use the documented query parameters.

**Query parameters:**
- `scope` — `active` (non-terminal orders) or `history` (`confirmed`/`cancelled`) (optional)
- `status` — Filter to one exact order status, or `current` as an alias for "every status except cancelled/confirmed" (optional)
- `per_page` — Items per page, 1–100, default 15 (optional)

**Example Success Response:**

*{ 200 OK — OK }*
```json
{
    "status": "success",
    "message": "Visits retrieved successfully.",
    "data": {
        "data": [
            {
                "id": 64,
                "uuid": "3f46ab7a-e7d5-47e1-8ff9-8feae7281da3",
                "order_number": "ORD-260823-SZKV",
                "status": "pending",
                "scheduled_date": null,
                "total_amount": "165.73",
                "items": [
                    {
                        "id": 173,
                        "service_name": "Furniture Assembly",
                        "pricing_type": "fixed",
                        "unit_price": "0.00",
                        "quantity": 2,
                        "line_total": "0.00",
                        "is_quoted": false,
                        "request_description": null,
                        "request_media_url": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
                    }
                ],
                "created_at": "2026-08-23T11:18:34+00:00"
            }
        ],
        "links": {
            "first": "http://localhost/api/v1/company/visits?page=1",
            "last": "http://localhost/api/v1/company/visits?page=1",
            "prev": null,
            "next": null
        },
        "meta": {
            "current_page": 1,
            "from": 1,
            "last_page": 1,
            "per_page": 15,
            "to": 1,
            "total": 1
        }
    }
}
```

**Actual Error Response(s):**

*{ 401 Unauthorized — 401 Unauthenticated }*
```json
{
    "status": "fail",
    "message": "Unauthenticated, you have to login first",
    "data": null
}
```

**What happens next:** Same order records as Orders & Jobs — Lifecycle; use `GET /company/orders/:id` for full details or the lifecycle actions (accept-price, cancel, etc.) there.

---
