reachestimate

预估覆盖人数和费用（reachestimate）

通过 API 获取不同最高价格金额下的预计送达量和费用范围，用于投放前的预算与覆盖规划。

• URL：https://api2.nxcloud.com/api/wa/reachestimate
• Method：POST
• Content-Type：application/json
• 需要鉴权：是

接口说明

覆盖人数预估值有助于您了解不同最高价格水平的预计送达量和费用。

可获取各种最高价格金额的预计送达量和费用范围。 预估值是使用历史数据生成的，仅供参考和规划之用。不保证未来的送达效果、费用或表现。实际结果可能因平台条件或其他变量的变化而有所不同。

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

Header 参数

参数名	类型	必选	示例值	说明
accessKey	String	是	fme2na3kdi3ki	用户身份标识
ts	String	是	1655710885431	当前请求时间戳（毫秒），服务端允许客户端请求最大时间误差为 60 秒
bizType	String	是	2	WhatsApp 业务类型，固定值 2
action	String	是	mt	业务操作标识
sign	String	是	6e9506557d1f289501d333ee2c365826	API 入参参数签名，见鉴权文档

Body 参数

参数名	类型	必选	示例值	说明
appkey	String	是	Xxx	应用 appkey
messaging_product	String	是	whatsapp	消息通道，固定值 whatsapp
business_phone	String	是	Xxx	商户手机号（需带国码）
country	String	是	CN	目标地理位置 ISO2 国家码
date_interval	String	是	L1D	历史数据回溯窗口，支持 L1D/L7D/L14D/L28D

请求示例

{
  "appkey": "xxx",
  "messaging_product": "whatsapp",
  "business_phone": "xxx",
  "country": "CN",
  "date_interval": "L1D"
}

响应参数

参数名	类型	说明
code	Integer	结果编码
data	JsonObject	预估结果或下游错误信息
message	String	请求结果说明

data 字段说明（成功场景）

字段名	类型	说明
waba_currency	String	WhatsApp Business 商业账户币种
estimates	Array	不同出价档位对应的送达与费用预估

estimates[] 字段说明

字段名	类型	说明
bid_amount	Number	每 1,000 次消息送达的最高价格（WABA 币种最小单位）
users	Number	目标用户数量（Beta 阶段固定为 1000）
deliveries_lower_bound	Number	该最高价格下的预计送达量下限
deliveries_upper_bound	Number	该最高价格下的预计送达量上限
cost_lower_bound	Number	每 1,000 次送达预计平均费用下限（WABA 币种最小单位）
cost_upper_bound	Number	每 1,000 次送达预计平均费用上限（WABA 币种最小单位）

响应示例

成功示例

{
  "code": 0,
  "data": {
    "waba_currency": "USD",
    "estimates": [
      {
        "deliveries_lower_bound": 0.0,
        "cost_lower_bound": 0.0,
        "deliveries_upper_bound": 83.0,
        "bid_amount": 1830.0,
        "cost_upper_bound": 387.6,
        "users": 1000.0
      },
      {
        "deliveries_lower_bound": 0.0,
        "cost_lower_bound": 0.0,
        "deliveries_upper_bound": 85.0,
        "bid_amount": 2196.0,
        "cost_upper_bound": 765.15936364424,
        "users": 1000.0
      }
    ]
  },
  "message": "success"
}

失败示例：下游数据暂不可用（Stale Data）

{
  "code": 0,
  "data": {
    "error": {
      "error_user_title": "Stale Data",
      "code": 2.0,
      "error_subcode": 5042002.0,
      "message": "Service temporarily unavailable",
      "type": "OAuthException",
      "is_transient": true,
      "fbtrace_id": "A0nZsOkh8MI2X8q_NB09gsU",
      "error_user_msg": "The reach estimation contains stale data. We are working fast to have this fixed. Please try again later."
    }
  },
  "message": "success"
}

失败示例：参数缺失

{
  "code": 9000,
  "data": null,
  "message": "country not null"
}

响应码说明

code	message	说明
0	success	请求已处理成功；若 data.error 非空，表示下游返回业务错误
-1	failure	系统异常，请联系技术支持
1000~100X	鉴权问题	详情见 API 鉴权文档
9000	参数异常	参数遗漏或格式错误
9001	系统业务错误	请联系技术人员排查
10003	该 WhatsApp 号码未绑定应用	请先完成号码与应用绑定

对接注意事项

1. country 和 date_interval 为必填项，缺失会直接返回参数错误。
2. date_interval 仅支持：L1D、L7D、L14D、L28D。
3. 建议业务成功判定条件：code == 0 且 data.error 不存在。
4. 预估结果仅用于规划，非实际送达与费用承诺值。