Desenvolvedores frequentemente buscam maneiras eficientes de integrar serviços financeiros em suas aplicações, e a API Brex se destaca como uma solução robusta para gerenciar limites de gastos, transações e recursos da equipe. Este artigo o guiará pelo processo de acesso e uso da API Brex. Você aprenderá a configurar a autenticação, explorar endpoints e incorporar a API em seus sistemas.
Ao prosseguir, lembre-se de que pequenos ajustes em sua abordagem, como a escolha dos escopos corretos durante a geração do token, podem impactar significativamente o sucesso da integração. Portanto, preste muita atenção a cada etapa para garantir uma conectividade perfeita.
O Que É a API Brex?
A API Brex oferece uma interface RESTful que permite aos desenvolvedores automatizar e personalizar fluxos de trabalho financeiros dentro da plataforma Brex. A Brex, uma empresa de tecnologia financeira, oferece serviços como cartões corporativos, gerenciamento de gastos e acompanhamento de despesas. Consequentemente, a API Brex permite interagir com esses recursos de forma programática.
A API Brex inclui várias APIs especializadas, como a API de Equipe (Team API) para gerenciar usuários e cartões, a API de Transações (Transactions API) para buscar transações liquidadas e a API de Onboarding para gerenciar indicações (referrals). Cada uma delas atende a diferentes aspectos da gestão financeira, permitindo que você crie relatórios personalizados, automatize convites de usuários ou rastreie despesas em tempo real.
Além disso, a Brex enfatiza a segurança e a conformidade, garantindo que as interações da API estejam alinhadas com os padrões da indústria. Portanto, ao usar a API Brex, você tem acesso a ferramentas que suportam operações financeiras escaláveis sem comprometer a integridade dos dados.
Por Que Você Deve Usar a API Brex?
Você deve usar a API Brex se sua aplicação requer integração com ferramentas financeiras corporativas. Por exemplo, equipes financeiras frequentemente precisam sincronizar dados de transações com softwares de contabilidade, e a API Brex facilita isso ao fornecer endpoints para listar transações e contas.
Além disso, a API reduz o esforço manual no gerenciamento de limites de gastos e acesso de usuários. Você pode automatizar a criação de cartões, definir limites mensais e monitorar atividades, o que otimiza as operações para empresas em crescimento. Adicionalmente, parceiros em contabilidade ou RH podem aproveitar a API de Onboarding para criar links de indicação personalizados, aprimorando os processos de aquisição de clientes.
No entanto, o verdadeiro valor reside em sua flexibilidade. Você integra a API Brex com sistemas existentes para criar painéis ou alertas personalizados, garantindo que os dados financeiros fluam eficientemente entre as plataformas. Como resultado, os desenvolvedores economizam tempo e reduzem erros em comparação com a entrada manual de dados.
Como Começar com o Acesso à API Brex?
Para começar com o acesso à API Brex, primeiro você se cadastra em uma conta Brex, caso ainda não tenha uma. Visite brex.com e crie uma conta como administrador, pois somente administradores de conta ou administradores de cartão podem gerar tokens de API.
Em seguida, faça login no painel da Brex.
Navegue até a seção Desenvolvedor em Configurações. Aqui, você clica em Criar Token para iniciar o processo. Você fornece um nome para o token, o que ajuda a identificar seu propósito mais tarde, como "Token de Integração para App".
Além disso, você seleciona os escopos apropriados durante esta etapa. Os escopos definem os níveis de acesso aos dados, como acesso de leitura a transações ou permissões de escrita para gerenciamento de usuários. Após confirmar suas seleções, você clica em Permitir Acesso, e o sistema gera o token.
É importante que você copie e armazene este token de forma segura imediatamente, pois a Brex o ofusca após a criação por motivos de segurança. Se você o perder, basta criar um novo. Os tokens expiram após 90 dias de inatividade, então monitore o uso para evitar interrupções.
Assim que tiver o token, você testa a conectividade básica. Por exemplo, você usa uma ferramenta como o curl para fazer uma solicitação GET simples a um endpoint, incluindo o token no cabeçalho Authorization. Isso verifica se sua configuração está funcionando corretamente.
Como Autenticar com a API Brex?
Você autentica com a API Brex usando tokens de portador (bearer tokens). Especificamente, você inclui o token no cabeçalho Authorization de cada requisição, formatado como "Bearer {seu_token}".
Por exemplo, considere este exemplo de curl:
curl -X GET https://platform.brexapis.com/v2/users/me \
-H "Authorization: Bearer bxt_jBWQLZXtu1f4sVT6UjaWPp7Gh9nVGjzEZgRX"
Esta requisição busca os detalhes do usuário atual. Se bem-sucedida, retorna dados JSON sobre o usuário.
Além disso, a Brex suporta tokens de usuário, que estão vinculados a privilégios administrativos específicos. Você gera esses tokens conforme descrito anteriormente, garantindo que escolha escopos que correspondam às suas necessidades. Por exemplo, se você planeja gerenciar cartões, selecione escopos para leitura e escrita em endpoints de cartão.
No entanto, se um token for comprometido, revogue-o imediatamente na página de Desenvolvedor no painel. Tokens revogados farão com que as chamadas de API subsequentes falhem com um erro 401, protegendo sua conta.
Na prática, você implementa o gerenciamento de tokens no código da sua aplicação. Bibliotecas como o módulo requests do Python simplificam isso:
import requests
headers = {
'Authorization': 'Bearer your_token_here'
}
response = requests.get('https://platform.brexapis.com/v2/users/me', headers=headers)
print(response.json())
Este trecho de código demonstra a autenticação ativa em um script.
Quais São os Principais Endpoints da API Brex?
A API Brex oferece vários endpoints em diversas APIs. Você começa explorando a API de Equipe (Team API), que gerencia usuários, departamentos, localizações, cartões e muito mais.
- Para usuários, você lista todos os usuários com GET /v2/users, filtrando por e-mail ou ID. Os parâmetros incluem cursor para paginação e limit para controlar o tamanho da resposta. Similarmente, você convida um novo usuário via POST /v2/users, fornecendo first_name, last_name, email e o manager_id opcional.
Além disso, você atualiza usuários com PUT /v2/users/{id}, alterando o status para ACTIVE ou DISABLED. Você também define limites mensais usando POST /v2/users/{id}/limit, especificando o valor no corpo da requisição.
- Para departamentos, você cria um com POST /v2/departments, exigindo um nome. Você os lista via GET /v2/departments e recupera detalhes específicos com GET /v2/departments/{id}.
- Localizações seguem um padrão similar: POST /v2/locations para criação, GET /v2/locations para listagem.
- Cargos (Titles), que representam funções de trabalho, usam endpoints como POST /v2/titles e GET /v2/titles/{id}.
- Cartões formam uma parte central. Você lista cartões com GET /v2/cards, filtrados por user_id. Para criar um cartão, POST /v2/cards com detalhes como owner, card_type (VIRTUAL ou PHYSICAL) e spend_controls. Spend_controls incluem limit_type e amounts.
Além disso, você atualiza cartões via PUT /v2/cards/{id}, os bloqueia com POST /v2/cards/{id}/lock (fornecendo um motivo como FRAUD), ou os encerra com POST /v2/cards/{id}/terminate.
- Operações sensíveis incluem GET /v2/cards/{id}/pan para números de cartão e POST /v2/cards/{id}/secure_email para enviar detalhes de forma segura.
- Entidades legais e empresas têm endpoints somente leitura como GET /v2/legal_entities e GET /v2/company.
- Mudando para a API de Transações, você busca transações de cartão liquidadas com GET /v2/transactions/card/primary, usando parâmetros como posted_at_start para filtragem de data. Para contas em dinheiro, GET /v2/transactions/cash/{id} lista as transações.
- Os endpoints de conta incluem GET /v2/accounts/card para contas de cartão e GET /v2/accounts/cash para contas em dinheiro. Você recupera extratos com GET /v2/accounts/card/primary/statements.
- A API de Onboarding foca em indicações (referrals). Você cria indicações com POST /v1/referrals, fornecendo referral_code e detalhes do solicitante. Liste-os via GET /v1/referrals e obtenha detalhes específicos com GET /v1/referrals/{id}. Uploads de documentos usam POST /v1/referrals/{id}/document_upload.
Outras APIs incluem Payments para transferências (GET /v2/transfers), Webhooks para notificações e Fields API para gerenciar campos personalizados.
Todos os endpoints de listagem suportam paginação com cursor e limit, garantindo uma recuperação de dados eficiente.
Como Usar a API Brex para Transações?
Você usa a API Brex para transações chamando endpoints na API de Transações. Primeiro, você identifica o tipo de conta — cartão ou dinheiro.
Para transações com cartão, você envia GET /v2/transactions/card/primary. Isso retorna compras liquidadas, reembolsos e estornos. Você filtra por user_ids ou posted_at_start, como "2025-01-01T00:00:00Z".
A resposta inclui detalhes como amount (valor), description (descrição), merchant (comerciante) e expense_id (ID da despesa), se expandidos.
Para transações em dinheiro, você especifica o ID da conta em GET /v2/transactions/cash/{id}. Isso lista todas as atividades para aquela conta em dinheiro.
Para gerenciar contas, você lista contas de cartão com GET /v2/accounts/card, que retorna IDs e status. Similarmente, GET /v2/accounts/cash fornece detalhes de contas em dinheiro.
Além disso, você busca extratos para auditoria. Use GET /v2/accounts/card/primary/statements para obter extratos de cartão finalizados, paginados conforme necessário.
Em código, você implementa isso da seguinte forma (exemplo em Python):
import requests
headers = {
'Authorization': 'Bearer your_token_here'
}
params = {
'posted_at_start': '2025-12-01T00:00:00Z',
'limit': 50
}
response = requests.get('https://platform.brexapis.com/v2/transactions/card/primary', headers=headers, params=params)
transactions = response.json()['items']
for tx in transactions:
print(f"Amount: {tx['amount']['amount']}, Description: {tx['description']}")
Este script busca e imprime transações recentes, demonstrando o uso prático.
Adicionalmente, você lida com erros como 404 para IDs inválidos verificando response.status_code.
Como Gerenciar Equipes com a API de Equipe Brex?
Você gerencia equipes usando os endpoints da API de Equipe. Comece listando usuários com GET /v2/users. Isso o ajuda a auditar os membros atuais da equipe.
Para adicionar um usuário, POST /v2/users com os campos obrigatórios:
{
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"department_id": "dept_123"
}
O sistema envia um e-mail de convite automaticamente.
Você atualiza os detalhes do usuário, como atribuir um novo gerente, via PUT /v2/users/{id}.
Para controle de gastos, POST /v2/users/{id}/limit define orçamentos mensais.
Departamentos e localizações aprimoram a organização. Você cria um departamento com POST /v2/departments:
{
"name": "Engineering",
"description": "Software development team"
}
Em seguida, atribua usuários a ele durante o convite ou atualização.
Cartões estão vinculados a usuários. Você cria um cartão virtual para um usuário:
{
"owner": {
"user_id": "user_456"
},
"card_name": "Project Card",
"card_type": "VIRTUAL",
"limit_type": "CARD",
"spend_controls": {
"limit": {
"amount": 5000,
"currency": "USD"
}
}
}
POST isso para /v2/cards.
Mais tarde, você bloqueia um cartão se necessário: POST /v2/cards/{id}/lock com o motivo "OTHER".
Essa abordagem garante o gerenciamento seguro da equipe.
Integrando a API Brex com Sua Aplicação: Exemplos de Código
Você integra a API Brex incorporando chamadas de API em sua base de código. Use bibliotecas como requests em Python ou axios em JavaScript.
Para um exemplo em Node.js, instale o axios:
npm install axios
Então, busque usuários:
const axios = require('axios');
const headers = {
Authorization: 'Bearer your_token_here'
};
axios.get('https://platform.brexapis.com/v2/users', { headers })
.then(response => {
console.log(response.data.items);
})
.catch(error => {
console.error(error.response.data);
});
Isso registra os dados do usuário.
Para integrações mais complexas, você usa webhooks. Assine eventos via API de Webhooks, configurando endpoints para receber notificações sobre atualizações de transações.
Em Python, lide com a paginação para grandes conjuntos de dados:
def fetch_all_users(headers, cursor=None):
users = []
while True:
params = {'limit': 100, 'cursor': cursor}
response = requests.get('https://platform.brexapis.com/v2/users', headers=headers, params=params)
data = response.json()
users.extend(data['items'])
cursor = data['next_cursor']
if not cursor:
break
return users
Esta função recupera todos os usuários iterativamente.
Você também protege dados sensíveis, como números de cartão, usando GET /v2/cards/{id}/pan apenas quando necessário e não armazenando nada localmente.
Como Você Pode Testar a API Brex com Apidog?
Você testa a API Brex de forma eficaz usando o Apidog, uma plataforma tudo-em-um para desenvolvimento de API. O Apidog permite projetar, depurar, simular (mock), testar e documentar APIs de forma intuitiva.
Em seguida, configure a autenticação adicionando seu token de portador (bearer token) nas variáveis globais ou nas configurações de ambiente. Isso se aplica a todas as requisições.
Você então envia requisições, como GET /v2/users/me, e visualiza as respostas em uma interface amigável. O Apidog destaca estruturas JSON e erros.
Além disso, você cria cenários de teste com asserções. Por exemplo, assegure que uma resposta de transação tenha status 200 e contenha 'amount'.
O recurso de simulação (mocking) do Apidog simula respostas para endpoints indisponíveis, auxiliando no desenvolvimento.
Adicionalmente, gere documentação com exemplos de código em várias linguagens, compartilhando-a com sua equipe.
Ao usar o Apidog, você otimiza os testes da API Brex, identificando problemas precocemente.
Quais São as Melhores Práticas para Usar a API Brex?
Você segue as melhores práticas para otimizar o uso da API Brex. Sempre use HTTPS e armazene tokens de forma segura, talvez em variáveis de ambiente ou cofres.
Implemente o tratamento de limite de taxa (rate limiting), pois a Brex impõe limites — tente novamente com recuo exponencial em erros 429.
- Paginar requisições para evitar timeouts; use cursor e limit de forma consistente.
- Monitore a expiração do token e automatize a renovação.
- Valide as entradas antes de enviar para evitar erros 400.
- Registre as chamadas de API para depuração, mas anonimize dados sensíveis.
- Use chaves de idempotência para POST/PUT para evitar duplicatas.
- Integre o tratamento de erros: Mapeie códigos HTTP para ações, como atualizar tokens em 401.
- Teste em ambientes de staging antes da produção.
- Mantenha-se atualizado com o changelog da Brex para quaisquer alterações.
Essas práticas garantem integrações confiáveis.
Problemas Comuns e Como Solucionar Problemas da API Brex?
Você pode encontrar problemas como falhas de autenticação. Se receber 401, verifique a validade do token — regenere se estiver expirado.
- Para 403 Forbidden, verifique se os escopos correspondem ao endpoint.
- 404 Not Found geralmente significa IDs inválidos; verifique novamente os caminhos.
- Limite de taxa excedido resulta em 429; implemente recuo (backoff).
- Erros de rede requerem lógica de nova tentativa.
Use as coleções Postman da Brex para testes iniciais, fazendo um "fork" de seu workspace.
Se os problemas persistirem, consulte a documentação ou entre em contato com o suporte.
Conclusão
Agora você entende como acessar e usar a API Brex de forma abrangente. Da autenticação ao uso de endpoints e testes com o Apidog, essas etapas permitem integrações robustas. Aplique-as para aprimorar seus fluxos de trabalho financeiros de forma eficiente.
