MultiTEL
开发者

GET/tcr/v2/campaignBuilder/brand/{brand_id}/usecase/{usecase}

读取品牌的活动要求

在准备活动注册之前，读取所选用例的子用例数量范围、运营商资格和消息要求。

本页
  1. 保持品牌与用例一致
  2. 读取当前要求
  3. 综合应用所选运营商的要求
  4. 准备样本和订阅者响应
  5. 在任何注册请求之前进行审查
  6. 处理失败的要求查询
  7. 请求
  8. 响应
  9. 错误
  10. 可用性与副作用

保持品牌与用例一致

请使用您账户下的品牌 ID，以及同一品牌的资格列表所返回的用例值。客户工作流会在向提供方发送请求之前检查所有权。请确认返回对象的 usecase 与所选值一致。针对某一品牌或用例的查询并不能确定另一品牌或用例的要求。

读取当前要求

当前活动表单所使用的要求
字段门户如何使用该字段
minSubUsecases / maxSubUsecases此选择的子用例最小和最大数量。请从有效的子用例目录中选择值，而不要使用自由文本。
mnoMetadata以运营商 ID 为键的运营商特定要求。选择运营商时，请使用当前响应中存在的 ID。
mnoSupport / qualify运营商支持情况和资格。对于任一字段被明确标记为 false 的运营商，门户会将其排除，并要求至少有一个符合条件的所选运营商。
minMsgSamples某运营商所要求的样本数量。门户要求至少提供一个非空样本，并满足符合条件的所选运营商中最高的最低数量要求。
reqSubscriberOptin / reqSubscriberOptout / reqSubscriberHelp必需的订阅者声明。在要求的情况下，对应的声明必须为 true。已启用的声明还需要填写其关键字和响应消息字段。
noEmbeddedLink / noEmbeddedPhone对嵌入链接或电话号码的限制。如果某个符合条件的所选运营商禁止某项已声明的功能，门户将拒绝该功能。

综合应用所选运营商的要求

各运营商的要求可能不同。未提供明确的运营商列表时，门户会考虑响应中的所有运营商元数据；非空列表会将检查限制在所选的那些 ID 范围内。不要只使用第一个运营商的样本数量或声明。请从响应中选择运营商，检查支持情况和资格，满足适用的最高样本最低数量，并在该选择范围内满足必需的选择加入、选择退出和帮助声明。门户会拒绝当前响应中不存在的所选运营商 ID，也会拒绝没有任何符合条件运营商的选择。

要求仅说明必须提供哪些内容；它们并不能证明客户的同意流程或活动内容符合这些要求。请收集真实且具有代表性的样本和声明。不要为了让表单通过而自动开启声明。

准备样本和订阅者响应

当前活动表单使用 sample1 至 sample5 作为消息样本。如果无法在现有表单中满足要求，请停止操作并联系支持团队解决所选项的问题。对于已启用的订阅者声明，请提供其对应的关键字和响应文本：optinKeywords/optinMessage、optoutKeywords/optoutMessage 以及 helpKeywords/helpMessage。请保持样本与所选用例及客户实际发送的消息一致。

在任何注册请求之前进行审查

当品牌、用例或运营商选择发生变化时，请刷新要求。门户会在创建之前重新验证所选用例、子用例数量、运营商资格、样本和声明。请另行审查账户定价和注册条款。此 GET 请求不会注册或批准活动，不会将其共享给消息运营商，也不会分配电话号码。创建和开通是各自独立的操作。

处理失败的要求查询

如果请求失败、返回了意料之外的 JSON，或者与所选用例不匹配，请保持表单处于未完成状态，并让客户在错误解决后重试。不要用空对象替代不可用的要求，也不要假定数据缺失即表示没有要求。请遵守 Retry-After，并对速率限制和可用性故障使用退避策略。

请求

请从允许的源 IP 地址通过 HTTPS 使用已启用的 API 账户。当前路由支持账户认证策略，包括 Basic 认证和已启用的 bearer API 账户。请勿使用提供方凭据。

在 URL 路径中带上品牌 ID 和所选用例值发送 GET 请求。无需请求正文。

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/campaignBuilder/brand/$BRAND_ID/usecase/$USECASE"
路径参数
名称类型必需说明
brand_idstring是与您已认证的 MultiTEL 账户关联的注册机构品牌 ID。请使用品牌 ID，而不是本地数据库行 ID、活动 ID 或企业税号。请将其编码为一个 URL 路径段。
usecasestring是从同一品牌的资格列表中选取的机器可读 usecase 值。请保留其大小写；不要发送翻译后的显示标签。请将其编码为一个 URL 路径段。

响应

当前 TCR 路由直接返回注册机构的 JSON 正文并保留其 HTTP 状态。它不会添加旧版 v3 status/response 封装结构。此处的简化虚构示例并非真实的资格结果。使用前请检查 HTTP 状态和预期的 JSON 结构。门户期望收到一个其 usecase 与所选用例一致的对象。运营商要求位于 mnoMetadata 之下，以运营商 ID 为键。示例中的运营商 ID 和要求均为虚构。可能还会返回提供方的其他字段。

示意性响应结构；并非真实账户数据或当前报价。

{
  "usecase": "2FA",
  "minSubUsecases": 0,
  "maxSubUsecases": 0,
  "mnoMetadata": {
    "12345": {
      "mnoSupport": true,
      "qualify": true,
      "minMsgSamples": 1,
      "reqSubscriberOptin": true,
      "reqSubscriberOptout": true,
      "reqSubscriberHelp": true,
      "noEmbeddedLink": false,
      "noEmbeddedPhone": false
    }
  }
}

错误

  • 401：账户认证失败。请检查 API 凭据、启用状态以及适用的源 IP 限制。
  • 404：该品牌未与已认证账户关联，或提供方找不到所请求的品牌或所选项。本地所有权拒绝会在向提供方发送请求之前返回。
  • 其他注册机构错误：上游 HTTP 状态和正文会被保留。无效或不可用的用例并不等于成功返回的空要求集。
  • 429：已达到账户或共享提供方的请求上限。请遵守 Retry-After。
  • 502/503：传输、提供方或速率限制器的可用性故障。请保留表单并使用退避策略重试。

可用性与副作用

  • 经审阅的 GET 请求会检查现有品牌的所有权、联系注册机构并写入请求审计记录。它不会创建品牌或活动，也不会收取注册费。
  • 提供方的费用元数据并非 MultiTEL 的客户零售报价。门户会在后续注册请求之前另行审查账户定价。
  • 资格和要求可能会发生变化。提交前请针对所选品牌和用例刷新这些信息。查询成功并不代表活动已获批准、已分配号码或已获准开始发送消息。