countries-api

Countries API

• Base Paths:
  • Public: /api/v1/countries
  • Admin: /api/admin/countries
• Auth:
  • Public: not required
  • Admin: required (admin middleware)

Provides a list of supported countries with an available flag to control whether a country is currently enabled across the app.

Model notes

• Country document stores: name, isoAlpha2, isoAlpha3, isoNumeric, currency \{ code, name, symbol? \}, and available: boolean (default true).

Public: List Countries

• Method: GET
• Path: /api/v1/countries
• Query:
  • available (optional): true | false | all
    • When omitted or set to all, returns all countries
    • true returns only enabled countries
    • false returns only disabled countries
• Response 200:

  {
    "result": [
      { 
        "name": "India", 
        "available": true,
        "listingAvailable": true,
        "listingBlocked": false
      },

      { 
        "name": "United States", 
        "available": false,
        "listingAvailable": true,
        "listingBlocked": false
      }

] }

• Errors: 500 on failure
• Notes:
  • Results are sorted by name ascending.
  • Fields exposed: name, available, listingAvailable, listingBlocked
  • listingAvailable: boolean indicating if listings are allowed for this country (computed as !listingBlocked)
  • listingBlocked: boolean indicating if listings are blocked for this country

Admin: List Countries (with pagination + sorting)

• Method: GET
• Path: /api/admin/countries
• Auth: required
• Query:
  • available (optional): true | false | all (default: all)
  • page (optional): number ≥ 1 (enables pagination when used with limit)
  • limit (optional): 1–100
  • sort (optional): asc | desc (default: asc) — sort by country name
• Response 200 (paginated when page and limit provided):

  {
    "result": [
      {
        "_id": "...",
        "id": 356,
        "name": "India",
        "isoAlpha2": "IN",
        "isoAlpha3": "IND",
        "isoNumeric": 356,
        "currency": { "code": "INR", "name": "Indian Rupee", "symbol": "₹" },
        "available": true
      }

], "page": 1, "limit": 20, "total": 250, "totalPages": 13, "sort": "asc" }

• Response 200 (when page/limit are omitted):
  • Returns a simple array of country objects (backward compatible)
• Errors: 401 unauthorized; 500 on failure
• Notes:
  • On first call, the system seeds countries from countries.json if the collection is empty.

Admin: Update Availability

• Method: PATCH
• Path: /api/admin/countries/:isoAlpha2/availability
• Auth: required
• Body: \{ "available": boolean \}
• Response 200:

  {
    "ok": true,
    "country": { "name": "India", "isoAlpha2": "IN", "available": true },
    "missingTaxRules": false
  }

• Behavior:
  • Toggles availability for the specified country (by ISO alpha‑2 code).
  • When enabling a country with no active tax rules configured, response includes missingTaxRules: true and a warning message to prompt adding tax rules first.
• Errors: 400 invalid input; 401 unauthorized; 404 not found; 500 failure