认证

您机器的凭证是 client_id 和 client_secret 这一对。用这两者换取 OAuth2 令牌（client_credentials），并在每次调用 /v2/ 时通过 Authorization: Bearer 发送该令牌。令牌有效期为 900 秒。

API 只接受来自您凭证中登记的服务器 IP 的调用。您可以在控制台生成 client_secret 并填写出口 IP，见控制台中的密钥与 IP。

令牌 #

POST /oauth/token

client_id 和 client_secret 通过 HTTP Basic 发送，也就是 curl -u 的做法：

curl -u "loja01:SEU_CLIENT_SECRET" -d "grant_type=client_credentials" -d "scope=cob.write cob.read pix.read ex.saldo.read ex.config.read" https://api.amunpay.com/oauth/token

POST /oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=cob.write cob.read pix.read ex.saldo.read ex.config.read
→ 200
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjAxSjEifQ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "cob.write cob.read pix.read ex.saldo.read ex.config.read"
}

除 Basic 之外，client_id 和 client_secret 也可以放在表单正文中。两种方式同时发送且取值不同时，返回 400 invalid_request。

令牌只对来自已登记 IP 的调用签发和生效：来自其他 IP 时，令牌请求和每次调用都返回 403 origem_nao_permitida。未登记任何 IP 时，任何调用都无法通过。

控制台中的密钥与 IP #

贵公司的管理员在控制台的 Integração（集成）菜单、Credenciais（凭证）标签页中，凭双因素验证码生成 client_secret。密钥只显示一次，与 client_id 并列，各带一个复制按钮，之后不再显示。丢失后请重新生成：旧密钥立即失效。已签发的令牌在过期前仍然有效，除非您标记了疑似泄露，此时这些令牌也会一并失效。

控制台接受公网 IP，网段最大为 /24（IPv4）或 /48（IPv6），最多 20 个 IP。对凭证的每项操作都会通过邮件通知贵公司的联系人，邮件中不含密钥。未登记技术联系人或财务联系人时，控制台既不能生成凭证，也不能添加 IP。

只有管理员可以生成凭证和修改 IP。其他用户可以查看 client_id 和 IP。如果 AmunPay 为您的账户开启了双因素等待期，刚启用双因素验证、刚被提升权限、刚被重新启用，或密码刚由他人重置的管理员，需要等待 24 小时才能生成。拥有独立凭证的子账户，其凭证由所属的主体公司生成。

如果页面提示该功能未对您的账户开放，请联系 AmunPay。AmunPay 也可以为您生成密钥并登记 IP，由 AmunPay 添加的新 IP 立即生效。

第一次调用 #

GET /v2/ex/config

GET /v2/ex/config
→ 200
{
  "conta": { "status": "ATIVA", "desde": "2026-09-18T09:20:23Z" },
  "capacidades": {
    "pix": true,
    "subcontas": true,
    "split": true,
    "baas": false
  },
  "recebedor": { "chave": "01J8Z3QK5W7R2N4M6P8T0V2X4Y" },
  "custodia": { "tipo": "PROPRIA", "custodiante": "Conta PI", "recusaAntesDoCredito": true },
  "depositoPorChave": { "modo": "RECUSAR" }
}

权限范围 #

令牌错误 #

POST /oauth/token 以 { "error", "error_description" } 格式响应。

调用错误 #