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.