> **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 — Flutter API (controller + presenter verified)

Source: GitLab `alalmiyalhura/outlet` main: `modules/Disputes/Routes/api.php`, `Interfaces/Http/Controllers/DisputeController.php`, `Presenters/{DisputeViews,ReportFormView,AdminPage}.php`. Base `/api/v1`. All seven endpoints require `Authorization: Bearer <token>` (`auth:sanctum`); errors localized by `LocalizeDisputeErrors`. `ref` path matches `[A-Za-z]{3}-?[0-9]{1,12}`. Buyer/seller ownership enforced by controller; unauthorized record access returns not found rather than revealing records. Examples below are **illustrative**, not runtime captures. Strings localized by request locale.

## Endpoint matrix

| Method | URL | Purpose | Success | Body/query |
|---|---|---|---|---|
| GET | `/dispute-reasons` | Active reason choices | 200 | none |
| GET | `/orders/{ref}/disputes/new` | Buyer report form + eligibility | 200 | path order ref |
| POST | `/orders/{ref}/disputes` | Buyer creates dispute | 201 | `reason`, `text`, `photos` |
| GET | `/orders/{ref}/dispute` | Latest dispute banner for participant | 200 | path order ref |
| GET | `/disputes` | My buyer/seller disputes | 200 | `role`, `group`, `per_page`, `page` |
| GET | `/disputes/{ref}` | Full dispute detail | 200 | path dispute ref |
| POST | `/disputes/{ref}/response` | Seller statement | 201 if changed, otherwise 200 | `text`, `photos` |

## 1. GET `/dispute-reasons`

Response `200` envelope `{ "data": [ ... ] }`; each array entry:

| Field | Type | Meaning |
|---|---|---|
| `code` | string | Reason identifier to send in `reason` |
| `label` | string | Localized title |
| `description` | string | Localized explanation (possibly empty) |
| `types` | string[] | Dispute types for which reason applies |

```json
{"data":[{"code":"not_received","label":"Illustrative reason","description":"Illustrative description","types":["not_arrived"]}]}
```
Reason codes and names are database-configured: **do not hardcode the illustrative code**. Only active records returned, sorted by `sort`, then `id`.

## 2. GET `/orders/{ref}/disputes/new`

Buyer-only report form. No query/body. Response `200` is `{ "data": { ... } }` with the following exact presenter keys:

| Field | Type | Meaning |
|---|---|---|
| `title` | string | Localized screen heading |
| `can_open` | boolean | Server-calculated eligibility |
| `blocked` | object/null | `code:string`, `message:string`, `dispute_ref:string/null`, `next:string`, `endpoint:string` |
| `type` | object/null | `{value:string,label:string}` |
| `window_ends_at` | ISO date-time/null | Reporting deadline |
| `order` | object | `ref`, `label`, `item_title`, `image_url`, `alt`, `meta`, `size`, `status:{value,label,tone}` |
| `question` | string | Heading above reason choices |
| `reasons` | object[] | `{code,label,description,enabled:boolean}` |
| `default_reason` | string/null | Auto-selected only when exactly one reason is enabled |
| `hint` | string/null | Special guidance, e.g. not arrived |
| `text` | object | `{label:string,max:int,required:boolean,counter:string}` |
| `photos` | object | `{label,max,limit_label,add_label,note,limit_toast,upload_endpoint}` |
| `after` | object | `{title:string,points:string[]}` |
| `submit` | object | `{label,method:"POST",endpoint,enabled:boolean,reason_required}` |

**Implementation:** use `can_open`, `reasons[].enabled`, `default_reason`, `text.required`, and limits from response. If `blocked.next="dispute"`, follow `blocked.endpoint`. No client-side eligibility guessing.

## 3. POST `/orders/{ref}/disputes`

Headers: bearer token, `Content-Type: application/json`; `Idempotency-Key` recommended for retries. Middleware `throttle:20,1` and `idempotent`.

| JSON field | Type | Controller validation |
|---|---|---|
| `reason` | string/null | nullable; max 40 chars; domain checks active reason and applicability |
| `text` | string/null | nullable; max 5000 chars; domain may require it per settings |
| `photos` | string[] | optional array max 10; each `^med_[a-f0-9]{32}$`; domain may enforce lower configured limit |

```json
{"reason":"<code from GET report form>","text":"Item issue description","photos":["med_0123456789abcdef0123456789abcdef"]}
```

Response `201` `{ "data": <DisputeDetail> }` where `DisputeDetail` is the full shape in endpoint 6. The buyer confirmation screen uses `data.confirmation` (non-null for buyer). One-open-dispute/order eligibility and ownership enforced server-side. Photos must be uploaded separately through `/api/v1/media` to obtain media refs.

## 4. GET `/orders/{ref}/dispute`

Latest dispute for order, visible only to buyer/seller. Response `200`:

| Field | Type |
|---|---|
| `ref`, `order_ref`, `role` | string (`role` buyer/seller) |
| `status` | `{value:string,label:string,tone:string}` |
| `reason` | `{code:string,label:string}` |
| `extra`, `title` | localized string |
| `decided` | boolean |
| `outcome` | string/null |
| `action` | `{key:"dispute",label:string,method:"GET",endpoint:string}` |

```json
{"data":{"ref":"DSP-981","order_ref":"OUT-123","role":"buyer","status":{"value":"open","label":"Illustrative open label","tone":"attention"},"reason":{"code":"example","label":"Illustrative reason"},"extra":"Illustrative summary","title":"Illustrative title","decided":false,"outcome":null,"action":{"key":"dispute","label":"Details","method":"GET","endpoint":"/api/v1/disputes/DSP-981"}}}
```

## 5. GET `/disputes`

| Query | Type | Allowed/default |
|---|---|---|
| `role` | enum | `buyer`, `seller`, `all` (default `all`) |
| `group` | enum | `all` (default), `pending`, `decided` |
| `per_page` | integer | 1..50, default 15 |
| `page` | integer | Laravel paginator page |

`pending` means statuses `open` or `under_review`; `decided` excludes those. Sorted newest `opened_at`, then `id`. Response is **top-level paginated JSON**, not `{data:{...}}`:

```json
{"data":[{"ref":"DSP-981","order_ref":"OUT-123","role":"buyer","reason":{"code":"example","label":"Illustrative reason"},"status":{"value":"open","label":"Open","tone":"attention"},"summary":"Illustrative summary","opened_at":"2026-11-22T10:00:00+00:00","opened_label":"Illustrative date","decided_at":null,"item_title":"Illustrative item","image_url":null,"endpoint":"/api/v1/disputes/DSP-981"}],"filters":{"roles":[{"key":"buyer","label":"Buyer"},{"key":"seller","label":"Seller"}],"groups":[{"key":"all","label":"All"},{"key":"pending","label":"Pending"},{"key":"decided","label":"Decided"}]},"empty":"Illustrative empty state","links":{"first":"...","last":"...","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":15,"to":1,"total":1}}
```
`data[]` row field types: `ref/order_ref/role/summary/opened_label/endpoint` strings; `reason` object; `status` object; `opened_at` ISO string; `decided_at`, `item_title`, `image_url` nullable strings. `filters`, `empty`, `links`, `meta` from `AdminPage::respond`.

## 6. GET `/disputes/{ref}`

Response `200`: `{ "data": <DisputeDetail> }`. **Full top-level field contract from `DisputeViews::show`:**

| Field | Type | Nested contract |
|---|---|---|
| `ref`, `role` | string | role `buyer`/`seller` |
| `type` | object | `{value,label}` strings |
| `header` | object | `{title,sub}` strings |
| `opened_at`, `opened_label` | string | ISO datetime / localized text |
| `status` | object | `{value,label,tone}` strings |
| `status_card` | object | `{title,sub,tone}` strings |
| `timeline` | object | `{title:string,steps:[{key,label,sub:string/null,state,at:string/null}]}` |
| `decision` | object/null | `{title,verdict,outcome:{value,label},decided_at,decided_label,amount,return_shipping}`; amount nullable `{label,value,note}`; return_shipping nullable `{payer,label,cost}` |
| `report` | object | `{title,reason:{code,label,title},text,text_title,photos,photos_title}` |
| `seller_statement` | object/null | `{title,text,photos,at,at_label}` |
| `respond_form` | object/null | `{title,sub,text_max:int,photos_max:int,submit,method:"POST",endpoint}` |
| `order` | object | `{title,ref,item_title,image_url,alt,meta,total,status,endpoint}` |
| `note` | string | localized guidance |
| `actions` | object[] | `{key,label,style,method:string/null,endpoint:string/null,...}`; chat includes `order_ref`, `read_only` |
| `can` | object | `{chat:boolean,respond:boolean,view_order:boolean}` |
| `confirmation` | object/null | Buyer only: `{title,sub,rows:[{key,label,value}],next_title,steps:[{n,title,sub}],actions:[...]}` |

`photos` are presenter-generated media objects; their nested shape is intentionally **not asserted** without reviewing `DisputeTexts::photos`. `can.respond` is true only for seller when statements enabled, status open/under_review, and no previous statement. Use server-supplied `actions` and `can`, not inferred status transitions.

## 7. POST `/disputes/{ref}/response`

Seller statement; bearer token, `Idempotency-Key` recommended; throttle 20/min.

| JSON field | Type | Validation |
|---|---|---|
| `text` | string/null | max 5000 |
| `photos` | string[] | optional max 10; each media ref `^med_[a-f0-9]{32}$` |

```json
{"text":"Seller's explanation","photos":[]}
```

Response `201` if changed, `200` if not changed; both use:

```json
{"data":{"changed":true,"message":"Illustrative localized success text","dispute":{"ref":"DSP-981","role":"seller","type":{"value":"not_arrived","label":"Illustrative type"}}}}
```
`dispute` in the example is **abbreviated**; actual response contains the **entire `DisputeDetail`** described in endpoint 6. Domain may reject non-seller, resolved dispute, or repeated statement; exact localized error payloads remain unverified.

## Client integration checklist

- Read allowed reasons and limits from form endpoint; never hardcode configured reason codes.
- Respect `can_open`/`blocked` and `can.respond`/`actions` flags.
- Media uploads use `/api/v1/media` and return `med_...` refs, not raw image URLs in POST bodies.
- Show `data.confirmation` on successful buyer submission.
- Handle `401`, `404` (including inaccessible records), `422` and throttling (`429`); exact localized error envelope pending middleware review.
- `Idempotency-Key` on creation/statement POST requests; do not retry blindly without it.
