从 v1 迁移 — 快速版

阅读时间：2 分钟。如需逐个端点的审计，请见从 v1 迁移 — 完整参考。

本指南面向已经在 API v1（https://api.corpxapi.com）上运行的集成方。新集成请直接使用 v2 并阅读快速入门指南。

需要修改的内容（请在你的代码中更新）

项目	之前（v1）	之后（v2）
API 基础 URL	https://api.corpxapi.com/v1	https://tenant.api.corpx.com/v1
OAuth Token URL	旧 Cognito 域名	https://auth.api.corpx.com/oauth2/token
client_id / client_secret	当前的	新的（与切换日期一起通过安全通道交付）
OAuth Scopes	api/full	api2/read api2/write

不会变的内容

• 所有 /v1/accounts/{accountId}/... 路径（除下方 4 项例外）
• 你的 webhook URL 和 HMAC 密钥
• account_id 仍是相同的 UUID
• Webhook 载荷与请求头
• BigPix 请求体 — 仍为 {amount, key, ...}（分块仍在服务端完成）

5 项具体例外

如果你的集成依赖以下任何一项，请在切换前阅读完整参考。否则只需切换 URL + 凭证即可。

例外	变更内容
Statement (GET /v1/accounts/{id}/statement)	路径相同，但现在是实时查询（无本地缓存）。延迟从约 50 ms 上升到约 500 ms–1.5 s，行项里不再包含派生的 tariff_ref 字段。对手方银行信息被简化为 name + document——branch、account、bankCode、bankIspb、pixKey 不再出现在对账单的行项中（清算银行不在其对账单端点中暴露这些字段）。如需完整 payload，请使用 GET /v1/accounts/{id}/pix/payments/lookup?endToEndId=... 或等待 outbound webhook（pix.in.completed / pix.out.completed）。详见参考文档 §4.1。
PIX QR-code — 响应已扁平化	4 个 QR 端点（POST /pix/qr-code/dynamic、POST /pix/qr-code/static、GET /pix/qr-code/lookup、DELETE /pix/qr-code）移除了 {statusCode, title, type, message, data: {...}} 信封。字段提升为顶层；data.payload 改名为 emv；data.location 已移除。详见参考文档 §4.9。
MED（/v1/accounts/{id}/pix/med/* 和 med.* webhook）	迁移期间临时返回 503。
fee.* / med.* / edi.* webhook + 交易对象上的 fee 字段	**临时暂停。**手续费作为对账单中的独立条目出现（type=internal-transfer 指向 CORPX_FEE_ACCOUNT_ID，identifier=fee-{slug}-...）。
已废弃与已移除端点	4 条路由作为已废弃别名继续工作（2026-11-21 下线），另有 7 条返回 404 — 见下方表格。

已废弃端点（在 2026-11-21 之前仍可用）

它们仍正常响应，但会在响应中附加 Deprecation: true + Sunset: Sat, 21 Nov 2026 00:00:00 GMT + Link: <successor-url>; rel="successor-version" 三个响应头。请在下次维护窗口迁移到规范替代路径。

已废弃路由（仍可用）	规范替代
GET /v1/accounts/{id}/pix/payments/{paymentId}	GET /v1/accounts/{id}/pix/payments/lookup?identifier=...
GET /v1/accounts/{id}/payments/{paymentId}（无 /pix/ 别名）	GET /v1/accounts/{id}/pix/payments/lookup?identifier=...
GET /v1/accounts/{id}/pix/qr-code（无 /lookup）	GET /v1/accounts/{id}/pix/qr-code/lookup?identifier=...
POST /v1/accounts/{id}/pix/out/qrcode（无连字符）	POST /v1/accounts/{id}/pix/out/qr-code

已移除端点（v2 上返回 404）

如果你从未调用过其中任何一个，请忽略本节。

v1 路由（已移除）	替代方案
POST /v1/webhooks/replay	对账单短窗轮询
GET /v1/integrator/webhooks	GET /v1/webhooks
GET /v1/integrator/webhooks/{id}/deliveries	无替代
POST /v1/integrator/events/replay	无替代
POST /v1/integrator/events/replay/batch	无替代
POST /v1/accounts/{id}/pix/med/{medId}/send	POST .../pix/med/{medId}/decide（但 MED 当前为 503）
POST /v1/accounts/{id}/pix/med/{medId}/response	POST .../pix/med/{medId}/answer（但 MED 当前为 503）

相关文档

• 从 v1 迁移 — 完整参考 — 逐个端点的审计
• Changelog v2.0
• 认证
• Webhooks

支持

联系方式：suporte-api@corpx.com — 工作时间内 1 小时内回复。