API Spec (Node/Express)

Base: https://api.udhaar.itsmehere.com · All /api/* require Authorization: Bearer <jwt>. Money in request/response is paise (integer). Errors: { error: "message" } + HTTP code.

Auth

POST /auth/send-otp

body: { phone } → { ok: true } (sends OTP via WhatsApp; rate-limited)

POST /auth/verify-otp

body: { phone, code } → { token, shop: { id, phone, shop_name, owner_name } } - Creates shop row on first successful verify.

Shop

GET /api/shop → shop profile

PATCH /api/shop body: { shop_name?, owner_name? } → updated profile

Customers

GET /api/customers

→ [{ id, name, phone, note, balance_paise, last_activity_at }] (balance computed server-side) Query: ?q= search by name, ?sort=balance|name|recent

POST /api/customers body: { name, phone?, note? } → customer

GET /api/customers/:id → customer + { balance_paise }

PATCH /api/customers/:id body: { name?, phone?, note? }

DELETE /api/customers/:id (soft delete)

Entries (ledger)

GET /api/customers/:id/entries

→ [{ id, type, amount_paise, note, entry_date, created_at }] newest first, paginated ?limit&before

POST /api/customers/:id/entries

body: { type: 'credit'|'payment', amount_paise, note?, entry_date? } → entry + new balance

PATCH /api/entries/:id body: { amount_paise?, note?, entry_date? }

DELETE /api/entries/:id (soft delete)

Summary

GET /api/summary

→ { total_outstanding_paise, customer_count, customers_in_debt, total_collected_this_month_paise }

Reminders

POST /api/customers/:id/remind

→ sends WhatsApp reminder with current balance; logs to reminders table. → { ok: true, status: 'sent' } or 4xx if customer has no phone / zero balance.

Templates

GET /api/templates

→ [{ key, text, description, variables, updated_at }] — the central WhatsApp message templates (stored in wa_templates). Read-only over the API; edit the table directly. See WhatsApp doc. Customers also get automatic udhaar_added / payment_received WhatsApp messages when their ledger changes (toggle NOTIFY_ON_ENTRY).

Sync (offline outbox flush)

POST /api/sync

body: { ops: [{ op_id, kind, payload, client_ts }] } → { results: [{ op_id, status, server_id? }] } (idempotent by op_id)

Validation rules

  • phone: E.164-ish, 10-digit Indian normalized to +91.
  • amount_paise: integer > 0, < 1_00_00_000_00 (sanity cap).
  • All string fields trimmed, length-capped.