Conventions:

• Versioning: /v1/...
• Auth: Admin (console/service-to-service) or Internal (private ops).
• Headers: X-Request-Id (required), Idempotency-Key (for POST/PUT that create resources), If-Match (ETag on updates).
• Pagination: cursor (limit, cursor), fallback offset where noted.

---

0) Platform ops (always first)

• GET /v1/health — liveness check (no deps). Done: returns 200 with build info.
• GET /v1/ready — readiness (DB ping, migrations table present). Done: 200 only if DB ok.
• GET /v1/metrics — Prometheus metrics. Done: histograms for request/DB timings.
• GET /v1/version — service + schema versions. Done: commit SHA, semver, schema hash.
• GET /v1/docs — OpenAPI UI (swagger/rapidoc). Done: reflects all routes.
• POST /v1/admin/rotate-keys (Internal) — rotate service secrets (if applicable).

---

1) Reference: Countries & Currencies

Countries

• GET /v1/countries — list (cursor+search+sort). Auth: Admin (read).
• POST /v1/countries — create country (uses Zod validation; idempotent via Idempotency-Key). Auth: Admin.
• GET /v1/countries/:code — fetch by ISO2. Auth: Admin.
• PATCH /v1/countries/:code — update (ETag/If-Match support). Auth: Admin.
• DELETE /v1/countries/:code — remove (if detach-clean). Auth: Admin.
• GET /v1/countries/:code/config — view effective country config. Auth: Admin.
• PUT /v1/countries/:code/config — replace config (version bump). Auth: Admin.
• GET /v1/countries/:code/history — audit events for country (paginated). Auth: Admin.
• GET /v1/countries:reference — helper lists: regions, timezones, locale examples. Public/Admin.

Currencies

• GET /v1/currencies — list all currencies (iso4217). Public/Admin.
• POST /v1/currencies — add/override local currency metadata. Admin.
• GET /v1/currencies/:code — fetch.
• PATCH /v1/currencies/:code — update metadata/format.
• DELETE /v1/currencies/:code — remove (if not in use).

Country ↔ Currency mapping

• GET /v1/countries/:code/currencies — list allowed + base.
• PUT /v1/countries/:code/currencies/base — set base currency.
• PUT /v1/countries/:code/currencies/allowed — set allowed array (must include base).

---

2) Tenants & Environments

• GET /v1/tenants — list/search. Admin.
• POST /v1/tenants — create (country, baseCurrency, status). Admin.
• GET /v1/tenants/:tenantId — get.
• PATCH /v1/tenants/:tenantId — update (name, status).
• POST /v1/tenants/:tenantId:suspend — change status to SUSPENDED.
• POST /v1/tenants/:tenantId:activate — change status to ACTIVE.

Environments (STG / PRD per tenant)

• GET /v1/tenants/:tenantId/environments — list.
• POST /v1/tenants/:tenantId/environments — create env (name, envType=STG|PRD|DEV).
• GET /v1/tenants/:tenantId/environments/:envId — get env.
• PATCH /v1/tenants/:tenantId/environments/:envId — update (flags).
• POST /v1/tenants/:tenantId/environments:promote — promote configs/schedules STG→PRD (keys/products filters).
• GET /v1/tenants/:tenantId/environments/:envId/audit — env audit trail.

---

3) Product Catalog

• GET /v1/products — list products (WALLET, TRANSFER, CASHIN, …).
• POST /v1/products — create/enable product.
• GET /v1/products/:code — get product.
• PATCH /v1/products/:code — update metadata/category/status.
• DELETE /v1/products/:code — soft-delete/deprecate.

---

4) Configs (hierarchical & versioned)

Scopes: GLOBAL | COUNTRY | TENANT | ENVIRONMENT

• GET /v1/configs/effective — resolve effective config by context (tenantId, envId, country).
• GET /v1/configs — list by scope/key (history aware).
• POST /v1/configs — create new key version {scope, scopeRef, key, value} (idempotent key).
• PATCH /v1/configs/:configId — deactivate/activate or supersede.
• GET /v1/configs/:configId — view specific version.
• POST /v1/configs:promote — STG→PRD for keys (tenant-scoped).
• POST /v1/configs:dry-run — simulate effective config for a context (debug tool).

---

5) Schedules (fees & limits)

Kinds: FEE, LIMIT (each is a “schedule” with items)

• GET /v1/schedules — list by {kind, product, scope, scopeRef, active?}.
• POST /v1/schedules — create schedule (inactive by default).
• GET /v1/schedules/:scheduleId — get schedule + items.
• PATCH /v1/schedules/:scheduleId — update metadata/active window.
• DELETE /v1/schedules/:scheduleId — archive schedule (if not active).
• POST /v1/schedules/:scheduleId/fees — add fee items (tiers).
• POST /v1/schedules/:scheduleId/limits — add limit items.
• GET /v1/schedules:effective — resolve active schedule for context (tenant/env/country).
• POST /v1/schedules:promote — STG→PRD (tenant, products filter).
• POST /v1/schedules:validate — static validation for overlaps/gaps, currency precision.

Resolution helpers (runtime calc)

• POST /v1/fees:quote — input {product, amount, currency, tenant/env/country} → fee tier resolved.
• POST /v1/limits:check — input {product, action, period[, currency]} → applicable limit row.

---

6) Feature Flags

• GET /v1/flags — list all flags with scope & rollout % (if you do gradual).
• PUT /v1/flags/:flagKey — set {enabled, scopes[]}.
• GET /v1/flags/effective — resolve for context (tenant/env/country + userId optional).

---

7) Idempotency & Outbox (operational visibility)

• GET /v1/idempotency — search by key/method/path/date (ops-only).

• GET /v1/idempotency/:key — show cached response metadata (no body unless internal).

• DELETE /v1/idempotency/:key — purge (admin/ops only; usually avoid).

• GET /v1/outbox — list unprocessed (filters by aggregate/event).

• POST /v1/outbox/:id:retry — force retry now.

• POST /v1/outbox:retry-batch — retry with filter (time window, attempts<).

• GET /v1/outbox/:id — view message payload/headers.

---

8) Audit Log

• GET /v1/audit — query by actor, action, resource, time (cursor).
• GET /v1/audit/:id — detail.

---

9) Webhooks (optional but handy for CPS)

• GET /v1/webhooks — list endpoints per tenant.
• POST /v1/webhooks — create endpoint (url, secret, events[]).
• GET /v1/webhooks/:id — get.
• PATCH /v1/webhooks/:id — rotate secret, pause/resume.
• DELETE /v1/webhooks/:id — delete.
• POST /v1/webhooks/:id:test — send test event now.

---

10) Tools / Reference utilities

• GET /v1/reference/timezones — IANA TZ list (cached).
• GET /v1/reference/regions — region/subregion map.
• GET /v1/reference/locales — locale hints (BCP47 samples).
• POST /v1/validate/country — server-side validate a payload without persisting (for UI).

---

Cross-cutting requirements (apply to all relevant endpoints)

• Security

  • JWT/service-token auth; RBAC (Admin, Ops, ReadOnly).
  • Input validation via Zod → consistent 400 Problem+JSON.
  • Rate limits on mutating routes (per IP/tenant).

• Idempotency

  • Idempotency-Key required for POST that creates resources and PUT upserts.
  • Store (method, path, hash) with response snapshot.

• ETag / Concurrency

  • Return ETag on GET; require If-Match on PATCH for write-heavy resources (countries, configs, schedules).

• Observability

  • Log reqId, traceId, tenantId, ip, and redact PII.
  • Metrics: per-route latency, DB timings, tx retries, 5xx count.
  • Traces: spans around DB transactions and promotions.

• Pagination

  • Prefer cursor (limit, cursor) with stable ordering; support offset for legacy UIs.

• Errors

  • Problem+JSON shape: { type, title, status, detail, instance }.
  • Domain codes: COUNTRY_NOT_FOUND, CONFIG_INVALID, SCHEDULE_OVERLAP, etc.

---

Suggested delivery order (minimizes rework)

1. Ops: health/ready/metrics/version/docs
2. Reference: currencies + countries (CRUD + search)
3. Tenants + Environments (STG/PRD)
4. Configs (versioned + effective resolution + promote)
5. Products
6. Schedules (fee/limit CRUD → validate → effective → promote)
7. Helpers (fees:quote, limits:check)
8. Feature flags
9. Idempotency/Outbox/Audit visibility
10. Webhooks (if needed)