DEV Community

Cover image for Como Usar a API Plaid: Guia do Desenvolvedor 2026
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar a API Plaid: Guia do Desenvolvedor 2026

Aplicativos fintech dificilmente começam do zero atualmente. Quando seu usuário conecta uma conta corrente ao seu app, é provável que o Plaid esteja envolvido, traduzindo logins bancários em JSON estruturado que seu backend pode consumir. A API do Plaid é responsável pela vinculação de contas, verificação de saldo, resgate de histórico de transações e validação de identidade em milhares de apps como Venmo, Robinhood e Chime.

Experimente o Apidog hoje

Este guia é prático para quem vai integrar o Plaid: como obter chaves, entender o fluxo do token Link ponta a ponta, conhecer os principais produtos e interpretar erros comuns em produção. Mostra também como testar cada etapa com o Apidog, reduzindo o retrabalho com payloads. Para detalhes oficiais, mantenha a documentação do Plaid aberta.

Open banking é um setor competitivo, e o Plaid é apenas uma das opções. Se você ainda avalia fornecedores, confira nossa análise das melhores APIs de open banking. Este artigo assume que você já escolheu o Plaid e está pronto para implementar.

TL;DR

  • Plaid conecta seu app a 12.000+ bancos nos EUA, Canadá e Europa.
  • Três ambientes: Sandbox (gratuito, dados fake), Development (100 Itens reais gratuitos) e Production (cobrança por uso).
  • Fluxo de vinculação em 4 passos: crie link_token no backend, abra Link no frontend, troque public_token por access_token, consuma os endpoints.
  • Principais produtos: Auth, Balance, Transactions, Identity, Investments, Liabilities, Income. Ative-os por Item.
  • Erros clássicos: ITEM_LOGIN_REQUIRED, INVALID_CREDENTIALS. Webhooks avisam quando algo exige atenção.
  • Limites de taxa por Item e cliente. Prefira webhooks ao polling frequente.

O que é Plaid?

Plaid é infraestrutura fintech intermediando seu app e o banco do usuário. O usuário insere suas credenciais no Plaid Link, que conecta ao banco (via API oficial ou scraping, conforme a instituição), normaliza os dados e retorna uma resposta JSON padronizada.

Seu app nunca armazena as credenciais do usuário. O Plaid mantém a sessão (chamada de Item) e fornece um access_token para consultas. Um Item representa um conjunto de credenciais em uma instituição, podendo incluir múltiplas contas (corrente, poupança, cartão, etc).

Plaid cobre contas correntes, poupança, cartões, empréstimos, investimentos e folha de pagamento. Não realiza transferências: para ACH, combine Plaid Auth com um processador de pagamentos. Veja o nosso artigo sobre as melhores APIs de pagamentos ACH.

Autenticação e configuração

Passo 1: Crie uma conta de desenvolvedor Plaid

Cadastre-se em plaid.com e valide seu e-mail. No painel, você terá acesso a três ambientes:

  • Sandbox: bancos e usuários fictícios. Use user_good / pass_good para login.
  • Development: bancos reais, até 100 Itens, grátis.
  • Production: ilimitado, cobrança por uso.

Passo 2: Obtenha suas chaves

No painel, vá em Team Settings > Keys e copie:

  • client_id: comum a todos ambientes
  • secret: um por ambiente (sandbox, dev, prod)

Guarde-os em variáveis de ambiente, nunca suba para o git.

Passo 3: Instale o SDK oficial

npm install plaid

Passo 4: Inicialize o cliente

import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';

const config = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});

const client = new PlaidApi(config);

Altere PlaidEnvironments.sandbox para .development ou .production conforme o ambiente.

Endpoints principais

O fluxo de integração Plaid segue quatro passos. Passos 1 e 3 são no backend, o passo 2 ocorre no frontend via Plaid Link.

Passo 1: Crie um link_token (backend)

const response = await client.linkTokenCreate({
  user: { client_user_id: 'user_123' },
  client_name: 'Seu Aplicativo',
  products: ['auth', 'transactions'],
  country_codes: ['US'],
  language: 'en',
});
const linkToken = response.data.link_token;

Ou via curl:

curl -X POST https://sandbox.plaid.com/link/token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "secret": "YOUR_SANDBOX_SECRET",
    "user": { "client_user_id": "user_123" },
    "client_name": "Seu Aplicativo",
    "products": ["auth", "transactions"],
    "country_codes": ["US"],
    "language": "en"
  }'

Passo 2: Abra o Plaid Link (frontend)

Envie o link_token ao frontend e passe ao SDK do Plaid Link. O usuário escolhe o banco, faz login e recebe um public_token no callback onSuccess.

Passo 3: Troque o public_token por access_token (backend)

const exchange = await client.itemPublicTokenExchange({
  public_token: publicToken,
});
const accessToken = exchange.data.access_token;
const itemId = exchange.data.item_id;

Armazene accessToken no backend, vinculado ao usuário. Ele é usado para todas as chamadas futuras.

Passo 4: Consuma os endpoints do produto

const accounts = await client.accountsGet({ access_token: accessToken });
const balance = await client.accountsBalanceGet({ access_token: accessToken });

Principais endpoints de produto

  • Auth: retorna números de conta e roteamento para ACH (/auth/get).
  • Balance: saldos em tempo real, sem cache (/accounts/balance/get).
  • Transactions: até 24 meses de transações (/transactions/sync).
  • Identity: nome, e-mail, telefone, endereço (/identity/get). Para uso KYC puro, compare com opções do nosso guia de APIs KYC.
  • Investments: participações e transações de investimentos (/investments/holdings/get).
  • Liabilities: detalhes de empréstimos estudantis, cartões e hipotecas (/liabilities/get).
  • Income: dados de folha de pagamento (/credit/payroll_income/get).

Testando a API do Plaid com Apidog

Testes ponta a ponta no Plaid podem ser complicados pois o Link exige um navegador. Mas você pode validar seus endpoints backend, ver erros e compartilhar requisições confiáveis usando o Apidog.

Importe a especificação OpenAPI do Plaid no Apidog e use endpoints já configurados com exemplos, tipos e autenticação. Crie variáveis de ambiente (client_id, secret, access_token) e alterne entre sandbox/produção facilmente. Use requisições encadeadas para executar linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet num só fluxo — valide o handshake completo sem abrir navegador.

O mock server do Apidog gera respostas para o frontend antes do backend estar preparado. Se migrando de outra ferramenta, siga nosso guia de testes de API sem Postman. Baixe o Apidog e aponte para a spec do Plaid para começar.

Erros comuns e limites de taxa

Os erros do Plaid trazem error_type, error_code e error_message. Em produção, trate especialmente estes:

  • INVALID_CREDENTIALS: senha errada no banco. Peça ao usuário para reautenticar via modo atualização do Link.
  • ITEM_LOGIN_REQUIRED: sessão inválida (troca de senha/MFA). Acione o Link para atualização. Webhook avisa quando isso ocorre.
  • RATE_LIMIT_EXCEEDED: limite de chamadas por Item/endpoint. Aguarde e tente novamente com jitter.
  • PRODUCT_NOT_READY: dados de transação ainda sendo sincronizados. Refaça a chamada após o webhook INITIAL_UPDATE.

Webhooks

Informe uma URL de webhook ao criar o link_token. O Plaid fará POST de eventos como SYNC_UPDATES_AVAILABLE (novas transações), ITEM: LOGIN_REQUIRED (reautenticação) e ITEM: ERROR (erro permanente). Sempre valide a assinatura JWT dos webhooks antes de processar.

Limites de taxa

Plaid limita requisições por Item e endpoint. Exemplo: /accounts/balance/get tem cerca de 5 req/minuto por Item em produção. Limites agregados também existem. Prática recomendada: use webhooks, cacheie saldos por alguns minutos e evite acessar Plaid diretamente via endpoints expostos ao usuário.

Preços do Plaid

O modelo de preços do Plaid é baseado em chamadas de API:

  • Sandbox: gratuito, ilimitado.
  • Development: gratuito até 100 Itens.
  • Production:
  • Auth: cerca de US$ 1,50 por conta vinculada (cobrado uma vez).
  • Balance: preço por chamada.
  • Transactions: mensal por Item (aprox. US$ 0,30).
  • Identity: por chamada.
  • Investments/Liabilities/Income: preços separados por Item.

O Plaid negocia preços para grandes volumes. Veja a página de produtos do Plaid para valores atualizados.

FAQ

  • Por quanto tempo dura um access_token? Indefinidamente, até revogação pelo usuário ou expiração da sessão pelo banco. Armazene criptografado, não expire do seu lado.
  • Posso usar o Plaid só para verificação de identidade? Pode usar o Plaid Identity, mas se o foco for KYC, avalie produtos dedicados. Veja nosso guia de Stripe Identity API.
  • O Plaid funciona fora dos EUA? Sim. Cobre EUA, Canadá, Reino Unido e grande parte da UE. O suporte depende do produto e do país — veja country_codes em /link/token/create.
  • E se o usuário trocar a senha do banco? O Item entra em ITEM_LOGIN_REQUIRED e você recebe um webhook. Acione o Link para atualização; o access_token permanece válido após nova autenticação.
  • Como testar o fluxo Link sem navegador real? Use o endpoint /sandbox/public_token/create para gerar um public_token sem Link. Ideal para testes automatizados.
  • Como integrar o Plaid no desenvolvimento local? Use secret de sandbox no .env e aponte para PlaidEnvironments.sandbox. Para webhooks locais, use tunelamento (ngrok, Cloudflare Tunnel).

Top comments (0)