> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Disputes — Dashboard API (source-reviewed)

Base path `/api/v1`. All endpoints require `Authorization: Bearer <Sanctum token>`. Permission is enforced individually on each route. JSON strings intended for display are localized by the Disputes middleware. Reviewed against GitLab `main` controllers and routes; illustrative examples below are **not runtime captures**.

## Common response contracts

| Shape | Fields |
|---|---|
| `Reason` | `id: integer`, `code: string`, `name: locale→string map`, `description: locale map|null`, `outcome_hint: locale map|null`, `types: string[]`, `sort: integer`, `is_active: boolean`, `disputes_count: integer`, `created_at/updated_at: ISO8601|null` |
| `DisputeSettings` | `images_max: integer`, `text_max: integer`, `text_required: boolean`, `seller_statements: boolean`, `review_sla_hours: integer`, `return_sla_days: integer`, `alert_recipients: integer[]` (from settings `toArray()`) |
| `Audit` | `id: integer`, `event: string`, `subject: string`, `subject_id: integer`, `old_values/new_values: object`, `actor_id: integer|null`, `actor: {id,name}|null`, `tags`, `at: ISO8601|null` |
| Pagination | Top-level `data`, `links: {first,last,prev,next}`, `meta: {current_page,from,last_page,per_page,to,total}`. `GET /admin/disputes` also has `summary` and `meta.filters`. |

## Endpoint contracts

### 1. `GET /api/v1/admin/disputes/reasons`

**Permission:** `disputes.reasons.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | Query: `filter[active]` = 0/1/true/false; `filter[type]` = valid dispute type. |

| Response | Contract |
|---|---|
| Success | 200 `data: Reason[]` including `disputes_count`. No pagination. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 2. `POST /api/v1/admin/disputes/reasons`

**Permission:** `disputes.reasons.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | JSON: `code` required string ≤40 (domain pattern `^[a-z][a-z0-9_]{1,39}$`); `name` required localized map; `types` required nonempty array of DisputeType; `description`, `outcome_hint` nullable localized maps; `sort` integer 0..1000000; `is_active` boolean. |

| Response | Contract |
|---|---|
| Success | 201 `data: Reason`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 3. `GET /api/v1/admin/disputes/reasons/{id}`

**Permission:** `disputes.reasons.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | `id`: integer reason ID. |

| Response | Contract |
|---|---|
| Success | 200 `data: Reason` with actual `disputes_count`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 4. `PATCH /api/v1/admin/disputes/reasons/{id}`

**Permission:** `disputes.reasons.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | Partial JSON: `name`, `types`, `description`, `outcome_hint`, `sort`. `code` and `is_active` prohibited; use activation endpoints. |

| Response | Contract |
|---|---|
| Success | 200 `data: Reason`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 5. `POST /api/v1/admin/disputes/reasons/{id}/activate`

**Permission:** `disputes.reasons.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | No body. `id`: integer. |

| Response | Contract |
|---|---|
| Success | 200 `data: {changed: boolean, ...Reason}`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 6. `POST /api/v1/admin/disputes/reasons/{id}/deactivate`

**Permission:** `disputes.reasons.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | No body. Existing disputes retain their original reason snapshot. |

| Response | Contract |
|---|---|
| Success | 200 `data: {changed: boolean, ...Reason}`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 7. `GET /api/v1/admin/disputes/reasons/{id}/history`

**Permission:** `disputes.reasons.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | `per_page` optional integer 1..100, default 25. |

| Response | Contract |
|---|---|
| Success | 200 top-level `data: Audit[]`, `links`, `meta`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 8. `GET /api/v1/admin/disputes/settings`

**Permission:** `settings.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | No body. |

| Response | Contract |
|---|---|
| Success | 200 `data: DisputeSettings`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 9. `PATCH /api/v1/admin/disputes/settings`

**Permission:** `settings.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | Partial JSON: `images_max` 1..PHOTOS_HARD_MAX; `text_max` 50..5000; `text_required`, `seller_statements` booleans; `review_sla_hours` 1..720; `return_sla_days` 1..90; `alert_recipients` distinct existing user IDs max 50; `reason` optional string ≤300 (audit reason). |

| Response | Contract |
|---|---|
| Success | 200 `data: DisputeSettings`. Changes apply to subsequent actions. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 10. `GET /api/v1/admin/disputes/settings/history`

**Permission:** `settings.manage`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | `per_page` 1..100, default 25. |

| Response | Contract |
|---|---|
| Success | 200 top-level `data: Audit[]`, `links`, `meta`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 11. `GET /api/v1/admin/disputes`

**Permission:** `disputes.view`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | Query `filter[status|type|reason|outcome]` (single or list supported by ListQuery); `filter[buyer_id|seller_id|decided_by]` positive integer; `filter[pending|overdue|return_overdue|has_photos|has_seller_statement]` boolean-like; `filter[search]`; amount/refund ranges, opened/decided date ranges; `sort` = opened_at, decided_at, amount, ref, status, id (prefix `-` descending); pagination via `per_page`. |

| Response | Contract |
|---|---|
| Success | 200 top-level `data: DisputeRow[]`, `summary`, `links`, `meta` (including available filters). Default sort newest opened unless only pending selected. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 12. `GET /api/v1/admin/disputes/{ref}`

**Permission:** `disputes.view`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | `ref`: dispute reference, pattern `[A-Za-z]{3}-?[0-9]{1,12}`. |

| Response | Contract |
|---|---|
| Success | 200 `data: AdminDisputeDetail`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 13. `GET /api/v1/admin/disputes/{ref}/history`

**Permission:** `disputes.view`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | `per_page` integer 1..100, default 25. |

| Response | Contract |
|---|---|
| Success | 200 top-level `data: Audit[]`, `links`, `meta`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 14. `POST /api/v1/admin/disputes/{ref}/review`

**Permission:** `disputes.review`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | No JSON body required. |

| Response | Contract |
|---|---|
| Success | 200 `data: {changed: boolean, ...AdminDisputeDetail}`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 15. `POST /api/v1/admin/disputes/{ref}/decide`

**Permission:** `disputes.decide`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | JSON `outcome` required DisputeOutcome enum; `verdict` required string with Decision::VERDICT_MIN..VERDICT_MAX. |

| Response | Contract |
|---|---|
| Success | 200 `data: {changed: boolean, ...AdminDisputeDetail}`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 16. `POST /api/v1/admin/disputes/{ref}/return-confirmed`

**Permission:** `disputes.confirm_return`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | JSON optional `note` nullable string ≤400. |

| Response | Contract |
|---|---|
| Success | 200 `data: {changed: boolean, ...AdminDisputeDetail}`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 17. `POST /api/v1/admin/disputes/{ref}/return-failed`

**Permission:** `disputes.decide`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | JSON `reason` required string with Dispute::RETURN_FAILED_REASON_MIN..RETURN_FAILED_REASON_MAX. This completes the sale for seller when return fails. |

| Response | Contract |
|---|---|
| Success | 200 `data: {changed: boolean, ...AdminDisputeDetail}`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

### 18. `POST /api/v1/admin/disputes/{ref}/notes`

**Permission:** `disputes.notes`. **Authentication:** Sanctum.

| Request field / rule | Type and validation |
|---|---|
| Input | JSON `body` nullable string ≤DisputeActions::NOTE_MAX, required if no `suspension_reference`; `suspension_reference` optional string ≤DisputeActions::REFERENCE_MAX. |

| Response | Contract |
|---|---|
| Success | 201 `data: {note_id: integer, ...AdminDisputeDetail}`. |
| Errors | `401` unauthenticated; `403` insufficient permission; `422` invalid input; `404` for nonexistent record/ref; domain state conflicts may return a localized business error (exact HTTP mapping requires middleware verification). |

## Illustrative JSON examples (not recorded responses)

**Create reason — request**
```json
{"code":"damaged_item","name":{"ar":"منتج تالف","en":"Damaged item"},"types":["item_issue"],"sort":10,"is_active":true}
```
**Note:** `item_issue` here is illustrative; check `DisputeType::values()` before using any type in production.

**List response — structural example**
```json
{"data":[],"summary":{"by_status":{},"pending":0,"overdue":0,"awaiting_return":0,"return_overdue":0},"links":{"first":"/api/v1/admin/disputes?page=1","last":"/api/v1/admin/disputes?page=1","prev":null,"next":null},"meta":{"current_page":1,"from":null,"last_page":1,"per_page":15,"to":null,"total":0,"filters":{"statuses":[],"types":[],"outcomes":[],"reasons":[]}}}
```

**Decision — request**
```json
{"outcome":"seller","verdict":"Reviewed evidence and decided in favor of the seller."}
```
**Note:** outcome values and verdict length must be confirmed against `DisputeOutcome` and `Decision` constants; example is explanatory only.

## Frontend behavior and boundaries

- Show controls only when the current user has the relevant permission; the backend is authoritative.
- A repeated state-changing action may return `changed: false`; treat it as a successful no-op, not a failure.
- Reason records are deactivated rather than deleted; existing disputes keep historical reason data.
- For audit pages use the top-level paginated shape, not `data.data`.
- The `return-failed` action is a distinct business transition from `return-confirmed`.

## Source of truth

- `modules/Disputes/Routes/api.php`
- `modules/Disputes/Interfaces/Http/Controllers/Admin/ReasonAdminController.php`
- `modules/Disputes/Interfaces/Http/Controllers/Admin/DisputeSettingsController.php`
- `modules/Disputes/Interfaces/Http/Controllers/Admin/DisputeAdminController.php`
- `modules/Disputes/Interfaces/Http/Presenters/AdminPage.php`

## Verification gaps

- Exact `AdminDisputeDetail` and queue row fields require review of `AdminDisputeViews.php`.
- Exact enum lists and domain minimum/maximum constants require checking their class definitions.
- HTTP status and body for localized business exceptions require checking the error middleware and exception handler.
