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)

informação

Se você ainda não possui credenciais, entre em contato com nossa equipe de suporte.

Ambientes

Ambiente	URL de Autenticação	URL da API	Observações
Sandbox (dev)	—	—	Temporariamente desativado.
Produção	https://auth.corpxapi.com/oauth2/token	https://api.corpxapi.com

Passo 1: Solicitar um Token de Acesso

Request

curl -X POST "https://auth.corpxapi.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

Parâmetro	Tipo	Obrigatório	Descrição
grant_type	string	Sim	Sempre client_credentials
client_id	string	Sim	Seu identificador de cliente
client_secret	string	Sim	Sua chave secreta

Resposta de Sucesso (200 OK)

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

Campo	Descrição
access_token	Token JWT para autenticação nas chamadas à API
expires_in	Tempo de validade em segundos (geralmente 3600 = 1 hora)
token_type	Tipo do token (sempre 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://api.corpxapi.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer eyJraWQiOiJ0emwzZWVYWGx1eVlDWHFwQXdBTzJWYWJNQ0llMFMyMXVRWGV2Y281N2RRPSIsImFsZyI6IlJTMjU2In0..." \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json"

Headers Obrigatórios

Header	Descrição
Authorization	Token de acesso no formato Bearer {access_token}
X-Tenant-Id	Seu identificador de tenant
Content-Type	application/json para requisições com body

Passo 3: Renovar o Token

O token expira após o tempo indicado em expires_in. Recomendamos:

1. Armazene o token em cache com seu tempo de expiração
2. Renove antes de expirar - solicite um novo token alguns minutos antes
3. Trate erros 401 - se receber 401 Unauthorized, obtenha um novo token

Exemplo de Renovação Automática (Bash)

#!/bin/bash

# Variables
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH_URL="https://auth.corpxapi.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://api.corpxapi.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.corpxapi.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://api.corpxapi.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.corpxapi.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://api.corpxapi.com/v1/accounts/${accountId}/balance`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Tenant-Id': TENANT_ID,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

Erros Comuns

Erro	Causa	Solução
invalid_client	Client ID ou Secret incorretos	Verifique suas credenciais
invalid_grant	Tipo de grant inválido	Use client_credentials
401 Unauthorized	Token expirado ou inválido	Obtenha um novo token
403 Forbidden	Token válido mas sem permissão	Verifique o X-Tenant-Id

Boas Práticas

1. Nunca exponha o client_secret em código client-side (frontend)
2. Use variáveis de ambiente para armazenar credenciais
3. Implemente cache de token para evitar requisições desnecessárias
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