Gishen-Mob/docs/BACKEND_SPEC.md

# Gishen-Mob Backend Spec

**Base URL (TBD):** `https://api.gishen.example/v1`  
**Auth:** Bearer JWT after phone OTP  
**Headers:** `Authorization`, `Accept-Language` (`en` | `am`), `Content-Type: application/json`

Shared with Gishen-Ecom / Gishen-B2B where noted.  
Patch this file whenever a feature is added or finalized.

## Auth
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| POST | `/auth/otp/request` | Required | `{ phone }` |
| POST | `/auth/otp/verify` | Required | `{ phone, code }` → session + user |
| POST | `/auth/biometric/bind` | Required | Device biometric public key |
| GET | `/users/me` | Required | Profile, locale, points, tier |
| PATCH | `/users/me` | Required | name, email, `locale`, biometric flag |

## Locale
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| PATCH | `/users/me` | Required | `{ locale: "en" \| "am" }` |
| — | Accept-Language | Required | All requests |

## Catalog
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| GET | `/catalog/products` | Required | q, category, badge, max — parity with Ecom |
| GET | `/catalog/products/:idOrSlug` | Required | |
| GET | `/catalog/categories` | Required | |

## Branches / Stock
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| GET | `/branches` | Required | |
| GET | `/branches/nearby` | Required | `lat`, `lng` |
| GET | `/stock/product/:productId` | Required | Nearby availability |

## Orders
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| POST | `/orders` | Required | items, fulfillment, branchId?, location, paymentMethod, prescriptionFileKeys?, notes, credit? |
| GET | `/orders/me` | Required | |
| GET | `/orders/:id` | Required | |
| GET | `/orders/:id/tracking` | Required | Rider trail when assigned |
| POST | `/orders/:id/cancel` | Required | |

## Payments
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| POST | `/payments/initiate` | Required | `chapa` \| `telebirr` \| `mpesa` only for delivery |
| POST | `/payments/webhook/*` | Required | Gateway callbacks |
| — | `pay_at_branch` | Required | Allowed **only** when `fulfillment=pickup` |

## Prescriptions
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| POST | `/uploads/signed-url` | Required | Rx images |
| POST | `/prescriptions` | Required | Multi-page keys, medicines[], patient, memberId? |
| POST | `/prescriptions/check` | Required | Match catalog → ready/review/unavailable |
| GET | `/prescriptions/me` | Required | |
| POST | `/prescriptions/:id/reorder` | Required | |

## Reminders
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| POST | `/health/reminders` | Required | Dose/refill schedules |
| POST | `/health/reminders/:id/confirm` | Required | `dose.confirmed` |
| GET | `/health/reminders/me` | Required | |

## Emergency contacts
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| GET | `/users/me/emergency-contacts` | Required | |
| POST | `/users/me/emergency-contacts` | Required | name, phone, relationship |
| DELETE | `/users/me/emergency-contacts/:id` | Required | |
| — | Job `dose.missed_escalation` | Required | After grace (default 30m) SMS/push to contact if no confirm |

## Family
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| GET | `/family/members` | Required | |
| POST | `/family/invites` | Required | phone or link code |
| POST | `/family/invites/accept` | Required | |
| DELETE | `/family/members/:id` | Required | |

## Subscriptions
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| GET | `/subscriptions/me` | Required | |
| POST | `/subscriptions` | Required | |
| POST | `/subscriptions/:id/pause` | Required | |
| POST | `/subscriptions/:id/resume` | Required | |
| POST | `/subscriptions/:id/cancel` | Required | |

## B2B / Corporate (shared with Gishen-B2B)
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| GET | `/users/me/contexts` | Required | personal + org memberships |
| POST | `/orgs/join` | Required | `{ code }` |
| GET | `/company/me` | Required | Member view: plan, allowance |
| POST | `/checkout/credit/quote` | Required | Basket split covered vs selfPay |

## Loyalty
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| GET | `/loyalty/me` | Required | |
| GET | `/loyalty/me/ledger` | Required | |
| POST | `/loyalty/redeem` | Required | |
| GET | `/referrals/me` | Required | |

## Push / Tracking
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| POST | `/devices` | Required | push token |
| — | Events | Required | order.*, dispatch.*, dose.*, refill.*, escalation.* |
| GET | `/orders/:id/tracking` | Required | |

## Contact / Support
| Method | Path | Status | Notes |
|--------|------|--------|-------|
| POST | `/contact` | Required | |
| — | Chatwoot | Deeplink | https://chat.yaltopia.com |

### Changelog
- 2026-08-06: Scaffold — skeleton created with all domains.
- 2026-08-06: Auth/Locale — OTP mock, biometric bind flag, language picker en/am, Accept-Language noted.
- 2026-08-06: Catalog — products/categories from Ecom data port; shop/search/favorites.
- 2026-08-06: Branches/Stock — GPS nearest sort; pickup selection (stock map stub).
- 2026-08-06: Orders/Payments/B2B — checkout with Chapa/Telebirr/M-Pesa; pay_at_branch pickup-only; WhatsApp handoff; credit quote split stub.
- 2026-08-06: Prescriptions/Reminders/Emergency — camera multi-page scan, check statuses, calendar dose push, escalation job contract.
- 2026-08-06: Family/Subscriptions — invite/manage; refill subscription CRUD.
- 2026-08-06: B2B/Account — contexts, join codes, profile switcher.
- 2026-08-06: Loyalty/Push/Tracking — wallet redeem/referral; order tracking map mock; device push channels.
- 2026-08-06: Contact/Support — contact form + Chatwoot/WhatsApp/call deeplinks.