{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Power Expert India Verified Tariff API", "version": "1.2.0-solar-candidate", "summary": "Verified electricity tariff API for Bihar and Maharashtra, with source evidence and fail-closed adjustment status.", "description": "Power Expert India Verified Tariff API. Bihar and Maharashtra verified base-tariff services. Maharashtra FY 2026-27 Phase 1 releases verified base-tariff calculation/reference coverage for MSEDCL, TPC-D, AEML and BEST. FAC/FPPPA/FPPAS/PPCA and Time-of-Day adjustments are not applied to the payable total in Maharashtra Phase 1. Subsidy, electricity duty, tax/cess, meter rent, arrears, penalties and miscellaneous ancillary bill components are excluded. The Maharashtra Phase 1 response must not be interpreted as exact utility-bill reproduction." }, "servers": [ { "url": "https://powerexpertindia.com/v1", "description": "Production" } ], "externalDocs": { "description": "Human-readable API documentation", "url": "https://powerexpertindia.com/v1/docs.php" }, "tags": [ { "name": "Service", "description": "Release identity, health, and state capability metadata." }, { "name": "Catalogue", "description": "Released states, categories and tariff rows." }, { "name": "Evidence", "description": "Public source traceability, subsidy entitlement, and historical FPPAS evidence." }, { "name": "Calculation", "description": "Verified base-tariff calculation with optional non-monetary subsidy-entitlement summary." } ], "security": [ { "XApiKey": [] }, { "BearerAuth": [] } ], "paths": { "/health": { "get": { "tags": [ "Service" ], "summary": "Health and release status", "operationId": "getHealth", "description": "Returns service-level health when state_code is omitted. Use state_code=BR or state_code=MH for state-specific release health.", "x-required-scope": "health:read", "responses": { "200": { "description": "Healthy verified release.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": { "service_status": "healthy", "release_status": "released", "production_serving_enabled": true, "release_stage": "public_access_v1", "release_id": "BR-2026-27-VERIFIED-STRICT-BASE-V1", "state_code": "BR", "financial_year": "2026-27", "effective_from": "2026-04-01", "verification_tier": "verified_strict", "schedule_rows": 34, "supported_subcategories": 32, "regression_cases": 45, "runtime_gate_checks": { "passed": 29, "total": 29 }, "release_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }, "meta": { "calculation_scope": "verified_base_tariff", "exact_current_net_bill": false } } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_KEY_REQUIRED", "message": "A valid API key is required." } } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_SCOPE_DENIED", "message": "The API client does not have permission for this route." } } } } }, "405": { "description": "Unsupported HTTP method.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "METHOD_NOT_ALLOWED", "message": "Allowed method: GET." } } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The API request rate limit has been exceeded.", "details": { "limit": 60, "remaining": 0, "reset_epoch": 1784332800, "retry_after_seconds": 1, "reason": "burst_limit" } } } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "The API request could not be completed." } } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "VERIFIED_RUNTIME_UNAVAILABLE", "message": "Required verified serving evidence is unavailable." } } } } } } } }, "/capabilities": { "get": { "tags": [ "Service" ], "summary": "Get Bihar API capabilities", "operationId": "getStateCapabilities", "description": "Returns an explicit fail-closed capability matrix for Bihar, including base-tariff calculation, non-monetary subsidy entitlement, historical FPPAS evidence, and blocked components.", "x-required-scope": "health:read", "parameters": [ { "name": "state_code", "in": "query", "required": false, "description": "State code. This OpenAPI contract documents the Bihar response.", "schema": { "type": "string", "enum": [ "BR" ], "default": "BR", "maxLength": 2 }, "example": "BR" } ], "responses": { "200": { "description": "Bihar capability matrix.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": { "state_code": "BR", "controller_version": "PEI Unified Bihar + Maharashtra Controller V2.2.8", "api_version": "PEI Verified Tariff API V1.2.0", "release_status": "released", "financial_year": "2026-27", "effective_from": "2026-04-01", "capabilities": { "base_tariff_calculation": { "status": "enabled", "route": "POST /v1/calculate", "schedule_rows": 34, "supported_subcategories": 32, "money_mode": "integer_paise" }, "subsidy_entitlement": { "status": "enabled_non_monetary", "route": "GET /v1/subsidy-entitlement", "calculate_summary_enabled": true, "billing_days_input": "optional", "supported_billing_days": [ 25, 30, 40 ], "generic_rounding_status": "not_verified_fail_closed", "source_evidence_integrity": "verified_server_pdf_sha256", "source_document_sha256": "e03d2e66ab847622256670c109edad3e0391882721c32b4d1479edd8e1d27fcc", "source_document_size_bytes": 1884287, "monetary_subsidy_included": false, "base_tariff_amount_adjusted": false }, "fppas": { "status": "historical_evidence_available_current_blocked", "route": "GET /v1/fppas-periods", "historical_period_records": 4, "current_rate_released": false, "rate_applied_in_calculate": false, "reason": "current_numeric_regime_not_verified" }, "statutory_levies": { "status": "blocked", "reason": "verified_rates_not_in_release" }, "exact_current_net_bill": { "status": "blocked" } }, "blocked_components": [ "monetary_subsidy_amount", "generic_subsidy_proration_rounding", "current_fppas_numeric_regime", "corrigendum_composition", "statutory_levies", "exact_current_net_bill" ] }, "meta": { "capability_contract": "state_aware_fail_closed_v1", "calculation_scope": "verified_base_tariff_plus_optional_non_monetary_subsidy_entitlement" } } } } }, "400": { "description": "The request or a query parameter is invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The requested state-specific contract is not released.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Unsupported HTTP method.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/states": { "get": { "tags": [ "Catalogue" ], "summary": "List released states", "operationId": "listStates", "description": "Returns states approved for verified-strict public serving. V1 currently returns Bihar only.", "x-required-scope": "states:read", "responses": { "200": { "description": "Released state list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatesEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": [ { "state_code": "BR", "state_name": "Bihar", "financial_year": "2026-27", "effective_from": "2026-04-01", "verification_tier": "verified_strict", "release_status": "released", "supported_subcategories": 32, "schedule_rows": 34 } ], "meta": { "count": 1 } } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_KEY_REQUIRED", "message": "A valid API key is required." } } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_SCOPE_DENIED", "message": "The API client does not have permission for this route." } } } } }, "405": { "description": "Allowed method: GET.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "METHOD_NOT_ALLOWED", "message": "Allowed method: GET." } } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The API request rate limit has been exceeded.", "details": { "limit": 60, "remaining": 0, "reset_epoch": 1784332800, "retry_after_seconds": 1, "reason": "burst_limit" } } } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "The API request could not be completed." } } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "VERIFIED_RUNTIME_UNAVAILABLE", "message": "Required verified serving evidence is unavailable." } } } } } } } }, "/categories": { "get": { "tags": [ "Catalogue" ], "summary": "List verified categories", "operationId": "listCategories", "description": "Lists verified tariff categories. For Maharashtra, licensee_code is required and the response is backed by the verified statewide Reference API.", "x-required-scope": "categories:read", "parameters": [ { "name": "state_code", "in": "query", "required": false, "description": "State code. Supported: BR and MH. Bihar remains the default where the endpoint permits omission; Maharashtra requests require explicit licensee selection where applicable.", "schema": { "type": "string", "enum": [ "BR", "MH" ], "default": "BR", "maxLength": 2 }, "example": "MH" }, { "name": "effective_on", "in": "query", "required": false, "description": "Exact YYYY-MM-DD date on or after 2026-04-01. Omission resolves to the release effective date.", "schema": { "type": "string", "format": "date", "maxLength": 10 }, "example": "2026-04-01" }, { "name": "licensee_code", "in": "query", "required": false, "description": "Required when state_code=MH. Supported canonical values: MH_MSEDCL, MH_TPCD, MH_AEML, MH_BEST. No automatic MSEDCL fallback.", "schema": { "type": "string", "enum": [ "MH_MSEDCL", "MH_TPCD", "MH_AEML", "MH_BEST" ] }, "example": "MH_AEML" }, { "name": "financial_year", "in": "query", "required": false, "description": "Maharashtra verified tariff financial year. Current public verified release: 2026-27.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "example": "2026-27" } ], "responses": { "200": { "description": "Verified category catalogue.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoriesEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": [ { "state_code": "BR", "financial_year": "2026-27", "effective_from": "2026-04-01", "state_subcategory_code": "BR_DS_II", "raw_category_label": "Domestic Service-II", "canonical_category_code": "DOMESTIC_GENERAL", "layer": "domestic", "supply_type": "low_tension", "slab_type": "flat", "schedule_row_count": 1, "required_calculation_inputs": [ "energy_units", "connected_load" ], "optional_calculation_inputs": [ "tod_period", "rts_voltage_mode", "apply_htss_11kv_surcharge", "effective_on" ], "verification_tier": "verified_strict" } ], "meta": { "state_code": "BR", "count": 32, "effective_on": "2026-04-01" } } } } }, "400": { "description": "Query parameter is too long.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INVALID_QUERY_PARAMETER", "message": "Query parameter is too long." } } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_KEY_REQUIRED", "message": "A valid API key is required." } } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_SCOPE_DENIED", "message": "The API client does not have permission for this route." } } } } }, "404": { "description": "Only Bihar (BR) is released in this serving build.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "STATE_NOT_RELEASED", "message": "Only Bihar (BR) is released in this serving build." } } } } }, "405": { "description": "Allowed method: GET.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "METHOD_NOT_ALLOWED", "message": "Allowed method: GET." } } } } }, "422": { "description": "effective_on must use YYYY-MM-DD.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INVALID_EFFECTIVE_DATE", "message": "effective_on must use YYYY-MM-DD." } } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The API request rate limit has been exceeded.", "details": { "limit": 60, "remaining": 0, "reset_epoch": 1784332800, "retry_after_seconds": 1, "reason": "burst_limit" } } } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "The API request could not be completed." } } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "VERIFIED_RUNTIME_UNAVAILABLE", "message": "Required verified serving evidence is unavailable." } } } } } } } }, "/tariffs": { "get": { "tags": [ "Catalogue" ], "summary": "List verified tariff rows", "operationId": "listTariffs", "description": "Returns verified tariff metadata. Maharashtra requires explicit licensee_code and category_id and preserves source, fixture and row hash traceability.", "x-required-scope": "tariffs:read", "parameters": [ { "name": "state_code", "in": "query", "required": false, "description": "State code. Supported: BR and MH. Bihar remains the default where the endpoint permits omission; Maharashtra requests require explicit licensee selection where applicable.", "schema": { "type": "string", "enum": [ "BR", "MH" ], "default": "BR", "maxLength": 2 }, "example": "MH" }, { "name": "effective_on", "in": "query", "required": false, "description": "Exact YYYY-MM-DD date on or after 2026-04-01. Omission resolves to the release effective date.", "schema": { "type": "string", "format": "date", "maxLength": 10 }, "example": "2026-04-01" }, { "name": "subcategory_code", "in": "query", "required": false, "description": "Case-insensitive exact state subcategory code.", "schema": { "type": "string", "maxLength": 100 }, "example": "BR_DS_II" }, { "name": "supply_type", "in": "query", "required": false, "description": "Case-insensitive exact supply-type filter.", "schema": { "type": "string", "maxLength": 50 }, "example": "low_tension" }, { "name": "area_type", "in": "query", "required": false, "description": "Case-insensitive exact area applicability filter.", "schema": { "type": "string", "maxLength": 50 }, "example": "urban" }, { "name": "licensee_code", "in": "query", "required": false, "description": "Required when state_code=MH. Supported: MH_MSEDCL, MH_TPCD, MH_AEML, MH_BEST.", "schema": { "type": "string", "enum": [ "MH_MSEDCL", "MH_TPCD", "MH_AEML", "MH_BEST" ] }, "example": "MH_AEML" }, { "name": "category_id", "in": "query", "required": false, "description": "Required when state_code=MH. Use the canonical category_id returned by GET /categories.", "schema": { "type": "string", "maxLength": 100 }, "example": "HT_INDUSTRY" }, { "name": "financial_year", "in": "query", "required": false, "description": "Maharashtra verified tariff financial year. Current public verified release: 2026-27.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "example": "2026-27" } ], "responses": { "200": { "description": "Verified tariff rows.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TariffsEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": [ { "state_code": "BR", "financial_year": "2026-27", "state_subcategory_code": "BR_DS_II", "raw_category_label": "Domestic Service-II", "supply_type": "low_tension", "slab_type": "flat", "slab_from": 0, "slab_to": null, "energy_rate_paise": 742, "energy_rate_paise_rupees": "7.42", "fixed_charge_paise": 8000, "fixed_charge_paise_rupees": "80.00", "fixed_charge_basis": "per_kw_or_part_per_month", "verification_tier": "verified_strict", "source_ref": "src_0123456789abcdef0123" } ], "meta": { "state_code": "BR", "count": 1, "effective_on": "2026-04-01", "filters": { "subcategory_code": "BR_DS_II", "supply_type": null, "area_type": null } } } } } }, "400": { "description": "Query parameter is too long.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INVALID_QUERY_PARAMETER", "message": "Query parameter is too long." } } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_KEY_REQUIRED", "message": "A valid API key is required." } } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_SCOPE_DENIED", "message": "The API client does not have permission for this route." } } } } }, "404": { "description": "Only Bihar (BR) is released in this serving build.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "STATE_NOT_RELEASED", "message": "Only Bihar (BR) is released in this serving build." } } } } }, "405": { "description": "Allowed method: GET.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "METHOD_NOT_ALLOWED", "message": "Allowed method: GET." } } } } }, "422": { "description": "effective_on must use YYYY-MM-DD.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INVALID_EFFECTIVE_DATE", "message": "effective_on must use YYYY-MM-DD." } } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The API request rate limit has been exceeded.", "details": { "limit": 60, "remaining": 0, "reset_epoch": 1784332800, "retry_after_seconds": 1, "reason": "burst_limit" } } } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "The API request could not be completed." } } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "VERIFIED_RUNTIME_UNAVAILABLE", "message": "Required verified serving evidence is unavailable." } } } } } } } }, "/subsidy-entitlement": { "get": { "tags": [ "Evidence" ], "summary": "Evaluate the Bihar 125-unit subsidy entitlement", "operationId": "getBiharSubsidyEntitlement", "description": "Returns the verified non-monetary Bihar domestic entitlement contract. Only the official 25, 30, and 40-day examples are executable. Other billing-day counts fail closed because the generic rounding rule is not verified.", "x-required-scope": "tariffs:read", "parameters": [ { "name": "state_code", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BR" ], "default": "BR", "maxLength": 2 }, "description": "Released state code.", "example": "BR" }, { "name": "consumer_class", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "domestic" ], "default": "domestic", "maxLength": 30 }, "description": "Only domestic consumers are covered.", "example": "domestic" }, { "name": "billing_days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366 }, "description": "Optional. Executable values are 25, 30, and 40 only.", "example": 30 }, { "name": "consumption_units", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "description": "Optional whole units. Requires billing_days when supplied.", "example": 126 } ], "responses": { "200": { "description": "Verified non-monetary subsidy-entitlement contract.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubsidyEntitlementEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": { "state_code": "BR", "scheme_code": "BR_MVUSY_DOMESTIC_125", "contract_version": "PEI Bihar Subsidy Entitlement Contract V1.0.0", "verification_tier": "verified_rule_contract", "consumer_scope": { "consumer_class": "domestic", "discoms": [ "NBPDCL", "SBPDCL" ], "area_types": [ "urban", "rural" ], "tenant_eligible_with_valid_consumer_account": true }, "entitlement": { "base_entitlement_units": 125, "standard_billing_days": 30, "pro_rata_required": true, "generic_rounding_mode": null, "generic_rounding_status": "not_verified_fail_closed", "official_examples": [ { "billing_days": 25, "entitlement_units": 104 }, { "billing_days": 30, "entitlement_units": 125 }, { "billing_days": 40, "entitlement_units": 167 } ] }, "included_subsidy_components": [ "energy_charge", "fixed_charge", "electricity_duty" ], "excess_consumption_contract": { "first_entitlement_units_fully_subsidised": true, "excess_units_billable": true, "electricity_duty_on_excess_units": true, "fixed_charge_reappears_when_entitlement_exceeded": true, "fy_2026_27_excess_category_rate_contract": null }, "evaluation": { "billing_days": 30, "entitlement_units": 125, "contract_application": "official_example_exact_match", "monetary_calculation_performed": false, "consumption_units": 126, "subsidised_units": 125, "chargeable_units": 1 }, "blocked": [ "generic_pro_rata_rounding_for_other_billing_days", "fy_2026_27_excess_category_monetary_rates", "monetary_subsidy_amount", "current_fppas_numeric_regime" ], "source_contract": { "source_id": "BR_SUBSIDY_MVUSY_FAQ_2025", "authority": "Bihar State Power Holding Company Limited", "official_url": "https://www.bsphcl.co.in/Downloads/MYVSY2025.pdf", "reviewed_pages": [ 1, 2, 3, 4 ], "source_document_sha256": "e03d2e66ab847622256670c109edad3e0391882721c32b4d1479edd8e1d27fcc", "source_document_hash_status": "verified_server_acquisition_magic_bytes_and_sha256", "source_document_content_type": "application/pdf", "source_document_size_bytes": 1884287, "source_document_magic_verified": true, "source_document_page_count": null, "source_document_page_count_status": "not_detected_non_blocking", "source_contract_sha256": "cfcc2bcbb6417f2c1bafdf8bb63419fb66fc230fdc589573c9bbeac33513a9fa", "source_verifier_file_sha256": "7176220711421d7e7bb45b28a87bc8467d8ec0ffd4745142f64fd755923250f9", "source_contract_gates": { "passed": 17, "total": 17 }, "fixture_cases": { "passed": 8, "total": 8 } }, "disclosure": { "entitlement_units_only": true, "monetary_subsidy_included": false, "fppas_included": false, "exact_current_net_bill": false } }, "meta": { "state_code": "BR", "calculation_scope": "non_monetary_subsidy_entitlement_only", "controller_version": "PEI Unified Bihar + Maharashtra Controller V2.2.8" } } } } }, "400": { "description": "The request or a query parameter is invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The requested state-specific contract is not released.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Unsupported HTTP method.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "A semantic input or fail-closed contract rule rejected the request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/fppas-periods": { "get": { "tags": [ "Evidence" ], "summary": "List verified historical Bihar FPPAS periods", "operationId": "listBiharHistoricalFppasPeriods", "description": "Returns frozen historical FPPAS evidence records. This endpoint is not a current-rate resolver and never applies a historical percentage to a bill.", "x-required-scope": "tariffs:read", "parameters": [ { "name": "state_code", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BR" ], "default": "BR", "maxLength": 2 }, "description": "Released state code.", "example": "BR" }, { "name": "period_month", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:19|20)[0-9]{2}-(?:0[1-9]|1[0-2])$", "maxLength": 7 }, "description": "Optional exact calculation month in YYYY-MM.", "example": "2026-01" }, { "name": "recovery_month", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:19|20)[0-9]{2}-(?:0[1-9]|1[0-2])$", "maxLength": 7 }, "description": "Optional exact recovery month in YYYY-MM.", "example": "2026-03" }, { "name": "authority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NBPDCL", "SBPDCL" ], "maxLength": 20 }, "description": "Optional official publishing authority filter.", "example": "SBPDCL" } ], "responses": { "200": { "description": "Historical FPPAS evidence catalogue.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FppasPeriodsEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": { "state_code": "BR", "contract_version": "PEI Bihar FPPAS Historical Period Evidence Contract V1.0.0", "status": "historical_evidence_available_current_regime_blocked", "records": [ { "artifact_id": "BR_NBPDCL_FPPAS_AUG_2025", "authority": "NBPDCL", "title": "FPPAS Calculation for Month of August 2025", "period_month": "2025-08", "rate_percent_string": "-5.35", "rate_basis_points": -535, "recovery_month": null, "recovery_month_status": "not_frozen", "discom_scope": [ "NBPDCL", "SBPDCL" ], "consumer_category_scope": [], "scope_status": "partial_official_evidence", "source_url": "https://nbpdcl.co.in/FPPAS_PDF/13/K.%209954/FPPAS_AUGUST-2025.PDF", "source_document_sha256": "bd6ab882e734e161f6b8444b4e24a2caeb1578108621a2ae9bf7fa4421e94bba", "source_pages": [ 2 ], "calculation_use": "historical_evidence_only_not_applied", "negative_rate_treatment": "not_released_for_production_calculation" }, { "artifact_id": "BR_SBPDCL_FPPAS_JAN_2026", "authority": "SBPDCL", "title": "FPPAS Calculation for January 2026", "period_month": "2026-01", "rate_percent_string": "-5.91", "rate_basis_points": -591, "recovery_month": "2026-03", "recovery_month_status": "derived_from_official_n_plus_2_rule", "discom_scope": [ "NBPDCL", "SBPDCL" ], "consumer_category_scope": [], "scope_status": "partial_official_evidence", "source_url": "https://www.sbpdcl.co.in/frmEnergyAccounting.aspx", "source_document_sha256": "3c1f8b22122bec13e05bd1a74a5a4b1e7b87ecba72e156ea053f49ecbd01df0c", "source_pages": [ 2, 3 ], "calculation_use": "historical_evidence_only_not_applied", "negative_rate_treatment": "not_released_for_production_calculation" } ], "record_count": 2, "available_period_months": [ "2025-08", "2026-01", "2026-02", "2026-03" ], "filters": { "period_month": null, "recovery_month": null, "authority": null }, "current_selection": { "billing_month": "2026-07", "required_calculation_month": "2026-05", "matching_historical_record_found": false, "current_rate_released": false, "current_fppas_engine_ready": false, "reason": "no_approved_current_period_scope_and_negative_rate_contract" }, "source_integrity": [ { "source_document_sha256": "bd6ab882e734e161f6b8444b4e24a2caeb1578108621a2ae9bf7fa4421e94bba", "periods": [ "2025-08" ], "pdf_magic_verified": true }, { "source_document_sha256": "3c1f8b22122bec13e05bd1a74a5a4b1e7b87ecba72e156ea053f49ecbd01df0c", "periods": [ "2026-01", "2026-02", "2026-03" ], "pdf_magic_verified": true } ], "blocked_components": [ "current_applicable_fppas_rate", "consumer_category_scope", "negative_rate_bill_treatment", "regime_resolver_selection", "exact_current_net_bill" ], "disclosure": { "historical_evidence_only": true, "rate_applied_to_bill": false, "current_rate_inferred": false, "monetary_calculation_performed": false } }, "meta": { "state_code": "BR", "calculation_scope": "historical_fppas_evidence_only", "controller_version": "PEI Unified Bihar + Maharashtra Controller V2.2.8" } } } } }, "400": { "description": "The request or a query parameter is invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The requested state-specific contract is not released.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Unsupported HTTP method.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "A semantic input or fail-closed contract rule rejected the request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sources": { "get": { "tags": [ "Evidence" ], "summary": "List public source evidence", "operationId": "listSources", "description": "Returns approved traceability metadata and schedule-row mappings without raw evidence bodies or server paths.", "x-required-scope": "sources:read", "parameters": [ { "name": "state_code", "in": "query", "required": false, "description": "State code. Use BR for Bihar or MH for Maharashtra. Maharashtra requires explicit licensee selection and statewide expansion may remain production-gated.", "schema": { "type": "string", "enum": [ "BR" ], "default": "BR", "maxLength": 2 }, "example": "BR" } ], "responses": { "200": { "description": "Public source catalogue.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcesEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": [ { "source_ref": "src_0123456789abcdef0123", "order_title": "Bihar Electricity Regulatory Commission Tariff Order FY 2026-27", "financial_year": "2026-27", "effective_from": "2026-04-01", "verification_tier": "verified_strict", "state_code": "BR", "release_id": "BR-2026-27-VERIFIED-STRICT-BASE-V1", "mapped_subcategory_codes": [ "BR_DS_II" ], "mapped_category_labels": [ "Domestic Service-II" ], "mapped_section_numbers": [ "7.2" ], "mapped_schedule_row_count": 1 } ], "meta": { "state_code": "BR", "verification_tier": "verified_strict", "source_ref_count": 1, "schedule_rows_mapped": 34, "source_raw_text_sha256": "5eb6372da3332efbd9d2e8c98882bbefe75bcb502771795b09425389da8307ac" } } } } }, "400": { "description": "Query parameter is too long.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INVALID_QUERY_PARAMETER", "message": "Query parameter is too long." } } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_KEY_REQUIRED", "message": "A valid API key is required." } } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_SCOPE_DENIED", "message": "The API client does not have permission for this route." } } } } }, "404": { "description": "Only Bihar (BR) is released in this serving build.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "STATE_NOT_RELEASED", "message": "Only Bihar (BR) is released in this serving build." } } } } }, "405": { "description": "Allowed method: GET.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "METHOD_NOT_ALLOWED", "message": "Allowed method: GET." } } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The API request rate limit has been exceeded.", "details": { "limit": 60, "remaining": 0, "reset_epoch": 1784332800, "retry_after_seconds": 1, "reason": "burst_limit" } } } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "The API request could not be completed." } } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "VERIFIED_RUNTIME_UNAVAILABLE", "message": "Required verified serving evidence is unavailable." } } } } } } } }, "/calculate": { "post": { "tags": [ "Calculation" ], "summary": "Calculate a verified base-tariff estimate", "operationId": "calculateBaseTariff", "description": "Calculates deterministic verified tariff results for released Bihar and Maharashtra coverage. Maharashtra supports MSEDCL, TPC-D, AEML and BEST verified FY 2026-27 base tariffs. FAC/FPPPA and payable ToD are not yet included in the Maharashtra payable total. Subsidy, tax, duty and cess are excluded unless a response explicitly states otherwise. The result is not claimed to be an exact utility bill.", "x-required-scope": "calculate:write", "x-max-request-body-bytes": 65536, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationRequest" }, "examples": { "domestic_ds_ii": { "summary": "DS-II, 100 units, 2 kW connected load", "value": { "state_code": "BR", "subcategory_code": "BR_DS_II", "energy_units": 100, "connected_load": "2" } }, "billing_demand": { "summary": "Demand-based category", "value": { "state_code": "BR", "subcategory_code": "BR_LTIS_I", "energy_units": 100, "recorded_demand": "11", "contract_demand": "10" } }, "domestic_ds_ii_with_subsidy_entitlement": { "summary": "DS-II, 126 units, 1 kW, official 30-day entitlement example", "value": { "state_code": "BR", "subcategory_code": "BR_DS_II", "energy_units": 126, "connected_load": "1", "billing_days": 30 } }, "maharashtra_aeml_ht_industry": { "summary": "Maharashtra AEML HT Industry verified base tariff", "value": { "state_code": "MH", "licensee_code": "MH_AEML", "financial_year": "2026-27", "category_id": "HT_INDUSTRY", "billing_demand_kva": 400, "consumption_kvah": 10000, "billing_date": "2026-08-10" } } } } } }, "responses": { "200": { "description": "Verified calculation response. Bihar responses include final_payable, electricity_duty and ancillary_charges fail-closed contracts.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationEnvelope" }, "example": { "status": "ok", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "data": { "state_code": "BR", "subcategory_code": "BR_DS_II", "category_label": "Domestic Service-II", "layer": "domestic", "financial_year": "2026-27", "effective_on": "2026-04-01", "verification_tier": "verified_strict", "calculation_scope": "verified_base_tariff_plus_non_monetary_subsidy_entitlement", "input": { "energy_units": 126, "connected_load": "1", "recorded_demand": "0", "contract_demand": "0", "tod_period": "", "rts_voltage_mode": "standard", "apply_htss_11kv_surcharge": false }, "result": { "energy_charge_paise": 93492, "energy_charge_paise_rupees": "934.92", "fixed_charge_paise": 8000, "fixed_charge_paise_rupees": "80.00", "demand_charge_paise": 0, "demand_charge_paise_rupees": "0.00", "excess_demand_charge_paise": 0, "excess_demand_charge_paise_rupees": "0.00", "tod_adjustment_paise": 0, "tod_adjustment_paise_rupees": "0.00", "special_adjustment_paise": 0, "special_adjustment_paise_rupees": "0.00", "base_total_paise": 101492, "base_total_paise_rupees": "1014.92", "currency": "INR", "integer_paise_only": true }, "source_refs": [ "src_0123456789abcdef0123" ], "disclosure": { "estimate_not_utility_bill": true, "subsidy_entitlement_contract_included": true, "subsidy_entitlement_evaluated": true, "subsidy_included": false, "monetary_subsidy_included": false, "base_total_reduced_for_subsidy": false, "fpppa_included": false, "corrigendum_composition_included": false, "exact_current_net_bill": false }, "coverage_status": "production_ready", "subsidy_entitlement": { "status": "evaluated_non_monetary", "scheme_code": "BR_MVUSY_DOMESTIC_125", "verification_tier": "verified_rule_contract", "billing_days": 30, "entitlement_units": 125, "consumption_units": 126, "subsidised_units": 125, "chargeable_units": 1, "contract_application": "official_example_exact_match", "generic_rounding_mode": null, "monetary_subsidy_amount_paise": null, "monetary_calculation_performed": false, "base_tariff_amount_adjusted_for_subsidy": false, "fppas_included": false, "source_contract_sha256": "cfcc2bcbb6417f2c1bafdf8bb63419fb66fc230fdc589573c9bbeac33513a9fa" }, "included_components": [ "energy_charge", "verified_fixed_or_demand_charge", "verified_category_specific_adjustments", "non_monetary_subsidy_entitlement_contract" ], "excluded_components": [ "monetary_subsidy_amount", "fppas_fpppa", "corrigendum_composition", "statutory_levies" ] }, "meta": { "release_id": "BR-2026-27-VERIFIED-STRICT-BASE-V1", "release_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "controller_version": "PEI Unified Bihar + Maharashtra Controller V2.2.8" } } } } }, "400": { "description": "The JSON request body is invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INVALID_JSON", "message": "The JSON request body is invalid." } } } } }, "401": { "description": "Authentication failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_KEY_REQUIRED", "message": "A valid API key is required." } } } } }, "403": { "description": "The key, state, scope, or browser origin is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "API_SCOPE_DENIED", "message": "The API client does not have permission for this route." } } } } }, "404": { "description": "The requested Bihar subcategory is not in the verified release.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "SUBCATEGORY_NOT_FOUND", "message": "The requested Bihar subcategory is not in the verified release." } } } } }, "405": { "description": "Allowed method: POST.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "METHOD_NOT_ALLOWED", "message": "Allowed method: POST." } } } } }, "409": { "description": "A tariff variant selector is required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "AMBIGUOUS_TARIFF_VARIANT", "message": "A tariff variant selector is required." } } } } }, "413": { "description": "JSON request body is too large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "REQUEST_BODY_TOO_LARGE", "message": "JSON request body is too large." } } } } }, "415": { "description": "Use Content-Type: application/json.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Use Content-Type: application/json." } } } } }, "422": { "description": "Calculation input is outside the allowed range.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INVALID_CALCULATION_INPUT", "message": "Calculation input is outside the allowed range." } } } } }, "429": { "description": "The configured per-minute or burst allowance was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The API request rate limit has been exceeded.", "details": { "limit": 60, "remaining": 0, "reset_epoch": 1784332800, "retry_after_seconds": 1, "reason": "burst_limit" } } } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "The API request could not be completed." } } } } }, "503": { "description": "The verified release, key registry, or runtime evidence is unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "api_version": "PEI Verified Tariff API V1.2.0", "request_id": "req_0123456789abcdef", "error": { "code": "VERIFIED_RUNTIME_UNAVAILABLE", "message": "Required verified serving evidence is unavailable." } } } } } } } }, "/solar-savings": { "post": { "summary": "Calculate a verified Bihar domestic before/after solar base-tariff comparison", "operationId": "calculateSolarSavingsBaseline", "security": [ { "XApiKey": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolarSavingsRequest" } } } }, "responses": { "200": { "description": "Verified solar savings baseline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolarSavingsResponse" } } } }, "401": { "description": "Authentication failed" }, "403": { "description": "Scope or state access denied" }, "404": { "description": "State/category not covered" }, "409": { "description": "Release mismatch" }, "422": { "description": "Invalid request" }, "429": { "description": "Rate or quota limit exceeded" } }, "x-required-scope": "calculate:write", "x-max-request-body-bytes": 65536, "description": "When billing_month is supplied, the verified Bihar FPPAS engine is applied independently to the before-solar and after-solar base calculations. If no approved executable FPPAS version is available, the response remains successful and explicitly falls back to the verified base-tariff comparison. The response evaluates the existing Bihar non-monetary subsidy-entitlement contract independently for before-solar and after-solar consumption. It does not calculate or deduct a monetary subsidy amount from the tariff result." } }, "/category-resolver": { "post": { "tags": [ "Calculation" ], "summary": "Resolve a caller-declared Bihar domestic class", "description": "Maps a caller-supplied domestic classification to an exact verified Bihar tariff subcategory. The API does not determine lifeline, scheme or government eligibility.", "operationId": "resolveBiharDomesticCategory", "security": [ { "XApiKey": [] }, { "BearerAuth": [] } ], "x-required-scope": "calculate:write", "x-max-request-body-bytes": 65536, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryResolverRequest" } } } }, "responses": { "200": { "description": "Verified category resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryResolverResponse" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope or state access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "State or consumer type not covered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Release mismatch or ambiguous resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate or quota limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "XApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Dedicated PEI client key. Never place it in a URL or query string." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "PEI API key", "description": "Alternative header form: Authorization: Bearer ." } }, "headers": { "XRequestId": { "description": "Traceable request identifier mirrored in the JSON envelope.", "schema": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$" } }, "XRateLimitLimit": { "description": "Configured per-minute limit for the authenticated key.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitRemaining": { "description": "Remaining accepted requests in the active minute window.", "schema": { "type": "integer", "minimum": 0 } }, "XRateLimitReset": { "description": "Unix epoch when the oldest active request leaves the minute window.", "schema": { "type": "integer", "minimum": 0 } }, "RetryAfter": { "description": "Seconds to wait before retrying a rate-limited request.", "schema": { "type": "integer", "minimum": 1 } } }, "schemas": { "SuccessEnvelope": { "type": "object", "required": [ "status", "api_version", "request_id", "data", "meta" ], "properties": { "status": { "type": "string", "const": "ok" }, "api_version": { "type": "string", "const": "PEI Verified Tariff API V1.2.0" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$" }, "data": [], "meta": { "type": "object" } } }, "ErrorEnvelope": { "type": "object", "required": [ "status", "api_version", "request_id", "error" ], "properties": { "status": { "type": "string", "const": "error" }, "api_version": { "type": "string", "const": "PEI Verified Tariff API V1.2.0" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$" }, "error": { "$ref": "#/components/schemas/ApiError" } } }, "ApiError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9_]+$" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } }, "HealthData": { "type": "object", "required": [ "service_status", "release_status", "production_serving_enabled", "release_stage", "release_id", "state_code", "financial_year", "effective_from", "verification_tier", "schedule_rows", "supported_subcategories", "regression_cases", "runtime_gate_checks", "release_sha256" ], "properties": { "service_status": { "type": "string", "const": "healthy" }, "release_status": { "type": "string", "const": "released" }, "production_serving_enabled": { "type": "boolean", "const": true }, "release_stage": { "type": "string", "const": "public_access_v1" }, "release_id": { "type": "string", "const": "BR-2026-27-VERIFIED-STRICT-BASE-V1" }, "state_code": { "type": "string", "const": "BR" }, "financial_year": { "type": "string", "const": "2026-27" }, "effective_from": { "type": "string", "format": "date", "const": "2026-04-01" }, "verification_tier": { "type": "string", "const": "verified_strict" }, "schedule_rows": { "type": "integer", "const": 34 }, "supported_subcategories": { "type": "integer", "const": 32 }, "regression_cases": { "type": "integer", "const": 45 }, "runtime_gate_checks": { "$ref": "#/components/schemas/RuntimeGateChecks" }, "release_sha256": { "$ref": "#/components/schemas/Sha256" } } }, "RuntimeGateChecks": { "type": "object", "required": [ "passed", "total" ], "properties": { "passed": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "StateSummary": { "type": "object", "required": [ "state_code", "state_name", "financial_year", "effective_from", "verification_tier", "release_status", "supported_subcategories", "schedule_rows" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "state_name": { "type": "string", "const": "Bihar" }, "financial_year": { "type": "string", "const": "2026-27" }, "effective_from": { "type": "string", "format": "date" }, "verification_tier": { "type": "string", "const": "verified_strict" }, "release_status": { "type": "string", "const": "released" }, "supported_subcategories": { "type": "integer", "const": 32 }, "schedule_rows": { "type": "integer", "const": 34 } } }, "CategorySummary": { "type": "object", "required": [ "state_code", "financial_year", "effective_from", "state_subcategory_code", "raw_category_label", "layer", "supply_type", "slab_type", "schedule_row_count", "required_calculation_inputs", "optional_calculation_inputs", "verification_tier" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "financial_year": { "type": "string" }, "effective_from": { "type": "string", "format": "date" }, "state_subcategory_code": { "type": "string", "maxLength": 100 }, "raw_category_label": { "type": "string" }, "canonical_category_code": { "type": [ "string", "null" ] }, "layer": { "type": "string", "enum": [ "domestic", "lt", "ht" ] }, "supply_type": { "type": "string" }, "slab_type": { "type": "string", "enum": [ "flat", "telescopic", "non_telescopic" ] }, "schedule_row_count": { "type": "integer", "minimum": 1 }, "required_calculation_inputs": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "optional_calculation_inputs": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "verification_tier": { "type": "string", "const": "verified_strict" } } }, "TariffRow": { "type": "object", "description": "Public verified schedule row. Exact fields vary by domestic, LT and HT tariff layer. Raw evidence bodies, text windows and filesystem paths are never exposed.", "required": [ "state_subcategory_code", "raw_category_label", "verification_tier", "source_ref" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "financial_year": { "type": "string" }, "state_subcategory_code": { "type": "string" }, "raw_category_label": { "type": "string" }, "canonical_category_code_hint": { "type": [ "string", "null" ] }, "supply_type": { "type": "string" }, "area_type": { "type": [ "string", "null" ] }, "slab_type": { "type": "string" }, "slab_from": { "type": [ "integer", "null" ] }, "slab_to": { "type": [ "integer", "null" ] }, "energy_rate_paise": { "type": [ "integer", "null" ], "minimum": 0 }, "energy_rate_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "energy_rate_paise_per_kvah": { "type": [ "integer", "null" ], "minimum": 0 }, "energy_rate_paise_per_kvah_rupees": { "$ref": "#/components/schemas/RupeeString" }, "fixed_charge_paise": { "type": [ "integer", "null" ], "minimum": 0 }, "fixed_charge_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "fixed_charge_basis": { "type": [ "string", "null" ] }, "demand_charge_paise_per_kva_month": { "type": [ "integer", "null" ], "minimum": 0 }, "demand_charge_paise_per_kva_month_rupees": { "$ref": "#/components/schemas/RupeeString" }, "section_number": { "type": [ "string", "null" ] }, "verification_tier": { "type": "string", "const": "verified_strict" }, "source_ref": { "type": "string", "pattern": "^src_[A-Za-z0-9_]+$" } }, "additionalProperties": true }, "SourceRecord": { "type": "object", "required": [ "source_ref", "state_code", "financial_year", "verification_tier", "release_id", "mapped_subcategory_codes", "mapped_category_labels", "mapped_section_numbers", "mapped_schedule_row_count" ], "properties": { "source_ref": { "type": "string", "pattern": "^src_[A-Za-z0-9_]+$" }, "source_document_id": { "type": [ "integer", "string", "null" ] }, "document_id": { "type": [ "integer", "string", "null" ] }, "order_title": { "type": [ "string", "null" ] }, "order_number": { "type": [ "string", "null" ] }, "financial_year": { "type": "string" }, "effective_from": { "type": [ "string", "null" ], "format": "date" }, "effective_to": { "type": [ "string", "null" ], "format": "date" }, "page": { "type": [ "integer", "string", "null" ] }, "page_number": { "type": [ "integer", "string", "null" ] }, "table": { "type": [ "string", "null" ] }, "table_number": { "type": [ "string", "null" ] }, "clause": { "type": [ "string", "null" ] }, "clause_number": { "type": [ "string", "null" ] }, "verification_origin": { "type": [ "string", "null" ] }, "verification_tier": { "type": "string", "const": "verified_strict" }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "official_url": { "type": [ "string", "null" ], "format": "uri" }, "raw_text_sha256": { "oneOf": [ { "$ref": "#/components/schemas/Sha256" }, { "type": "null" } ] }, "evidence_sha256": { "oneOf": [ { "$ref": "#/components/schemas/Sha256" }, { "type": "null" } ] }, "state_code": { "type": "string", "const": "BR" }, "release_id": { "type": "string", "const": "BR-2026-27-VERIFIED-STRICT-BASE-V1" }, "release_source_raw_text_sha256": { "$ref": "#/components/schemas/Sha256" }, "mapped_subcategory_codes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "mapped_category_labels": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "mapped_section_numbers": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "mapped_schedule_row_count": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "CalculationRequest": { "type": "object", "required": [ "subcategory_code", "energy_units" ], "properties": { "state_code": { "type": "string", "enum": [ "BR", "MH" ], "default": "BR", "description": "BR for Bihar or MH for Maharashtra." }, "subcategory_code": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Exact code returned by GET /categories." }, "energy_units": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 100000000 }, { "type": "string", "pattern": "^\\d+$" } ], "description": "Non-negative whole units. Numeric strings are accepted by the current controller." }, "connected_load": { "$ref": "#/components/schemas/DecimalInput" }, "recorded_demand": { "$ref": "#/components/schemas/DecimalInput" }, "contract_demand": { "$ref": "#/components/schemas/DecimalInput" }, "tod_period": { "type": "string", "maxLength": 60, "default": "" }, "rts_voltage_mode": { "type": "string", "enum": [ "standard", "above_132kv", "below_132kv" ], "default": "standard" }, "apply_htss_11kv_surcharge": { "type": "boolean", "default": false }, "effective_on": { "type": "string", "format": "date", "description": "Must be on or after 2026-04-01." }, "billing_days": { "type": "integer", "minimum": 1, "maximum": 366, "description": "Optional for Bihar domestic categories. Only 25, 30, or 40 are currently accepted for subsidy-entitlement evaluation; every other value fails closed.", "examples": [ 30 ] }, "licensee_code": { "type": "string", "description": "Required for Maharashtra. Canonical values: MH_MSEDCL, MH_TPCD, MH_AEML, MH_BEST.", "enum": [ "MH_MSEDCL", "MH_TPCD", "MH_AEML", "MH_BEST" ] }, "financial_year": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "example": "2026-27" }, "category_id": { "type": "string", "maxLength": 100, "description": "Canonical Maharashtra category identifier returned by GET /categories." }, "consumption_kvah": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "number", "minimum": 0 }, { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" } ], "description": "Maharashtra kVAh consumption input where the verified tariff row bills on kVAh." }, "consumption_units": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "number", "minimum": 0 }, { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" } ], "description": "Maharashtra kWh consumption input where the verified tariff row bills on kWh." }, "billing_demand_kva": { "$ref": "#/components/schemas/DecimalInput" }, "billing_demand_kw": { "$ref": "#/components/schemas/DecimalInput" }, "billing_date": { "type": "string", "format": "date" } }, "additionalProperties": true, "description": "State-aware calculation contract. Bihar uses subcategory_code and energy_units plus category-specific load/demand inputs. Maharashtra requires explicit licensee_code and category_id, plus the billing-basis input required by the verified tariff row. No automatic kWh↔kVAh or kW↔kVA conversion is performed." }, "CalculationInputEcho": { "type": "object", "required": [ "energy_units", "connected_load", "recorded_demand", "contract_demand", "tod_period", "rts_voltage_mode", "apply_htss_11kv_surcharge" ], "properties": { "energy_units": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "connected_load": { "type": "string" }, "recorded_demand": { "type": "string" }, "contract_demand": { "type": "string" }, "tod_period": { "type": "string" }, "rts_voltage_mode": { "type": "string" }, "apply_htss_11kv_surcharge": { "type": "boolean" } } }, "CalculationResult": { "type": "object", "description": "Layer-specific deterministic result. Every integer field containing 'paise' is accompanied by a *_rupees two-decimal string.", "required": [ "base_total_paise", "base_total_paise_rupees", "currency", "integer_paise_only" ], "properties": { "energy_charge_normal_paise": { "type": "integer", "minimum": 0 }, "energy_charge_normal_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "energy_charge_paise": { "type": "integer", "minimum": 0 }, "energy_charge_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "fixed_charge_paise": { "type": "integer", "minimum": 0 }, "fixed_charge_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "fixed_or_demand_charge_paise": { "type": "integer", "minimum": 0 }, "fixed_or_demand_charge_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "demand_charge_paise": { "type": "integer", "minimum": 0 }, "demand_charge_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "excess_demand_charge_paise": { "type": "integer", "minimum": 0 }, "excess_demand_charge_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "tod_adjustment_paise": { "type": "integer" }, "tod_adjustment_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "special_adjustment_paise": { "type": "integer", "minimum": 0 }, "special_adjustment_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "energy_rate_paise_per_kvah_after_voltage_rule": { "type": "integer", "minimum": 0 }, "energy_rate_paise_per_kvah_after_voltage_rule_rupees": { "$ref": "#/components/schemas/RupeeString" }, "base_total_paise": { "type": "integer", "minimum": 0 }, "base_total_paise_rupees": { "$ref": "#/components/schemas/RupeeString" }, "billed_whole_load_or_demand": { "type": "integer", "minimum": 0 }, "billing_demand_whole_kva": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "const": "INR" }, "integer_paise_only": { "type": "boolean", "const": true } }, "additionalProperties": false }, "CalculationDisclosure": { "type": "object", "required": [ "estimate_not_utility_bill", "subsidy_included", "fpppa_included", "corrigendum_composition_included", "exact_current_net_bill", "subsidy_entitlement_contract_included", "subsidy_entitlement_evaluated", "monetary_subsidy_included", "base_total_reduced_for_subsidy" ], "properties": { "estimate_not_utility_bill": { "type": "boolean", "const": true }, "subsidy_included": { "type": "boolean", "const": false }, "fpppa_included": { "type": "boolean", "const": false }, "corrigendum_composition_included": { "type": "boolean", "const": false }, "exact_current_net_bill": { "type": "boolean", "const": false }, "subsidy_entitlement_contract_included": { "type": "boolean" }, "subsidy_entitlement_evaluated": { "type": "boolean" }, "monetary_subsidy_included": { "type": "boolean", "const": false }, "base_total_reduced_for_subsidy": { "type": "boolean", "const": false } } }, "CalculationData": { "type": "object", "required": [ "state_code", "subcategory_code", "category_label", "layer", "financial_year", "effective_on", "verification_tier", "calculation_scope", "input", "result", "source_refs", "disclosure", "coverage_status", "subsidy_entitlement", "included_components", "excluded_components" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "subcategory_code": { "type": "string" }, "category_label": { "type": "string" }, "layer": { "type": "string", "enum": [ "domestic", "lt", "ht" ] }, "financial_year": { "type": "string", "const": "2026-27" }, "effective_on": { "type": "string", "format": "date" }, "verification_tier": { "type": "string", "const": "verified_strict" }, "calculation_scope": { "type": "string", "enum": [ "verified_base_tariff", "verified_base_tariff_plus_non_monetary_subsidy_entitlement" ] }, "input": { "$ref": "#/components/schemas/CalculationInputEcho" }, "result": { "$ref": "#/components/schemas/CalculationResult" }, "source_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "disclosure": { "$ref": "#/components/schemas/CalculationDisclosure" }, "coverage_status": { "type": "string", "const": "production_ready" }, "subsidy_entitlement": { "$ref": "#/components/schemas/CalculationSubsidyEntitlementSummary" }, "included_components": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "excluded_components": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "electricity_duty": { "$ref": "#/components/schemas/BiharElectricityDutyContract" }, "ancillary_charges": { "$ref": "#/components/schemas/BiharAncillaryChargesContract" }, "final_payable": { "$ref": "#/components/schemas/BiharFinalPayableComposition" } } }, "DecimalInput": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,9}(?:\\.\\d{1,3})?$" }, { "type": "integer", "minimum": 0, "maximum": 999999999 } ], "description": "Non-negative decimal string with at most three decimal places. Whole integer JSON values are also accepted and normalized to strings." }, "RupeeString": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "description": "Two-decimal rupee representation paired with an integer-paise field." }, "Sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "HealthEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HealthData" }, "meta": { "type": "object", "required": [ "calculation_scope", "exact_current_net_bill" ], "properties": { "calculation_scope": { "type": "string", "const": "verified_base_tariff" }, "exact_current_net_bill": { "type": "boolean", "const": false } } } } } ] }, "StatesEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StateSummary" }, "minItems": 1, "maxItems": 1 }, "meta": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "const": 1 } } } } } ] }, "CategoriesEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CategorySummary" } }, "meta": { "type": "object", "required": [ "state_code", "count", "effective_on" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "count": { "type": "integer", "minimum": 0 }, "effective_on": { "type": "string", "format": "date" } } } } } ] }, "TariffsEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TariffRow" } }, "meta": { "type": "object", "required": [ "state_code", "count", "effective_on", "filters" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "count": { "type": "integer", "minimum": 0 }, "effective_on": { "type": "string", "format": "date" }, "filters": { "type": "object", "properties": { "subcategory_code": { "type": [ "string", "null" ] }, "supply_type": { "type": [ "string", "null" ] }, "area_type": { "type": [ "string", "null" ] } } } } } } } ] }, "SourcesEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SourceRecord" } }, "meta": { "type": "object", "required": [ "state_code", "verification_tier", "source_ref_count", "schedule_rows_mapped", "source_raw_text_sha256" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "verification_tier": { "type": "string", "const": "verified_strict" }, "source_ref_count": { "type": "integer", "minimum": 1 }, "schedule_rows_mapped": { "type": "integer", "const": 34 }, "source_raw_text_sha256": { "$ref": "#/components/schemas/Sha256" } } } } } ] }, "CalculationEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalculationData" }, "meta": { "type": "object", "required": [ "release_id", "release_sha256", "controller_version" ], "properties": { "release_id": { "type": "string", "const": "BR-2026-27-VERIFIED-STRICT-BASE-V1" }, "release_sha256": { "$ref": "#/components/schemas/Sha256" }, "controller_version": { "$ref": "#/components/schemas/ControllerVersion" } } } } } ] }, "ControllerVersion": { "type": "string", "const": "PEI Unified Bihar + Maharashtra Controller V2.2.14" }, "NullableInteger": { "type": [ "integer", "null" ] }, "NullableString": { "type": [ "string", "null" ] }, "CapabilityStatus": { "type": "string", "enum": [ "enabled", "enabled_non_monetary", "historical_evidence_available_current_blocked", "blocked" ] }, "BiharCapabilitiesData": { "type": "object", "required": [ "state_code", "controller_version", "api_version", "release_status", "financial_year", "effective_from", "capabilities", "blocked_components" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "controller_version": { "$ref": "#/components/schemas/ControllerVersion" }, "api_version": { "type": "string", "const": "PEI Verified Tariff API V1.2.0" }, "release_status": { "type": "string", "const": "released" }, "financial_year": { "type": "string", "const": "2026-27" }, "effective_from": { "type": "string", "format": "date", "const": "2026-04-01" }, "capabilities": { "type": "object", "required": [ "base_tariff_calculation", "subsidy_entitlement", "fppas", "statutory_levies", "exact_current_net_bill" ], "properties": { "base_tariff_calculation": { "type": "object", "required": [ "status", "route", "schedule_rows", "supported_subcategories", "money_mode" ], "properties": { "status": { "type": "string", "const": "enabled" }, "route": { "type": "string", "const": "POST /v1/calculate" }, "schedule_rows": { "type": "integer", "const": 34 }, "supported_subcategories": { "type": "integer", "const": 32 }, "money_mode": { "type": "string", "const": "integer_paise" } } }, "subsidy_entitlement": { "type": "object", "required": [ "status", "route", "calculate_summary_enabled", "billing_days_input", "supported_billing_days", "generic_rounding_status", "source_evidence_integrity", "source_document_sha256", "source_document_size_bytes", "monetary_subsidy_included", "base_tariff_amount_adjusted" ], "properties": { "status": { "type": "string", "const": "enabled_non_monetary" }, "route": { "type": "string", "const": "GET /v1/subsidy-entitlement" }, "calculate_summary_enabled": { "type": "boolean", "const": true }, "billing_days_input": { "type": "string", "const": "optional" }, "supported_billing_days": { "type": "array", "prefixItems": [ { "type": "integer", "const": 25 }, { "type": "integer", "const": 30 }, { "type": "integer", "const": 40 } ], "items": false, "minItems": 3, "maxItems": 3 }, "generic_rounding_status": { "type": "string", "const": "not_verified_fail_closed" }, "source_evidence_integrity": { "type": "string", "const": "verified_server_pdf_sha256" }, "source_document_sha256": { "type": "string", "const": "e03d2e66ab847622256670c109edad3e0391882721c32b4d1479edd8e1d27fcc" }, "source_document_size_bytes": { "type": "integer", "const": 1884287 }, "monetary_subsidy_included": { "type": "boolean", "const": false }, "base_tariff_amount_adjusted": { "type": "boolean", "const": false } } }, "fppas": { "type": "object", "required": [ "status", "route", "historical_period_records", "current_rate_released", "rate_applied_in_calculate", "reason" ], "properties": { "status": { "type": "string", "const": "historical_evidence_available_current_blocked" }, "route": { "type": "string", "const": "GET /v1/fppas-periods" }, "historical_period_records": { "type": "integer", "const": 4 }, "current_rate_released": { "type": "boolean", "const": false }, "rate_applied_in_calculate": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "current_numeric_regime_not_verified" } } }, "statutory_levies": { "type": "object", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "const": "blocked" }, "reason": { "type": "string", "const": "verified_rates_not_in_release" } } }, "exact_current_net_bill": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "const": "blocked" } } } } }, "blocked_components": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true } } }, "CapabilitiesEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BiharCapabilitiesData" }, "meta": { "type": "object", "required": [ "capability_contract", "calculation_scope" ], "properties": { "capability_contract": { "type": "string", "const": "state_aware_fail_closed_v1" }, "calculation_scope": { "type": "string", "const": "verified_base_tariff_plus_optional_non_monetary_subsidy_entitlement" } } } } } ] }, "SubsidyOfficialExample": { "type": "object", "required": [ "billing_days", "entitlement_units" ], "properties": { "billing_days": { "type": "integer", "enum": [ 25, 30, 40 ] }, "entitlement_units": { "type": "integer", "enum": [ 104, 125, 167 ] } } }, "SubsidyEvaluation": { "type": [ "object", "null" ], "properties": { "billing_days": { "type": "integer", "enum": [ 25, 30, 40 ] }, "entitlement_units": { "type": "integer", "enum": [ 104, 125, 167 ] }, "contract_application": { "type": "string", "const": "official_example_exact_match" }, "monetary_calculation_performed": { "type": "boolean", "const": false }, "consumption_units": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "subsidised_units": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "chargeable_units": { "type": "integer", "minimum": 0, "maximum": 100000000 } } }, "SubsidySourceContract": { "type": "object", "required": [ "source_id", "authority", "official_url", "reviewed_pages", "source_document_sha256", "source_document_hash_status", "source_document_content_type", "source_document_size_bytes", "source_document_magic_verified", "source_document_page_count", "source_document_page_count_status", "source_contract_sha256", "source_verifier_file_sha256", "source_contract_gates", "fixture_cases" ], "properties": { "source_id": { "type": "string", "const": "BR_SUBSIDY_MVUSY_FAQ_2025" }, "authority": { "type": "string", "const": "Bihar State Power Holding Company Limited" }, "official_url": { "type": "string", "format": "uri" }, "reviewed_pages": { "type": "array", "items": { "type": "integer" }, "minItems": 4 }, "source_document_sha256": { "type": "string", "const": "e03d2e66ab847622256670c109edad3e0391882721c32b4d1479edd8e1d27fcc" }, "source_document_hash_status": { "type": "string", "const": "verified_server_acquisition_magic_bytes_and_sha256" }, "source_document_content_type": { "type": "string", "const": "application/pdf" }, "source_document_size_bytes": { "type": "integer", "const": 1884287 }, "source_document_magic_verified": { "type": "boolean", "const": true }, "source_document_page_count": { "type": [ "integer", "null" ] }, "source_document_page_count_status": { "type": "string", "const": "not_detected_non_blocking" }, "source_contract_sha256": { "type": "string", "const": "cfcc2bcbb6417f2c1bafdf8bb63419fb66fc230fdc589573c9bbeac33513a9fa" }, "source_verifier_file_sha256": { "type": "string", "const": "7176220711421d7e7bb45b28a87bc8467d8ec0ffd4745142f64fd755923250f9" }, "source_contract_gates": { "$ref": "#/components/schemas/RuntimeGateChecks" }, "fixture_cases": { "$ref": "#/components/schemas/RuntimeGateChecks" } } }, "SubsidyEntitlementData": { "type": "object", "required": [ "state_code", "scheme_code", "contract_version", "verification_tier", "consumer_scope", "entitlement", "included_subsidy_components", "excess_consumption_contract", "evaluation", "blocked", "source_contract", "disclosure" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "scheme_code": { "type": "string", "const": "BR_MVUSY_DOMESTIC_125" }, "contract_version": { "type": "string", "const": "PEI Bihar Subsidy Entitlement Contract V1.0.0" }, "verification_tier": { "type": "string", "const": "verified_rule_contract" }, "consumer_scope": { "type": "object", "required": [ "consumer_class", "discoms", "area_types", "tenant_eligible_with_valid_consumer_account" ], "properties": { "consumer_class": { "type": "string", "const": "domestic" }, "discoms": { "type": "array", "prefixItems": [ { "const": "NBPDCL" }, { "const": "SBPDCL" } ], "items": false, "minItems": 2, "maxItems": 2 }, "area_types": { "type": "array", "prefixItems": [ { "const": "urban" }, { "const": "rural" } ], "items": false, "minItems": 2, "maxItems": 2 }, "tenant_eligible_with_valid_consumer_account": { "type": "boolean", "const": true } } }, "entitlement": { "type": "object", "required": [ "base_entitlement_units", "standard_billing_days", "pro_rata_required", "generic_rounding_mode", "generic_rounding_status", "official_examples" ], "properties": { "base_entitlement_units": { "type": "integer", "const": 125 }, "standard_billing_days": { "type": "integer", "const": 30 }, "pro_rata_required": { "type": "boolean", "const": true }, "generic_rounding_mode": { "type": "null" }, "generic_rounding_status": { "type": "string", "const": "not_verified_fail_closed" }, "official_examples": { "type": "array", "items": { "$ref": "#/components/schemas/SubsidyOfficialExample" }, "minItems": 3, "maxItems": 3 } } }, "included_subsidy_components": { "type": "array", "prefixItems": [ { "const": "energy_charge" }, { "const": "fixed_charge" }, { "const": "electricity_duty" } ], "items": false, "minItems": 3, "maxItems": 3 }, "excess_consumption_contract": { "type": "object", "required": [ "first_entitlement_units_fully_subsidised", "excess_units_billable", "electricity_duty_on_excess_units", "fixed_charge_reappears_when_entitlement_exceeded", "fy_2026_27_excess_category_rate_contract" ], "properties": { "first_entitlement_units_fully_subsidised": { "type": "boolean", "const": true }, "excess_units_billable": { "type": "boolean", "const": true }, "electricity_duty_on_excess_units": { "type": "boolean", "const": true }, "fixed_charge_reappears_when_entitlement_exceeded": { "type": "boolean", "const": true }, "fy_2026_27_excess_category_rate_contract": { "type": "null" } } }, "evaluation": { "$ref": "#/components/schemas/SubsidyEvaluation" }, "blocked": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "source_contract": { "$ref": "#/components/schemas/SubsidySourceContract" }, "disclosure": { "type": "object", "required": [ "entitlement_units_only", "monetary_subsidy_included", "fppas_included", "exact_current_net_bill" ], "properties": { "entitlement_units_only": { "type": "boolean", "const": true }, "monetary_subsidy_included": { "type": "boolean", "const": false }, "fppas_included": { "type": "boolean", "const": false }, "exact_current_net_bill": { "type": "boolean", "const": false } } } } }, "SubsidyEntitlementEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubsidyEntitlementData" }, "meta": { "type": "object", "required": [ "state_code", "calculation_scope", "controller_version" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "calculation_scope": { "type": "string", "const": "non_monetary_subsidy_entitlement_only" }, "controller_version": { "$ref": "#/components/schemas/ControllerVersion" } } } } } ] }, "CalculationSubsidyEntitlementSummary": { "type": [ "object", "null" ], "description": "Present for Bihar domestic calculations. When billing_days is omitted, status is not_evaluated. This block never changes the base tariff amount.", "properties": { "status": { "type": "string", "enum": [ "not_evaluated", "evaluated_non_monetary" ] }, "reason": { "type": "string" }, "scheme_code": { "type": "string", "const": "BR_MVUSY_DOMESTIC_125" }, "verification_tier": { "type": "string" }, "supported_billing_days": { "type": "array", "items": { "type": "integer" }, "minItems": 3, "maxItems": 3 }, "billing_days": { "type": "integer", "enum": [ 25, 30, 40 ] }, "entitlement_units": { "type": "integer" }, "consumption_units": { "type": "integer" }, "subsidised_units": { "type": "integer" }, "chargeable_units": { "type": "integer" }, "contract_application": { "type": "string" }, "generic_rounding_mode": { "type": "null" }, "monetary_subsidy_amount_paise": { "type": "null" }, "monetary_calculation_performed": { "type": "boolean", "const": false }, "base_tariff_amount_adjusted_for_subsidy": { "type": "boolean", "const": false }, "fppas_included": { "type": "boolean", "const": false }, "source_contract_sha256": { "$ref": "#/components/schemas/Sha256" } } }, "FppasHistoricalRecord": { "type": "object", "required": [ "artifact_id", "authority", "title", "period_month", "rate_percent_string", "rate_basis_points", "recovery_month", "recovery_month_status", "discom_scope", "consumer_category_scope", "scope_status", "source_url", "source_document_sha256", "source_pages", "calculation_use", "negative_rate_treatment" ], "properties": { "artifact_id": { "type": "string" }, "authority": { "type": "string", "enum": [ "NBPDCL", "SBPDCL" ] }, "title": { "type": "string" }, "period_month": { "type": "string", "pattern": "^(?:19|20)[0-9]{2}-(?:0[1-9]|1[0-2])$" }, "rate_percent_string": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]{1,2})?$" }, "rate_basis_points": { "type": "integer" }, "recovery_month": { "type": [ "string", "null" ], "pattern": "^(?:19|20)[0-9]{2}-(?:0[1-9]|1[0-2])$" }, "recovery_month_status": { "type": "string" }, "discom_scope": { "type": "array", "items": { "type": "string", "enum": [ "NBPDCL", "SBPDCL" ] }, "minItems": 1 }, "consumer_category_scope": { "type": "array", "items": { "type": "string" } }, "scope_status": { "type": "string", "const": "partial_official_evidence" }, "source_url": { "type": "string", "format": "uri" }, "source_document_sha256": { "$ref": "#/components/schemas/Sha256" }, "source_pages": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1 }, "calculation_use": { "type": "string", "const": "historical_evidence_only_not_applied" }, "negative_rate_treatment": { "type": "string", "const": "not_released_for_production_calculation" } } }, "FppasPeriodsData": { "type": "object", "required": [ "state_code", "contract_version", "status", "records", "record_count", "available_period_months", "filters", "current_selection", "source_integrity", "blocked_components", "disclosure" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "contract_version": { "type": "string", "const": "PEI Bihar FPPAS Historical Period Evidence Contract V1.0.0" }, "status": { "type": "string", "const": "historical_evidence_available_current_regime_blocked" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/FppasHistoricalRecord" } }, "record_count": { "type": "integer", "minimum": 0, "maximum": 4 }, "available_period_months": { "type": "array", "prefixItems": [ { "const": "2025-08" }, { "const": "2026-01" }, { "const": "2026-02" }, { "const": "2026-03" } ], "items": false, "minItems": 4, "maxItems": 4 }, "filters": { "type": "object", "required": [ "period_month", "recovery_month", "authority" ], "properties": { "period_month": { "type": [ "string", "null" ] }, "recovery_month": { "type": [ "string", "null" ] }, "authority": { "type": [ "string", "null" ], "enum": [ "NBPDCL", "SBPDCL", null ] } } }, "current_selection": { "type": "object", "required": [ "billing_month", "required_calculation_month", "matching_historical_record_found", "current_rate_released", "current_fppas_engine_ready", "reason" ], "properties": { "billing_month": { "type": "string", "pattern": "^(?:19|20)[0-9]{2}-(?:0[1-9]|1[0-2])$" }, "required_calculation_month": { "type": "string", "pattern": "^(?:19|20)[0-9]{2}-(?:0[1-9]|1[0-2])$" }, "matching_historical_record_found": { "type": "boolean" }, "current_rate_released": { "type": "boolean", "const": false }, "current_fppas_engine_ready": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "no_approved_current_period_scope_and_negative_rate_contract" } } }, "source_integrity": { "type": "array", "items": { "type": "object", "required": [ "source_document_sha256", "periods", "pdf_magic_verified" ], "properties": { "source_document_sha256": { "$ref": "#/components/schemas/Sha256" }, "periods": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "pdf_magic_verified": { "type": "boolean", "const": true } } }, "minItems": 2, "maxItems": 2 }, "blocked_components": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "disclosure": { "type": "object", "required": [ "historical_evidence_only", "rate_applied_to_bill", "current_rate_inferred", "monetary_calculation_performed" ], "properties": { "historical_evidence_only": { "type": "boolean", "const": true }, "rate_applied_to_bill": { "type": "boolean", "const": false }, "current_rate_inferred": { "type": "boolean", "const": false }, "monetary_calculation_performed": { "type": "boolean", "const": false } } } } }, "FppasPeriodsEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FppasPeriodsData" }, "meta": { "type": "object", "required": [ "state_code", "calculation_scope", "controller_version" ], "properties": { "state_code": { "type": "string", "const": "BR" }, "calculation_scope": { "type": "string", "const": "historical_fppas_evidence_only" }, "controller_version": { "$ref": "#/components/schemas/ControllerVersion" } } } } } ] }, "SolarSavingsRequest": { "type": "object", "additionalProperties": false, "required": [ "state_code", "existing_monthly_units", "post_solar_import_units", "release_id", "verification_tier" ], "properties": { "state_code": { "type": "string", "enum": [ "BR" ] }, "subcategory_code": { "type": "string", "example": "BR_DS_II", "description": "Optional when consumer_type and domestic_class are supplied. When both forms are supplied, they must resolve to the same category." }, "connected_load": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "example": "2" }, "load_unit": { "type": "string", "enum": [ "kw", "hp", "kva" ] }, "existing_monthly_units": { "type": "integer", "minimum": 0, "example": 450 }, "post_solar_import_units": { "type": "integer", "minimum": 0, "example": 150 }, "effective_on": { "type": "string", "format": "date" }, "release_id": { "type": "string", "example": "BR-2026-27-VERIFIED-STRICT-BASE-V1" }, "verification_tier": { "type": "string", "enum": [ "verified_strict" ] }, "consumer_type": { "type": "string", "enum": [ "domestic" ], "description": "Required when domestic_class is used for internal category resolution." }, "domestic_class": { "type": "string", "enum": [ "urban", "general", "rural", "lifeline" ], "description": "Caller-declared Bihar domestic classification. The API does not determine government or lifeline eligibility." }, "billing_month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-05", "description": "Optional billing month used by the verified Bihar FPPAS selector." }, "discom_code": { "type": "string", "enum": [ "NBPDCL", "SBPDCL" ], "description": "Optional Bihar distribution company selector for FPPAS." } }, "oneOf": [ { "required": [ "subcategory_code" ] }, { "required": [ "consumer_type", "domestic_class" ] } ], "description": "The request may use either an explicit subcategory_code or consumer_type=domestic with domestic_class for internal verified mapping." }, "SolarSavingsResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "api_version", "request_id", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "api_version": { "type": "string", "example": "PEI Verified Tariff API V1.2.0" }, "request_id": { "type": "string", "example": "req_bdcd24619052713e" }, "data": { "$ref": "#/components/schemas/SolarSavingsData" }, "meta": { "type": "object", "additionalProperties": false, "required": [ "release_id", "controller_version", "wrapper_contract" ], "properties": { "release_id": { "type": "string", "example": "BR-2026-27-VERIFIED-STRICT-BASE-V1" }, "controller_version": { "type": "string", "example": "PEI Unified Bihar + Maharashtra Controller V2.2.8" }, "wrapper_contract": { "type": "string", "example": "PEI Verified Solar Savings Baseline V1.0.0" } } } } }, "SolarMoneyResult": { "type": "object", "additionalProperties": false, "required": [ "energy_charge_paise", "energy_charge_paise_rupees", "fixed_charge_paise", "fixed_charge_paise_rupees", "demand_charge_paise", "demand_charge_paise_rupees", "excess_demand_charge_paise", "excess_demand_charge_paise_rupees", "tod_adjustment_paise", "tod_adjustment_paise_rupees", "special_adjustment_paise", "special_adjustment_paise_rupees", "base_total_paise", "base_total_paise_rupees", "currency", "integer_paise_only" ], "properties": { "energy_charge_paise": { "type": "integer", "minimum": 0, "example": 333900 }, "energy_charge_paise_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "3339.00" }, "fixed_charge_paise": { "type": "integer", "minimum": 0, "example": 16000 }, "fixed_charge_paise_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "160.00" }, "demand_charge_paise": { "type": "integer", "minimum": 0, "example": 0 }, "demand_charge_paise_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.00" }, "excess_demand_charge_paise": { "type": "integer", "minimum": 0, "example": 0 }, "excess_demand_charge_paise_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.00" }, "tod_adjustment_paise": { "type": "integer", "example": 0 }, "tod_adjustment_paise_rupees": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "special_adjustment_paise": { "type": "integer", "example": 0 }, "special_adjustment_paise_rupees": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "base_total_paise": { "type": "integer", "minimum": 0, "example": 349900 }, "base_total_paise_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "3499.00" }, "currency": { "type": "string", "enum": [ "INR" ] }, "integer_paise_only": { "type": "boolean", "enum": [ true ] } } }, "SolarCalculationSide": { "type": "object", "additionalProperties": false, "required": [ "energy_units", "result" ], "properties": { "energy_units": { "type": "integer", "minimum": 0, "example": 450 }, "result": { "$ref": "#/components/schemas/SolarMoneyResult" } } }, "SolarSavingsSummary": { "type": "object", "additionalProperties": false, "required": [ "monthly_base_tariff_saving_paise", "monthly_base_tariff_saving_paise_rupees", "annualized_base_tariff_saving_paise", "annualized_base_tariff_saving_paise_rupees", "base_cost_reduction_basis_points", "base_cost_reduction_percent" ], "properties": { "monthly_base_tariff_saving_paise": { "type": "integer", "minimum": 0, "example": 222600 }, "monthly_base_tariff_saving_paise_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2226.00" }, "annualized_base_tariff_saving_paise": { "type": "integer", "minimum": 0, "example": 2671200 }, "annualized_base_tariff_saving_paise_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "26712.00" }, "base_cost_reduction_basis_points": { "type": "integer", "minimum": 0, "maximum": 10000, "example": 6362 }, "base_cost_reduction_percent": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "63.62" } } }, "SolarSavingsEvidence": { "type": "object", "additionalProperties": false, "required": [ "release_id", "financial_year", "effective_from", "effective_on", "verification_tier", "calculation_version", "release_sha256", "source_refs" ], "properties": { "release_id": { "type": "string", "example": "BR-2026-27-VERIFIED-STRICT-BASE-V1" }, "financial_year": { "type": "string", "example": "2026-27" }, "effective_from": { "type": "string", "format": "date", "example": "2026-04-01" }, "effective_on": { "type": "string", "format": "date", "example": "2026-04-01" }, "verification_tier": { "type": "string", "enum": [ "verified_strict" ] }, "calculation_version": { "type": "string", "example": "PEI Verified Solar Savings Baseline V1.0.0" }, "release_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source_refs": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "SolarSavingsLimitations": { "type": "object", "additionalProperties": false, "required": [ "exact_current_bill", "solar_generation_estimated", "post_solar_import_supplied_by_client", "net_metering_applied", "export_credit_applied", "fppas_applied", "monetary_subsidy_applied", "statutory_levies_applied", "payback_or_roi_calculated", "annualized_value_is_monthly_baseline_times_12" ], "properties": { "exact_current_bill": { "type": "boolean" }, "solar_generation_estimated": { "type": "boolean" }, "post_solar_import_supplied_by_client": { "type": "boolean" }, "net_metering_applied": { "type": "boolean" }, "export_credit_applied": { "type": "boolean" }, "fppas_applied": { "type": "boolean" }, "monetary_subsidy_applied": { "type": "boolean" }, "statutory_levies_applied": { "type": "boolean" }, "payback_or_roi_calculated": { "type": "boolean" }, "annualized_value_is_monthly_baseline_times_12": { "type": "boolean" } } }, "SolarSavingsDisclosure": { "type": "object", "additionalProperties": false, "required": [ "estimate_not_utility_bill", "verified_base_tariff_comparison_only", "not_a_guaranteed_solar_saving" ], "properties": { "estimate_not_utility_bill": { "type": "boolean" }, "verified_base_tariff_comparison_only": { "type": "boolean" }, "not_a_guaranteed_solar_saving": { "type": "boolean" } } }, "SolarSavingsData": { "type": "object", "additionalProperties": false, "required": [ "calculation_type", "coverage_status", "state_code", "subcategory_code", "category_label", "input", "before_solar", "after_solar", "savings", "evidence", "limitations", "disclosure", "proposal_evidence" ], "properties": { "calculation_type": { "type": "string", "enum": [ "verified_solar_savings_baseline" ] }, "coverage_status": { "type": "string", "enum": [ "production_verified" ], "example": "production_verified" }, "state_code": { "type": "string", "enum": [ "BR" ] }, "subcategory_code": { "type": "string", "example": "BR_DS_II" }, "category_label": { "type": "string", "example": "DS-II" }, "input": { "type": "object", "additionalProperties": false, "required": [ "existing_monthly_units", "post_solar_import_units", "solar_offset_units", "connected_load", "load_unit" ], "properties": { "existing_monthly_units": { "type": "integer", "minimum": 0 }, "post_solar_import_units": { "type": "integer", "minimum": 0 }, "solar_offset_units": { "type": "integer", "minimum": 0 }, "connected_load": { "type": "string", "example": "2" }, "load_unit": { "type": "string", "example": "kW" } } }, "before_solar": { "$ref": "#/components/schemas/SolarCalculationSide" }, "after_solar": { "$ref": "#/components/schemas/SolarCalculationSide" }, "savings": { "$ref": "#/components/schemas/SolarSavingsSummary" }, "evidence": { "$ref": "#/components/schemas/SolarSavingsEvidence" }, "limitations": { "$ref": "#/components/schemas/SolarSavingsLimitations" }, "disclosure": { "$ref": "#/components/schemas/SolarSavingsDisclosure" }, "proposal_evidence": { "$ref": "#/components/schemas/SolarProposalEvidence" } } }, "SolarProposalUsageBaseline": { "type": "object", "additionalProperties": false, "required": [ "existing_monthly_units", "post_solar_import_units", "solar_offset_units" ], "properties": { "existing_monthly_units": { "type": "integer", "minimum": 0, "example": 450 }, "post_solar_import_units": { "type": "integer", "minimum": 0, "example": 150 }, "solar_offset_units": { "type": "integer", "minimum": 0, "example": 300 } } }, "SolarProposalTariffComparison": { "type": "object", "additionalProperties": false, "required": [ "before_solar_base_total_paise", "before_solar_base_total_rupees", "after_solar_base_total_paise", "after_solar_base_total_rupees", "monthly_base_tariff_saving_paise", "monthly_base_tariff_saving_rupees", "annualized_base_tariff_saving_paise", "annualized_base_tariff_saving_rupees", "base_cost_reduction_basis_points", "base_cost_reduction_percent" ], "properties": { "before_solar_base_total_paise": { "type": "integer", "minimum": 0, "example": 349900 }, "before_solar_base_total_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "3499.00" }, "after_solar_base_total_paise": { "type": "integer", "minimum": 0, "example": 127300 }, "after_solar_base_total_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1273.00" }, "monthly_base_tariff_saving_paise": { "type": "integer", "minimum": 0, "example": 222600 }, "monthly_base_tariff_saving_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2226.00" }, "annualized_base_tariff_saving_paise": { "type": "integer", "minimum": 0, "example": 2671200 }, "annualized_base_tariff_saving_rupees": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "26712.00" }, "base_cost_reduction_basis_points": { "type": "integer", "minimum": 0, "maximum": 10000, "example": 6362 }, "base_cost_reduction_percent": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "63.62" } } }, "SolarProposalTariffBasis": { "type": "object", "additionalProperties": false, "required": [ "release_id", "financial_year", "effective_on", "verification_tier", "release_sha256", "source_refs" ], "properties": { "release_id": { "type": "string", "example": "BR-2026-27-VERIFIED-STRICT-BASE-V1" }, "financial_year": { "type": "string", "example": "2026-27" }, "effective_on": { "type": "string", "format": "date", "example": "2026-04-01" }, "verification_tier": { "type": "string", "enum": [ "verified_strict" ] }, "release_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source_refs": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "SolarProposalDisclaimer": { "type": "object", "additionalProperties": false, "required": [ "estimate_not_utility_bill", "verified_base_tariff_comparison_only", "not_a_guaranteed_solar_saving", "post_solar_import_supplied_by_client", "excluded_components" ], "properties": { "estimate_not_utility_bill": { "type": "boolean", "enum": [ true ] }, "verified_base_tariff_comparison_only": { "type": "boolean", "enum": [ true ] }, "not_a_guaranteed_solar_saving": { "type": "boolean", "enum": [ true ] }, "post_solar_import_supplied_by_client": { "type": "boolean", "enum": [ true ] }, "excluded_components": { "type": "array", "minItems": 7, "maxItems": 7, "uniqueItems": true, "items": { "type": "string", "enum": [ "solar_generation_estimation", "net_metering", "export_credit", "fppas", "monetary_subsidy", "statutory_levies", "payback_or_roi" ] } } } }, "SolarProposalEvidence": { "type": "object", "additionalProperties": false, "required": [ "object_version", "proposal_use", "machine_verifiable", "state_code", "subcategory_code", "category_label", "usage_baseline", "verified_base_tariff_comparison", "tariff_basis", "proposal_disclaimer" ], "properties": { "object_version": { "type": "string", "enum": [ "PEI Solar Proposal Evidence Object V1.0.0" ] }, "proposal_use": { "type": "string", "enum": [ "solar_savings_baseline" ] }, "machine_verifiable": { "type": "boolean", "enum": [ true ] }, "state_code": { "type": "string", "enum": [ "BR" ] }, "subcategory_code": { "type": "string", "example": "BR_DS_II" }, "category_label": { "type": "string", "example": "DS-II" }, "usage_baseline": { "$ref": "#/components/schemas/SolarProposalUsageBaseline" }, "verified_base_tariff_comparison": { "$ref": "#/components/schemas/SolarProposalTariffComparison" }, "tariff_basis": { "$ref": "#/components/schemas/SolarProposalTariffBasis" }, "proposal_disclaimer": { "$ref": "#/components/schemas/SolarProposalDisclaimer" } } }, "CategoryResolverRequest": { "type": "object", "additionalProperties": false, "required": [ "state_code", "consumer_type", "domestic_class", "release_id", "verification_tier" ], "properties": { "state_code": { "type": "string", "enum": [ "BR" ] }, "consumer_type": { "type": "string", "enum": [ "domestic" ] }, "domestic_class": { "type": "string", "enum": [ "urban", "general", "rural", "lifeline" ] }, "connected_load": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,9}(?:\\.\\d{1,3})?$" }, { "type": "integer", "minimum": 0 } ], "example": "2" }, "load_unit": { "type": "string", "description": "Case-insensitive kW input; normalized to kw.", "example": "kW" }, "effective_on": { "type": "string", "format": "date" }, "release_id": { "type": "string", "enum": [ "BR-2026-27-VERIFIED-STRICT-BASE-V1" ] }, "verification_tier": { "type": "string", "enum": [ "verified_strict" ] } } }, "CategoryResolverResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "api_version", "request_id", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "api_version": { "type": "string", "example": "PEI Verified Tariff API V1.2.0" }, "request_id": { "type": "string", "example": "req_example" }, "data": { "type": "object", "additionalProperties": false, "required": [ "resolution_type", "coverage_status", "resolution_status", "confidence", "state_code", "input_classification", "resolved_category", "evidence", "disclosure" ], "properties": { "resolution_type": { "type": "string", "enum": [ "verified_domestic_category_mapping" ] }, "coverage_status": { "type": "string", "enum": [ "production_verified" ] }, "resolution_status": { "type": "string", "enum": [ "resolved_verified" ] }, "confidence": { "type": "string", "enum": [ "exact" ] }, "state_code": { "type": "string", "enum": [ "BR" ] }, "input_classification": { "type": "object", "additionalProperties": false, "required": [ "consumer_type", "domestic_class", "connected_load", "load_unit" ], "properties": { "consumer_type": { "type": "string", "enum": [ "domestic" ] }, "domestic_class": { "type": "string", "enum": [ "urban", "general", "rural", "lifeline" ] }, "connected_load": { "nullable": true, "type": "string" }, "load_unit": { "nullable": true, "type": "string" } } }, "resolved_category": { "type": "object", "additionalProperties": false, "required": [ "subcategory_code", "category_label", "canonical_category_code", "layer", "supply_type", "required_calculation_inputs", "optional_calculation_inputs" ], "properties": { "subcategory_code": { "type": "string", "enum": [ "BR_DS_II", "BR_DS_III", "BR_DS_I_RURAL", "BR_KUTIR_JYOTI" ] }, "category_label": { "type": "string" }, "canonical_category_code": { "type": "string", "enum": [ "DOMESTIC_URBAN", "DOMESTIC_GENERAL", "DOMESTIC_RURAL", "DOMESTIC_LIFELINE" ] }, "layer": { "type": "string", "enum": [ "domestic" ] }, "supply_type": { "type": "string", "enum": [ "low_tension" ] }, "required_calculation_inputs": { "type": "array", "items": { "type": "string" } }, "optional_calculation_inputs": { "type": "array", "items": { "type": "string" } } } }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "release_id", "financial_year", "effective_on", "verification_tier", "release_sha256" ], "properties": { "release_id": { "type": "string" }, "financial_year": { "type": "string" }, "effective_on": { "type": "string", "format": "date" }, "verification_tier": { "type": "string", "enum": [ "verified_strict" ] }, "release_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "disclosure": { "type": "object", "additionalProperties": false, "required": [ "classification_supplied_by_client", "eligibility_determined_by_api", "government_scheme_eligibility_verified", "automatic_category_guess_performed", "caller_must_confirm_consumer_classification" ], "properties": { "classification_supplied_by_client": { "type": "boolean", "enum": [ true ] }, "eligibility_determined_by_api": { "type": "boolean", "enum": [ false ] }, "government_scheme_eligibility_verified": { "type": "boolean", "enum": [ false ] }, "automatic_category_guess_performed": { "type": "boolean", "enum": [ false ] }, "caller_must_confirm_consumer_classification": { "type": "boolean", "enum": [ true ] } } } } }, "meta": { "type": "object", "additionalProperties": false, "required": [ "release_id", "controller_version", "resolver_contract" ], "properties": { "release_id": { "type": "string" }, "controller_version": { "type": "string" }, "resolver_contract": { "type": "string", "enum": [ "PEI Bihar Domestic Category Resolver V1.0.0" ] } } } } }, "BiharContractSelfCheck": { "type": "object", "required": [ "passed", "total", "passed_count" ], "properties": { "passed": { "type": "boolean" }, "total": { "type": "integer", "minimum": 0 }, "passed_count": { "type": "integer", "minimum": 0 }, "checks": { "type": "object", "additionalProperties": { "type": "boolean" } } } }, "BiharElectricityDutyContract": { "type": "object", "description": "Fail-closed Bihar electricity-duty contract. Current FY 2026-27 monetary rate is not applied until the authoritative notification body is source-locked.", "properties": { "status": { "type": "string", "example": "blocked_pending_notification_body_source_lock" }, "verification_tier": { "type": "string" }, "applied": { "type": "boolean" }, "applied_to_payable": { "type": "boolean" }, "payable_mutation_performed": { "type": "boolean" }, "amount_paise": { "type": [ "integer", "null" ] }, "amount_is_zero": { "type": "boolean" }, "rate_basis_points": { "type": [ "integer", "null" ] }, "rate_percent": { "type": [ "string", "null" ] }, "charge_base": { "type": [ "string", "null" ] }, "category_scope": { "type": [ "string", "null" ] }, "exemptions": { "type": [ "string", "null" ] }, "rounding_rule": { "type": [ "string", "null" ] }, "statutory_source_contract": { "type": "object", "properties": { "state_code": { "type": "string", "const": "BR" }, "act": { "type": "object" }, "notification": { "type": "object", "properties": { "identifier": { "type": "string", "example": "S.O. No. 182" }, "date": { "type": "string", "format": "date", "example": "2018-05-25" }, "official_registry": { "type": "string", "example": "India Code" }, "registry_listing_verified": { "type": "boolean" }, "body_source_locked_for_production": { "type": "boolean" } } }, "fy_2026_27_current_rate_verified": { "type": "boolean" } } }, "self_check": { "$ref": "#/components/schemas/BiharContractSelfCheck" } } }, "BiharAncillaryChargesContract": { "type": "object", "description": "Fail-closed Bihar meter-rent and ancillary-charge contract. Unverified consumer charges are never silently treated as zero.", "properties": { "status": { "type": "string", "example": "verified_fail_closed_contract_complete" }, "verification_tier": { "type": "string" }, "applied_to_payable": { "type": "boolean" }, "payable_mutation_performed": { "type": "boolean" }, "meter_rent": { "type": "object", "properties": { "status": { "type": "string", "example": "not_verified_separate_consumer_charge" }, "amount_paise": { "type": [ "integer", "null" ] }, "amount_is_zero": { "type": "boolean" }, "rate_contract_available": { "type": "boolean" }, "billing_frequency": { "type": [ "string", "null" ] }, "reason": { "type": "string" } } }, "one_time_service_connection_charges": { "type": "object" }, "arrears_penalties_and_dps": { "type": "object" }, "miscellaneous_ancillary_adjustments": { "type": "object" }, "electricity_duty_and_statutory_levies": { "type": "object" }, "self_check": { "$ref": "#/components/schemas/BiharContractSelfCheck" }, "payable_complete": { "type": "boolean" }, "exact_current_net_bill": { "type": "boolean" } } }, "BiharFinalPayableComposition": { "type": "object", "description": "Composition of currently verified Bihar monetary components. estimated_payable_paise must not be treated as an exact utility bill while blocking_components is non-empty.", "properties": { "contract_version": { "type": "string", "const": "br.payable_composition.v1" }, "status": { "type": "string", "enum": [ "complete_verified_payable", "partial_verified_payable_blocked" ] }, "verification_tier": { "type": "string" }, "base_total_paise": { "type": "integer", "minimum": 0 }, "fppas_applied": { "type": "boolean" }, "fppas_adjustment_paise": { "type": [ "integer", "null" ] }, "verified_monetary_subsidy_applied": { "type": "boolean" }, "verified_monetary_subsidy_paise": { "type": [ "integer", "null" ] }, "verified_component_payable_candidate_paise": { "type": "integer", "minimum": 0 }, "estimated_payable_paise": { "type": "integer", "minimum": 0 }, "estimated_payable_is_exact_current_net_bill": { "type": "boolean" }, "rebates_applied_to_payable": { "type": "boolean" }, "ancillary_applied_to_payable": { "type": "boolean" }, "electricity_duty_applied_to_payable": { "type": "boolean" }, "blocking_components": { "type": "array", "items": { "type": "string" } }, "unresolved_components": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "status": { "type": "string" }, "amount_paise": { "type": [ "integer", "null" ] }, "blocks_exact_current_net_bill": { "type": "boolean" } } } }, "blocking_component_count": { "type": "integer", "minimum": 0 }, "payable_complete": { "type": "boolean" }, "exact_current_net_bill": { "type": "boolean" }, "estimate_not_utility_bill": { "type": "boolean" }, "base_tariff_result_preserved": { "type": "boolean" }, "self_check": { "$ref": "#/components/schemas/BiharContractSelfCheck" } } } } }, "x-pei-release": { "release_id": "BR-2026-27-VERIFIED-STRICT-BASE-V1", "state_code": "BR", "financial_year": "2026-27", "effective_from": "2026-04-01", "verification_tier": "verified_strict", "schedule_rows": 34, "supported_subcategories": 32, "frozen_regression_cases": 45, "runtime_gate_checks": 29, "calculation_scope": "verified_base_tariff_plus_optional_non_monetary_subsidy_entitlement", "exact_current_net_bill": false, "api_version": "PEI Verified Tariff API V1.2.0", "controller_version": "PEI Unified Bihar + Maharashtra Controller V2.2.8", "subsidy_entitlement": { "status": "enabled_non_monetary", "supported_billing_days": [ 25, 30, 40 ], "source_document_sha256": "e03d2e66ab847622256670c109edad3e0391882721c32b4d1479edd8e1d27fcc", "monetary_subsidy_included": false }, "fppas": { "status": "historical_evidence_available_current_blocked", "historical_records": 4, "current_rate_released": false, "rate_applied_to_bill": false } }, "x-pei-security": { "query_string_api_keys": "rejected", "query_parameter_names_rejected": [ "key", "api_key", "apikey" ], "default_rate_limit_per_minute": 60, "burst_requests": 20, "burst_window_seconds": 10, "cors": "per-key allowlist", "request_logging": "privacy-safe; no plaintext API key" }, "x-pei-regression-evidence": { "suite": "API-Level Full Regression & Security Test V1.0.0", "executed_on": "2026-07-18", "tests_total": 84, "tests_passed": 84, "tests_failed": 0, "tests_skipped": 0 }, "x-pei-contract-sync": { "controller_version": "PEI Unified Bihar + Maharashtra Controller V2.2.8", "synchronized_routes": [ "GET /v1/capabilities", "GET /v1/subsidy-entitlement", "GET /v1/fppas-periods", "POST /v1/calculate (optional billing_days and non-monetary subsidy summary)" ], "monetary_subsidy_enabled": false, "current_fppas_enabled": false, "tariff_money_formula_changed": false, "live_health_runtime_gate_checks": { "passed": 29, "total": 29 }, "br_ds_ii_fixed_charge_basis": "per_kw_or_part_per_month" }, "x-pei-bihar-payable-contract": { "controller_version": "PEI Unified Bihar + Maharashtra Controller V2.2.14", "contract_version": "br.payable_composition.v1", "master_regression_runner": "V1.2.9", "electricity_duty_current_rate_verified": false, "exact_current_net_bill_available": false }, "x-pei-maharashtra-phase-1": { "status": "released", "financial_year": "2026-27", "scope": "verified_base_tariff", "released_licensees": [ "MH_MSEDCL", "MH_TPCD", "MH_AEML", "MH_BEST" ], "fac_fpppa_payable": false, "tod_payable": false, "subsidy_payable": false, "tax_duty_payable": false, "exact_current_net_bill": false } }