EMI Calculator - API Reference

Audience: Frontend engineers (storefront + admin panel), backend engineers, QA, and API consumers. Scope: The 25 routes — 2 public customer routes under /api/mobile/emi/..., 23 admin routes under /api/admin/emi/....

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

5. Auth, Identity, and Permissions

Two permission modules. Emi_* = switch, price source, eligibility mode, tenure vocabulary, product/category eligibility. EmiBanks_* = banks, rates, tenures. Emi_UPDATE is the wider grant — it carries the store-wide kill switch.

6. DTO and Model Reference

6.1 EmiProductParamsDto — customer routes

6.2 EmiVariantQueryDto — /options, and CalculateEmiQueryDto — /calculate

Both routes bind their query with whitelist: true, forbidNonWhitelisted: true (the global ValidationPipe), so any unexpected query key — a campaign tag like utm_source, a cache-buster like ?_=169… — is a 400 VALIDATION_FAILED on what used to be a lenient public route. This is a genuine behavior change from before the variant work: /options took no query DTO at all previously.

6.3 UpdateEmiSettingsDto — PUT /settings

6.4 Bank DTOs

CreateEmiBankDto: name (non-blank, ≤255), logoKey/logoAlt (alt requires key), minLoanAmount / maxLoanAmount (integers, min ≤ max, nullable), displayOrder (≥0). UpdateEmiBankDto: same fields, optional. ReorderEmiBanksDto: bankIds array.

6.5 Rate DTO

CreateEmiBankRateDto: annualRateBps (integer 0…10000), effectiveFrom (ISO instant, bounded < 2100).

6.6 Response DTOs

• EmiOptionsDto: available, unavailableReason, productId, productName, variantId (uuid | null — the configuration these quotes are for; null means basePrice is the product's "from" figure), variantName (string | null — null both when no variant was requested AND when the requested variant is the product's sole configuration with no label of its own), basePrice (0 when unavailable), banks[] (see the handoff body in §8.1).
• EmiCalculationDto: productId, productName, variantId (uuid | null — the configuration financed; null means the quote is the product's "from" estimate and must not be presented beside a chosen variant), variantName (string | null), bankId, bankName, basePrice, annualRateBps, tenureMonths, monthlyEmi, totalRepayment, totalInterest, isEstimate: true.
• EmiBankAdminDto / EmiBankRateAdminDto / EmiTenureAdminDto / settings DTO: admin CRUD shapes, all money in paisa, rates in bps.

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/mobile/emi/products/{productId}/options

Purpose

The storefront asks this before rendering any "Calculate EMI" affordance. It returns eligibility, the base price, and every offerable bank with its rate, loan limits, applicability and already computed quotes per offered period. It never returns 4xx for an ineligible product — available: false distinguishes "no EMI" from "no such product". Only a genuinely missing product 404s, and so does a variantId that names no live configuration OF THIS PRODUCT — that is an identity failure, not an eligibility answer.

Pass variantId (optional, EmiVariantQueryDto) once the customer has chosen a configuration. Without it the quotes are the product's "from" estimate, computed from the cheapest live configuration, and variantId comes back null in the response so a client can tell which it received.

Auth and Permissions

• Auth: @Public() · Rate limit: PUBLIC_READ 60/min

Response

{
  "success": true,
  "message": "EMI options fetched successfully",
  "data": {
    "available": true,
    "unavailableReason": null,
    "productId": "019fcc90-e010-7698-ae7a-faec1e7bed42",
    "productName": "Galaxy S24 Ultra",
    "variantId": "019fcc90-1234-7698-ae7a-faec1e7bed99",
    "variantName": "512GB",
    "basePrice": 13120091,
    "banks": [
      {
        "id": "0199b000-0000-7000-8000-00000000ba01",
        "name": "Nabil Bank",
        "logo": { "url": "/uploads/banks/nabil.png", "alt": "Nabil Bank" },
        "annualRateBps": 1200,
        "minLoanAmount": 500000,
        "maxLoanAmount": 50000000,
        "isApplicable": true,
        "unavailableReason": null,
        "quotes": [
          { "tenureMonths": 6,  "monthlyEmi": 2263850, "totalRepayment": 13583100, "totalInterest": 463009 },
          { "tenureMonths": 12, "monthlyEmi": 1165704, "totalRepayment": 13988448, "totalInterest": 868357 }
        ]
      }
    ]
  }
}

When unavailable: available: false, unavailableReason populated, basePrice: 0, banks: [].

quotes is already computed — render those numbers, do not recompute them. A bank with isApplicable: false has empty quotes and a populated unavailableReason (price outside the bank's loan limits).

Side Effects

None — reads only.

Error Cases

8.2 GET /api/mobile/emi/products/{productId}/calculate

Purpose

One bank, one tenure, full exact breakdown. The client has already seen what is on offer, so a failure here means something changed underneath or the request was hand-made — every failure raises a specific code.

Pass the same variantId that was used to list the options, or the plan quoted back will be a different configuration's. The response echoes variantId and variantName so a client can detect both a reprice and a configuration mismatch.

Auth and Permissions

• Auth: @Public() · Rate limit: PUBLIC_READ 60/min

Request

Response

{
  "success": true,
  "message": "EMI calculated successfully",
  "data": {
    "productId": "019fcc90-…", "productName": "Galaxy S24 Ultra",
    "variantId": "019fcc90-1234-7698-ae7a-faec1e7bed99", "variantName": "512GB",
    "bankId": "0199b000-…",   "bankName": "Nabil Bank",
    "basePrice": 13120091,
    "annualRateBps": 1200,
    "tenureMonths": 12,
    "monthlyEmi": 1165704,
    "totalRepayment": 13988448,
    "totalInterest": 868357,
    "isEstimate": true
  }
}

basePrice is echoed so the client can detect the product was repriced between listing options and calculating.

Side Effects

None. The server computes it as an exact rational in BigInt with no floating point anywhere — do not recompute client-side; the server is right.

Error Cases

8.3 GET /api/admin/emi/settings

Purpose

Read the store-wide switch, price source and eligibility mode.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Emi_READ · Rate limit: ADMIN_READ

8.4 PUT /api/admin/emi/settings

Purpose

Flip the store-wide switch, set the price source, set the eligibility mode. Takes effect within 30 seconds (config cache).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Emi_UPDATE · Rate limit: ADMIN_WRITE

Side Effects

Singleton upsert (CHECK (id = 1)); emi cache domain invalidated after commit.

Error Cases

8.5 GET /api/admin/emi/tenures

Purpose

List the tenure vocabulary (~9 seeded periods: 3, 6, 9, 12, 18, 24, 36, 48, 60).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Emi_READ · Rate limit: ADMIN_READ

8.6 PUT /api/admin/emi/tenures

Purpose

Replace the vocabulary. Periods must stay within 1…120; deactivate rather than delete a period still assigned to a bank.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Emi_UPDATE · Rate limit: ADMIN_WRITE

Error Cases

8.7–8.9 GET/POST/DELETE /api/admin/emi/eligibility/categories

Purpose

Select and deselect categories as eligible. A selected category confers EMI on all its descendants (tree expansion at read time).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permissions: Emi_READ / Emi_CREATE / Emi_DELETE · Rate limit: ADMIN_READ / ADMIN_WRITE

Error Cases

8.10–8.12 GET/POST/DELETE /api/admin/emi/eligibility/products

Purpose

Select and deselect individual products. Membership is the union of the category and product selections (when mode is selected).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permissions: Emi_READ / Emi_CREATE / Emi_DELETE

Error Cases

8.13 GET /api/admin/emi/eligibility/effective-products

Purpose

The product list a customer would actually see — mirrors the customer gate: live status, sellingPrice > 0, and the current eligibility mode (expansion when selected; everything when entire_store).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Emi_READ · Rate limit: ADMIN_READ

8.14 GET /api/admin/emi/banks

Purpose

List banks with rates and tenures attached, sorted (displayOrder/name/createdAt — a closed set), paginated.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_READ · Rate limit: ADMIN_READ

8.15 POST /api/admin/emi/banks

Purpose

Create a bank. Name is NFC-normalised and unique among live banks.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_CREATE · Rate limit: ADMIN_WRITE

Error Cases

8.16 PATCH /api/admin/emi/banks/reorder

Purpose

Rewrite displayOrder from the supplied id order. All ids must exist and be live (404 otherwise). Transactional.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_UPDATE · Rate limit: ADMIN_WRITE

8.17 GET /api/admin/emi/banks/{bankId}

Purpose

One bank with its rate history and offered tenures.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_READ · Rate limit: ADMIN_READ

Error Cases

8.18 PATCH /api/admin/emi/banks/{bankId}

Purpose

Update name/logo/loan limits/display order/active flag.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_UPDATE · Rate limit: ADMIN_WRITE

Error Cases

8.19 DELETE /api/admin/emi/banks/{bankId}

Purpose

Soft delete. A bank disappears from the customer catalog.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_DELETE · Rate limit: ADMIN_WRITE

Error Cases

8.20 POST /api/admin/emi/banks/{bankId}/restore

Purpose

Restore a soft-deleted bank.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_RESTORE · Rate limit: ADMIN_WRITE

8.21 GET /api/admin/emi/banks/{bankId}/rates

Purpose

The append-only rate history.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_READ · Rate limit: ADMIN_READ

8.22 POST /api/admin/emi/banks/{bankId}/rates

Purpose

Schedule a rate (annualRateBps 0…10000, effectiveFrom ISO instant). It becomes the quoted rate at effective_from. There is no PATCH — a rate is corrected by superseding it.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_CREATE · Rate limit: ADMIN_WRITE

Error Cases

8.23 DELETE /api/admin/emi/banks/{bankId}/rates/{rateId}

Purpose

Cancel a scheduled rate (only while effective_from > now()). A rate that is or has been in force is refused — the record of what was quoted.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_DELETE · Rate limit: ADMIN_WRITE

Error Cases

8.24 GET /api/admin/emi/banks/{bankId}/tenures

Purpose

The bank's offered periods.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_READ · Rate limit: ADMIN_READ

8.25 PUT /api/admin/emi/banks/{bankId}/tenures

Purpose

Replace the bank's offered periods wholesale. Every month must be in the vocabulary and active (deactivation blocks new assignments). Serialised with FOR UPDATE so two concurrent replaces cannot produce the union of their sets.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: EmiBanks_UPDATE · Rate limit: ADMIN_WRITE

Error Cases

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (options)

9.3 Error Branch (calculate)

10. Pagination, Sorting, Filtering, and Search

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered in §6 and §8: minimal and full payloads for every body endpoint, the two customer responses with real verified numbers (§8.1/8.2), every nullable field, per-endpoint error tables with the exact codes, and the uuid-v7 / tenure-integer validation notes.

13.3 API Diagram Pack

Route ownership (§9.1), options sequence (§9.2), calculate error tree (§9.3), plus the estimator and rate-boundary flows in the feature/backend docs.

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8, §13.1).
• Every parent route prefix and runtime URL is documented (§2, §4) — including the /api/mobile/emi/... and NO-/api/emi/... fact.
• Every DTO field, enum, default, transform, and validator is documented (§6, §7).
• Every response field, nullable field, and generated field is documented (§6.6, §8).
• Every auth, guard, permission, and public branch is documented (§5).
• Every success, validation, auth, not-found, conflict, and rate-limit branch is documented (§8).
• Every database read/write, cache hit/miss/invalidation, queue job, and external call is documented (§8 side effects, §11).
• Every route has examples for minimal request, success response, and representative failures (§8).
• Every endpoint family has route, sequence, and error diagrams (§9).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (See Also).

15. Integration Checklist

• Every route from controllers is documented (25/25).
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented (25/25, including EMI_VARIANT_NOT_FOUND).
• Every auth guard and permission is documented.
• Every cache key, queue job, and external call is documented — no queue exists by design.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/emi/backend
• Features and flows doc: /docs/developer/emi/feature
• TDD: not yet published