{
  "components": {
    "schemas": {
      "ExternalCapabilities": {
        "additionalProperties": false,
        "properties": {
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "delivery_types": {
            "items": {
              "enum": [
                "license_key",
                "activation_url",
                "instructions"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "devices": {
            "const": false,
            "type": "boolean"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "identity_exchange": {
            "const": false,
            "type": "boolean"
          },
          "protocol": {
            "const": "launch-external-licensing-v1",
            "type": "string"
          },
          "purchase_types": {
            "items": {
              "enum": [
                "perpetual",
                "fixed_term"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "protocol",
          "connection_ref",
          "environment",
          "purchase_types",
          "delivery_types"
        ],
        "type": "object"
      },
      "ExternalCapabilitiesResponse": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ExternalCapabilities"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ExternalDelivery": {
        "additionalProperties": false,
        "properties": {
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "delivery": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExternalDeliveryValue"
              },
              {
                "type": "null"
              }
            ]
          },
          "entitlement_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "ready",
              "unavailable"
            ],
            "type": "string"
          },
          "version": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "connection_ref",
          "environment",
          "entitlement_ref",
          "version",
          "status",
          "delivery"
        ],
        "type": "object"
      },
      "ExternalDeliveryResponse": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ExternalDelivery"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ExternalDeliveryValue": {
        "additionalProperties": false,
        "properties": {
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": {
            "enum": [
              "license_key",
              "activation_url",
              "instructions"
            ],
            "type": "string"
          },
          "value": {
            "description": "敏感内容，最多 4096 个 UTF-8 字节。绝不能写入日志。激活 URL 必须使用已配置的 HTTPS 源地址。",
            "maxLength": 4096,
            "type": "string"
          }
        },
        "required": [
          "type",
          "value",
          "expires_at"
        ],
        "type": "object"
      },
      "ExternalError": {
        "additionalProperties": false,
        "properties": {
          "error": {
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "request_id"
        ],
        "type": "object"
      },
      "ExternalReceipt": {
        "additionalProperties": false,
        "properties": {
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "entitlement_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "error_code": {
            "anyOf": [
              {
                "maxLength": 96,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "event_id": {
            "format": "uuid",
            "type": "string"
          },
          "payload_sha256": {
            "pattern": "^[0-9a-f]{64}$",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "applied",
              "rejected",
              "manual_review"
            ],
            "type": "string"
          },
          "version": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "event_id",
          "connection_ref",
          "environment",
          "entitlement_ref",
          "version",
          "payload_sha256",
          "status",
          "error_code"
        ],
        "type": "object"
      },
      "ExternalReceiptResponse": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ExternalReceipt"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ExternalSnapshot": {
        "additionalProperties": false,
        "properties": {
          "account_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "change_reason": {
            "enum": [
              "purchase",
              "renewal",
              "upgrade",
              "refund",
              "reversal",
              "suspension",
              "resumption",
              "expiry",
              "reconciliation"
            ],
            "type": "string"
          },
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "desired_state": {
            "enum": [
              "active",
              "suspended",
              "expired",
              "revoked"
            ],
            "type": "string"
          },
          "entitlement_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "event_id": {
            "format": "uuid",
            "type": "string"
          },
          "launch_plan_version_id": {
            "format": "uuid",
            "type": "string"
          },
          "launch_product_id": {
            "format": "uuid",
            "type": "string"
          },
          "plan_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "product_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "schema": {
            "const": "launch-external-licensing-v1",
            "type": "string"
          },
          "type": {
            "const": "entitlement.snapshot",
            "type": "string"
          },
          "valid_from": {
            "format": "date-time",
            "type": "string"
          },
          "valid_until": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "version": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "schema",
          "event_id",
          "connection_ref",
          "environment",
          "type",
          "change_reason",
          "account_ref",
          "entitlement_ref",
          "launch_product_id",
          "launch_plan_version_id",
          "product_ref",
          "plan_ref",
          "version",
          "desired_state",
          "valid_from",
          "valid_until"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "description": "由商户授权服务实现，由 Launch 调用。这是商业状态协议，不是许可证生成器或运行时 SDK。签名针对精确请求字节；重试保持事件 ID 和请求内容不变。请阅读配套接入指南。",
    "title": "Launch 外部授权桥接",
    "version": "1.0.0",
    "x-document-language": "zh-Hans"
  },
  "openapi": "3.1.0",
  "paths": {
    "/launch/v1/capabilities": {
      "get": {
        "operationId": "externalCapabilities",
        "parameters": [
          {
            "description": "已配置的密钥 ID。",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "十进制 Unix 秒，误差范围 +/-300 秒。",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "至少 16 个随机字节，使用不带填充的 base64url；在 600 秒内去重。",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request))；精确字节格式参见接入指南。",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalCapabilitiesResponse"
                }
              }
            },
            "description": "成功返回"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "签名或时间戳无效"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "连接或环境不匹配"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "重放、幂等或状态冲突"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "触发频率限制；遵循 Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "暂时不可用"
          }
        },
        "summary": "验证连接和支持的协议"
      }
    },
    "/launch/v1/entitlements/{entitlement_ref}/delivery": {
      "get": {
        "operationId": "getExternalDelivery",
        "parameters": [
          {
            "description": "已配置的密钥 ID。",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "十进制 Unix 秒，误差范围 +/-300 秒。",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "至少 16 个随机字节，使用不带填充的 base64url；在 600 秒内去重。",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request))；精确字节格式参见接入指南。",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "entitlement_ref",
            "required": true,
            "schema": {
              "pattern": "^[A-Za-z0-9_-]{1,128}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalDeliveryResponse"
                }
              }
            },
            "description": "成功返回"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "签名或时间戳无效"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "连接或环境不匹配"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "不存在此购买"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "重放、幂等或状态冲突"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "触发频率限制；遵循 Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "暂时不可用"
          }
        },
        "summary": "读取已有交付，绝不创建另一份许可证"
      }
    },
    "/launch/v1/events": {
      "post": {
        "operationId": "submitExternalPurchase",
        "parameters": [
          {
            "description": "已配置的密钥 ID。",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "十进制 Unix 秒，误差范围 +/-300 秒。",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "至少 16 个随机字节，使用不带填充的 base64url；在 600 秒内去重。",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request))；精确字节格式参见接入指南。",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalSnapshot"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalReceiptResponse"
                }
              }
            },
            "description": "已有事件或同步应用的结果"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalReceiptResponse"
                }
              }
            },
            "description": "已持久接收；pending 不代表交付完成"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "签名或时间戳无效"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "连接或环境不匹配"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "重放、幂等或状态冲突"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "未知套餐或不支持的购买类型"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "触发频率限制；遵循 Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "暂时不可用"
          }
        },
        "summary": "持久化完整的绝对购买快照，不得重复签发"
      }
    },
    "/launch/v1/events/{event_id}": {
      "get": {
        "operationId": "getExternalEvent",
        "parameters": [
          {
            "description": "已配置的密钥 ID。",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "十进制 Unix 秒，误差范围 +/-300 秒。",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "至少 16 个随机字节，使用不带填充的 base64url；在 600 秒内去重。",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request))；精确字节格式参见接入指南。",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "event_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalReceiptResponse"
                }
              }
            },
            "description": "成功返回"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "签名或时间戳无效"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "连接或环境不匹配"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "EVENT_NOT_FOUND：只有此结果允许重新提交原事件"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "重放、幂等或状态冲突"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "触发频率限制；遵循 Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "暂时不可用"
          }
        },
        "summary": "恢复或查询原事件回执"
      }
    }
  },
  "servers": [
    {
      "url": "https://licenses.example.com"
    }
  ]
}