开发者

开发文档

通过 HTTP API 或 SMPP 发送短信和 RCS，跟踪每条消息的状态，并在您的系统中接收状态更新。

快速开始

创建账户，并通过 PIX 或 USDT 充值。
在控制台的“API / SMPP 连接”中登记您服务器的 IP。只有这些地址可以使用 API 和 SMPP。
生成凭据：API 令牌以及 SMPP 用户名和密码。凭据只显示一次，请妥善保存。
在控制台中查看您的发件人 SID，或调用 GET /api/v1/routes.

身份验证

所有请求均使用 HTTPS，并在 Authorization 请求头中携带令牌：

Authorization: Bearer TOKEN
Content-Type: application/json

切勿将令牌放在应用、网页或公开代码仓库中。如怀疑泄露，请在控制台重新生成凭据，旧凭据会立即失效。

API 基础地址与凭据一起显示在控制台中。

短信 API

POST/api/v1/messages

发送一条消息。

字段	必填	说明
`sid`	是	您账户的发件人 SID。
`to`	是	目标号码。巴西号码可带或不带 55（5511999990000 或 11999990000）。
`text`	是	消息内容。
`reference`	否	您的自定义标识（最多 128 个字符）。重复提交相同的 reference 不会重复发送。
`channel`	否	sms（默认）或 rcs。

curl -X POST https://[API]/api/v1/messages \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sid":"SID","to":"5511999990000","text":"您的验证码是 482913","reference":"pedido-1001"}'

响应：

{ "id": "dx1234567", "status": "queued", "amount": 45000, "currency": "BRL" }

amount 字段为扣费金额，单位为货币的百万分之一（45000 = 0.045 巴西雷亚尔）。

支持长短信：Diamond X 自动拆分文本，手机上显示为一条完整消息。每段最多 153 个无重音字符（含重音、表情或中文时为 67 个），最多 20 段。按段计费；不超过 160 个字符（含重音、表情或中文时为 70 个）的消息计为一段。

GET/api/v1/messages/{id}

查询消息状态。

{ "id": "dx1234567", "status": "delivered", "phone": "5511999990000", "channel": "sms",
  "created_at": "…", "updated_at": "…", "delivered_at": "…" }

Status	含义
`queued`	在 Diamond X 队列中。
`sent`	运营商已接收，等待确认。
`delivered`	已送达手机。
`undelivered`	运营商无法送达。
`failed`	发送失败或被拒绝。
`unknown`	运营商未返回最终确认。

GET/api/v1/routes

列出您账户中可用的 SID，包括渠道（sms 或 rcs）、国家、价格和币种。

GET/api/v1/balance

显示可用余额、进行中发送所预留的余额以及账户币种。

RCS

账户开通 RCS SID 后，使用同一个发送接口，并设置 "channel": "rcs":

{"sid":"SID_RCS","to":"5511999990000","text":"您的订单已发货！","channel":"rcs"}

消息会带着您品牌的名称、标志和认证标识送达。卡片、轮播、按钮以及品牌代理注册，请参阅控制台中的 RCS 指南。

Webhooks

在控制台登记您系统的 HTTPS 地址，即可接收消息状态更新，无需轮询 API。

每次回调都会在请求头 X-DiamondX-Signature 中附带 HMAC-SHA256 签名，密钥显示在控制台中。处理前请先校验签名。
请返回 HTTP 2xx。如果您的系统不可用，Diamond X 会重试。
使用 id 或您的 reference 将事件与发送记录对应。

SMPP

SMPP 3.4 协议，支持 transmitter、receiver 和 transceiver 绑定。
每个账户最多 3 个连接，每个连接有独立的用户名和密码。
在 registered_delivery 中请求后，通过 deliver_sm 返回送达报告（DLR）。
长短信：使用 UDH 或 SAR 分段发送，手机上合并显示。
仅允许控制台中登记的 IP 访问。
地址、端口、用户名（system_id）和密码在登录后显示于控制台的“API / SMPP 连接”中。

错误码

错误会返回 HTTP 状态码，并在 error 字段中附带说明。

状态码	发生情况
`400`	字段无效或缺失、号码不属于该 SID 所在国家，或 SID 未在账户中启用。
`401`	令牌缺失或无效。
`403`	无访问权限：IP 未登记、账户未激活或 SID 未开通。
`404`	未找到消息。

集成遇到问题？请联系技术支持： WhatsApp · site@diamondx.app