{
  "openapi": "3.1.0",
  "info": {
    "title": "Kepler Ops — Enterprise Operations Intelligence API Gateway",
    "version": "2.0.0",
    "description": "Unified high-performance webhook gateway and deterministic operational intelligence engine across E-Commerce, 3PL Logistics, Ocean Freight, Fintech, and Marketplaces."
  },
  "servers": [
    {
      "url": "https://www.getkeplerops.com",
      "description": "Production Live Gateway (getkeplerops.com)"
    },
    {
      "url": "https://kepler-pic-server-production.up.railway.app",
      "description": "Direct Railway Ingress"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development & Testing Server"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Gateway Health & Async Queue Status",
        "responses": {
          "200": {
            "description": "Server is healthy"
          }
        }
      }
    },
    "/v1/tenants/me": {
      "get": {
        "summary": "Get Tenant Profile & Module Entitlements",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant profile and enabled modules"
          },
          "401": {
            "description": "Missing X-API-Key header"
          },
          "403": {
            "description": "Invalid API Key"
          }
        }
      }
    },
    "/v1/webhooks/shopify/{tenantId}/order-cancelled": {
      "post": {
        "summary": "Tenant-Specific Shopify Cancellation Webhook (W2)",
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-shopify-hmac-sha256",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook enqueued"
          },
          "401": {
            "description": "Invalid HMAC"
          },
          "402": {
            "description": "Subscription inactive / payment required"
          },
          "403": {
            "description": "Fulfillment module not enabled on plan"
          }
        }
      }
    },
    "/v1/webhooks/shopify/{tenantId}/order-created": {
      "post": {
        "summary": "Tenant-Specific Shopify COD Fraud Webhook (W6)",
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "COD check enqueued"
          },
          "402": {
            "description": "Subscription inactive"
          },
          "403": {
            "description": "COD Risk module not enabled on plan"
          }
        }
      }
    },
    "/v1/audits/weight-reconciler": {
      "post": {
        "summary": "Courier Volumetric Weight Surcharge Audit (W7)",
        "description": "Evaluates courier volumetric weight overcharges against catalog dimensions.",
        "responses": {
          "200": {
            "description": "Weight discrepancy analysis and financial leak"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/freight-demurrage": {
      "post": {
        "summary": "Global Ocean Freight Container Demurrage Watchdog (W10)",
        "description": "Evaluates container port dwell time and calculates USD demurrage penalties.",
        "responses": {
          "200": {
            "description": "Demurrage risk evaluation and countdown status"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/margin-reconciler": {
      "post": {
        "summary": "Shopify Discount Stacking & Margin Loss Audit (W11)",
        "description": "Evaluates order direct contribution margin and catches coupon abuse.",
        "responses": {
          "200": {
            "description": "Margin analysis and negative profit warning"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/amazon-fba": {
      "post": {
        "summary": "Amazon FBA Surcharges & Storage Watchdog (W12)",
        "description": "Evaluates aged inventory storage overstay and stranded unit drain.",
        "responses": {
          "200": {
            "description": "FBA health assessment"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/catalog-health": {
      "post": {
        "summary": "Shopify Bulk Catalog & Tax Health Checker (W13)",
        "description": "Evaluates missing 6-digit HSN codes, 0g weights, and untaxed items.",
        "responses": {
          "200": {
            "description": "Catalog integrity audit result"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/marketplace-parity": {
      "post": {
        "summary": "Amazon ↔ Flipkart ↔ Meesho Parity Guard (W14)",
        "description": "Evaluates multi-channel price parity and Buy Box suppression risk.",
        "responses": {
          "200": {
            "description": "Marketplace parity evaluation"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/ndr-watchdog": {
      "post": {
        "summary": "Courier NDR & Fake Attempt Watchdog (W15)",
        "description": "Evaluates fake courier delivery denial and impending 36h RTO cutoffs.",
        "responses": {
          "200": {
            "description": "NDR risk and dispute escalation instructions"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/split-shipment": {
      "post": {
        "summary": "Multi-Warehouse Split-Shipment Watchdog (W16)",
        "description": "Catches preventable multi-location order splits doubling shipping freight.",
        "responses": {
          "200": {
            "description": "Split shipment optimization verdict"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/subscription-dunning": {
      "post": {
        "summary": "Subscription Dunning & Involuntary Churn Watchdog (W17)",
        "description": "Catches exhausted dunning retries and 30-day card expirations.",
        "responses": {
          "200": {
            "description": "Subscription churn risk evaluation"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/pincode-risk": {
      "post": {
        "summary": "Chronic High-RTO Pincode & ODA Watchdog (W18)",
        "description": "Evaluates postal codes with <40% delivery success rates and ODA zones.",
        "responses": {
          "200": {
            "description": "Pincode serviceability and COD risk verdict"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/amazon-ppc": {
      "post": {
        "summary": "Amazon PPC Bleeding Keyword Watchdog (W19)",
        "description": "Catches zero-conversion keywords with 30+ clicks and unprofitable high ACoS targets.",
        "responses": {
          "200": {
            "description": "PPC keyword waste assessment"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/returns-qc": {
      "post": {
        "summary": "Returns QC Quarantine & Stockout Watchdog (W20)",
        "description": "Identifies returns stuck in quarantine backlog >14 days and artificial stockouts.",
        "responses": {
          "200": {
            "description": "Returns QC triage verdict"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/fx-markup": {
      "post": {
        "summary": "Multi-Currency FX Conversion Watchdog (W21)",
        "description": "Detects hidden FX conversion spreads >2.5% applied by payment gateways.",
        "responses": {
          "200": {
            "description": "FX spread overcharge calculation"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/v1/audits/eway-compliance": {
      "post": {
        "summary": "B2B E-Way Bill Expiry & IRN Compliance (W22)",
        "description": "Alerts on in-transit E-Way bills expiring in <=6 hours and missing B2B IRN QR codes.",
        "responses": {
          "200": {
            "description": "E-Way compliance audit verdict"
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    }
  }
}