Guia de Autenticação

Este guia explica passo a passo como obter um token de acesso para utilizar a API PIX da CorpX.

Visão Geral

A API CorpX utiliza OAuth 2.0 com o fluxo Client Credentials para autenticação. Você precisará das suas credenciais (client_id e client_secret) para obter um token de acesso válido.

Pré-requisitos

Antes de começar, certifique-se de que você possui:

• Client ID - Seu identificador único de cliente
• Client Secret - Chave secreta para autenticação
• X-Tenant-Id - Seu identificador de tenant (ex.: tenant-suaempresa)

Ambientes

Passo 1: Solicitar um Token de Acesso

Request

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"

Parâmetros

Resposta de Sucesso (200 OK)

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

Resposta de Erro (401 Unauthorized)

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

Passo 2: Usar o Token nas Requisições

Com o token obtido, inclua-o no header Authorization de todas as requisições à API.

Exemplo: Consultar Saldo

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"

Headers Obrigatórios

Passo 3: Renovar o Token

O token expira após o tempo indicado em expires_in (5 minutos nas credenciais atuais). É obrigatório reutilizar o mesmo token até perto desse prazo:

1. Armazene o token em cache com o expires_in que veio na resposta
2. Renove antes de expirar — com TTL de 5 minutos, renovar no último minuto já é apertado
3. Trate o 403 de token expirado — a API responde 403 Forbidden, não 401; ao recebê-lo, obtenha um novo token e repita a chamada

Exemplo de Renovação Automática (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"

Exemplos Completos em Diferentes Linguagens

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';
let cached = { token: null, expiresAt: 0 };
async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt) {
    return cached.token;
  }
  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' } }
  );
  cached = {
    token: response.data.access_token,
    expiresAt: Date.now() + (response.data.expires_in - 60) * 1000
  };
  return cached.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;
}

Escopos de credencial

Cada credencial (client_id/client_secret) carrega um conjunto de escopos que define exatamente o que ela pode fazer. Você escolhe os escopos ao criar a credencial no painel do backoffice (seção API Credentials, disponível para usuários com perfil tenant manager).

Escopos que você mesmo concede:

kyc.read é o único escopo de consulta que não é coberto por read: como ele entrega rosto de cliente, precisa ser concedido explicitamente. A rota também exige a feature kyc_artifacts habilitada no tenant — veja Arquivos comprobatórios.

Cada escopo já consulta o próprio domínio. É o que permite uma credencial de recebimento que emite QR code e vê se ele foi pago sem ter acesso ao saldo e ao extrato: basta conceder qrcode.manage sozinho. Marque read apenas quando a credencial precisar realmente das consultas amplas da conta.

Escopos que movimentam dinheiro são emitidos pela CorpX, nunca pelo painel:

Se você pedir um desses escopos pelo painel, a criação é recusada com 403 scope_not_self_service — fale com o suporte para emitirmos a credencial.

Credenciais delegadas

O escopo credentials.delegate é CorpX-only: a master do internet banking emite filhas amarradas a uma conta. Se você recebeu essa filha (feature API do IB), esta seção BaaS não é o seu guia — vá para Internet banking.

Restrição por conta

Uma credencial pode ficar restrita a contas específicas do seu tenant. É o caminho para, por exemplo, dar a um subsistema uma credencial que só emite QR code de uma conta. Chamadas a contas fora do conjunto respondem 403 forbidden — o erro genérico de permissão, sem insufficient_scope: o escopo está lá, a conta é que não. A mensagem não distingue conta inexistente de conta fora do conjunto, de propósito.

Combinando as duas dimensões: qrcode.manage + uma única conta resulta numa credencial que cobra por QR code naquela conta e não enxerga mais nada — nem o saldo dela, nem as outras contas do tenant.

Quando falta escopo

Se a credencial não tem o escopo da rota, a API responde 403 Forbidden nomeando o que falta:

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

Credenciais emitidas antes dos escopos granulares continuam funcionando sem alteração: elas mantêm o par grosso (api2/read api2/write) e acesso total.

Acesso suspenso por pendência

Quando existe uma pendência em aberto com a CorpX, o acesso do tenant pode ser suspenso temporariamente. A suspensão não invalida sua credencial: o mesmo client_id/client_secret continua obtendo token normalmente, e a recusa vem na chamada à API.

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

Dois pontos importantes:

• O dinheiro não para. PIX recebido continua sendo creditado, e você continua recebendo os webhooks desses eventos. O que a suspensão bloqueia é iniciar novas operações.
• Reativar é imediato. Assim que a pendência é regularizada, o acesso volta na chamada seguinte — não é preciso gerar credencial nova nem novo token.

O motivo da pendência não vem no corpo do erro: ele aparece no painel do backoffice, para os operadores do seu time.

Erros Comuns

Boas Práticas

1. Reutilize o token — um token por chamada é proibido
2. Nunca exponha o client_secret em código client-side (frontend)
3. Use variáveis de ambiente para armazenar credenciais
4. Monitore a expiração e renove tokens de forma proativa
5. Use HTTPS para todas as comunicações

Próximos Passos

Agora que você sabe como autenticar, explore os outros guias:

• Guia de QR Code Dinâmico - Gerar cobranças PIX
• Guia de Cash Out - Fazer transferências PIX
• Guia de Devolução - Solicitar estornos