kirukib
7310a349c5
Ship Expo Router screens, seeded stores, and polished UX so auth, shop, checkout, prescriptions, loyalty, family, and account processes work end-to-end offline. Co-authored-by: Cursor <cursoragent@cursor.com>
136 lines
5.8 KiB
Markdown
136 lines
5.8 KiB
Markdown
# 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.
|