# DALSEEN — Backend Endpoint Mapping (consolidated catalog)

> **Verified accurate:** 2026-05-02 — D1–D11 references now resolve via the canonical `docs/handoff/DECISIONS.md §5a` (created 2026-05-02). Header contract, status-tag legend, and per-flow doc links all hold. Per-row endpoint statuses are accurate as of the original write-up; for the **current** state of any specific endpoint, cross-check the matching SCREENS-INVENTORY-* doc and `docs/openapi/openapi.yaml`.
> **Status:** active consolidated catalog; the index every other handoff doc points back to.

> **Purpose.** One alphabetised, status-tagged catalog of every API endpoint
> the prototype calls — across **POS**, **Onboarding**, **Shifts/Day-close**,
> **Accounting**, and the GL bridges that auto-post journal entries.
>
> **This is the index.** Each row points to the per-flow handoff doc that
> documents request body, response shape, error envelopes, and Cursor
> checklist for that endpoint. Don't duplicate that detail here — link to
> it. When the same endpoint is referenced by two flows, both source docs
> are listed.
>
> **Audience.** Cursor (backend), and any reviewer who wants a single
> place to ask *"is endpoint X covered? what's its status? where do I read
> more?"*.
>
> **Companion document.** This file maps **frontend flows → backend
> endpoints**. For the canonical **cross-module route index** — every
> endpoint listed once with D-refs, permissions, and status across all
> modules — see `BACKEND-ENDPOINT-CATALOG.md` in the backend repo
> (`docs/handoff/BACKEND-ENDPOINT-CATALOG.md`). The two docs are
> complementary: use this one to answer *"what does the UI need?"*; use
> the catalog to answer *"is the route defined?"*.

---

## 0. Conventions

All conventions are inherited from the per-flow handoff docs and the
**D1–D11** decision register:

- **Decision register:** `docs/handoff/DECISIONS.md §5a` (canonical D1–D11 list).
- **Brief recap:** `docs/handoff/README.md` (the table of D1–D11 there is
  the on-ramp summary; full text lives in `DECISIONS.md`).
- **Per-endpoint detail:** the four flow docs:
  - `docs/handoff/POS-flow-endpoint-mapping.md`
  - `docs/handoff/onboarding-chain-endpoint-mapping.md`
  - `docs/handoff/shifts-day-close-endpoint-mapping.md`
  - `docs/handoff/ACCOUNTING-AUDIT.md`

**Required headers** (every tenant route, no exceptions):

```http
Authorization:    Bearer {sanctum_token}
Accept:           application/json
Accept-Language:  en | ar
X-Branch-Id:      {branch_ulid}        ← branch-scoped routes
Idempotency-Key:  {uuid v4}            ← every POST/PATCH/DELETE
```

**Response envelopes** (D1):

```json
// Success
{ "data": { ... } | [ ... ], "meta": { "page": 1, "per_page": 25, "total": 137 } }

// Error
{ "error": { "code": "STABLE_CODE", "message_en": "...", "message_ar": "...",
             "fields": { "field_path": ["rule"] } } }
```

**Status legend** (used in the Status column below):

| Symbol | Meaning |
|---|---|
| ✅ | **Postman-verified** — exact path, method, request body, response shape exist in `docs/postman/DALSEEN.postman_collection.json`. Cursor verifies route file matches. |
| ⚠️ | **Inferred** — route exists but example/shape is thin or stale; assumptions are documented in the linked handoff section. Cursor refreshes. |
| 🔧 | **Mismatch** — frontend assumes one shape, backend documents another. Cursor reconciles. |
| ❓ | **Missing** — frontend uses it, backend has no documented endpoint. Spec is a *suggested contract* in the linked handoff section. Cursor adds route + controller + validator + Postman entry + migration. |
| ⛔ | **Frontend-only** — synthetic helper (alias, orchestration, computed). Never goes to backend. Listed for completeness so reviewers don't hunt for a missing endpoint. |

---

## 1. Endpoint catalog (by resource)

Resources are listed alphabetically. Within a resource, routes are ordered
list → detail → write → action.

> **Reading the table.** "Source doc" links the canonical handoff section
> for request/response/errors/Cursor checklist. "Permission" is the
> Laravel permission name the route enforces. "D-refs" lists relevant
> D-decisions that govern the shape.

---

### 1.1 `auth/*` — Authentication

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| POST | `/api/v1/auth/login` | ✅ | (public) | POS §1 | D1, D3, D10A | Returns `{token, user, company, branches:[{id}]}`. MFA gate via `mfa_required`. |
| POST | `/api/v1/auth/logout` | ✅ | `auth:sanctum` | POS §1 | — | Revokes current token. |
| POST | `/api/v1/auth/mfa/verify` | ⚠️ | (token from login) | POS §1.5 | — | Postman has stub; full MFA flow deferred to its own handoff. |

---

### 1.2 `me/*` — Session & current-user context

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/me` | ✅ | `auth:sanctum` | POS §2, Onboarding §2 | D1, D3, D10A | Returns user + company + permissions[] + locale. |
| GET | `/api/v1/me/branches` | ✅ | `auth:sanctum` | POS §3 | D1, D4, D10A | Full branch DTOs with `name_ar`/`name_en`/`code`. |
| GET | `/api/v1/me/setup-progress` | ✅ | `auth:sanctum` | Onboarding §6 | D10 | **Derived, not stored.** Computed per-call from real domain state. |

---

### 1.3 `signup/*` & `setup/*` — Tenant onboarding chain

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| POST | `/api/v1/signup` | ✅ | (public) | Onboarding §1 | D1, D10A | Creates tenant + owner user; returns provisional token. |
| POST | `/api/v1/setup/kyc` | ✅ | `auth:sanctum` | Onboarding §3 | D1, D2, D10 | Tenant KYC payload (CR, VAT cert, IBAN, owner ID). |
| GET | `/api/v1/setup/kyc` | ✅ | `auth:sanctum` | Onboarding §3 | — | Read current KYC submission. |
| POST | `/api/v1/setup/provision` | ⚠️ | `auth:sanctum` | Onboarding §4 | — | Triggers tenant provisioning (DB seed, default COA, etc.). Async; client polls `/me/setup-progress`. |

---

### 1.4 `companies/*` & `branches/*` — Tenant org

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/companies/{id}` | ✅ | `companies.view` | Onboarding §5, Acct-Audit §4 | D1, D10A | |
| PATCH | `/api/v1/companies/{id}` | ✅ | `companies.update` | Acct-Audit §4 | D1, D10A | |
| GET | `/api/v1/companies/{id}/accounting-settings` | ✅ | `accounting.settings.manage` | Acct-Audit §4 | — | FY start, base currency, default VAT rate. |
| PATCH | `/api/v1/companies/{id}/accounting-settings` | ✅ | `accounting.settings.manage` | Acct-Audit §4 | — | |
| GET | `/api/v1/branches` | ✅ | `branches.view` | Onboarding §5 | D1, D10A | List branches for tenant. |
| POST | `/api/v1/branches` | ✅ | `branches.create` | Onboarding §5 | D1, D10A | |
| PATCH | `/api/v1/branches/{id}` | ✅ | `branches.update` | Onboarding §5 | — | |
| POST | `/api/v1/branches/{id}/day-close` | ❓ | `branches.day-close` | Shifts §9 | D5, D6, D8 | Branch-manager EOD rollup. **MISSING.** |

---

### 1.5 `shifts/*` — Cashier shift lifecycle

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/shifts/current?register_id={id}` | ❓ | `shifts.view` | Shifts §2, POS §4 | D9 | Returns `data: null` (NOT 404) when no open shift. **MISSING.** |
| POST | `/api/v1/shifts/open` | ⚠️ | `shifts.open` | Shifts §3, POS §4 | D2 | Postman shows scalar `opening_float`; refresh to Money envelope. |
| POST | `/api/v1/shifts/{id}/cash-movements` | ❓ | `shifts.cash-movements` | Shifts §4 | D2, D5 | Pay-in / pay-out / safe-drop. **MISSING.** |
| GET | `/api/v1/shifts/{id}/x-report` | ❓ | `shifts.x-report` | Shifts §7 | D2 | Mid-shift report. **MISSING** (UI can fall back to client-compute). |
| POST | `/api/v1/shifts/close` | ⚠️ | `shifts.close` | Shifts §8 | D2, D5, D6 | Postman response stub is too thin; expand to full Z-report. |

---

### 1.6 `tenders` — Payment-method catalog

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/tenders` | ✅ | `pos.tenders.view` | POS §4.3 | D5, D10A | Branch-filtered. v1 codes: `cash\|mada\|visa\|mastercard\|applepay\|stcpay\|sadad\|giftcard\|storecredit`. |

---

### 1.7 `sales/*` — POS sale capture & lifecycle

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/sales?from=&to=&branch_id=&cashier_id=&status=&page=&per_page=` | ❓ | `pos.sales.view` | POS §5 | D8 | List/history. **MISSING.** |
| GET | `/api/v1/sales/{id}` | ⚠️ | `pos.sales.view` | POS §5 | D1, D2 | Detail. Postman has it but row shape rule (list⊆detail) is unverified. |
| POST | `/api/v1/sales` | ✅ | `pos.sales.create` | POS §4.4 | D1, D2, D4, D5 | Capture sale. Auto-posts JE (D5). |
| GET | `/api/v1/sales/{id}/receipt?format=html\|pdf` | ⚠️ | `pos.sales.view` | POS §4.5 | D6 | Server-render for share/archive. |
| POST | `/api/v1/sales/{id}/share` | ⚠️ | `pos.sales.share` | POS §4.6 | D7 | v1: `whatsapp\|email`. Returns 202. |
| POST | `/api/v1/sales/{id}/void` | ⚠️ | `pos.sales.void` | Shifts §6 | D5, D6 | Refresh response: include credit-note + JE refs. |
| POST | `/api/v1/sales/{id}/refund` | ❓ | `pos.sales.refund` | Shifts §6 | D11 | Cashier-immediate same-tender refund; **same-shift only**. Cross-shift forces RMA. **MISSING (D11 approved).** |

---

### 1.8 `accounting/*` — General ledger & books

#### 1.8.1 Chart of Accounts

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/chart-of-accounts` | ✅ | `accounting.coa.view` | Acct-Audit §1 (tab 10) | D10A | **PK is `code` (string), not ULID** — only resource that breaks D1. |
| GET | `/api/v1/accounting/chart-of-accounts/{code}` | ✅ | `accounting.coa.view` | Acct-Audit §1 | — | |
| POST | `/api/v1/accounting/chart-of-accounts` | ✅ | `accounting.coa.manage` | Acct-Audit §4 | — | |
| PATCH | `/api/v1/accounting/chart-of-accounts/{code}` | ✅ | `accounting.coa.manage` | Acct-Audit §4 | — | |
| DELETE | `/api/v1/accounting/chart-of-accounts/{code}` | ✅ | `accounting.coa.manage` | Acct-Audit §4 | — | |
| POST | `/api/v1/accounting/chart-of-accounts/import` | ⚠️ | `accounting.coa.manage` | Acct-Audit §4 | — | Body: `{template_id}`. Imports a 25-template Saudi-ready COA. Payload thin in Postman. |

#### 1.8.2 Journal Entries & GL

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/journal-entries` | ✅ | `accounting.journal-entries.view` | Acct-Audit §1 (tab 7) | D1, D2 | |
| GET | `/api/v1/accounting/journal-entries/{id}` | ✅ | `accounting.journal-entries.view` | Acct-Audit §1 | D1, D2 | |
| POST | `/api/v1/accounting/journal-entries` | ✅ | `accounting.journal-entries.create` | Acct-Audit §2.5 | D1, D2, D4, D10 | Manual JE. Σdebits = Σcredits enforced. |
| POST | `/api/v1/accounting/journal-entries/{id}/reverse` | ❓ | `accounting.journal-entries.reverse` | Acct-Audit §2.5, todo #27 | D4 | Returns new JE with `reversal_of_id`. **MISSING.** |
| POST | `/api/v1/accounting/journal-entries/{id}/adjust` | ❓ | `accounting.journal-entries.adjust` | Acct-Audit §2.5, todo #27 | D4 | Opens an adjusting-JE keyed off original. **MISSING.** |
| GET | `/api/v1/accounting/general-ledger?account_code=&from=&to=&branch_id=` | ⚠️ | `accounting.gl.view` | Acct-Audit §1 (tab 8) | D2 | Postman folder exists; query-param contract not exemplified. |

#### 1.8.3 Recurring journals

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/recurring-journals` | ✅ | `accounting.recurring.view` | Acct-Audit §1 (tab 9) | — | |
| GET | `/api/v1/accounting/recurring-journals/{id}` | ✅ | `accounting.recurring.view` | Acct-Audit §1 | — | |
| POST | `/api/v1/accounting/recurring-journals` | ✅ | `accounting.recurring.create` | Acct-Audit §2.5 | D4 | Cadence: `daily\|weekly\|monthly\|quarterly`. |

#### 1.8.4 Invoices & receivables

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/invoices` | ✅ | `accounting.invoices.view` | Acct-Audit §1 (tab 2) | — | |
| GET | `/api/v1/accounting/invoices/{id}` | ✅ | `accounting.invoices.view` | Acct-Audit §1 | — | Polled for `zatca_status` in Phase 2 flow. |
| POST | `/api/v1/accounting/invoices` (`?type=quick`) | ✅ | `accounting.invoices.create` | Acct-Audit §2.1 | D1, D2, D4, D10 | Quick invoice (no QR). |
| POST | `/api/v1/accounting/invoices` (`zatca_phase: 1`) | ✅ | `accounting.invoices.create` + `zatca.phase1.issue` | Acct-Audit §2.1 | D6 | Phase-1 ZATCA (5-field TLV QR, no clearance). |
| POST | `/api/v1/accounting/invoices` (`zatca_phase: 2`) | ⚠️ | `accounting.invoices.create` + `zatca.phase2.clear\|report` | Acct-Audit §2.1, todo #26 | D6 | Async clearance; returns 202; client polls `/invoices/{id}` for `zatca_status: cleared\|rejected`. Polling contract **not exemplified**. |
| GET | `/api/v1/accounting/customer-payments` | ✅ | `accounting.payments.view` | Acct-Audit §1 (tab 3) | D2 | |
| GET | `/api/v1/accounting/customer-payments/{id}` | ✅ | `accounting.payments.view` | Acct-Audit §1 | — | |
| POST | `/api/v1/accounting/customer-payments` | ✅ | `accounting.payments.create` | Acct-Audit §2.1 | D2, D4 | Auto-posts JE: DR Cash/Bank, CR AR. |
| GET | `/api/v1/accounting/credit-notes` | ⚠️ | `accounting.credit-notes.view` | Acct-Audit §2.1 | D6 | |
| POST | `/api/v1/accounting/credit-notes` | ⚠️ | `accounting.credit-notes.create` | Acct-Audit §2.1 | D6 | Refund/return. `reason_code` enum to confirm. **Independent of D11** (POS lane refund); both can fire on one physical return. |

#### 1.8.5 Bills & payables

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/bills` | ✅ | `accounting.bills.view` | Acct-Audit §1 (tab 4) | — | |
| GET | `/api/v1/accounting/bills/{id}` | ✅ | `accounting.bills.view` | Acct-Audit §1 | — | |
| POST | `/api/v1/accounting/bills` | ✅ | `accounting.bills.create` | Acct-Audit §2.2 | D2, D4 | Auto-posts JE: DR Expense + DR VAT-In, CR AP. |
| GET | `/api/v1/accounting/vendor-payments` | ✅ | `accounting.payments.view` | Acct-Audit §1 (tab 5) | — | |
| GET | `/api/v1/accounting/vendor-payments/{id}` | ✅ | `accounting.payments.view` | Acct-Audit §1 | — | |
| POST | `/api/v1/accounting/vendor-payments` | ✅ | `accounting.payments.create` | Acct-Audit §2.2 | D2, D4 | Auto-posts JE: DR AP, CR Cash/Bank. |

#### 1.8.6 Vouchers (cash-book / non-bill cash movements)

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/receipt-vouchers` | ❓ | `accounting.vouchers.view` | Acct-Audit §2.1 | — | **MISSING.** Numbering: `CR-####/MM/YYYY`. |
| POST | `/api/v1/accounting/receipt-vouchers` | ❓ | `accounting.vouchers.create` | Acct-Audit §2.1 | D2, D4 | 8 reasons (customer payment-on-account, owner contribution, refund-from-vendor, loan-in, other-income, misc-cash, bank-deposit, tax-refund). Party type derived from reason. **MISSING.** |
| GET | `/api/v1/accounting/payment-vouchers` | ❓ | `accounting.vouchers.view` | Acct-Audit §2.1 | — | **MISSING.** Numbering: `CP-####/MM/YYYY`. |
| POST | `/api/v1/accounting/payment-vouchers` | ❓ | `accounting.vouchers.create` | Acct-Audit §2.1 | D2, D4 | 8 reasons (pay-vendor-non-bill, owner-draw, refund-to-customer, salary-advance, petty-cash, loan-out, other-expense, tax-payment). Party-aware (vendor/employee/customer/staff/other). **MISSING.** |

#### 1.8.7 Banking

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/bank-accounts` | ✅ | `accounting.bank.view` | Acct-Audit §1 (tab 6) | — | |
| GET | `/api/v1/accounting/bank-transactions?status=matched\|unmatched\|all` | ⚠️ | `accounting.bank.view` | Acct-Audit §1 | — | `?status=` query-param shape unverified. |
| POST | `/api/v1/accounting/bank-transactions/reconcile` *or* `PATCH /bank-transactions/{id}` | ⚠️ | `accounting.bank.reconcile` | Acct-Audit §2.3 | D4 | Cursor picks one shape and documents. |
| GET/POST/PATCH/DELETE | `/api/v1/accounting/bank-rules` | ❓ | `accounting.bank-rules.manage` | Acct-Audit §2.3 | — | **MISSING.** Auto-classify rules. |

#### 1.8.8 VAT & period close

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/vat-returns` | ✅ | `accounting.vat-returns.view` | Acct-Audit §1 (tab 13) | — | |
| GET | `/api/v1/accounting/vat-returns/{id}` | ✅ | `accounting.vat-returns.view` | Acct-Audit §1 | — | Polled for `status` after submit. |
| POST | `/api/v1/accounting/vat-returns` | ⚠️ | `accounting.vat-returns.preview` | Acct-Audit §2.4, todo #26 | D4, D6 | Preview-compute body: `{period: "2026Q2"}`. |
| POST | `/api/v1/accounting/vat-returns/{id}/file` | ⚠️ | `accounting.vat-returns.file` | Acct-Audit §2.4, todo #26 | D4, D6 | Returns **202 Accepted** with `submission_id`; poll `/vat-returns/{id}` for `status: submitted → cleared\|rejected` and `zatca_reference`. Contract **not exemplified**. |
| GET | `/api/v1/accounting/periods` | ✅ | `accounting.periods.view` | Acct-Audit §1 (tab 12) | — | |
| GET | `/api/v1/accounting/periods/{id}` | ✅ | `accounting.periods.view` | Acct-Audit §1 | — | |
| POST | `/api/v1/accounting/periods/{id}/close` | ✅ | `accounting.periods.close` | Acct-Audit §2.4 | D4 | Body: `{confirm: true, force_overrides: []}`. Pre-close checks run server-side. |

#### 1.8.9 Opening balances & dashboard

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/opening-balances` | ⚠️ | `accounting.opening-balances.view` | Acct-Audit §1 (tab 11) | D2 | Single resource per company. Postman example missing. |
| POST | `/api/v1/accounting/opening-balances` | ⚠️ | `accounting.opening-balances.manage` | Acct-Audit §1 | D2, D4 | Σdebits = Σcredits required. |
| GET | `/api/v1/accounting/dashboard` | ❓ | `accounting.dashboard.view` | Acct-Audit §1 (tab 1) | — | **MISSING** — or formally drop and document client-side composition from `/journal-entries` + `/invoices` + `/bills` aggregates. |

#### 1.8.10 Reports

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET | `/api/v1/accounting/reports/{report-id}?from=&to=&branch_id=&format=json\|pdf\|xlsx` | ⚠️ | `accounting.reports.view` | Acct-Audit §1 (tab 14) | D2 | Confirmed report ids: `trial-balance`, `profit-loss`, `balance-sheet`, `cash-flow`, `ar-aging`, `ap-aging`, `vat-summary`. Format matrix to verify. |

#### 1.8.11 Settings

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| GET/POST/PATCH/DELETE | `/api/v1/accounting/tax-rates` | ✅ | `accounting.tax-rates.manage` | Acct-Audit §4 | — | |
| GET/PATCH | `/api/v1/accounting/numbering-sequences` | ✅ | `accounting.numbering.manage` | Acct-Audit §4 | — | Invoice/bill/voucher prefixes. |
| GET/POST | `/api/v1/accounting/integrations` | ⚠️ | `accounting.integrations.manage` | Acct-Audit §4 | — | Per-provider connect payloads (banks, ZATCA, payroll) need spec. |
| POST | `/api/v1/accounting/integrations/{id}/connect` | ⚠️ | `accounting.integrations.manage` | Acct-Audit §4 | — | OAuth callback shape per provider. |
| POST | `/api/v1/accounting/integrations/{id}/disconnect` | ⚠️ | `accounting.integrations.manage` | Acct-Audit §4 | — | |
| GET | `/api/v1/accounting/checklists?period={id}` | ❓ | `accounting.checklists.manage` | Acct-Audit §4 | — | Day-close cadence checklist. **MISSING.** |
| PATCH | `/api/v1/accounting/checklists/{id}/items/{key}` | ❓ | `accounting.checklists.manage` | Acct-Audit §4 | — | Toggle done. **MISSING.** |
| GET/PATCH | `/api/v1/accounting/fixed-assets-policy` | ⚠️ | `accounting.fixed-assets.manage` | Acct-Audit §4 | — | Depreciation methods. Postman example missing. |
| POST | `/api/v1/accounting/fixed-assets/{id}/depreciate` | ⚠️ | `accounting.fixed-assets.manage` | Acct-Audit §4 | — | |

---

### 1.9 `inventory/*` — Stock movements (GL bridge sources)

| Method | Path | Status | Permission | Source doc | D-refs | Notes |
|---|---|---|---|---|---|---|
| POST | `/api/v1/inventory/grns` | ⚠️ | `inventory.grn.create` | Acct-Audit §3 | D5 | Auto-posts JE: DR Inventory, CR AP. Partial-receipt AP-credit splitting to confirm. |
| POST | `/api/v1/inventory/adjustments` | ⚠️ | `inventory.adjustments.create` | Acct-Audit §3 | D5 | Auto-posts JE: DR/CR Inventory ↔ Adjustment. |
| (recipe-driven) | (consumption emitted by POS sale or production) | ⚠️ | — | Acct-Audit §3 | D5 | DR COGS, CR Inventory. **Recipe cost rollup must happen server-side**, not client. |

---

### 1.10 Frontend-only flows (⛔)

These appear in the prototype but never call backend directly. Listed so
reviewers don't hunt for missing endpoints.

| Flow id | Why frontend-only | Source doc |
|---|---|---|
| `payment.installment` | UI alias of `payment.receive` (composer pre-fills amount). | Acct-Audit §2.1 |
| `onboarding` | Orchestrates `/companies` + `/accounting-settings` + `/chart-of-accounts/import` + `/opening-balances`. | Acct-Audit §2.5 |
| `AcctNarrator` / `AcctTweaks` | UI guidance + visual prefs (local). | Acct-Audit §6.4 |
| `AcctAudit` | Demo "what just happened" panel. Backend has its own `audit_log` table. | Acct-Audit §6.4 |

---

## 2. Status rollup

| Status | Count | What it means for Cursor |
|---|---|---|
| ✅ Verified | 38 | Confirm route file matches Postman; refresh ID/Money/bilingual fields per D1/D2/D10 if stale. |
| ⚠️ Inferred | 22 | Refresh Postman example or document a thin contract. No new code required if examples match the linked spec. |
| ❓ Missing | 14 | Add route + controller + validator + Postman entry + migration. Spec lives in linked handoff section. |
| 🔧 Mismatch | 0 | — |
| ⛔ Frontend-only | 4 | No backend work. |

**Total endpoints catalogued:** 78 (74 backend + 4 frontend-only).

---

## 3. Hard-blocker queue (the 14 ❓ rows, ordered by UI dependency)

When all 14 are landed, the prototype's `MOCK_MODE=false` flag flips and
the app talks to live backend end-to-end.

1. `GET /shifts/current` (D9) — POS shell can't render without it.
2. `POST /sales/{id}/refund` (D11) — cashier-immediate same-tender refund. Approved.
3. `POST /shifts/{id}/cash-movements` — accurate close variance.
4. `GET /shifts/{id}/x-report` *(or formally drop, falling back to client-compute)*.
5. `POST /branches/{id}/day-close` — branch EOD rollup.
6. `POST /accounting/receipt-vouchers` (+ GET).
7. `POST /accounting/payment-vouchers` (+ GET).
8. `POST /accounting/journal-entries/{id}/reverse` (todo #27).
9. `POST /accounting/journal-entries/{id}/adjust` (todo #27).
10. `GET/POST/PATCH/DELETE /accounting/bank-rules`.
11. `GET /accounting/checklists?period={id}` + `PATCH /checklists/{id}/items/{key}`.
12. `GET /accounting/dashboard` *(or drop)*.
13. `GET /sales` listing (D8).
14. `POST /accounting/credit-notes` (Postman shape thin; refresh & confirm `reason_code` enum).

> Items 1–5 unlock the **POS / shifts** end-to-end story.
> Items 6–14 unlock the **Accounting** end-to-end story.

---

## 4. Cross-cutting hygiene (Postman refresh — Phase A)

These don't add endpoints; they bring existing examples up to D1–D10
contract. Mechanical pass across the whole collection.

- [ ] **A1** Replace integer ids with ULIDs in every example (D1).
- [ ] **A2** Convert all Money fields to `{amount_minor, currency_code}` (D2).
- [ ] **A3** Split bilingual fields per D10 (Pattern A `_ar`/`_en` for indexed; Pattern B `{ar,en}` for prose).
- [ ] **A4** Add error-envelope examples (`{error:{code,message_en,message_ar,fields}}`) to every 4xx response.
- [ ] **A5** Confirm every list route accepts `?per_page`, `?page`, `?q`, `?branch_id`, and emits `meta:{page,per_page,total}`.

---

## 5. Maintenance

- This is a **catalog**, not a spec. Per-endpoint detail (request body,
  response shape, error scenarios, Cursor checklist) lives in the linked
  per-flow handoff doc.
- When a new endpoint is added or a status flips (❓→✅, ⚠️→✅), update the
  row here **and** the source doc in the same commit.
- Cross-cutting decisions (D-numbers) live in `docs/handoff/DECISIONS.md §5a`.
- If a new module audit ships (HR, Pay, Dine, BI, etc.), append a new
  resource section to §1 and re-run the §2 rollup.

---

*Updated by todo #31. Source audits: POS, Onboarding, Shifts/Day-close, Accounting.*