{
  "openapi": "3.1.0",
  "info": {
    "title": "KAKA CARD MARKET reserved publisher integration",
    "version": "0.1.0",
    "description": "Planned API contract only. No endpoints deployed. Publishers may implement their own compatible service."
  },
  "x-implementation-status": "reserved-not-deployed",
  "paths": {
    "/v1/collections/{chainId}/{contractAddress}/{editionId}": {
      "get": {
        "operationId": "getCollection",
        "summary": "读取弹次资料（预留）",
        "parameters": [
          {
            "name": "chainId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "enum": [
                56,
                97
              ]
            }
          },
          {
            "name": "contractAddress",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          },
          {
            "name": "editionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[-A-Za-z0-9_]{1,80}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "已验证的弹次资料"
          },
          "404": {
            "description": "卡集不存在"
          }
        }
      }
    },
    "/v1/collection-bindings": {
      "post": {
        "operationId": "submitBinding",
        "summary": "验证发行商后关联规则（预留）",
        "security": [
          {
            "publisherSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BindingDraft"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "已验证并保存的绑定"
          },
          "401": {
            "description": "身份无效"
          },
          "403": {
            "description": "无发行权限"
          },
          "409": {
            "description": "冲突或重复提交"
          }
        }
      }
    },
    "/v1/rulesets": {
      "post": {
        "operationId": "publishRuleset",
        "summary": "发布冻结规则版本（未来功能，不提供 AI 生成功能）",
        "security": [
          {
            "publisherSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "version",
                  "manifestUrl",
                  "contentHash"
                ],
                "properties": {
                  "version": {
                    "type": "string"
                  },
                  "manifestUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "contentHash": {
                    "type": "string",
                    "description": "由服务端验证实际内容摘要"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "规则版本已验证并发布"
          },
          "401": {
            "description": "身份无效"
          },
          "422": {
            "description": "规则不合法"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "publisherSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "短期会话，由服务端验证钱包签名、nonce、域、有效期及发行权限后颁发；不是服务器 API key。"
      }
    },
    "schemas": {
      "CollectionKey": {
        "type": "object",
        "required": [
          "chainId",
          "contractAddress",
          "editionId"
        ],
        "properties": {
          "chainId": {
            "type": "integer",
            "enum": [
              56,
              97
            ]
          },
          "contractAddress": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "editionId": {
            "type": "string",
            "pattern": "^[-A-Za-z0-9_]{1,80}$"
          }
        }
      },
      "BindingDraft": {
        "type": "object",
        "required": [
          "schemaVersion",
          "status",
          "collection"
        ],
        "properties": {
          "schemaVersion": {
            "const": "0.1"
          },
          "status": {
            "const": "local-draft"
          },
          "collection": {
            "$ref": "#/components/schemas/CollectionKey"
          },
          "externalBattleUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "rulesManifestUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        }
      }
    }
  }
}