Autenticación

La credencial de su máquina es el par client_id y client_secret. Intercambie los dos por un token OAuth2 (client_credentials) y envíe el token en Authorization: Bearer en toda llamada a /v2/. El token vale 900 segundos.

La API solo acepta llamadas desde las IP de su servidor registradas en su credencial. Usted genera el client_secret e informa las IP de salida en el panel, en El secreto y las IP en el panel.

Token #

POST /oauth/token

El client_id y el client_secret van en HTTP Basic. Es lo que hace 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"
}

Como alternativa al Basic, client_id y client_secret pueden ir en el cuerpo del formulario. Enviar los dos de ambas formas con valores diferentes responde 400 invalid_request.

El token solo se emite y solo vale para llamadas que vienen de las IP registradas: desde otra IP, la solicitud del token y cada llamada responden 403 origem_nao_permitida. Sin ninguna IP registrada, ninguna llamada pasa.

El secreto y las IP en el panel #

El gestor de su empresa genera el client_secret en el panel, en Integração, en la pestaña Credenciais, con el código del segundo factor. El secreto aparece una sola vez, junto al client_id, cada uno con el botón de copiar, y nunca se vuelve a mostrar. Si lo pierde, genere otro: el anterior deja de valer en el acto. Los tokens ya emitidos valen hasta expirar, salvo cuando usted marca sospecha de filtración, que también los invalida.

El panel acepta IP pública, con prefijo de hasta /24 (IPv4) o /48 (IPv6), hasta 20 IP. Todo acto sobre la credencial va por correo electrónico a los contactos de su empresa, sin el secreto. Sin contacto técnico ni financiero registrado, el panel no genera ni incluye IP.

Solo el gestor genera y cambia las IP. Los demás usuarios ven el client_id y las IP. Si AmunPay activa la espera del segundo factor para su cuenta, el gestor que acaba de activar el segundo factor, que fue promovido, reactivado o al que otra persona le restableció la contraseña espera 24 horas para generar. La credencial de una subcuenta con credencial propia la genera la empresa titular.

Si la pantalla dice que la funcionalidad no está habilitada para su cuenta, hable con AmunPay. AmunPay también genera el secreto y registra las IP por usted, y por AmunPay la IP nueva vale en el acto.

Primera llamada #

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" }
}

Alcances #

Errores del token #

El POST /oauth/token responde en el formato { "error", "error_description" }.

Errores en las llamadas #