Skip to main content

Getting Started

Bem-vindo à Banking API! Este guia irá ajudá-lo a dar os primeiros passos e fazer sua primeira chamada à API.

Pré-requisitos​

Antes de começar, você precisa:

  • Credenciais de acesso (Client ID e Client Secret) fornecidas pela equipe
  • Acesso ao ambiente (Development, Staging ou Production)
  • Ferramenta para fazer requisições HTTP (cURL, Postman, ou seu cliente HTTP preferido)

Objetivo deste Guia​

Ao final deste guia, você será capaz de:

  1. Obter um token de autenticação
  2. Fazer sua primeira requisição à API
  3. Entender a estrutura básica das respostas

Passo 1: Obter Credenciais​

Se você ainda não possui credenciais, entre em contato com nossa equipe através de [email protected].

Você receberá:

  • Client ID: Identificador único do seu cliente
  • Client Secret: Chave secreta para autenticação
  • Base URL: URL do ambiente (ex: https://api.bancodigital.com)

Passo 2: Autenticar e Obter Token​

A Banking API usa OAuth2 com Client Credentials. Para obter um token:

curl -X POST https://api.bancodigital.com/public/gw_banking/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=seu-client-id" \
  -d "client_secret=seu-client-secret"

Resposta de sucesso:

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

Dica: Guarde o access_token. Você precisará dele para todas as requisições subsequentes.

Passo 3: Fazer sua Primeira Requisição​

Agora que você tem um token, vamos consultar o saldo de uma conta. Este é um exemplo prático que você pode usar imediatamente.

Endpoint: Consultar Saldo​

curl -X GET "https://api.bancodigital.com/public/gw_banking/v1/accounts/123/balance" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Resposta de sucesso:

{
  "accountId": "123",
  "balance": {
    "available": 1500.5,
    "current": 2000.0,
    "blocked": 500.5
  },
  "currency": "BRL",
  "lastUpdated": "2025-11-19T10:30:00Z"
}

Entendendo a Resposta​

  • accountId: Identificador da conta consultada
  • balance.available: Saldo disponível para transações
  • balance.current: Saldo total atual da conta
  • balance.blocked: Valor bloqueado (retenções, garantias, etc)
  • currency: Moeda (BRL = Real Brasileiro)
  • lastUpdated: Timestamp da última atualização

Fórmula do Saldo​

available = current - blocked

No exemplo acima: 1500.50 = 2000.00 - 500.50

Exemplo Completo em Node.js​

import axios from 'axios';

const API_BASE_URL = 'https://api.bancodigital.com';
const CLIENT_ID = 'seu-client-id';
const CLIENT_SECRET = 'seu-client-secret';

// 1. Obter token
async function getToken() {
  const response = await axios.post(
    `${API_BASE_URL}/public/gw_banking/v1/auth/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;
}

// 2. Consultar saldo
async function getBalance(token: string, accountId: string) {
  const response = await axios.get(
    `${API_BASE_URL}/public/gw_banking/v1/accounts/${accountId}/balance`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
  return response.data;
}

// Uso
(async () => {
  try {
    const token = await getToken();
    const balance = await getBalance(token, '123');
    console.log('Saldo da conta:', balance);
  } catch (error) {
    console.error('Erro:', error.response?.data || error.message);
  }
})();

Próximos Passos​

Agora que você já sabe o básico, explore:

  1. Autenticação & mTLS - Aprenda mais sobre autenticação e mTLS
  2. Balance Flow - Entenda o fluxo completo de consulta de saldo
  3. Errors & Retries - Como tratar erros e implementar retry

Dicas Importantes​

Tokens Expiraram?​

Tokens expiram após 1 hora (3600 segundos). Quando isso acontecer, você receberá um erro 401 Unauthorized. Simplesmente obtenha um novo token seguindo o Passo 2.

Correlation ID​

Todas as requisições retornam um x-correlation-id no header. Use este ID ao reportar problemas ou debugar requisições.

Rate Limits​

  • 1000 requisições por minuto por cliente
  • 10000 requisições por hora por cliente

Se você exceder esses limites, receberá um erro 429 Too Many Requests.

Problemas?​

Se você encontrou algum problema:

  1. Verifique se suas credenciais estão corretas
  2. Confirme que está usando a URL correta do ambiente
  3. Verifique se o token não expirou
  4. Consulte o guia de Errors & Retries
  5. Entre em contato: [email protected]