> **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.

# Accounts — Flutter API handoff

**Source of truth:** GitLab `alalmiyalhura/outlet`, `main`, `modules/Accounts/Routes/api.php` plus the named controllers, request validators, `AccountViews`, and domain exceptions. **Scope:** all 17 app/public Accounts routes. Admin routes belong in `dashboard/accounts.md`. Prefix all routes with `/api/v1`. This is a code-derived contract, **not** evidence of staging execution.

## Shared integration contract

- `GET /sellers/{id}` is public, throttled `120/min`. Every other endpoint below requires `Authorization: Bearer <sanctum-token>`.
- Responses generally use `{ "data": ... }`. Account/address/seller mutations additionally use a top-level localized `message`; seller setup may include `notice`. Address collection responses contain `meta`.
- Errors use `{ "error": { "code": "...", "message": "localized text", "request_id": "...", "details": ... } }`. Validation is HTTP 422; unauthenticated 401; missing/other user's address 404. Do not show raw national ID or IBAN after saving.
- Server provides localized display labels; use `name`, `label`, `message` and other text returned, rather than reproducing business wording in Flutter.

## Endpoint index

| # | Method | Path | Result | Access |
|---|---|---|---|---|
| 1 | GET | `/sellers/{id}` | Public seller profile | Guest |
| 2 | GET | `/me/account` | Account summary | Auth |
| 3 | PATCH | `/me/account` | Edit account | Auth |
| 4 | GET | `/me/deletion` | Deletion eligibility | Auth |
| 5 | GET | `/me/addresses` | Address list | Auth |
| 6 | POST | `/me/addresses` | Add address | Auth |
| 7 | GET | `/me/addresses/{id}` | Address details | Auth |
| 8 | PUT | `/me/addresses/{id}` | Edit address | Auth |
| 9 | DELETE | `/me/addresses/{id}` | Remove address; returns list | Auth |
| 10 | POST | `/me/addresses/{id}/default` | Set default; returns list | Auth |
| 11 | POST | `/me/addresses/{id}/sales-pickup` | Set pickup; returns list | Auth |
| 12 | GET | `/me/seller-profile` | Seller setup state | Auth |
| 13 | PUT | `/me/seller-profile` | Complete seller setup | Auth |
| 14 | PUT | `/me/seller-profile/bank` | Update payout bank | Auth |
| 15 | POST | `/me/seller-profile/terms` | Accept terms | Auth |
| 16 | GET | `/banks/resolve` | Validate/identify IBAN | Auth |
| 17 | GET | `/banks` | Supported banks | Auth |

## Shared response objects — field tables

### Account summary (`GET/PATCH /me/account` → `data`)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Current user ID |
| `name`, `first_name`, `initial` | string | Display and abbreviated names |
| `avatar_url` | string/null | Avatar URL |
| `phone` | object/null | `number`, `formatted`, `masked`, `last4`, `short_masked`: strings; private account only |
| `city` | object/null | Localized city, typically `id` and `name` |
| `profile` | object | `complete:boolean`, `missing:Requirement[]` |
| `member_since` | ISO-8601 string/null | Account membership date |
| `member_since_year` | integer/null | Year |
| `member_since_label` | string/null | Localized display text |
| `addresses` | object | `count:integer`, `default:AddressBrief/null` |
| `seller` | SellerBrief | Seller readiness and masked payout |
| `listings` | object/null | `count:integer`, `row_value:string`; null if provider not registered |

### AddressBrief and AddressDetail

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Address ID |
| `label` | `home \| work \| other` | Address type |
| `label_name` | string | Localized display label |
| `custom_label` | string/null | User-specified name for `other` |
| `city` | object/null | Localized city (`id`, `name`) |
| `detail`, `summary` | string | Raw detailed address and formatted one-line summary |
| `is_default`, `is_sales_pickup` | boolean | Current flags |
| `courier_note` | string/null | AddressDetail only: uncovered delivery city warning |
| `can_delete`, `can_set_default`, `sales_pickup_locked` | boolean | AddressDetail server-computed actions |
| `delete_blocked` | object/null | `{code:string,message:string}` when deletion forbidden |
| `delete_sheet` | object/null | `{title,body,confirm,dismiss}` localized strings |
| `created_at`, `updated_at` | ISO-8601 string/null | AddressDetail timestamps |

### SellerBrief / SellerProfile (`data`)

| Field | Type | Meaning |
|---|---|---|
| `is_seller`, `ready_to_sell` | boolean | Setup completed and current eligibility |
| `missing` | Requirement[] | `{key:string,label:string}` |
| `pickup_address` | AddressBrief/null | Current sales pickup |
| `payout_account` | object/null | `iban_masked`, `iban_last4`, `holder_name`, `bank:{code,name}`, `updated_at` |
| `pickup_address_suggestion` | AddressBrief/null | SellerProfile only; preferred address for form |
| `pickup_note` | string/null | Courier coverage warning |
| `holder_name_default` | string/null | Prefill for bank holder |
| `national_id` | object/null | `{masked:string,kind:string}`; never full ID |
| `national_id_editable` | boolean | Whether support unlock allows edit |
| `iban_on_file`, `iban_required` | boolean | Conditional setup requirements |
| `setup_completed_at` | ISO-8601 string/null | Completion timestamp |
| `terms` | object | `current_version`, `accepted_version`, `accepted_at`, `accepted:boolean`, `page_slug` |

### Public seller profile (`GET /sellers/{id}`)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Seller user ID |
| `display_name`, `initial` | string | Public name |
| `avatar_url` | string/null | Public avatar |
| `city` | object/null | Localized city |
| `member_since_year` | integer/null | Registration year |
| `member_since_label`, `meta_line` | string | Localized seller header texts |
| `rating_avg` | number/null | Average rating |
| `rating_count`, `listed_count` | integer | Review count and visible listings |
| `rating` | object | `average:string/null`, `average_label:string/null`, `count:int`, `count_label:string`, `stars_filled:int`, `empty:bool`, `empty_text:string/null`, `label:string` |

## 1. GET `/sellers/{id}` — public seller

**Path:** `id` positive numeric seller user ID. **Body/query:** none. **200:** `{ "data": PublicSellerProfile }` as table above. **404:** `seller_not_found`. Seller phone, national ID and IBAN are deliberately absent.

## 2. GET `/me/account` — own profile

**Request:** no body/query. **200:** `{ "data": AccountSummary }`. The service ensures a market profile exists before presenting the response. Never assume `seller.ready_to_sell` equals `seller.is_seller`.

## 3. PATCH `/me/account` — edit profile

| Request field | Type | Required | Validation / behavior |
|---|---|---|---|
| `name` | string | No (`sometimes`) | Length 2–120 |
| `city_id` | integer | No (`sometimes`) | At least 1; domain checks city availability |

**200:** `{ "data": AccountSummary, "message": "localized saved toast" }`. Changing the phone number is **not** supported here; use Identity OTP flow. Example request: `{ "name": "Sara Ahmed", "city_id": 1 }`.

## 4. GET `/me/deletion` — deletion conditions

**200:** `data` fields:

| Field | Type | Meaning |
|---|---|---|
| `can_delete` | boolean | All server conditions met |
| `blockers` | string[] | Blocking condition keys |
| `title`, `headline`, `body`, `conditions_title`, `notice` | string | Localized page content |
| `conditions` | object[] | Each `{key,met:boolean,title,detail,count:int,amount:{amount:string,currency:string}/null,action:{label,screen}/null}` |
| `confirmation` | object | `{method:"password",label,placeholder}` |
| `submit` | object | `{label,enabled:boolean,method:"POST",endpoint:"/api/v1/me/deletion"}` |
| `blocked_message` | string/null | Shown when blockers exist |
| `confirm_sheet` | object | `{title,body,confirm,cancel}` |

**Business rules:** checks running orders, open disputes, wallet balance and pending withdrawals. Actual deletion is `POST /me/deletion` in **Identity**, not this module; do not invoke deletion when `can_delete=false`.

## 5. GET `/me/addresses` — address list

**200:** `{ "data": AddressDetail[], "meta": {"count":int,"max":int,"can_add":bool,"keep_one_address":bool} }`. No pagination. `max` and `keep_one_address` come from live account policy. Addresses are always caller-scoped.

## 6. POST `/me/addresses` — create

| Request field | Type | Required | Validation |
|---|---|---|---|
| `label` | enum string | Yes | `home`, `work`, `other` |
| `custom_label` | string/null | If `label=other` | Max 20; nonempty for other |
| `city_id` | integer | Yes | Min 1; domain checks city availability |
| `detail` | string | Yes | Domain minimum from policy; maximum 500 characters |
| `is_default` | boolean | No | Optional default flag |
| `is_sales_pickup` | boolean | No | Optional seller pickup flag; subject to coverage rules |

**Example:**
```json
{"label":"home","city_id":1,"detail":"District, street, building 12","is_default":true}
```
**201:** `{ "data": AddressDetail, "message": "localized address added" }`. Possible 422 codes include `address_limit_reached`, `invalid_address_label`, `address_detail_too_short`, `address_detail_too_long`, `city_not_available`, `pickup_city_not_covered`.

## 7. GET `/me/addresses/{id}` — address details

**Path:** `id` numeric. **200:** `{ "data": AddressDetail }`. **404:** `address_not_found`, including another user's address.

## 8. PUT `/me/addresses/{id}` — update

**Path:** `id` numeric. **Body:** same fields and validation as POST (full replacement semantics for required fields). **200:** `{ "data": AddressDetail, "message": "localized address saved" }`. **404:** `address_not_found`. Respect `sales_pickup_locked` and server business errors.

## 9. DELETE `/me/addresses/{id}` — remove

**Body:** none. **200:** updated `{ "data": AddressDetail[], "meta": AddressListMeta, "message": "localized address deleted" }`, **not 204**. **404:** `address_not_found`. **422:** `last_address` or `sales_pickup_address_required` when applicable.

## 10. POST `/me/addresses/{id}/default` — set default

**Body:** none. **200:** updated address collection plus `meta` and localized `message`, same structure as GET address list. The UI should refresh the whole list from the response.

## 11. POST `/me/addresses/{id}/sales-pickup` — set seller pickup

**Body:** none. **200:** updated address collection plus `meta` and localized `message`. **422:** can include `pickup_city_not_covered` if the address cannot serve as courier pickup. This is different from seller setup's nonblocking direct-delivery notice.

## 12. GET `/me/seller-profile` — seller setup

**200:** `{ "data": SellerProfile }` (shared table). **Headers:** `Cache-Control: no-store`. Sensitive identifiers are returned only masked. The app must follow `national_id_editable`, `iban_required`, `terms.accepted` and `missing` rather than infer eligibility.

## 13. PUT `/me/seller-profile` — complete seller setup

| Request field | Type | Required | Validation |
|---|---|---|---|
| `national_id` | string | Yes | Max 20; domain checks Saudi ID/iqama 10 digits, starts 1/2, check digit |
| `iban` | string/null | Only when no saved IBAN | Max 40; domain validates SA IBAN and supported bank |
| `account_holder_name` | string/null | No | Max 100; existing name may be reused |
| `pickup_address_id` | integer | Yes | Min 1; must belong to user |
| `accept_terms` | accepted boolean | Yes | Must be true |
| `terms_version` | string/null | No | Max 32; current version enforced by domain |

**Example:**
```json
{"national_id":"<valid 10-digit ID>","iban":"<valid SA IBAN>","account_holder_name":"Sara Ahmed","pickup_address_id":12,"accept_terms":true,"terms_version":"<version from GET seller-profile>"}
```
**200:** `{ "data": SellerProfile, "message": "localized success", "notice": string|null }`; `Cache-Control: no-store`. Notice about an uncovered courier city does not necessarily fail seller setup; direct delivery may still be allowed. Possible 422 codes: `invalid_national_id`, `invalid_iban`, `unknown_bank`, `iban_required`, `national_id_locked`, `selling_terms_not_accepted`, `selling_terms_outdated`.

## 14. PUT `/me/seller-profile/bank` — change payout account

| Request field | Type | Required | Validation |
|---|---|---|---|
| `iban` | string | Yes | Max 40; full value must be reentered |
| `account_holder_name` | string | Yes | Max 100; domain checks minimum/maximum |

**200:** `{ "data": SellerProfile, "message": "localized IBAN saved" }`, `Cache-Control: no-store`. Full IBAN is never echoed; display `data.payout_account.iban_masked`.

## 15. POST `/me/seller-profile/terms` — accept updated terms

| Request field | Type | Required | Validation |
|---|---|---|---|
| `terms_version` | string | Yes | Max 32 |

**200:** `{ "data": SellerProfile, "message": "localized terms accepted" }`, `Cache-Control: no-store`. Compare `terms.accepted_version` with `terms.current_version` before allowing seller actions.

## 16. GET `/banks/resolve` — interactive IBAN helper

| Query field | Type | Required | Validation |
|---|---|---|---|
| `iban` | string | Yes | Max 40 |

**200:** `data`:

| Field | Type | Meaning |
|---|---|---|
| `complete` | boolean | Enough digits for final check |
| `valid` | boolean/null | Null while incomplete; true/false after full check |
| `error` | string/null | `invalid_iban`, `unknown_bank`, or null |
| `error_message`, `row_text` | string/null | Localized feedback; row may be bank name |
| `tone` | `error \| normal \| null` | UI state |
| `bank` | object/null | `{code:string,name:string}` |
| `iban_masked` | string/null | Masked full valid IBAN |
| `digits_entered`, `digits_required` | integer | Saudi IBAN digits count; required 22 |

**Important:** Invalid/unknown IBAN is reported **inside a 200 response** for this helper, not necessarily an HTTP error. Partial IBAN returns `complete:false`, `valid:null` unless malformed. The endpoint has its own named throttle.

## 17. GET `/banks` — active supported banks

**Body/query:** none. **200:** `{ "data": [{"code":"<bank code>","name":"<localized bank name>"}] }`. Only active banks, sorted by code.

## Errors and Flutter handling

| HTTP | Codes / examples | Recommended handling |
|---|---|---|
| 401 | `unauthenticated` | Sign-in flow |
| 404 | `address_not_found`, `seller_not_found` | Not found / inaccessible |
| 422 | `validation_failed` | Render `error.details` per input |
| 422 | `invalid_national_id`, `invalid_iban`, `unknown_bank`, `selling_terms_outdated` | Use localized `error.message` and refresh server state |
| 422 | `address_limit_reached`, `last_address`, `sales_pickup_address_required`, `pickup_city_not_covered` | Explain business restriction |
| 429 | `too_many_attempts` | Respect retry headers/details |

**Implementation notes:** Never log full `national_id` or `iban`; never persist these values in client diagnostics. Use server-computed `can_delete`, `can_add`, `ready_to_sell`, and address flags. Refresh account/seller state after writes. The API does not return an unmasked stored IBAN.

## Verified source map

- Routes: `modules/Accounts/Routes/api.php`
- Controllers: `PublicSellerController`, `MyAccountController`, `AccountDeletionController`, `AddressController`, `SellerProfileController`, `BankController`
- Requests: `UpdateAccountRequest`, `AddressRequest`, `SellerSetupRequest`, `BankDetailsRequest`
- Presenters: `AccountViews`, `LangSellerRatingLabels`
- Domain: `AddressDetails`, `AccountsNotFound`, `AccountsRuleViolation`

**Verification status:** 17/17 app routes mapped to source-defined request/response shapes. Staging integration tests, auth edge cases and actual environment policy values **not executed**.
