REST API v1

MangoOTP 开发者 API

通过 Partner API 自动化一次性接码业务。请求必须使用 X-API-Key，并遵守 IP 白名单、partnerOrderNo 防重、限流和轮询频率约束。

code查看接口手册 key登录创建 API Key

Quickstart 流程

典型集成从密钥创建到验证码送达分为四步。

创建 API Key

登录后在 API 密钥页面创建以 mago_live_ 开头的密钥。原始密钥只展示一次，请立即保存。

一个账号只保留一个有效合作方密钥。正式接入前请配置固定出口 IP 白名单和 Webhook URL。

获取指定国家服务价格

先获取服务，再获取该服务可用国家，最后按指定服务和国家获取唯一平台售价和库存估算。

价格接口只返回完成业务所需的平台报价与库存信息。

创建接码订单

提交 service、country、sellPrice 和可选 maxSellPrice，并携带 partnerOrderNo 防止重试导致重复冻结余额。

未传 maxSellPrice 时当前售价必须等于 sellPrice；传入后当前售价不得超过该上限。

轮询订单状态

通过订单号查询号码、短信验证码和状态。终态包括成功、失败、超时和取消。

仅在结果明确失败、缺货或价格失效后，才可以安全地重新发起操作。

shield

鉴权

所有合作方 API 请求使用 X-API-Key。密钥只保存 SHA-256 hash，必须命中非空 IP 白名单；系统不信任 X-Forwarded-For 作为白名单依据。

X-API-Key: mago_live_xxxxxxxxxxxxxxxx

bolt

合作方订单号与价格保护

POST /api/v1/activation/createOrder 使用 partnerOrderNo、必填 sellPrice 和可选 maxSellPrice。完全一致的业务重试不会重复创建订单；系统在冻结资金前重新校验当前 Catalog 售价和可售状态。

{"partnerOrderNo":"partner-order-20260707-001"}

接口手册

按合作方实际接入顺序逐个说明接口。每个接口都给出请求地址、参数、请求示例、成功响应和常见错误。

Partner API

独立 X-API-Key 鉴权的接码与主账户余额查询接口。API Key 管理由登录后的 User JWT 接口负责，不属于 Partner 开放 API。

GET/api/v1/activation/getServices

获取服务目录

X-API-Key

无业务参数返回系统支持的全部已启用接码服务；合作方可初始化服务选择器或定时刷新本地缓存。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key，必须命中当前密钥的 IP 白名单。
X-Request-Id	Header	string	否	合作方可选请求关联号，格式为 1～64 位安全字符。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	array	是	成功时为 array；失败响应中可能为 null。具体结构见下方 data 字段。
data[]	array	是	服务列表数组，按平台展示顺序返回。
data[].serviceCode	string	是	平台服务代码，用于查国家、报价和下单。
data[].serviceName	string	是	服务展示名称。

请求示例

GET https://api.mangootp.com/api/v1/activation/getServices
X-API-Key: mago_live_xxx
Accept: application/json

成功响应

{
  "code": "0",
  "message": "success",
  "data": [
    {
      "serviceCode": "telegram",
      "serviceName": "Telegram"
    }
  ]
}

常见错误

AUTH-E001：未携带 API Key。
AUTH-E002：API Key 无效、已撤销、过期或 IP 白名单不匹配。

GET/api/v1/activation/getCountries

获取支持国家

X-API-Key

无业务参数返回系统支持的全部已启用国家，用于生成国家选择器；报价和库存由 getPrice 同步返回。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key。
X-Request-Id	Header	string	否	合作方可选请求关联号，格式为 1～64 位安全字符。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	array	是	成功时为 array；失败响应中可能为 null。具体结构见下方 data 字段。
data[]	array	是	系统支持的全部已启用国家列表。
data[].countryCode	string	是	ISO 国家代码，用于报价和下单。
data[].countryName	string	是	当前语言的国家展示名。
data[].flagEmoji	string / null	否	国家旗帜 emoji。
data[].phonePrefix	string / null	否	国家电话区号。

请求示例

GET https://api.mangootp.com/api/v1/activation/getCountries
X-API-Key: mago_live_xxx
Accept: application/json

成功响应

{
  "code": "0",
  "message": "success",
  "data": [
    {
      "countryCode": "US",
      "countryName": "United States",
      "flagEmoji": "🇺🇸",
      "phonePrefix": "+1"
    }
  ]
}

常见错误

AUTH-E001：未携带 API Key。
AUTH-E002：API Key 无效、已撤销、过期或 IP 白名单不匹配。

GET/api/v1/activation/getPrice

获取指定国家服务价格

X-API-Key

返回当前平台售价和该服务、国家组合的整数库存估算；该接口不签发报价令牌。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key。
X-Request-Id	Header	string	否	合作方可选请求关联号，1～64 位字母、数字、点、下划线、冒号或连字符；会写入技术审计，但不替代平台 X-Trace-Id。
service	Query	string	是	平台服务代码。
country	Query	string	是	ISO 国家代码，例如 US、GB。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	object	是	成功时为 object；失败响应中可能为 null。具体结构见下方 data 字段。
data.service	string	是	请求的服务代码。
data.country	string	是	请求的国家代码。
data.sellPrice	decimal number	是	当前 Catalog 行的平台单位售价。
data.currency	string	是	接口当前返回的价格币种代码为 USD。
data.availableCount	integer	是	当前 Catalog 聚合库存估算，不代表为调用方预留。

请求示例

GET https://api.mangootp.com/api/v1/activation/getPrice?service=telegram&country=US
X-API-Key: mago_live_xxx
Accept: application/json

成功响应

{
  "code": "0",
  "message": "success",
  "data": {
    "service": "telegram",
    "country": "US",
    "sellPrice": 1.050000,
    "currency": "USD",
    "availableCount": 42
  }
}

常见错误

OTP-E006：当前服务和国家暂无库存。
COMMON-E002：service 或 country 格式非法。
AUTH-E002：API Key 校验失败。

POST/api/v1/activation/createOrder

创建接码订单

X-API-Key

创建接码订单并按当前 Catalog 售价冻结余额。未传 maxSellPrice 时当前售价必须等于 sellPrice；传入上限时当前售价不得超过上限。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key。
X-Request-Id	Header	string	否	合作方可选请求关联号，1～64 位字母、数字、点、下划线、冒号或连字符；会写入技术审计，但不替代平台 X-Trace-Id。
partnerOrderNo	Body	string	是	合作方系统生成的业务订单号。同一账户、接码业务下必须唯一；同一次业务请求重试时必须保持不变。
service	Body	string	是	平台服务代码。
country	Body	string	是	ISO 国家代码。
sellPrice	Body	decimal number	是	合作方最近读取的平台售价；最多六位小数且必须大于零。
maxSellPrice	Body	decimal number	否	可选的最高接受售价，必须不小于 sellPrice。未提交时不允许任何价格变化。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	object	是	成功时为 object；失败响应中可能为 null。具体结构见下方 data 字段。
data.orderNo	string	是	MangoOTP 接码订单号。
data.partnerOrderNo	string	是	合作方订单号。
data.status	string	是	接码订单当前状态。
data.phone	string / null	否	已分配号码；分配前为空。
data.smsCode	string / null	否	平台提取的 OTP；收到短信前为空。
data.payAmount	decimal number	是	本订单向用户冻结并最终结算的应付金额。
data.currency	string	是	订单计价币种，当前固定为 USD。

请求示例

POST https://api.mangootp.com/api/v1/activation/createOrder
X-API-Key: mago_live_xxx
Accept: application/json
Content-Type: application/json

{
  "partnerOrderNo": "partner-order-20260707-001",
  "service": "telegram",
  "country": "US",
  "sellPrice": 1.05,
  "maxSellPrice": 1.10
}

成功响应

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "PENDING",
    "phone": null,
    "smsCode": null,
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

常见错误

ACC-E004：账户可用余额不足。
ORD-E004：sellPrice 或 maxSellPrice 与当前售价规则不符。
OTP-E006：当前 Catalog 无可用库存。
COMMON-E003：售价格式或精度非法。

GET/api/v1/activation/getOrders

查询接码订单列表

X-API-Key

分页查询当前 API Key 所属用户的接码订单。适合合作方后台同步订单状态和历史记录。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key。
X-Request-Id	Header	string	否	合作方可选请求关联号，1～64 位字母、数字、点、下划线、冒号或连字符；会写入技术审计，但不替代平台 X-Trace-Id。
page	Query	number	否	页码，默认 1。
size	Query	number	否	每页数量，默认 20，受平台最大分页限制。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	object	是	成功时为 object；失败响应中可能为 null。具体结构见下方 data 字段。
data.total	number	是	符合条件的订单总数。
data.records[]	array	是	当前页订单记录。
data.records[].orderNo	string	是	MangoOTP 接码订单号。
data.records[].partnerOrderNo	string	是	合作方订单号。
data.records[].status	string	是	接码订单当前状态。
data.records[].serviceCode	string	是	服务代码。
data.records[].countryCode	string	是	ISO 国家代码。
data.records[].phone	string / null	否	已分配号码；分配前为空。
data.records[].smsCode	string / null	否	平台提取的 OTP；收到短信前为空。
data.records[].payAmount	decimal number	是	本订单向用户冻结并最终结算的应付金额。
data.records[].refundAmount	decimal number	是	已退还给用户的金额。
data.records[].createdAt	datetime string	是	订单创建时间。
data.records[].completedAt	datetime string / null	否	订单完成时间；未完成时为空。

请求示例

GET https://api.mangootp.com/api/v1/activation/getOrders?page=1&size=20
X-API-Key: mago_live_xxx
Accept: application/json

成功响应

{
  "code": "0",
  "message": "success",
  "data": {
    "total": 1,
    "records": [
      {
        "orderNo": "AO202607070000000001",
        "partnerOrderNo": "partner-order-20260707-001",
        "status": "ACTIVE",
        "serviceCode": "telegram",
        "countryCode": "US",
        "phone": "+12025550123",
        "smsCode": null,
        "payAmount": 1.050000,
        "refundAmount": 0.000000,
        "createdAt": "2026-06-22T18:07:22",
        "completedAt": null
      }
    ]
  }
}

常见错误

AUTH-E002：API Key 校验失败。
COMMON-E003：page 或 size 超出范围。

GET/api/v1/activation/getOrder?orderNo={orderNo}

查询接码订单详情

X-API-Key

查询一个接码订单的当前状态、手机号和验证码。合作方应读取业务 code 与 data.status，而不是只依赖 HTTP 状态码。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key。
X-Request-Id	Header	string	否	合作方可选请求关联号，1～64 位字母、数字、点、下划线、冒号或连字符；会写入技术审计，但不替代平台 X-Trace-Id。
orderNo	Query	string	是	MangoOTP 接码订单号。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	object	是	成功时为 object；失败响应中可能为 null。具体结构见下方 data 字段。
data.orderNo	string	是	MangoOTP 接码订单号。
data.partnerOrderNo	string	是	合作方订单号。
data.status	string	是	接码订单当前状态。
data.phone	string / null	否	已分配号码；分配前为空。
data.smsCode	string / null	否	平台提取的 OTP；收到短信前为空。
data.payAmount	decimal number	是	本订单向用户冻结并最终结算的应付金额。
data.currency	string	是	订单计价币种，当前固定为 USD。

请求示例

GET https://api.mangootp.com/api/v1/activation/getOrder?orderNo=AO202607070000000001
X-API-Key: mago_live_xxx
Accept: application/json

成功响应

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "SUCCESS",
    "phone": "+12025550123",
    "smsCode": "834921",
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

常见错误

ORD-E001：订单不存在或不属于当前 API Key 用户。
COMMON-E002：orderNo 格式非法。

POST/api/v1/activation/cancelOrder?orderNo={orderNo}

取消接码订单

X-API-Key

取消仍处于可取消状态的订单。在途处理、已收到短信或终态订单不会被重复取消。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key。
X-Request-Id	Header	string	否	合作方可选请求关联号，1～64 位字母、数字、点、下划线、冒号或连字符；会写入技术审计，但不替代平台 X-Trace-Id。
orderNo	Query	string	是	MangoOTP 接码订单号。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	object	是	成功时为 object；失败响应中可能为 null。具体结构见下方 data 字段。
data.orderNo	string	是	MangoOTP 接码订单号。
data.partnerOrderNo	string	是	合作方订单号。
data.status	string	是	接码订单当前状态。
data.phone	string / null	否	已分配号码；分配前为空。
data.smsCode	string / null	否	平台提取的 OTP；收到短信前为空。
data.payAmount	decimal number	是	本订单向用户冻结并最终结算的应付金额。
data.currency	string	是	订单计价币种，当前固定为 USD。

请求示例

POST https://api.mangootp.com/api/v1/activation/cancelOrder?orderNo=AO202607070000000001
X-API-Key: mago_live_xxx
Accept: application/json

成功响应

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "CANCELLED",
    "phone": null,
    "smsCode": null,
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

常见错误

ORD-E003 / ORD-E005：当前状态不允许取消。
ORD-E001：订单不存在或不属于当前 API Key 用户。

GET/api/v1/account/getBalance

获取账户余额

X-API-Key

仅凭 API Key 身份返回其所属用户的 MAIN 账户可用余额；不接收邮箱或用户标识，也不提供任何资金写操作。

参数	位置	类型	必填	说明
X-API-Key	Header	string	是	合作方 API Key，固定包含 account:read scope。
X-Request-Id	Header	string	否	合作方可选请求关联号；格式与其他 Partner API 相同。

返回字段	类型	必返	说明
code	string	是	统一业务码。成功固定为 "0"；失败时按错误码处理。code 是唯一机器可读业务判断契约。
message	string	是	辅助日志文案，不得解析或用于业务判断。后端仅维护英文和简体中文，其他请求语言回退英文。
data	object	是	成功时为 object；失败响应中可能为 null。具体结构见下方 data 字段。
data.accountType	string	是	固定为 MAIN。
data.currency	string	是	主账户币种，当前为 USD。
data.availableBalance	decimal number	是	主账户当前可用余额。

请求示例

GET https://api.mangootp.com/api/v1/account/getBalance
X-API-Key: mago_live_xxx
Accept: application/json

成功响应

{
  "code": "0",
  "message": "success",
  "data": {
    "accountType": "MAIN",
    "currency": "USD",
    "availableBalance": 97.410000
  }
}

常见错误

AUTH-E002：API Key 无效、撤销、过期或 IP 白名单不匹配。
ACC-E001：MAIN 主账户不存在。

Webhook 事件

Webhook 仅在接码订单收到短信时通知合作方系统。回调地址在登录后的 API 密钥页面配置。

activation.sms_received

接码短信送达

接码订单收到短信并解析 OTP 后触发。接码创建接口已同步返回手机号，因此号码分配不再单独推送。

{
  "eventId": "evt_AO202607070000000001_activation_sms_received",
  "eventType": "activation.sms_received",
  "status": "SUCCESS",
  "orderNo": "AO202607070000000001",
  "occurredAt": "2026-06-22T18:09:01Z",
  "data": {
    "orderNo": "AO202607070000000001",
    "service": "telegram",
    "country": "US",
    "phone": "+12025550123",
    "payAmount": 1.050000,
    "smsCode": "834921",
    "smsText": "Telegram code: 834921"
  }
}

verified_user

Webhook 签名与重试

配置入口：登录后在 API 密钥页面为当前 API Key 配置一个 Webhook URL；Webhook 与接口请求共用同一个 API Key 归属关系。
签名方式：每次投递都会携带 X-Webhook-Signature: sha256=<hex>。先对当前 API Key 做 SHA-256 得到 64 位小写十六进制文本，再以该文本的 UTF-8 字节为 HMAC-SHA256 密钥，对原始 HTTP JSON body 字节直接签名。Webhook 不生成独立签名密钥。
辅助请求头：X-Webhook-Event 表示事件类型，X-Webhook-Delivery-Id 在同一业务事件的全部通知中保持不变，X-Webhook-Attempt 表示第几次通知，X-Webhook-Timestamp 表示 Unix 秒级时间戳；这些辅助头不参与签名。
通知策略：最多通知 5 次，包括首次立即通知；未确认时分别等待 1、3、5、15 分钟后继续通知，因此事件相对时间为 0、1、4、9、24 分钟。第 5 次仍未确认则结果为 FAIL，手动通知也不会突破 5 次上限。
接收端确认：仅当 HTTP 状态为 2xx 且响应体去除首尾空白后严格等于 SUCCESS，平台才停止通知。接收端应先验签，再按 eventId 做幂等入库；Webhook 不能替代订单查询接口。

Webhook 字段	类型	必返	说明
eventType	string	是	业务事件类型，对应 X-Webhook-Event，例如 activation.sms_received。
eventId	string	是	事件唯一 ID，接收方应按该字段做幂等入库。
status	string	条件必返	事件发生后的订单状态；订单类事件必返。
orderNo	string	条件必返	订单类事件顶层必返的业务单号，方便接收方日志和告警直接定位订单。
occurredAt	datetime string	是	事件发生时间，ISO-8601 格式。
data.orderNo	string	是	平台接码业务单号，以 AO 开头。
data.service	string	否	服务代码；失败事件中可能为空。
data.country	string	否	国家代码；失败事件中可能为空。
data.phone	string	条件必返	接码订单已分配的手机号；创建订单响应已同步返回，Webhook 在短信送达时返回。
data.smsCode	string	条件必返	短信送达事件中解析出的 OTP。
data.smsText	string	否	短信原文或内容预览，供合作方展示或排查。
data.payAmount	decimal number	否	接码短信送达事件中的用户实付金额。

状态机与轮询

客户侧不要只依赖 HTTP 状态码。请读取业务 code 和订单 status；终态不可逆。

PENDING

订单已创建，正在分配号码或等待明确结果；此状态不可取消。

ACTIVE

号码已分配，等待短信；可轮询订单详情获取 smsCode。

SUCCESS

已收到验证码并完成订单，终态。

TIMEOUT / FAILED / CANCELLED / BANNED

退款或终止后的终态，具体语义由状态名区分。

错误码处理

业务失败会返回统一 code。客户端需要按 code 做重试、换国家、充值或人工处理。

错误码	含义	建议处理
COMMON-E001 / E002 / E003	缺少参数、格式错误或超出范围。	检查必填字段、长度、金额精度和 code 格式。
AUTH-E001 / AUTH-E002	未认证或认证失效。	检查 X-API-Key 是否正确、是否撤销、过期或 IP 白名单不匹配。
ACC-E004	账户可用余额不足。	充值并确认可用余额更新后重试。
OTP-E006 / SMS-E003	当前组合暂无可用库存。	更换国家/服务或稍后重试。
ORD-E001 / ORD-E003 / ORD-E005	订单不存在或当前状态不允许该操作。	刷新订单状态后再判断下一步。
ORD-E004	提交售价或接受价格上限校验失败。	重新获取价格，并提交新的 sellPrice；需要容忍涨价时同时提交 maxSellPrice。
SMS-E001 / SMS-E004	号码服务暂时不可用。	先按业务单号查询结果；结果明确失败后再稍后重试，长时间无结果请联系客服。

speed

接口限流与查询频率

API Key 级限流：创建密钥时可配置 rateLimitQps，默认 5 QPS；可配置上限以 USER 后台创建密钥页面显示的当前平台策略为准。
平台通用窗口限流：未命中特定规则时，GET 默认 300 次/分钟，非 GET 默认 30 次/分钟；触发限流返回 HTTP 429 与业务码 COMMON-E429。
响应头：限流响应会返回 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset，客户端应按这些头做退避。
价格查询返回当前 Catalog 售价和库存估算，不包含有效期；创建订单始终重新读取当前售价和可售状态。
接码订单轮询：建议同一订单 5-10 秒查询一次；ACTIVE 状态下过高频率查询不会加快短信到达，只会增加限流风险。