身份认证

如何发送

每次调用都需要两个必填 header:

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

带认证的余额查询调用示例:

curl https://api.exemplo.processamento.com/v1/user/balance \
  -H "Authorization: Bearer $PIX_TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch('https://api.exemplo.processamento.com/v1/user/balance', {
  headers: {
    Authorization: `Bearer ${process.env.PIX_TOKEN}`,
    'Content-Type': 'application/json',
  },
});
const balance = await res.json();

import os
import requests

res = requests.get(
    'https://api.exemplo.processamento.com/v1/user/balance',
    headers={
        'Authorization': f'Bearer {os.environ["PIX_TOKEN"]}',
        'Content-Type': 'application/json',
    },
)
balance = res.json()

req, _ := http.NewRequest("GET", "https://api.exemplo.processamento.com/v1/user/balance", nil)
req.Header.Set("Authorization", "Bearer " + os.Getenv("PIX_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

<?php
$ch = curl_init('https://api.exemplo.processamento.com/v1/user/balance');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('PIX_TOKEN'),
    'Content-Type: application/json',
  ],
]);
$balance = json_decode(curl_exec($ch), true);

存储位置

绝不要将 token 暴露在前端、公开仓库或日志中。请把它当作密码:存放于密钥库,通过环境变量注入。

推荐方案:

Google Secret Manager,如果您已在使用 GCP,这是理想选择。
HashiCorp Vault,适用于自托管环境。
AWS Secrets Manager,AWS 的等价方案。
CI 环境变量,切勿提交到代码库。

错误格式

Pix Processamento 所有的错误响应(4xx 和 5xx)都遵循同一格式。最重要的字段是 requestId,它在 Pix Processamento 内部日志中唯一标识该次调用。

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Não foi possível processar esta solicitação",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

字段	用途
`statusCode`	响应的 HTTP 状态码(与 status 一致)。
`error`	错误简称(`Unauthorized`、`Bad Request`、`Internal Server Error`)。
`message`	葡萄牙语描述错误内容。用于日志记录,而非展示给最终用户。
`requestId`	Pix Processamento 中该次调用的唯一 ID。开支持工单时附上此 ID,他们可以直接追溯。

请始终在错误日志中记录 requestId。当您以"生产环境出错"开支持工单时,团队首先要的就是这个 ID。有 requestId 几分钟即可定位问题;没有则可能要花几个小时。

try {
  const res = await fetch(url, { headers, body });
  if (!res.ok) {
    const err = await res.json();
    log.error('Pix Processamento 错误', {
      requestId: err.requestId,
      statusCode: err.statusCode,
      message: err.message,
      endpoint: url,
    });
    throw new Error(`Pix Processamento ${err.statusCode}: ${err.message} (requestId=${err.requestId})`);
  }
} catch (e) {
  // ...
}

通过 requestId 开启支持

提交工单知识库支持门户

错误排查

401 Unauthorized

最常见的原因,按顺序排列:

Token 缺失,未发送 Authorization header。
Token 错误,拼写错误、多余空格、编码错误。
Token 已吊销,已轮换但您仍在使用旧 token。
权限不足,该 token 不具备此 endpoint 所需的作用域。

响应示例:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmou00000abcdef01s6ghij1k2lm"
}

403 Forbidden

Token 有效,但无权执行该操作。请检查 endpoint 是否需要额外作用域,或您的账户是否已开通该功能(例如内部转账可能需要预先审批)。

轮换

如果 token 泄露,请立即联系 Pix Processamento 支持,以便签发新 token 并吊销旧 token。

提现与转账的 IP 白名单

为资金流出账户的操作提供额外一层保护。白名单启用后,POST /v1/withdraw、POST /v1/withdraw/qrcode 和 POST /v1/internal-transfer 仅接受来自已登记 IP 的调用。其他任何 IP 都会收到 403,errorCode 为 PZA203,即使 token 有效。这些路由的 GET 查询也经过同样的校验。

如何管理

在 Web 面板中自助管理,位于安全菜单的 IP 白名单 部分。每次添加或删除都需要 step-up 确认(操作密码),所有变更均记录审计。

限制:

每个账户最多 20 个生效 IP。
每 5 分钟最多 5 次添加。

被锁定禁止变更的账户在尝试添加或删除 IP 时会收到 403,errorCode 为 PZA204。此时请联系支持团队。

最佳实践

登记基础设施的 固定出口 IP(NAT/egress)。本地机器的动态 IP 会在第一次变化时失效。
迁移基础设施时,先添加新 IP,再删除旧 IP,这样过渡期间提现不会中断。
在代码中将 PZA203 视为配置错误而非业务错误:应通知基础设施团队,而不是重试。

本页内容