{ "openapi": "3.1.0", "info": { "title": "GreenFinance 开放 API", "version": "1.0.0", "summary": "绿色项目识别与双碳核算的计算服务接口", "description": "GreenFinance（greenfinance.cn）面向 AI Agent 与银行业务系统开放的绿色金融计算能力。\n\n**返回格式**：各接口直接返回结果对象，没有统一的 {success, data} 外层封装。多数计算类接口的结果对象内含 success 字段，早期路由（知识库、目录）则没有，请按各接口的响应定义处理。\n\n**错误格式**：计算类接口返回 {success:false, error}；知识库与目录类返回 {message}；标准判据类返回 {error, message}。产品碳足迹接口在计算失败时仍返回 HTTP 200，需检查响应体的 success 字段。\n\n**鉴权与限流**：本规范收录的接口均可匿名调用，无需 API Key。部分接口按 IP 限流，携带 Authorization: Bearer 的已登录调用额度更高。超限返回 429。\n\n**未收录的能力**：AI 绿色识别（每次调用消耗模型算力）与排放因子的批量查询不在公开规范内，需要联系 contact@greenfinance.cn 申请。MCP 服务正在安全加固，暂未对外提供。\n\n**工具定位**：全部核算接口为初步测算，正式披露与履约报告以主管部门发布的核算指南和第三方核查结论为准。", "contact": { "name": "GreenFinance", "email": "contact@greenfinance.cn", "url": "https://greenfinance.cn/api" }, "license": { "name": "使用条款", "url": "https://greenfinance.cn/about" } }, "servers": [ { "url": "https://greenfinance.cn", "description": "生产环境" } ], "security": [], "components": { "securitySchemes": {} }, "externalDocs": { "description": "开放 API 说明页", "url": "https://greenfinance.cn/api" }, "tags": [ { "name": "平台", "description": "健康检查与版本" }, { "name": "碳核算", "description": "企业、产品与行业快筛的碳排放核算" }, { "name": "行业碳核算", "description": "全国碳市场重点行业口径" }, { "name": "测算工具", "description": "光伏与储能项目测算" }, { "name": "排放因子", "description": "因子类别与单条查询" }, { "name": "标准判据", "description": "按标准阈值判定项目指标是否达标" }, { "name": "知识库", "description": "绿色产业目录与逐条解读" } ], "paths": { "/api/v1/health": { "get": { "tags": [ "平台" ], "operationId": "getHealth", "summary": "服务健康检查", "responses": { "200": { "description": "服务状态", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "timestamp": { "type": "string", "format": "date-time" }, "uptime": { "type": "number", "description": "进程运行秒数" }, "services": { "type": "object", "properties": { "api": { "type": "string" }, "database": { "type": "string" } } } } } } } } } } }, "/api/v1/version": { "get": { "tags": [ "平台" ], "operationId": "getVersion", "summary": "查询后端构建版本", "responses": { "200": { "description": "构建版本信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "buildVersion": { "type": "string" }, "commit": { "type": [ "string", "null" ] } } } } } } } } }, "/api/v1/calculator/carbon-accounting": { "post": { "tags": [ "碳核算" ], "operationId": "calculateCarbonAccounting", "summary": "企业组织层面温室气体核算", "description": "按 ISO 14064-1 与 GB/T 32150 口径核算范围一、范围二、范围三排放。下列数组至少有一个非空：fuels、fugitiveEmissions、purchasedEnergy、materials、inboundLogistics、outboundLogistics、businessTravel、employeeCommuting、waste。匿名调用与登录调用的额度不同。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "companyName": { "type": "string", "description": "可选；不填即匿名试算" }, "reportingPeriod": { "type": "string", "description": "核算期间，如 2025" }, "electricityMode": { "type": "string", "enum": [ "simplified", "precise", "power-mix-estimate" ], "description": "外购电力口径：全国平均 / 精确区域 / 电源结构估算" }, "electricityDataYear": { "type": "integer", "enum": [ 2022, 2023 ] }, "noStore": { "type": "boolean", "description": "true 时不落库保存报告" }, "fuels": { "type": "array", "description": "范围一：现场化石燃料燃烧", "items": { "type": "object", "required": [ "fuelType", "quantity" ], "properties": { "fuelType": { "type": "string", "description": "燃料因子 ID（如 fuel-diesel-t）或名称关键词（如 \"柴油\"）" }, "quantity": { "type": "number", "description": "年消耗量" }, "unit": { "type": "string", "description": "计量单位，如 t、L、m³、MWh；不填则按因子推断" } } } }, "fugitiveEmissions": { "type": "array", "description": "范围一：制冷剂等逸散排放", "items": { "type": "object", "required": [ "gasType", "quantity" ], "properties": { "gasType": { "type": "string", "description": "制冷剂或气体类型，如 HFC-134a、R-410A" }, "quantity": { "type": "number", "description": "年排放量，千克" } } } }, "purchasedEnergy": { "type": "array", "description": "范围二：购入电力、热力、蒸汽、冷力", "items": { "type": "object", "required": [ "energyType", "quantity" ], "properties": { "energyType": { "type": "string", "enum": [ "electricity", "heat", "steam", "cooling" ] }, "quantity": { "type": "number", "description": "年消耗量" }, "unit": { "type": "string", "description": "计量单位，默认 kWh，也支持 MWh" } } } }, "materials": { "type": "array", "description": "范围三：原材料投入", "items": { "type": "object", "required": [ "materialType", "quantity" ], "properties": { "materialType": { "type": "string", "description": "材料因子 ID 或名称关键词" }, "quantity": { "type": "number", "description": "年消耗量" }, "unit": { "type": "string", "description": "计量单位，默认 kg，也支持 t" } } } }, "inboundLogistics": { "type": "array", "description": "范围三：入场物流", "items": { "type": "object", "required": [ "transportType", "tonneKm" ], "properties": { "transportType": { "type": "string", "description": "运输方式因子 ID 或名称关键词" }, "tonneKm": { "type": "number", "description": "吨公里数" } } } }, "outboundLogistics": { "type": "array", "description": "范围三：出场物流", "items": { "type": "object", "required": [ "transportType", "tonneKm" ], "properties": { "transportType": { "type": "string", "description": "运输方式因子 ID 或名称关键词" }, "tonneKm": { "type": "number", "description": "吨公里数" } } } }, "businessTravel": { "type": "array", "description": "范围三：商务差旅", "items": { "type": "object", "required": [ "transportType", "distance" ], "properties": { "transportType": { "type": "string", "description": "交通方式因子 ID 或名称关键词" }, "distance": { "type": "number", "description": "人公里数或公里数" } } } }, "employeeCommuting": { "type": "array", "description": "范围三：员工通勤", "items": { "type": "object", "required": [ "transportType", "distance" ], "properties": { "transportType": { "type": "string", "description": "交通方式因子 ID 或名称关键词" }, "distance": { "type": "number", "description": "人公里数或公里数" } } } }, "waste": { "type": "array", "description": "范围三：废弃物处理", "items": { "type": "object", "required": [ "wasteType", "treatmentMethod", "quantity" ], "properties": { "wasteType": { "type": "string", "description": "废弃物类型因子 ID 或名称关键词" }, "treatmentMethod": { "type": "string", "enum": [ "recycling", "landfill", "incineration-energy", "incineration-no-energy", "composting" ] }, "quantity": { "type": "number", "description": "年处理量，千克" } } } } } } } } }, "responses": { "200": { "description": "核算结果", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "totalEmissions": { "type": "number", "description": "总排放量，吨 CO2e" }, "totalEmissionsKg": { "type": "number" }, "scope1": { "type": "object", "additionalProperties": true, "description": "范围一分项" }, "scope2": { "type": "object", "additionalProperties": true, "description": "范围二分项" }, "scope3": { "type": "object", "additionalProperties": true, "description": "范围三分项" }, "categoryBreakdown": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "分类别排放明细" } }, "factorsUsed": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } }, "methodologyNotes": { "type": "array", "items": { "type": "string" } }, "standardsApplied": { "type": "object", "additionalProperties": true, "description": "本次计算采用的标准与因子版本" }, "reportId": { "type": "string" } } } } } }, "400": { "description": "入参不合法（缺必填项或取值不在枚举内）", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/carbon-footprint": { "post": { "tags": [ "碳核算" ], "operationId": "calculateProductCarbonFootprint", "summary": "产品碳足迹核算（从摇篮到大门）", "description": "按产品生命周期方法逐环节累加碳足迹。注意：内部计算失败时仍返回 HTTP 200，需检查响应体的 success 字段。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productCategory" ], "properties": { "productCategory": { "type": "string", "enum": [ "internal-combustion-engine", "plastic-products", "furniture", "lighting", "livestock-products", "recycled-plastics" ] }, "productName": { "type": "string" }, "quantity": { "type": "number" }, "customData": { "type": "object", "additionalProperties": true, "description": "覆盖默认值的自定义活动数据" }, "lighting": { "type": "object", "properties": { "ratedPower": { "type": "number" }, "ratedLifespan": { "type": "number" } } }, "livestock": { "type": "object", "properties": { "productType": { "type": "string" }, "feedConversionRatio": { "type": "number" } } }, "furniture": { "type": "object", "properties": { "furnitureType": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "碳足迹结果；success 为 false 时表示计算未成功", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "product": { "type": "object", "additionalProperties": true, "description": "产品标识与数量" }, "methodology": { "type": "object", "additionalProperties": true, "description": "采用的标准、功能单位与系统边界" }, "totalCarbonFootprint": { "type": "number" }, "phases": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "各生命周期阶段结果" } }, "dominantPhase": { "type": "string" }, "dataSource": { "type": "string", "enum": [ "default", "custom", "mixed" ] }, "reductionTips": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "productCategory 缺失或不在枚举内", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "validCategories": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/carbon-footprint/categories": { "get": { "tags": [ "碳核算" ], "operationId": "listProductCarbonFootprintCategories", "summary": "列出支持的产品碳足迹品类", "description": "返回品类名称、对应标准与生命周期阶段，不含任何排放因子数值。", "responses": { "200": { "description": "品类清单", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "totalCategories": { "type": "integer" }, "frameworkStandard": { "type": "object", "additionalProperties": true, "description": "框架标准" }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "品类、标准与阶段" } } } } } } } } } }, "/api/v1/calculator/carbon-screening": { "post": { "tags": [ "碳核算" ], "operationId": "screenIndustryEmissions", "summary": "按行业与营收快速估算排放量级", "description": "用行业排放强度乘营收做量级快筛，适合尽调初筛，不能替代实际核算。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "industry", "revenueWanyuan" ], "properties": { "industry": { "type": "string", "description": "行业名称或代码，取值见行业清单接口" }, "revenueWanyuan": { "type": "number", "exclusiveMinimum": 0, "description": "年营收，万元" }, "noStore": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "快筛结果", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "emissionsTonne": { "type": "number" }, "industry": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "sector": { "type": "string" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "exclude" ] } } }, "usedFallback": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "入参不合法（缺必填项或取值不在枚举内）", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/carbon-screening/industries": { "get": { "tags": [ "碳核算" ], "operationId": "listScreeningIndustries", "summary": "列出快筛支持的行业", "description": "只返回行业代码、名称与门类，不含排放强度数值。", "responses": { "200": { "description": "行业清单", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "industries": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "code / name / sector" } }, "fallback": { "type": "object", "additionalProperties": true, "description": "未命中时使用的兜底行业" }, "meta": { "type": "object", "additionalProperties": true, "description": "数据年份与行业分类标准" } } } } } } } } }, "/api/v1/calculator/pv-carbon": { "post": { "tags": [ "测算工具" ], "operationId": "calculatePvCarbon", "summary": "光伏项目发电量、碳减排与收益测算", "description": "按装机容量与地理位置调用气象数据估算发电量，再折算碳减排与收益。定位方式二选一：给 cityName，或同时给 latitude 与 longitude。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "capacityKw" ], "properties": { "capacityKw": { "type": "number", "exclusiveMinimum": 0, "description": "装机容量，千瓦" }, "cityName": { "type": "string", "description": "城市名，取值见城市清单接口" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "tiltAngle": { "type": "number" }, "systemEfficiency": { "type": "number" }, "selfConsumptionRate": { "type": "number" }, "investmentPerKw": { "type": "number" }, "feedInTariffYuanPerKwh": { "type": "number" }, "retailElecPriceYuanPerKwh": { "type": "number" }, "annualDegradationRate": { "type": "number" }, "gridEmissionFactor": { "type": "number" }, "pvEmissionFactor": { "type": "number" }, "projectLifeYears": { "type": "integer" } } } } } }, "responses": { "200": { "description": "测算结果", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true, "description": "回显的入参" }, "location": { "type": "object", "additionalProperties": true, "description": "解析出的位置信息" }, "annualSummary": { "type": "object", "additionalProperties": true, "description": "年度汇总：发电量、上网与自用电量、碳减排量、收益、投资回收期、度电成本" }, "monthlyMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "逐月指标" } }, "riskIndicators": { "type": "object", "additionalProperties": true, "description": "风险提示指标" }, "twentyFiveYearProjection": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "逐年预测" } } } } } } }, "400": { "description": "入参不合法，或上游气象数据获取失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/pv-carbon/cities": { "get": { "tags": [ "测算工具" ], "operationId": "listPvCarbonCities", "summary": "列出光伏测算支持的城市", "responses": { "200": { "description": "按省份分组的城市名清单（无 success 字段）", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "cities": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "note": { "type": "string" } } } } } } } } }, "/api/v1/calculator/pv-carbon/defaults": { "get": { "tags": [ "测算工具" ], "operationId": "getPvCarbonDefaults", "summary": "查询光伏测算各参数的默认取值", "description": "返回倾角、系统效率、自用比例、单位投资、上网电价等默认值。注意返回键名与请求字段名不完全一致，例如此处的 feedInTariff 对应请求参数 feedInTariffYuanPerKwh。", "responses": { "200": { "description": "各参数的 value / unit / description（无 success 字段）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "键为参数名，值为 {value, unit, description}" } } } } } } }, "/api/v1/calculator/energy-storage": { "post": { "tags": [ "测算工具" ], "operationId": "calculateEnergyStorage", "summary": "储能电站峰谷套利收益测算", "description": "按省份分时电价测算储能电站的日收益、年收益、回收期与内部收益率。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "province" ], "properties": { "province": { "type": "string", "description": "省份名，取值见省份清单接口" }, "capacityMWh": { "type": "number", "minimum": 0, "maximum": 1000 }, "investmentWanYuan": { "type": "number" }, "operatingDaysPerYear": { "type": "integer", "minimum": 1, "maximum": 365 }, "roundTripEfficiency": { "type": "number" }, "discountRate": { "type": "number" }, "projectYears": { "type": "integer" }, "chargeDischargeMode": { "type": "string", "enum": [ "one_charge_one_discharge", "two_charge_two_discharge" ], "description": "也接受中文「一充一放」「两充两放」与 1c1d / 2c2d 写法" } } } } } }, "responses": { "200": { "description": "测算结果", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true, "description": "回显的入参" }, "electricityPricing": { "type": "object", "additionalProperties": true, "description": "该省分时电价与峰谷价差" }, "dailyNetRevenue": { "type": "number" }, "annualNetRevenue": { "type": "number" }, "simplePaybackYearsPreTax": { "type": "number" }, "irrPreTax": { "type": "number" }, "npvPreTax": { "type": "number" } } } } } }, "400": { "description": "省份缺失或不支持", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "availableProvinces": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/energy-storage/compare": { "get": { "tags": [ "测算工具" ], "operationId": "compareEnergyStorageProvinces", "summary": "跨省份比较储能收益", "description": "同一套项目参数在各省的收益对比。注意这是 GET，参数走 query string。", "parameters": [ { "name": "capacityMWh", "in": "query", "schema": { "type": "number" } }, { "name": "investmentWanYuan", "in": "query", "schema": { "type": "number" } }, { "name": "operatingDaysPerYear", "in": "query", "schema": { "type": "integer" } }, { "name": "chargeDischargeMode", "in": "query", "schema": { "type": "string", "enum": [ "one_charge_one_discharge", "two_charge_two_discharge" ] } } ], "responses": { "200": { "description": "各省对比结果与最优、最差省份", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "provinces": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "单省测算结果" } }, "bestProvince": { "type": "object", "additionalProperties": true, "description": "收益最高的省份" }, "worstProvince": { "type": "object", "additionalProperties": true, "description": "收益最低的省份" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/energy-storage/provinces": { "get": { "tags": [ "测算工具" ], "operationId": "listEnergyStorageProvinces", "summary": "列出储能测算支持的省份及分时电价", "responses": { "200": { "description": "省份清单与各时段电价", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "total": { "type": "integer" }, "provinces": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "省份与分时电价、峰谷价差" } } } } } } } } } }, "/api/v1/calculator/steel-accounting": { "post": { "tags": [ "行业碳核算" ], "operationId": "calculateSteelAccounting", "summary": "钢铁行业碳核算（全国碳市场口径）", "description": "按钢铁行业核算指南试算：化石燃料燃烧、含碳原料过程排放、电极消耗、净购入电力热力与固碳产品扣除。\n\n入参各数组元素上限 200 条；下列分组至少填一个：fuels、carbonates、electrodeConsumption、carbonInputs、carbonProducts、processes、cogenUnits、byproductGasBalances。\n\n工具定位为初步测算，履约报告以主管部门指南与第三方核查结论为准。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "行业核算入参。至少提供以下分组之一：fuels、carbonates、electrodeConsumption、carbonInputs、carbonProducts、processes、cogenUnits、byproductGasBalances。各分组的字段以服务端 zod schema 为准，可先用空对象调用读取 400 响应中的提示。" } } } }, "responses": { "200": { "description": "核算结果（分项排放与汇总）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "含 success 与分项、汇总排放量的结果对象。" } } } }, "400": { "description": "入参不合法（缺必填项或取值不在枚举内）", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/cement-accounting": { "post": { "tags": [ "行业碳核算" ], "operationId": "calculateCementAccounting", "summary": "水泥行业碳核算（全国碳市场口径）", "description": "试算熟料生产的碳酸盐分解过程排放、燃料燃烧排放与净购入电力热力间接排放。\n\n入参各数组元素上限 200 条；下列分组至少填一个：clinkerLines、enterpriseFuels、powerFacilities、otherFacilityEmission。\n\n工具定位为初步测算，履约报告以主管部门指南与第三方核查结论为准。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "行业核算入参。至少提供以下分组之一：clinkerLines、enterpriseFuels、powerFacilities、otherFacilityEmission。各分组的字段以服务端 zod schema 为准，可先用空对象调用读取 400 响应中的提示。" } } } }, "responses": { "200": { "description": "核算结果（分项排放与汇总）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "含 success 与分项、汇总排放量的结果对象。" } } } }, "400": { "description": "入参不合法（缺必填项或取值不在枚举内）", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/aluminum-accounting": { "post": { "tags": [ "行业碳核算" ], "operationId": "calculateAluminumAccounting", "summary": "电解铝行业碳核算（全国碳市场口径）", "description": "试算炭阳极消耗排放、阳极效应全氟化碳排放、碳酸盐分解与电力间接排放。\n\n入参各数组元素上限 200 条；下列分组至少填一个：electrolysisLines、enterpriseFuels、carbonates、powerFacilities、otherFacilityEmission。\n\n工具定位为初步测算，履约报告以主管部门指南与第三方核查结论为准。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "行业核算入参。至少提供以下分组之一：electrolysisLines、enterpriseFuels、carbonates、powerFacilities、otherFacilityEmission。各分组的字段以服务端 zod schema 为准，可先用空对象调用读取 400 响应中的提示。" } } } }, "responses": { "200": { "description": "核算结果（分项排放与汇总）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "含 success 与分项、汇总排放量的结果对象。" } } } }, "400": { "description": "入参不合法（缺必填项或取值不在枚举内）", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/power-accounting": { "post": { "tags": [ "行业碳核算" ], "operationId": "calculatePowerAccounting", "summary": "发电设施碳核算", "description": "按《企业温室气体排放核算与报告指南发电设施》试算机组燃料燃烧与购入电力排放。\n\n入参各数组元素上限 200 条；下列分组至少填一个：units、purchasedElectricity。\n\n工具定位为初步测算，履约报告以主管部门指南与第三方核查结论为准。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "行业核算入参。至少提供以下分组之一：units、purchasedElectricity。各分组的字段以服务端 zod schema 为准，可先用空对象调用读取 400 响应中的提示。" } } } }, "responses": { "200": { "description": "核算结果（分项排放与汇总）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "含 success 与分项、汇总排放量的结果对象。" } } } }, "400": { "description": "入参不合法（缺必填项或取值不在枚举内）", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/calculator/city-inventory": { "post": { "tags": [ "行业碳核算" ], "operationId": "calculateCityInventory", "summary": "城市温室气体清单核算", "description": "按省级温室气体清单编制指南框架试算城市级清单：能源活动、工业过程、农业、土地利用变化与林业、废弃物处理。\n\n入参各数组元素上限 200 条；下列分组至少填一个：能源活动、工业过程、农业、土地利用、废弃物等部门数组。\n\n工具定位为初步测算，履约报告以主管部门指南与第三方核查结论为准。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "行业核算入参。至少提供以下分组之一：能源活动、工业过程、农业、土地利用、废弃物等部门数组。各分组的字段以服务端 zod schema 为准，可先用空对象调用读取 400 响应中的提示。" } } } }, "responses": { "200": { "description": "核算结果（分项排放与汇总）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "含 success 与分项、汇总排放量的结果对象。" } } } }, "400": { "description": "入参不合法（缺必填项或取值不在枚举内）", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/emission-factors/categories": { "get": { "tags": [ "排放因子" ], "operationId": "listEmissionFactorCategories", "summary": "列出排放因子的类别与来源", "description": "返回类别名称、条目数、涉及的排放范围与数据来源，不含任何因子数值。因子数值只在计算结果中逐条展示，或通过单条查询接口获取。", "responses": { "200": { "description": "类别清单", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "totalFactors": { "type": "integer" }, "totalCategories": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "类别、标签、条目数、范围、来源" } }, "sources": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/v1/emission-factors/detail/{id}": { "get": { "tags": [ "排放因子" ], "operationId": "getEmissionFactorDetail", "summary": "按 ID 查询单条排放因子", "description": "用于核对某一次计算所引用的因子取值与来源，单条查询、可核查。批量导出因子库不在开放范围内。", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "单条因子", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "factor": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "category": { "type": "string", "enum": [ "fuel", "electricity", "heat", "fugitive", "material", "freight", "passenger", "waste" ] }, "nameCn": { "type": "string" }, "nameEn": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "scope": { "type": "integer", "enum": [ 1, 2, 3 ] }, "source": { "type": "string" }, "sourceYear": { "type": "integer" }, "region": { "type": "string", "enum": [ "CN", "GLOBAL" ] }, "gasType": { "type": "string", "enum": [ "CO2", "CO2e", "CH4", "N2O", "GWP" ] } } } } } } } }, "404": { "description": "ID 不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "hint": { "type": "string" } } } } } }, "429": { "description": "触发限流；匿名调用额度低于已登录调用", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "retryAfter": { "type": "integer", "description": "建议等待秒数" }, "hint": { "type": "string" } } } } } }, "500": { "description": "服务端计算失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "面向调用方的错误说明" } }, "required": [ "success", "error" ] } } } } } } }, "/api/v1/standards/verify": { "post": { "tags": [ "标准判据" ], "operationId": "verifyStandardCompliance", "summary": "按标准判据核对项目指标是否达标", "description": "给定绿色产业目录条目号或标准号，以及项目实测参数，逐条判定是否满足标准阈值，并列出还缺哪些参数。判定为确定性查表，不经过模型推断。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "catalogCode 与 standardNo 至少提供一个", "properties": { "catalogCode": { "type": "string", "description": "绿色产业目录条目号，如 1.1.18" }, "standardNo": { "type": "string", "description": "标准号，如 GB 24500" }, "params": { "type": "object", "additionalProperties": true, "description": "项目实测参数，键为指标 ID，值为实测数值" }, "historyId": { "type": "string" } } } } } }, "responses": { "200": { "description": "判定结果", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "evaluations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "逐条标准的判定结果，含指标、状态、要求值" } }, "missing_params": { "type": "array", "items": { "type": "string" } }, "advisory_rules": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "提示性条款" } }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "未提供 catalogCode 或 standardNo", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "标准不存在，或该标准没有可判定的阈值表", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "判定失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/knowledge/catalog": { "get": { "tags": [ "知识库" ], "operationId": "getKnowledgeCatalog", "summary": "获取绿色产业知识库目录树", "description": "返回一级/二级/三级目录结构与已生成解读的条目 ID。每 IP 每分钟 30 次。", "responses": { "200": { "description": "目录树", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "含 tree、totalL3、generatedCount、generatedIds、enMap" } } } }, "429": { "description": "超出每分钟 30 次限制", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "服务端错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/knowledge/{id}": { "get": { "tags": [ "知识库" ], "operationId": "getKnowledgeEntry", "summary": "获取单条绿色产业解读", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目录条目号（如 1.1.1）或英文 slug" } ], "responses": { "200": { "description": "条目全文", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "中英双语解读，含产业概况、目录界定、绿色认定要点、市场与政策、漂绿风险信号。字段由数据文件定义。" } } } }, "404": { "description": "条目不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "429": { "description": "超出每分钟 30 次限制", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "服务端错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/categories/level1": { "get": { "tags": [ "知识库" ], "operationId": "listCatalogLevel1", "summary": "列出绿色产业目录一级分类", "responses": { "200": { "description": "一级分类名称数组", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "500": { "description": "服务端错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } } } }