认证指南

本指南逐步说明如何获取访问令牌以使用 CorpX PIX API。

概述

CorpX API 使用 OAuth 2.0 的 Client Credentials 流程进行认证。您需要使用您的凭据（client_id 和 client_secret）来获取有效的访问令牌。

前提条件

在开始之前，请确保您已具备以下信息：

Client ID - 您的唯一客户端标识符
Client Secret - 用于认证的密钥
X-Tenant-Id - 您的租户标识符（例如：tenant-suaempresa）

信息

如果您还没有凭据，请联系我们的支持团队。

环境

环境	认证 URL	API URL	备注
Sandbox（开发）	—	—	暂时停用。
生产环境	`https://auth.api.corpx.com/oauth2/token`	`https://tenant.api.corpx.com`

第一步：请求访问令牌

请求

curl -X POST "https://auth.api.corpx.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

参数

参数	类型	必填	描述
`grant_type`	string	是	固定为 `client_credentials`
`client_id`	string	是	您的客户端标识符
`client_secret`	string	是	您的密钥
`scope`	string	否	该凭证范围的子集，以空格分隔。省略时返回包含其全部范围的令牌

成功响应 (200 OK)

{
  "access_token": "eyJraWQiOiJ0emwzZWVYWGx1eVlDWHFwQXdBTzJWYWJNQ0llMFMyMXVRWGV2Y281N2RRPSIsImFsZyI6IlJTMjU2In0...",
  "expires_in": 300,
  "token_type": "Bearer"
}

字段	描述
`access_token`	用于 API 调用认证的 JWT 令牌
`expires_in`	有效期（秒）
`token_type`	令牌类型（固定为 `Bearer`）

始终以 expires_in 为准

不同凭证的 TTL 并不相同：在后台管理中创建的凭证有效期为 5 分钟 （expires_in: 300），而早期手工开通的凭证仍为 1 小时。请不要在客户端硬编码 3600——请读取响应中的 expires_in，并留出足够余量提前续期。

错误响应 (401 Unauthorized)

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

第二步：在请求中使用令牌

获取令牌后，在所有 API 请求的 Authorization 头中携带该令牌。

示例：查询余额

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer eyJraWQiOiJ0emwzZWVYWGx1eVlDWHFwQXdBTzJWYWJNQ0llMFMyMXVRWGV2Y281N2RRPSIsImFsZyI6IlJTMjU2In0..." \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json"

必需的请求头

请求头	描述
`Authorization`	格式为 `Bearer {access_token}` 的访问令牌
`X-Tenant-Id`	您的租户标识符
`Content-Type`	带有请求体的请求使用 `application/json`

第三步：续期令牌

令牌会在 expires_in 指定的时间后过期。我们建议：

缓存令牌并记录响应中返回的 expires_in
在过期前续期 —— TTL 为 5 分钟时，等到最后一分钟才续期已经很紧张
处理令牌过期的 403 —— API 返回 403 Forbidden 而非 401；收到后请重新获取令牌并重试该调用

自动续期示例 (Bash)

#!/bin/bash

# Variables
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH_URL="https://auth.api.corpx.com/oauth2/token"

# Function to get token
get_token() {
  response=$(curl -s -X POST "$AUTH_URL" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    -d "client_id=$CLIENT_ID" \
    -d "client_secret=$CLIENT_SECRET")
  
  echo "$response" | jq -r '.access_token'
}

# Get token
TOKEN=$(get_token)

# Use the token
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: tenant-suaempresa"

不同语言的完整示例

Python

import requests

# Credentials
CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_secret"
TENANT_ID = "tenant-suaempresa"

# Get token
auth_response = requests.post(
    "https://auth.api.corpx.com/oauth2/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET
    }
)

token = auth_response.json()["access_token"]

# Use the token
headers = {
    "Authorization": f"Bearer {token}",
    "X-Tenant-Id": TENANT_ID,
    "Content-Type": "application/json"
}

response = requests.get(
    "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance",
    headers=headers
)

print(response.json())

Node.js

const axios = require('axios');

const CLIENT_ID = 'your_client_id';
const CLIENT_SECRET = 'your_client_secret';
const TENANT_ID = 'tenant-suaempresa';

async function getToken() {
  const response = await axios.post(
    'https://auth.api.corpx.com/oauth2/token',
    new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET
    }),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
  );
  return response.data.access_token;
}

async function getBalance(accountId) {
  const token = await getToken();
  
  const response = await axios.get(
    `https://tenant.api.corpx.com/v1/accounts/${accountId}/balance`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Tenant-Id': TENANT_ID,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

凭证权限范围

每个凭证（client_id/client_secret）都带有一组权限范围，精确定义它能做什么。创建凭证时在后台面板（API Credentials，面向租户管理员）选择范围。

可自助授予的范围：

范围	可用于
`read`	账户级的宽泛查询：余额、流水、时间线、账目明细
`qrcode.manage`	静态与动态 QR 码：创建、取消以及查询自身 QR 的付款状态
`pix_keys.manage`	PIX 密钥：列出、创建和删除
`webhooks.manage`	Webhook 订阅、投递记录与重发
`exports.create`	流水导出：创建、跟踪与下载
`med.defend`	MED：查询、回应并上传证据（不决定退款）

每个范围本身就能查询自己的领域。 这正是"只收款"凭证得以实现的原因：只授予 qrcode.manage，凭证即可创建 QR 码并查看是否已付款，而无法访问余额和流水。只有当凭证确实需要账户级的宽泛查询时，才勾选 read。

涉及资金划转的范围由 CorpX 签发，面板不提供：

范围	可用于
`pix_out.create`	所有形式的 PIX out（`/pix/out/*`），并可查询自身付款的状态
`refund.create`	退回已收到的 PIX，并可查询自身退款的状态
`internal_transfer.create`	内部转账，并可查询收款方
`ted.create`	TED，并可查询自身转账的状态
`boleto_payment.create`	Boleto 预览、支付与状态
`med.decide`	决定 MED 退款

在面板中申请这些范围会被拒绝并返回 403 scope_not_self_service——请联系支持，由我们签发凭证。

按账户限制

凭证可以限制在租户的特定账户上。例如，可以给某个子系统一个只能为一个账户生成 QR 码的凭证。访问范围外账户的调用返回 403 forbidden——这是通用的权限错误，而不是 insufficient_scope：范围是有的，只是账户不在允许集合内。该消息刻意不区分"账户不存在"与"账户不在集合内"。

两个维度可以叠加：qrcode.manage 加上单一账户，即得到一个只能在该账户上通过 QR 码收款的凭证——既看不到该账户的余额，也看不到租户的其他账户。

缺少范围时

若凭证缺少该路由所需的范围，API 返回 403 Forbidden 并指明缺少的范围：

{ "errorCode": "insufficient_scope", "message": "esta credencial não tem escopo para esta operação; é necessário o escopo qrcode.manage" }

在细粒度范围之前签发的凭证保持不变：仍使用粗粒度组合（api2/read api2/write）并拥有完整访问权限。

因待办事项被暂停访问

当租户与 CorpX 之间存在未处理的待办事项时，其访问权限可能被临时暂停。暂停不会使凭据失效：同一组 client_id/client_secret 仍可正常获取令牌，拒绝发生在调用 API 时。

状态	仍可使用	其他调用的响应
已暂停	查询（`GET`）——余额、流水、操作状态	写操作返回 `403 tenant_suspended`
已停用	无	所有路由返回 `403 tenant_disabled`

{ "errorCode": "tenant_suspended", "message": "há uma pendência em aberto: operações de escrita estão suspensas até a regularização, consultas seguem disponíveis" }

两点需要注意：

资金不会停止。 收到的 PIX 仍会入账，相关事件的 webhook 也照常发送。暂停限制的是发起新的操作。
恢复是即时的。 待办事项处理完毕后，下一次调用即可恢复访问，无需申请新凭据或新令牌。

待办事项的具体原因不会出现在错误响应中，它显示在后台面板中，供贵方运营人员查看。

常见错误

错误	原因	解决方案
`invalid_client`	Client ID 或 Secret 不正确	检查您的凭据
`invalid_grant`	无效的 grant type	使用 `client_credentials`
`401 Unauthorized`	缺少 `Authorization` 请求头	发送 `Authorization: Bearer <token>`
`403 Forbidden`（令牌无效/已过期）	令牌过期、无效或签名不正确	重新获取令牌。注意过期返回 `403` 而非 `401`
`403 insufficient_scope`	凭证缺少该路由所需的范围	创建带有错误消息中所指范围的凭证
`403 tenant_suspended`	存在未处理的待办事项，写操作被暂停	联系 CorpX 支持处理；查询仍可使用
`403 tenant_disabled`	租户已停用	联系 CorpX 支持恢复访问
`403 forbidden`	令牌有效，但在该 tenant 或该账户上没有权限	检查 `X-Tenant-Id`，并确认该凭证是否被限制在其他账户

最佳实践

切勿将 client_secret 暴露在客户端代码（前端）中
使用环境变量存储凭据
实施令牌缓存以避免不必要的请求
监控过期时间并主动续期令牌
使用 HTTPS 进行所有通信

后续步骤

现在您已了解如何进行认证，请探索其他指南：

动态 QR Code 指南 - 生成 PIX 收款码
Cash Out 指南 - 发起 PIX 转账
退款指南 - 申请退款

概述​

前提条件​

环境​

第一步：请求访问令牌​

请求​

参数​

成功响应 (200 OK)​

错误响应 (401 Unauthorized)​

第二步：在请求中使用令牌​

示例：查询余额​

必需的请求头​

第三步：续期令牌​

自动续期示例 (Bash)​

不同语言的完整示例​

Python​

Node.js​

凭证权限范围​

按账户限制​

缺少范围时​

因待办事项被暂停访问​

常见错误​

最佳实践​

后续步骤​

概述