API 集成指南
欢迎使用 CorpX API。本指南专为与 /v1 API 和 Webhooks 进行集成的合作伙伴团队编写。它是技术文档的补充，重点介绍在生产环境中开始运营所需的信息。
基础 URL
| 环境 | 基础 URL | 备注 |
|---|---|---|
dev（沙箱） | — | 暂时停用。 沙箱环境即将恢复，请联系支持团队获取更多信息。 |
prd | https://api.corpxapi.com | 生产环境，7×24 小时监控 |
生产环境 URL 和 OAuth 凭证在入驻流程中提供。请将示例中的占位符替换为分配给您的租户的实际值。
身份认证
合作伙伴直接通过我们的身份提供商进行认证。支持以下两种流程：
- Client Credentials – 机器对机器集成。使用 CorpX 颁发的 Client ID/Secret，向令牌端点请求令牌。
- Authorization Code – 基于浏览器的流程。CorpX 配置重定向 URI，并将授权码返回给您的应用程序。
每次调用都需要包含访问令牌：
Authorization: Bearer <access_token>
令牌包含租户上下文和所需角色，因此无需额外的身份标识请求头。
必需的请求头
| 请求头 | 使用时机 | 说明 |
|---|---|---|
X-Tenant-Id | 每次调用（/v1/health 除外） | 在多租户负载中标识租户。API Gateway 和 WAF 需要此请求头。 |
Idempotency-Key | 所有 POST/PUT/PATCH 操作 | 每个请求唯一。CorpX API 将响应存储在 DynamoDB 中，如果请求体不同则返回 HTTP 409。 |
Content-Type | POST/PUT/PATCH | 始终为 application/json。 |
幂等性行为
Idempotency-Key在可变端点上是必需的（/v1/accounts/{accountId}/pix/out、/v1/accounts/{accountId}/pix/out/refund等）。- 密钥在 24 小时后过期。
- 使用相同密钥和相同请求体的第二次请求将返回 HTTP 200/202 和缓存的响应体。
- 使用相同密钥但不同请求体的第二次请求将返回 HTTP 409
idempotency_conflict。
授权矩阵
系统评估 (subject, action, resource, tenant) 的组合。面向合作伙伴开放的操作：
| 资源类型 | 资源键示例 | 操作 |
|---|---|---|
account | account:123456 | read, pix_send, pix_qr_create, pix_qr_static_create, pix_qr_due_date_create, pix_qr_capture, pix_qr_cancel, pix_qr_read, pix_refund, pix_invoice_read |
account_holder | account-holder:123456 | pix_key_list, pix_key_preview, pix_key_create, pix_key_delete, internal_transfer_create, ted_transfer_create |
被拒绝的决策将返回 HTTP 403 forbidden。如需新的操作或角色，请联系 CorpX 支持团队。
错误目录
所有响应都使用 errors.md 中记录的信封格式。重点说明：
- 400
missing_headers→ 缺少或格式错误的请求头。 - 401
invalid_signature→ Webhook 入站 HMAC 验证失败。 - 409
idempotency_conflict→ 幂等性不匹配。 - 429
rate_limit→ 默认突发 100 rps，持续 6,000 rph（每租户）。 - 5xx
partner_error→ CorpX API 不可用或合作伙伴服务中断。建议实现指数退避重试（最多三次）。
集成商门户
使用集成商门户进行管理操作和监控：
- 链接：
https://backoffice.corpxapi.com - 功能：账户数据仪表盘、可用/冻结/总余额、近期交易和账单。
- Webhooks：配置和维护投递 URL。
Webhooks
可用事件
GET /v1/webhooks/events- 列出可用的事件类型
出站（CorpX API → 租户）
- 投递请求头：
X-Webhook-Event、X-Webhook-ID、X-Webhook-Tenant、Authorization、Idempotency-Key。 - IP 白名单：
34.138.140.223、34.138.161.100、35.231.250.193、35.196.71.29、34.138.56.192。 - 重试：指数退避（最多 6 次尝试）和 DLQ 用于手动重放。
- 重放：使用
POST /v1/webhooks/replay端点，传入eventId+tenantId以触发新的投递尝试。 - 支持的认证类型：
HMAC、API_KEY、BASIC、BEARER、IP_WHITELIST。
测试清单
- 身份认证：申请生产凭证并获取您的第一个 OAuth2 令牌。
- 收款（QR Code）：生成动态 QR Code 并使用
examples.md中的示例检查其状态。 - 付款（Cashout）：使用测试密钥执行 PIX
out转账。 - 账户管理：查询余额并获取近期交易账单。
- PIX 密钥：列出、预览和注册账户持有人的 PIX 密钥。
- Webhooks：验证通知接收，并在需要时使用重放功能。
- MED：列出您账户的未处理违规和争议。
支持与联系方式
- Slack： 每位客户专属私有频道——请在入驻流程中向 CorpX 团队申请访问权限。
- 邮箱：
support@corpxapi.com