Gishen-Mob/docs/BACKEND_SPEC.md

Gishen-Mob Backend Spec

Base URL (TBD): https://api.gishen.example/v1
Auth: Bearer JWT after verified sign-in (phone OTP, email, Google, or Telegram)
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 } — SMS OTP
POST	/auth/otp/verify	Required	{ phone, code } → session + user
POST	/auth/email/login	Required	{ email, password } → session + user
POST	/auth/email/register	Optional	{ name, email, password, phone? }
POST	/auth/oauth/google	Required	{ idToken } (or auth code) → session + user
POST	/auth/oauth/telegram	Required	Telegram Login Widget payload → session + user
POST	/auth/guest	Required	Optional device id → limited guest session (isGuest: true)
POST	/auth/biometric/bind	Required	Device biometric public key
GET	/users/me	Required	Profile, locale, points, tier, authProvider
PATCH	/users/me	Required	name, email, phone, locale, biometric flag

Providers (mobile UI): google | email | phone | telegram | guest
Guest sessions may browse catalog and generate pharmacist order codes; loyalty, corporate, and some care features require a non-guest account.

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

Favorites

Method	Path	Status	Notes
GET	/favorites/me	Required	Product ids
PUT	/favorites/:productId	Required	Add
DELETE	/favorites/:productId	Required	Remove

Addresses

Method	Path	Status	Notes
GET	/users/me/addresses	Required	Saved delivery addresses
POST	/users/me/addresses	Required	label, street, area, landmark?, isDefault?
PATCH	/users/me/addresses/:id	Required
DELETE	/users/me/addresses/:id	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?, anyBranch?
GET	/orders/me	Required	Authenticated user’s orders
GET	/orders/:id	Required
GET	/orders/by-code/:code	Required	Lookup by GSH-XXXX (guest + pickup). Mobile uses this for “find my code”.
GET	/orders/:id/tracking	Required	Rider trail when assigned
POST	/orders/:id/cancel	Required

Guest / pharmacist order codes (parity with Gishen Ecom Web)

Guests (and optionally signed-in pickup) receive a short pharmacist reference code (GSH-XXXX).

Method	Path	Status	Notes
POST	/orders/guest-codes	Required	Basket snapshot + customer name/phone → { code, orderId, status: "requested" }. Mobile shows copy / share / screenshot card.
GET	/admin/orders/by-code/:code	Required	Admin — pharmacist enters code to create / hydrate the POS order (shared with Ecom admin).
POST	/admin/orders/by-code/:code/fulfill	Required	Mark created / confirmed after admin processing

Mobile contract

• Guest checkout forces pickup + pay_at_branch + any-branch code.
• Response includes pickupCode, status: requested until pharmacist creates the order in admin.
• Share payload should include code, customer, line items, total (plain text for WhatsApp / clipboard).

Payments

Method	Path	Status	Notes
POST	/payments/intent	Required	chapa | arifpay | telebirr | mpesa | bank | cod | pay_at_branch
POST	/payments/webhook/*	Required	Gateway callbacks
GET	/users/me/payment-preference	Required	Saved preferred method
PUT	/users/me/payment-preference	Required
—	pay_at_branch	Required	Allowed only when fulfillment=pickup (required for guest / assisted pharmacist codes)
—	cod	Required	Delivery only
—	bank	Required	May require receipt upload via signed URL

Prescriptions (Rx Care)

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
GET	/prescriptions/:id	Required	Detail + attached reminders
POST	/prescriptions/:id/reorder	Required

Reminders

Method	Path	Status	Notes
POST	/health/reminders	Required	Dose/refill schedules (times[], graceMinutes, escalate?)
POST	/health/reminders/:id/confirm	Required	dose.confirmed
POST	/health/reminders/:id/snooze	Required
GET	/health/reminders/me	Required
—	Local + remote push	Required	Daily dose window; calendar UI on /prescriptions/:id/calendar

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

Notifications (in-app inbox)

Distinct from order list. Home bell → inbox.

Method	Path	Status	Notes
GET	/notifications/me	Required	kinds: order | rx | dose | loyalty | promo | system
POST	/notifications/:id/read	Required
POST	/notifications/read-all	Required
DELETE	/notifications/:id	Required
POST	/devices	Required	push token registration
GET	/notifications/prefs	Required	{ sms, email, push, orderUpdates, refillReminders, marketing }
PUT	/notifications/prefs	Required	Same shape

Push / Tracking

Method	Path	Status	Notes
POST	/devices	Required	push token
—	Events	Required	order., dispatch., dose., refill., escalation., guest_code.
GET	/orders/:id/tracking	Required

Contact / Support

Method	Path	Status	Notes
POST	/contact	Required
—	Chatwoot	Deeplink	https://chat.yaltopia.com
—	WhatsApp / Call	Deeplink	Branch support numbers

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.
• 2026-08-07: Auth providers — Google, Email, Phone OTP, Telegram, and Guest session contracts; authProvider on /users/me.
• 2026-08-07: Guest pharmacist codes — POST /orders/guest-codes, GET /orders/by-code/:code, admin fulfill-by-code (Ecom parity); mobile copy/share/screenshot card.
• 2026-08-07: Notifications inbox — dedicated /notifications/me (separate from Orders); Favorites + Addresses endpoints documented; Rx Care dose reminder confirm/snooze.
• 2026-08-10: Profile/Checkout/Rx finalize — payment preference screen (Chapa, ArifPay, Telebirr, M-Pesa, bank, COD, pay_at_branch); notification prefs (GET/PUT /notifications/prefs); checkout loyalty redeem + Rx cart gate + assisted code for signed-in; Rx status stepper + queried reply; mock POST /payments/intent.