{
  "openapi": "3.0.3",
  "info": {
    "title": "iSMSNOW 短信 API",
    "version": "1.0.0",
    "description": "iSMSNOW API。鉴权方式：Authorization: Bearer {API Key}，API Key 在控制台获取。",
    "contact": {
      "name": "和恆電訊有限公司",
      "email": "support@ismsnow.com",
      "url": "https://www.ismsnow.com"
    }
  },
  "servers": [
    {
      "url": "https://app.ismsnow.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "在控制台获取的 API Key"
      }
    }
  },
  "tags": [
    {
      "name": "短信 API"
    }
  ],
  "paths": {
    "/api/v3/sms/send": {
      "post": {
        "tags": [
          "短信 API"
        ],
        "operationId": "postApiV3SmsSend",
        "summary": "发送短信",
        "description": "向一个或多个号码发送短信，可定时发送。需要账号具备短信发送权限（短信快速发送、批量发送或营销任务任一项），否则返回 403。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recipient",
                  "message"
                ],
                "properties": {
                  "recipient": {
                    "type": "string",
                    "description": "接收号码，带国际区号、不带 +，如 8613800138000。多个号码用英文逗号分隔"
                  },
                  "sender_id": {
                    "type": "string",
                    "description": "测试阶段填 Signature 即可，为占位值，无需修改：签名 / 发件人 ID 由平台统一下发，不会按此处填写的内容变更。开通正式发送后为号码（含区号）或字母发件人 ID（最长 11 位），需是账号已报备的签名 / 发件人"
                  },
                  "type": {
                    "type": "string",
                    "description": "plain（默认，短信）或 unicode"
                  },
                  "message": {
                    "type": "string",
                    "description": "消息内容。示例中的验证码 123456 可替换为任意 6 位数字。含中文等非 GSM 字符时自动按 unicode 发送"
                  },
                  "schedule_time": {
                    "type": "string",
                    "format": "date-time",
                    "description": "定时发送，格式 Y-m-d H:i，如 2026-10-08 09:30，按账号时区"
                  }
                }
              },
              "examples": {
                "example1": {
                  "summary": "单个号码示例请求",
                  "value": {
                    "recipient": "8613800000000",
                    "sender_id": "Signature",
                    "type": "plain",
                    "message": "您的注册验证码为：123456，5分钟内有效。本条为通道实测短信，正式接入后，短信签名与正文内容均支持自定义修改。"
                  }
                },
                "example2": {
                  "summary": "多个号码示例请求",
                  "value": {
                    "recipient": "8613800000000,8613900000000",
                    "sender_id": "Signature",
                    "type": "plain",
                    "message": "您的注册验证码为：123456，5分钟内有效。本条为通道实测短信，正式接入后，短信签名与正文内容均支持自定义修改。",
                    "schedule_time": "2026-10-08 09:30"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "message": "说明文字",
                  "data": {
                    "uid": "606812e63f78b",
                    "to": "8613800138000",
                    "from": "YourName",
                    "message": "您的验证码是 123456",
                    "status": "Delivered",
                    "cost": "1"
                  }
                }
              }
            }
          },
          "400": {
            "description": "失败",
            "content": {
              "application/json": {
                "example": {
                  "status": "error",
                  "message": "错误原因"
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/sms/{uid}": {
      "get": {
        "tags": [
          "短信 API"
        ],
        "operationId": "getApiV3SmsByUid",
        "summary": "查看短信",
        "description": "uid 为发送时返回的消息 uid。只能查询自己账号的消息。\n\n想实时收到状态回执和上行短信，可在「开发者」页配置 Webhook，平台会主动推送，无需轮询。",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "发送时返回的消息 uid（URL 路径参数），只能查询自己账号的消息",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "data": {
                    "uid": "606812e63f78b",
                    "to": "8613800138000",
                    "from": "YourName",
                    "message": "您的验证码是 123456",
                    "status": "Delivered",
                    "cost": "1"
                  }
                }
              }
            }
          },
          "400": {
            "description": "失败",
            "content": {
              "application/json": {
                "example": {
                  "status": "error",
                  "message": "错误原因"
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/sms": {
      "get": {
        "tags": [
          "短信 API"
        ],
        "operationId": "getApiV3Sms",
        "summary": "查看所有消息",
        "description": "按时间倒序，每页 25 条，用 page 翻页。返回字段：uid、to / from（接收号码 / 发件人）、message、status（发送状态，如 Delivered、Failed）、cost（费用）。",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "data": [
                    {
                      "uid": "606812e63f78b",
                      "to": "8613800138000",
                      "from": "YourName",
                      "message": "您的验证码是 123456",
                      "status": "Delivered",
                      "cost": "1"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "失败",
            "content": {
              "application/json": {
                "example": {
                  "status": "error",
                  "message": "错误原因"
                }
              }
            }
          }
        }
      }
    }
  }
}