开发者

API 参考

所有 SMetaGateway REST 端点，基于 OpenAPI 3.1 契约生成。请从服务器使用 Bearer API 密钥；金额为十进制字符串。

基础 URL: https://smg.sabco24.com/api/v1
版本: 0.2.0 · OpenAPI 3.1

端点

按资源分组的全部操作。

方法	路径	说明	认证
系统
GET	`/health`	检查服务健康状态和网关模式。	公开
GET	`/config`	读取公共客户端配置，包括验证码站点密钥。	公开
身份验证
POST	`/auth/register`	注册商户并开启所有者会话。	公开
POST	`/auth/login`	登录并开启所有者会话。	公开
POST	`/auth/verify-email`	通过邮件中的链接确认邮箱，并开启所有者会话。	公开
POST	`/auth/password/forgot`	发送密码重置链接邮件。	公开
POST	`/auth/password/reset`	通过重置链接设置新密码并登录。	公开
POST	`/auth/google`	使用 Google 登录或注册，并开启所有者会话。	公开
GET	`/auth/session`	检查此浏览器是否已登录。	公开
POST	`/auth/logout`	结束当前所有者会话。	公开
账户
GET	`/me`	获取商户账户、钱包、发票、密钥、Webhook 和统计数据。	所有者会话
PATCH	`/me`	更新商户显示名称。	所有者会话
钱包
GET	`/wallets`	列出已登记的收款地址。	API 密钥或会话
POST	`/wallets`	登记带校验和的 TRON 收款地址（所有权未验证）。	所有者会话
发票
GET	`/invoices`	列出最近 500 张发票。	API 密钥或会话
POST	`/invoices`	创建发票并将唯一的精确应付金额保留 90 天。	API 密钥或会话
GET	`/invoices/{id}`	获取属于该商户的单张发票。	API 密钥或会话
收银台
GET	`/checkout/{token}`	通过收银台令牌读取对付款人安全的信息。	公开
API 密钥
POST	`/api-keys`	创建 API 密钥（可设置有效期）；密钥只显示一次。	所有者会话
POST	`/api-keys/{id}/roll`	用名称和有效期相同的新密钥替换 API 密钥。	所有者会话
DELETE	`/api-keys/{id}`	立即吊销 API 密钥。	所有者会话
账本
GET	`/ledger.csv`	以 CSV 导出完整运营账本。	API 密钥或会话
Webhooks
POST	`/webhooks`	登记公开 HTTPS Webhook 端点；签名密钥只显示一次。	所有者会话
DELETE	`/webhooks/{id}`	停用端点并取消待投递事件。	所有者会话
POST	`/webhooks/{id}/test`	发送已签名的 webhook.test 事件。	所有者会话
POST	`/webhooks/deliveries/{id}/retry`	重试失败或待处理的 Webhook 投递。	所有者会话
支持
POST	`/support/chat`	使用姓名、邮箱和第一条消息开始网站对话；返回私密对话令牌。	公开
GET	`/support/chat`	使用对话令牌读取网站对话。	公开
POST	`/support/chat/messages`	在网站对话中继续发送消息；已关闭的对话会重新打开。	公开
POST	`/support/contact`	无需账户即可向支持团队发送消息。	公开
GET	`/support/tickets`	列出您的支持工单。	所有者会话
POST	`/support/tickets`	提交支持工单。	所有者会话
GET	`/support/tickets/{id}`	查看您的某个工单及其消息。	所有者会话
POST	`/support/tickets/{id}/messages`	回复您的工单；已关闭的工单会重新打开。	所有者会话
POST	`/support/tickets/{id}/close`	关闭您的工单。	所有者会话
GET	`/support/inbox`	支持团队：列出所有工单，待处理优先。	所有者会话
GET	`/support/inbox/{id}`	支持团队：查看工单及联系信息。	所有者会话
POST	`/support/inbox/{id}/messages`	支持团队：回复商户工单。	所有者会话
POST	`/support/inbox/{id}/status`	支持团队：设置工单状态。	所有者会话

系统

GET`/api/v1/health`

公开

检查服务健康状态和网关模式。

返回: 200 application/json

字段	类型	必填	说明
`status`	`"ok"`	否
`mode`	`"live"`	否	Invoices are confirmed from verified TRON mainnet transfers.
`live_payments_enabled`	`true`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/health"

GET`/api/v1/config`

公开

读取公共客户端配置，包括验证码站点密钥。

captcha is null when Cloudflare Turnstile is not configured; otherwise send captcha_token with sign-in, registration, contact and chat requests. google is null when Google sign-in is not configured.

返回: 200 application/json

字段	类型	必填	说明
`captcha`	`object`	是
`google`	`object`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/config"

身份验证

POST`/api/v1/auth/register`

公开

注册商户并开启所有者会话。

No session is started. The account can sign in after the emailed link (valid 24 hours, single use) is confirmed with POST /auth/verify-email. Answers 503 email_unavailable when the server cannot send email.

请求体

字段	类型	必填	说明
`email`	`string (email)`	是
`password`	`string (password)`	是	length 12–128
`captcha_token`	`string`	否	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048
`name`	`string`	否	length 0–100
`locale`	`"en" \| "fa" \| "ar" \| "zh" \| "es" \| "fr" \| "ru"`	否	Language of the email. — default "en"

返回: 201 application/json

字段	类型	必填	说明
`verification_required`	`true`	是
`email`	`string (email)`	是
`email_sent`	`boolean`	是	False when the SMTP server rejected the message; signing in later sends a new link.

响应

201Account created; confirmation email sent
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Email delivery is not configured (email_unavailable) or captcha verification is unavailable

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Store","email":"merchant@example.com","password":"a-long-unique-passphrase","locale":"en"}'

POST`/api/v1/auth/login`

公开

登录并开启所有者会话。

An account whose email is not yet confirmed answers 403 email_not_verified after a correct password, and a new confirmation link is emailed at most every 5 minutes.

请求体

字段	类型	必填	说明
`email`	`string (email)`	是
`password`	`string (password)`	是	length 10–128
`captcha_token`	`string`	否	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048
`locale`	`"en" \| "fa" \| "ar" \| "zh" \| "es" \| "fr" \| "ru"`	否	Language of the email. — default "en"

返回: 200 application/json

字段	类型	必填	说明
`merchant`	`Merchant`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com","password":"a-long-unique-passphrase"}'

POST`/api/v1/auth/verify-email`

公开

通过邮件中的链接确认邮箱，并开启所有者会话。

token comes from the #verify= fragment of the emailed link. Tokens are single use; a newer email replaces older links.

请求体

字段	类型	必填	说明
`token`	`string`	是	Single-use token from the emailed link. — pattern ^[A-Za-z0-9_-]{43}$

返回: 200 application/json

字段	类型	必填	说明
`merchant`	`Merchant`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAILED_LINK"}'

POST`/api/v1/auth/password/forgot`

公开

发送密码重置链接邮件。

Always answers 202 whether or not an account exists. The link is valid for 1 hour and single use.

请求体

字段	类型	必填	说明
`email`	`string (email)`	是
`captcha_token`	`string`	否	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048
`locale`	`"en" \| "fa" \| "ar" \| "zh" \| "es" \| "fr" \| "ru"`	否	Language of the email. — default "en"

返回: 202 application/json

字段	类型	必填	说明
`success`	`true`	是

响应

202Accepted
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Email delivery is not configured (email_unavailable) or captcha verification is unavailable

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com","locale":"en"}'

POST`/api/v1/auth/password/reset`

公开

通过重置链接设置新密码并登录。

token comes from the #reset= fragment of the emailed link. Every existing session of the account is revoked, and the email counts as confirmed.

请求体

字段	类型	必填	说明
`token`	`string`	是	Single-use token from the emailed link. — pattern ^[A-Za-z0-9_-]{43}$
`password`	`string (password)`	是	length 12–128

返回: 200 application/json

字段	类型	必填	说明
`merchant`	`Merchant`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAILED_LINK","password":"a-new-long-unique-passphrase"}'

POST`/api/v1/auth/google`

公开

使用 Google 登录或注册，并开启所有者会话。

Send the credential returned by Google Identity Services. The server verifies the RS256 signature against Google keys, the issuer, audience (GOOGLE_CLIENT_ID), expiry and email_verified. A new email creates an account (201). An existing confirmed account with the same email is linked to the Google account on first use; an unconfirmed one is claimed by the Google owner and its password stops working.

请求体

字段	类型	必填	说明
`credential`	`string`	是	Google ID token (JWT). — length 20–4096

返回: 200 application/json

字段	类型	必填	说明
`merchant`	`Merchant`	否

响应

200Signed in
201Account created
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Google keys are temporarily unreachable

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/auth/google" \
  -H "Content-Type: application/json" \
  -d '{"credential":"GOOGLE_ID_TOKEN_FROM_GOOGLE_IDENTITY_SERVICES"}'

GET`/api/v1/auth/session`

公开

检查此浏览器是否已登录。

返回: 200 application/json

字段	类型	必填	说明
`signed_in`	`boolean`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/auth/session"

POST`/api/v1/auth/logout`

公开

结束当前所有者会话。

返回: 200 application/json

字段	类型	必填	说明
`success`	`true`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/auth/logout" \
  -H "Content-Type: application/json" \
  -d '{}'

账户

GET`/api/v1/me`

所有者会话

获取商户账户、钱包、发票、密钥、Webhook 和统计数据。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

返回: 200 Dashboard

字段	类型	必填
`merchant`	`Merchant`	是
`wallets`	`Wallet[]`	是
`invoices`	`Invoice[]`	是
`events`	`Event[]`	是
`api_keys`	`ApiKey[]`	是
`webhooks`	`Webhook[]`	是
`deliveries`	`Delivery[]`	是
`stats`	`object`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/me" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

PATCH`/api/v1/me`

所有者会话

更新商户显示名称。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

请求体

字段	类型	必填	说明
`name`	`string`	是	length 1–100

返回: 200 Dashboard

字段	类型	必填
`merchant`	`Merchant`	是
`wallets`	`Wallet[]`	是
`invoices`	`Invoice[]`	是
`events`	`Event[]`	是
`api_keys`	`ApiKey[]`	是
`webhooks`	`Webhook[]`	是
`deliveries`	`Delivery[]`	是
`stats`	`object`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X PATCH "https://smg.sabco24.com/api/v1/me" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

钱包

GET`/api/v1/wallets`

API 密钥或会话

列出已登记的收款地址。

返回: 200 application/json

字段	类型	必填	说明
`wallets`	`Wallet[]`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/wallets" \
  -H "Authorization: Bearer $SMETA_API_KEY"

POST`/api/v1/wallets`

所有者会话

登记带校验和的 TRON 收款地址（所有权未验证）。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

请求体

字段	类型	必填	说明
`label`	`string`	是	length 1–80
`address`	`string`	是	pattern ^T[1-9A-HJ-NP-Za-km-z]{33}$

返回: 200 application/json

字段	类型	必填	说明
`wallet`	`Wallet`	否

响应

200Existing address
201Registered
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/wallets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"label":"Main business wallet","address":"T_YOUR_PUBLIC_TRON_ADDRESS"}'

发票

GET`/api/v1/invoices`

API 密钥或会话

列出最近 500 张发票。

返回: 200 application/json

字段	类型	必填	说明
`invoices`	`Invoice[]`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/invoices" \
  -H "Authorization: Bearer $SMETA_API_KEY"

POST`/api/v1/invoices`

API 密钥或会话

创建发票并将唯一的精确应付金额保留 90 天。

Amount allocation is global for (network, token contract, receiving address, final payable micro-units), including merchants sharing an address. Reservations outlive invoice expiry. Historical amount reuse is assigned review status. The invoice is confirmed only when a verified TRON transfer of exactly payable_amount reaches wallet_address between creation and expiry.

必需请求头

字段	类型	必填	说明
`Idempotency-Key`	`string`	是	每次发票尝试使用唯一密钥；重试时请复用。

请求体 `CreateInvoice`

字段	类型	必填	说明
`merchant_order_id`	`string`	是	Unique per merchant. Reuse the original idempotency key for retries. — length 1–120
`amount`	`string`	是	Base price in USDT; minimum 0.000001, maximum 1000000000. The server adds a disclosed identification adjustment. — pattern ^(0\|[1-9][0-9]{0,9})(\.[0-9]{1,6})?$ · e.g. "49.95"
`wallet_id`	`string`	是	ID of a wallet registered to this merchant. — length 1–100
`description`	`string`	否	length 1–1000
`metadata`	`object`	否	JSON object, at most 16 KiB when serialized. Keep customer secrets out of metadata.
`expires_in_minutes`	`integer`	否	range 1–1440 · default 20

返回: 200 InvoiceEnvelope

字段	类型	必填	说明
`invoice`	`Invoice`	是
`idempotent_replay`	`boolean`	否

响应

200Identical idempotent replay
201Invoice allocated
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/invoices" \
  -H "Authorization: Bearer $SMETA_API_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"merchant_order_id":"1001","amount":"49.95","wallet_id":"WALLET_ID","description":"Example order","expires_in_minutes":20}'

GET`/api/v1/invoices/{id}`

API 密钥或会话

获取属于该商户的单张发票。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Invoice ID

返回: 200 application/json

字段	类型	必填	说明
`invoice`	`Invoice`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/invoices/ID" \
  -H "Authorization: Bearer $SMETA_API_KEY"

收银台

GET`/api/v1/checkout/{token}`

公开

通过收银台令牌读取对付款人安全的信息。

路径参数

字段	类型	必填	说明
`token`	`string`	是	Checkout capability token from checkout_url

返回: 200 application/json

字段	类型	必填	说明
`invoice`	`CheckoutInvoice`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/checkout/TOKEN"

API 密钥

POST`/api/v1/api-keys`

所有者会话

创建 API 密钥（可设置有效期）；密钥只显示一次。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

请求体

字段	类型	必填	说明
`name`	`string`	是	length 1–80
`expires_in_days`	`integer \| null`	否	Days until the key expires. Omit or send null for a key that never expires. — range 1–3650 · e.g. 90

返回: 201 application/json

字段	类型	必填
`api_key`	`ApiKey & object`	否
`secret`	`string`	否
`warning`	`string`	否

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/api-keys" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

POST`/api/v1/api-keys/{id}/roll`

所有者会话

用名称和有效期相同的新密钥替换 API 密钥。

The old key is revoked in the same transaction. The new secret is shown once.

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	API key ID

返回: 201 application/json

字段	类型	必填
`api_key`	`ApiKey & object`	否
`secret`	`string`	否
`warning`	`string`	否
`replaced_key_id`	`string`	否

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/api-keys/ID/roll" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE`/api/v1/api-keys/{id}`

所有者会话

立即吊销 API 密钥。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	API key ID

返回: 200 application/json

字段	类型	必填	说明
`success`	`true`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X DELETE "https://smg.sabco24.com/api/v1/api-keys/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

账本

GET`/api/v1/ledger.csv`

API 密钥或会话

以 CSV 导出完整运营账本。

返回: 200 text/csv

响应

200CSV includes separate base, adjustment and payable columns; not a statutory accounting report.
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/ledger.csv" \
  -H "Authorization: Bearer $SMETA_API_KEY"

Webhooks

POST`/api/v1/webhooks`

所有者会话

登记公开 HTTPS Webhook 端点；签名密钥只显示一次。

Port 443 only. Local/private targets, IP literals, credentials, URL fragments and redirects are rejected. DNS is resolved and checked again at delivery time.

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

请求体

字段	类型	必填	说明
`url`	`string (uri)`	是	length 0–2048

返回: 201 application/json

字段	类型	必填	说明
`webhook`	`Webhook & object`	否
`secret`	`string`	否

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/webhooks" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example.com/hooks/smeta"}'

DELETE`/api/v1/webhooks/{id}`

所有者会话

停用端点并取消待投递事件。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Webhook ID

返回: 200 application/json

字段	类型	必填	说明
`success`	`true`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X DELETE "https://smg.sabco24.com/api/v1/webhooks/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/webhooks/{id}/test`

所有者会话

发送已签名的 webhook.test 事件。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Webhook ID

返回: 200 application/json

字段	类型	必填	说明
`event`	`Event`	否
`deliveries`	`Delivery[]`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/webhooks/ID/test" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST`/api/v1/webhooks/deliveries/{id}/retry`

所有者会话

重试失败或待处理的 Webhook 投递。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Delivery ID

返回: 200 application/json

字段	类型	必填	说明
`delivery`	`Delivery`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/webhooks/deliveries/ID/retry" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST`https://your-server.example/hooks/smeta`

Receive a signed gateway event at your configured URL

Verify HMAC-SHA256(secret, timestamp + "." + original raw body). The signature header is sha256=<lowercase hex>. Reject timestamps outside your five-minute window and deduplicate event IDs. Each retry is freshly signed. GET the saved invoice with your server key and reconcile it before fulfilling once. invoice.confirmed includes the matched on-chain transaction.

必需请求头

X-SMeta-Event-IdX-SMeta-TimestampX-SMeta-Signature

响应

200Persisted successfully or already processed. Any 2xx acknowledges delivery.
400Invalid event
401Invalid or stale signature
503Temporary failure; retry delivery

支持

POST`/api/v1/support/chat`

公开

使用姓名、邮箱和第一条消息开始网站对话；返回私密对话令牌。

Opens a ticket from the visitor's first message, name and email. The response contains chat_token, shown only here; send it as X-Support-Chat-Token to read replies and continue. Contact details are never echoed back.

请求体

字段	类型	必填	说明
`message`	`string`	是	length 1–5000
`name`	`string`	是	length 1–100
`email`	`string (email)`	是	length 0–254
`captcha_token`	`string`	否	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048

返回: 201 application/json

字段	类型	必填	说明
`chat_token`	`string`	是	Private bearer token for this conversation.
`ticket`	`object`	是
`name`	`string`	是
`messages`	`SupportMessage[]`	是

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"Do you support WooCommerce?","name":"Jane Doe","email":"jane@example.com","captcha_token":"TURNSTILE_RESPONSE_TOKEN"}'

GET`/api/v1/support/chat`

公开

使用对话令牌读取网站对话。

必需请求头

字段	类型	必填	说明
`X-Support-Chat-Token`	`string`	是	chat_token returned when the chat was started. Keep it private; it is the only key to this conversation.

返回: 200 application/json

字段	类型	必填
`ticket`	`object`	是
`name`	`string`	是
`messages`	`SupportMessage[]`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/support/chat" \
  -H "X-Support-Chat-Token: VALUE"

POST`/api/v1/support/chat/messages`

公开

在网站对话中继续发送消息；已关闭的对话会重新打开。

必需请求头

字段	类型	必填	说明
`X-Support-Chat-Token`	`string`	是	chat_token returned when the chat was started. Keep it private; it is the only key to this conversation.

请求体

字段	类型	必填	说明
`message`	`string`	是	length 1–5000

返回: 201 application/json

字段	类型	必填
`ticket`	`object`	是
`name`	`string`	是
`messages`	`SupportMessage[]`	是

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/chat/messages" \
  -H "X-Support-Chat-Token: VALUE" \
  -H "Content-Type: application/json" \
  -d '{"message":"Thanks, that helps."}'

POST`/api/v1/support/contact`

公开

无需账户即可向支持团队发送消息。

Creates a ticket that the support team answers by email. Only the reference is returned.

请求体

字段	类型	必填	说明
`name`	`string`	是	length 1–100
`email`	`string (email)`	是	length 0–254
`subject`	`string`	是	length 1–150
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	否	default "general"
`message`	`string`	是	length 1–5000
`captcha_token`	`string`	否	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048

返回: 201 application/json

字段	类型	必填	说明
`ticket`	`object`	否

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/contact" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com","subject":"Question about pricing","category":"general","message":"Do you charge per invoice?","captcha_token":"TURNSTILE_RESPONSE_TOKEN"}'

GET`/api/v1/support/tickets`

所有者会话

列出您的支持工单。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

返回: 200 application/json

字段	类型	必填	说明
`tickets`	`SupportTicket[]`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/support/tickets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/tickets`

所有者会话

提交支持工单。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

请求体

字段	类型	必填	说明
`subject`	`string`	是	length 1–150
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	否	default "general"
`message`	`string`	是	length 1–5000

返回: 201 SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Webhook signature fails","category":"technical","message":"Deliveries return 401 since yesterday."}'

GET`/api/v1/support/tickets/{id}`

所有者会话

查看您的某个工单及其消息。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Ticket ID

返回: 200 SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/support/tickets/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/tickets/{id}/messages`

所有者会话

回复您的工单；已关闭的工单会重新打开。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Ticket ID

请求体

字段	类型	必填	说明
`message`	`string`	是	length 1–5000

返回: 201 SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets/ID/messages" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"message":"string"}'

POST`/api/v1/support/tickets/{id}/close`

所有者会话

关闭您的工单。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Ticket ID

返回: 200 SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets/ID/close" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

GET`/api/v1/support/inbox`

所有者会话

支持团队：列出所有工单，待处理优先。

Requires a session for an account listed in SUPPORT_STAFF_EMAILS.

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

返回: 200 application/json

字段	类型	必填	说明
`tickets`	`SupportTicket[]`	否

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/support/inbox" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

GET`/api/v1/support/inbox/{id}`

所有者会话

支持团队：查看工单及联系信息。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Ticket ID

返回: 200 SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X GET "https://smg.sabco24.com/api/v1/support/inbox/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/inbox/{id}/messages`

所有者会话

支持团队：回复商户工单。

Contact-form tickets return 409 email_reply_required because the visitor has no account.

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Ticket ID

请求体

字段	类型	必填	说明
`message`	`string`	是	length 1–5000

返回: 201 SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

响应

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/inbox/ID/messages" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"message":"string"}'

POST`/api/v1/support/inbox/{id}/status`

所有者会话

支持团队：设置工单状态。

需要控制台所有者会话 Cookie；此操作不接受 API 密钥。

路径参数

字段	类型	必填	说明
`id`	`string`	是	Ticket ID

请求体

字段	类型	必填	说明
`status`	`"open" \| "answered" \| "closed"`	是

返回: 200 SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

响应

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

请求示例

curl -X POST "https://smg.sabco24.com/api/v1/support/inbox/ID/status" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"status":"open"}'

数据模型

API 返回和接受的对象。

Error

字段	类型	必填	说明
`error`	`object`	是
`mode`	`"live"`	是	Invoices are confirmed from verified TRON mainnet transfers.

Merchant

字段	类型	必填	说明
`id`	`string`	是
`name`	`string`	是
`email`	`string (email)`	是
`mode`	`"live"`	是	Invoices are confirmed from verified TRON mainnet transfers.
`support_staff`	`boolean`	否	True when this account is listed in SUPPORT_STAFF_EMAILS and may use the support inbox.

SupportTicket

字段	类型	必填	说明
`id`	`string`	是
`reference`	`string`	是	Human-friendly reference such as SMG-1A2B3C4D5E.
`subject`	`string`	是
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	是	default "general"
`status`	`"open" \| "answered" \| "closed"`	是	open: waiting for support; answered: support replied; closed: resolved.
`source`	`"dashboard" \| "contact" \| "chat"`	是	dashboard: merchant ticket; contact: contact form, answered by email; chat: website chat widget, answered in place.
`created_at`	`string (date-time)`	是
`updated_at`	`string (date-time)`	是
`name`	`string`	否	Support inbox only.
`email`	`string (email)`	否	Support inbox only.
`merchant_id`	`string \| null`	否	Support inbox only. Null for contact-form and website-chat tickets.
`merchant_name`	`string \| null`	否	Support inbox only.

SupportMessage

字段	类型	必填
`id`	`string`	是
`author`	`"customer" \| "staff"`	是
`body`	`string`	是
`created_at`	`string (date-time)`	是

SupportThread

字段	类型	必填	说明
`ticket`	`SupportTicket`	是
`messages`	`SupportMessage[]`	是

Wallet

字段	类型	必填
`id`	`string`	是
`label`	`string`	是
`address`	`string`	是
`network`	`"tron-mainnet"`	是
`verified`	`false`	是
`verification_status`	`"unverified"`	是
`created_at`	`string (date-time)`	是

CheckoutInvoice

字段	类型	必填	说明
`id`	`string`	是
`base_amount`	`string`	是	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`adjustment`	`string`	是	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`payable_amount`	`string`	是	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`wallet_address`	`string`	是
`status`	`"pending" \| "confirmed" \| "expired" \| "review"`	是
`created_at`	`string (date-time)`	否
`expires_at`	`string (date-time)`	否
`reserved_until`	`string (date-time)`	否
`description`	`string`	否
`tx_hash`	`string \| null`	否	TRON transaction hash of the matched USDT transfer (64 hex characters).
`mode`	`"live"`	是	Invoices are confirmed from verified TRON mainnet transfers.
`network`	`"tron-mainnet"`	否
`token`	`"USDT"`	否
`token_contract`	`"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`	否
`amount_reuse_review`	`boolean`	否
`merchant_name`	`string`	是	Merchant business display name.

Invoice

字段	类型	必填	说明
`id`	`string`	是
`base_amount`	`string`	是	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`adjustment`	`string`	是	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`payable_amount`	`string`	是	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`wallet_address`	`string`	是
`status`	`"pending" \| "confirmed" \| "expired" \| "review"`	是
`created_at`	`string (date-time)`	否
`expires_at`	`string (date-time)`	否
`reserved_until`	`string (date-time)`	否
`description`	`string`	否
`tx_hash`	`string \| null`	否	TRON transaction hash of the matched USDT transfer (64 hex characters).
`mode`	`"live"`	是	Invoices are confirmed from verified TRON mainnet transfers.
`network`	`"tron-mainnet"`	否
`token`	`"USDT"`	否
`token_contract`	`"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`	否
`amount_reuse_review`	`boolean`	否
`checkout_url`	`string (uri)`	否
`checkout_token`	`string`	否	Capability token. Treat checkout URLs as confidential invoice links.
`merchant_order_id`	`string`	是
`wallet_id`	`string`	是
`metadata`	`object`	是

CreateInvoice

字段	类型	必填	说明
`merchant_order_id`	`string`	是	Unique per merchant. Reuse the original idempotency key for retries. — length 1–120
`amount`	`string`	是	Base price in USDT; minimum 0.000001, maximum 1000000000. The server adds a disclosed identification adjustment. — pattern ^(0\|[1-9][0-9]{0,9})(\.[0-9]{1,6})?$ · e.g. "49.95"
`wallet_id`	`string`	是	ID of a wallet registered to this merchant. — length 1–100
`description`	`string`	否	length 1–1000
`metadata`	`object`	否	JSON object, at most 16 KiB when serialized. Keep customer secrets out of metadata.
`expires_in_minutes`	`integer`	否	range 1–1440 · default 20

InvoiceEnvelope

字段	类型	必填	说明
`invoice`	`Invoice`	是
`idempotent_replay`	`boolean`	否

ApiKey

字段	类型	必填	说明
`id`	`string`	是
`name`	`string`	是
`prefix`	`string`	是	First characters of the secret, for identification only.
`mode`	`"live"`	是	Invoices are confirmed from verified TRON mainnet transfers.
`scopes`	`"invoices:read" \| "invoices:write" \| "ledger:read"[]`	是
`created_at`	`string (date-time)`	否
`last_used_at`	`string \| null (date-time)`	否
`revoked_at`	`string \| null (date-time)`	否
`expires_at`	`string \| null (date-time)`	否	Null when the key never expires.
`expired`	`boolean`	否

Webhook

字段	类型	必填
`id`	`string`	是
`url`	`string (uri)`	是
`created_at`	`string (date-time)`	否
`active`	`boolean`	是

Delivery

字段	类型	必填
`id`	`string`	是
`webhook_id`	`string`	是
`event_id`	`string`	是
`status`	`"pending" \| "sending" \| "delivered" \| "failed" \| "cancelled"`	是
`attempts`	`integer`	是
`next_attempt_at`	`string \| null (date-time)`	否
`last_error`	`string \| null`	否
`response_status`	`integer \| null`	否
`created_at`	`string (date-time)`	否
`delivered_at`	`string \| null (date-time)`	否

Event

字段	类型	必填	说明
`id`	`string`	是
`type`	`"invoice.created" \| "invoice.confirmed" \| "invoice.expired" \| "invoice.review" \| "webhook.test"`	是
`created_at`	`string (date-time)`	是
`mode`	`"live"`	是	Invoices are confirmed from verified TRON mainnet transfers.
`data`	`object`	是

ConfirmedEvent

字段	类型	必填	说明
`id`	`string`	是
`type`	`"invoice.confirmed"`	是
`created_at`	`string (date-time)`	是
`mode`	`"live"`	是	Invoices are confirmed from verified TRON mainnet transfers.
`data`	`object`	是

Dashboard

字段	类型	必填
`merchant`	`Merchant`	是
`wallets`	`Wallet[]`	是
`invoices`	`Invoice[]`	是
`events`	`Event[]`	是
`api_keys`	`ApiKey[]`	是
`webhooks`	`Webhook[]`	是
`deliveries`	`Delivery[]`	是
`stats`	`object`	是

端点

系统

响应

响应

身份验证

请求体

响应

请求体

响应

请求体

响应

请求体

响应

请求体

响应

请求体

响应

响应

响应

账户

响应

请求体

响应

钱包

响应

请求体

响应

发票

响应

必需请求头

请求体 CreateInvoice

响应

路径参数

响应

收银台

路径参数

响应

API 密钥

请求体

响应

路径参数

响应

路径参数

响应

账本

响应

Webhooks

请求体

响应

路径参数

响应

路径参数

响应

路径参数

响应

必需请求头

响应

支持

请求体

响应

必需请求头

响应

必需请求头

请求体

响应

请求体

响应

响应

请求体

响应

路径参数

响应

路径参数

请求体

响应

路径参数

响应

响应

路径参数

响应

请求体 `CreateInvoice`