Base URL
| 环境 | URL |
|---|
| 生产 | https://api.pixusglobal.com |
| 测试 | https://staging.pixusglobal.com |
Staging 环境目前正在维护中，可能会出现不稳定情况。
身份验证
所有路由都需要在 Authorization 头中提供 Bearer Token：
Authorization: Bearer <token>
Content Negotiation
| 格式 | Content-Type | Accept | 描述 |
|---|
| JSON | application/json | application/json | 默认，兼容性好 |
| msgpack | application/msgpack | application/msgpack | 二进制，更高效 |
msgpack 推荐用于服务器间集成，适合对性能有较高要求的场景。
可用端点
| 方法 | 路由 | 描述 |
|---|
| GET | /client/quote | 生成交易报价 |
报价在 5 秒后过期。quoteId 必须在过期前用于创建订单。
| 方法 | 路由 | 描述 |
|---|
| POST | /client/order | 创建买入订单 |
| GET | /client/orders | 筛选列出订单 |
| GET | /client/orders/:id | 按 ID 查询订单 |
| GET | /client/orders/:id/tracking | 追踪加密货币发送 |
订单状态
| 状态 | 描述 |
|---|
pending | 订单已创建，等待付款 |
partial | 已收到部分付款 |
paid | 已全额付款 |
withdrawn | 加密货币已发送至目标钱包 |
settled | 完全结算 |
财务余额
| 方法 | 路由 | 描述 |
|---|
| GET | /client/balance | 查询财务摘要 |
- 法币余额（BRL）和加密货币余额（USDT）
- 信用额度总额、已用和可用
canWithdraw 标志表示是否可以提款
Webhooks
| 方法 | 路由 | 描述 |
|---|
| POST | /client/webhook/config | 配置 Webhook |
| GET | /client/webhook/config | 查询配置 |
| GET | /client/webhook/:id/logs | 特定 Webhook 的日志 |
| GET | /client/webhook/logs | 所有 Webhook 日志 |
Webhook 事件
| 事件 | 描述 |
|---|
quote | 新报价生成 |
order | 新订单创建 |
deposit_fiat | 法币存款（PIX）已收到 |
deposit_crypto | 加密货币存款已收到 |
withdrawal_fiat | 法币提款（PIX）已发送 |
withdrawal_crypto | 加密货币已发送至区块链 |
Payload 格式
Webhook 向配置的 URL 发送 POST 请求，包含事件数据：
{
"event": "order",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 1000,
"symbol": "USDTBRL",
"price": "5.4200",
"side": "BUY",
"timestamp": "2025-01-15T14:30:00.000Z"
}
}
| 参数 | 类型 | 默认值 | 描述 |
|---|
limit | number | 20 | 每页条数 |
offset | number | 1 | 当前页 |
常见错误码
| 状态码 | 描述 |
|---|
400 | 参数无效或报价已过期 |
401 | Token 缺失或无效 |
403 | 无权访问该资源 |
404 | 资源未找到 |
500 | 服务器内部错误 |
