# Pluggy Docs
> Developer documentation for the Pluggy API
Links below point at the markdown source. Drop the .md for the rendered page.
The full text of every page is at /llms-full.txt.
OpenAPI: /openapi/pluggy-api.json, /openapi/status-api.json, /openapi/enrichment-api.json
MCP server: https://mcp.pluggy.ai/mcp
## Getting Started
- [Visão geral](https://docs.pluggy.ai/pt/docs/overview.md): O que é o Pluggy, os três objetos sobre os quais toda a API é construída e as duas maneiras de criar sua primeira integração.
- [Início Rápido](https://docs.pluggy.ai/pt/docs/quickstart.md): Crie seu primeiro item e leia suas transações — com um agente conectado à documentação ao vivo, ou manualmente.
- [Autenticação](https://docs.pluggy.ai/pt/docs/authentication.md): Saiba como autenticar-se com a Referência da API Pluggy.
- [Glossário](https://docs.pluggy.ai/pt/docs/get-started/glossary.md): Antes de começar a trabalhar com nossa Referência da API, há alguns conceitos importantes que você precisa conhecer.
- [FAQ](https://docs.pluggy.ai/pt/docs/get-started/faq.md): As perguntas que mais recebemos sobre items, conectores, ambientes e atualizações.
- [Contato e suporte](https://docs.pluggy.ai/pt/docs/get-started/contact.md): Quem contatar na Pluggy: vendas e integração para empresas, a comunidade do Discord para uso pessoal.
- [Excluindo sua conta Pluggy](https://docs.pluggy.ai/pt/docs/get-started/delete-account.md): Como fechar uma conta de desenvolvedor que você não usa mais, o que é removido com ela e qual canal escrever — incluindo solicitações de proteção de dados sob a LGPD.
- [Uma aplicação ou uma por cliente?](https://docs.pluggy.ai/pt/docs/get-started/multi-tenant-applications.md): Como organizar aplicações quando seu próprio produto atende a muitas empresas — o que ter uma aplicação de produção por inquilino muda e o que não muda.
## integrations
- [Integração com Slack](https://docs.pluggy.ai/pt/docs/integrations/slack.md): Adicione o bot de documentação hospedado da Pluggy ao seu espaço de trabalho Slack — faça perguntas e obtenha respostas da documentação ao vivo. Sem configuração, sem auto-hospedagem.
## Guides
- [Sandbox](https://docs.pluggy.ai/pt/docs/guides/sandbox.md): Teste sua integração com o ambiente sandbox da Pluggy.
- [Dashboard: conectores, testar conexões e o itemId](https://docs.pluggy.ai/pt/docs/guides/dashboard-connectors.md): Passo a passo no Dashboard da Pluggy: escolha quais conectores o Pluggy Connect exibe, conecte uma conta diretamente do Dashboard e copie o itemId e suas credenciais da API.
- [Uso pessoal: leia seus próprios dados com Meu Pluggy](https://docs.pluggy.ai/pt/docs/guides/meu-pluggy-personal-use.md): Passo a passo para indivíduos: conecte seus bancos no Meu Pluggy, adicione o conector MeuPluggy no Dashboard da Pluggy e leia suas próprias contas através da Referência da API — grátis, sem due diligence.
## Pluggy Connect Widget
- [Introdução](https://docs.pluggy.ai/pt/docs/connect-widget/introduction.md): Pluggy Connect é um widget que você pode integrar facilmente, ajudando você a começar rapidamente com o Pluggy, permitindo que seus usuários conectem suas contas diretamente ao API do Pluggy dentro do seu aplicativo.
- [Autenticação](https://docs.pluggy.ai/pt/docs/connect-widget/authentication.md): Ao conectar-se ao Pluggy a partir de uma aplicação do lado do cliente (ou seja, Connect Widget), um Connect Token é necessário. Este token fornece acesso limitado restrito aos dados do recurso Item gerado.
- [Ambientes e Configurações](https://docs.pluggy.ai/pt/docs/connect-widget/environments.md): Saiba mais sobre os ambientes disponíveis e as opções de configuração para o Connect Widget da Pluggy, incluindo testes em sandbox e configuração de produção.
- [Atualizando um Item](https://docs.pluggy.ai/pt/docs/connect-widget/updating-item.md): Saiba como atualizar um Item existente usando o Connect Widget da Pluggy em vez de criar uma nova conexão do zero.
- [Personalização](https://docs.pluggy.ai/pt/docs/connect-widget/customization.md): A partir do Dashboard, é possível personalizar certos aspectos visuais do Pluggy Connect para que você possa oferecer aos seus usuários uma experiência mais personalizada e com a sua marca.
- [Guia de Suporte ao OAuth](https://docs.pluggy.ai/pt/docs/connect-widget/oauth-support.md): Seguindo essas diretrizes, você pode garantir uma experiência de integração OAuth tranquila para seus usuários em várias plataformas e dispositivos.
## Connections
- [Item](https://docs.pluggy.ai/pt/docs/connections/item.md): Um Item é a representação de uma conexão com um Conector específico de uma Instituição e serve como ponto de entrada para acessar o conjunto de produtos recuperados do usuário que deu consentimento para coletar seus dados.
- [Ciclo de vida do Item](https://docs.pluggy.ai/pt/docs/connections/item-lifecycle.md): Entenda os diferentes status e estados de execução que um Item passa durante a criação, atualização e sincronização com instituições financeiras.
- [Erros e Validações](https://docs.pluggy.ai/pt/docs/connections/errors-validations.md): Saiba mais sobre os diferentes status e erros que você pode enfrentar ao usar a Referência da API do Pluggy.
- [Avisos e Códigos de Status](https://docs.pluggy.ai/pt/docs/connections/warnings-status-codes.md): Entendendo os códigos de aviso e seus significados ao recuperar dados dos conectores Pluggy.
- [Consentimentos e expiração](https://docs.pluggy.ai/pt/docs/connections/consents.md): A primeira vez que um Item se conecta, um Consentimento é criado com uma data de expiração. O Consentimento mostra quais produtos financeiros um item está autorizado a recuperar por um determinado período.
- [Cobertura de Conectores](https://docs.pluggy.ai/pt/docs/connections/connectors-coverage.md): Aqui você encontrará todos os conectores disponíveis no Pluggy listados por tipo de conector, detalhando quais produtos são suportados em cada caso.
- [Recursos de Item](https://docs.pluggy.ai/pt/docs/connections/resources.md): O que a instituição declarou para um consentimento de Open Finance, recurso por recurso — e como diferenciar 'o banco não compartilhou' de 'não coletamos'.
- [Cobertura de Cartões de Crédito](https://docs.pluggy.ai/pt/docs/connections/credit-cards-coverage.md): Aqui você encontrará a cobertura que temos para cada conector em relação ao produto Cartão de Crédito.
- [Cobertura de contas](https://docs.pluggy.ai/pt/docs/connections/accounts-coverage.md): Aqui você encontrará a cobertura que temos para cada connector em relação ao produto de Conta.
- [Cobertura de dados de pagamento](https://docs.pluggy.ai/pt/docs/connections/paymentdata-coverage.md): Aqui você encontrará a cobertura de dados que temos para cada conector em relação ao produto de Dados de Pagamento.
- [Cobertura de investimentos](https://docs.pluggy.ai/pt/docs/connections/investments-coverage.md): Aqui você encontrará a cobertura que temos para cada connector em relação ao produto de Investimentos.
- [Cobertura de Transações de Investimento](https://docs.pluggy.ai/pt/docs/connections/investment-transactions-coverage.md): Aqui você encontrará a cobertura que temos para cada connector em relação ao produto de Transações de Investimento.
- [Cobertura de empréstimos](https://docs.pluggy.ai/pt/docs/connections/loans-coverage.md): Aqui você encontrará a cobertura que temos para cada conector em relação ao produto Loans.
- [Cobertura de identidade](https://docs.pluggy.ai/pt/docs/connections/identity-coverage.md): Aqui você encontrará a cobertura que temos para cada conector em relação ao produto de Identidade.
- [Open Finance vs Direct: diferenças de campo](https://docs.pluggy.ai/pt/docs/connections/open-finance-vs-direct-fields.md): Quais campos da API você obtém apenas de conexões de Open Finance e quais apenas de conexões Diretas.
- [Relatar Problemas](https://docs.pluggy.ai/pt/docs/connections/reporting-issues.md): Este guia explica como entender os problemas que os usuários podem ter e como relatá-los à equipe de suporte da Pluggy.
## Open Finance
- [Conectores Open Finance](https://docs.pluggy.ai/pt/docs/open-finance/overview.md): A Pluggy suporta a obtenção de dados da Rede Brasileira de Open Finance com Conectores Open Finance, seguindo o mesmo modelo de dados que os conectores padrão.
- [Cobertura de Instituições de Open Finance](https://docs.pluggy.ai/pt/docs/open-finance/institutions-coverage.md): Todas as instituições disponíveis via Open Finance, seus contextos (Pessoal, Empresarial, Investimentos) e os produtos que cada connector expõe.
- [Criando um Item](https://docs.pluggy.ai/pt/docs/open-finance/creating-item.md): Como criar sua primeira conexão Regulada de Open Finance, passo a passo através do Connect Widget da Pluggy ou através da API.
- [Considerações e FAQ](https://docs.pluggy.ai/pt/docs/open-finance/considerations-faq.md): Coisas a ter em mente ao integrar dados regulados de Open Finance que podem ser diferentes de Conexões Diretas.
- [Cobertura de Dados de Pagamento Open Finance](https://docs.pluggy.ai/pt/docs/open-finance/payment-data.md): Detalhes de cobertura para a disponibilidade de dados de contrapartida CPF/CNPJ em dados de pagamento de transação Open Finance, por conector e tipo de operação.
- [Cobertura de Investimentos em Open Finance](https://docs.pluggy.ai/pt/docs/open-finance/investments.md): Tabela de cobertura para subtipos de investimento suportados por cada conector de instituição de Open Finance.
- [Limites de Taxa Operacional](https://docs.pluggy.ai/pt/docs/open-finance/rate-limits.md): Limites operacionais do Open Finance impostos pela Rede Brasileira de Open Finance na obtenção de dados por produto, instituição e CPF/CNPJ, além do tempo de resposta da rede e requisitos de tempo limite.
- [SCR — Sistema de Informação de Crédito](https://docs.pluggy.ai/pt/docs/open-finance/scr.md): Consulte o Sistema de Informações de Crédito do Bacen para o documento por trás de um item de Open Finance conectado e leia o payload que o Banco Central retorna.
## Products
- [Conta](https://docs.pluggy.ai/pt/docs/products/accounts.md): O produto da conta é a lista de contas bancárias, como Conta Corrente ou Conta Poupança e Cartão de Crédito, que estavam disponíveis no conector selecionado.
- [Saldo em Tempo Real](https://docs.pluggy.ai/pt/docs/products/real-time-balance.md): A endpoint de saldo em tempo real busca o saldo da conta diretamente da instituição financeira sem acionar uma sincronização completa de itens.
- [Contas de Cartão de Crédito](https://docs.pluggy.ai/pt/docs/products/credit-card-bills.md): A entidade Bill é recuperada de instituições que suportam este produto. Ela representa uma fatura associada a uma conta do tipo Crédito, especificamente o subtipo CARTÃO_DE_CRÉDITO.
- [Transações de cartão de crédito e o ciclo de extrato](https://docs.pluggy.ai/pt/docs/products/credit-card-statement-cycle.md): Por que as transações de cartão de crédito são excluídas e recriadas com um novo id em torno do fechamento de um extrato, o que identifica uma transação entre as sincronizações e o que reconciliar quando não há um id de provedor estável.
- [Transação](https://docs.pluggy.ai/pt/docs/products/transactions.md): Recupere até 12 meses de dados de transações. Os dados das transações das contas fornecem insights sobre o comportamento financeiro do usuário.
- [Classificação de Transações](https://docs.pluggy.ai/pt/docs/products/transaction-categorization.md): A categorização de transações é um recurso onde classificamos suas Transações em categorias úteis (Restaurantes, Postos de Gasolina, Renda, etc.) usando nosso motor de IA de categorização.
- [Investimento](https://docs.pluggy.ai/pt/docs/products/investments.md): A entidade de Investimento é recuperada não apenas de Corretoras (XP, Clear), mas também de instituições bancárias de varejo e empresariais.
- [Transações de Investimento](https://docs.pluggy.ai/pt/docs/products/investment-transactions.md): Cada investimento contém uma lista de transações correspondentes a Aplicações ou Saques. O esquema da transação contém um conjunto de detalhes dessa operação.
- [Empréstimo](https://docs.pluggy.ai/pt/docs/products/loans.md): A entidade Empréstimo é recuperada de instituições que suportam este produto. Ela representa um empréstimo contratado pelo usuário, incluindo dados como número do contrato, impostos, taxas de juros, garantias, parcelas, etc.
- [Identidade](https://docs.pluggy.ai/pt/docs/products/identity.md): A entidade de Identidade é recuperada de instituições que suportam este produto, acessando detalhes de informações pessoais relacionadas ao proprietário da conta da conexão.
- [Parcelas de Cartão de Crédito](https://docs.pluggy.ai/pt/docs/products/credit-card-installments.md): Como o Pluggy captura, sincroniza e entrega compras parceladas de cartão de crédito via API, incluindo comportamentos específicos de instituições, limites de taxa de Open Finance e melhores práticas de webhook.
## Intelligence APIs
- [Insights de Conexão](https://docs.pluggy.ai/pt/docs/intelligence/connection-insights.md): Com base nas contas conectadas, você pode recuperar insights do usuário, livro de variáveis, análise de renda e padrões recorrentes.
- [Enriquecimento de Transações](https://docs.pluggy.ai/pt/docs/intelligence/transaction-enrichment.md): Se você precisar aprimorar seus próprios dados, oferecemos diferentes soluções como uma API para você usar.
- [Análise de Pagamentos Recorrentes](https://docs.pluggy.ai/pt/docs/intelligence/recurring-payments.md): Oferecemos uma API de Pagamentos Recorrentes que permite identificar as despesas e receitas recorrentes de um usuário, útil para o perfil financeiro.
## Payments
- [Visão Geral dos Pagamentos](https://docs.pluggy.ai/pt/docs/payments/overview.md): Com o Pluggy Payments, você pode facilmente criar links de pagamento para cobrar seus clientes e acompanhar automaticamente seus pagamentos, aproveitando integrações OAuth seguras com instituições que utilizam a infraestrutura de Iniciação de Pagamentos do Open Finance.
- [Ciclo de Vida e Erros da Intenção de Pagamento](https://docs.pluggy.ai/pt/docs/payments/intent-lifecycle.md): Aqui você pode encontrar os possíveis status de um Payment Intent e os códigos de erro que podem ocorrer ao tentar processar um pagamento.
- [Pagamentos Agendados (Pix Agendado)](https://docs.pluggy.ai/pt/docs/payments/scheduled-payments.md): Com nossa funcionalidade de iniciação de pagamentos, você pode agendar pagamentos para ocorrer no futuro (também chamado de PIX RECORRENTE) usando diferentes modos de agendamento.
- [Webhooks de Pagamento Agendado](https://docs.pluggy.ai/pt/docs/payments/scheduled-webhooks.md): Saiba mais sobre o fluxo de webhook e os payloads para pagamentos agendados, incluindo códigos de erro que podem ocorrer durante o processamento de pagamentos.
- [FAQ](https://docs.pluggy.ai/pt/docs/payments/scheduled-faq.md): O objetivo desta página é responder a perguntas comuns sobre Pagamentos Agendados.
- [PIX Automático](https://docs.pluggy.ai/pt/docs/payments/pix-automatico.md): Introdução ao Pix Automático com Pluggy - seu portal para pagamentos recorrentes automáticos e sem esforço no Brasil.
- [Começando](https://docs.pluggy.ai/pt/docs/payments/pix-getting-started.md): Integrando com o gateway de pagamentos da Pluggy para Pix Automático - aprenda como criar sua primeira solicitação de pagamento, lidar com autorização, agendar pagamentos e gerenciar tentativas.
- [Agendador de PIX Automático](https://docs.pluggy.ai/pt/docs/payments/pix-scheduler.md): O Agendador de PIX Automático automatiza o agendamento de pagamentos recorrentes sem intervenção manual, respeitando a janela de agendamento permitida de D+2 a D+10.
- [Tentativas automáticas](https://docs.pluggy.ai/pt/docs/payments/pix-retries.md): Quando um Pagamento Pix Automático falha, o Pluggy pode gerenciar automaticamente as tentativas para você - sem chamadas de API extras, sem polling, sem jobs cron do seu lado.
- [Perguntas Frequentes](https://docs.pluggy.ai/pt/docs/payments/pix-faq.md): Perguntas comuns relacionadas a como o Pix Automático funciona, incluindo solicitações de pagamento, primeiros pagamentos, agendamento, cancelamento e tentativas.
- [Cobertura](https://docs.pluggy.ai/pt/docs/payments/coverage.md): Aqui você entenderá como acompanhar quais Instituições suportam cada tipo de pagamento.
- [PIX por biometria](https://docs.pluggy.ai/pt/docs/payments/pix-biometric.md): Deixe os pagadores vincularem uma conta bancária uma vez e confirmarem cada Pix posterior com a biometria de seu dispositivo, sem serem redirecionados para o banco.
- [Começando com PIX por biometria](https://docs.pluggy.ai/pt/docs/payments/pix-biometric-getting-started.md): Crie uma solicitação de pagamento PIX por biometria, envie o pagador para a página de pagamento e acompanhe o pagamento e a conta vinculada.
- [Gerenciando contas vinculadas](https://docs.pluggy.ai/pt/docs/payments/pix-biometric-enrollments.md): Liste, leia e revogue as contas que seus pagadores vincularam para Pix por biometria, veja os pagamentos feitos com cada uma e leia o saldo que um pagador compartilhou.
## Smart Transfers
- [Introdução](https://docs.pluggy.ai/pt/docs/smart-transfers/introduction.md): A API de Smart Transfers da Pluggy torna os pagamentos instantâneos, fáceis e seguros. Aqui descrevemos de forma simples como você pode implementá-la.
- [Criando uma pré-autorização](https://docs.pluggy.ai/pt/docs/smart-transfers/preauthorization.md): Nesta seção, você aprenderá como criar uma pré-autorização para realizar pagamentos sem interação do usuário.
- [Criando um pagamento](https://docs.pluggy.ai/pt/docs/smart-transfers/creating-payment.md): Nesta seção, você aprenderá como criar um pagamento associado a uma Pré-autorização de Transferência Inteligente.
- [Sandbox de Smart Transfers](https://docs.pluggy.ai/pt/docs/smart-transfers/sandbox.md): A maneira mais fácil de experimentar o produto Smart Transfers é usando o conector sandbox.
## Developer Tools
- [Conceitos básicos](https://docs.pluggy.ai/pt/docs/developer-tools/basic-concepts.md): Protocolos de segurança, convenções da API, ambiente, identificadores de solicitação e paginação usados pela Pluggy API.
- [Executar no Postman](https://docs.pluggy.ai/pt/docs/developer-tools/postman.md): Acesse a Coleção Postman da Pluggy para testar todos os endpoints da API disponíveis usando seu CLIENT_ID e CLIENT_SECRET.
- [Conectar uma conta](https://docs.pluggy.ai/pt/docs/developer-tools/connect-account.md): Saiba como conectar a Referência da API da Pluggy com uma instituição financeira, incluindo Direct Connectors com e sem códigos de verificação.
- [Tutoriais](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials.md): Obtenha guias passo a passo sobre como conectar sua conta com sucesso a instituições financeiras específicas.
- [SDKs do Lado do Servidor](https://docs.pluggy.ai/pt/docs/developer-tools/server-sdks.md): A Pluggy oferece bibliotecas de cliente para Node.js, .NET e Java para simplificar a integração com a API.
- [Integrações sem código](https://docs.pluggy.ai/pt/docs/developer-tools/no-code.md): Aqui está uma lista de integrações que não requerem nenhum desenvolvimento para começar a usar o Pluggy.
- [Bolha](https://docs.pluggy.ai/pt/docs/developer-tools/bubble.md): Guia passo a passo para integrar o Pluggy Connect em uma aplicação Bubble.
- [Códigos de Erro](https://docs.pluggy.ai/pt/docs/developer-tools/error-codes.md): Os seguintes erros descrevem, de forma geral, o que você receberá para os diferentes endpoints disponíveis na Referência da API do Pluggy.
- [Limites de taxa](https://docs.pluggy.ai/pt/docs/developer-tools/rate-limits.md): A API da Pluggy implementa um limitador de taxa para maximizar sua estabilidade ao lidar com grandes picos de solicitações recebidas.
- [Página de Status da API](https://docs.pluggy.ai/pt/docs/developer-tools/status-page-api.md): Consuma programaticamente a página de status pública da Pluggy — saúde do conector, incidentes e componentes de infraestrutura.
- [Webhook](https://docs.pluggy.ai/pt/docs/developer-tools/webhooks-ref.md): Saiba mais sobre os webhooks enviados pelo Pluggy para criar uma integração reativa a mudanças de dados e pagamentos.
- [Configurar e Solucionar Problemas](https://docs.pluggy.ai/pt/docs/developer-tools/webhook-troubleshoot.md): Visualize, crie e edite webhooks no Dashboard, veja quais webhooks foram enviados, seus payloads e tente novamente para sincronizar os dados coletados.
- [Detectando falhas de autenticação](https://docs.pluggy.ai/pt/docs/developer-tools/authentication-failures.md): Não há um evento de webhook dedicado para um login bancário falhado. `item/error` é o evento, e seu `error.code` informa se o usuário precisa reinserir as credenciais, autorizar em seu dispositivo ou apenas esperar.
- [Servidor MCP](https://docs.pluggy.ai/pt/docs/developer-tools/mcp.md): Conecte qualquer agente de IA — Claude, ChatGPT/Codex, Cursor, VS Code, Windsurf, Gemini — à documentação ao vivo da Pluggy, Referência da API, changelog, Receitas e Q&A curada através do servidor MCP hospedado, sem autenticação.
- [Habilidades do Agente](https://docs.pluggy.ai/pt/docs/developer-tools/ai-skills.md): Habilidades oficiais da Pluggy para agentes de codificação de IA como Claude Code, Cursor e GitHub Copilot — instale com um comando para que seu agente construa e revise integrações seguindo os padrões documentados da Pluggy.
- [Webhooks de Chamados de Suporte](https://docs.pluggy.ai/pt/docs/developer-tools/support-ticket-webhooks.md): Receba um evento sempre que um dos seus tickets da API de Suporte ao Parceiro mudar — status, resolução, respostas e prioridade — assinado com HMAC-SHA256 e refeito em caso de falha.
## Integration Checklist
- [Criando um caso de uso do zero](https://docs.pluggy.ai/pt/docs/integration-checklist/use-case.md): Este artigo é um guia passo a passo para construir um aplicativo de exemplo simples que se integra com o Pluggy.
- [Checklist de Integração do Pluggy](https://docs.pluggy.ai/pt/docs/integration-checklist/overview.md): Siga estas etapas para garantir que seu aplicativo esteja totalmente integrado com a Pluggy API.
- [Obtenha suas chaves da API](https://docs.pluggy.ai/pt/docs/integration-checklist/api-keys.md): Conheça o Dashboard. Crie sua primeira Aplicação e obtenha suas chaves de acesso.
- [Crie seu primeiro Item](https://docs.pluggy.ai/pt/docs/integration-checklist/first-item.md): Conheça nossa aplicação de demonstração. Conheça o Pluggy Connect e nosso ambiente Sandbox.
- [Use nossos SDKs para Autenticar](https://docs.pluggy.ai/pt/docs/integration-checklist/sdk-auth.md): Usando suas credenciais CLIENT_ID e CLIENT_SECRET da Aplicação, configure a autenticação com a Referência da API Pluggy.
- [Configurar o Pluggy Connect Widget no seu aplicativo](https://docs.pluggy.ai/pt/docs/integration-checklist/setup-widget.md): O Connect Widget é a solução frontend plug and play da Pluggy que permite aos usuários conectar suas contas financeiras em um fluxo passo a passo.
- [Sincronização de dados: Atualizar um Item](https://docs.pluggy.ai/pt/docs/integration-checklist/data-sync.md): Após criar um Item, o próximo passo é mantê-lo atualizado.
- [Configurar sincronização bidirecional com Webhooks](https://docs.pluggy.ai/pt/docs/integration-checklist/webhooks-sync.md): Webhooks permitem que o Pluggy notifique sua aplicação sobre eventos sem que você precise solicitar atualizações, mantendo você atualizado com as últimas mudanças.
- [Gerenciamento de consentimento: Excluir um Item](https://docs.pluggy.ai/pt/docs/integration-checklist/consent-management.md): É de extrema importância que sua integração permita que seus usuários revoguem o consentimento dado ao compartilhar seus dados financeiros.
- [Inscreva-se na nossa Página de Status](https://docs.pluggy.ai/pt/docs/integration-checklist/status-page.md): Confira nossa página de status pública, onde postamos qualquer incidente e interrupções, para que você possa ficar ciente de quaisquer problemas existentes.
## Boleto
- [API de Gerenciamento de Boleto](https://docs.pluggy.ai/pt/docs/boleto/management-api.md): Emita boletos, acompanhe seu pagamento e receba um webhook no momento em que um for liquidado — através de uma única API que oculta as diferenças de cada banco.
- [Cobertura](https://docs.pluggy.ai/pt/docs/boleto/coverage.md): Quais instituições a Referência da API de Gestão de Boleto pode emitir hoje, quais estão sendo construídas e como cada uma autoriza uma conexão.
- [Testando com o Sandbox](https://docs.pluggy.ai/pt/docs/boleto/sandbox.md): Emita boletos e veja-os alcançar cada status por conta própria, sem uma conta bancária, um pagador real ou esperar o vencimento passar.
- [Inter Empresas](https://docs.pluggy.ai/pt/docs/boleto/inter.md): O que uma conexão de boleto Inter Empresas precisa, como o Inter reporta pagamentos e os comportamentos que vale a pena conhecer antes de você entrar ao vivo.
## Tutorials
- [Tutorial Caixa PF (Mobile)](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/caixa-pf-mobile.md): Guia passo a passo para autorizar seu dispositivo e conectar uma conta pessoal da Caixa Econômica Federal usando o aplicativo móvel da Caixa.
- [Tutorial Caixa PF (Web)](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/caixa-pf-web.md): Guia passo a passo para autorizar seu dispositivo e conectar uma conta pessoal da Caixa Econômica Federal usando Internet Banking na web.
- [Tutorial Caixa PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/caixa-pj.md): Quais credenciais usar ao conectar uma conta empresarial da Caixa Empresas: o mesmo nome de usuário e senha usados no Internet Banking.
- [Tutorial do Banco Inter MEI](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/inter-mei.md): Como conectar uma conta MEI do Banco Inter fazendo login no aplicativo Inter com o seu número de conta MEI e escaneando o código QR de acesso.
- [Tutorial do Banco Inter Empresas](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/inter-pj.md): Como criar uma integração de API no Banco Inter Empresas para obter o Client ID, Client Secret, chave e certificado necessários para se conectar com o Pluggy.
- [Tutorial Sicredi](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/sicredi.md): Quais credenciais usar ao conectar uma conta Sicredi Empresas: CNPJ, nome de usuário e senha — as mesmas usadas no aplicativo Sicredi.
- [Tutorial Sicoob PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/sicoob-pj.md): Quais credenciais usar ao conectar uma conta Sicoob Empresas: número da cooperativa, chave de acesso e senha do Internet Banking.
- [Tutorial do Usuário Secundário Santander PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/santander-pj-secondary-user.md): Guia passo a passo para criar um usuário secundário no Santander Empresas para que você possa conectar sua conta empresarial com o Pluggy.
- [Tutorial Santander PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/santander-pj.md): Quais credenciais usar ao conectar uma conta empresarial Santander Empresas: agência, conta, nome de usuário e senha — as mesmas usadas no Internet Banking.
- [Tutorial Itaú PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/itau-pj.md): Quais credenciais usar ao conectar uma conta empresarial Itaú Empresas: agência, conta, senha e CPF — as mesmas usadas no Internet Banking.
- [Tutorial Itaú PJ — Usuário Sem Token](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/itau-pj-user-without-token.md): Como criar um usuário operador sem um token no Itaú Empresas: crie um perfil de acesso, adicione um operador e valide-o pela web.
- [Tutorial do Banco do Brasil PJ — Autorização de Dispositivo](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bb-pj-device-authorization.md): Como autorizar um dispositivo no Internet Banking do Banco do Brasil para que você possa conectar sua conta do Banco do Brasil Empresas.
- [Tutorial do Banco do Brasil PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bb-pj.md): Quais credenciais usar ao conectar uma conta empresarial do Banco do Brasil Empresas: chave J, senha J e senha de 8 dígitos — além das melhores práticas para uma conexão bem-sucedida.
- [Tutorial Bradesco PJ — Habilitar Acesso ao Aplicativo Móvel](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bradesco-pj-mobile-access.md): Como habilitar o acesso ao aplicativo móvel para um usuário do Bradesco Empresas através da seção de administração do Internet Banking.
- [Tutorial Bradesco PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bradesco-pj.md): Quais credenciais usar ao conectar uma conta empresarial Bradesco Empresas: nome de usuário, senha e a chave de segurança gerada no aplicativo Bradesco.
- [Tutorial de Open Finance PF do Bradesco](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bradesco-pf-of.md): Guia passo a passo para conectar uma conta pessoal (PF) do Bradesco via Open Finance, utilizando a validação por QR code no aplicativo do Bradesco.
- [Tutorial Efí Bank PJ](https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/efi-pj.md): Como criar uma aplicação de API no Efí Bank Empresas para obter o Client ID, Client Secret e o certificado necessário para se conectar com o Pluggy.
## API Reference
- [Autenticação](https://docs.pluggy.ai/pt/docs/reference/authentication.md): As duas credenciais que a API Pluggy aceita, como cada uma é emitida, quanto tempo dura e a que pode acessar.
- [Conceitos Básicos](https://docs.pluggy.ai/pt/docs/reference/basic-concepts.md): URL base, transporte, convenções de solicitação e resposta, e como os endpoints paginados são lidos.
- [Códigos de Erro](https://docs.pluggy.ai/pt/docs/reference/error-codes.md): Os códigos de status HTTP que a API Pluggy retorna, o que cada um significa e a estrutura de um corpo de erro.
- [Limites de Taxa](https://docs.pluggy.ai/pt/docs/reference/rate-limits.md): Limites de solicitação por endpoint, a resposta 429 e os cabeçalhos que indicam quando tentar novamente.
- [Webhook](https://docs.pluggy.ai/pt/docs/reference/webhooks.md): Assinando eventos, a lista de eventos, a carga útil que cada notificação carrega e as regras de entrega e reenvio.
- [SDKs do Lado do Servidor](https://docs.pluggy.ai/pt/docs/reference/server-sdks.md): As bibliotecas de cliente oficiais, como instalar cada uma e o documento OpenAPI para gerar o seu próprio.
## API Reference: Status
- [GET /api/status](https://docs.pluggy.ai/pt/reference/status/status-snapshot): Retrieve status snapshot
- [GET /api/connectors-incidents](https://docs.pluggy.ai/pt/reference/status/status-connector-incidents): Retrieve active incidents by connector
- [GET /api/summary](https://docs.pluggy.ai/pt/reference/status/status-summary): Retrieve status summary
## API Reference: Enrichment
- [POST /categorize](https://docs.pluggy.ai/pt/reference/enrichment/categorize): Categorize
- [POST /behavior-analysis](https://docs.pluggy.ai/pt/reference/enrichment/behavior-analysis): Behavior Analysis
- [POST /recurring-payments](https://docs.pluggy.ai/pt/reference/enrichment/recurring-payments): Recurring Payments
## API Reference: Auth
- [POST /auth](https://docs.pluggy.ai/pt/reference/auth/auth-create): Criar Chave da API
- [POST /connect_token](https://docs.pluggy.ai/pt/reference/auth/connect-token-create): Criar Connect Token
## API Reference: Connector
- [GET /connectors](https://docs.pluggy.ai/pt/reference/connector/connectors-list): Lista
- [GET /connectors/{id}](https://docs.pluggy.ai/pt/reference/connector/connector-retrieve): Recuperar
- [POST /connectors/{id}/validate](https://docs.pluggy.ai/pt/reference/connector/connectors-validate): Validar
## API Reference: Items
- [POST /items](https://docs.pluggy.ai/pt/reference/items/items-create): Criar
- [GET /items/{id}](https://docs.pluggy.ai/pt/reference/items/items-retrieve): Consultar
- [PATCH /items/{id}](https://docs.pluggy.ai/pt/reference/items/items-update): Atualizar
- [DELETE /items/{id}](https://docs.pluggy.ai/pt/reference/items/items-delete): Excluir
- [GET /items/{id}/resources](https://docs.pluggy.ai/pt/reference/items/items-resources): Recursos de Item
- [POST /items/{id}/mfa](https://docs.pluggy.ai/pt/reference/items/items-send-mfa): Enviar MFA
- [PATCH /items/{id}/disable-auto-sync](https://docs.pluggy.ai/pt/reference/items/items-disable-autosync): Desativar a sincronização automática do item
- [GET /v2/items](https://docs.pluggy.ai/pt/reference/items/items-list-by-cursor): Listar
## API Reference: SCR
- [GET /items/{id}/scr](https://docs.pluggy.ai/pt/reference/scr/items-retrieve-scr): Recuperar SCR
## API Reference: Consent
- [GET /consents](https://docs.pluggy.ai/pt/reference/consent/consents-list): Lista
- [GET /consents/{id}](https://docs.pluggy.ai/pt/reference/consent/consent-retrieve): Recuperar
## API Reference: Account
- [GET /accounts](https://docs.pluggy.ai/pt/reference/account/accounts-list): Lista
- [GET /accounts/{id}](https://docs.pluggy.ai/pt/reference/account/accounts-retrieve): Recuperar
- [GET /accounts/{id}/statements](https://docs.pluggy.ai/pt/reference/account/account-statements-list): Listar extratos de conta
- [GET /accounts/{id}/balance](https://docs.pluggy.ai/pt/reference/account/account-balance-get): Obtenha saldo em tempo real
## API Reference: Transaction
- [GET /transactions](https://docs.pluggy.ai/pt/reference/transaction/transactions-list): Listar por Página (obsoleto)
- [GET /v2/transactions](https://docs.pluggy.ai/pt/reference/transaction/transactions-list-by-cursor): Lista
- [GET /transactions/{id}](https://docs.pluggy.ai/pt/reference/transaction/transactions-retrieve): Recuperar
- [PATCH /transactions/{id}](https://docs.pluggy.ai/pt/reference/transaction/transactions-Update): Atualizar
## API Reference: Investment
- [GET /investments](https://docs.pluggy.ai/pt/reference/investment/investments-list): Lista
- [GET /investments/{id}](https://docs.pluggy.ai/pt/reference/investment/investments-retrieve): Recuperar
- [GET /investments/{id}/transactions](https://docs.pluggy.ai/pt/reference/investment/investment-transactions-list): Listar transações de investimento
## API Reference: Identity
- [GET /identity](https://docs.pluggy.ai/pt/reference/identity/identity-find-by-item): Encontrar por item
- [GET /identity/{id}](https://docs.pluggy.ai/pt/reference/identity/identity-retrieve): Recuperar
## API Reference: Webhook
- [GET /webhooks](https://docs.pluggy.ai/pt/reference/webhook/webhooks-list): Lista
- [POST /webhooks](https://docs.pluggy.ai/pt/reference/webhook/webhooks-create): Criar
- [GET /webhooks/{id}](https://docs.pluggy.ai/pt/reference/webhook/webhooks-retrieve): Recuperar
- [PATCH /webhooks/{id}](https://docs.pluggy.ai/pt/reference/webhook/webhooks-update): Atualizar
- [DELETE /webhooks/{id}](https://docs.pluggy.ai/pt/reference/webhook/webhooks-delete): Excluir
## API Reference: Category
- [GET /categories](https://docs.pluggy.ai/pt/reference/category/categories-list): Lista
- [GET /categories/{id}](https://docs.pluggy.ai/pt/reference/category/categories-retrieve): Recuperar
- [GET /categories/rules](https://docs.pluggy.ai/pt/reference/category/client-category-rules-list): Regras da Categoria de Listagem
- [POST /categories/rules](https://docs.pluggy.ai/pt/reference/category/client-category-rules-create): Criar Regra de Categoria
- [DELETE /categories/rules/{id}](https://docs.pluggy.ai/pt/reference/category/client-category-rules-delete): Excluir Regra de Categoria
## API Reference: Loan
- [GET /loans](https://docs.pluggy.ai/pt/reference/loan/loans-list): Lista
- [GET /loans/{id}](https://docs.pluggy.ai/pt/reference/loan/loans-retrieve): Recuperar
## API Reference: Merchant
- [GET /merchants](https://docs.pluggy.ai/pt/reference/merchant/merchants-get-by-cnpj): Obter comerciantes pela lista de CNPJ
## API Reference: Bill
- [GET /bills](https://docs.pluggy.ai/pt/reference/bill/bills-list): Lista
- [GET /bills/{id}](https://docs.pluggy.ai/pt/reference/bill/bills-retrieve): Recuperar
## API Reference: Payment Customer
- [GET /payments/customers](https://docs.pluggy.ai/pt/reference/payment-customer/payment-customers-list): Lista
- [POST /payments/customers](https://docs.pluggy.ai/pt/reference/payment-customer/payment-customer-create): Criar
- [GET /payments/customers/{id}](https://docs.pluggy.ai/pt/reference/payment-customer/payment-customer-retrieve): Recuperar
- [PATCH /payments/customers/{id}](https://docs.pluggy.ai/pt/reference/payment-customer/payment-customer-update): Atualizar
- [DELETE /payments/customers/{id}](https://docs.pluggy.ai/pt/reference/payment-customer/payment-customer-delete): Excluir
## API Reference: Payment Recipient
- [GET /payments/recipients](https://docs.pluggy.ai/pt/reference/payment-recipient/payment-recipients-list): Lista
- [POST /payments/recipients](https://docs.pluggy.ai/pt/reference/payment-recipient/payment-recipient-create): Criar
- [GET /payments/recipients/{id}](https://docs.pluggy.ai/pt/reference/payment-recipient/payment-recipient-retrieve): Recuperar
- [PATCH /payments/recipients/{id}](https://docs.pluggy.ai/pt/reference/payment-recipient/payment-recipient-update): Atualizar
- [DELETE /payments/recipients/{id}](https://docs.pluggy.ai/pt/reference/payment-recipient/payment-recipient-delete): Excluir
- [GET /payments/recipients/institutions](https://docs.pluggy.ai/pt/reference/payment-recipient/payment-recipients-institution-list): Listar Instituições
- [GET /payments/recipients/institutions/{id}](https://docs.pluggy.ai/pt/reference/payment-recipient/payment-recipient-institutions-retrieve): Recuperar Instituição
## API Reference: Payment Request
- [GET /payments/requests](https://docs.pluggy.ai/pt/reference/payment-request/payment-requests-list): Lista
- [POST /payments/requests](https://docs.pluggy.ai/pt/reference/payment-request/payment-request-create): Criar
- [POST /payments/requests/pix-qr](https://docs.pluggy.ai/pt/reference/payment-request/payment-request-create-pix-qr): Criar solicitação de pagamento via QR PIX
- [GET /payments/requests/{id}](https://docs.pluggy.ai/pt/reference/payment-request/payment-request-retrieve): Recuperar
- [PATCH /payments/requests/{id}](https://docs.pluggy.ai/pt/reference/payment-request/payment-request-update): Atualizar
- [DELETE /payments/requests/{id}](https://docs.pluggy.ai/pt/reference/payment-request/payment-request-delete): Excluir
## API Reference: Automatic PIX
- [POST /payments/requests/automatic-pix](https://docs.pluggy.ai/pt/reference/automatic-pix/payment-request-create-automatic-pix): Criar solicitação de pagamento PIX automático
- [POST /payments/requests/{id}/automatic-pix/schedule](https://docs.pluggy.ai/pt/reference/automatic-pix/payment-request-create-automatic-pix-schedule): Agendar pagamento automático via PIX
- [GET /payments/requests/{id}/automatic-pix/schedules](https://docs.pluggy.ai/pt/reference/automatic-pix/payment-request-get-automatic-pix-schedules): Listar pagamentos automáticos de PIX agendados
- [GET /payments/requests/{requestId}/automatic-pix/schedules/{paymentId}](https://docs.pluggy.ai/pt/reference/automatic-pix/payment-request-get-automatic-pix-schedule): Obtenha um pagamento PIX agendado automaticamente
- [POST /payments/requests/{id}/automatic-pix/cancel](https://docs.pluggy.ai/pt/reference/automatic-pix/payment-request-cancel-automatic-pix-consent): Cancelar um consentimento automático de PIX
- [POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/cancel](https://docs.pluggy.ai/pt/reference/automatic-pix/cancel-automatic-pix-schedule): Cancelar um agendamento automático de PIX
- [POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry](https://docs.pluggy.ai/pt/reference/automatic-pix/retry-automatic-pix-schedule): Tentar novamente um agendamento automático de PIX
## API Reference: Payment Schedule
- [GET /payments/requests/{id}/schedules](https://docs.pluggy.ai/pt/reference/payment-schedule/payment-schedules-list): Listar Agendas
- [POST /payments/requests/{id}/schedules/cancel](https://docs.pluggy.ai/pt/reference/payment-schedule/payment-schedules-cancel): Cancelar Autorização de Agendamento de Pagamento
- [POST /payments/requests/{id}/schedules/{scheduleId}/cancel](https://docs.pluggy.ai/pt/reference/payment-schedule/payment-schedules-cancel-specific): Cancelar Agendamento de Pagamento
## API Reference: Payment Intent
- [GET /payments/intents](https://docs.pluggy.ai/pt/reference/payment-intent/payment-intents-list): Lista
- [POST /payments/intents](https://docs.pluggy.ai/pt/reference/payment-intent/payment-intent-create): Criar
- [GET /payments/intents/{id}](https://docs.pluggy.ai/pt/reference/payment-intent/payment-intent-retrieve): Recuperar
## API Reference: Pix por biometria
- [POST /payments/requests/pix-biometric](https://docs.pluggy.ai/pt/reference/pix-por-biometria/payment-request-create-pix-biometric): Criar solicitação de pagamento Pix por biometria
- [GET /pix-biometric/enrollments](https://docs.pluggy.ai/pt/reference/pix-por-biometria/pix-biometric-enrollments-list): Listar vínculos
- [GET /pix-biometric/enrollments/{id}](https://docs.pluggy.ai/pt/reference/pix-por-biometria/pix-biometric-enrollment-retrieve): Recuperar vínculo
- [POST /pix-biometric/enrollments/{id}/revoke](https://docs.pluggy.ai/pt/reference/pix-por-biometria/pix-biometric-enrollment-revoke): Revogar vínculo
- [GET /pix-biometric/enrollments/{id}/balance](https://docs.pluggy.ai/pt/reference/pix-por-biometria/pix-biometric-enrollment-balance-retrieve): Consultar saldo da conta
- [DELETE /pix-biometric/enrollments/{id}/data-consent](https://docs.pluggy.ai/pt/reference/pix-por-biometria/pix-biometric-enrollment-data-consent-delete): Cancelar permissão de saldo
## API Reference: Smart Transfer
- [GET /smart-transfers/preauthorizations](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-tranfers-preauthorizations-list): Listar pré-autorizizações
- [POST /smart-transfers/preauthorizations](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-transfer-preauthorization-create): Criar pré-autorização
- [GET /smart-transfers/preauthorizations/{id}](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-transfer-preauthorization-retrieve): Recuperar pré-autorização
- [GET /smart-transfers/preauthorizations/{id}/balance](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-transfer-preauthorization-balance-retrieve): Recuperar saldo da conta de origem
- [DELETE /smart-transfers/preauthorizations/{id}/data-consent](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-transfer-preauthorization-data-consent-delete): Cancelar permissão de saldo
- [GET /smart-transfers/preauthorizations/{id}/payments](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-transfer-preauthorization-payments-list): Listar pagamentos de pré-autorização
- [POST /smart-transfers/payments](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-transfer-payment-create): Criar pagamento
- [GET /smart-transfers/payments/{id}](https://docs.pluggy.ai/pt/reference/smart-transfer/smart-transfer-paymentretrieve): Recuperar pagamento
## API Reference: Boleto Management
- [POST /boleto-connections](https://docs.pluggy.ai/pt/reference/boleto-management/boleto-connection-create): Conectar credenciais de boleto
- [POST /boleto-connections/from-item](https://docs.pluggy.ai/pt/reference/boleto-management/boleto-connection-create-from-item): Criar conexão de boleto a partir do Item
- [DELETE /boleto-connections/{id}](https://docs.pluggy.ai/pt/reference/boleto-management/boleto-connection-delete): Excluir conexão de boleto
- [POST /boletos](https://docs.pluggy.ai/pt/reference/boleto-management/boleto-create): Emitir Boleto
- [POST /boletos/{id}/cancel](https://docs.pluggy.ai/pt/reference/boleto-management/boleto-cancel): Cancelar Boleto
- [GET /boletos/{id}](https://docs.pluggy.ai/pt/reference/boleto-management/boleto-get): Obter Boleto
## Recipes
- [Deleting your Data](https://docs.pluggy.ai/pt/recipes/deleting-your-data.md): Delete Items to remove user consents from Pluggy.
- [Encrypt parameters](https://docs.pluggy.ai/pt/recipes/encrypt-parameters.md): Example to encrypt your parameters before create or update an item.
- [Generate a Connect Token with permissions to update an existing Item](https://docs.pluggy.ai/pt/recipes/generate-a-connect-token-with-permissions-to-update-an-existing-item.md): In order to update an Item you should generate, in your server, a Connect Token linked to the Item Id you want to update.
- [PluggyConnect: Continue connecting item in background as soon as user's login is completed](https://docs.pluggy.ai/pt/recipes/pluggyconnect-continue-connecting-item-in-background-as-soon-as-users-login-is-completed.md): Hide PluggyConnect in background as soon as the login step has been completed, so the User can focus again on your application. PluggyConnect will continue polling the item status until it's completed.
- [Polling an item connector's execution status](https://docs.pluggy.ai/pt/recipes/polling-an-item-connectors-execution-status.md): How to check and poll for the Item status, to know when the Item execution finishes and be able to act on it.
- [Update an Item using Pluggy Connect](https://docs.pluggy.ai/pt/recipes/update-an-item-using-pluggy-connect.md): Full standalone HTML client example to update an existing Item using Pluggy Connect widget.
## Changelog
- [Atualizações de Produto | Setembro/2026](https://docs.pluggy.ai/pt/changelog#2026.09): Published 2026-09-30
- [Atualizações de Produto | Agosto/2026](https://docs.pluggy.ai/pt/changelog#2026.08): Published 2026-08-31
- [Atualizações de produto | Julho/2026](https://docs.pluggy.ai/pt/changelog#2026.07): Published 2026-08-13
- [Atualizações de produto | Junho/2026](https://docs.pluggy.ai/pt/changelog#2026.06): Published 2026-08-13
- [Atualizações de Produto | Julho/2026](https://docs.pluggy.ai/pt/changelog#2026.07): Published 2026-08-13
- [Atualizações de Produto | Junho/2026](https://docs.pluggy.ai/pt/changelog#2026.06): Published 2026-08-12
- [Atualizações de produto | Maio/2026](https://docs.pluggy.ai/pt/changelog#2026.05): Published 2026-07-22
- [Atualizações de Produto | Março/2026](https://docs.pluggy.ai/pt/changelog#2026.03): Published 2026-04-09
- [Atualizações de Produto | Fevereiro 2026](https://docs.pluggy.ai/pt/changelog#2026.02): Published 2026-03-18
- [Atualizações de Produto | Setembro](https://docs.pluggy.ai/pt/changelog#2025.09): Published 2025-10-07
- [[Atualizações de Produto] Agosto-25](https://docs.pluggy.ai/pt/changelog#2025.08): Published 2025-09-15
- [[Atualizações de Produto] Julho-25](https://docs.pluggy.ai/pt/changelog#2025.07): Published 2025-08-07
- [[Atualizações de Produto] Junho-25](https://docs.pluggy.ai/pt/changelog#2025.06): Published 2025-07-04
- [[Atualizações de Produto] Maio-25](https://docs.pluggy.ai/pt/changelog#2025.05): Published 2025-06-05
- [[Atualizações de Produto] Abril-25](https://docs.pluggy.ai/pt/changelog#2025.04): Published 2025-05-05
- [[Atualizações de Produto] Março-25](https://docs.pluggy.ai/pt/changelog#2025.03): Published 2025-04-08
- [[Atualizações de Produto] Fevereiro-25](https://docs.pluggy.ai/pt/changelog#2025.02): Published 2025-03-07
- [[Atualizações de Produto] Janeiro-25](https://docs.pluggy.ai/pt/changelog#2025.01): Published 2025-01-27
- [[Atualizações de Produto] Dezembro-24](https://docs.pluggy.ai/pt/changelog#2024.12): Published 2024-12-16
- [[Atualizações de Produto] Novembro-24](https://docs.pluggy.ai/pt/changelog#2024.11): Published 2024-11-18
- [[Atualizações de Produto] Outubro-24](https://docs.pluggy.ai/pt/changelog#2024.10): Published 2024-10-08
- [Q3 (Jun-Sep) 2024](https://docs.pluggy.ai/pt/changelog#2024.Q3): Published 2024-08-27
- [Q2 (Apr-Jun) 2024](https://docs.pluggy.ai/pt/changelog#2024.Q2): Published 2024-06-21
- [Q1 (Jan-Mar) 2024](https://docs.pluggy.ai/pt/changelog#2024.Q1): Published 2024-06-21
- [Dezembro de 2023 (Atualização Mensal)](https://docs.pluggy.ai/pt/changelog#2023.12): Published 2023-12-07
- [December 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.12): Published 2023-12-07
- [Setembro de 2023 (atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.09): Published 2023-10-08
- [September 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.09): Published 2023-10-08
- [Agosto 2023 (Atualização Mensal)](https://docs.pluggy.ai/pt/changelog#2023.08): Published 2023-09-07
- [August 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.08): Published 2023-09-07
- [Julho 2023 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.07): Published 2023-08-07
- [July 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.07): Published 2023-08-07
- [Junho 2023 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.06): Published 2023-07-04
- [June 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.06): Published 2023-07-04
- [Maio 2023 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.05): Published 2023-06-01
- [May 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.05): Published 2023-05-31
- [Abril 2023 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.04): Published 2023-05-08
- [April 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.04): Published 2023-05-03
- [Março 2023 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.03): Published 2023-04-03
- [March 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.03): Published 2023-03-14
- [Fevereiro 2023 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.02): Published 2023-02-21
- [February 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.02): Published 2023-02-20
- [Janeiro 2023 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2023.01): Published 2023-01-11
- [January 2023 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2023.01): Published 2023-01-10
- [Dezembro 2022 (Atualização mensal)](https://docs.pluggy.ai/pt/changelog#2022.12): Published 2022-12-16
- [December 2022 (Monthly Update)](https://docs.pluggy.ai/pt/changelog#2022.12): Published 2022-12-15
---
## Visão geral
Source: https://docs.pluggy.ai/pt/docs/overview.md
Pluggy é uma plataforma de open finance para a América Latina. Uma integração de API alcança centenas de instituições financeiras — contas bancárias, cartões de crédito, investimentos, empréstimos, identidade e pagamentos — e retorna seus dados em uma única forma normalizada, seja ela proveniente de um conector de Open Finance regulamentado ou de um dos próprios conectores da Pluggy.
## Os três objetos
Quase tudo na API é um desses, e o resto depende deles:
- **Connector** — uma instituição financeira e os produtos que ela pode retornar.
- **Item** — a conexão de um usuário através de um conector, criada após seu consentimento. É o ponto de entrada para seus dados e a coisa que você armazena do seu lado.
- **Product** — os dados normalizados que um item fornece: contas, transações, investimentos, identidade, empréstimos.
O [Glossary](/docs/get-started/glossary) tem o restante do vocabulário; o guia [Item](/docs/connections/item) cobre o ciclo de vida que você realmente passará seu tempo.
## Duas maneiras de construir a primeira integração
Ambas terminam no mesmo lugar — um item criado e suas transações na sua tela.
Conecte seu agente de codificação a estes docs com uma URL, depois forneça o prompt que constrói todo o fluxo.
Cinco passos com curl: um aplicativo, uma chave de API, um connect token, o widget, os dados.
### Aponte um agente para a documentação ao vivo
Se você codifica com Claude, Cursor, Copilot, Codex ou Gemini, conecte-os à nossa documentação primeiro. É uma URL, hospedada, sem chave:
```bash
claude mcp add --transport http pluggy-docs https://mcp.pluggy.ai/mcp
```
O agente então lê os guias atuais e a especificação OpenAPI em tempo de execução, em vez de recordar qualquer versão da nossa API que estava em seus dados de treinamento — a diferença entre código que roda e código que parece certo. A configuração para todos os outros clientes está na página [MCP server](/docs/developer-tools/mcp), e o prompt que constrói todo o fluxo está no [Quick Start](/docs/quickstart).
Mais duas superfícies, para agentes que você não pode configurar: cada página aqui tem um gêmeo em markdown — adicione `.md` à sua URL — e [`/llms.txt`](https://v2.docs.pluggy.ai/llms.txt) indexa todos eles. Qualquer coisa que possa buscar uma URL pode ler nossos docs corretamente.
### Ou siga os passos você mesmo
O [Quick Start](/docs/quickstart) é composto por cinco passos: crie um aplicativo, obtenha uma chave de API, emita um connect token, abra o widget, leia os dados. Nada neste site assume que você usa um agente.
## Sandbox primeiro
Novos aplicativos começam com acesso aos [Sandbox connectors](/docs/guides/sandbox), para que você possa executar todo o fluxo — incluindo os casos de falha que você preferiria encontrar agora do que em produção — contra instituições falsas, sem credenciais reais envolvidas.
## Início Rápido
Source: https://docs.pluggy.ai/pt/docs/quickstart.md
Ao final desta página, um usuário conectou uma instituição financeira e você está lendo suas contas e transações. Cinco etapas, qualquer que seja o caminho que você seguir: crie uma aplicação, obtenha uma chave de API, emita um connect token, abra o widget, leia os dados.
## Construa com um agente
Seu agente pode escrever essa integração, e ele escreve uma muito melhor quando está lendo nossa documentação atual em vez de lembrar uma versão mais antiga dela.
### 1. Conecte os docs
Uma URL hospedada, sem chave de API, nada para instalar:
```bash
claude mcp add --transport http pluggy-docs https://mcp.pluggy.ai/mcp
```
Cursor, ChatGPT, Codex, VS Code, Windsurf e Gemini cada um usa a mesma URL em sua própria configuração — o trecho exato para cada um está na página do
[servidor MCP](/docs/developer-tools/mcp). Adicionar nossa
[Habilidade de Agente](/docs/developer-tools/ai-skills) por cima fornece os padrões de integração para acompanhar a referência.
### 2. Descreva o que você quer
Cole isso, com sua pilha preenchida:
```text
Use o servidor MCP da Pluggy Docs (pluggy-docs) para cada pergunta sobre a Pluggy — leia os guias atuais e a especificação OpenAPI antes de escrever código, e cite as páginas que você usou.
Construa uma integração mínima da Pluggy em :
1. Uma rota de servidor que troca CLIENT_ID e CLIENT_SECRET por uma chave de API.
2. Uma rota de servidor que emite um connect token para um usuário específico.
3. Uma página frontend que abre o widget Pluggy Connect com esse token e
armazena o itemId de seu callback onSuccess.
4. Uma rota de servidor que lista as contas desse item e suas transações,
lidando com paginação.
Regras: CLIENT_SECRET nunca sai do servidor, as credenciais vêm de variáveis de ambiente, e o status do item é tratado — nem toda conexão está pronta no momento em que o widget fecha.
```
Então, faça a ele as perguntas que você de outra forma teria pesquisado — *por que este item está em `WAITING_USER_INPUT`?*, *o que significa este evento de webhook?* — e ele responderá a partir das mesmas páginas que você está lendo agora.
### 3. O que ainda é sua responsabilidade
Um agente não pode se inscrever por você. Crie a conta e a aplicação na etapa 1 abaixo, coloque as credenciais em seu ambiente e leia o código que ele escreveu antes de executá-lo contra qualquer coisa real — o Sandbox existe exatamente para isso.
Cada página aqui tem um gêmeo em markdown: adicione `.md` a qualquer URL de docs. O índice completo está em
[`/llms.txt`](https://v2.docs.pluggy.ai/llms.txt), o site inteiro como um arquivo está em
[`/llms-full.txt`](https://v2.docs.pluggy.ai/llms-full.txt), e a especificação OpenAPI está
em [`/openapi/pluggy-api.json`](https://v2.docs.pluggy.ai/openapi/pluggy-api.json).
O botão **Copiar para LLM** no topo de cada página lhe dá a mesma coisa para uma
única página.
## Ou faça manualmente
Confira nosso [repositório de quickstart](https://github.com/pluggyai/quickstart) no GitHub -- ele contém aplicativos de exemplo prontos para rodar (Node, Python, Java e exemplos frontend) que implementam todo esse fluxo.
### 1. Crie sua conta e aplicação
1. Inscreva-se no [Dashboard da Pluggy](https://dashboard.pluggy.ai).
2. Crie uma **aplicação**. Cada aplicação tem seu próprio `CLIENT_ID` e `CLIENT_SECRET`. O `CLIENT_SECRET` é mostrado apenas uma vez, quando a aplicação é criada -- copie-o e armazene-o com segurança. O `CLIENT_ID` permanece na página da aplicação no Dashboard.
Novas aplicações começam com acesso aos nossos [conectores Sandbox](/docs/guides/sandbox), para que você possa testar todo o fluxo com instituições falsas antes de ir para a produção.
### 2. Obtenha uma chave de API
Autentique-se com suas credenciais para obter uma chave de API. Esta etapa deve ser feita a partir do seu **servidor** -- nunca exponha seu `CLIENT_SECRET` em código do lado do cliente.
```bash
curl -X POST https://api.pluggy.ai/auth \
-H "Content-Type: application/json" \
-d '{
"clientId": "YOUR_CLIENT_ID",
"clientSecret": "YOUR_CLIENT_SECRET"
}'
```
A resposta contém um `apiKey`, válido por 2 horas, com acesso total à API:
```json
{
"apiKey": "eyJhbGciOiJIUzI1..."
}
```
### 3. Crie um Connect Token
Para permitir que seus usuários conectem suas contas a partir do seu aplicativo, crie um Connect Token de curta duração (válido por 30 minutos) com sua chave de API:
```bash
curl -X POST https://api.pluggy.ai/connect_token \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{}'
```
A resposta contém um `accessToken` -- este é o token que você passa para o widget. Veja [Autenticação](/docs/authentication) para os detalhes completos sobre escopos e opções.
### 4. Abra o Connect Widget
Use o [Connect Widget](/docs/connect-widget/introduction) em seu frontend, inicializado com o `accessToken` da etapa anterior. O widget lida com todo o fluxo de autenticação com a instituição financeira e cria um [Item](/docs/connections/item) -- a representação da conexão do usuário. Pegue o `itemId` do evento `onSuccess` do widget.
### 5. Busque os dados
Com a conexão criada, use sua chave de API (lado do servidor) para recuperar os dados:
```bash
# Liste as contas da conexão
curl "https://api.pluggy.ai/accounts?itemId=YOUR_ITEM_ID" \
-H "X-API-KEY: YOUR_API_KEY"
# Liste as transações de uma conta
curl "https://api.pluggy.ai/transactions?accountId=YOUR_ACCOUNT_ID" \
-H "X-API-KEY: YOUR_API_KEY"
```
## Próximos passos
- Entenda os conceitos principais no [Glossário](/docs/get-started/glossary)
- Teste cada fluxo com o [Sandbox](/docs/guides/sandbox)
- Explore todos os endpoints na [Referência da API](/reference)
## Autenticação
Source: https://docs.pluggy.ai/pt/docs/authentication.md
Pluggy usa dois tipos de credenciais, dependendo de onde a solicitação é feita:
- **API Key** -- usada para solicitações do lado do servidor. Ela dá acesso total a todos os endpoints da API Pluggy.
- **Connect Token** -- usada em aplicações do lado do cliente (ou seja, o [Connect Widget](/docs/connect-widget/introduction)). Seu acesso é limitado em escopo.
O acesso do Connect Token é limitado apenas aos dados do recurso Item gerado ([GET /items/:id](/reference/items-retrieve)), e um acesso reduzido aos dados das Contas recuperadas ([GET /accounts?itemId=](/reference/accounts-list)).
Portanto, por exemplo, um Connect Token recém-criado não pode ser usado para acessar informações que foram criadas anteriormente com um Connect Token diferente.
Para qualquer outro tipo de solicitação, como recuperar todos os dados de produtos relacionados ao Item, configurar webhooks, [e mais](/reference/auth), você precisará fazer solicitações do lado do servidor usando sua API Key.
## Criar uma API Key
Primeiro, você precisará se autenticar com a API Pluggy, usando seu `CLIENT_ID` e `CLIENT_SECRET`, para [criar uma API Key](/reference/auth-create) via `POST /auth`.
*Observe que essas credenciais são extremamente **sensíveis**, então, por favor, certifique-se de fazer esta etapa apenas em seu servidor seguro.*
Esta API Key expira após 2 horas e lhe dará acesso total a todos os endpoints da API Pluggy.
## Criar um Connect Token
Em seguida, com sua API Key, você terá que fazer uma chamada para [POST /connect_token](/reference/connect-token-create).
O `connectToken` é válido apenas por 30 minutos.
O uso recomendado é 1-por-conexão, então sugerimos criar um novo sempre que você quiser criar ou atualizar um Item.
O uso deste **Connect Token** é idêntico ao da **API Key**: basta passá-lo no cabeçalho de autenticação da solicitação, e a API Pluggy cuidará de validar seu escopo.
Tentativas de acessar dados detalhados de produtos usando um Connect Token (em vez de uma API Key) resultarão em uma resposta da API `403 Forbidden`.
### Configurando um Connect Token
Ao criar um Connect Token, você pode fornecer algumas `ItemOptions` que serão passadas para todos os Itens criados usando o mesmo Connect Token. **Elas devem ser enviadas aninhadas dentro do atributo `options` do corpo da solicitação** -- este é o payload completo:
```json
{
"options": {
"webhookUrl": "https://example.com/webhook",
"clientUserId": "My App UserId",
"oauthRedirectUri": "https://pluggy.ai/demo",
"avoidDuplicates": true
}
}
```
- `webhookUrl`: URL onde você receberá todos os eventos dos Itens criados com este token.
- `clientUserId`: Você pode usar este campo para vincular um Item ao identificador do seu usuário.
- `oauthRedirectUri`: URL para redirecionar o usuário após o fluxo de conexão.
- `avoidDuplicates`: Evita criar um novo Item se já houver um com as mesmas credenciais.
O único outro atributo aceito na raiz do corpo é `itemId`, usado quando o widget atualiza um Item existente (veja [Atualizando um Item](/docs/connect-widget/updating-item)).
Qualquer outra propriedade enviada na **raiz** do corpo é ignorada. Enviar `clientUserId`
na raiz em vez de dentro de `options` ainda retorna `200 OK`, mas o valor é
descartado: os Itens criados com esse token terão `clientUserId: null`, e o
campo também será `null` nos payloads de webhook `item/created`, `item/updated` e `item/error`.
```json
// ❌ Errado -- clientUserId é silenciosamente descartado
{ "clientUserId": "My App UserId", "options": { "avoidDuplicates": true } }
// ✅ Correto
{ "options": { "clientUserId": "My App UserId", "avoidDuplicates": true } }
```
Se você já tiver Itens criados dessa forma, pode preencher o valor com
[PATCH /items/{id}](/reference/items-update).
## Criando um Item
Para resumir, o fluxo para criar um [Item](/docs/connections/item) usando um `connectToken` é:
1. Seu servidor se autentica com `CLIENT_ID` e `CLIENT_SECRET` para obter uma API Key.
2. Seu servidor cria um Connect Token e o envia para sua aplicação cliente.
3. Sua aplicação cliente usa o Connect Token para criar o Item.
Se você estiver usando nosso [Connect Widget](/docs/connect-widget/introduction), você só precisará se preocupar em fornecer o Connect Token -- o resto será tratado por nós.
### Mantendo uma referência de conexão
Ao inicializar o Connect Widget para seu usuário, você pode querer rastrear a qual usuário a conexão criada pertence. Isso pode ser feito de algumas maneiras:
- **Evento `onSuccess` do Connect Widget**: Quando a conexão é criada e retornada, você pode recuperar o `itemId` para armazenar do seu lado.
- **Webhooks**: Após o Item ter sido criado e sincronizado com sucesso, você receberá eventos. Veja [Webhooks](/docs/developer-tools/webhooks-ref).
- **Vinculando seu identificador de usuário a um Item**: Se você precisar vincular o Item ao seu usuário, pode armazenar uma referência em nosso Item usando o `clientUserId`. Este valor pode ser fornecido ao criar o `connectToken` ou ao criar um Item diretamente através do [endpoint de Itens](/docs/connections/item).
## Glossário
Source: https://docs.pluggy.ai/pt/docs/get-started/glossary.md
## Produto
Um Produto representa dados padronizados de uma instituição financeira com um conjunto específico de atributos para um propósito específico. ou seja, Contas, Cartões de Crédito, Investimentos, Identidade, Transações.
## Conector
Um Conector representa uma integração com uma instituição financeira que recupera produtos específicos com base no acesso do usuário.
## Tipo de Conector
Cada conector tem um `tipo` que indica qual lado da instituição ele alcança: `PERSONAL_BANK` (conta bancária de um indivíduo), `BUSINESS_BANK` (conta bancária de uma empresa) ou `INVESTMENT`. Conectores de INVESTMENT alcançam a corretora ou plataforma de investimento do usuário, não sua conta corrente. A mesma instituição pode ter um conector de cada tipo, cada um com seu próprio id — por exemplo, os conectores de Open Finance BTGPactual (675, `PERSONAL_BANK`) e BTGPactual Investimentos (614, `INVESTMENT`).
## Item
Um Item é a representação de uma conexão através de um conector específico de uma Instituição, e serve como ponto de entrada para acessar o conjunto de produtos recuperados, após o usuário ter dado seu consentimento para coletar seus dados.
Para criar um Item, a maneira mais fácil para um usuário é interagir com nosso [Pluggy Connect Widget](/docs/pluggy-connect-introduction), onde ele pode fornecer seu consentimento, seguir os passos de autenticação e, finalmente, habilitar o acesso a todos os seus produtos através da nossa API.
## Chave da API
Uma **chave da API** funciona como um segredo da API e expira 2 horas após a criação. Esta será usada para autenticar todas as solicitações feitas à API da Pluggy. Uma vez que o token expire, um novo deve ser criado, usando suas correspondentes credenciais **CLIENT_ID** e **CLIENT_SECRET**.
Você pode obter suas próprias credenciais **Client ID** e **Client Secret** se inscrevendo em nosso [Dashboard](http://dashboard.pluggy.ai/).
Todas as chaves da API podem ser revogadas a partir do nosso Dashboard caso você precise, e obter novas chaves.
## Connect Token
O **Connect Token** é outro tipo de segredo da API. Ele expira 30 minutos após a criação. É orientado para ser usado no `lado do cliente`, uma vez que seu acesso é restrito a ([`GET /items/:id`](/reference/items-retrieve)), e acesso reduzido aos dados das Contas recuperadas ([`GET /accounts?itemId`](/reference/accounts-list)).
Para gerá-lo, (nota: isso deve ser feito no `lado do servidor`) você deve fazer uma chamada para [POST /connect_token](/reference/connect-token-create) usando sua **chave da API**. Veja mais informações sobre **Connect Token** [aqui](/docs/authentication).
## FAQ
Source: https://docs.pluggy.ai/pt/docs/get-started/faq.md
Aqui você encontrará as perguntas mais frequentes.
## Conceitos básicos
### O que é um item?
Um item representa a conexão entre um usuário e uma instituição financeira, bem como todos os dados retornados nessa conexão.
### O que é uma aplicação e quais os tipos disponíveis?
Uma aplicação diz respeito as chaves de _clientId_ e _clientSecret_ utilizadas para acessar a API. Essas chaves devem ser manuseadas com atenção, pois é somente com elas que os dados da API podem ser retornados. É possível criar aplicações nos ambientes de `Desenvolvimento` e `Produção`.
### Qual a diferença entre apiKey e connectToken?
[apiKey](/reference/auth/auth-create) é a chave que dá acesso à nossa API. É obtida através das credenciais do cliente na Pluggy (_clientId_ & _clientSecret_) e tem validade de 2 horas.
[connectToken](/reference/auth/connect-token-create) é a chave utilizada para acessar o Pluggy Connect Widget, ou seja, a interface gráfica de nossa API. Para obter o connectToken é necessário a obtenção da apiKey em primeiro lugar. O connectToken tem duração de 30 minutos.
## Conectores e instituições financeiras
### Qual a diferença entre conectores Pluggy e conectores Open Finance?
| | Conectores Pluggy (não regulado) | Conectores Open Finance (regulado) |
| -------------- | ------------------------------------- | ------------------------------------- |
| **Tecnologia** | Proprietária da Pluggy | Estrutura regulada pelo Banco Central |
| **Acesso** | Direto às instituições financeiras | Via consentimento do usuário |
| **Dados** | Conforme exibidos no Internet Banking | Padronizados e enriquecidos |
Para mais informações, acesse nossa [documentação](/docs/connections/item).
### Como consultar as instituições financeiras disponíveis para conexão?
Existem algumas maneiras de consultar as instituições financeiras (conectores) disponíveis:
- **Documentação:** conectores Open Finance (regulado) [aqui](/docs/open-finance/overview#institutions-supported-by-open-finance), conectores Pluggy (não regulado) [aqui](/docs/connections/connectors-coverage).
- **API:** consultar [aqui](/reference/connector/connectors-list).
- **Dashboard:** consultar [aqui](https://dashboard.pluggy.ai/customization).
### Quais instituições precisam de token para conectar?
As instituições que requerem token para realizar a conexão podem ser analisadas nesta [página](/docs/connections/connectors-coverage) de nossa documentação.
### Como habilitar os conectores em minha aplicação?
Para habilitar conectores na nossa widget, basta acessar a aba de **Customização** no nosso [dashboard](https://dashboard.pluggy.ai/customization).
### É possível pular a etapa de selecionar o banco na Pluggy Connect Widget?
Sim, nós disponibilizamos um atributo `selectedConnectorId` que permite exibir apenas o conector pré-definido. Mais detalhes em nossa [documentação](/docs/connect-widget/environments#available-configurations).
## Gerenciamento de items e conexões
### Se um usuário conectar duas vezes a mesma conta, serão geradas duas conexões diferentes?
Sim. Cada vez que o usuário dá seu consentimento (inserção de credenciais nos conectores Pluggy ou seleção dos dados a serem compartilhados nos conectores Open Finance), é gerada nova conexão (novo `itemId`). Para evitar que isso ocorra, devemos realizar uma conexão e atualizar essa mesma conexão (itemId) para que os dados mais recentes possam ser retornados pela nossa API.
Para mitigar esse cenário, oferecemos uma configuração que verifica se a conta já foi conectada anteriormente. Para mais informações, acesse nossa [documentação](/docs/connections/item#avoiding-duplicates).
### Como posso identificar que uma conexão (itemId) pertence a um cliente específico?
Nós disponibilizamos um campo para ser preenchido com as informações do usuário que está realizando a conexão. Esse campo é o `clientUserId` e deve ser enviado no momento da criação do item (conexão da conta) ou, para usuários da Pluggy Connect Widget, pode ser enviado no momento de sua abertura.
O campo `clientUserId` recebe qualquer dado (string) que você quiser enviar, mas recomendamos o seguinte padrão: `"nome | email | cpf_ou_cnpj"`.
Mais detalhes em nossa [documentação](/reference/auth/connect-token-create).
### Como realizar a revogação de um consentimento (conexão)?
Para revogar um consentimento, basta deletar o item correspondente via API. Isso encerra a conexão e remove os dados associados.
### Por que o itemId parou de atualizar?
Uma das causas mais comuns é o atingimento do limite de requisições. Isso ocorre quando a mesma conta é conectada diversas vezes, fazendo com que o usuário atinja o limite junto à instituição financeira.
**Limite por CPF/CNPJ**: esse limite é compartilhado entre todos os `itemIds` do mesmo CPF ou CNPJ. Quando atingido, as transações só voltarão a ser atualizadas no **próximo mês**.
### O item atingiu o limite — o que fazer?
Infelizmente não é possível reverter o limite no mês corrente. Para evitar que isso volte a acontecer, evite criar múltiplas conexões para a mesma conta — reutilize sempre o mesmo itemId e atualize-o quando precisar de dados mais recentes.
### É possível listar todos os items que eu já criei na Pluggy?
Sim, com [GET /v2/items](/reference/items-list-by-cursor), filtrando por `clientUserId` ou `connectorId`. O endpoint é **opt-in e vem desabilitado**: listar permite que uma API key enumere todas as suas conexões, por isso ele é habilitado por time mediante solicitação — veja [Contato e suporte](/docs/get-started/contact) — e não pode ser habilitado no plano Free nem em contas de uso pessoal do Meu Pluggy. Até lá ele responde `403` com `LIST_ITEMS_FEATURE_NOT_ENABLED`. Em qualquer caso, o caminho mais seguro é guardar cada `itemId` do seu lado quando o item é criado (o `onSuccess` do widget e o webhook `item/created` trazem esse valor). Veja a página [Item](/docs/connections/item).
### Perdi um itemId. Como encontro de novo?
Guarde cada `itemId` do seu lado quando o item é criado — ele vem no callback `onSuccess` do widget (`item.id`) e no webhook `item/created` (`itemId`), junto com o `clientUserId` que você definiu. Se uma conexão falhar, a tela de erro do widget mostra o id do item como código de erro, para que o seu usuário possa passá-lo a você. Listar items com `GET /v2/items` é opt-in por time — veja a página [Item](/docs/connections/item).
### Uma conta do Meu Pluggy pode ter bancos de titulares diferentes?
Hoje, sim. Isso está em revisão por motivos de compliance e pode ser restringido no futuro (ainda sem data), então não construa um fluxo de produto que dependa disso.
### As novas transações de uma conta são atualizadas em tempo real?
Não. As novas transações de uma conta somente estarão disponíveis para a consulta após uma atualização na conexão. Para mais informações sobre a atualização das contas, consultar nossa [documentação](/docs/connect-widget/updating-item).
Novas transações nos conectores Open Finance (regulado) podem levar até 24h para estarem disponíveis para consulta.
### Como funciona a atualização automática?
A Pluggy sistematiza uma atualização automática para os itemIds. Basta manifestar interesse nos nossos canais de comunicação. É possível escolher um horário de início das atualizações. Os itemIds vão para uma fila e são atualizados de acordo com a capacidade de processamento, para evitar sobrecargas.
## Ambientes e produção
### Como ir para produção?
Para ir para produção, basta criar uma nova aplicação de produção na nossa dashboard, aba de `Aplicações`, clicando em `"Ir para a produção"`.
É importante criar essa aplicação de produção pois, nessa aplicação:
- É disponibilizada atualização automática;
- Não há limite de itemIds;
- Não há acesso a página demo, para que dados sensíveis de clientes não fiquem expostos.
### É possível ter ambientes de Desenvolvimento e Produção separados? Mudaria o client_id/secret?
Sim, é possível criar diferentes ambientes através de nosso [Dashboard](https://dashboard.pluggy.ai/). Quando um novo ambiente é criado, novas credenciais são geradas (`clientId` e `clientSecret`).
O ambiente de **Desenvolvimento** tem limite de criação de **100 items**.
## Webhooks e eventos
### Quais os eventos disponíveis no webhook?
A lista dos eventos disponíveis pode ser consultada [aqui](/docs/developer-tools/webhooks-ref).
## Contato e suporte
Source: https://docs.pluggy.ai/pt/docs/get-started/contact.md
Qual canal se encaixa depende de como você usa o Pluggy.
## Empresas e equipes construindo um produto
Fale com **Vendas**. Eles gerenciam a integração de empresas e clientes em um plano pago e fornecem os pontos de contato em tempo real para sua integração.
- E-mail: **sales@pluggy.ai**
- WhatsApp: [+55 11 91419-2228](https://wa.me/5511914192228)
- Preços e planos: [pluggy.ai/precos](https://www.pluggy.ai/precos)
Este também é o canal para ir para produção, contratar um plano, solicitar um orçamento ou habilitar um recurso de opt-in para sua equipe (por exemplo, [listando itens](/docs/connections/item#searching-and-listing-items)).
## Uso pessoal (suas próprias contas, através do Meu Pluggy)
O uso pessoal passa pelo [Meu Pluggy](https://meu.pluggy.ai) e pelo conector MeuPluggy — o passo a passo é o guia do Meu Pluggy em [meu.pluggy.ai/api-guide](https://meu.pluggy.ai/api-guide). Dúvidas sobre isso são respondidas pela comunidade no **Discord**: [discord.com/invite/EanrwJADby](https://discord.com/invite/EanrwJADby).
## Teste
Uma nova conta do Dashboard começa com um **teste gratuito de 15 dias**, e o Dashboard mostra quantos dias restam. Recursos marcados como recursos de teste (por exemplo, [categorização de transações](/docs/products/transaction-categorization)) estão habilitados durante esse período.
## O que o plano gratuito inclui
O plano gratuito cobre o acesso a dados. **Inteligência de dados** — categorização, enriquecimento, comerciantes, pagamentos recorrentes e outros produtos de insights — faz parte apenas dos planos pagos.
## Excluindo sua conta Pluggy
Source: https://docs.pluggy.ai/pt/docs/get-started/delete-account.md
## Excluindo uma conta de desenvolvedor
Fechar uma **conta de desenvolvedor** — o login que você usa em
[dashboard.pluggy.ai](https://dashboard.pluggy.ai) — não é uma ação de autoatendimento
no Dashboard. Para fechar uma, escreva para nós:
- **E-mail**: [support@pluggy.ai](mailto:support@pluggy.ai), ou
[sales@pluggy.ai](mailto:sales@pluggy.ai) se sua equipe estiver em um plano pago e
a conta estiver vinculada a um contrato.
- Informe-nos o **endereço de e-mail da conta** a ser fechada, desse mesmo endereço
sempre que possível, para que possamos confirmar que é sua.
Outros canais de contato, e qual se encaixa em qual situação, estão em
[Contato e suporte](/docs/get-started/contact).
Excluir um **Item** remove a conexão bancária de um usuário final e seus dados, e você
pode fazer isso você mesmo a qualquer momento com
[`DELETE /items/{id}`](/reference/items-delete) — veja
[Ciclo de vida do Item](/docs/connections/item-lifecycle#data-retention-and-automatic-cleanup).
Excluir sua **conta** diz respeito ao seu próprio login do Pluggy e às aplicações que ela
possui.
## O que o fechamento da conta remove
- **Todas as aplicações que você possui**, juntamente com suas credenciais de cliente — as chaves da API
dessas aplicações param de funcionar, então qualquer coisa que ainda chame a API com
elas começará a falhar.
- **As equipes onde você é o único membro, ou o último `OWNER` restante.** Se
uma equipe deve sobreviver a você, promova outro membro a `OWNER` **antes** de solicitar
a exclusão, ou a equipe será removida com sua conta.
- **A conta em si.** O endereço de e-mail é liberado, então você pode se inscrever
novamente mais tarde com o mesmo endereço, se precisar.
Se você tiver conexões ativas que deseja remover, exclua esses Itens explicitamente enquanto
ainda tiver chaves da API funcionando. É a maneira limpa de encerrar as conexões, e
revoga o consentimento de Open Finance onde se aplica.
## Solicitações de proteção de dados (LGPD)
Uma solicitação para acessar, corrigir ou apagar **dados pessoais** é um processo diferente
de fechar uma conta, e vai para o Encarregado de Proteção de Dados da Pluggy:
- **E-mail**: [dpo@pluggy.ai](mailto:dpo@pluggy.ai)
- Solicitações de correção, exclusão ou uma cópia dos dados mantidos sobre você podem levar
**até 15 dias**, conforme declarado na
[política de privacidade da Pluggy](https://www.pluggy.ai/legal).
Se você é um **usuário final** — você conectou sua própria conta bancária através de um
produto construído na Pluggy — peça a esse produto para excluir seus dados: ele possui a
conexão, e a Pluggy processa os dados em seu nome. Para contas conectadas
através do [Meu Pluggy](https://meu.pluggy.ai), o canal da comunidade é
[Discord](https://discord.com/invite/EanrwJADby).
## Uma aplicação ou uma por cliente?
Source: https://docs.pluggy.ai/pt/docs/get-started/multi-tenant-applications.md
Se o seu produto atende a muitas empresas — uma plataforma de contabilidade, um ERP, um SaaS onde cada cliente é uma organização separada — você pode dar **a cada inquilino sua própria aplicação de produção**, com seu próprio `client_id` e `client_secret`.
Você também pode executar tudo através de uma única aplicação. Ambas as opções são suportadas, e a escolha é sua.
## O que aplicações separadas oferecem
Cada aplicação é seu próprio limite, então uma por inquilino significa:
- **Credenciais separadas.** Um `client_secret` vazado ou rotacionado afeta um inquilino, não todos eles.
- **Sua própria URL de [webhook](/docs/developer-tools/webhooks-ref)**, para que os eventos cheguem já atribuídos a um inquilino em vez de precisarem ser roteados depois do fato.
- **Sua própria [personalização do Pluggy Connect](/docs/connect-widget/customization)** — o nome e o logotipo da empresa são definidos na aplicação no Dashboard, para que o titular da conta veja a marca correta ao autorizar seu banco.
- **Um limite de auditoria limpo.** Itens criados sob uma aplicação só são acessíveis com as credenciais daquela aplicação — `GET /items/{id}` com a chave da aplicação errada não retorna o Item de outro inquilino.
[Limites de taxa](/docs/reference/rate-limits) são contados **por endpoint, por IP, por minuto** — explicitamente *não* por conta e não por chave da API. Cada servidor atrás do mesmo IP de saída compartilha um orçamento, não importa quantas aplicações ele autentique. Se você está dividindo em uma aplicação por inquilino para obter mais throughput, isso não funcionará; espalhe o tráfego entre IPs de saída ou ao longo do tempo.
## O que isso não decide
Duas coisas são comerciais em vez de técnicas, e não são a mesma questão de como você organiza as aplicações:
- Se as conexões incluídas no seu plano são contadas por aplicação ou em toda a conta.
- O que uma segunda, terceira ou quinquagésima aplicação de produção implica para o seu contrato.
Essas questões pertencem ao Vendas — [sales@pluggy.ai](mailto:sales@pluggy.ai) ou no WhatsApp na [página de preços](https://www.pluggy.ai/precos). Pergunte antes de construir o layout em torno de uma suposição.
## O consentimento permanece com o titular da conta
Qualquer que seja o layout que você escolher, a pessoa que autoriza a conexão bancária é o **titular da conta**, no ambiente do seu próprio banco. Isso não muda porque seu cliente é uma empresa que atende outras empresas: uma firma de contabilidade não pode autorizar em nome da empresa cujos dados ela lê. Cada titular de conta conecta sua própria instituição através do Pluggy Connect, e o [Item](/docs/connections/item-lifecycle) resultante pertence à aplicação sob a qual a conexão foi criada.
## Integração com Slack
Source: https://docs.pluggy.ai/pt/docs/integrations/slack.md
## Visão Geral
Pluggy executa um **bot público hospedado no Slack** que responde perguntas da documentação ao vivo do Pluggy diretamente no Slack. Adicione-o ao seu espaço de trabalho e sua equipe pode perguntar sobre a API, procurar informações e obter respostas com links para a documentação — sem sair do Slack e sem precisar construir nada.
Assim como o [servidor MCP](/docs/developer-tools/mcp), o bot é **hospedado pelo Pluggy**: não há aplicativo Slack para criar, nem escopos OAuth para configurar, nem URLs de solicitação, e nem variáveis de ambiente. Você o adiciona e o utiliza.
## Adicione o bot ao seu espaço de trabalho
Clique em **Adicionar ao Slack** e aprove a instalação para o seu espaço de trabalho (você precisará de permissão de administrador do espaço de trabalho para instalar aplicativos):
Esse é todo o processo de configuração. Uma vez instalado, convide o bot para qualquer canal onde você deseja usá-lo.
## Use-o
- **Mencione-o** em um canal onde ele está:
```
@Pluggy Docs como eu crio um connect token e abro o Connect Widget?
```
- **Envie uma mensagem direta** com uma pergunta — nenhum comando necessário:
```
Quais escopos o Connect Widget precisa?
```
O bot responde com uma resposta concisa baseada na documentação do Pluggy, com links para os guias relevantes.
## O que ele pode acessar (hoje)
Por enquanto, o bot responde apenas da **documentação pública** do Pluggy — o mesmo conteúdo disponível em [v2.docs.pluggy.ai](https://v2.docs.pluggy.ai): guias, referência da API, changelog, receitas e perguntas e respostas curadas. Ele **não** acessa sua conta Pluggy, aplicativos ou dados.
Assim como o servidor MCP, o bot permitirá opcionalmente que você **faça login com sua conta do dashboard do Pluggy** e mantenha uma sessão, para que ele possa responder perguntas específicas da **sua equipe** — seus aplicativos, itens e uso. Até você fazer login — e hoje, na v0 — ele permanece na **documentação pública**.
## Privacidade
O bot apenas lê as mensagens que o mencionam ou que você envia por DM, usa essas mensagens para pesquisar na documentação e responde. Ele não armazena seus dados do Slack.
## Solução de Problemas
- **O bot não responde** — certifique-se de que ele foi **convidado para o canal** (menções só funcionam onde o bot é um membro), ou tente uma mensagem direta.
- **"Adicionar ao Slack" não instalou** — você precisa de permissão de **administrador do espaço de trabalho** para adicionar aplicativos; peça ao seu administrador do Slack para executar a instalação.
- **As respostas parecem erradas ou desatualizadas** — o bot responde com base na documentação pública ao vivo; se algo estiver errado na própria documentação, avise a equipe do Pluggy.
## Sandbox
Source: https://docs.pluggy.ai/pt/docs/guides/sandbox.md
Usando nosso ambiente de produção, você pode acessar conectores `Live` e `Sandbox`. Para fins de teste, você pode experimentar sua integração usando nosso **conector Sandbox** (que representa nosso ambiente `Sandbox`). Isso permitirá que você veja como as transações se atualizam ao longo do tempo e teste todas as possíveis conexões válidas e fluxos errôneos. As transações do Sandbox são atualizadas semanalmente e podem também mudar diariamente, portanto, o ambiente não é estático.
Todos os itens do sandbox que não forem atualizados por mais de **30 dias** serão excluídos sem possibilidade de recuperação no futuro.
**Você encontrará diferentes fluxos:**
1. Fluxo básico (também incluímos um fluxo especial da Caixa)
2. Fluxo básico para Negócios
3. MFA 1 etapa
4. MFA 2 etapas
5. Contas conjuntas (fluxo da Bradesco Conta Conjunta)
6. Fluxo de Login QR
7. Fluxo de Open Finance
**Para um fluxo bem-sucedido, as credenciais são:**
- **Senha correta**: `password-ok`
- **Token MFA correto**: `123456`
Cada nome de usuário de teste abaixo mapeia para um status de execução específico. Veja [Ciclo de vida do Item](/docs/connections/item-lifecycle) para a descrição completa dos status de item e execução.
## Estrutura da resposta do Sandbox
O Sandbox (conector Pluggy Bank) retorna dados sintéticos, mas com a mesma estrutura de campo que as respostas de produção. Abaixo está o mapeamento de campos observado em `/accounts`, `/transactions`, `/investments` e `/loans` para um item de teste consultado.
### Contas
```json /accounts
// Sempre retorna pelo menos 1 conta BANCO/CORRENTE e 1 conta CRÉDITO/CARTÃO DE CRÉDITO:
{
"type": "BANK", "subtype": "CHECKING_ACCOUNT",
"balance": 21544.6, "currencyCode": "BRL",
"marketingName": "GOLD Conta Corrente", "taxNumber": "333.333.333-33", "owner": "John Doe",
"bankData": {
"transferNumber": "123/0001/12345-0",
"closingBalance": 21544.6,
"automaticallyInvestedBalance": 2154.46,
"hasReservedBalance": true,
"reservedBalances": [{ "name": "Caixinha Para Férias", "availableAmounts": [{ "amount": 1000.04, "remuneration": { "indexer": "CDI", "rateType": "LINEAR", "preFixedRate": 0.3 } }] }]
},
"creditData": null
}
{
"type": "CREDIT", "subtype": "CREDIT_CARD",
"balance": -503.1,
"creditData": {
"level": "BLACK", "brand": "MASTERCARD",
"balanceCloseDate": "2026-07-23", "balanceDueDate": "2026-07-28",
"creditLimit": 300000, "availableCreditLimit": 300000,
"minimumPayment": 100.62, "holderType": "MAIN", "status": "ACTIVE"
}
}
// Note que bankData/creditData são mutuamente exclusivos dependendo do tipo da conta - o Sandbox até simula reservedBalances ("cofrinhos") dentro de bankData, o que não é trivial encontrar documentado em outro lugar.
```
### Transações
```json /transactions
// Transação simples (recorrente, sem metadados extras) — salário, débitos recorrentes:
{ "description": "SALARIO EMPRESA XYZ LTDA", "amount": 8500, "type": "CREDIT", "category": "Salary", "categoryId": "01010000", "paymentData": null,
"creditCardMetadata": null }
// Pagamento de boleto — o único registro com paymentData populado:
{
"description": "Pagamento de boleto", "amount": -100, "type": "DEBIT",
"category": "Transfer - Bank Slip", "categoryId": "05010000",
"paymentData": {
"payer": { "documentNumber": { "type": "CPF", "value": "111.111.111-11" }, "name": "Francisco Souza", "routingNumberISPB": "60701190" },
"paymentMethod": "BOLETO",
"receiver": { "documentNumber": { "type": "CNPJ", "value": "PL.UGG.Y12/AB00-42" }, "name": "Pluggy Brasil Instituição de Pagamento LTDA" },
"boletoMetadata": { "baseAmount": 90, "discountAmount": 0, "interestAmount": 10, "digitableLine": "11190000111001113911100000021110600000000111000" }
}
}
// Compra parcelada no cartão de crédito — o único registro com creditCardMetadata populado:
{
"description": "NETFLIX.COM", "amount": -55.9,
"creditCardMetadata": { "installmentNumber": 2, "totalInstallments": 6, "totalAmount": -335.4, "payeeMCC": 5812, "billId":
"3b3341e4-d30c-48d6-bcbe-79a3fe47d704" }
}
// Em outras palavras: o Sandbox simula pagamentos de boleto e compras parceladas no cartão, mas a conta corrente consultada aqui não possui transferências Pix, TED ou intercontas — todas as 17 transações da conta corrente são: pagamento de boleto, débitos recorrentes (telecomunicações, eletricidade, taxas de condomínio), salário e pagamento de contas. No cartão de crédito, todas as 9 transações são compras (assinaturas/acadêmia), sem exemplos de disputa, reembolso ou adiantamento em dinheiro.
```
### Investimentos
```json /investments
// 8 investimentos em 6 combinações de tipo/subtipo:
// SECURITY/PGBL — plano de previdência
{
"type": "SECURITY", "subtype": "PGBL", "name": "ITAU Sandbox previdencia",
"balance": 11720.42, "value": 3.605103, "amount": 1720.42,
"lastMonthRate": -0.8, "lastTwelveMonthsRate": 5.97, "annualRate": 7.64,
"issuer": "ITAU UNIBANCO ASSET MANAGEMENT LTDA", "issuerCNPJ": "40.430.971/0001-96"
}
// SECURITY/RETIREMENT — plano de previdência emitido pela própria Pluggy
{
"type": "SECURITY", "subtype": "RETIREMENT", "name": "Pluggy PREVIDENCIA",
"balance": 1359.39, "amountProfit": 359.39, "amountOriginal": 1000,
"issuer": "Banco do Pluggy", "dueDate": "2026-07-23T16:16:27.300Z"
}
// MUTUAL_FUND/INVESTMENT_FUND — aparece duas vezes (Premium/Básico)
{
"type": "MUTUAL_FUND", "subtype": "INVESTMENT_FUND", "name": "Fondo de Investimento Premium",
"balance": 1359.39, "quantity": 3, "value": 500, "amount": 1500,
"taxes": 40.61, "taxes2": 100, "amountProfit": 359.39, "amountOriginal": 1000
}
// FIXED_INCOME/CDB — título de renda fixa
{
"type": "FIXED_INCOME", "subtype": "CDB", "name": "CDR",
"balance": 2000, "rate": 150, "rateType": "CDI", "fixedAnnualRate": 2.5,
"dueDate": "2026-07-23T16:16:27.300Z", "issuer": "Banco do Pluggy",
"institution": { "name": "BANCO BTG PACTUAL S/A", "number": "30306294000145" }
}
// ETF/ETF — aparece duas vezes: uma ativa, uma totalmente retirada
{
"type": "ETF", "subtype": "ETF", "name": "ISUS11 STOCK", "code": "ISUS11", "isin": "123456789",
"quantity": 1, "amount": 2000, "status": "ACTIVE"
}
{
"type": "ETF", "subtype": "ETF", "name": "BOVA11", "code": "BOVA11",
"quantity": 0, "value": 118.4, "status": "TOTAL_WITHDRAWAL"
}
// EQUITY/REAL_ESTATE_FUND — REIT (FII)
{
"type": "EQUITY", "subtype": "REAL_ESTATE_FUND", "name": "GGRC11", "code": "GGRC11", "isin": "BRGGRCCTF002",
"quantity": 1, "amount": 118.4, "issuer": "GGR COVEPI RENDA FDO INV IMOB"
}
// Nenhum exemplo de SECURITY/ação individual (equidade mantida fora de um fundo), e nada explicitamente
// rotulado como Tesouro Direto — o mais próximo disponível é o FIXED_INCOME/CDB acima.
```
### Empréstimos
```json /loans
{
"productName": "Crédito Pessoal Consignado",
"type": "CREDITO_PESSOAL_COM_CONSIGNACAO",
"kind": "LOAN",
"contractAmount": 50000, "currencyCode": "BRL",
"contractDate": "2022-08-01T00:00:00.000Z", "dueDate": "2028-01-15T00:00:00.000Z",
"installmentPeriodicity": "MONTHLY", "amortizationScheduled": "SAC", "CET": 0.29,
"interestRates": [{ "interestRateType": "SIMPLE", "postFixedRate": 0.55, "preFixedRate": 0.6, "referentialRateIndexerSubType": "TJLP" }],
"installments": { "dueInstallments": 57, "paidInstallments": 73, "pastDueInstallments": 73, "totalNumberOfInstallments": 130632 },
"payments": { "contractOutstandingBalance": 1000.04 }
}
// Apenas um tipo/kind de empréstimo é simulado: crédito pessoal consignado. Nenhum financiamento de imóvel, veículo ou empréstimo pessoal sem consignação é representado.
```
Os valores acima são exemplos ilustrativos do que o Sandbox pode retornar - eles existem para ajudá-lo a construir contra a estrutura de campo correta. O Sandbox não é destinado a ser usado como um alvo para testes automatizados que afirmam o comportamento específico da Pluggy.
## 1- Fluxos básicos
O fluxo básico também funciona para **conectores de Negócios**.
| Status de execução | Nome de usuário | Descrição |
|---|---|---|
| `SUCCESS` | `user-ok` | Conexão bem-sucedida. |
| `ALREADY_LOGGED_IN` | `user-logged` | O usuário já possui uma sessão de login aberta (precisa sair manualmente). |
| `ACCOUNT_LOCKED` | `user-locked` | A conta do usuário está bloqueada, precisa de ação manual para ser desbloqueada. |
| `UNEXPECTED_ERROR` | `user-error` | O conector teve um erro aleatório. |
| `SITE_NOT_AVAILABLE` | `user-unavailable` | O site do provedor não estava disponível. |
| `ACCOUNT_NEEDS_ACTION` | `user-account-need-actions` | O provedor está solicitando alguma ação manual do usuário (ou seja, aceitar novos termos de uso). |
| `ACCOUNT_NEEDS_ACTION` + `providerMessage` | `user-account-need-actions-provider-message` | O provedor está solicitando alguma ação manual do usuário, incluindo instruções para resolver isso no campo de erro do item `providerMessage`. |
| `CONNECTION_ERROR` | `user-connection-error` | Houve um erro de conexão interno com o provedor (ou seja, problema de Proxy). |
| `INVALID_CREDENTIALS` | qualquer outra coisa | As credenciais de usuário/senha eram inválidas. |
| `PARTIAL_SUCCESS` | `user-ok-account-error` | Erro ao recuperar o produto da conta. |
| `SUCCESS` com avisos | `user-ok-account-warning` | Aviso no produto da conta. |
| `ACCOUNT_CREDENTIALS_RESET` | `user-account-credentials-reset` | O usuário precisa atualizar algumas de suas credenciais na instituição. |
| `USER_NOT_SUPPORTED` | `user-not-supported` | O usuário não está autorizado a realizar login na instituição através da Pluggy. |
| `SUCCESS` com dados de duas contas correntes | `user-ok-two-checking-accounts` | Sucesso, mas retorna um exemplo de duas contas correntes. |
### Ampliar dados de resultado
Nos casos em que é necessário testar grandes quantidades de transações no resultado, você pode usar o nome de usuário `user-ok-perf` ou `user-ok-perf-XXx` para recriar essa situação. `XX` representa o multiplicador para o número de transações a serem recuperadas. Por exemplo, se você escolher 1000 como XX, o nome de usuário resultante seria `user-ok-perf-1000x`, a fim de multiplicar o resultado por esse número.
O limite desse multiplicador é 5000, então se você usar um número maior, o multiplicador será apenas 5000.
### Fluxo Básico | Status de Autorização Pendente (fluxo da Caixa)
Este é um caso especial que emula o fluxo da Caixa. Consiste em três possíveis status de execução a serem retornados.
Quando um usuário se conecta pela primeira vez, a execução esperada retornada será para confirmar o dispositivo do usuário mostrado (ou seja, "1234-5678").
Assim, a primeira execução (após o usuário confirmar o dispositivo do lado dele) retornará `USER_AUTHORIZATION_PENDING` e uma mensagem que informa o tempo que o usuário deve esperar até que a autorização seja concedida pela Caixa.
Uma vez que essa etapa é concluída, existem dois cenários possíveis:
1. Se o usuário atualizar o item dentro do tempo a ser aguardado, o resultado da execução será `USER_AUTHORIZATION_NOT_GRANTED` e uma mensagem para lembrar o tempo a ser aguardado até que a autorização seja concedida pela Caixa (no caso do Sandbox, o tempo é de 2 minutos).
2. Se o usuário atualizar o item após o tempo de espera, os dados da conta serão recuperados com sucesso e o relatório de execução será `SUCCESS`.
Veja a tabela abaixo para mais detalhes:
| Status de execução | Nome de usuário | Descrição |
|---|---|---|
| `USER_AUTHORIZATION_PENDING` | `user-ok-auth-pending` | Isso reportará um status `USER_AUTHORIZATION_PENDING`, e uma mensagem para esperar 2 minutos até que a instituição conceda autorização. Então, você pode atualizar o item para recuperar os dados após esses 2 minutos, ou obter uma mensagem de autorização ainda não concedida (por favor, leia as próximas linhas). |
| `USER_AUTHORIZATION_NOT_GRANTED` | reutilizar credenciais (atualizar) | Se o item for atualizado antes que a instituição conceda autorização, o status reportado será `USER_AUTHORIZATION_NOT_GRANTED` e você será solicitado a esperar novamente os 2 minutos após a primeira execução. |
| `SUCCESS` | reutilizar credenciais (atualizar) | Se o item for atualizado uma vez que a autorização da instituição for concluída, então os dados devem ser recuperados e o relatório de status será `SUCCESS`. |
## 3- MFA 1 etapa
| Cenário | Nome de usuário | MFA | Descrição |
|---|---|---|---|
| Login Ok | `user-ok` | `123456` | Conexão bem-sucedida. |
| `INVALID_CREDENTIALS_MFA` | `user-ok` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. |
## 4- MFA 2 etapas
| Cenário | Nome de usuário | MFA | Descrição |
|---|---|---|---|
| Login Ok | `user-ok` | `123456` | Conexão bem-sucedida. |
| `INVALID_CREDENTIALS_MFA` | `user-ok` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. |
| Login Ok (MFA com imagem QR) | `user-ok-img` | `123456` | Conexão bem-sucedida. |
| `INVALID_CREDENTIALS_MFA` (MFA com imagem QR) | `user-ok-img` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. |
| Login Ok (MFA com opções para selecionar) | `user-ok-select` | qualquer | Conexão bem-sucedida. |
| Login OK (com seleção de telefone antes do MFA) | `user-ok-phone` | `123456` | Conexão bem-sucedida. |
| `INVALID_CREDENTIALS_MFA` (com seleção de telefone antes do MFA) | `user-ok-phone` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. |
| Login Ok (com seleção de empresa após o MFA) | `user-ok-multi-company` | `123456` | Conexão bem-sucedida. |
| `INVALID_CREDENTIALS_MFA` | `user-ok-multi-company` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. |
| `UNEXPECTED_ERROR` | `user-ok-mfa-error` | `123456` | O conector teve um erro aleatório. |
| `ACCOUNT_LOCKED` | `user-ok-mfa-locked` | `123456` | A conta do usuário está bloqueada, precisa de ação manual para ser desbloqueada. |
| `SITE_NOT_AVAILABLE` | `user-ok-mfa-unavailable` | `123456` | O site do provedor não estava disponível. |
| `CONNECTION_ERROR` | `user-ok-mfa-connection-error` | `123456` | Houve um erro de conexão interno com o provedor (ou seja, problema de Proxy). |
| `ALREADY_LOGGED_IN` | `user-ok-mfa-logged` | `123456` | O usuário já possui uma sessão de login aberta (precisa sair manualmente). |
| `ACCOUNT_NEEDS_ACTION` | `user-ok-mfa-account-need-actions` | `123456` | O provedor está solicitando alguma ação manual do usuário (ou seja, aceitar novos termos de uso). |
## 5- Contas Conjuntas (fluxo da Bradesco Conta Conjunta)
Este é um caso especial que emula o fluxo da Bradesco Conta Conjunta.
**Abaixo você encontrará dois exemplos:**
1. Testando no widget Pluggy Connect
2. Testando via Postman
### 1- Testando no widget Pluggy Connect
Ao usar o [widget Pluggy Connect](/docs/connect-widget/introduction), o usuário será apresentado para escolher primeiro entre uma "Conta única" ou uma "Conta conjunta".
- Se o usuário selecionar **"Conta única"**, será solicitado que forneça as credenciais bancárias e MFA na mesma etapa que as credenciais.
- Se o usuário selecionar **"Conta conjunta"**, será solicitado apenas as credenciais bancárias. Em seguida, será perguntado qual conta deseja conectar, e depois disso, o MFA será necessário. Se o MFA estiver correto, a conta será conectada com sucesso.
### 2- Testando via Postman
- Ao testar "conta única", a solicitação é a mesma que a MFA 1 etapa do sandbox. As credenciais bancárias e o MFA são enviados juntos.
- Ao testar "conta conjunta", você deve incluir um parâmetro de MFA 1 etapa, com o valor simulado: `000000`.
Note que isso é o mesmo que o fluxo do widget Connect. Quando o usuário seleciona o fluxo "conta conjunta", a interface não está pedindo para completar o parâmetro MFA.
## 6- Fluxo de Login QR
Este é um caso que originalmente simula um fluxo semelhante ao QR do Inter. Nenhuma credencial é necessária. Uma vez iniciado, o item entrará em um status `WAITING_USER_ACTION` e retornará um código QR para o usuário escanear.
Esse fluxo simulará um código QR em rápida mudança por 10 segundos e, em seguida, simulará o usuário lendo o QR e avançando o estado para um fluxo de login normal.
## 7- Fluxo de Open Finance
Para se conectar usando nossa conexão sandbox (veja [Criando um item de Open Finance](/docs/open-finance/creating-item)), você precisará enviar um CPF:
| Cenário | CPF |
|---|---|
| Fluxo básico | 761.092.776-73 |
| Fluxo de autorização múltipla - aprovado | 238.242.640-30 |
| Fluxo de autorização múltipla - rejeitado | 051.177.670-55 |
| Fluxo básico - com autenticação lenta | 002.502.737-99 |
| Fluxo básico - forçar erro ao obter recursos OF | 163.511.711-99 |
Isso o redirecionará para a página de login do banco simulado. Por favor, use as seguintes credenciais:
- Usuário: `user-ok`
- Senha: `password-ok`
### Como funciona o fluxo de autorização múltipla (múltipla alçada)?
Esse fluxo simula um cenário onde, para recuperar dados da conta, o item deve ser aprovado por outra pessoa (normalmente outro associado da empresa). Para testar esse cenário, siga estas etapas:
1. Crie um item sandbox usando um dos CPFs listados na tabela acima. O item não retornará contas imediatamente. Em vez disso, o campo `statusDetail` indicará que as contas requerem autorização.
2. Atualize esse item. Dependendo do CPF que você forneceu, as contas podem ou não ser retornadas.
## Testando pagamentos e boletos
A iniciação de pagamentos e boletos têm suas próprias instituições sandbox. Para PIX, crie a Solicitação de Pagamento com `isSandbox: true`; uma solicitação sandbox aceita apenas conectores sandbox, e uma solicitação ao vivo aceita apenas conectores ao vivo. A página de consentimento do banco sandbox solicita `user-ok` / `password-ok`. Boletos não têm Solicitação de Pagamento: crie uma conexão de boleto com o conector sandbox `8` em vez disso.
| Tipo de pagamento | Conector | Entradas necessárias | Como é concluído no sandbox | Webhooks |
|---|---|---|---|---|
| PIX (imediato) | `600` | Intenção de pagamento `parameters.cpf`: `76109277673` | Dentro de segundos após aprovar o `consentUrl` | `payment_intent/created`, `payment_intent/completed`, `payment_request/updated` |
| PIX Agendado | `600` | Iniciação de pagamento para pagamentos agendados habilitados em sua conta; solicitação de pagamento com um `schedule`; intenção `parameters.cpf`: `76109277673` | No momento do consentimento, como um único pagamento — as datas agendadas não são aguardadas | `payment_intent/created`, `scheduled_payment/completed` |
| Pix Automático | `600` | CNPJ do destinatário; intenção `parameters.cpf`: `76109277673` e `parameters.name` | Um `firstPayment` sem data ou datado para hoje é executado imediatamente após o consentimento, com um `startDate` posterior; um `firstPayment` futuro e pagamentos agendados (D+2 a D+10) são executados às 09:00 UTC na data | `payment_intent/created`, `payment_intent/completed`, `payment_request/updated`, `automatic_pix_payment/created`, `automatic_pix_payment/completed` |
| Boleto | `8` | Uma conexão de boleto com `credentials` vazias; os centavos do `amount` escolhem o cenário | Por si só, um passo a cada 5 minutos | `boleto/updated` |
O PIX agendado usa seu próprio contrato de iniciação de pagamento, portanto, a iniciação de pagamento para pagamentos agendados deve ser habilitada em sua conta, também para testá-lo no sandbox. Sem isso, `POST /payments/intents` retorna `403` com `PAYMENT_INITIATION_NOT_ALLOWED` para uma solicitação de pagamento com um `schedule`, no sandbox também. Entre em contato com o suporte da Pluggy para habilitá-lo.
Um valor de `404.04` faz com que o banco sandbox (`600`) rejeite o pagamento de forma síncrona — `POST /payments/intents` falha para um PIX imediato ou agendado ou um primeiro pagamento do Pix Automático, e a solicitação de agendamento falha para uma cobrança do Pix Automático — assim você pode testar seu tratamento de erros.
Guias passo a passo:
- PIX (imediato): [Testando pagamentos com o banco Sandbox](/docs/payments/overview#testing-payments-with-sandbox-bank)
- PIX Agendado: [Pagamentos Agendados — Testando no sandbox](/docs/payments/scheduled-payments#testing-in-sandbox)
- Pix Automático: [Introdução — Testando no sandbox](/docs/payments/pix-getting-started#10-testing-in-sandbox) e o [tempo de agendamento do sandbox](/docs/payments/pix-scheduler#testing-in-sandbox)
- Boleto: [Testando com o Sandbox](/docs/boleto/sandbox)
## Dashboard: conectores, testar conexões e o itemId
Source: https://docs.pluggy.ai/pt/docs/guides/dashboard-connectors.md
Três coisas que toda integração precisa do [Pluggy Dashboard](https://dashboard.pluggy.ai), com o local exato para clicar. Os mesmos passos funcionam para qualquer conector — um banco, uma instituição de Open Finance, ou o **MeuPluggy** para uso pessoal (veja [Uso pessoal com Meu Pluggy](/docs/guides/meu-pluggy-personal-use)).
## 1. Escolha quais conectores o Pluggy Connect exibe
A seleção de conectores é definida uma vez para sua **equipe** e se aplica ao widget Pluggy Connect de cada aplicação.
1. No menu à esquerda, abra **Customização** (sob *Dados Financeiros*).
2. Vá para a aba **Conectores**.
3. Escolha um modo:
- **Padrão para todos selecionados** — todos os conectores disponíveis são exibidos.
- **Seleção personalizada ativa** — apenas os conectores que você ativar são exibidos.
4. Use a caixa de pesquisa para encontrar um conector pelo nome (por exemplo `MeuPluggy`, `Itaú`, `Nubank`). Os resultados são agrupados por categoria (*Pessoal*, *Negócios*, *Investimento*); abra um grupo e escolha entre suas abas **Conectores OF** e **Direct Connectors** — **MeuPluggy** é um conector Direct (ele possui o selo *Direct*). No modo personalizado, ative o interruptor do conector.
5. Use **Pré-visualização** à direita para abrir o widget real e verificar a lista que seus usuários verão.
O Pluggy Connect sempre precisa de pelo menos um conector selecionado. A marca (nome, logo, cores, texto do botão) está na aba **Geral** da mesma página — veja [Customização](/docs/connect-widget/customization).
## 2. Conectar uma conta a partir do Dashboard
Você não precisa de um frontend para testar uma conexão: cada aplicação tem uma página **Demo** que abre o Pluggy Connect para você.
1. Abra **Aplicações** e clique na aplicação que você deseja usar (o ícone de engrenagem abre suas configurações).
2. Abra sua página **Demo** e clique em **Conectar Conta**.
3. Escolha a instituição no widget e finalize a conexão. O conector **Sandbox** está sempre listado aqui (pesquise `Sandbox`), então você pode testar com as [credenciais do sandbox](/docs/guides/sandbox) em qualquer plano; o item que ele cria é chamado *Pluggy Bank*.
## 3. Encontre o itemId
Cada conexão cria um **Item**, e seu id — o `itemId` — é o que a API usa para ler dados (`GET /accounts?itemId=…`).
1. Na mesma página **Demo**, a coluna à esquerda **Itens Conectados** lista os itens da aplicação.
2. Clique em um item: seus detalhes mostram o **itemId** com um botão de copiar, além de suas contas, identidade e investimentos.
Na sua própria integração, o `itemId` também chega no callback `onSuccess` do widget e em cada webhook `item/*` — armazene-o quando a conexão for criada. Veja [Item](/docs/connections/item).
## 4. Client ID e Client Secret
1. Abra **Aplicações**. Cada aplicação mostra seu **Client ID**, que você pode copiar a qualquer momento.
2. O **Client Secret** é exibido **apenas uma vez**, quando é gerado: quando você cria a aplicação, ou quando clica em **Gerar novo secret** na página da aplicação. Copie-o para o seu gerenciador de segredos imediatamente — o diálogo só fecha após você confirmar que o armazenou.
3. Troque ambos por uma chave de API com `POST /auth` (veja [Autenticação](/docs/authentication)).
Depois que esse diálogo é fechado, o Client Secret não está disponível em nenhum lugar — nem no Dashboard e nem através da API. Se você perdê-lo, clique em **Gerar novo secret** na página da aplicação. O secret anterior para de funcionar imediatamente, então atualize toda integração que o utiliza.
Apenas **Owners** e **Admins** da equipe podem gerar um novo secret. Quando uma aplicação é movida para produção, seu secret é rotacionado e o Dashboard exibe um aviso pedindo a um Owner ou Admin para gerar um novo.
## Perguntas comuns
- **"O conector que eu quero não está no widget."** Verifique a aba **Conectores**: no modo personalizado, apenas conectores ativados aparecem.
- **"Eu quero dados reais (de produção)."** As empresas solicitam isso com **Liberar dados reais** na aplicação (isso leva a Vendas e due diligence). Para **uso pessoal**, escolha essa opção e você será direcionado para [Meu Pluggy](/docs/guides/meu-pluggy-personal-use), que é gratuito.
## Uso pessoal: leia seus próprios dados com Meu Pluggy
Source: https://docs.pluggy.ai/pt/docs/guides/meu-pluggy-personal-use.md
Se você é uma pessoa que deseja ler **suas próprias** contas bancárias com código — um script de finanças pessoais, uma planilha, um aplicativo que só você usa — o caminho é **Meu Pluggy** mais o **conector MeuPluggy**. É gratuito, não precisa de diligência prévia e não expira com o teste. É apenas para uso pessoal (até 5 conexões, sem uso comercial).
Empresas que estão construindo um produto para seus usuários seguem a integração regular em vez disso ([Início Rápido](/docs/quickstart)) e falam com [Vendas](/docs/get-started/contact).
O guia oficial do Meu Pluggy está em [meu.pluggy.ai/api-guide](https://meu.pluggy.ai/api-guide). Esta página mostra os mesmos quatro passos com as telas do Dashboard do Pluggy.
## Passo 1 — Conecte seus bancos no Meu Pluggy
Inscreva-se em [meu.pluggy.ai](https://meu.pluggy.ai) e conecte seus bancos lá. É aqui que cada banco é autorizado (CPF, o aplicativo do banco, aprovação). **Cada banco é autorizado separadamente**, e um banco que você adicionar depois precisa de sua própria autorização.
## Passo 2 — Adicione o conector MeuPluggy no Dashboard
1. Faça login no [Dashboard do Pluggy](https://dashboard.pluggy.ai) **com a mesma conta** que você usa no Meu Pluggy.
2. Se você usar uma seleção de conector personalizada, certifique-se de que **MeuPluggy** esteja ativado: **Customização → Conectores**, pesquise `MeuPluggy` e abra a aba **Direct Connectors** do grupo *Pessoal* ([como](/docs/guides/dashboard-connectors#1-choose-which-connectors-pluggy-connect-shows)).
3. Abra **Aplicações → seu aplicativo → Demo** e clique em **Conectar Conta**.
4. No widget, escolha **MeuPluggy** — não seu banco, e não o Sandbox — e faça login com sua conta do Meu Pluggy.
Cada banco que você conectou no Meu Pluggy se torna um **item** nesta aplicação. Esses itens refletem a conexão do Meu Pluggy: eles refletem cada atualização automaticamente (Meu Pluggy atualiza a cada 24 horas), não podem ser atualizados manualmente e enviam webhooks como qualquer item.
Se o Dashboard pedir seu CPF e uma aprovação bancária novamente, você escolheu o conector próprio do banco em vez de **MeuPluggy**. Volte e escolha MeuPluggy.
## Passo 3 — Copie o itemId e suas credenciais
- **itemId:** na mesma página **Demo**, clique no item em **Itens Conectados** e copie seu id ([como](/docs/guides/dashboard-connectors#3-find-the-itemid)). Guarde-o — `GET /v2/items` não está disponível para contas do Meu Pluggy.
- **Client ID / Client Secret:** o Client ID está em **Aplicações**, na linha do seu aplicativo. O Client Secret é mostrado apenas uma vez, quando é gerado — se você não o armazenou, gere um novo na página do aplicativo ([como](/docs/guides/dashboard-connectors#4-client-id-and-client-secret)).
## Passo 4 — Leia seus dados
```bash
# 1. Troque suas credenciais por uma chave de API
curl -X POST https://api.pluggy.ai/auth \
-H "Content-Type: application/json" \
-d '{"clientId": "", "clientSecret": ""}'
# → { "apiKey": "..." }
# 2. Liste as contas de uma conexão
curl "https://api.pluggy.ai/accounts?itemId=" \
-H "X-API-KEY: "
# 3. Transações de uma conta (seu id vem do passo 2)
curl "https://api.pluggy.ai/transactions?accountId=" \
-H "X-API-KEY: "
```
Os SDKs ([Node, Python e mais](/docs/developer-tools/server-sdks)) fazem as mesmas chamadas.
## A autorização expira após um ano
Quando você faz login no Meu Pluggy no Passo 2, você autoriza seu aplicativo a ler as conexões que você tem lá. Essa autorização é o que os itens MeuPluggy leem, e **dura um ano** a partir do momento em que você a concede. Cada conexão bancária dentro do Meu Pluggy mantém seu próprio consentimento com o banco; esta é separada e fica acima delas.
Você pode ver quando termina no próprio item: [GET /items/\{id\}](/reference/items-retrieve) retorna isso como `consentExpiresAt`.
### O que acontece quando expira
- **As leituras param.** Contas, transações e as outras listas desse item voltam vazias.
- **A próxima atualização falha com um erro de login.** O item muda para `LOGIN_ERROR` com o código `USER_AUTHORIZATION_EXPIRED`, e o webhook `item/error` é acionado. Se você escuta webhooks, esse é seu sinal.
Até que essa próxima atualização ocorra, o item ainda pode mostrar seu último status — `UPDATED`, sem erro — enquanto as leituras voltam vazias. Verifique `consentExpiresAt`: uma leitura vazia com uma data passada significa que a autorização expirou, não que suas conexões bancárias pararam de sincronizar.
### Como renová-la
Repita o Passo 2: abra **Aplicações → seu aplicativo → Demo**, clique em **Conectar Conta**, escolha **MeuPluggy** e faça login com sua conta do Meu Pluggy. Conceder isso inicia um novo período de um ano.
Uma atualização acionada pela API ou pela sincronização automática não pode renová-la, porque ninguém está lá para fazer login: termina em `USER_AUTHORIZATION_EXPIRED`, como acima.
Após autorizar novamente, verifique em qual item seus dados estão antes de continuar lendo. Se você armazenar transações do seu lado, reconcilie-as por seus próprios ids em vez de assumir que o item manteve seu id.
Excluir sua conta do Meu Pluggy encerra a autorização imediatamente.
## Testando sem dados reais
Para tentar o fluxo sem suas próprias contas, use o conector **Sandbox** com suas [credenciais de teste](/docs/guides/sandbox). Sua conexão do Meu Pluggy é dados reais, nunca um sandbox.
## Perguntas
Dúvidas sobre uso pessoal vão para a comunidade no Discord: [discord.com/invite/EanrwJADby](https://discord.com/invite/EanrwJADby).
## Introdução
Source: https://docs.pluggy.ai/pt/docs/connect-widget/introduction.md
## O que é Pluggy Connect?
Pluggy Connect é um widget que oferecemos para ajudar você a começar rapidamente com Pluggy. Seus usuários o usarão para conectar suas contas, dentro do seu aplicativo, diretamente à API Pluggy.
O Connect Widget é a solução frontend plug & play da Pluggy que permite aos usuários conectar suas contas financeiras em um fluxo passo a passo, para que você só precise se preocupar em interagir com os dados deles, em vez de se preocupar com fluxos de login complicados.
Durante o processo de conexão, o widget gerencia:
- Validação de credenciais
- Autenticação multifatorial (MFA)
- Gerenciamento de erros
## Como Funciona
A integração típica segue estas etapas principais:
1. **Configuração do Token de Backend**: Primeiro, você precisará configurar um endpoint no seu backend que obtenha e forneça um **Connect Token**. Este token concede autorização ao Pluggy Connect para acessar a API Pluggy em nome da sua aplicação. Este processo deve ser feito no seu backend, já que o endpoint requer autenticação usando o `CLIENT_ID` e `CLIENT_SECRET` da sua aplicação.
2. **Integração Frontend**: Com seu endpoint de Connect Token implantado, você está pronto para integrar o Pluggy Connect em sua aplicação do lado do cliente. Existem exemplos de frontend totalmente funcionais que você pode clonar e começar a usar imediatamente para lançar a interface do Pluggy Connect, substituindo a URL do endpoint do Connect Token pela sua própria.
3. **Conexão do Usuário**: Quando seu usuário clica em "Conectar minha conta", um Connect Token é obtido e o Connect Widget é instanciado com esse token e abre um modal para o usuário inserir suas credenciais.
4. **Recuperação de Dados**: Assim que o widget termina, ele emite um evento `onSuccess` com o `id` do **Item** recém-criado. Este ID do Item é necessário para qualquer ação futura que você queira realizar com os dados bancários conectados.
## Suporte à Plataforma
Pluggy Connect é uma ferramenta fácil de integrar e rápida de configurar que funciona em todos os navegadores e plataformas, incluindo:
- Web (React, Next.js, JavaScript Puro)
- iOS
- Android
- React Native
- Flutter
- Webviews Móveis
## Callbacks de Evento
O widget suporta vários callbacks para melhorar a experiência do usuário, como redirecionar usuários para uma página de sucesso ou mostrar mensagens de erro. Você pode passar uma função para o widget executar quando um evento acontecer:
- **onSuccess**: Acionado quando a conexão é bem-sucedida. Recebe um objeto contendo os dados do item (por exemplo, `onSuccess={({ item }) => console.log(item.id)}`).
- **onError**: Acionado quando ocorre um erro. Recebe informações de erro e pode acessar os dados do item, se disponíveis (por exemplo, `onError={({ message, data: { item } }) => showErrorPage(message)}`).
- **onClose**: Acionado quando o usuário fecha o modal do widget.
- **onOpen**: Acionado quando o widget é aberto.
- **onEvent**: Trata eventos específicos de interação do usuário, como `LOGIN_SUCCESS`, `LOGIN_MFA_SUCCESS`, `LOGIN_STEP_COMPLETED` e `ITEM_RESPONSE`.
## Suporte a MFA
Pluggy Connect gerencia fluxos de autenticação multifatorial automaticamente. Na primeira vez que um usuário vincula uma conexão MFA, ele recebe um parâmetro extra na lista de credenciais (um parâmetro de uso único). Se você usar o widget Pluggy Connect, não precisará entrar em mais detalhes sobre o fluxo -- a Pluggy já cuidou de tudo para você.
## Começando
Para começar a usar o Pluggy Connect, você precisará:
1. Uma conta Pluggy com `CLIENT_ID` e `CLIENT_SECRET` (disponíveis no [Dashboard](https://dashboard.pluggy.ai))
2. Um endpoint de backend que gera Connect Tokens
3. Uma integração frontend usando um dos SDKs disponíveis
Confira as seções a seguir para mais detalhes sobre [Autenticação](/docs/connect-widget/authentication), [Ambientes e Configurações](/docs/connect-widget/environments), [Atualizando um Item](/docs/connect-widget/updating-item), [Personalização](/docs/connect-widget/customization) e [Suporte a OAuth](/docs/connect-widget/oauth-support).
## Autenticação
Source: https://docs.pluggy.ai/pt/docs/connect-widget/authentication.md
## Visão Geral
Ao conectar-se ao Pluggy a partir de uma aplicação do lado do cliente (ou seja, o Connect Widget), exigimos o uso de um **Connect Token**. O acesso ao Connect Token é limitado apenas aos dados do recurso Item gerado (`GET /items/:id`), e um acesso reduzido aos dados das Contas recuperadas (`GET /accounts?itemId`).
Um Connect Token recém-criado não pode ser usado para acessar informações que foram criadas anteriormente com um Connect Token diferente.
## Connect Token
Um Connect Token é um token de acesso limitado que:
- **Expira em 30 minutos** após a criação
- Destina-se a ser usado por **aplicações frontend** (Web ou Móvel) para autenticar-se com o Pluggy
- É especialmente útil para usuários finais conectarem suas contas através do widget Pluggy Connect
- Tem visibilidade apenas para as conexões que foram criadas usando este token
## Fluxo de Autenticação
Tanto as Chaves da API quanto os Connect Tokens podem ser recuperados usando o `CLIENT_ID` e `CLIENT_SECRET` fornecidos no [Dashboard](https://dashboard.pluggy.ai).
O processo de autenticação funciona da seguinte forma:
### 1. Autenticação do Backend
Primeiro, autentique-se com a API do Pluggy usando seu `CLIENT_ID` e `CLIENT_SECRET` para criar uma Chave da API:
```bash
curl --request POST \
--url https://api.pluggy.ai/auth \
--header 'Content-Type: application/json' \
--data '{
"clientId": "YOUR_CLIENT_ID",
"clientSecret": "YOUR_CLIENT_SECRET"
}'
```
### 2. Criar um Connect Token
Configure um endpoint no seu backend que obtém e fornece um Connect Token, que concede autorização ao Pluggy Connect para acessar a API do Pluggy em nome da sua aplicação:
```bash
curl --request POST \
--url https://api.pluggy.ai/connect_token \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: YOUR_API_KEY' \
--data '{
"options": {
"clientUserId": "your-user-id",
"webhookUrl": "https://www.myapi.com/notifications"
}
}'
```
Ao criar um Connect Token, você pode fornecer algumas `ItemOptions` que serão passadas para todos os itens criados usando o mesmo token:
| Parâmetro | Descrição |
|-----------|-------------|
| `clientUserId` | Um identificador para o usuário na sua aplicação, útil para rastreabilidade |
| `webhookUrl` | URL onde o Pluggy enviará notificações de webhook |
| `oauthRedirectUri` | URI para redirecionar usuários após o processo de OAuth |
| `avoidDuplicates` | Se deve evitar a criação de itens duplicados |
### 3. Integração do Widget Frontend
Use o Connect Token na sua aplicação frontend para inicializar o widget Pluggy Connect:
```javascript
import PluggyConnect from 'pluggy-connect-sdk';
const pluggyConnect = new PluggyConnect({
connectToken: 'your-connect-token',
onSuccess: (itemData) => {
console.log('Conexão bem-sucedida!', itemData);
},
onError: (error) => {
console.error('Erro de conexão:', error);
},
});
pluggyConnect.init();
```
Ou com React:
```jsx
import { PluggyConnect } from 'react-pluggy-connect';
function App() {
return (
console.log(item.id)}
onError={({ message }) => console.error(message)}
/>
);
}
```
## Aviso de Segurança
Não armazene `clientId` e `clientSecret` no frontend. Se essas informações forem visíveis no código da sua página, um atacante pode roubar todos os dados bancários dos seus usuários.
Você precisa criar um endpoint de backend que gera um Connect Token para cada usuário que visita sua página. Este Connect Token tem permissões e duração restritas por razões de segurança.
A arquitetura adequada é:
1. **Backend** gera o Connect Token usando `CLIENT_ID` e `CLIENT_SECRET` (mantidos seguros no servidor)
2. **Frontend** recebe apenas o Connect Token de escopo limitado
3. **Frontend** usa o Connect Token com o Pluggy Connect Widget
## Ambientes e Configurações
Source: https://docs.pluggy.ai/pt/docs/connect-widget/environments.md
Obtenha sua aplicação web rapidamente e sem problemas integrada à nossa plataforma usando nosso Connect Widget!
## Ambientes
O Connect Widget funciona em um único ambiente **Produção**, disponível em:
```
https://connect.pluggy.ai
```
Usando o ambiente de produção, você pode acessar tanto os conectores `Live` quanto os conectores `Sandbox` — não há uma URL de sandbox separada.
### Testes no Sandbox
Para fins de teste, você pode experimentar sua integração usando nossos conectores do **Pluggy Bank** Sandbox. As transações do Pluggy Bank são atualizadas semanalmente e podem também mudar diariamente, portanto, o ambiente não é estático. Ele permite que você teste todos os fluxos de login e cenários que você encontraria ao usar qualquer um dos conectores Live disponíveis.
Para exibir conectores Sandbox na etapa de seleção de Conector, defina a propriedade `includeSandbox` como `true` (não destinado para uso em produção). É uma opção do **widget**, passada para `new PluggyConnect(...)` — `POST /connect_token` não possui esse campo. Integrando sem o widget, liste os conectores sandbox com `GET /connectors?sandbox=true`:
```javascript
const pluggyConnect = new PluggyConnect({
connectToken: 'your-connect-token',
includeSandbox: true,
onSuccess: (itemData) => {
console.log('Success!', itemData);
},
});
```
#### Credenciais de teste do Pluggy Bank
Para uma conexão bem-sucedida com o conector Pluggy Bank, use:
| Campo | Valor |
| :-------------------------- | :------------- |
| Usuário | `user-ok` |
| Senha | `password-ok` |
| Token MFA (quando solicitado) | `123456` |
Qualquer outro nome de usuário resultará em um erro `INVALID_CREDENTIALS`. Para a lista completa de usuários de teste cobrindo cenários de erro (conta bloqueada, site não disponível, fluxos de MFA, Open Finance e mais), consulte o [guia do Sandbox](/docs/guides/sandbox).
## SDKs disponíveis
O Connect Widget está atualmente disponível para os seguintes ambientes:
| Plataforma | Pacote / Exemplo |
| :---------------------- | :---------------------------------------------------------------------------------------------------- |
| React | [react-pluggy-connect](https://www.npmjs.com/package/react-pluggy-connect) |
| React Native | [react-native-pluggy-connect](https://www.npmjs.com/package/react-native-pluggy-connect) |
| Flutter | [flutter_pluggy_connect](https://pub.dev/packages/flutter_pluggy_connect) |
| JavaScript Vanilla | [pluggy-connect-sdk](https://www.npmjs.com/package/pluggy-connect-sdk) |
| Next.js | [Exemplo de Quickstart](https://github.com/pluggyai/quickstart/tree/master/frontend/nextjs) |
| JavaScript Simples (HTML) | [Exemplo de Quickstart](https://github.com/pluggyai/quickstart/blob/master/frontend/html/index.html) |
Navegue até cada projeto para encontrar informações de uso mais detalhadas em cada README. Você também pode conferir nosso repositório de [Quickstarts](https://github.com/pluggyai/quickstart) para ajudá-lo a começar com sua própria integração.
Deixe-nos saber se você precisa, ou está interessado em contribuir, com uma biblioteca para uma linguagem não representada aqui! Escreva para nós em [hello@pluggy.ai](mailto:hello@pluggy.ai)
## Configurações disponíveis
**Nota:** todos os parâmetros são opcionais, exceto pelo `connectToken`.
| Propriedade | Descrição | Tipo |
| :------- | :---------- | :--- |
| `connectToken` | Seu token Pluggy Connect, que será usado para acessar a API. | `string` |
| `includeSandbox` | Se deve exibir conectores Sandbox na etapa de seleção de Conector (não destinado para uso em produção). | `boolean` |
| `allowConnectInBackground` | Se `true`, o Connect pode ser minimizado pelo usuário para continuar a conexão com o componente oculto. | `boolean` |
| `allowFullscreen` | Se definido como `false`, o Connect não será exibido em tela cheia em telas pequenas/móveis; será exibido como um modal. O padrão é `true`. | `boolean` |
| `updateItem` | ID do Item a ser atualizado. Se especificado, o widget exibirá diretamente o formulário de credenciais do Item a ser atualizado. | `string` |
| `selectedConnectorId` | Se especificado, e o Conector estiver disponível, após aceitar os termos, o widget navegará diretamente para o formulário de login deste Conector, pulando a etapa de seleção de conector. | `number` |
| `connectorTypes` | Lista de Tipos de Conector. Se definido, apenas Conectores dos tipos de conector especificados (`PERSONAL_BANK`, `BUSINESS_BANK`, etc.) serão listados. Útil para casos de diferentes fluxos para usuários PF ou PJ. | `ConnectorType[]` |
| `connectorIds` | Lista de IDs de Conector. Se definido, apenas Conectores com os IDs de conector especificados serão listados. | `number[]` |
| `countries` | Lista de códigos de países (formato ISO-3166-1 alpha-2). Se definido, apenas Conectores dos países especificados serão listados. | `CountryCode[]` |
| `products` | Se definido, apenas os produtos especificados neste array serão executados na criação do Item (para serem executados, você deve tê-los habilitados na assinatura da sua equipe). **Importante**: os tipos de produtos devem ser especificados em letras maiúsculas (`ACCOUNTS`, `CREDIT_CARDS`, `TRANSACTIONS`, etc.). | `ProductType[]` |
| `language` | String ISO de idioma usada para exibir o widget. Se não especificado, ou se o idioma selecionado não for suportado, o idioma padrão `'pt'` será usado. | `string` |
| `theme` | Tema a ser usado para exibir a interface. Pode ser `'light'` ou `'dark'`. O padrão é `'light'`. | `'light' \| 'dark'` |
| `openFinanceParameters` | Objeto com CPF e CNPJ apenas para conectores de Open Finance; o formulário será preenchido automaticamente com esses valores. Contém campos de string opcionais `cpf` e `cnpj`. | `{ cpf?: string; cnpj?: string }` |
| `forceOauthInBrowser` | Se definido como `true`, as URLs de OAuth sempre abrirão no navegador do sistema em vez de em uma webview. Isso ajuda a evitar problemas relacionados à webview. Este prop tem precedência sobre o valor de configuração da API. | `boolean` |
| `forceAskForCredentials` | Se definido como `true`, o widget sempre solicitará credenciais ao atualizar um Item, mesmo que o sistema normalmente tentasse atualizar automaticamente. | `boolean` |
| `onSuccess` | Função a ser executada quando um Item foi criado/atualizado com sucesso. | `(data: { item: Item }) => void \| Promise` |
| `onError` | Função a ser executada em um erro geral ao carregar o widget, ou quando o status de criação/atualização de um Item não foi bem-sucedido. Para validar qual erro ocorreu, verifique `item.executionStatus`. | `(error: { message: string; data?: { item: Item } }) => void \| Promise` |
| `onOpen` | Função a ser executada quando o modal do widget foi aberto. | `() => void \| Promise` |
| `onClose` | Função a ser executada quando o modal do widget foi fechado. | `() => void \| Promise` |
| `onHide` | Função a ser executada quando o modal do widget foi ocultado. Ela só será chamada se a propriedade `allowConnectInBackground` estiver definida como `true`. | `() => void \| Promise` |
| `onEvent` | Função a ser executada para lidar com eventos de interação do usuário personalizados. Veja [onEvent](#onevent) abaixo para mais informações. | **Desde v2.0.0:** `(payload: ConnectEventPayload) => void \| Promise` **Até v1.x:** `(event: string, metadata: { timestamp: number }) => void` |
## onEvent
Use este callback para lidar com eventos específicos de interação do usuário.
A propriedade `event` dentro do `payload` de `onEvent` é o evento atual acionado. Os eventos disponíveis que podem ser tratados por meio deste método são:
| Nome do evento | Descrição |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `'SUBMITTED_CONSENT'` | O usuário confirmou os termos e o consentimento de privacidade na primeira tela de Boas-vindas. |
| `'SELECTED_INSTITUTION'` | O usuário selecionou uma instituição para se conectar. |
| `'SUBMITTED_LOGIN'` | O usuário enviou credenciais para criar o Item de conexão. |
| `'SUBMITTED_MFA'` | O usuário enviou um parâmetro extra que foi solicitado pela instituição para se conectar. |
| `'LOGIN_SUCCESS'` | O usuário enviou credenciais para criar o Item de conexão **com sucesso**. |
| `'LOGIN_MFA_SUCCESS'` | O usuário enviou um parâmetro extra que foi solicitado pela instituição para se conectar **com sucesso**. |
| `'LOGIN_STEP_COMPLETED'` | Conclusão bem-sucedida do login. O usuário efetivamente fez login na instituição. |
| `'ITEM_RESPONSE'` | Chamado toda vez que o objeto Item é recuperado da API Pluggy, seja quando criado, atualizado ou cada vez que é recuperado para verificar seu status de conexão/executação. |
O objeto `payload` tem uma propriedade `timestamp`, e alguns eventos incluem dados extras:
- `'SELECTED_INSTITUTION'` inclui a propriedade `connector`, que é o conector selecionado pelo usuário.
- `'LOGIN_SUCCESS'`, `'LOGIN_MFA_SUCCESS'`, `'LOGIN_STEP_COMPLETED'` e `'ITEM_RESPONSE'` incluem a propriedade `item`, que é os dados do Item relacionados à conexão atual.
Desde a versão 2.0.0 do widget, `onEvent` recebe um único objeto de payload: `(payload: ConnectEventPayload) => void`.
Nas versões 1.x, ele recebia dois argumentos: `(event: string, metadata: { timestamp: number }) => void`.
## Webhooks e callbacks
Após um usuário fazer uma conexão com o Pluggy Connect Widget, existem duas maneiras de obter o ID do Item recém-criado.
### Callbacks do Connect Widget
No frontend da sua aplicação (site, aplicativo, etc.), quando você está usando o Connect Widget, você tem acesso a [callbacks](#available-configurations). Dessa forma, você pode passar uma função para o widget que será executada quando um evento acontecer (por exemplo, uma conta conectada com sucesso ou com erro). O que é importante saber aqui é que os callbacks são usados para melhorar a experiência do usuário, como redirecionar usuários para uma página de sucesso ou mostrar uma mensagem de erro.
```jsx
console.log(item.id)}
onError={({ message, data: { item } }) => showErrorPage(message)}
/>
```
Essa abordagem é ótima para lidar com a lógica do frontend, mas é inconsistente por natureza: você não pode contar com ela para sua lógica de negócios ou integridade do banco de dados. Por exemplo, um usuário pode fechar a aplicação antes que a conexão termine com sucesso, e você nunca perceberá que a conexão foi finalizada. Para ser consistente, use webhooks.
A Caixa Econômica Federal (PF & PJ) possui fluxos de autorização que exigem que o usuário autorize a Pluggy como um dispositivo confiável, e o processo tem um atraso de cerca de 30 minutos.
Nesse cenário, você receberá um `onError` com o status `USER_AUTHORIZATION_PENDING`, e o evento de SUCESSO será comunicado via webhooks.
### Webhooks
Um webhook (também conhecido como callback web) é um método simples que facilita para um aplicativo ou sistema fornecer informações em tempo real sempre que um evento acontece — ou seja, é uma maneira de receber dados passivamente entre dois sistemas através de um `HTTP POST`.
Os webhooks enviarão uma notificação para sua API / backend quando eventos relacionados a conexões acontecerem. Por exemplo, você pode ser notificado quando um Item é criado ou atualizado (leia mais na [referência de Webhooks](/docs/developer-tools/webhooks-ref)).
Você precisará criar um endpoint para ouvir os eventos de webhook da Pluggy e, em seguida, criar um webhook apontando para esse endpoint. Mais detalhes podem ser encontrados na [referência de Webhooks](/docs/developer-tools/webhooks-ref), mas o que é importante entender aqui é que os webhooks são a maneira de obter o ID do Item de uma conexão para que você possa trabalhar. Embora você também possa recuperar o ID do Item com callbacks no frontend, lidar com a lógica de negócios com eles é uma má prática: por exemplo, um usuário fechando o site enquanto faz a conexão resultará na perda do ID do Item daquela conexão, significando que você nunca poderá recuperar os dados do Item.
### Resumo
| | Callbacks | Webhooks |
| :--------------------------- | :--------------------------------- | :------------------------------------------------------------------------ |
| Onde usá-los | Frontend | Backend |
| Como a informação é entregue | Chamadas de função de callback JavaScript | Requisições HTTP POST |
| Propósito | Melhorar a experiência do usuário | Entregar notificações ao seu backend quando eventos relacionados à Pluggy acontecerem |
## Atualizando um Item
Source: https://docs.pluggy.ai/pt/docs/connect-widget/updating-item.md
## Visão Geral
Após criar um Item com sucesso, você pode continuar a coletar dados de produtos que aparecem nos dias seguintes, acionando uma atualização para sua referência de Item existente, em vez de criar um novo Item do zero.
Atualizar um Item existente é mais econômico, pois apenas recupera os dados dos produtos da instituição gerados após o último processo de coleta.
## Como Atualizar um Item
Para atualizar um Item existente usando o Pluggy Connect, siga estas etapas:
### 1. Crie um Connect Token com o ID do Item
Crie um novo Connect Token, especificando o parâmetro `itemId` da conexão do Item correspondente que você deseja atualizar. Isso é necessário para permitir que o Pluggy valide corretamente que você está autorizado a acessar e atualizar este Item específico.
```bash
curl --request POST \
--url https://api.pluggy.ai/connect_token \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: YOUR_API_KEY' \
--data '{
"itemId": "ITEM_ID_TO_UPDATE"
}'
```
### 2. Passe o Connect Token e o ID do Item para o Widget
Passe para o Connect tanto o `connectToken` recém-criado quanto o `id` do Item correspondente através da propriedade `updateItem`:
```javascript
import PluggyConnect from 'pluggy-connect-sdk';
const pluggyConnect = new PluggyConnect({
connectToken: 'your-connect-token',
updateItem: 'ITEM_ID_TO_UPDATE',
onSuccess: (itemData) => {
console.log('Item atualizado com sucesso!', itemData);
},
onError: (error) => {
console.error('Erro na atualização:', error);
},
});
pluggyConnect.init();
```
Ou com React:
```jsx
import { PluggyConnect } from 'react-pluggy-connect';
function UpdateWidget({ connectToken, itemId }) {
return (
console.log('Atualizado!', item.id)}
onError={({ message }) => console.error(message)}
/>
);
}
```
## Comportamento do Widget Durante a Atualização
- Se **não houver mais entrada do usuário necessária**, o Pluggy Connect iniciará automaticamente o processo de atualização.
- Caso contrário, quando **novas credenciais e/ou um parâmetro MFA forem necessários**, o Pluggy Connect solicitará ao usuário que os complete antes que o processo de atualização comece.
Confira um exemplo HTML completo e autônomo em nossa receita: [Atualizar um Item usando Pluggy Connect](/recipes/update-an-item-using-pluggy-connect).
## Quando a Entrada do Usuário é Necessária
Na maioria dos casos, você pode simplesmente iniciar o processo de atualização do Item sem problemas ou mais entradas do usuário. No entanto, existem alguns cenários em que isso não é possível, devido a limitações relacionadas a requisitos de autenticação adicionais da instituição (como um requisito de MFA) ou devido ao Item ter um estado de credenciais inválido que requer nova entrada de credenciais do usuário.
Esses cenários são os seguintes:
- Items que não puderam ser bem-sucedidos devido a um problema com suas credenciais (status do Item: `INVALID_CREDENTIALS`).
- Items que não podem ser sincronizados automaticamente pelo Pluggy em nosso processo de sincronização diário, devido à conexão precisar de uma entrada adicional do usuário, como um parâmetro MFA.
### Caso: INVALID_CREDENTIALS
Isso acontece quando:
- As credenciais fornecidas pelo usuário não estavam corretas, por exemplo, devido a uma entrada incorreta.
- As credenciais estavam corretas, mas quando tentamos sincronizar automaticamente o Item reutilizando as últimas credenciais válidas, encontramos um erro de login inválido.
Para qualquer uma dessas situações, o usuário precisará usar o Pluggy Connect para atualizar este Item e fornecer novas credenciais.
Após isso, se a etapa de login for bem-sucedida, qualquer atualização futura deste Item reutilizará as novas credenciais fornecidas, e nosso processo de sincronização automática voltará a funcionar.
### Caso: Item Não Sincronizável Automaticamente
Este é o caso para instituições que requerem um passo adicional de login MFA.
Nesse cenário, a única opção para que o Item seja atualizado é que o usuário abra o Pluggy Connect configurado para o Item correspondente e resolva o desafio MFA necessário.
Alguns exemplos são:
- XP
- Bradesco
- Easynvest
Você pode encontrar na lista completa de [Conectores](/docs/connections/connectors-coverage) quais requerem um MFA.
Existem algumas instituições que apenas requerem uma verificação inicial ou autorização de dispositivo como um MFA pela primeira vez. Após isso, nenhuma entrada manual adicional é necessária do usuário, então poderemos sincronizar automaticamente esses Items também.
## Forçando a Reentrada de Credenciais com `forceAskForCredentials`
Por padrão, ao atualizar um Item que já está em um estado válido/conectado, o widget pode tentar reexecutar a conexão automaticamente — sem mostrar o formulário de credenciais — uma vez que as credenciais já estão armazenadas.
Definir `forceAskForCredentials: true` substitui esse comportamento e sempre apresenta o formulário de credenciais ao usuário, exigindo que eles reentrem explicitamente suas credenciais antes que a atualização prossiga.
`forceAskForCredentials` só tem um efeito significativo quando `updateItem` também está definido. É destinado exclusivamente para fluxos de atualização de Item, não para a criação de novos Items.
```javascript
pluggyConnect.init({
updateItem: "",
forceAskForCredentials: true,
// ...outras opções
});
```
### Quando Usar Esta Opção
| Cenário | Por que `forceAskForCredentials` ajuda |
|---------|---------------------------------------|
| O usuário mudou sua senha bancária | Garante que a nova senha seja capturada em vez de tentar novamente com credenciais desatualizadas |
| Seu fluxo requer confirmação explícita de credenciais por conformidade ou segurança | Garante que o usuário reentre ativamente as credenciais, criando uma etapa de reautorização intencional |
| Você suspeita que as credenciais armazenadas podem estar desatualizadas | Força uma nova entrada em vez de confiar em uma tentativa de reconexão automática que pode falhar |
### Resumo do Comportamento
| `forceAskForCredentials` | Estado do Item | Comportamento do Widget |
|--------------------------|----------------|-------------------------|
| `false` (padrão) | Válido / conectado | Pode pular o formulário de credenciais e tentar reconexão automaticamente |
| `true` | Válido / conectado | Sempre mostra o formulário de credenciais antes de prosseguir |
| `true` ou `false` | Qualquer | Sem efeito se `updateItem` não estiver definido |
## Limitações ao Atualizar Items Através da API
Quando novos usuários criam equipes e aplicações, esses IDs de cliente têm um limite para atualizar Items diretamente através da API com o endpoint `PATCH /items`: atualizações não podem ser realizadas mais de uma vez por hora.
Essa limitação não afeta atualizações manuais feitas através do widget — não há limitações nesse caso. Além disso, quando você estiver prestes a mover sua aplicação para produção, recomendamos conversar com nossa equipe de suporte para remover essa limitação.
## Atualizações Automáticas
O Pluggy fornece [atualizações automáticas de Items](/docs/connections/item#auto-sync) para aplicações de **Produção**, a cada 24, 12 ou 8 horas, dependendo do seu plano.
## Conclusão e Webhooks
Uma vez que uma atualização foi concluída:
1. O Item muda seu status para `UPDATED`
2. O webhook `item/updated` é acionado
3. Espera-se que os clientes implementem um **processo de sincronização** após o webhook para sincronizar os dados
## Melhores Práticas
- Sempre crie um novo Connect Token com o `itemId` específico antes de acionar uma atualização
- Escute o callback `onSuccess` para confirmar que a atualização foi concluída
- Implemente manipuladores de webhook para processar dados atualizados de forma assíncrona
- Use o evento de webhook `item/updated` para acionar seu processo de sincronização de dados
## Personalização
Source: https://docs.pluggy.ai/pt/docs/connect-widget/customization.md
## Visão Geral
A partir do nosso [Dashboard](https://dashboard.pluggy.ai), é possível personalizar certos aspectos visuais do Pluggy Connect para que você possa oferecer aos seus usuários uma experiência mais personalizada e com a sua marca. Abaixo, listamos e explicamos cada um desses aspectos.
Este recurso está disponível para a **assinatura Pro** e também em nossa **Avaliação Gratuita**.
## Nome da Empresa
Você pode editar o texto incluído na primeira tela que o usuário vê e, assim, destacar o nome da sua empresa. Este campo tem um limite de **20 caracteres**.
O nome da empresa aparece de forma proeminente na tela de boas-vindas do widget Pluggy Connect, proporcionando aos usuários um reconhecimento imediato da sua marca.
## Logo
Você pode adicionar o logotipo da sua empresa para tornar o Pluggy Connect mais alinhado com sua estética. Existem duas maneiras de adicionar seu logotipo:
- **Enviar um arquivo**: Envie um arquivo de imagem diretamente do seu computador
- **Colar uma URL**: Forneça uma URL apontando para a imagem do seu logotipo
O logotipo será exibido nas telas principais do widget, reforçando a identidade da sua marca ao longo do fluxo de conexão.
## Cor Primária
A cor primária, principal da sua marca, dará um toque especial à sua integração com o Pluggy Connect, proporcionando aos seus usuários uma maior sensação de pertencimento.
Você verá a cor primária aplicada em:
- Telas principais
- Botões
- Componentes de UI mais relevantes
- Elementos interativos
Isso ajuda a manter a consistência visual entre sua aplicação e o widget Pluggy Connect.
## Raio de Borda
Você pode editar o **raio de borda** de todos os botões no widget Pluggy Connect. Isso permite que você combine o estilo do botão normalmente usado no sistema de design da sua empresa.
Por exemplo:
- Um raio de borda de `0px` dá aos botões cantos afiados e quadrados
- Um raio de borda maior dá aos botões cantos mais arredondados
## Texto do Botão
Além do raio de borda, o **texto dos botões** pode ser alterado: o da primeira tela e os da tela de credenciais — a redação que uma diretriz de marca geralmente dita, "Continuar" contra "Conectar minha conta".
## Seleção de Conectores
Você pode selecionar os conectores que deseja mostrar no Pluggy Connect. Você os encontrará separados por tipo de conectores, e isso permitirá que você **ative e desative** facilmente.
Você precisa sempre ter pelo menos um conector selecionado.
Os tipos de conectores disponíveis incluem:
- **Bancário Pessoal** - Conectores de contas bancárias pessoais
- **Bancário Empresarial** - Conectores de contas bancárias empresariais e corporativas
- **Investimento** - Conectores de plataformas de investimento
Ao selecionar apenas os conectores relevantes para o seu caso de uso, você pode proporcionar uma experiência mais focada para seus usuários.
## Textos de Consentimento
Os textos de consentimento são o que o usuário lê na primeira tela do Pluggy Connect, sob **Termos e Condições de uso** e **Políticas de Privacidade**.
Estes não são autoatendidos. Para usar os seus, entre em contato com nossa equipe de Vendas: os documentos são lidos e validados primeiro, para verificar se não há conflito com os próprios termos do Pluggy, e o texto aprovado é então incluído na sua integração.
## Aplicando Personalizações
Todas as alterações de personalização são feitas através do [Pluggy Dashboard](https://dashboard.pluggy.ai/customization). As mudanças entram em vigor imediatamente para todas as novas sessões do widget Pluggy Connect.
Para personalizar seu widget:
1. Faça login no [Pluggy Dashboard](https://dashboard.pluggy.ai)
2. Navegue até a seção **Personalização**
3. Atualize os campos desejados (nome da empresa, logotipo, cor primária, raio de borda, texto do botão, conectores)
4. Salve suas alterações
O widget refletirá automaticamente a personalização atualizada para todas as sessões de usuário subsequentes.
## Guia de Suporte ao OAuth
Source: https://docs.pluggy.ai/pt/docs/connect-widget/oauth-support.md
## Visão Geral
Algumas instituições financeiras exigem um fluxo de autorização OAuth para conectar contas de usuários. Este guia explica como configurar corretamente o Pluggy Connect widget para lidar com redirecionamentos OAuth em diferentes plataformas e dispositivos.
Seguindo estas diretrizes, você pode garantir uma experiência de integração OAuth suave para seus usuários em várias plataformas e dispositivos.
### O que o OAuth muda para sua integração
OAuth é um padrão de delegação de acesso: em vez de digitar credenciais em seu
aplicativo, o usuário o autoriza dentro da própria interface da instituição e a
instituição emite um token. Duas coisas decorrem disso, e ambas são o motivo pelo qual esses
conectores precisam de configuração extra do seu lado:
- **O usuário sai do seu aplicativo** — ele se autentica na instituição e
precisa ser trazido de volta. Essa viagem de retorno é para isso que serve o `oauthRedirectUri`.
- **A conexão é renovada sem pedir novamente.** Um token OAuth pode ser renovado,
então a conexão permanece ativa sem enviar o usuário pelo login toda
vez — o que também é o motivo pelo qual essas conexões tendem a quebrar menos do que as baseadas em credenciais.
A única coisa que costuma dar errado é a viagem de retorno. Alguns navegadores móveis não
permitem que a janela de autorização se feche sozinha, e sem um URI de redirecionamento, o usuário fica
encarando uma página de autorização finalizada sem caminho de volta para seu aplicativo.
## Configurando o URI de Redirecionamento OAuth
Para lidar com redirecionamentos após o processo OAuth, você precisa definir um `oauthRedirectUri`. Este URI é usado para redirecionar os usuários de volta ao seu aplicativo após terem concluído o processo OAuth com a instituição financeira.
### Requisitos
O `oauthRedirectUri` deve cumprir as seguintes regras:
- Deve ser **HTTPS** ou um **deep link**
- **Não pode** ser `localhost` ou `127.0.0.1`
### Criando um Connect Token com Redirecionamento OAuth
Ao criar um Connect Token, inclua o `oauthRedirectUri` nas opções:
```bash
curl --request POST \
--url https://api.pluggy.ai/connect_token \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: YOUR_API_KEY' \
--data '{
"options": {
"clientUserId": "your-user-id",
"oauthRedirectUri": "https://your-own-url.com"
}
}'
```
Se você criar um item com um Connect Token e também especificar o `oauthRedirectUri` no momento da criação do item, o sistema priorizará o parâmetro `oauthRedirectUri` fornecido no nível do item.
### Exemplos de URIs de redirecionamento
| URI | Válido | Por quê |
|-----|-------|-----|
| `https://app.example.com/pluggy/callback` | Sim | Página HTTPS em seu aplicativo |
| `myapp://my-deep-link` | Sim | Deep link em um aplicativo nativo |
| `http://app.example.com/callback` | Não | HTTP simples é rejeitado |
| `http://localhost:3000/callback` | Não | `localhost` e `127.0.0.1` são rejeitados |
Testando localmente, use o esquema de deep link do seu aplicativo ou um túnel HTTPS para sua
máquina — um URI `localhost` é recusado quando o token é criado, não depois.
## Comportamento Específico do Navegador
O fluxo OAuth se comporta de maneira diferente dependendo da plataforma do usuário:
### Navegadores de Desktop
Para **navegadores de desktop**, a janela de autorização tentará **fechar automaticamente** após a conclusão do processo OAuth.
Se fechar a janela não for possível, o usuário será redirecionado para o `oauthRedirectUri` fornecido.
### Navegadores Móveis
Para **navegadores móveis**, os usuários serão **redirecionados para o `oauthRedirectUri`** após completar a autorização OAuth.
Alguns navegadores móveis não permitem fechar a janela de autorização OAuth após a conclusão. Para resolver isso, você deve fornecer um `oauthRedirectUri` na solicitação do Connect Token, que será usado para redirecionar os usuários de volta ao seu aplicativo.
## Lidando com o Redirecionamento
Seu aplicativo deve estar preparado para lidar com o redirecionamento de volta para o `oauthRedirectUri`. Quando o usuário for redirecionado, você deve:
1. Verificar o status da conexão
2. Retomar a experiência do usuário em seu aplicativo
3. Lidar com quaisquer erros que possam ter ocorrido durante o processo OAuth
## Considerações sobre a Plataforma
### Aplicativos Web
Para aplicativos web, o `oauthRedirectUri` deve ser um URL HTTPS válido que aponte para uma página em seu aplicativo que possa lidar com o redirecionamento e retomar o fluxo de conexão.
### Aplicativos Móveis (Nativos)
Para aplicativos móveis nativos, você pode usar um **deep link** como o `oauthRedirectUri`. Isso permite que o fluxo OAuth redirecione de volta para seu aplicativo nativo após a autorização ser concluída.
Certifique-se de que seu aplicativo esteja devidamente configurado para lidar com o esquema de deep link tanto no iOS quanto no Android.
### React Native / Flutter
Ao usar React Native ou Flutter com o Pluggy Connect SDK, configure o `oauthRedirectUri` para usar o esquema de deep link do seu aplicativo. O SDK lidará com o redirecionamento e retomará o fluxo de conexão dentro do widget.
## Integração Backend, sem o widget
Criar itens de Open Finance pela API é possível, mas a Pluggy recomenda o Pluggy Connect widget: ele mantém o fluxo de conexão em conformidade com os requisitos de Open Finance e atualizado com as mudanças da instituição, sem trabalho do seu lado.
Se você criar itens a partir do seu próprio backend em vez de através do widget, você não
precisa de um Connect Token: autentique-se com sua chave de API e passe
`oauthRedirectUri` para [items-create](/reference/items/items-create), exatamente como você
faria nas opções do token.
```bash
curl --request POST \
--url https://api.pluggy.ai/items \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: YOUR_API_KEY' \
--data '{
"connectorId": 600,
"parameters": {
"user": "user-ok",
"password": "password-ok"
},
"oauthRedirectUri": "https://your-own-url.com"
}'
```
A URL OAuth para enviar o usuário pode não estar na resposta do `POST /items`: pode
demorar alguns segundos a mais para aparecer. Consulte [GET /items/\{id\}](/reference/items-retrieve)
até que o parâmetro do item do tipo `oauth` carregue a URL. Quando um valor é dado em ambos
os lugares — nas opções do Connect Token e na criação do item — o que está no item
vence, porque é o mais específico dos dois.
## Melhores Práticas
- Sempre forneça um `oauthRedirectUri` quando seus usuários puderem se conectar a instituições que usam OAuth
- Use URLs HTTPS para aplicativos web e deep links para aplicativos móveis nativos
- Teste o fluxo OAuth em navegadores de desktop e móveis para garantir uma experiência suave
- Lide com casos extremos onde a janela de autorização não pode ser fechada automaticamente
- O `connectToken` é válido por **30 minutos apenas** — o uso recomendado é um token por conexão
## Item
Source: https://docs.pluggy.ai/pt/docs/connections/item.md
Como introduzimos [anteriormente](/docs/glossary), um Item é a representação de uma conexão com um Conector específico de uma Instituição e serve como ponto de entrada para acessar o conjunto de produtos recuperados do usuário que deu seu consentimento para coletar seus dados.
## Criando um Item: fluxo de autenticação da Instituição
Para criar um Item, a maneira mais fácil, polida, testada em batalha e menos propensa a erros para um usuário é interagir com nosso [Pluggy Connect Widget](/docs/pluggy-connect-introduction), onde eles podem fornecer consentimento, seguir os passos de autenticação da Instituição e rapidamente ter seus produtos disponíveis em nossa API.
Caso contrário, você pode desenvolver uma aplicação que implemente o fluxo de criação de Item por conta própria, embora isso possa ser uma tarefa assustadora, complexa e difícil de acertar; portanto, não é a escolha preferida que recomendamos.
Quando um Item é criado e a sincronização da instituição é concluída com sucesso, recuperaremos todos os dados dos produtos financeiros mais recentes, de até os últimos 365 dias.
### Acessando os dados coletados do Item
Para acessar os dados dos produtos coletados do Item, você terá que interagir com nossa API usando os endpoints relacionados. Para ajudar a reduzir os tempos de desenvolvimento, fornecemos vários [SDKs do lado do servidor](/docs/server-side-sdks). Se nenhum atender às suas necessidades, por favor, nos avise! Ficaremos felizes em ajudar.
Recomendamos fortemente que, se houver um SDK existente para sua linguagem, você o utilize, pois é totalmente suportado pela nossa equipe de desenvolvimento e à prova de erros.
Se você acabar criando sua própria integração, não forneceremos suporte para essa implementação específica.
### Produtos
Quando *Pluggy* cria um Item, ele coleta automaticamente todos os produtos solicitados como uma execução passo a passo, puxando as informações da FI e armazenando-as em nosso banco de dados. *Por padrão, coletará todos os produtos habilitados na assinatura da sua equipe.*
Ao recuperar um item, você encontrará a lista de produtos habilitados para este item, e poderá especificar esse valor também na criação.
Para personalizar quais produtos você deseja coletar para um `item` específico, você pode enviar o parâmetro `products` (usando o tipo de produto em maiúsculas) ao [criar](/reference/items-create) o `item` (se você integrar através da API) ou na [configuração do widget](/docs/environments-and-configurations#available-configurations) usando a propriedade `products`.
Em um item de Open Finance, o que você pediu e o que a instituição realmente compartilha são duas listas diferentes. [`GET /items/{id}/resources`](/docs/connections/resources) mostra a segunda — cada recurso que a instituição declarou para este consentimento e o que ela relata sobre cada um — que é como você distingue "o banco nunca compartilhou" de "não coletamos". O `resourcesCollectedAt` do Item indica quando essa lista foi lida pela última vez, e `hasResourcesPendingAuthorization` se algum recurso nela ainda está aguardando a autorização do usuário em seu banco — veja [Recursos pendentes de autorização](/docs/connections/resources#resources-pending-authorization).
## Atualizando um Item
O processo para atualizar um Item é bastante semelhante ao de criação. A maneira recomendada de fazê-lo também é usando nosso widget Pluggy Connect, conforme explicado [aqui](/docs/updating-an-item). Também pode ser feito via API: [Atualizar um Item](/reference/items-update) (também revise: [Item Enviar MFA](/reference/items-send-mfa)).
Quando uma atualização de Item é bem-sucedida, recuperamos todos os dados dos produtos desde a última vez que fizemos uma coleta de dados e mesclamos com os dados coletados anteriormente.
Além disso, dados de *até 4 dias antes* da última data de atualização bem-sucedida também serão coletados e mesclados, para compensar quaisquer possíveis mudanças ou adições que possam ter ocorrido nos dados da instituição e não perder o controle deles.
### Auto-sincronização
Uma vez criado, um **Item** terá uma referência aos parâmetros e credenciais do usuário armazenados necessários para executar a coleta de dados da instituição. Observe que todas as credenciais são criptografadas e **nunca** podem ser recuperadas da API.
Isso permite que *Pluggy* execute nosso processo de auto-sincronização: em um cronograma acordado com você, coletaremos os dados de transação dos últimos dias e os adicionaremos automaticamente ao conjunto de dados coletados existentes.
Dessa forma, você sempre terá acesso atualizado aos dados dos produtos da Instituição conectada, e **não será necessário configurar nenhum processo em lote** para atualizar suas conexões, apenas ouvir as notificações de webhook de novas atualizações.
#### Escolhendo um cronograma
A auto-sincronização pode seguir um de dois cronogramas. Ambos são configurados pela Pluggy em sua aplicação — entre em contato com seu gerente de conta para configurar um ou alterá-lo.
- **A cada N horas.** As sincronizações ocorrem em um intervalo fixo, contado a partir do final da sincronização anterior. Os intervalos disponíveis são 6, 8, 12, 24, 30, 48 e 96 horas. Opcionalmente, podemos ancorar o ciclo diário a uma hora de início, para que a primeira sincronização de cada dia ocorra perto de um horário que você escolher. Como cada sincronização é contada a partir de quando a anterior terminou, o horário exato do dia varia. Se você precisar que as sincronizações ocorram em horários previsíveis, use a opção abaixo.
- **Em horários específicos do dia.** As sincronizações ocorrem em até **4 horários fixos por dia** — por exemplo, 09:00, 11:00, 13:00 e 18:00. Esta é a melhor opção quando seu produto depende de dados atualizados em momentos específicos — por exemplo, conciliação durante o horário comercial ou verificação de transferências recebidas antes de um corte diário. Dentro de cada janela, as sincronizações individuais são distribuídas ao longo da hora, em vez de todas ocorrerem exatamente no mesmo minuto. Em uma conta com muitas conexões, espere que elas sejam concluídas progressivamente ao longo da janela, em vez de todas de uma vez.
Quando há um erro em uma atualização de auto-sincronização, duas coisas podem acontecer:
- Se foi um `LOGIN_ERROR` (por exemplo, quando as credenciais são inválidas), a atualização não será tentada novamente e o Item não será mais atualizado pela auto-sincronização. A auto-sincronização só será retomada quando o cliente conectar o Item com sucesso novamente.
- Se foi um erro diferente, tentamos a atualização a cada 1 hora até 5 tentativas; após isso, o Item também é removido da auto-sincronização.
O `nextAutoSyncAt` no endpoint [GET /items/\{id\}](/reference/items-retrieve) indica quando será a próxima atualização de auto-sincronização para o Item, ou nulo se não tiver auto-sincronização. Lembre-se de que esta é a data **mínima** em que a próxima atualização de auto-sincronização será executada: pode ser ligeiramente atrasada dependendo da carga do conector da instituição no momento.
O recurso de auto-sincronização está disponível apenas para aplicações **Produção**. Pode ser configurado para rodar a cada 24, 12 ou 8 horas com base na sua assinatura.
Se você precisar manter as conexões sincronizadas, a única maneira seria usar nossa Auto-Sincronização; o processo de atualização em lote será mitigado e nunca deve ser criado.
#### Conexões Meu Pluggy são um caso separado
[Meu Pluggy](https://meu.pluggy.ai) é um serviço autônomo para usuários finais conectando suas próprias contas, e possui suas próprias regras. Conexões feitas **dentro do Meu Pluggy** são atualizadas automaticamente **a cada 24 horas**, gratuitamente — essa cadência pertence ao serviço em si e não depende da assinatura de nenhuma aplicação.
Isso é importante quando sua aplicação se conecta através do **conector MeuPluggy**, porque existem **dois Itens distintos**:
| Item | Onde vive | Como se atualiza |
|---|---|---|
| O Item original | Dentro do Meu Pluggy | Automaticamente, a cada 24 horas |
| O Item proxy | Na sua aplicação | Reflete **todas** as atualizações do Item original automaticamente; não executa sua própria auto-sincronização e **não pode** ser atualizado manualmente |
Portanto, ambas as afirmações são verdadeiras ao mesmo tempo e não estão em conflito: *"As conexões Meu Pluggy são atualizadas diariamente"* (o Item original) e *"Itens proxy MeuPluggy não são auto-sincronizados"* (o Item proxy). Eles são objetos diferentes.
Algumas regras decorrem disso:
- **Uma autorização por banco.** Cada banco que a pessoa conectou no Meu Pluggy é autorizado separadamente em sua aplicação. Um banco adicionado ao Meu Pluggy mais tarde precisa de sua própria autorização.
- **Sem atualizações manuais.** Um Item proxy não pode ser atualizado através da API (sem atualização/`PATCH`). Ele segue as atualizações da conexão original.
- **Webhooks funcionam como de costume.** Itens proxy recebem webhooks como qualquer outro Item.
Para qualquer outro conector, o Item em sua aplicação segue as regras de auto-sincronização descritas acima.
Se você é um indivíduo lendo suas próprias contas, o conector MeuPluggy não é uma opção entre várias — é todo o caminho, e é gratuito. Meu Pluggy é seu próprio produto e documenta isso em seu próprio site: veja o [guia de acesso à API](https://meu.pluggy.ai/api-guide).
`nextAutoSyncAt` é retornado apenas quando a aplicação tem auto-sincronização habilitada. Um `null` lá significa *"esta aplicação não tem auto-sincronização configurada"*, não *"a conexão está quebrada"*.
## Notificações de Webhook
É possível ouvir Notificações de Webhook para recuperar todos os eventos relacionados a um `Item` específico. Para isso, você só precisa fornecer uma URL válida no parâmetro `webhookUrl`, seja ao criar um [Connect Token](/reference/connect-token-create), ou na própria [solicitação de criação do Item](/reference/items-create).
Você pode encontrar mais informações na seção [Webhook](/docs/webhooks).
Se você criar múltiplos webhooks para um item usando o `webhookUrl` e a configuração de Webhook em nível de cliente, você receberá múltiplas notificações.
### Evitando duplicatas
Para evitar que um usuário conecte sua conta mais de uma vez no Pluggy, fornecemos uma configuração ao criar sua conexão, que validará se as credenciais já existem antes de passar pelo processo de autenticação.
Usando essa configuração, o usuário receberá um erro da API especificando que já existe um Item criado para essas credenciais.
Você pode configurá-lo de duas maneiras:
- Se você estiver usando *Pluggy Connect*, pode [criar o token](/reference/connect-token-create) com as opções do item para `avoidDuplicates` como verdadeiro, e todos os itens gerados com esse `connectToken` serão validados.
- Se você estiver conectado diretamente através da API, pode [criar o item](/reference/items-create) com a mesma opção no payload.
Ao criar um item que já existe, você receberá um erro HTTP 400.
```json
{
"code": 400,
"codeDescription": "ITEM_USER_ALREADY_EXISTS",
"message": "Existem outros itens com as mesmas credenciais, você não pode criar um novo",
"data": {
"items": [
"d0f8a8c0-e8e3-11e9-b210-d663bd873d93",
"d0f8a8c0-e8e3-11e9-b210-d663bd873d94"
]
}
}
```
O array `data.items` contém os ids dos itens existentes que já utilizam essas credenciais, para que você possa direcionar seu usuário à conexão que ele já possui em vez de pedir que ele tente novamente. Observe que os ids estão aninhados sob `data` — eles não são retornados na raiz do corpo da resposta.
Esses conectores suportam o recurso Evitar duplicatas:
- Conectores diretos Pluggy: todos
- Conectores de Open Finance:
- Nubank
### Referenciando seu usuário
Ao criar um `Item`, você pode usar o `clientUserId` como um identificador externo de seus sistemas. Isso ajudará você a identificar um item com seu usuário.
Você pode configurar isso de duas maneiras:
- Usando nosso widget Pluggy Connect, você pode criar um connectToken com o valor para `clientUserId`. Todos os itens criados com esse token de conexão terão esse valor.
- Ao criar Itens através de nossa API, o payload possui um parâmetro `clientUserId` para receber essa referência.
### Buscando e listando itens
Antes de buscar a listagem, mantenha o `itemId` quando você obtiver — isso cobre quase todos os casos:
- **Widget:** o callback `onSuccess` recebe o item (`item.id`).
- **Webhooks:** `item/created` e todos os outros eventos `item/*` carregam `itemId` e seu `clientUserId`.
- **Conexões falhadas:** a tela de erro do widget mostra o id do item como o código de erro, para que um usuário final possa fornecê-lo à sua equipe de suporte.
Você pode recuperar as conexões que pertencem à sua conta com [GET /v2/items](/reference/items-list-by-cursor), as mais recentemente criadas primeiro. Os resultados podem ser restringidos com `clientUserId` — o identificador externo que você atribuiu ao criar o Item — ou com `connectorId`, para listar apenas as conexões a uma determinada instituição.
Este endpoint é **opt-in e desativado por padrão**. A listagem permite que uma chave de API enumere cada conexão que você possui, o que é um nível de acesso mais amplo do que recuperar um Item conhecido pelo seu id, portanto, é habilitado por acordo: peça por isso através de [Contato e suporte](/docs/get-started/contact). Não pode ser habilitado no plano Gratuito ou em contas de uso pessoal do Meu Pluggy. Até lá, o endpoint responde `403` com `LIST_ITEMS_FEATURE_NOT_ENABLED`.
As respostas são paginadas por cursor. Em vez de um número de página, cada resposta carrega um valor `next` apontando para a próxima página: anexe-o como está ao caminho do endpoint e pare assim que voltar `null`. Quaisquer filtros que você enviou já fazem parte de `next`, portanto, não há necessidade de repeti-los.
```javascript
let next = ''
const items = []
do {
const response = await fetch(`https://api.pluggy.ai/v2/items${next}`, {
headers: { 'X-API-KEY': apiKey },
})
const page = await response.json()
items.push(...page.results)
next = page.next
} while (next !== null)
```
O parâmetro `after` aceita apenas o valor do cursor. Enviar a string completa `next` como `after` é rejeitado com `INVALID_CURSOR`.
Listar é uma conveniência, não um substituto para sua própria contabilidade: ainda recomendamos rastrear suas conexões em sua fonte de dados pelo seu `itemId`, e manter essas referências sincronizadas.
## Ciclo de vida do Item
Source: https://docs.pluggy.ai/pt/docs/connections/item-lifecycle.md
Se você decidir usar nosso widget Pluggy Connect, não será necessário entrar em mais detalhes sobre o fluxo - já cobrimos tudo para você.
## Status do Item
Para entender o status atual de um item, devemos revisar seu campo `status`. Isso dará uma primeira visão sobre a saúde da conexão.
| Valor | Descrição | Significado |
|---|---|---|
| `UPDATING` | A conexão está sincronizando com o provedor. | Um processo de atualização está em andamento e será atualizado em breve. |
| `LOGIN_ERROR` | O processo de sincronização terminou com erros. | A conexão deve ser atualizada para ser executada novamente. Não acionaremos atualizações automáticas até que novos parâmetros de credenciais sejam fornecidos. |
| `OUTDATED` | O processo de sincronização terminou com erros. | Os parâmetros foram validados corretamente, mas houve um erro na última execução. Pode ser tentado novamente. |
| `WAITING_USER_INPUT` | O processo de sincronização precisa da entrada do usuário para continuar. | A conexão requer a entrada do usuário para continuar o processo de sincronização, isso é comum para conectores de autenticação MFA. |
| `UPDATED` | O processo de sincronização terminou com sucesso. | O último processo de sincronização foi concluído com sucesso e todos os novos dados estão disponíveis para coleta. |
Como mencionado acima, quando acionamos uma atualização, o status da conexão será definido como `UPDATING`. Este é um status em andamento, o que significa que você precisará verificá-lo novamente em alguns segundos.
Se as credenciais enviadas forem inválidas, você encontrará um status `LOGIN_ERROR` e será necessário atualizá-lo, fornecendo novas credenciais.
Caso ocorra um erro inesperado, você encontrará o status `OUTDATED`, e terá que revisar o campo `executionStatus` para mais detalhes.
Finalmente, o cenário mais comum é o status `UPDATED`, que significa que a conexão foi sincronizada com sucesso com a instituição.
## Status de Execução passo a passo
Cada item é criado ou atualizado através de uma execução, que, assim como o item, passa por diferentes estados à medida que é executada.
Cada status de Item está associado a um conjunto de possíveis valores de `executionStatus`, de acordo com o seguinte diagrama.
Essas combinações de status fornecem informações específicas não apenas sobre os passos que estão sendo executados enquanto o Item está sendo atualizado, mas também sobre o resultado final da execução. Assim, por exemplo, se o status do item for `OUTDATED`, podemos verificar o valor relacionado de `executionStatus` para saber a causa específica de não ter terminado com sucesso.
Você pode revisar o status de execução atual detalhado do Item através deste campo, `executionStatus`.
Esse valor indica o passo atual em que a execução se encontra, que pode ser um estado transitório (em andamento) ou um estado final.
### Estados transitórios
Os seguintes estados representam que a execução do Item ainda está em andamento, portanto, é provável que continue a mudar por conta própria.
| Valor | Descrição |
|---|---|
| `CREATED` | A conexão foi iniciada com sucesso. |
| `LOGIN_IN_PROGRESS` | A conexão está atualmente na etapa de autenticação de Login. |
| `LOGIN_MFA_IN_PROGRESS` | A conexão está atualmente na segunda etapa de autenticação de Login. Este estado ocorre após o envio de um parâmetro de token MFA apenas. |
| `ACCOUNTS_IN_PROGRESS` | Coletando dados de Contas atualmente. Implica que a etapa de Login foi concluída. |
| `CREDITCARDS_IN_PROGRESS` | Coletando dados de Cartões de Crédito atualmente. Implica que a etapa de coleta de Contas foi concluída (ou pulada). |
| `TRANSACTIONS_IN_PROGRESS` | Coletando dados de Transações de Contas e Cartões de Crédito atualmente. Implica que a etapa de coleta de Cartões de Crédito foi concluída (ou pulada). |
| `INVESTMENT_TRANSACTIONS_IN_PROGRESS` | Coletando Transações de Investimento atualmente. Implica que a etapa de coleta de Transações foi concluída (ou pulada). **Nota: apenas alguns conectores suportam este produto.** |
| `PAYMENT_DATA_IN_PROGRESS` | Coletando dados de Pagamentos de Transações atualmente. Implica que a etapa de coleta de Transações de Investimento foi concluída (ou pulada). **Nota: apenas alguns conectores suportam este produto.** |
| `IDENTITY_IN_PROGRESS` | Coletando dados de Identidade atualmente. Implica que as etapas de Transações (e Dados de Pagamento, se houver) foram concluídas (ou puladas). |
| `MERGING` | Analisando e armazenando todos os dados coletados. Implica que todos os dados disponíveis da Instituição foram coletados. |
### Estados finais
Esses estados representam uma Execução que terminou de ser executada.
Podemos distinguir dois tipos possíveis de estados finais:
- Um estado final, seja com um resultado de sucesso ou erro.
- Um estado intermediário, que significa que mais entrada do Usuário é necessária. Nesse caso, uma nova Execução precisa ser iniciada cumprindo as ações necessárias.
#### Estados de sucesso
| Valor | Descrição |
|---|---|
| `SUCCESS` | A execução foi concluída com sucesso, os produtos foram coletados. |
| `PARTIAL_SUCCESS` | A execução foi concluída com sucesso, os produtos foram coletados, mas alguns deles falharam. Verifique o atributo `statusDetail` do Item para mais informações. |
#### Atualizações parciais
Um item cuja atualização foi concluída com alguns produtos faltando relata `executionStatus` `PARTIAL_SUCCESS`, e `statusDetail` identifica quais produtos não foram coletados (`isUpdated: false`).
Algumas conexões são atualizadas mais de uma vez por dia, e essas atualizações extras cobrem apenas parte dos produtos do item. Uma atualização parcial nunca relata o item como totalmente atualizado: se a atualização completa do dia terminou como `PARTIAL_SUCCESS`, o item mantém esse status até que uma atualização completa posterior colete todos os produtos com sucesso.
Isso significa que `executionStatus` e `statusDetail` sempre concordam: você pode confiar apenas em `executionStatus` para decidir se um ciclo precisa de atenção e aprofundar-se em `statusDetail` apenas quando ele disser isso.
#### Estados de erro
| Valor | Descrição |
|---|---|
| `ERROR` | Ocorreu um erro inesperado na conexão. |
| `MERGE_ERROR` | A conexão foi concluída com sucesso e os dados foram coletados, mas tivemos um erro inesperado ao armazená-los em nossos registros. |
| `INVALID_CREDENTIALS` | Não foi possível autenticar a conta do usuário na instituição devido a credenciais incorretas. |
| `ALREADY_LOGGED_IN` | Não foi possível fazer login porque há uma sessão ativa e a Instituição não permitiu a criação de uma nova. |
| `SITE_NOT_AVAILABLE` | Falha ao obter uma resposta do site da Instituição. Possivelmente entrou em manutenção, fora de serviço ou temporariamente indisponível. |
| `INVALID_CREDENTIALS_MFA` | A segunda etapa de login falhou devido a um parâmetro de token MFA incorreto ou expirado fornecido. |
| `USER_INPUT_TIMEOUT` | A segunda etapa de login foi abortada após o tempo limite da solicitação do parâmetro MFA. |
| `ACCOUNT_LOCKED` | Não foi possível fazer login porque a conta do usuário foi bloqueada. O usuário precisa entrar em contato com a Instituição para desbloqueá-la. |
| `ACCOUNT_NEEDS_ACTION` | Não foi possível prosseguir com a coleta de dados porque uma ação manual do usuário é necessária, como resolver uma solicitação da Instituição para aceitar novos Termos de Uso, fornecer mais/informações pessoais novas, ou outra coisa. |
| `USER_NOT_SUPPORTED` | O Pluggy atualmente não suporta o tipo de conta que o usuário está tentando conectar, para a instituição selecionada. Por exemplo, uma conta "Operador" no conector Caixa Business. |
| `ACCOUNT_CREDENTIALS_RESET` | A instituição financeira está solicitando a redefinição das credenciais do usuário, isso pode ocorrer devido a uma senha expirada ou novas medidas de segurança implementadas pela instituição. |
| `CONNECTION_ERROR` | Falha ao estabelecer uma conexão com o site da Instituição. |
| `USER_AUTHORIZATION_NOT_GRANTED` | Não foi possível prosseguir com a coleta de dados porque o Usuário não concedeu autorização de Dispositivo ao Conector Pluggy. |
| `USER_AUTHORIZATION_REVOKED` | O usuário removeu o consentimento para compartilhar seus dados na Instituição Financeira. |
#### Estados intermediários
| Valor | Descrição |
|---|---|
| `WAITING_USER_INPUT` | Após uma etapa de login inicial bem-sucedida, a Instituição está esperando uma entrada adicional do usuário para continuar a execução, ou seja, um parâmetro extra de token MFA. Mais informações [aqui](/reference/items-send-mfa). |
| `USER_AUTHORIZATION_PENDING` | Um caso especial, semelhante ao `ACCOUNT_NEEDS_ACTION`, mas neste cenário o Usuário precisa fornecer autorização manual em seu Dispositivo ou conta da Instituição. Assim que o usuário resolver isso, o Pluggy prosseguirá com a coleta de dados automaticamente alguns minutos depois, nenhuma ação externa adicional é necessária. |
Veja [Itens em nossa referência da API](/reference/items) para mais informações.
## Fluxo de Sincronização
Durante o processo de criação ou atualização de um Item, ele passará por diferentes estados até que a coleta de dados seja concluída.
Quando o processo começa, o status será definido como `UPDATING` e, a partir daí, há alguns valores de estado possíveis que detalharemos abaixo, com base no fluxo de login específico do Conector.
Existem 3 possibilidades de fluxo de login específico do Conector: quando o conector não requer um parâmetro MFA, quando o conector requer um MFA que é acessível pelo usuário anteriormente (ou seja, usando o Google Authenticator), ou quando o conector requer um MFA que é gerado/solicitado ao usuário logo após a etapa inicial de login ter sido concluída.
### 1- Conectores sem parâmetro MFA
Este é o caso mais simples. O fluxo de login prosseguirá apenas com as credenciais do usuário.
**A- Se as credenciais do usuário estiverem corretas**, então a conexão prosseguirá e tentará recuperar os dados dos produtos. Então:
1. Se tudo correr bem, o status final do Item será `UPDATED`, e o `executionStatus` relacionado será `SUCCESS`.
2. Se algo der errado, mas pelo menos alguns dos dados dos produtos puderem ser recuperados, o status do Item também será `UPDATED`, e o `executionStatus` relacionado será `PARTIAL_SUCCESS`. Mais informações sobre o que falhou estarão disponíveis no campo `executionReport` do Item.
3. Se algo der muito errado com a conexão, como um erro inesperado, e nenhum dado puder ser recuperado, o status do Item será `OUTDATED` e o `executionStatus` relacionado será `ERROR`.
Nos casos acima, todos os itens são considerados atualizáveis, uma vez que as credenciais iniciais estavam corretas.
Por padrão, os Itens atualizáveis são sincronizados automaticamente por nós, uma vez por dia.
**B- Se as credenciais do usuário não estiverem corretas**, então o status do Item será `LOGIN_ERROR`.
Nesse caso, o Item não é considerado atualizável. O usuário terá que acionar manualmente uma atualização e recomeçar fornecendo um novo conjunto de credenciais.
O status `LOGIN_IN_PROGRESS` pode levar até 5 minutos, pois algumas instituições podem levar esse tempo para começar a retornar os dados da conta do usuário, portanto, considere essa janela de tempo em sua implementação.
### 2- Conectores com etapa de verificação de 1 passo
Este caso de Conector pode ser identificado encontrando em um dos valores de campo de credenciais do conector, uma credencial que tem o campo `mfa` definido como `true`.
O mesmo fluxo da etapa anterior ocorrerá.
Aqui os Itens **não são atualizáveis**, uma vez que uma entrada extra fornecida pelo usuário é necessária para cada execução de conexão.
**Exceções**
Existem algumas exceções, como Banco do Brasil PJ, que nos permite continuar sincronizando com a instituição (sem mais solicitações de MFA), uma vez que a autorização inicial do dispositivo foi concedida.
Nos casos em que o parâmetro MFA é enviado repetidamente entre as execuções, a API retornará uma solicitação inválida com a mensagem específica sem executar o conector.
### 3- Conectores com uma etapa de verificação de 2 passos
Este caso de Conector pode ser identificado verificando o campo base de dados do conector `mfa`, definido como `true`.
Assim, após fornecer as credenciais iniciais do usuário, se estiverem corretas, o Item saltará para um estado diferente: `WAITING_USER_INPUT`.
Neste estado, a conexão será suspensa, até que o usuário envie o código de validação. Assim que o usuário enviar o novo parâmetro, se o parâmetro enviado estiver correto, a execução será retomada como nos cenários anteriores até que o item termine a execução em um dos três possíveis estados finais `UPDATED`, `OUTDATED` ou `LOGIN_ERROR`.
Este caso de Itens **não é atualizável**, uma vez que uma entrada extra fornecida pelo usuário é necessária para cada execução de conexão.
A única exceção é **Nubank**, que pode ser atualizado após uma autorização inicial do dispositivo.
## Resumo
O seguinte diagrama de estado resume o fluxo de conexão do Item.
## Retenção de dados e limpeza automática
O Pluggy remove automaticamente os dados armazenados assim que não são mais necessários. As três políticas abaixo são executadas como trabalhos em segundo plano e se aplicam a todos os itens, independentemente de como foram criados.
Sempre que um item é removido por qualquer um desses processos, o evento webhook `item/deleted` é emitido. Veja [Webhooks](/docs/developer-tools/webhooks-ref) para o payload.
| Cenário | Quando é acionado | O que acontece |
|---|---|---|
| Item deletado pelo cliente | Imediatamente, em `DELETE /items/{id}` | O item é marcado como deletado, as credenciais armazenadas são apagadas, o consentimento de Open Finance é revogado (quando aplicável), e as autorizações OAuth são expiradas. Os dados do item (contas, transações, etc.) são permanentemente deletados. |
| Item de Sandbox não utilizado | Quando `updatedAt` é mais antigo que **30 dias** | O item e todos os seus dados relacionados são permanentemente removidos. Recrie o item para continuar testando. |
| Conector descontinuado pelo Pluggy | **30 dias** após o conector ser descontinuado | Cada item ainda anexado a esse conector é automaticamente deletado, seguindo o mesmo processo de uma exclusão iniciada pelo cliente (`item/deleted` webhook emitido). Os dados são então permanentemente removidos, de acordo com a política acima. |
### O que isso significa para você
- **A descontinuação do conector lhe dá uma janela de 30 dias.** Quando o Pluggy anuncia a descontinuação de um conector, incentive os usuários finais afetados a reconectar através de um conector ainda suportado antes do prazo de 30 dias. Após essa janela, o item é deletado e as credenciais armazenadas e os dados históricos se tornam inacessíveis.
- **Inscreva-se em `item/deleted`** se precisar reagir a exclusões automáticas em seu sistema (por exemplo, para atualizar seu próprio estado de usuário, remover dados em cache ou notificar o usuário final).
- **Credenciais e dados armazenados nunca são retidos além do que é estritamente necessário.** Assim que um item entra em qualquer um dos fluxos de exclusão acima, suas credenciais são apagadas antes de qualquer processamento adicional.
Itens de Sandbox seguem um cronograma mais rigoroso porque existem apenas para testes — itens de produção nunca são removidos apenas devido à inatividade.
## Erros e Validações
Source: https://docs.pluggy.ai/pt/docs/connections/errors-validations.md
Aprenda sobre os diferentes status e erros que você pode enfrentar ao usar a API da Pluggy.
Ao conectar um Item, se a conexão for bem-sucedida e todos os produtos forem recuperados corretamente, `GET /items/:id` retornará algo como isto:
```json
{
"id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
"status": "UPDATED",
"executionStatus": "SUCCESS",
"lastUpdatedAt": "2024-09-27T14:51:46.216Z",
"error": null,
"statusDetail": null
}
```
Se o status de execução for `SUCCESS`, isso significa que todos os produtos (contas, transações, etc) foram recuperados corretamente da instituição e estão prontos para serem recuperados.
## Item falhou ao fazer login
Ao criar ou atualizar um item, podemos falhar ao fazer login, o que retorna um status `LOGIN_ERROR`:
```json
{
"id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
"status": "LOGIN_ERROR",
"executionStatus": "INVALID_CREDENTIALS",
"error": {
"code": "INVALID_CREDENTIALS",
"message": "Credenciais inválidas."
},
"statusDetail": null
}
```
Aqui, nenhum produto foi recuperado, e não podemos tentar a conexão novamente: precisamos que o usuário atualize suas credenciais.
## Item falhou ao começar a recuperar produtos
Existem situações em que não conseguimos recuperar nenhum produto (por exemplo, a instituição está fora do ar, a instituição nos informa que há outra sessão ativa e nos expulsa, etc), mas isso não é necessariamente um problema com o login. Nesses casos, o item terá o status `OUTDATED`:
```json
{
"id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
"status": "OUTDATED",
"executionStatus": "CONNECTION_ERROR",
"error": {
"code": "CONNECTION_ERROR",
"message": "Erro de conectividade, por favor, tente novamente."
},
"statusDetail": null
}
```
Quando a instituição está passando por uma instabilidade, o `executionStatus` será `SITE_NOT_AVAILABLE`, no entanto, quando é um erro inesperado do nosso lado, o `executionStatus` será `ERROR` ou `CONNECTION_ERROR`.
Você pode tentar atualizar o item novamente para ver se o problema persiste (por exemplo, o banco pode estar instável pela manhã, mas se recuperar mais tarde durante o dia).
Se você tiver sincronização automática, itens `OUTDATED` são tentados automaticamente até 5 vezes, com 1 hora entre cada tentativa. Se falhar 5 vezes, ele é removido da sincronização automática.
## Item falhou ao recuperar um produto específico
Às vezes, acessamos a instituição corretamente, mas um determinado produto não pode ser recuperado. Isso resultará em um status de `UPDATED` com um status de execução de `PARTIAL_SUCCESS`. O campo `statusDetail` terá informações sobre quais produtos falharam.
```json
{
"id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
"status": "UPDATED",
"executionStatus": "PARTIAL_SUCCESS",
"error": null,
"statusDetail": {
"accounts": {
"warnings": [],
"isUpdated": true,
"lastUpdatedAt": "2024-01-23T22:39:55.622Z"
},
"transactions": {
"warnings": [],
"isUpdated": false,
"lastUpdatedAt": "2024-01-21T22:39:55.622Z"
},
"creditCards": null
}
}
```
Você também pode tentar novamente nesses casos para ver se o problema persiste. A sincronização automática não tenta novamente `PARTIAL_SUCCESS`.
Quando produtos falham ou têm problemas, o `statusDetail` inclui avisos que explicam o motivo. Aprenda mais sobre avisos e como lidar com eles no guia [Avisos & Códigos de Status](/docs/warnings-status-codes).
## O objeto de Erro
O seguinte tipo representa a estrutura completa do erro:
```typescript
type ExecutionErrorResult = {
code: ExecutionErrorCodes
message: string
providerMessage?: string
attributes?: Record
}
```
Com certos erros, o objeto de erro é retornado com uma chave `attributes` com informações adicionais necessárias para execuções futuras:
```json
{
"error": {
"code": "USER_AUTHORIZATION_PENDING",
"message": "O usuário precisa conceder as permissões necessárias para sua conta.",
"attributes": {
"deviceNickname": "123456789"
}
}
}
```
Quando o código de erro é `ACCOUNT_NEEDS_ACTION`, usamos um campo chamado `providerMessage` em português, com qualquer mensagem de alerta relevante da instituição:
```json
{
"error": {
"code": "ACCOUNT_NEEDS_ACTION",
"message": "A conta precisa de uma ação manual do usuário.",
"providerMessage": "Sua senha deve ser alterada"
}
}
```
O campo `providerMessage` é a mensagem exata retornada pela Instituição Financeira ao encontrar um erro, sem qualquer tratamento. Dessa forma, o usuário pode ter uma mensagem amigável e clara sobre o motivo pelo qual isso está acontecendo. Não fornecemos uma lista dessas mensagens, pois estão sujeitas a alterações pela IF.
## Tratamento de erros
A lógica de tratamento de erros, em geral, pode parecer algo assim:
- **Se `executionStatus` for `SUCCESS`**
- Buscar todos os produtos (transações, contas, etc)
- Verificar os avisos (se houver) para ver informações sobre como os dados podem ser melhorados.
- **Se `executionStatus` for `PARTIAL_SUCCESS`**
- Buscar todos os produtos `isUpdated: true`
- Levantar um alerta interno se for um produto crítico (por exemplo, `TRANSACTIONS`) ou adicionar um alerta para o usuário.
- Verificar os avisos (se houver) para ver informações sobre por que o produto falhou.
- **Se o status for `LOGIN_ERROR`** (Open Finance não requer tratamento desse caso):
- Não buscar nenhum produto
- Solicitar ao usuário que insira suas credenciais novamente
- **Se o status for `OUTDATED`**:
- Não buscar nenhum produto
- Levantar um alerta interno ou adicionar um alerta para o usuário
Para conectores diretos, todos os casos de erro estão descritos [aqui](/docs/item-lifecycle#error-states).
### Casos de erro do Open Finance
Para o Open Finance, há apenas um subconjunto de possíveis casos de erro, conforme segue, dividido por status e `executionStatus`:
- **`LOGIN_ERROR`**:
- `INVALID_CREDENTIALS`: o CPF/CNPJ é inválido
- `USER_AUTHORIZATION_NOT_GRANTED`: o usuário rejeitou o consentimento durante o fluxo de autorização
- `USER_AUTHORIZATION_REVOKED`: o usuário revogou o consentimento de seu banco
- **`OUTDATED`**:
- `USER_INPUT_TIMEOUT`: o usuário nunca terminou o fluxo de autorização
- `SITE_NOT_AVAILABLE`: a instituição está atualmente instável
- `ERROR`/`CONNECTION_ERROR`: ocorreu um erro inesperado ao acessar a instituição
- **`UPDATED`**:
- `PARTIAL_SUCCESS`: falha ao recuperar um produto, provavelmente porque o limite mensal foi atingido ou porque a instituição tem uma instabilidade temporária nesse produto.
Um produto também pode falhar porque a instituição não respondeu dentro do **tempo limite de 15 segundos** da rede. Veja [Tempo de resposta e tempo limite](/docs/open-finance/rate-limits#response-time-and-timeout) para como esse limite funciona e como difere da meta de desempenho da rede (P95).
## Validações de Criação de Item
As validações na API da Pluggy são muito importantes. Elas são usadas para evitar a execução de conectores com parâmetros inválidos e para criar conexões de item que não serão sincronizadas devido a credenciais ou parâmetros inválidos. Ao criar ou atualizar um item, as validações serão executadas para esse item com base nas credenciais do conector.
Este é um exemplo de uma resposta de validação ao criar um item:
```json
// HTTP 400
{
"message": "Os parâmetros do conector não correspondem às regras de validação",
"errors": [
{
"code": "002",
"message": "o comprimento do parâmetro user deve ser de pelo menos 6.",
"parameter": "user"
},
{
"code": "002",
"message": "o comprimento do parâmetro password deve ser de pelo menos 6.",
"parameter": "password"
}
]
}
```
## Erros de rejeição de atualização
Existem alguns casos em que um item não pôde ser atualizado devido ao estado do item:
| Código | Código de Erro | Descrição | Ação |
|---|---|---|---|
| 409 | `ITEM_IS_ALREADY_UPDATING` | O item já está atualizando | Aguarde o item terminar a sincronização existente. |
| 409 | `ITEM_CREATION_LIMIT_EXCEEDED` | Não é permitido atualizar o item porque ele foi atualizado antes da frequência mínima do cliente | Aguarde até que o atraso contratado tenha ocorrido. |
| 409 | `CLIENT_HAS_ITEM_UPDATES_DISABLED` | O cliente não pode acionar atualizações manuais, pois foi desativado pela Pluggy | Entre em contato com a equipe de suporte para entender por que o cliente foi desativado para atualizações. |
| 400 | `ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT` | O item foi originalmente conectado com uma conta diferente, por favor, use a conta original | O usuário inicialmente se conectou com uma empresa/conta diferente, não pode alterar a configuração de conexão. |
## Avisos e Códigos de Status
Source: https://docs.pluggy.ai/pt/docs/connections/warnings-status-codes.md
Entendendo os códigos de aviso e seus significados ao recuperar dados dos conectores Pluggy.
## Visão Geral
Ao recuperar dados de instituições financeiras através do Pluggy, você pode encontrar situações em que alguns dados estão indisponíveis ou não podem ser recuperados por várias razões. O Pluggy utiliza um sistema de aviso padronizado para informá-lo sobre essas situações sem falhar em todo o processo de coleta de dados.
Os avisos são retornados como parte do `statusDetail` para cada tipo de produto (Contas, Cartões de Crédito, Transações, etc.) e incluem:
- Um **código**: Um identificador único para o tipo de aviso
- Uma **mensagem**: Uma descrição legível por humanos do problema
- Uma **providerMessage** (opcional): A mensagem exata da Instituição Financeira em português, sem tratamento
Isso permite que você lide com essas situações de forma elegante em sua aplicação e forneça feedback apropriado aos seus usuários.
Erros indicam que toda a solicitação falhou e nenhum dado foi recuperado (veja [Erros & Validações](/docs/errors-validations)). Avisos indicam que a solicitação foi bem-sucedida, mas alguns dados podem estar incompletos ou indisponíveis. Sua aplicação deve lidar com ambos os cenários de forma apropriada.
## Quando os Avisos Ocorrem
Os avisos estão incluídos no `statusDetail` nestes cenários:
- O produto não pôde ser recuperado, e contém o motivo (`isUpdated: false`)
- O produto foi recuperado corretamente, mas pode ser melhorado com alguma ação do usuário (`isUpdated: true`)
Por exemplo: se o usuário não tem acesso a transações, nós as retornamos como vazias, mas um aviso sobre transações informa que, com mais permissões, poderíamos estar recuperando transações.
### Cenários Comuns
#### Problemas de Permissão
O usuário não concedeu as permissões necessárias durante o fluxo de consentimento, ou o consentimento expirou.
#### Status do Recurso
Um recurso específico (conta, cartão de crédito, empréstimo ou investimento) está em um estado que impede a recuperação de dados:
- **Autorização Pendente**: O recurso está aguardando autorização do usuário na instituição financeira
- **Indisponível Temporariamente**: O recurso está temporariamente indisponível (por exemplo, manutenção)
- **Indisponível**: O recurso está permanentemente indisponível
Nos itens de Open Finance, o `hasResourcesPendingAuthorization` do Item resume os recursos pendentes em todos os produtos, e
[`GET /items/{id}/resources?status=PENDING_AUTHORISATION`](/docs/connections/resources#resources-pending-authorization) lista-os.
#### Limites de Taxa
A instituição financeira atingiu seu limite de taxa operacional para o período atual. Veja [Limites de Taxa Operacional](/docs/rate-limits-of) para mais informações sobre limites de taxa de Open Finance.
#### Problemas de Sincronização
Alguns dados não puderam ser sincronizados, mas dados de fallback de uma sincronização bem-sucedida anterior estão sendo usados em vez disso.
## Lidando com Avisos
Os avisos estão incluídos na resposta para cada produto. Aqui está um exemplo de como os avisos aparecem na resposta da API:
**Conectores OF**
```json title="Conectores OF"
{
"accounts": [],
"warnings": {
"accounts": [
{
"code": "ACCT_002",
"message": "A conta c0a7d38c-d967-3b94-9d0b-c391068f4b20 está pendente de autorização"
}
],
"creditCards": [],
"transactions": [],
"loans": []
}
}
```
**Conectores Diretos**
```json title="Conectores Diretos"
{
"accounts": [],
"warnings": {
"investments": [
{
"code": "001",
"message": "O usuário não tem permissões para visualizar investimentos nesta conta",
"providerMessage": "Seu perfil de usuário não está habilitado para esta transação."
}
],
"creditCards": [],
"transactions": [],
"loans": []
}
}
```
Neste exemplo, uma conta está pendente de autorização e não foi incluída na lista de contas.
## Referência de Códigos de Aviso
### Conectores de Open Finance
Os conectores de Open Finance utilizam um sistema de aviso padronizado e tipado com códigos específicos por produto.
#### Contas (ACCOUNTS)
| Código | Motivo | Descrição |
|---|---|---|
| `ACCT_001` | Permissão ausente | O usuário não concedeu permissão para coletar contas (`ACCOUNTS_ALL`) |
| `ACCT_002` | Autorização pendente | A conta está pendente de autorização na instituição financeira |
| `ACCT_003` | Indisponível temporariamente | A conta está temporariamente indisponível |
| `ACCT_004` | Indisponível | A conta está indisponível |
| `ACCT_005` | Permissão de limites de cheque ausente | O usuário não concedeu permissão para coletar limites de cheque das contas (`ACCOUNTS_LIMITS`) |
| `ACCT_006` | Limite rígido de contas | Existem mais de 260 contas correntes para recuperar, mas retornamos apenas até esse número |
#### Cartões de Crédito (CREDIT_CARDS)
| Código | Motivo | Descrição |
|---|---|---|
| `CC_001` | Permissão ausente | O usuário não concedeu permissão para coletar cartões de crédito (`CREDIT_CARDS_ALL`) |
| `CC_002` | Autorização pendente | O Cartão de Crédito está pendente de autorização na instituição financeira |
| `CC_003` | Indisponível temporariamente | O Cartão de Crédito está temporariamente indisponível |
| `CC_004` | Indisponível | O Cartão de Crédito está indisponível |
| `CC_005` | Permissão de faturas ausente | O usuário não concedeu permissão para coletar faturas de cartões de crédito (`CREDIT_CARDS_BILLS`) |
| `CC_006` | Permissão de transações ausente | O usuário não concedeu permissão para coletar transações de cartões de crédito (`CREDIT_CARDS_TRANSACTIONS`) |
| `CC_007` | Limites ausentes | A instituição não retorna limite para este cartão de crédito |
#### Transações (TRANSACTIONS)
| Código | Motivo | Descrição |
|---|---|---|
| `TXN_001` | Permissão ausente | O usuário não concedeu permissão para coletar transações de contas (`ACCOUNTS_ALL` ou `ACCOUNTS_TRANSACTIONS`) |
| `TXN_002` | Nenhuma conta disponível | Nenhuma conta disponível para buscar transações |
| `TXN_003` | Limite de taxa atingido | Etapa de transações pulada devido a erro de limite de taxa na etapa de contas e nenhuma conta disponível |
| `TXN_004` | Sem permissão para coletar contas | O usuário não concedeu permissão para coletar contas, etapa de transações pulada |
| `TXN_005` | A etapa de contas teve erros | Etapa de transações pulada devido a erros na etapa de contas |
| `TXN_006` | Limite de taxa atingido | Erro de limite de taxa na etapa de contas, mas prosseguindo com transações usando contas disponíveis |
#### Empréstimos (LOANS)
| Código | Motivo | Descrição |
|---|---|---|
| `LOAN_001` | Permissão ausente | O usuário não concedeu permissão para coletar empréstimos (`CREDIT_OPERATIONS_ALL`) |
| `LOAN_002` | Autorização pendente | O empréstimo está pendente de autorização na instituição financeira |
| `LOAN_003` | Indisponível temporariamente | O empréstimo está temporariamente indisponível |
| `LOAN_004` | Indisponível | O empréstimo está indisponível |
| `LOAN_005` | Falha na sincronização de parcelas | Falha ao sincronizar as Parcelas do Empréstimo, usando dados de fallback da sincronização anterior |
| `LOAN_006` | Falha na sincronização de pagamentos | Falha ao sincronizar os Pagamentos do Empréstimo, usando dados de fallback da sincronização anterior |
#### Investimentos (INVESTMENTS)
| Código | Motivo | Descrição |
|---|---|---|
| `INV_001` | Permissão ausente | O usuário não concedeu permissão para coletar investimentos (`INVESTMENTS_ALL`) |
| `INV_002` | Autorização pendente | O investimento está pendente de autorização na instituição financeira |
| `INV_003` | Não suportado pela FI | Produto de investimento não suportado pela instituição financeira |
| `INV_004` | Limite de taxa atingido | Limite mensal de Open Finance atingido |
| `INV_005` | Tipo de produto não suportado | Tipo específico de produto de investimento não suportado pela instituição financeira |
`LOAN_002` e `INV_002` são relatados uma vez por contrato ou investimento, até 100 por produto. Algumas instituições mantêm todos os contratos ou posições já mantidos no consentimento, então um item pode ter mais; se você receber 100 deles, liste todos com [`GET /items/{id}/resources?status=PENDING_AUTHORISATION`](/docs/connections/resources#filtering-by-status).
#### Identidade (IDENTITY)
| Código | Motivo | Descrição |
|---|---|---|
| `ID_001` | Permissão ausente | O usuário não concedeu permissão para coletar identidade (`REGISTRATION_ALL`) |
| `ID_002` | Permissão de subproduto não concedida | A permissão de subproduto de identidade específica não foi concedida |
| `ID_003` | Limite de taxa de subproduto atingido | O limite de taxa de subproduto de identidade específico foi atingido |
| `ID_004` | Erro conhecido | Erro 400 conhecido para subproduto de identidade específico |
### Conectores Diretos
Os conectores diretos podem usar códigos genéricos (como `001`, `002`, `003`) com significados específicos do conector. O campo `providerMessage` fornece contexto em português da instituição.
Aqui está uma lista de avisos conhecidos para Conectores Diretos:
| Conector + Produto | Código | Mensagem | Mensagem do Provedor (PT-BR) | Item de Ação |
|---|---|---|---|---|
| Itaú PJ PAYMENT_DATA | `001` | O usuário não tem permissão para obter dados de pagamento de QR code PIX recebido | Consulte seu gerente ou Central de Atendimento para liberar permissões | Contate o gerente para conceder permissões de PIX |
| Itaú PJ PAYMENT_DATA | `001` | O cliente não tem permissões para ver dados de pagamento PIX | Cliente não tem permissão para acesso a PIX | Conceda acesso ao usuário na seção PIX |
| Itaú PJ INVESTMENTS | `001` | O usuário não tem permissões para visualizar investimentos | Seu perfil de usuário não está habilitado para esta transação | Conceda acesso ao usuário na seção de investimentos |
| Itaú PJ CREDIT_CARDS | `001` | O usuário não tem acesso aos resumos de cartões de crédito | - | Conceda acesso à seção de cartões de crédito |
| Santander PJ ACCOUNTS | `001` | O operador não tem acesso às Contas | - | Permita que o operador acesse a seção de contas |
| Santander PJ ACCOUNTS | `002` | O usuário não tem acesso ao 'Extrato 365 dias' | - | Informação recuperada de 'Saldo e Extrato' em vez disso |
| Santander PJ CREDIT_CARDS | `001` | O usuário não tem permissões, não pode recuperar cartões de crédito | - | Permita que o operador acesse a seção de cartões de crédito |
| Santander PJ TRANSACTIONS | `003` | O usuário não tem acesso ao 'Extrato 365 dias' ou está offline | - | Permita acesso ao 'Extrato 365' para remover limitações de dados |
| Bradesco PJ PAYMENT_DATA | `001` | O usuário não tem permissões para obter pagamentos TED / PIX / TEF | - | - |
| Bradesco PJ INVESTMENTS | `001` | O usuário não tem acesso a fundos mútuos / investimentos de renda fixa | Solicite ao usuário máster para ter acesso a esse serviço | Solicite ao usuário máster para conceder acesso |
| Bradesco PJ INVESTMENTS_TRANSACTIONS | `001` | O usuário não tem acesso às informações de transações de investimentos | Solicite ao usuário máster para ter acesso a esse serviço | Solicite ao usuário máster para conceder acesso |
| Bradesco PJ INVESTMENTS_TRANSACTIONS | `001` | O usuário não tem permissões para visualizar transações de renda fixa / fundos mútuos | - | - |
| Bradesco PJ TRANSACTIONS | `001` | Transações não estão habilitadas para esta conta | Solicite ao usuário máster para ter acesso a esse serviço | Solicite ao usuário máster para conceder acesso |
| Caixa PJ TRANSACTIONS | `001` | Situação impeditiva para movimentar sua conta | Situação impeditiva para movimentar sua conta. Procure sua agência para regularizar | Contate a agência para regularizar |
| XP INVESTMENTS | `001` | O usuário não tem permissões para acessar ativos do Tesouro | A Conta não está habilitada para operar no Tesouro Direto pois já existe outra conta XP Inc atrelada ao CPF do cliente. Caso queira trocar a conta habilitada, entre em contato com a XP | O usuário deve conceder acesso ao Tesouro Direto |
| Sicoob PJ ACCOUNTS | `001` | O usuário não tem permissões para obter contas | Usuário não tem permissão para executar a transação - Consultas - Saldo de conta corrente | Permita que o usuário acesse a seção de saldo da conta pelo aplicativo móvel |
O campo `providerMessage` contém a mensagem exata da Instituição Financeira em português, sem nenhum tratamento. Dessa forma, o usuário pode ter uma mensagem amigável e clara do motivo pelo qual isso está acontecendo. Não fornecemos uma lista completa dessas mensagens, pois estão sujeitas a alterações pela FI.
## Consentimentos e expiração
Source: https://docs.pluggy.ai/pt/docs/connections/consents.md
A primeira vez que um Item se conecta, um Consentimento é criado com uma data de expiração. O Consentimento mostra quais produtos financeiros um item está autorizado a recuperar por um determinado período. Você pode usar a API de Consentimentos para obter todos os consentimentos dados a um item.
Por padrão, os Consentimentos de Open Finance não têm expiração. No entanto, o usuário pode revogá-los a partir do aplicativo do seu Banco conectado sempre que necessário.
```json
{
"id": "a182a0ae-16b3-4790-9396-3724aa0bc14b",
"itemId": "ed893a30-5fab-45d8-917c-e71a313dbe5e",
"products": [
"ACCOUNTS",
"CREDIT_CARDS",
"TRANSACTIONS",
"INVESTMENTS",
"IDENTITY",
"INVESTMENTS_TRANSACTIONS",
"PAYMENT_DATA",
"LOANS"
],
"openFinancePermissionsGranted": [
"REGISTRATION_ALL",
"ACCOUNTS_ALL",
"CREDIT_CARDS_ALL",
"CREDIT_OPERATIONS_ALL",
"INVESTMENTS_ALL"
],
"createdAt": "2024-06-11T15:10:45.362Z",
"expiresAt": null,
"revokedAt": null
}
```
| Propriedade | Descrição | Obrigatório |
|---|---|---|
| `id` | Identificador principal do consentimento | Sim |
| `itemId` | Identificador principal do item associado ao consentimento | Sim |
| `products` | Produtos a serem coletados na conexão | Sim |
| `openFinancePermissionsGranted` | Produtos consentidos pelo usuário para serem coletados. Disponível apenas para conectores de Open Finance. | |
| `createdAt` | Data em que o consentimento foi dado | Sim |
| `expiresAt` | Data em que o consentimento expira. Nulo se o consentimento não expira | |
| `revokedAt` | Data em que o consentimento foi revogado. | |
Veja [Documentos de Gestão de Consentimento](/reference/consent/consents-list) para mais informações.
## Expiração / revogação de consentimento
Quando um consentimento expira (por exemplo, itens antigos de Open Finance) ou é revogado pelo usuário a partir do aplicativo, todos os seus endpoints de dados (contas, transações, etc) retornarão dados vazios.
Para continuar usando o Item após a expiração (indicada pelo campo `consentExpiresAt`), você precisará executar uma atualização no item (`PATCH` no Item), pedindo ao usuário para se conectar novamente. O usuário passará pelo fluxo de consentimento mais uma vez, renovando o consentimento.
Uma vez que isso seja concluído com sucesso, o item voltará ao status de execução `SUCCESS`, e os endpoints de dados estarão disponíveis novamente, com uma nova data `consentExpiresAt` no Item.
Não há necessidade de criar um novo item para renovar um consentimento; itens expirados funcionam da mesma forma que os de erro de login. Atualizações exigirão um login bem-sucedido para começar a sincronizar diariamente.
Por padrão, solicitamos consentimentos não expirantes, enquanto o usuário pode reajustar essa configuração como desejar. Se nulo, não há nenhuma expiração para essa conexão.
Existem alguns conectores como Inter PJ que têm uma expiração de consentimento padrão de um ano.
## Cobertura de Conectores
Source: https://docs.pluggy.ai/pt/docs/connections/connectors-coverage.md
import { Callout } from './components/mdx/Callout'
Esta tabela é o que o conector suporta em geral. Para um item específico, a instituição
declara o que realmente compartilha sob esse consentimento — veja
[Recursos do item](/docs/connections/resources).
Esta lista é mantida em sincronia com a Referência da API Pluggy. Você pode sempre consultar `GET /connectors` para a lista ao vivo.
Estas tabelas descrevem conectores **diretos**. O BTGPactual aqui é o conector de investimento direto (214); os conectores Open Finance BTG estão cobertos em [Cobertura de Instituições Open Finance](/docs/open-finance/institutions-coverage).
🏦 Aqui você encontrará todos os conectores disponíveis no Pluggy listados por tipo de conector, detalhando quais produtos são suportados em cada caso.
🟢 Disponível
🟡 Disponível condicionalmente (veja notas de rodapé)
🔴 Não disponível
## Pessoal
| Conector | Identidade | Contas | Cartões de Crédito | Transações | Dados de Pagamento | Investimentos | Transações de Investimento | Empréstimos | MFA | Atualizações Automáticas |
| --------------------------- | ----------- | ------ | ------------------ | ---------- | ------------------ | ------------- | ------------------------- | ----------- | --- | ----------------------- |
| Banco do Brasil Previdência | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🔴 |
| Caixa Economica Federal ¹ | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 |
| Redes Ethereum | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 |
| Inter | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Mercado Pago | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 |
| MeuPluggy | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 |
| Wise | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 |
## Empresarial
| Conector | Identidade | Contas | Cartões de Crédito | Transações | Dados de Pagamento | Investimentos | Transações de Investimento | Empréstimos | MFA | Atualizações Automáticas |
| ------------------------------------ | ----------- | ------ | ------------------ | ---------- | ------------------ | ------------- | ------------------------- | ----------- | --- | ----------------------- |
| Banco do Brasil Empresas² | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🟡 |
| Banco do Nordeste do Brasil Empresas | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 |
| Banrisul Empresas | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 |
| Bradesco Empresas³ | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟡 |
| Caixa Economica Federal Empresas⁴ | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 |
| Cora | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 |
| Efí Bank | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 |
| Inter Empresas⁴ | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 |
| Itaú Empresas⁵ | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 |
| Santander Empresas⁶ | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 | 🟡 |
| Sicredi Empresas⁴ | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 |
## Investimento
| Conector | Identidade | Contas | Cartões de Crédito | Transações | Dados de Pagamento | Investimentos | Transações de Investimento | Empréstimos | MFA | Atualizações Automáticas |
| ------------------ | ----------- | ------ | ------------------ | ---------- | ------------------ | ------------- | ------------------------- | ----------- | --- | ----------------------- |
| Avenue | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| BTGPactual | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Caixa Previdência | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 |
| EQI | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Mercado Bitcoin | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 |
| Necton | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| XP Investimentos⁷⁸ | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🟡 |
***
* ¹ O conector da Caixa depende da ação do usuário em completar uma autorização multifatorial. Quando o usuário insere suas credenciais, pode levar até 30 minutos para concluir o processo de login.
* ² MFA necessário no primeiro acesso apenas. Atualizações automáticas suportadas para acesso de administrador e operador.
* ³ MFA necessário apenas para acesso de administrador. Atualizações automáticas suportadas apenas com acesso de operador — o acesso de administrador não suporta atualizações automáticas.
* ⁴ Atualizações automáticas suportadas apenas com acesso de administrador.
* ⁵ MFA é necessário para algumas contas. Contas com MFA não serão atualizadas automaticamente.
* ⁶ MFA necessário apenas para acesso de administrador. Atualizações automáticas suportadas para acesso de administrador (requer acesso móvel habilitado) e acesso de operador.
* ⁷ Atualizações automáticas apenas para contas empresariais (sem MFA).
* ⁸ Transações de Investimento para o tipo SECURITY não estão disponíveis.
Você pode ver o status do conector em nossa [página de status](https://status.pluggy.ai/)
## Recursos de Item
Source: https://docs.pluggy.ai/pt/docs/connections/resources.md
Quando um produto retorna vazio, há duas razões muito diferentes por trás disso, e elas levam a
próximos passos opostos:
- **a instituição nunca compartilhou** — o consentimento não cobre, o usuário ainda precisa
autorizá-lo, ou o banco informa que está indisponível. O usuário final pode corrigir isso em seu banco;
- **não temos o registro** — o consentimento cobre, mas a sincronização não o trouxe. Isso
é nossa responsabilidade.
`GET /items/{id}/resources` responde à primeira. Ele lista os recursos que a instituição financeira
declarou para o consentimento deste item, exatamente como a instituição os relatou — nada inferido,
nada mesclado com nossos próprios dados.
Apenas instituições de Open Finance relatam uma lista de recursos. Um item em um conector direto retorna uma
página vazia em vez de um erro, então é seguro chamar para qualquer item.
## A resposta
O endpoint é paginado (`page`, `pageSize`, padrão 500 por página):
```json
{
"page": 1,
"total": 3,
"totalPages": 1,
"results": [
{ "resourceId": "92792126-fa1e-4e1c-a2b2-5b7b0d4a0b11", "type": "ACCOUNT", "status": "AVAILABLE" },
{ "resourceId": "0d1e2f34-55aa-4b0c-9f3d-77c1a0e2b345", "type": "CREDIT_CARD_ACCOUNT", "status": "PENDING_AUTHORISATION" },
{ "resourceId": "5f6a7b89-1122-4c33-8d44-99e0f1a2b3c4", "type": "FUND", "status": "UNAVAILABLE" }
]
}
```
Cada entrada tem três campos:
| Campo | O que é |
| :-- | :-- |
| `resourceId` | O **identificador** da instituição para o recurso. Ele corresponde ao `providerId` da conta, cartão de crédito, empréstimo ou investimento correspondente — não é um id da Pluggy. |
| `type` | O tipo de recurso de Open Finance, conforme declarado. |
| `status` | O que a instituição relata sobre este recurso. |
### Filtrando por status
Passe `status` para obter apenas os recursos em um estado, por exemplo
`GET /items/{id}/resources?status=PENDING_AUTHORISATION`. Valores aceitos: `AVAILABLE`,
`PENDING_AUTHORISATION`, `UNAVAILABLE`, `TEMPORARILY_UNAVAILABLE`. A paginação funciona da mesma forma, e
`total` conta apenas os recursos correspondentes.
## Status
| Status | O que significa | Quem age |
| :-- | :-- | :-- |
| `AVAILABLE` | A instituição compartilha este recurso sob o consentimento. | Ninguém — se os dados ainda estiverem faltando, é uma questão de coleta, não de consentimento. |
| `PENDING_AUTHORISATION` | O consentimento abrange este recurso, mas o usuário ainda não o autorizou em sua instituição. | O usuário final, no aplicativo do banco. |
| `UNAVAILABLE` | A instituição informa que não está disponível. | O usuário final, ou ninguém — a instituição decide. |
| `TEMPORARILY_UNAVAILABLE` | A instituição informa que está indisponível por enquanto. | Tente novamente mais tarde. |
`PENDING_AUTHORISATION` mantém a grafia britânica de Open Finance. É da regulamentação, não um erro de digitação.
## Tipos
| Tipo | Produto ao qual pertence |
| :-- | :-- |
| `ACCOUNT` | Contas |
| `CREDIT_CARD_ACCOUNT` | Cartões de crédito |
| `LOAN`, `FINANCING`, `INVOICE_FINANCING`, `UNARRANGED_ACCOUNT_OVERDRAFT` | Empréstimos — as mesmas quatro famílias que o [`kind`](/docs/products/loans) do Empréstimo usa |
| `BANK_FIXED_INCOME`, `CREDIT_FIXED_INCOME`, `VARIABLE_INCOME`, `TREASURE_TITLE`, `FUND` | Investimentos |
## Quão atualizada está a lista
A lista é um instantâneo da última execução que realmente alcançou a instituição, então pode ser
mais antiga que o próprio item. O **`resourcesCollectedAt`** do Item diz quando foi coletada.
Esse campo também é o que torna uma lista vazia legível:
- `resourcesCollectedAt` definido, lista vazia → a instituição não compartilhou **nada** sob este consentimento;
- `resourcesCollectedAt` `null` → a lista **nunca foi obtida**. Uma resposta vazia não diz
nada sobre o consentimento.
## Recursos pendentes de autorização
O **`hasResourcesPendingAuthorization`** do Item informa se algo nesta lista está aguardando
o usuário, sem precisar paginar por ela. Ele é lido desta mesma lista, então os dois sempre concordam.
| Valor | O que significa |
| :-- | :-- |
| `true` | A instituição declara pelo menos um recurso `PENDING_AUTHORISATION`. |
| `false` | A lista foi lida e nada nela está pendente. |
| `null` | A lista ainda não foi lida (`resourcesCollectedAt` é `null`), por exemplo, enquanto a primeira execução do item ainda está em andamento. Sempre `null` para conectores que não sejam Open Finance. |
A lista é armazenada antes que os webhooks `item/created` e `item/updated` sejam enviados, então ler o
Item quando o webhook chega fornece o valor para essa execução. Lê-la antes, enquanto a
primeira execução ainda está em andamento, e será `null`.
Uma maneira típica de lidar com isso:
1. Em `item/created` ou `item/updated`, chame `GET /items/{id}`.
2. Se `hasResourcesPendingAuthorization` for `true`, chame
`GET /items/{id}/resources?status=PENDING_AUTHORISATION` para ver quais recursos estão aguardando.
3. Informe ao seu usuário o que ele ainda precisa autorizar no aplicativo do banco — `type` diz a qual produto
cada recurso pertence. Para contas empresariais, isso é frequentemente a aprovação de um segundo signatário.
4. Assim que o usuário os autorizar, a próxima atualização do item traz os dados dele, e o
seguinte `item/updated` chega com `hasResourcesPendingAuthorization` definido como `false`.
## O que não responde
Se a Pluggy possui o registro correspondente é uma questão separada. Um recurso pode estar `AVAILABLE` e
ainda não ter dados do nosso lado, e o inverso também acontece — mantemos registros entre execuções,
então os dados podem estar lá de uma sincronização anterior de um recurso que a instituição não declara mais.
Para esse lado, use os endpoints de produtos (`/accounts`, `/investments`, `/loans`) e o
`statusDetail` do Item, que relata os resultados de coleta por produto. Veja
[Item](/docs/connections/item) e [Warnings & Status Codes](/docs/connections/warnings-status-codes).
## Um triagem trabalhada
Um cliente relata que um item conectado a um banco de Open Finance não retorna investimentos.
1. `GET /items/{id}` — o `status` é `UPDATED`? O que diz `statusDetail.investments`? Se ele
relatar um erro, o problema é de coleta e para aqui. Avisos `INV_002` listam os
investimentos ainda pendentes de autorização no banco (até 100), e
`hasResourcesPendingAuthorization: true` diz que algum recurso, em qualquer produto, está aguardando o
usuário; o passo 2 tem a lista completa.
2. `GET /items/{id}/resources` — há tipos de investimento na lista? Adicione
`?status=PENDING_AUTHORISATION` para ver apenas os que estão aguardando o usuário.
- nenhum, e `resourcesCollectedAt` está definido → a instituição não compartilha investimentos sob
este consentimento. Nada a corrigir do nosso lado;
- presente como `PENDING_AUTHORISATION` → o usuário precisa autorizar esse recurso em seu banco;
- presente como `AVAILABLE` → o consentimento cobre e deveríamos tê-lo. Isso é uma questão de coleta
que vale a pena [reportar](/docs/connections/reporting-issues), com o id do item e o
`resourceId` em mãos.
As tabelas de cobertura por conector respondem a uma pergunta diferente — o que um conector suporta em geral —
e vivem em [Connectors coverage](/docs/connections/connectors-coverage). Este endpoint responde a
**um** consentimento, conforme a instituição declarou hoje.
## Cobertura de Cartões de Crédito
Source: https://docs.pluggy.ai/pt/docs/connections/credit-cards-coverage.md
Aqui você encontrará a cobertura que temos para cada conector em relação ao produto Cartão de Crédito
## Referências
🟢 Disponível;
🔴 Não disponível.
## Pessoal
| Conector | Vários Cartões | Parcelas | Limite Flexível | Data de Fechamento | Data de Vencimento | Limite de Crédito | Limite de Crédito Disponível | Pagamento Mínimo | Contas |
| :--------------------- | :------------- | :------------------------------------------------------------ | :-------------- | :------------------ | :----------------- | :---------------- | :-------------------------- | :--------------- | :----- |
| Caixa Econômica Federal | 🟢 (2 meses) | 🟢 installmentNumber 🟢 totalInstallments 🟢 totalAmount | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Mercado Pago | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco Safra | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Rede Ethereum | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Inter | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | | 🟢 |
## Negócios
| Conector | Vários Cartões | Parcelas | Limite Flexível | Data de Fechamento | Data de Vencimento | Limite de Crédito | Limite de Crédito Disponível | Pagamento Mínimo | Contas |
| :------------------------------- | :------------- | :------- | :-------------- | :------------------ | :----------------- | :---------------- | :-------------------------- | :--------------- | :----- |
| Santander Empresas | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Bradesco Empresas | 🟢 (1 mês) | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Itaú Empresas | 🟢 (2 meses) | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| Caixa Econômica Federal Empresas | 🟢 (2 meses) | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Banco do Brasil Empresas | 🟢 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco Inter Empresas | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Sicredi Empresas | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Conta Simples | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
## Investimento
| Conector | Vários Cartões | Parcelas | Limite Flexível | Data de Fechamento | Data de Vencimento | Limite de Crédito | Limite de Crédito Disponível | Pagamento Mínimo | Contas |
| :--------------- | :------------- | :------- | :-------------- | :------------------ | :----------------- | :---------------- | :-------------------------- | :--------------- | :----- |
| XP Investimentos | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
## Cobertura de contas
Source: https://docs.pluggy.ai/pt/docs/connections/accounts-coverage.md
Aqui você encontrará a cobertura que temos para cada conector em relação ao produto de Conta
Estas tabelas descrevem conectores **diretos**. O BTGPactual aqui é o conector de investimento direto (214); para conectores de Open Finance veja [Cobertura de Instituições de Open Finance](/docs/open-finance/institutions-coverage).
## Referências
🟢 Disponível.
🔴 Não disponível.
## Pessoal
| Conector | Conta Corrente | Conta Poupança | Acesso de Administrador | Acesso de Operador | Fluxo de Conta Conjunta | Fluxo de Múltiplas Contas |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Caixa Econômica Federal | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Banco Inter | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Mercado Pago | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
## Empresarial
| Conector | Conta Corrente | Conta Poupança | Acesso de Administrador | Acesso de Operador | Fluxo de Conta Conjunta | Fluxo de Múltiplas Contas |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Santander Empresas | 🟢 (90 dias de transações) | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 |
| Bradesco Empresas | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 |
| Itaú Empresas | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 |
| Caixa Econômica Federal Empresas | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 |
| Banco do Brasil Empresas | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 |
| Banco Inter Empresas | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 |
| Sicredi Empresas | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 |
| Cora | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 |
## Investimento
| Conector | Conta Corrente | Conta Poupança | Acesso de Administrador | Acesso de Operador | Fluxo de Conta Conjunta | Fluxo de Múltiplas Contas |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| XP Investimentos | 🟢 Conta Investimento 🟢 Conta digital | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 |
| BTGPactual | 🟢 | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 |
| Avenue | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 |
| EQI | 🟢 | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 |
| Necton | 🟢 | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 |
## Cobertura de dados de pagamento
Source: https://docs.pluggy.ai/pt/docs/connections/paymentdata-coverage.md
Aqui você encontrará a cobertura de dados que temos para cada conector em relação ao produto de Dados de Pagamento.
## Referências
🟢 Disponível.
🔴 Não disponível.
## Pessoal
| Conector | PIX (entrada) | PIX (saída) | TED (entrada) | TED (saída) | DOC (entrada) | DOC (saída) | TEF (entrada) | TEF (saída) | BOLETO (saída) |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Caixa Econômica Federal | 🟢 (12 meses) | 🟢 (12 meses) | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco Inter | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
## Empresarial
| Conector | PIX (entrada) | PIX (saída) | TED (entrada) | TED (saída) | DOC (entrada) | DOC (saída) | TEF (entrada) | TEF (saída) | BOLETO (saída) |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Santander Empresas | 🟢 (12 meses) | 🟢 (3 meses) | 🔴 | 🟢 (3 meses) | 🔴 | 🟢 (3 meses) | 🔴 | 🟢 (3 meses) | 🟢 (3 meses) |
| Bradesco Empresas | 🟢 (12 meses) | 🟢 (12 meses) | 🔴 | 🟢 (12 meses) | 🔴 | 🟢 (12 meses) | 🔴 | 🟢 (12 meses) | 🟢 (12 meses) |
| Itaú Empresas | 🟢 (3 meses) | 🟢 (12 meses) | 🔴 | 🟢 (12 meses) | 🔴 | 🟢 (12 meses) | 🔴 | 🟢 (12 meses) | 🟢 (12 meses) |
| Caixa Econômica Federal Empresas | 🟢 (12 meses) | 🟢 (12 meses) | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco do Brasil Empresas | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) |
| Banco Inter Empresas | 🟢 (24 meses) | 🟢 (24 meses) | 🟢 (24 meses) | 🟢 (24 meses) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 (24 meses) |
| Sicredi Empresas | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🟢 (12 meses) | 🔴 | 🔴 | 🟢 (12 meses) |
| Conta Simples | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
## Cobertura de investimentos
Source: https://docs.pluggy.ai/pt/docs/connections/investments-coverage.md
Aqui você encontrará a cobertura que temos para cada conector em relação ao produto de Investimentos
Esta tabela é o que o conector suporta em geral. Para um item específico, a instituição
declara o que realmente compartilha sob esse consentimento — veja
[Recursos do Item](/docs/connections/resources).
Estas tabelas descrevem conectores **diretos**. O BTGPactual aqui é o conector de investimento direto (214); para conectores de Open Finance veja [Cobertura de Instituições de Open Finance](/docs/open-finance/institutions-coverage).
## Referências
🟢 Disponível.
🔴 Não disponível.
## Pessoal
| Conector | Renda Fixa | Fundos Mútuos | Ações | ETF | Imóveis | Segurança | COE |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Caixa Econômica Federal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 |
| Banco Inter | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Mercado Pago | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Ethereum Network | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 |
| Caixa Previdência | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 |
| Banco do Brasil Previdência (Brasilprev) | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 |
## Empresarial
| Conector | Renda Fixa | Fundos Mútuos | Ações | ETF | Imóveis | Segurança | COE |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Santander Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Bradesco Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Itaú Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Caixa Econômica Federal Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco do Brasil Empresas | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco Inter Empresas | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Sicredi Empresas | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
## Investimento
| Conector | Renda fixa | Fundos mútuos | Ações | ETF | Imóveis | Segurança | COE | Retirada Total | Nota de Corretagem |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| XP Investimentos | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| BTGPactual | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 Apenas para Ações | 🔴 |
| Avenue | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| EQI | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 Apenas para Ações | 🔴 |
## Cobertura de Transações de Investimento
Source: https://docs.pluggy.ai/pt/docs/connections/investment-transactions-coverage.md
Aqui você encontrará a cobertura que temos para cada conector em relação ao produto de Transações de Investimento
Esta tabela é o que o conector suporta em geral. Para um item específico, a instituição declara o que realmente compartilha sob esse consentimento — veja
[Recursos do Item](/docs/connections/resources).
Estas tabelas descrevem conectores **diretos**. O BTGPactual aqui é o conector de investimento direto (214); para conectores de Open Finance veja [Cobertura de Instituições de Open Finance](/docs/open-finance/institutions-coverage).
## Tenha em mente as seguintes referências
🟢 Disponível na instituição e implementado;
🔵 Disponível na instituição e não implementado;
🔴 Não disponível na instituição.
## Pessoal
| Conector | Fundos Mútuos | Renda Fixa | Tesouraria | Ações | Títulos | COE |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Inter | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
## Empresarial
| Conector | Fundos Mútuos | Renda Fixa | Tesouraria | Ações | Títulos | COE |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| Itaú Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 |
| Caixa Econômica Federal Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco do Brasil Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 |
| Bradesco Empresas | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 |
| Semear | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 |
## Investimento
| Conector | Fundos Mútuos | Renda Fixa | Tesouraria | Ações | Títulos | COE |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| XP Investimentos | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 |
| BTGPactual | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Avenue | 🟢 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 |
| Caixa Previdência | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 |
## Cobertura de empréstimos
Source: https://docs.pluggy.ai/pt/docs/connections/loans-coverage.md
## Pessoal
| Conector | Empréstimos suportados |
| :-- | :-- |
| Open Finance | 🟢 |
## Cobertura de identidade
Source: https://docs.pluggy.ai/pt/docs/connections/identity-coverage.md
Aqui você encontrará a cobertura que temos para cada conector em relação ao produto de Identidade
## Pessoal
| Conector | Identidade |
| :-- | :-- |
| Caixa Econômica Federal | fullName document documentType |
| Banco Inter | fullName |
| Mercado Pago | fullName document documentType phoneNumbers.type phoneNumbers.value emails.type emails.value addresses.fullAddress |
| Banco do Brasil Previdência | fullName document documentType birthDate phoneNumbers.type phoneNumbers.value emails.value emails.type addresses.city addresses.state addresses.country addresses.postalCode addresses.type |
## Empresarial
| Conector | Identidade |
| :-- | :-- |
| Santander Empresas | taxNumber companyName |
| Bradesco Empresas | fullName taxNumber emails.type emails.value companyName addresses.fullAddress addresses.city addresses.state addresses.postalCode addresses.type phoneNumbers.type phoneNumbers.value |
| Itaú Empresas | fullName companyName taxNumber |
| Caixa Econômica Federal Empresas | fullName addresses.type addresses.postalCode addresses.fullAddress addresses.city addresses.state addresses.country addresses.primaryAddress phoneNumbers.type phoneNumbers.value taxNumber |
| Banco do Brasil Empresas | fullName companyName document documentType phoneNumber.value email.value |
| Banco Inter Empresas | taxNumber companyName |
## Investimento
| Conector | Identidade |
| :-- | :-- |
| XP Investimentos | fullName document documentType birthDate phoneNumbers.type phoneNumbers.value emails.type emails.value relations.type relations.name addresses.type addresses.primaryAddress addresses.fullAddress addresses.postalCode addresses.state addresses.city addresses.country jobTitle companyName investorProfile |
| BTG Pactual | fullName birthDate document documentType phoneNumbers.type phoneNumbers.value emails.type emails.value investorProfile |
| XP - Wealth | companyName providerId |
## Open Finance vs Direct: diferenças de campo
Source: https://docs.pluggy.ai/pt/docs/connections/open-finance-vs-direct-fields.md
Pluggy retorna os mesmos objetos — `Transaction`, `Account`, `Identity` — independentemente de como um item foi conectado. **Os objetos têm a mesma estrutura, mas nem todos os campos estão preenchidos a partir de ambas as fontes.** Um campo que está sempre presente para um cliente pode estar permanentemente `null` para outro, puramente por causa do tipo de conexão.
Esta página lista os campos que existem **apenas de um lado**, para que você possa distinguir "esta instituição não envia" de "isso nunca chega por esse tipo de conexão".
Então é uma questão de cobertura por instituição, não de tipo de conexão. As páginas de cobertura detalham por conector: [Cartões de Crédito](/docs/connections/credit-cards-coverage), [Contas](/docs/connections/accounts-coverage), [Dados de Pagamento](/docs/connections/paymentdata-coverage), [Identidade](/docs/connections/identity-coverage).
## Por que eles diferem
As conexões **Open Finance (regulamentadas)** leem as APIs regulamentadas da instituição. O esquema é fixado pela especificação do Open Finance Brasil, então cada instituição retorna a mesma estrutura e a Pluggy a mapeia uma vez. Se a especificação não tem um campo para algo, nenhuma instituição pode enviá-lo — a lacuna é regulatória, não técnica, e nenhum trabalho por instituição a fecha.
As conexões **Diretas** leem os próprios canais da instituição. Não há um esquema comum, então o que chega depende do que cada instituição expõe. É por isso que a cobertura direta é publicada por conector, enquanto a cobertura do Open Finance é essencialmente uniforme.
A consequência prática: Open Finance oferece **amplitude e consistência**, enquanto os conectores diretos às vezes oferecem **campos que a regulamentação nunca definiu**.
## Somente Open Finance
| Campo | Objeto | Notas |
| :-- | :-- | :-- |
| `providerId` | `Transaction` | O id da transação da própria instituição. O único identificador estável do lado do provedor que expomos. Conectores diretos não têm equivalente garantido — reconcilie por `date` + `amount` + `description` em vez disso. |
| `creditCardMetadata.billId` | `Transaction` | Liga a transação à fatura à qual foi cobrada. |
| `creditCardMetadata.billPostDate` | `Transaction` | A data em que a instituição postou a transação em uma fatura, conforme a instituição relata — nunca ajustada pela Pluggy, ao contrário da `date` da transação. `null` enquanto a transação não estiver postada em uma fatura ainda ou quando a instituição não a reporta. Não retroativa: transações sincronizadas antes do campo existir não carregam chave, o que significa o mesmo que `null`. |
| `creditCardMetadata.transactionDateTime` | `Transaction` | O timestamp da transação conforme a instituição relata, normalizado para ISO-8601 válido. Não retroativa. |
| `creditCardMetadata.paymentType` | `Transaction` | `SINGLE` (cobrado integralmente em uma fatura) ou `INSTALLMENT`. Não retroativa. |
| `brandAdditionalInfo` | `Account` | Texto livre descrevendo a marca quando `brand` é `OTHER`. |
| `investorProfile` | `Identity` | Classificação do perfil do investidor (Conservador, Moderado, Agressivo). |
| `qualifications` | `Identity` | Dados de renda, patrimônio e ocupação. |
| `financialRelationships` | `Identity` | Os produtos do cliente e a data de início do relacionamento com a instituição. |
| `openFinancePermissionsGranted` | `Consent` | As permissões que o usuário realmente consentiu. Não tem significado para uma conexão direta. |
O [endpoint de saldo em tempo real](/docs/products/real-time-balance) também é somente Open Finance — chamá-lo em uma conta não-Open-Finance retorna um erro.
## Somente Direto
| Campo | Objeto | Notas |
| :-- | :-- | :-- |
| `creditCardMetadata.totalAmount` | `Transaction` | O valor total de uma compra parcelada (a soma de cada parcela). O esquema de cartão de crédito do Open Finance não tem equivalente: ele reporta cada parcela, nunca o total da compra. Disponível em alguns conectores diretos — veja [Cobertura de Cartões de Crédito](/docs/connections/credit-cards-coverage). |
| `balance` em cada transação | `Transaction` | Saldo corrente após a transação. Suportado por Itaú PJ, Sicredi PF & PJ e Bradesco PJ. |
- `creditCardMetadata.totalAmount`, em uma **transação** — o total da compra de um plano de parcelamento. **Somente Direto.**
- `totalAmount`, em uma **fatura** — o valor da fatura inteira. **Disponível no Open Finance**, mapeado a partir de `billTotalAmount`.
Ver um `totalAmount` preenchido em uma fatura em uma conexão Open Finance não significa que o campo de nível de transação também estará preenchido.
## Campos que as pessoas esperam que sejam exclusivos, mas não são
`paymentData` — os detalhes do pagador/recebedor em uma transferência — é **preenchido por ambos**. Open Finance o mapeia a partir das partes da transação regulamentada, e conectores diretos o extraem onde a instituição o expõe. O que varia é *quão completamente* ele é preenchido, por instituição, que é o que [Cobertura de Dados de Pagamento](/docs/connections/paymentdata-coverage) rastreia.
O mesmo se aplica a `merchant`, `category` e `operationType`: ambos os lados podem preenchê-los, com diferenças por instituição em quão detalhado chega.
## Escopo e atualidade
Esta página cobre **Transações, Contas, Identidade e Consentimentos**, que é onde a questão surge na prática. Investimentos, Empréstimos e Notas de Corretagem ainda não estão detalhados aqui; para esses, trate as páginas de cobertura por conector como a fonte da verdade.
A lista é derivada dos mapeadores de conectores, não de amostragem de dados de produção — um campo listado como disponível ainda pode ser `null` para uma determinada instituição ou uma determinada transação. A presença aqui significa *este tipo de conexão pode retorná-lo*, não *ele está sempre lá*.
Última revisão: **2026-09-24**, em relação ao mapeamento da API de Cartão de Crédito Open Finance Brasil v2.4.0.
## Relatar Problemas
Source: https://docs.pluggy.ai/pt/docs/connections/reporting-issues.md
## Visão Geral
Este guia explica como entender problemas que os usuários podem ter e como relatá-los à equipe de suporte da Pluggy.
## Entendendo Erros
Quando um item encontra um erro esperado, ele retornará com o status `OUTDATED`, com `ERROR` como o status de execução. Erros podem ocorrer após a fornecimento de credenciais, quando o item começa a se conectar à instituição financeira e começa a fornecer respostas/webhooks.
### Erros Inesperados
Erros inesperados geralmente são retornados quando a instituição financeira (FI) está instável ou quando há um caso que não foi mapeado pela Pluggy. Se erros inesperados forem consistentes, você deve relatá-los à equipe.
Quando a instituição está passando por uma instabilidade, o `executionStatus` será `SITE_NOT_AVAILABLE`. No entanto, quando é um erro inesperado do lado da Pluggy, o `executionStatus` será `ERROR` ou `CONNECTION_ERROR`.
### Erros de Conexão
Erros de conexão ocorrem após a fornecimento de credenciais, quando o item começa a se conectar à instituição financeira. Esses erros estão tipicamente relacionados a:
- Instabilidade ou inatividade da instituição
- Cenários não mapeados do lado da Pluggy
- Mudanças de autenticação na instituição
## Como Relatar Problemas
Quando você está enfrentando problemas, o importante é fornecer contexto suficiente para que a equipe de suporte possa investigar.
### Usando o Widget
Ao usar o widget, o usuário acabará em uma tela com um erro inesperado e um ErrorCode. Se você estiver usando o Connect widget da Pluggy, esse erro será exibido no widget. Relate uma captura de tela do widget para dar à equipe de suporte contexto suficiente.
### Usando a API Diretamente
Se você estiver criando sua própria UX, você verá o erro na resposta HTTP POST `/items`. Relate a resposta HTTP para dar à equipe de suporte contexto suficiente.
Ao usar o widget, uma captura de tela da **tela de erro ou do código de erro** é suficiente.
É altamente recomendável que os clientes rastreiem as tentativas de conexão de seus usuários, armazenando-as como conexões malsucedidas. Você pode capturar o `itemId` através da implementação do seu Connect widget da Pluggy, capturando o evento `onError`, ou através do evento [webhook item/error](/docs/developer-tools/webhooks-ref).
Ao conectar diretamente através da API, envie o **itemId** trocado no fluxo da API.
**Não podemos analisar erros sem um itemId, então é obrigatório que você o capture e forneça.**
### Relatório de Execução
Mais informações sobre o que falhou estarão disponíveis no campo `executionReport` do Item. Se algo der errado fatalmente com a conexão, como um erro inesperado, e nenhum dado puder ser recuperado, o status do Item será `OUTDATED` e o `executionStatus` relacionado será `ERROR`.
O widget e a resposta HTTP fornecem informações suficientes para você entender o que está dando errado, e eles dão à equipe de suporte o contexto necessário para investigar o problema.
## Erros ao Fornecer Credenciais (HTTP 400)
Geralmente, esse problema ocorre quando o usuário envia suas credenciais, mas a criação do Item não é bem-sucedida. Isso significa que a criação do Item retorna um erro HTTP 400 para validações.
Geralmente, isso significa:
- As credenciais não estão no formato correto.
- Existem credenciais ausentes.
- Há uma conexão ativa, ou uma conexão duplicada foi detectada.
Se você estiver usando o Connect widget da Pluggy, esse erro será exibido no **widget**; se você estiver criando sua própria UX, você verá esse erro na **resposta** HTTP POST `/items`. Para mais detalhes sobre quais erros são retornados, você pode conferir a [referência da API](/reference/items-create).
Quando você estiver tendo esse tipo de problema, relate uma **captura de tela do widget** ou a **resposta HTTP** para dar à equipe de suporte contexto suficiente. Esperamos que o widget e a resposta HTTP forneçam informações suficientes para você entender o que está dando errado.
## Página de Status
A Pluggy possui uma página de status pública onde eles publicam quaisquer incidentes e interrupções para que você possa ficar ciente de quaisquer problemas existentes. Você pode visitar a página de status em [status.pluggy.ai](https://status.pluggy.ai).
Você também pode se inscrever usando o botão no topo da página de status para ser notificado sobre incidentes assim que eles acontecerem. Você pode receber atualizações de incidentes e mensagens de status de manutenção no Slack ao se inscrever.
Para mais informações sobre como se inscrever na página de status, veja [Inscreva-se em nossa Página de Status](/docs/subscribe-to-our-status-page).
## Páginas Relacionadas
- [Erros & Validações](/docs/errors-validations)
- [Ciclo de vida do Item](/docs/item-lifecycle)
- [Cobertura de Conectores](/docs/connectors-coverage)
## Conectores Open Finance
Source: https://docs.pluggy.ai/pt/docs/open-finance/overview.md
import { Callout } from './components/mdx/Callout'
Na Pluggy, além dos nossos Conectores habituais, agora também suportamos a obtenção de dados da [Rede Brasileira de Open Finance](https://openfinancebrasil.org.br) com Conectores de Open Finance.
Os Conectores de Open Finance seguem o modelo de dados da Pluggy como qualquer outro Conector (Itens, Contas, Transações, etc.), portanto, não há **mudança disruptiva** ao obter dados de Open Finance. No entanto, existem algumas diferenças nos **produtos** que eles recuperam, nas **instituições** que suportam e **na forma como o usuário conecta** sua conta. Neste guia, discutiremos essas diferenças para que você possa escolher qual tipo de conector é mais adequado para o seu caso de uso.
Se você estiver interessado em usar Conectores de Open Finance, entre em contato com nossa equipe de vendas para habilitá-lo para o seu plano.
## Produtos suportados por Open Finance
Atualmente, o Open Finance suporta os seguintes produtos:
* `ACCOUNTS`
* `CREDIT_CARDS`
* `TRANSACTIONS`
* `IDENTITY`
* `LOANS`
* `INVESTMENTS` & `INVESTMENT_TRANSACTIONS` & `BROKERAGE_NOTES`
* `EXCHANGE_OPERATIONS`
## Instituições suportadas por Open Finance
Aqui está uma comparação do suporte das **instituições brasileiras** entre Open Finance e conectores Diretos. Cada contexto é um conector separado com seu próprio id: para BTGPactual, o lado de Open Finance é BTGPactual (675), BTGPactual Empresas (655), BTGPactual Investimentos (614) e BTGPactual Investimentos Empresas (779), e o lado direto é o conector de investimento BTGPactual (214).
| Instituição | Conector Open Finance | Conector Direto |
| --------------------------- | ------------------------------- | ------------------ |
| Itau | Pessoal, Empresarial | Pessoal, Empresarial |
| Bradesco | Pessoal, Empresarial | Pessoal, Empresarial |
| Caixa | Pessoal, Empresarial | Pessoal, Empresarial |
| Santander | Pessoal, Empresarial | Empresarial |
| Banco do Brasil | Pessoal, Empresarial | Empresarial |
| Nubank | Pessoal, Empresarial | Nenhum |
| BTGPactual | Pessoal, Empresarial, Investimentos | Investimentos |
| Sicredi | Pessoal, Empresarial | Empresarial |
| Sicoob | Pessoal, Empresarial | Nenhum |
| Banrisul | Pessoal, Empresarial | Empresarial |
| Mercado Pago | Pessoal, Empresarial | Pessoal |
| Itau Cartoes | Nenhum | Pessoal |
| Banco Bmg | Pessoal, Empresarial | Nenhum |
| Unicred | Pessoal, Empresarial | Nenhum |
| XP Investimentos | Pessoal, Empresarial | Pessoal, Empresarial |
| Next | Pessoal, Empresarial | Nenhum |
| PicPay | Pessoal, Empresarial | Nenhum |
| Banco PAN | Pessoal | Empresarial |
| Banco Digio | Pessoal | Nenhum |
| Banco do Nordeste do Brasil | Pessoal, Empresarial | Empresarial |
| Uber Conta by Digio | Pessoal | Nenhum |
| Woop | Pessoal | Nenhum |
| Investimentos BB | Investimentos | Nenhum |
| Agora Investimentos | Investimentos, Empresarial | Nenhum |
| Ion | Investimentos | Nenhum |
| Modal Mais | Nenhum | Pessoal |
| Safra | Pessoal, Empresarial | Nenhum |
| Cora | Nenhum | Empresarial |
| Citi | Empresarial | Nenhum |
| Safra Financeira | Pessoal, Empresarial | Nenhum |
| Banco Sofisa | Pessoal, Empresarial | Nenhum |
| Banco BV | Pessoal, Empresarial | Nenhum |
| Meliuz | Pessoal | Nenhum |
| Rico Investimentos | Investimentos | Nenhum |
| Clear Corretora | Investimentos | Nenhum |
| Bradescard | Pessoal | Nenhum |
| InfinitePay | Pessoal, Empresarial | Nenhum |
| Caixa Tem | Pessoal | Pessoal |
| Necton | Pessoal | Investimentos |
| RecargaPay | Pessoal, Empresarial | Nenhum |
| Stone Pagamentos | Pessoal, Empresarial | Nenhum |
| Itau BBA | Empresarial | Nenhum |
| Toro Investimentos | Investimentos, Empresarial | Nenhum |
| Santander Cartoes | Pessoal, Empresarial | Nenhum |
| Porto Bank | Pessoal, Empresarial | Nenhum |
| Neon | Pessoal | Nenhum |
| EQI | Investimentos | Investimentos |
| Rede Celcoin | Pessoal, Empresarial | Nenhum |
| Santander Corretora | Investimentos | Nenhum |
| PagueVeloz (Serasa) | Pessoal, Empresarial | Nenhum |
| Itau Emps | Empresarial | Nenhum |
| C6 Bank | Pessoal, Empresarial | Nenhum |
| PagBank | Pessoal, Empresarial | Nenhum |
| Inter | Pessoal, Empresarial | Pessoal, Empresarial |
| Midway | Pessoal | Nenhum |
| Banco BRB | Pessoal, Empresarial | Pessoal |
| Banco Mercantil | Pessoal, Empresarial | Nenhum |
| Banco Master | Pessoal | Nenhum |
| Cartao Sam's Club | Pessoal | Nenhum |
| Cartao Atacadao | Pessoal | Nenhum |
| Cartao Carrefour | Pessoal | Nenhum |
| 99Pay | Pessoal | Nenhum |
| QI SCD | Pessoal, Empresarial | Nenhum |
| Crefisa | Pessoal, Empresarial | Nenhum |
| Porto Bank Empresas | Empresarial | Nenhum |
| Monte Bravo | Investimentos | Nenhum |
| Azimut | Pessoal | Nenhum |
Conectores de Investimento que não foram mencionados aqui, e outros tipos como Economia Digital e Processadores de Pagamento, não são atualmente suportados por Open Finance, mas têm Conectores Diretos disponíveis.
Confira a documentação de [Cobertura de Conectores](/docs/connectors-coverage) para todos os Conectores Diretos suportados.
Nossa API oferece o endpoint `/connectors?isOpenFinance=true` que descreve todas as Instituições Financeiras suportadas para conexões Reguladas de Open Finance. Cada conector pode suportar produtos diferentes, valide cada um usando a lista de `products` retornada pela instituição. Novos conectores aparecerão automaticamente neste endpoint, então as informações estarão sempre atualizadas em nossa API.
## Usando Conectores de Open Finance na minha Aplicação
Uma vez que você tenha o Open Finance habilitado para o seu plano, para adicionar um Conector de Open Finance, siga estes passos:
1. Vá para Dashboard -> Customização
2. Encontre os conectores de Open Finance e adicione-os à sua lista de conectores Pessoal, Empresarial ou de Investimento
Os conectores de Open Finance terão uma tag de Open Finance e aparecerão como "\[OF]" na lista de conectores selecionados.
Agora, os usuários poderão escolher essas instituições no Pluggy Connect (elas se parecem com qualquer conector habitual).
## Limites de Taxa de Open Finance
Acesse o seguinte link: [Limites de Taxa Operacional](/docs/open-finance/rate-limits)
## Cobertura de Instituições de Open Finance
Source: https://docs.pluggy.ai/pt/docs/open-finance/institutions-coverage.md
A tabela abaixo lista todas as instituições disponíveis via Open Finance, os contextos em que estão disponíveis (Pessoal / Empresarial / Investimentos) e quais produtos cada conector expõe. A cobertura de produtos é mostrada como a união entre todos os contextos — um produto marcado com 🟢 pode estar disponível apenas em um contexto específico (por exemplo, Pessoal ou Empresarial).
Cada contexto é um conector separado com seu próprio id. Por exemplo, a linha do BTGPactual cobre BTGPactual (675) e BTGPactual Empresas (655), e a linha do BTGPactual Investimentos cobre BTGPactual Investimentos (614) e BTGPactual Investimentos Empresas (779).
| Institution | OF Context | Accounts | Transactions | Credit Cards | Investments | Inv. Transactions |
| --------------------------- | --------------------- | -------- | ------------ | ------------ | ----------- | ----------------- |
| 6P Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| 99Pay | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Ágora Investimentos | Empresarial, Investimentos | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 |
| Apex | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| ASA | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| Atlanta | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Axiis Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Banco Bmg | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco BRB | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco Digio | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco do Brasil | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco do Nordeste do Brasil | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco Guanabara | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| Banco Master | Pessoal | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| Banco Mercantil | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco PAN | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco Sofisa | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banrisul | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| BPO Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Bradescard | Pessoal | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 |
| Bradesco | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| BTGPactual | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| BTGPactual Investimentos | Empresarial, Investimentos | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| BV - Corporate | Empresarial | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| BV - Pessoa Física - APP | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| BV - Pessoa Física - Web | Pessoal | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| C6 Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| CAIXA - clientes sem conta | Pessoal, Empresarial | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 |
| Caixa Econômica Federal | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Caixa Tem | Pessoal | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| Cartão Atacadão | Pessoal | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 |
| Cartão Carrefour | Pessoal | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| Cartão Sam's Club | Pessoal | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 |
| CEAPE BANK | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Celcoin Baas | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Cielo | Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Citi | Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Clear Corretora | Investimentos | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Concept | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Conta Bemol | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Conta Universal | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| CRB Money | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Dezbrazil | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| DMX | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Ease Bankly | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Ella Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| EMCASH | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| EQI | Investimentos | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| ESBank | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Exclusive | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Fixxbank | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Genius | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Giffty | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Gift Premium | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Glorya | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| GoalBox | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Gold Pass | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| GS3 | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| H+ plus | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| HausBank | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Health Cash | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Hiperbanco | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Hyak Bank | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Ibanx | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| iHold | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| IlevaCard | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Imobi Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Incentivale | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| InfinitePay | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Inova | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Inter | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Investimentos BB | Investimentos | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| Íon | Investimentos | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| Itaú | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Itaú BBA | Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Itaú Emps | Empresarial | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| JoyCard | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Lemon | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Lothus | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Mais Todos | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Mark Up | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Meirelles | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Méliuz | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Mercado Pago | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Meu Premio | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Meu Premio 360 | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Midway | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Monte Bravo | Investimentos | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Moovi | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| MOTTU | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Multipremium | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Necton | Pessoal | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| Neon | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Next | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Nitybank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Nubank | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Omnion | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Onn Marketing | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Ovni | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| P2x | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| PagBank | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Pague Veloz Serasa | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| PayCard | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| PicPay | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| PicPay Negócios | Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Player's Bank | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Pocket | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Porto Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| POWPAY | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Prix | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Pulse | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| QI SCD | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Rapidium Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| RecargaPay | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Rede Celcoin | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| RelacionaMais | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Resolve Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Rhiza Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Rico Investimentos | Investimentos | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Safra | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Safra Financeira | Pessoal, Empresarial | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 |
| Santander | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Santander Cartões | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Santander Corretora | Investimentos | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 |
| SEMEC BANK | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Sicoob | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Sicredi | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Simpbank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Smart | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Snob Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Spin | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Stone Pagamentos | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| Suppero | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Tokpay | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Toro Investimentos | Empresarial, Investimentos | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 |
| Uber Conta by Digio | Pessoal | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 |
| Unicred | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Unique | Pessoal | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Uze | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Won Bank | Pessoal, Empresarial | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Woop | Pessoal | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| XP Banking | Pessoal, Empresarial | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
Os Conectores de Investimento que não foram mencionados aqui, e outros tipos como Economia Digital e Processadores de Pagamento, não são atualmente suportados pelo Open Finance, mas têm Conectores Diretos disponíveis.
Confira a documentação sobre a [Cobertura de Conectores](/docs/connectors-coverage) para todos os Conectores Diretos suportados.
Nossa API oferece o endpoint `/connectors?isOpenFinance=true` que descreve todas as Instituições Financeiras suportadas para conexões Reguladas de Open Finance.
Cada conector pode suportar produtos diferentes, valide cada um usando a lista `products` retornada pela instituição.
Novos conectores aparecerão automaticamente neste endpoint, então as informações estarão sempre atualizadas em nossa API.
Para detalhes oficiais dos participantes por marca, confira também o diretório de participantes do Open Finance Brasil, como a [página do participante Ailos](https://openfinancebrasil.org.br/quem-participa/?marca=ailos&modalidade=).
## Criando um Item
Source: https://docs.pluggy.ai/pt/docs/open-finance/creating-item.md
Como criar sua primeira conexão Regulada de Open Finance, passo a passo através do Connect Widget da Pluggy ou através da API.
## Conectando um Item com Open Finance através do Pluggy Connect
Quando um usuário se conecta através do Open Finance, o processo de login é diferente de um _Direct Connector_.
Primeiro, o usuário é solicitado a informar seu CPF (para conectores pessoais) ou CNPJ.
Em seguida, o usuário é levado à página de login do Open Finance da instituição (com um pop-up) para completar o processo de login.
Esta etapa depende da instituição: pode solicitar que o usuário escaneie um QR, ou oferecer um link que abre o aplicativo da instituição diretamente, pedir credenciais, etc.
Após o login, o usuário é solicitado a selecionar as informações que compartilhará.
Depois que o usuário aceita compartilhar essas informações, o pop-up é fechado e ele é levado de volta à tela de conexão, enquanto o conector termina de recuperar os dados.
Esse fluxo é resolvido de forma padrão no Pluggy Connect. Se você não estiver usando o Pluggy Connect, consulte o guia no final desta página.
## Conectando um Item com Open Finance através da API
Use esta abordagem se você não usar o Pluggy Connect e quiser se conectar usando a API da Pluggy.
Criar itens de Open Finance pela API é possível, mas a Pluggy recomenda o widget Pluggy Connect: ele mantém o fluxo de conexão em conformidade com os requisitos de Open Finance e atualizado com as mudanças da instituição, sem trabalho da sua parte.
Uma vez que o recurso de Open Finance esteja habilitado para o seu plano, siga estas etapas:
1. Obtenha o ID do conector para o Conector de Open Finance de sua escolha. No endpoint /connectors você verá eles começando com ID 600 e superiores. Por exemplo, o Conector de Open Finance do Itau tem ID 601.
2. Crie um Item para o ID desse conector. Ele exigirá CPF ou CNPJ dependendo se é um conector Pessoal ou Empresarial.
3. Siga a documentação do [Pluggy OAuth v2](/docs/connect-an-account#oauth-v2) para completar o login. Com esse fluxo, a partir do Item criado você obterá uma URL para abrir para o usuário, que o transferirá para o login da instituição. A URL pode não estar na resposta do `POST /items`: pode levar alguns segundos a mais para aparecer, então consulte [GET /items/\{id\}](/reference/items-retrieve) até que o parâmetro do item do tipo `oauth` a contenha. **Nota**: O usuário terá alguns minutos para abrir a URL antes que ela expire. Depois, ele terá 20' para passar pelo fluxo completo na página da instituição.
4. Uma vez que o usuário complete o login, ele é redirecionado para um endpoint de callback do Pluggy OAuth que inicia a conexão no Item automaticamente.
5. Recupere os dados do Item.
O link para acessar o banco e completar o fluxo de consentimento é um link de uso único. Ao enviar este link através de aplicativos de mensagens (Slack, WhatsApp, Google Meet, etc.), o aplicativo de mensagens visita primeiro o link e, portanto, pode invalidá-lo antes que o usuário o acesse. Certifique-se de que este link chegue ao usuário sem essas interações acontecendo primeiro, ou então ele mostrará uma tela de erro.
### Conta de Teste de Open Finance
Para se conectar usando nossa conexão de sandbox, veja [Fluxo de Open Finance no Sandbox](/docs/sandbox#7---open-finance-flow).
## Considerações e FAQ
Source: https://docs.pluggy.ai/pt/docs/open-finance/considerations-faq.md
Things to keep in mind when integrating Open Finance Regulated data that can be different from Direct Connections.
## Cartões de Crédito
As transações de cartão de crédito se comportam de maneira diferente em cada instituição; como regra geral, as instituições fornecerão novas compras diariamente e, uma vez que a fatura estiver fechada/vencida, retornará todas as transações associadas a ela.
### Parcelas Futuras
Quando um usuário faz várias parcelas de uma compra, as instituições se comportam de maneiras diferentes.
- A maioria das instituições retornará a primeira parcela nas atualizações diárias; essa informação é retornada quando recuperamos as informações semanais das transações atuais.
- BTGPactual Investimentos (614), as parcelas futuras (número da parcela >= 2) são recuperadas na primeira conexão com o status `PENDING`.
Todas as transações serão atualizadas para postadas, com seu correspondente **billId** uma vez que a fatura esteja fechada.
### Parcelas
- Algumas instituições, como XP Banking (602), podem mostrar transações para a compra completa da operação feita em parcelas. Isso será a soma de todas as parcelas e nunca terá um **billId**.
### Faturas
Devido a uma limitação da API das Instituições Financeiras, faturas abertas não são retornadas até que as faturas estejam fechadas ou vencidas (isso depende da FI).
Uma vez que a fatura é retornada, todas as transações terão a relação `billId` atribuída. Até que a fatura apareça na FI, não poderemos criar a `Bill` nem vinculá-la ao seu correspondente `billId`.
Além disso, algumas transações são retornadas apenas na lista de transações da fatura, então serão retornadas uma vez que a fatura tenha aparecido na FI (ou seja, Parcelas Futuras).
**_Nota_**: _Vencido significa que passou da data de vencimento, não relacionado ao status de pagamento._
### Conta Corrente
Transações que estão bloqueadas ou sendo processadas aparecerão como `PENDING` até que as transações sejam concluídas. O número de dias que esse processo pode levar varia entre instituições e tipos de transações. Quando a transação está bloqueada, ela será somada ao `blockedBalance` da conta. Uma vez que as transações tenham sido processadas (Compensado), elas aparecerão como postadas, e o saldo mudará de `blockedBalance` para o `balance` da conta.
#### Pagamentos Programados
As instituições de Open Finance podem expor os pagamentos programados da conta (boletos, transferências e débitos que o usuário já programou, `LANCAMENTO_FUTURO` na especificação de Open Finance) até uma janela que cada instituição define. Para os conectores listados abaixo, a Pluggy solicita essa janela em cada sincronização e retorna os pagamentos programados como transações com `status: PENDING` e uma `date` no futuro. Eles não afetam o `balance` da conta até que sejam liquidadas.
| Conector | Janela |
|-----------|--------|
| Itaú (601) | 90 dias à frente |
| Itaú Empresas (618) | 90 dias à frente |
| C6 Bank (626) | 90 dias à frente |
| C6 Bank Empresas (726) | 90 dias à frente |
Quando o pagamento é liquidado, a transação se torna `POSTED` como uma atualização no local (`transactions/updated`, mesmo `id`): ou a instituição manteve o mesmo `providerId`, ou — a especificação de Open Finance permite que mude nesse momento — a Pluggy vinculou a transação liquidada à programada por valor e data. Se a programação for cancelada, a transação `PENDING` é excluída (`transactions/deleted`) na primeira sincronização após sua data programada.
Do seu lado, `status: POSTED` é o que já aconteceu; `status: PENDING` com uma `date` após hoje é o que está por vir.
Contas correntes têm um limite rígido de 260 recursos; além desse limite, as contas não são coletadas e um aviso será adicionado nos detalhes do status do item. Se você tiver mais contas, entre em contato com o suporte.
## Diferenças conhecidas entre conectores
### XP
| | Regulado | Direto |
| --- | --- | --- |
| Auto-sync | Sim | Não (PJ são atualizáveis) |
| MFA | Não | Sim (PJ não) |
| Ativos COE | Não | Sim |
| Ativos de Segurança | Não | Sim |
| Tempo de transações de investimento (INITIAL_UPDATE) | 1 ano | 4 anos |
| Total de retiradas de investimentos antes da primeira conexão | Não | Sim |
| Transações de portabilidade de ativos | Não | Sim |
## Perguntas Frequentes (FAQ)
- _Na primeira conexão, os conectores de Open Finance retornam investimentos totalmente retirados?_
- Não, apenas investimentos ativos no momento da primeira conexão são retornados. A partir desse ponto, se você retirar totalmente um desses investimentos, ele mudará de status para TOTAL_WITHDRAWAL.
- _O Itau PJ OF (618) retorna transações consolidadas (SISPAG CONSOLIDADO, PIX QRS CONSOLIDADO) ou transações detalhadas?_
- Ele sempre retorna transações **detalhadas**, com o CPF / CNPJ da contraparte dentro do paymentData.
- O que acontece quando o consentimento de um **Item** expira?
- Os metadados do item ainda estariam disponíveis, mas os dados do usuário não estariam disponíveis. Os clientes serão obrigados a solicitar um novo consentimento de seu usuário no item existente para renovar o consentimento. Veja [Consents Docs](/docs/consents) para mais informações.
## Cobertura de Dados de Pagamento Open Finance
Source: https://docs.pluggy.ai/pt/docs/open-finance/payment-data.md
Para conectores de Open Finance, a disponibilidade do CPF/CNPJ da contraparte de uma transação (em seus [dados de pagamento](/docs/transactions#transaction-payment-data-schema)) dependerá do tipo de operação da transação (como PIX, TED, BOLETO, etc).
Para os seguintes tipos, **não se espera** receber Dados de Pagamento para **qualquer instituição**:
- **PACOTE_TARIFA_SERVIÇOS, TARIFA_SERVIÇOS_AVULSOS, ENCARGOS_JUROS_CHEQUE_ESPECIAL**, porque o beneficiário é a própria instituição.
- **PORTABILIDADE_SALARIO**, porque o beneficiário é o próprio titular da conta.
- **RENDIMENTO_APLIC_FINANCEIRA, RESGATE_APLIC_FINANCEIRA, SAQUE**: porque não se qualificam como operações de "pagamento".
Para os seguintes tipos, espera-se que a informação da contraparte esteja ausente em **casos específicos**:
- **TED, PIX, BOLETO, CONVENIO_ARREDACACAO, FOLHA_PAGAMENTO**, para operações em lote, a informação da contraparte não está disponível.
- **DEPOSITO**, para pagamentos abaixo de R$2000, a informação da contraparte não está disponível.
- **CARTAO**
- **Pagamentos de contas**: a informação da contraparte está disponível.
- **Cartões de débito e pré-pagos**: a informação da contraparte não está disponível.
Para mais detalhes, por favor, leia a [documentação de Open Finance sobre informações da contraparte](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/193658890/Orienta+es+-+DC+Contas).
## Cobertura de dados de pagamento da contraparte
A tabela a seguir fornece o status de cobertura para dados de contraparte CPF/CNPJ com base no conector, tipo de operação e tipo de transação (DEBITO ou CREDITO):
- 🟢 - dados da contraparte estão presentes mais de 90% do tempo
- 🟠 - dados da contraparte estão presentes apenas condicionalmente (menos de 90% do tempo)
- 🔴 - dados da contraparte estão **nunca** presentes (0%)
- (-) - o conector não retorna transações com esse operationType
| Conector | PIX (Cr) | PIX (Dr) | TED (Cr) | TED (Dr) | DOC (Cr) | DOC (Dr) | BOLETO (Cr) | BOLETO (Dr) | CARTAO (Cr) | CARTAO (Dr) | CONV_ARR (Cr) | CONV_ARR (Dr) | DEPOSITO (Cr) | DEPOSITO (Dr) | FOLHA_PAG (Cr) | FOLHA_PAG (Dr) | OP_CRED (Cr) | OP_CRED (Dr) | OUTROS (Cr) | OUTROS (Dr) | TRANSF_MI (Cr) | TRANSF_MI (Dr) |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Itau (601) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🟠 | 🟠 | 🔴 | 🔴 | 🟠 | 🟠 | 🟠 | 🔴 | 🟢 | 🔴 | 🟠 | 🟠 | 🟠 | 🟠 | 🟠 | 🟠 |
| XP Banking (602) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | 🔴 | 🔴 | - | 🔴 | - | - | - | - | 🔴 | 🔴 | 🟠 | 🟠 | 🟢 | - |
| Bradesco (603) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🔴 | 🟢 | 🟠 | 🔴 | 🔴 | 🟠 | 🟠 | 🟠 | 🟠 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🟢 | 🟢 |
| Rico Investimentos (605) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | 🔴 | 🔴 | - | 🔴 | - | - | - | - | 🔴 | 🔴 | 🟠 | 🟠 | - | - |
| Mercado Pago (606) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🟢 | 🟢 | - | - | - | - | 🟢 | - | - | - | 🟢 | - | 🟠 | 🟠 | 🟢 | 🟢 |
| Santander (608) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | 🔴 | 🟠 | 🟠 | 🟠 | 🟠 | - | 🟢 | - | 🔴 | - | 🟠 | 🟠 | 🟢 | 🟢 |
| Bradesco Empresas (609) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🔴 | 🟢 | 🟢 | 🔴 | - | 🟠 | 🟠 | 🟠 | 🔴 | 🟠 | 🔴 | 🔴 | 🟠 | 🟠 | 🟠 | 🟢 |
| Banco do Brasil (611) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | - | 🟢 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🟢 | 🟢 |
| Nubank (612) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | 🟠 | - | - | - | - | - | 🟠 | 🔴 | 🔴 | 🔴 |
| BTGPactual Investimentos (614) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | 🔴 | - | - | - | - | - | 🔴 | 🔴 | 🟢 | 🟢 |
| Caixa Economica Federal Empresas (616) | 🟢 | 🟢 | 🟠 | 🟠 | - | - | 🔴 | 🟠 | 🔴 | 🟠 | 🟠 | 🟠 | 🔴 | 🔴 | - | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🟠 | 🟠 |
| Itau Empresas (618) | 🟢 | 🟢 | 🟠 | 🔴 | - | - | 🔴 | 🟠 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🔴 | 🔴 | 🟠 | 🟠 | 🟠 | 🟠 | 🟢 | 🟠 | 🟠 |
| Caixa Economica Federal (619) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🔴 | 🟢 | 🔴 | 🟠 | 🟠 | 🟠 | 🔴 | - | 🟢 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🟢 | 🟢 |
| Santander Empresas (621) | 🟢 | 🟢 | 🟢 | 🟠 | - | - | - | - | 🔴 | 🟠 | 🟠 | 🟠 | 🟠 | - | - | - | 🟠 | - | 🟠 | 🟠 | 🟠 | 🟢 |
| Clear Corretora (623) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟠 | 🟠 | - | - |
| C6 Bank (626) | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟢 | 🟠 | - | - |
| Sicredi Empresas (627) | 🟢 | 🟢 | 🟢 | 🟠 | - | - | - | - | 🔴 | 🟠 | 🔴 | 🟠 | 🟠 | 🔴 | - | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🟢 | 🟢 |
| Sicoob Empresas (628) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | - | 🔴 | 🟢 | 🟢 | 🟢 | - | 🟢 | 🟢 | - | - | - | - | - | 🟢 | 🟠 | 🟢 | 🟢 |
| Safra (629) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | 🔴 | 🔴 | - | 🟠 | 🔴 | - | 🟢 | - | - | - | 🔴 | 🔴 | 🟢 | 🟢 |
| Iti (638) | 🟢 | 🟢 | 🟢 | - | - | - | - | - | 🔴 | 🔴 | - | 🟢 | - | - | 🟢 | - | - | - | 🟢 | 🟠 | - | - |
| PicPay (651) | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | 🔴 | - | 🟢 | - | 🔴 | 🔴 | 🟠 | 🟠 | 🟠 | 🟢 |
| Banco Bmg (652) | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | 🟢 | - | - | - | 🟢 | 🟢 | 🟢 | - |
| Banco Digio (653) | 🟢 | 🟢 | - | - | - | - | - | - | 🔴 | 🔴 | - | - | - | - | - | - | - | - | 🟠 | 🔴 | - | - |
| BTGPactual Empresas (655) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🟢 | 🟠 | 🔴 | 🔴 | - | 🔴 | 🔴 | - | - | - | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 |
| Next (656) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | 🔴 | 🔴 | - | 🟠 | 🟠 | - | 🟢 | - | - | - | 🟠 | 🟠 | 🟢 | 🟠 |
| Banco PAN (657) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | 🔴 | - | - | - | 🟠 | 🔴 | 🟠 | 🟠 | - | - |
| Sicoob (658) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🟢 | - | - | - | - | 🟢 | - | 🟢 | - | - | - | 🟢 | 🟢 | 🟢 | 🟢 |
| Banrisul (659) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | 🟢 | 🟢 | 🟢 | - | 🟢 | - | 🔴 | - | 🟠 | 🟠 | 🟢 | 🟢 |
| Banrisul Empresas (660) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🔴 | 🟢 | - | 🟢 | 🟢 | 🟠 | 🟢 | - | - | 🟠 | 🔴 | - | 🟢 | 🟠 | 🟢 | 🟢 |
| Sicredi (661) | 🟢 | 🟢 | 🟢 | 🟠 | - | - | - | - | 🔴 | 🟠 | 🔴 | 🟠 | 🟠 | 🔴 | 🟠 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🟠 | 🟠 |
| Banco do Brasil Empresas (662) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟠 | 🔴 | - | 🔴 | 🔴 | 🔴 | 🔴 | 🟠 | 🟢 | 🟢 |
| Unicred (663) | 🔴 | 🔴 | 🔴 | 🟠 | - | - | 🔴 | 🔴 | 🔴 | 🔴 | - | - | 🔴 | 🔴 | - | - | - | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Nubank Empresas (664) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🔴 | 🟠 | - | - | - | - | 🟠 | - | - | - | - | - | 🟠 | 🔴 | 🔴 | - |
| Mercado Pago Empresas (665) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🟠 | 🟢 | - | - | - | - | 🟢 | - | - | - | - | - | 🟠 | 🟠 | 🟢 | 🟢 |
| Unicred Empresas (670) | 🔴 | 🔴 | 🔴 | 🟠 | - | - | 🔴 | 🔴 | 🔴 | 🔴 | - | - | 🔴 | 🔴 | - | - | - | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco do Nordeste do Brasil (671) | 🟢 | 🟠 | 🟠 | 🟢 | - | - | - | - | 🔴 | 🔴 | - | 🟢 | 🔴 | - | - | - | 🔴 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 |
| Banco do Nordeste do Brasil Empresas (672) | 🟢 | 🟠 | 🟠 | 🟢 | - | - | - | - | 🔴 | 🔴 | - | 🟠 | 🔴 | - | - | - | 🔴 | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 |
| Investimentos BB (673) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | 🔴 | 🟢 | 🟠 | - | 🟢 | - | 🔴 | 🔴 | 🔴 | 🟠 | 🟠 | 🟢 |
| Uber Conta by Digio (674) | 🟢 | 🟢 | - | - | - | - | 🔴 | 🟠 | 🔴 | 🔴 | - | - | - | - | - | - | - | - | 🟢 | 🔴 | - | - |
| BTGPactual (675) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🟢 | 🟠 | 🔴 | 🔴 | - | - | 🔴 | - | 🟢 | - | - | - | 🔴 | 🔴 | 🟢 | 🟢 |
| Ion (677) | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟠 | 🟠 | - | - |
| Neon (689) | 🔴 | 🔴 | 🔴 | - | - | - | 🔴 | - | 🔴 | 🔴 | - | - | - | - | 🔴 | - | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | - |
| Safra Empresas (697) | 🟢 | 🟢 | 🟢 | 🔴 | - | - | - | - | 🔴 | 🔴 | - | 🟠 | 🔴 | - | - | - | - | - | 🔴 | 🔴 | 🟢 | 🔴 |
| XP Banking Empresas (702) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟠 | 🟠 | - | 🟢 |
| Banco Paulista (705) | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| Banco Sofisa (714) | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟠 | 🟠 | - | - |
| BV - Pessoa Fisica - APP (716) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | 🟢 | 🟢 | - | 🟢 | - | - | - | - | - | - | - | - | 🟢 | 🟢 | 🟢 | 🟢 |
| BV - Corporate (718) | - | - | - | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| Meliuz (720) | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| RecargaPay (767) | 🔴 | 🔴 | - | - | - | - | - | - | - | - | - | - | 🔴 | - | - | - | 🔴 | 🔴 | 🔴 | 🔴 | - | - |
| RecargaPay Empresas (768) | 🔴 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🔴 | - | - | - |
| InfinitePay (777) | 🟠 | 🟠 | - | - | - | - | - | - | 🔴 | 🔴 | - | - | - | - | - | - | - | - | 🔴 | 🔴 | - | - |
| InfinitePay Empresas (778) | 🟠 | 🟠 | - | - | - | - | - | - | 🔴 | 🔴 | - | - | - | - | - | - | 🔴 | 🔴 | 🔴 | 🔴 | - | - |
| BTGPactual Investimentos Empresas (779) | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🔴 | 🔴 | - | 🟢 |
| Caixa Tem (783) | 🟢 | 🟢 | - | - | - | - | - | - | 🔴 | 🔴 | 🔴 | 🟠 | 🔴 | - | - | - | 🔴 | - | 🟠 | 🟠 | - | - |
| Itau Emps (786) | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟢 | - |
| Stone Pagamentos (787) | - | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟢 | 🟠 | - | - |
| Stone Pagamentos Empresas (788) | - | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟠 | 🟠 | - | - |
| Necton (793) | 🟢 | - | - | - | - | - | - | - | - | - | - | - | 🔴 | - | - | - | - | - | 🔴 | 🔴 | - | - |
| Itau BBA (794) | 🟢 | 🟢 | 🟢 | 🔴 | - | - | - | - | 🔴 | 🔴 | - | 🟠 | 🟠 | - | - | - | 🔴 | 🔴 | 🟠 | 🟢 | 🟠 | - |
| Monte Bravo (795) | 🟢 | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟠 | 🟢 | - | - |
| Porto Bank (800) | 🟢 | 🟢 | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🟠 | 🟢 | - | - |
| EQI (802) | 🟢 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🔴 | 🔴 | - | - |
| 99Pay (804) | - | 🔴 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 🔴 | 🔴 | - | - |
| Inter (823) | - | 🟢 | - | 🔴 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
## Cobertura de Investimentos em Open Finance
Source: https://docs.pluggy.ai/pt/docs/open-finance/investments.md
Para Open Finance, cada instituição suporta certos **subtipos** de investimento (veja [Tipos e Subtipos de Investimentos](/docs/products/investments#investments-types--subtypes)).
Aqui está uma tabela que indica se o subtipo de investimento é suportado (🟢) ou não (🔴), dependendo da instituição:
Cada linha é um conector de Open Finance, identificado pelo seu id. O BTG possui quatro, um por `tipo` de conector: BTGPactual (675, `PERSONAL_BANK`), BTGPactual Empresas (655, `BUSINESS_BANK`), BTGPactual Investimentos (614, `INVESTMENT`) e BTGPactual Investimentos Empresas (779, `BUSINESS_BANK`). A cobertura pertence ao id do conector, não à marca.
| Conector | BDR (EQUITY) | REAL_ESTATE_FUND (EQUITY) | STOCK (EQUITY) | ETF (ETF) | CDB (FIXED_INCOME) | CRA (FIXED_INCOME) | CRI (FIXED_INCOME) | DEBENTURES (FIXED_INCOME) | LCA (FIXED_INCOME) | LCI (FIXED_INCOME) | TREASURY (FIXED_INCOME) | EXCHANGE_FUND (MUTUAL_FUND) | FIXED_INCOME_FUND (MUTUAL_FUND) | INVESTMENT_FUND (MUTUAL_FUND) | MULTIMARKET_FUND (MUTUAL_FUND) | STOCK_FUND (MUTUAL_FUND) | FIP_FUND (MUTUAL_FUND) |
| :-------------------------------------- | :----------- | :-------------------------- | :------------- | :-------- | :------------------ | :------------------ | :------------------ | :------------------------- | :------------------ | :------------------ | :----------------------- | :---------------------------- | :--------------------------------- | :------------------------------ | :------------------------------- | :------------------------- | :----------------------- |
| Itaú (601) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| XP Banking (602) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Bradesco (603) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Rico Investimentos (605) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Mercado Pago (606) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Santander (608) | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Bradesco Empresas (609) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Banco do Brasil (611) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Nubank (612) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| BTGPactual Investimentos (614) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Caixa Econômica Federal Empresas (616) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Itaú Empresas (618) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Caixa Econômica Federal (619) | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Ágora Investimentos (620) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Santander Empresas (621) | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Clear Corretora (623) | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Sicredi Empresas (627) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Sicoob Empresas (628) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Safra (629) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| PicPay (651) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Banco Bmg (652) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco Digio (653) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| BTGPactual Empresas (655) | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Next (656) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Banco PAN (657) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Sicoob (658) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Banrisul (659) | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Banrisul Empresas (660) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Sicredi (661) | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Banco do Brasil Empresas (662) | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Unicred (663) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Nubank Empresas (664) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Unicred Empresas (670) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco do Nordeste do Brasil (671) | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Banco do Nordeste do Brasil Empresas (672) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Investimentos BB (673) | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| BTGPactual (675) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Safra Empresas (697) | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| XP Banking Empresas (702) | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Banco Sofisa (714) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🔴 |
| BV - Pessoa Física - APP (716) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| BV - Corporate (718) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Ágora Investimentos Empresas (781) | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Necton (793) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Monte Bravo (795) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Toro Investimentos (796) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Inter (823) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| C6 Bank (626) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| PagBank (692) | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| C6 Bank Empresas (726) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🔴 | 🔴 |
| PagBank Empresas (816) | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Íon (677) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Neon (689) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Sandbox Open Finance | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 |
| InfinitePay (777) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| EQI (802) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Inter Empresas (824) | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Stone Pagamentos Empresas (788) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| BTGPactual Investimentos Empresas (779) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🔴 |
| Méliuz (720) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Uber Conta by Digio (674) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco BRB (817) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🟢 | 🔴 |
| Stone Pagamentos (787) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| InfinitePay Empresas (778) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Itaú BBA (794) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Midway (688) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Santander Corretora (812) | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco Sofisa Empresas (715) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Mercado Pago Empresas (665) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Banco BRB Empresas (818) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🟢 | 🟢 | 🔴 | 🔴 | 🔴 |
| Banco Mercantil (742) | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
| Toro Investimentos Empresas (797) | 🟢 | 🔴 | 🔴 | 🔴 | 🟢 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 | 🔴 |
Alguns bancos, como NuBank e PicPay, têm opções de investimento chamadas "Cofrinhos" e "Caixinhas", que se configuram como CDBs. Assim, eles estão cobertos pela conexão e devem aparecer na seção de investimentos também.
## Limites de Taxa Operacional
Source: https://docs.pluggy.ai/pt/docs/open-finance/rate-limits.md
## Limites de Taxa do Open Finance
Existem dois tipos diferentes de limites envolvidos quando a Pluggy recupera dados: limites de taxa da API da Pluggy e limites operacionais do Open Finance impostos pelas instituições financeiras.
A Rede Brasileira de Open Finance impõe **limites operacionais** sobre o número de vezes **por mês** que qualquer pessoa usando Open Finance pode buscar cada **produto**. Esses limites não vêm da Pluggy; eles restringem com que frequência a Pluggy pode sincronizar dados. Eles se aplicam por combinação de CPF/CNPJ, instituição e produto (ou seja, cartão, conta, investimento ou empréstimo).
A Pluggy gerencia os limites de taxa, para que você não precise se preocupar com isso.
Sob o uso normal dos Conectores do Open Finance (um CPF e instituição **em apenas um item**), você **não precisará se preocupar com Limites de Taxa**, já que você nunca os alcançaria, mesmo que tivesse atualizações automáticas habilitadas em todos os seus itens, atualizando até 4 vezes por dia.
No entanto, tenha em mente que se você conectar o mesmo CPF/CNPJ à mesma instituição criando múltiplos itens, você atingirá a limitação do Open Finance mais rapidamente, o que significa que alguns produtos não estarão atualizando/retornando seus dados até que o limite seja renovado no próximo mês. Quando não estiver usando um item, **inicie a exclusão** dele para evitar a sincronização automática.
### Contas (Corrente e Poupança)
| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Lista e detalhes da conta | 4 | Criação do item e a cada 7 dias |
| Saldo da conta | 420 | A cada atualização * |
| Transações recentes (1 a 6 dias atrás) | 240 | A cada atualização * |
| Transações não recentes (7 a 365 dias atrás) | 4 | Criação do item e a cada 7 dias |
\* Cada Atualização significa que cada execução que o item faz.
**Considerações**
- Após 240 solicitações, novas transações não aparecerão até o próximo mês.
- Após 420 solicitações, o saldo da conta não será atualizado até o próximo mês.
- Em cada atualização, ambas as solicitações são consumidas, e atualmente, não é suportado apenas recuperar o saldo. Se necessário, crie uma conexão que apenas recuperaria o produto **CONTAS**, enviando no array `products` o produto desejado.
### Cartões de Crédito
| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Lista e detalhes do cartão de crédito | 4 | Criação do item e a cada 7 dias |
| Faturas de cartão de crédito & transações de fatura | 30 | Criação do item e uma vez por dia |
| Limites de cartão de crédito | 240 | A cada atualização * |
| Transações recentes (1 a 6 dias atrás) | 240 | A cada atualização * |
| Transações não recentes (7 a 365 dias atrás) | 4 | Criação do item e a cada 7 dias |
\* Cada Atualização significa que cada execução que o item faz.
**Considerações**
- Se um novo cartão de crédito aparecer como autorizado, pode levar até 7 dias para aparecer nas respostas.
- Transações de fatura de cartão de crédito (faturas fechadas e passadas) serão atualizadas diariamente.
- Limites de cartão de crédito e novas transações serão sincronizados em cada atualização.
- Após 240 atualizações, isso tem uma média de 8 atualizações por dia. Ele atingirá os limites de taxa e não atualizará transações até o próximo mês.
### Investimentos
| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Lista de investimentos | 30 | Criação do item e uma vez por dia |
| Detalhe do investimento | 4 | Criação do item e a cada 7 dias |
| Saldo do investimento | 120 | A cada atualização * |
| Transações de Investimento (Recentes - 1 a 6 dias atrás) | 120 | A cada atualização * |
| Transações de Investimento (Histórico - 7 a 365 dias atrás) | 4 | Criação do item e sob demanda. |
\* Cada Atualização significa que cada execução que o item faz.
**Considerações**
- Se um item for atualizado 120 vezes antes do final do mês, novas transações ou saldos não serão sincronizados até o dia 1 do próximo mês.
- Detalhes recuperam a taxa do ativo, rateType, fixedAnnualRate, etc. Essas informações não devem mudar e são recuperadas na criação. Se houver uma mudança por algum motivo, será refletida após 7 dias daquela atualização.
- Se um novo investimento foi adquirido, mas o limite de taxa já foi atingido, ele não aparecerá até o próximo mês.
### Outros produtos
| Produto | Solicitações mensais permitidas | Momentos em que buscamos este produto |
| --- | --- | --- |
| Identidade | 4 | Criação do item e a cada 7 dias |
| Lista e Detalhe de Empréstimos | 4 | Criação do item e a cada 7 dias |
| Parcelas de Empréstimos | 30 | Criação do item e uma vez por dia |
| Pagamentos de Empréstimos | 30 | Criação do item e uma vez por dia |
- Empréstimos serão atualizados diariamente; se um item for atualizado mais de uma vez por dia, não sincronizará os dados do empréstimo.
- As informações de identidade são recuperadas na criação do item e sincronizarão atualizações a cada 7 dias. Se houver algum dado pessoal atualizado, não refletirá mudanças até que execute uma sincronização após 7 dias da sincronização inicial.
## Entendendo um item que atingiu o limite de taxa
### Como o limite de taxa é retornado como um aviso?
Quando um limite de taxa é atingido, você verá o Item no status **PARTIAL_SUCCESS** e dentro do detalhe do status, um aviso sobre o produto que falhou:
```json
{
"id": "44534b0e-717e-497d-890f-08c2faa468c1",
"status": "PARTIAL_SUCCESS",
"statusDetail": {
"accounts": {
"warnings": [
{
"code": "423",
"message": "Limite mensal de taxa do Open Finance atingido no produto 'accounts' para este CPF/CNPJ e instituição. O produto não pôde ser atualizado."
}
],
"isUpdated": false,
"lastUpdatedAt": "2023-10-19T19:19:58.188Z"
}
}
}
```
## Tempo de resposta e timeout
Os limites operacionais mensais não são o único requisito não funcional que a Rede Brasileira de Open Finance impõe às instituições. Dois outros importam quando uma sincronização falha porque a instituição foi lenta para responder, e eles são frequentemente confundidos um com o outro:
| Requisito | Limite | O que mede |
| --- | --- | --- |
| **Timeout** | **15 segundos** | Quanto tempo o cliente espera por uma única solicitação antes de desistir. Espera-se que a instituição responda com `504 Gateway Timeout` quando atinge seu próprio timeout. |
| **Desempenho** | P95 abaixo de **1.500 ms** (endpoints de alta e média-alta frequência), **2.000 ms** (média frequência), **4.000 ms** (baixa frequência) | O percentil 95 do tempo de resposta da instituição, medido em todo o seu tráfego diário naquele endpoint. |
A Pluggy aplica o **timeout de 15 segundos da rede a cada solicitação de Open Finance à instituição, em cada conector** — não há valor por instituição ou por produto. Quando uma instituição não responde dentro desse intervalo, abortamos a solicitação; o produto afetado não é atualizado e um aviso é adicionado ao `statusDetail` do Item, exatamente como mostrado acima para limites de taxa.
O valor de 1.500 ms é uma meta de *desempenho* medida sobre o tráfego agregado de uma instituição — não é um prazo para qualquer solicitação individual. Uma solicitação respondida em 1.600 ms, ou em 9 segundos, está bem dentro do limite de 15 segundos e a Pluggy aguardará por ela e usará a resposta. Apenas solicitações que ultrapassam **15 segundos** são abortadas.
Essa distinção vale a pena ter em mente ao abrir um caso com uma instituição: exceder a meta P95 e exceder o timeout são duas infrações diferentes, com evidências diferentes por trás delas.
## SCR — Sistema de Informação de Crédito
Source: https://docs.pluggy.ai/pt/docs/open-finance/scr.md
O **SCR** (_Sistema de Informações de Crédito_) é o registro oficial das operações de crédito do Banco Central do Brasil. Todas as instituições financeiras do país reportam a ele: empréstimos, financiamentos, limites, garantias e co-obrigação. É a própria fonte, não uma pontuação inferida a partir dela.
A Pluggy expõe o SCR por trás de um item conectado de Open Finance. O item fornece o CPF ou CNPJ e serve como evidência do consentimento do titular da conta.
O SCR está disponível sob solicitação. Fale conosco para habilitá-lo em sua
assinatura — sem isso, o endpoint retorna `SCR_FEATURE_NOT_ENABLED`.
Qualquer consulta ao SCR depende da autorização prévia do titular das operações de crédito. Sua instituição é responsável por solicitar essa autorização e por atender aos pré-requisitos de consulta, mensagens de esclarecimento e ao registro e armazenamento das autorizações estabelecidas na regulamentação vigente — veja
[Resolução CMN n°
5.037](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=RESOLU%C3%87%C3%83O%20CMN&numero=5037).
## Requisitos
Antes da primeira chamada:
1. O **recurso SCR** habilitado em sua assinatura.
2. Um item conectado de **Open Finance** — um [sandbox](#testing-in-the-sandbox) também funciona. Conectores diretos não são elegíveis.
3. O **CPF ou CNPJ** desse item conhecido por nós — é com isso que consultamos o Bacen.
Um item que falhar em qualquer um dos últimos dois retorna `SCR_ITEM_NOT_SUPPORTED`.
## Consultar o SCR
```
GET /items/{id}/scr
```
| Parâmetro | Em | Descrição |
| --------- | ----- | ------------------------------------------------- |
| `id` | path | O item cujo titular da conta você deseja consultar |
| `from` | query | Primeira data-base, no formato `YYYYMM`. Opcional |
| `to` | query | Última data-base, no formato `YYYYMM`. Opcional |
```bash
curl --request GET \
--url 'https://api.pluggy.ai/items/d0e8448e-0156-4b4a-ae6c-3e2a6d9bff5c/scr?from=202604&to=202607' \
--header 'X-API-KEY: YOUR_API_KEY'
```
Detalhes completos sobre parâmetros e esquema estão na [referência da API](/reference/scr/items-retrieve-scr).
## Datas-base são meses, e elas têm atraso
O SCR não funciona em dias. O Bacen consolida uma **data-base** (_data-base_) por mês, e cada uma só se torna completa alguns meses depois — as instituições ainda estão entregando seus relatórios nesse meio tempo.
Duas consequências que vale a pena considerar:
- **Solicitar o mês atual não retorna nada.** O Bacen ainda não o fechou.
- **Quando você omite `from` e `to`**, a Pluggy consulta as últimas 4 datas-base, terminando 2 meses atrás a partir de hoje. Em setembro de 2026, isso é de `202604` a `202607`.
Se você enviar apenas um limite, a janela se ancla nele: `?to=202501` retorna de `202410` a `202501`.
Cada data-base carrega `docProc` e `volProc` — a porcentagem de documentos esperados e volume já incorporados. Uma data-base recente com baixa cobertura é uma imagem parcial, não uma vazia.
## Resposta
A resposta é o próprio payload do Bacen, encaminhado sem alterações. Os nomes dos campos, códigos e estrutura são do SCR, então um valor que você lê aqui é o mesmo valor que uma instituição lê na fonte.
```json
{
"dtbConsult": "202604 a 202607",
"cdCli": "11222333",
"tpCli": "2",
"lsDtb": [
{
"dtb": 202607,
"docProc": "99.8",
"volProc": "99.9",
"qtdIfs": 4,
"qtdCongFinc": 3,
"dtbIniRel": "201803",
"coobAss": 0,
"coobRec": 0,
"lsOp": [
{
"mod": "0203",
"oriRec": "0101",
"indx": "01",
"varCamb": "00",
"resVenc": { "v20": 12500.0, "v40": 12500.0, "v110": 37500.0 },
"lsGar": [{ "tp": "0501", "qtd": 1 }]
}
]
}
]
}
```
### Nível superior
| Campo | Tipo | Descrição |
| ----------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `dtbConsult` | string | As datas-base consultadas |
| `cdCli` | string | O documento consultado: o CPF para um indivíduo, ou a **raiz do CNPJ de 8 dígitos** para uma empresa |
| `tpCli` | string | `"1"` para um indivíduo, `"2"` para uma entidade legal |
| `lsDtb` | array | Uma entrada por data-base consultada. Uma data-base sem dados ainda é listada |
| `listaDeMensagensDeValidacao` | array | Mensagens de validação levantadas pelo Bacen para a solicitação, cada uma com um `codigo` e uma `mensagem` |
### Dentro de uma data-base (`lsDtb[]`)
| Campo | Tipo | Descrição |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `dtb` | number | A data-base, no formato `YYYYMM`. Numérico, não uma string |
| `msg` | string | Mensagem do Bacen para esta data-base, quando houver uma |
| `docProc` | string | Porcentagem dos 3040 documentos esperados já incorporados pelo Bacen, excluindo instituições isentas |
| `volProc` | string | Porcentagem do volume de operações esperado já aceito para a data-base |
| `qtdIfs` | number | Número de instituições financeiras onde o titular possui operações |
| `qtdCongFinc` | number | Número de conglomerados financeiros. Compare com `qtdIfs` para distinguir a verdadeira diversificação de contraparte da aparente |
| `dtbIniRel` | string | Início do relacionamento do titular com o sistema financeiro nacional |
| `coobAss` | number | Co-obrigação assumida pelo titular em atribuições de crédito, em BRL |
| `coobRec` | number | Co-obrigação recebida em atribuições de crédito, em BRL |
| `lsOp` | array | Grupos de operações |
### Dentro de um grupo de operações (`lsOp[]`)
O SCR não retorna contratos um por um. As operações são **agregadas** pela combinação de modalidade, fonte de recursos, índice e variação cambial, então uma entrada pode representar vários contratos da mesma natureza.
| Campo | Tipo | Descrição |
| ---------- | ------ | ---------------------------------------------------------------------------------------------- |
| `mod` | string | Código da modalidade — que tipo de crédito é |
| `oriRec` | string | Código da fonte de recursos |
| `indx` | string | Código da taxa de referência ou índice |
| `varCamb` | string | Código da variação da taxa de câmbio |
| `subJDisc` | string | Presente quando a operação está sob disputa: `"D"` desacordo, `"J"` sub judice, `"JD"` ambos |
| `resVenc` | object | Saldos divididos por vértices de maturidade — veja abaixo |
| `lsGar` | array | Garantias que respaldam o grupo, por tipo (`tp`) e quantidade (`qtd`) |
| `lsInfAd` | array | Informações complementares reportadas para o grupo, por tipo (`tp`), código (`cd`) e quantidade (`qtd`) |
Os códigos por trás de `mod`, `oriRec`, `indx`, `varCamb` e `tp` são próprios do Bacen. Seu significado é publicado na referência **DOC3040** — leia-os lá em vez de inferi-los.
### Vértices de maturidade (`resVenc`)
`resVenc` distribui o saldo do grupo em 30 vértices, em BRL. Cada chave é um código de maturidade do Bacen — `v20`, `v40`, `v60`, `v80`, `v110`, `v120`, `v130`, `v140`, `v150`, `v160`, `v165`, `v170`, `v175`, `v180`, `v190`, `v199`, `v205`, `v210`, `v220`, `v230`, `v240`, `v245`, `v250`, `v255`, `v260`, `v270`, `v280`, `v290`, `v310` e `v320` — e apenas os vértices que carregam um valor estão presentes. Eles se dividem em três famílias:
| Família | O que significa |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ainda não vencido** | Pagamentos cuja data ainda não chegou. O limite é generoso — um pagamento até **14 dias** atrasado ainda conta aqui, então pequenos atrasos operacionais não são lidos como inadimplência. Mede compromisso, não problemas: o que importa é a forma da curva ao longo do tempo |
| **Atrasado** | Pagamentos mais de 14 dias atrasados, classificados em categorias progressivamente mais antigas. Duas dívidas do mesmo valor, uma 20 dias atrasada e outra 200, são situações opostas. Leia a **migração entre categorias** mês a mês: valor descendo a escada é recuperação, subindo é uma inadimplência em progresso |
| **Categorias especiais** | Alguns vértices não são janelas de tempo; representam estados ou compromissos que não se encaixam na régua de maturidade |
A janela exata por trás de cada código individual é definida no layout DOC3040, em sua tabela de códigos de maturidade (_Código de Vencimento_). Leia lá: o número na chave é um código, não uma contagem de dias, então não infira uma janela a partir disso. Sem essa tabela, você ainda pode somar a exposição total e separar saldos ainda não vencidos de atrasados; construir uma curva de envelhecimento precisa das janelas código por código.
## Testando no sandbox
Você pode integrar o SCR sem uma conta real. Crie um item com o
conector de **Open Finance Sandbox** (`600`) usando um dos
[CPFs de sandbox](/docs/guides/sandbox#7--open-finance-flow), então chame `GET /items/{id}/scr` como de costume.
Um item de sandbox retorna um payload **sintético** com o mesmo esquema que a produção. `cdCli` é
o documento do item, `tpCli` o segue, e `lsDtb` tem uma entrada por data-base na
janela solicitada — a janela padrão se aplica quando `from` e `to` são omitidos. Cada data-base
carrega alguns grupos de operações, com garantias e saldos em `resVenc`, e é marcada com
`msg: "Dados sintéticos - sandbox da Pluggy"` para que um payload sintético nunca possa ser confundido com um
real.
A resposta do sandbox é gerada, não consultada: nenhuma solicitação chega ao Bacen e a chamada não é
cobrada. O mesmo item e janela sempre retornam os mesmos valores, então você pode afirmar
contra eles em testes automatizados.
As verificações são as que você encontrará na produção. O recurso SCR deve estar habilitado em sua
assinatura (`SCR_FEATURE_NOT_ENABLED` caso contrário), o item deve ser Open Finance — os conectores de sandbox do Pluggy
retornam `SCR_ITEM_NOT_SUPPORTED` — e um intervalo invertido retorna
`SCR_INVALID_REQUEST`. Um limite exclusivo do sandbox: uma janela maior que **60 datas-base** também
é rejeitada com `SCR_INVALID_REQUEST`.
## Erros
| Status | Código | O que significa |
| ------ | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| 400 | `SCR_INVALID_REQUEST` | O intervalo de datas-base foi rejeitado. Verifique se `from` e `to` estão no formato `YYYYMM` e se `from` não está após `to`. A mensagem de erro pode se referir a eles como `databaseIni` e `databaseFim` |
| 403 | `SCR_FEATURE_NOT_ENABLED` | O SCR não está habilitado em sua assinatura |
| 404 | `ITEM_NOT_FOUND` | Nenhum item desse tipo, ou sua autorização foi revogada |
| 422 | `SCR_ITEM_NOT_SUPPORTED` | O item não é uma conexão de Open Finance, ou seu CPF/CNPJ está faltando ou malformado |
| 500 | `SCR_FETCH_ERROR` | Não conseguimos completar a consulta |
| 502 | `SCR_SERVICE_UNAVAILABLE` | O serviço SCR do Bacen está indisponível. Tente novamente mais tarde |
Um `502` carrega um `correlationId` sob `data`. Cite-o quando você relatar a falha para nós — é o que nos permite rastrear a consulta exata.
```json
{
"code": 502,
"codeDescription": "SCR_SERVICE_UNAVAILABLE",
"message": "O serviço SCR do Bacen está temporariamente indisponível. Por favor, tente novamente mais tarde.",
"data": { "correlationId": "8047f6e9-bb9e-4b04-8515-e2210dc4c544" }
}
```
O serviço SCR do Bacen tem interrupções prolongadas. Projete para `502` — tente novamente com
retrocesso, e não trate uma consulta indisponível como uma ausência de histórico de crédito.
## Conta
Source: https://docs.pluggy.ai/pt/docs/products/accounts.md
O produto **conta** é a lista de contas bancárias, como Conta Corrente ou Conta Poupança e Cartão de Crédito, que estavam disponíveis no conector selecionado.
A resposta variará dependendo do Tipo de Contas, fornecendo um objeto `data` relacionado ao seu tipo `bankData` ou `creditData`.
```json title="Bank"
{
"id": "a658c848-e475-457b-8565-d1fffba127c4",
"type": "BANK",
"subtype": "CHECKING_ACCOUNT",
"number": "0001/12345-0",
"name": "Conta Corrente",
"marketingName": "GOLD Conta Corrente",
"balance": 120950,
"itemId": "a0922d6f-2007-4169-a181-b961500608db",
"taxNumber": "333.333.333-33",
"owner": "John Doe",
"currencyCode": "BRL",
"bankData": {
"transferNumber": "123/0001/12345-0",
"closingBalance": 120950,
"automaticallyInvestedBalance": 100,
"overdraftContractedLimit": 0,
"overdraftUsedLimit": 0,
"unarrangedOverdraftAmount": 0
}
}
```
```json title="Credit"
{
"id": "4f61bd6d-e6fc-44b2-9c4b-5609058de7ab",
"type": "CREDIT",
"subtype": "CREDIT_CARD",
"name": "Itau Uniclass 2.0 Mastercard Platinum",
"marketingName": "Itau Uniclass 2.0 Mastercard Platinum",
"taxNumber": "***.***.123-22",
"owner": "FEDERICO MIRAS",
"number": "1234",
"balance": 142.41,
"itemId": "fc214524-4725-4974-9f7a-0f1b50ea39e0",
"currencyCode": "BRL",
"creditData": {
"level": "PLATINUM",
"brand": "MASTERCARD",
"brandAdditionalInfo": null,
"balanceCloseDate": "2020-07-08",
"balanceDueDate": "2020-07-17",
"availableCreditLimit": 51300,
"creditLimit": 51800,
"isLimitFlexible": false,
"balanceForeignCurrency": 500,
"minimumPayment": 100,
"status": "ACTIVE",
"holderType": "MAIN"
}
}
```
| Propriedade | Descrição | Necessário |
|-------------|-----------|------------|
| id | Identificador único do modelo de Conta, usado para recuperar transações relacionadas | Sim |
| type | Tipo de conta (BANK / CREDIT). | Sim |
| subtype | O subtipo de conta (`CHECKING_ACCOUNT` / `SAVINGS_ACCOUNT` / `CREDIT_CARD`). | Sim |
| number | Para tipo **BANK**, este campo retorna o número da conta. Ex: 12345-6 (ou 12345-6/500 em algumas contas poupança). Para tipo **CREDIT**, este campo retorna os últimos quatro dígitos do cartão de crédito. Ex: 1234. Para conectores com tipo **PAYMENT_ACCOUNT**, o número representa o número da conta de destino do fundo. | Sim |
| balance | Para tipo **BANK**, este campo retorna o saldo disponível atual da conta. Para tipo **CREDIT**, este campo retorna o valor do saldo atual da fatura em aberto ainda não paga. Para conectores com tipo **PAYMENT_ACCOUNT**, o saldo só pode ser retornado em contas digitais, não em contas externas. Mais detalhes [aqui](#balance). | Sim |
| currencyCode | Código ISO da moeda da conta, ex: USD ou EUR | Sim |
| name | Nome da conta, ex: Conta Poupança 1234 ou Mastercard Gold. | Sim |
| marketingName | O nome extra fornecido para algumas contas que estão relacionadas ao nível da conta. Nem sempre fornecido. | |
| owner | Nome do proprietário da conta. | |
| taxNumber | Número de identificação fiscal formatado do proprietário da conta (CPF ou CNPJ). Para conectores com tipo **PAYMENT_ACCOUNT**, taxNumber representa o CNPJ da empresa conectada. A disponibilidade varia de acordo com o conector. Para alguns conectores empresariais (por exemplo, Bradesco PJ, Caixa PJ), contas sob o mesmo itemId podem retornar diferentes valores de `taxNumber`, uma vez que o valor vem da empresa selecionada ou diretamente da API da instituição. | |
| bankData | Dados específicos para tipos de conta bancária. | |
| creditData | Dados específicos para tipos de conta de crédito. | |
### Saldo
Os saldos das Contas Bancárias (Corrente e Poupança) representam o montante que o titular atualmente possui disponível para gastar. Se esse valor for negativo, representa uma dívida que o titular tem com a instituição financeira, um exemplo disso seria um cheque especial.
Os saldos dos Cartões de Crédito são o montante devido à instituição, isso significaria o saldo em aberto do mês atual do usuário. Se a fatura anterior foi paga com um valor excedente, o saldo retornaria um valor negativo.
Para conectores de Open Finance, o saldo do Cartão de Crédito é o limite utilizado para aquele cartão de crédito.
Contas do tipo crédito podem aproveitar o `availableCreditLimit` para consolidar uma visão 360 dos cartões de crédito.
`creditLimit` = `availableCreditLimit` (ainda a gastar) + `balance` (saldo em aberto) + dívida do saldo anterior.
### Saldos de contas bancárias em Open Finance
Para conectores de Open Finance, a instituição relata o montante disponível de uma conta bancária e, quando os possui, o montante bloqueado e o montante automaticamente investido. Nem toda instituição relata os dois últimos, então trate-os como opcionais. A Pluggy os mapeia assim:
| Campo | Valor |
|-------|-------|
| `balance` | O montante disponível. |
| `bankData.closingBalance` | `balance` + o montante bloqueado (o saldo contábil). `null` se a instituição não reporta um montante bloqueado. |
| `bankData.automaticallyInvestedBalance` | O montante automaticamente investido, inalterado. `null` se a instituição não o reporta. |
A soma em `closingBalance` é a mesma para cada conector de Open Finance. O que muda para algumas instituições é qual montante é usado como `balance`.
**Itaú e Banco do Brasil.** No Itaú PF (601), Itaú PJ (618), Banco do Brasil PF (611) e Banco do Brasil PJ (662), quando o montante automaticamente investido é maior que zero, ele é usado como `balance` em vez do montante disponível, e `closingBalance` é calculado a partir disso. Essas instituições relatam o dinheiro mantido no investimento automático (investimento automático do Itaú, Rende Fácil do Banco do Brasil) separadamente do montante disponível: algumas enviam o mesmo valor em ambos, outras enviam zero como disponível e o montante total como automaticamente investido. Em ambos os casos, o titular da conta vê esse montante como seu saldo no aplicativo do banco, então é isso que `balance` retorna. `automaticallyInvestedBalance` ainda retorna o montante exatamente como reportado.
**Cheque especial.** Se `balance` for zero e a conta tiver cheque especial em uso (`overdraftUsedLimit` maior que zero), `balance` é retornado como o negativo do cheque especial utilizado. Isso se aplica ao saldo coletado quando o item é sincronizado; o [endpoint de saldo em tempo real](/docs/products/real-time-balance) retorna os montantes da instituição sem esse ajuste.
Use `balance` para o montante que o titular pode gastar. Use `closingBalance` quando precisar do saldo contábil incluindo montantes bloqueados. Não adicione `automaticallyInvestedBalance` a `balance` no Itaú ou Banco do Brasil: quando é maior que zero, já é o `balance`.
## Dados bancários
| Propriedade | Descrição |
|-------------|-----------|
| transferNumber | Este campo retorna a informação mais importante da conta: COMPE / Agência / Conta. Ex.: 123 / 1234 / 12345-6 |
| closingBalance | Saldo contábil da conta. Para conectores de Open Finance, é sempre `balance` + o montante bloqueado reportado pela instituição, e é `null` quando a instituição não reporta um montante bloqueado. Não é o saldo de fechamento do dia anterior. Veja [Saldos de contas bancárias em Open Finance](#bank-account-balances-on-open-finance). |
| automaticallyInvestedBalance | Montante que a instituição automaticamente investiu da conta (por exemplo, investimento automático do Itaú ou Rende Fácil do Banco do Brasil), retornado exatamente como a instituição o reporta. |
| overdraftContractedLimit | Montante do limite de cheque especial contratado. |
| overdraftUsedLimit | Montante total utilizado do limite especial de cheque e do adiantamento ao depositante. |
| unarrangedOverdraftAmount | Valor da operação contratada em caráter emergencial para cobrir saldo pendente em conta de depósito à vista e excesso sobre o limite de cheque especial acordado. |
## Dados de Crédito
| Propriedade | Descrição |
|-------------|-----------|
| minimumPayment | Pagamento mínimo do saldo para o período atual. |
| balanceForeignCurrency | Saldo em moeda estrangeira para o período atual. |
| availableCreditLimit | O limite de crédito disponível para a conta ainda a gastar. |
| creditLimit | O limite de crédito para a conta. |
| isLimitFlexible | Se o cartão de crédito é ilimitado. |
| balanceDueDate | Data de Vencimento do saldo para a conta do cartão. (aaaa-mm-dd) |
| balanceCloseDate | Data de fechamento quando o saldo foi calculado. (aaaa-mm-dd) |
| level | Nível do tipo de cartão (Black, Signature, etc). |
| brand | Marca do cartão (Mastercard, Visa, Elo, etc). |
| brandAdditionalInfo | Texto livre especificando a categoria da marca quando `brand` é `OTHER`. *Disponível apenas em conectores de Open Finance.* |
| status | Status do cartão (ACTIVE, BLOCKED, CANCELLED). Para *conectores regulamentados* retornamos apenas **ACTIVE**, significando que o status do cartão ainda está sendo recuperado da FI. |
| holderType | Tipo de titular do cartão (MAIN ou ADDITIONAL) |
## Limites de Crédito Desagregados
Alguns cartões de crédito podem ter múltiplas linhas de crédito ou diferentes modalidades de operação. O campo `disaggregatedCreditLimits` fornece informações detalhadas sobre cada linha de crédito para ajudá-lo a identificar corretamente o cartão principal e calcular saldos precisos.
### Quando Usar Limites Desagregados
Use este recurso quando você encontrar:
- Saldos de cartões de crédito incorretos
- Múltiplas linhas de crédito no mesmo cartão
- Diferentes modalidades de operação com limites separados
### Estrutura
`disaggregatedCreditLimits` vive dentro de `creditData` e é um array de objetos, um por linha de crédito:
```json
{
"creditData": {
"disaggregatedCreditLimits": [
{
"creditLineLimitType": "LIMITE_CREDITO_TOTAL",
"consolidationType": "INDIVIDUAL",
"identificationNumber": "1000",
"isLimitFlexible": false,
"usedAmount": 149.84,
"usedAmountCurrencyCode": "BRL",
"lineName": "CREDITO_A_VISTA",
"limitAmount": 1000.0,
"limitAmountCurrencyCode": "BRL",
"customizedLimitAmount": 2000.0,
"customizedLimitAmountCurrencyCode": "BRL",
"availableAmount": 850.16,
"availableAmountCurrencyCode": "BRL"
}
]
}
}
```
### Campos Chave
| Campo | Tipo | Descrição | Exemplo |
|-------|------|-----------|---------|
| `creditLineLimitType` | string | Tipo de limite de crédito | `"LIMITE_CREDITO_TOTAL"` ou `"LIMITE_CREDITO_MODALIDADE_OPERACAO"` |
| `consolidationType` | string | Indica se o limite é consolidado ou individual | `"INDIVIDUAL"` ou `"CONSOLIDATED"` |
| `identificationNumber` | string | Número de identificação adicional do cartão de crédito | `"1000"` |
| `isLimitFlexible` | boolean | Indica se o limite é flexível | `false` |
| `usedAmount` | number | Montante utilizado do cartão de crédito adicional | `149.84` |
| `usedAmountCurrencyCode` | string | Código da moeda do montante utilizado | `"BRL"` |
| `lineName` | string | Nome da linha de limite de crédito. Um dos `CREDITO_A_VISTA`, `CREDITO_PARCELADO`, `SAQUE_CREDITO_BRASIL`, `SAQUE_CREDITO_EXTERIOR`, `EMPRESTIMO_CARTAO_CONSIGNADO`, `OUTROS` | `"CREDITO_A_VISTA"` |
| `lineNameAdditionalInfo` | string | Texto livre descrevendo a linha quando `lineName` é `OUTROS` | `"SAQUE_CREDITO"` |
| `limitAmount` | number | Montante do limite adicional do cartão de crédito | `1000.00` |
| `limitAmountCurrencyCode` | string | Código da moeda do limite | `"BRL"` |
| `limitAmountReason` | string | Razão pela qual o montante total do limite reportado é zero | `"Limite zerado após análise"` |
| `customizedLimitAmount` | number | Montante total do limite personalizado pelo cliente através dos canais eletrônicos da instituição | `2000.00` |
| `customizedLimitAmountCurrencyCode` | string | Código da moeda do montante do limite personalizado | `"BRL"` |
| `availableAmount` | number | Montante disponível do cartão de crédito adicional | `850.16` |
| `availableAmountCurrencyCode` | string | Código da moeda do montante disponível | `"BRL"` |
Veja [Contas](/reference/account) em nossa referência da API para mais informações.
## Saldo em Tempo Real
Source: https://docs.pluggy.ai/pt/docs/products/real-time-balance.md
O endpoint de saldo em tempo real busca o saldo da conta diretamente da instituição financeira sem acionar uma sincronização completa de itens. Isso é útil quando você precisa de informações de saldo atualizadas entre ciclos de sincronização regulares.
```
GET /accounts/{id}/balance
```
```json
{
"balance": 1500.50,
"blockedBalance": 0,
"automaticallyInvestedBalance": 200,
"closingBalance": 1500.50,
"currencyCode": "BRL",
"updateDateTime": "2024-01-15T10:30:00Z"
}
```
| Campo | Descrição |
|-------|-------------|
| `balance` | Saldo disponível da conta. Mesmo valor que `balance` no [recurso da conta](/reference/accounts-retrieve). |
| `blockedBalance` | Valor atualmente bloqueado ou retido na conta. Presente apenas quando a instituição o reporta. |
| `automaticallyInvestedBalance` | Valor mantido na instalação de investimento automático da conta. Presente apenas quando a instituição o reporta. |
| `closingBalance` | Saldo contábil da conta: `balance` mais `blockedBalance`. Mesmo valor que `bankData.closingBalance` no recurso da conta. Presente apenas quando a instituição o reporta. |
| `currencyCode` | Moeda dos valores acima. |
| `updateDateTime` | Quando a instituição atualizou pela última vez o saldo. |
O valor de `balance` retornado por este endpoint é calculado usando a mesma lógica que uma execução completa de itens, incluindo a regra do Itaú e Banco do Brasil para valores automaticamente investidos. A única exceção é o ajuste de cheque especial: uma execução completa retorna `balance` como o negativo do cheque especial utilizado quando a instituição reporta zero e o cheque especial está em uso, e este endpoint não faz isso. Veja [Saldos de contas bancárias no Open Finance](/docs/products/accounts#bank-account-balances-on-open-finance).
Quando você chama este endpoint, o recurso da conta é atualizado com o que a instituição respondeu: `balance`, e, quando reportado, `bankData.closingBalance` e `bankData.automaticallyInvestedBalance`. Qualquer solicitação subsequente `GET /accounts/{id}` reflete os valores buscados pela chamada de saldo em tempo real, de modo que ambos os endpoints permanecem consistentes sem esperar pela próxima sincronização. Valores que a instituição não reportou permanecem como a última sincronização os armazenou.
`blockedBalance`, `automaticallyInvestedBalance` e `closingBalance` são omitidos da resposta quando a instituição não os reporta. Trate-os como opcionais na sua integração.
Este endpoint está disponível apenas para **conectores Open Finance**. Chamá-lo em contas não Open Finance retornará um erro.
**Limitação de taxa:** O limite de taxa para este endpoint é **compartilhado com a execução completa de itens**. Solicitações ao endpoint de saldo em tempo real e sincronizações de itens contam para a mesma cota de limite de taxa imposta pela instituição financeira. Se a instituição limitar a taxa da solicitação, você receberá uma resposta `429`.
| Código de Resposta | Descrição |
|--------------------|-------------|
| `200` | Saldo buscado e conta atualizada |
| `404` | Conta não encontrada para o ID fornecido |
| `429` | Limite de taxa imposto pela instituição financeira -- tente novamente mais tarde |
| `500` | Erro ao buscar o saldo do conector |
Veja [Obter saldo em tempo real](/reference/account-balance-get) na referência da API para mais detalhes.
## Contas de Cartão de Crédito
Source: https://docs.pluggy.ai/pt/docs/products/credit-card-bills.md
A entidade **Bill** é recuperada de instituições que suportam este produto. Ela representa uma fatura (fatura) associada a uma conta do tipo "Crédito", especificamente o subtipo `CREDIT_CARD`. A fatura representa cada fatura que o provedor do cartão envia ao usuário no final do mês com os detalhes da dívida, os impostos envolvidos no período e quando vence.
Esta entidade é retornada obrigatoriamente para todas as instituições FI em conexões Open Finance Reguladas. Para conexões Open Finance Diretas, ela é retornada apenas em Inter PF & Itau Cartoes.
```json
{
"id": "76edd0fa-57b4-4391-be8d-e8b6249d04b1",
"dueDate": "2023-09-15T00:00:00.000Z",
"totalAmount": 10000.76,
"totalAmountCurrencyCode": "BRL",
"minimumPaymentAmount": 3000,
"allowsInstallments": true,
"payments": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"valueType": "FULL_PAYMENT",
"paymentDate": "2023-09-15T00:00:00.000Z",
"paymentMode": "PIX",
"amount": 10000.76,
"currencyCode": "BRL"
}
],
"financeCharges": [
{
"id": "6119c3e0-706c-4a7a-a734-0fc7a0a94bdb",
"type": "IOF",
"amount": 7.01,
"currencyCode": "BRL",
"additionalInfo": "NA"
},
{
"id": "3cd450a1-79d1-43fd-a5ea-f77b3fca960d",
"type": "OTHER",
"amount": 0,
"currencyCode": "BRL",
"additionalInfo": "NA"
}
]
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| id | string | Não | Identificador primário |
| dueDate | string | Não | Data de vencimento da fatura, exibida para pagamento pelo cliente |
| totalAmount | number | Não | Valor total da fatura |
| totalAmountCurrencyCode | string | Não | Código que referencia a moeda da fatura |
| minimumPaymentAmount | number | Sim | Valor mínimo de pagamento da fatura |
| allowsInstallments | boolean | Sim | Indica se a fatura permite pagamentos parcelados (true) ou não (false) |
| financeCharges | array | Não | Lista de encargos associados à fatura ([CreditCardBillFinanceCharge](#credit-card-bill-finance-charge)) |
| payments | array | Não | Lista de pagamentos associados à fatura ([CreditCardBillPayment](#credit-card-bill-payment)) |
## Encargo Financeiro da Fatura do Cartão de Crédito
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| id | string | Não | Identificador primário |
| type | string | Não | Denominação dos encargos que se aplicam à fatura da conta de pagamento pós-pago: LATE_PAYMENT_REMUNERATIVE_INTEREST, LATE_PAYMENT_FEE, LATE_PAYMENT_INTEREST, IOF, OTHER |
| amount | number | Não | Valor cobrado pelo encargo/taxa |
| currencyCode | string | Não | Código que referencia a moeda do encargo |
| additionalInfo | string | Sim | Campo livre, obrigatório preencher se o tipo de encargo 'OTHER' for selecionado |
## Pagamento da Fatura do Cartão de Crédito
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| id | string | Não | Identificador primário |
| valueType | string | Não | Tipo de pagamento realizado contra a fatura (por exemplo, FULL_PAYMENT, MINIMUM_PAYMENT, OTHER) |
| paymentDate | string | Não | Data em que o pagamento foi realizado |
| paymentMode | string | Não | Modo utilizado para realizar o pagamento (por exemplo, PIX, débito em conta, boleto bancário) |
| amount | number | Não | Valor pago |
| currencyCode | string | Não | Código que referencia a moeda do pagamento |
### Como verificar se uma fatura anterior está quitada
O saldo de uma fatura é considerado quitado quando os pagamentos registrados no **próximo** ciclo de faturamento cobrem o valor total da fatura anterior mais quaisquer encargos financeiros (juros, taxas, etc.) que se acumularam durante esse próximo ciclo:
```
totalAmount(Bill N) + sum(financeCharges(Bill N+1)) = sum(payments(Bill N+1))
```
Onde **N** é a fatura que você deseja verificar e **N+1** é a fatura imediatamente seguinte.
#### Exemplo: verificando a quitação da fatura de janeiro
Suponha que um cliente tenha duas faturas consecutivas: **Janeiro** (Bill N) e **Fevereiro** (Bill N+1).
Para confirmar que o saldo de janeiro foi totalmente pago, a seguinte condição deve ser atendida:
```
totalAmount(Janeiro) + sum(financeCharges(Fevereiro)) = sum(payments(Fevereiro))
```
| Campo | Fonte | Valor |
|-------|-------|-------|
| `totalAmount` | Fatura de janeiro | R$ 500,00 |
| `sum(financeCharges)` | Fatura de fevereiro | R$ 12,50 |
| `sum(payments)` | Fatura de fevereiro | R$ 512,50 |
Como **500,00 + 12,50 = 512,50**, a fatura de janeiro é considerada **quitada**.
## Transações de cartão de crédito e o ciclo de extrato
Source: https://docs.pluggy.ai/pt/docs/products/credit-card-statement-cycle.md
Os dados do cartão de crédito se movem mais do que os dados da conta corrente: as linhas são reavaliadas à medida que a fatura se fecha, as parcelas são re-datadas para o ciclo ao qual pertencem e as compras pendentes são confirmadas. Esta página explica o que isso faz com os `id`s das transações e como reconciliar através disso.
## O que identifica uma transação entre sincronizações
Em cada sincronização, o Pluggy combina as transações que acabou de coletar com as que já armazenou, usando uma única chave:
- **O próprio id da transação da instituição**, quando a conexão fornece um.
- Caso contrário, **um valor derivado da `description`, `amount`, `date` da transação e sua posição entre transações idênticas no mesmo dia.**
A consequência é a parte importante:
| Resultado | O que você recebe | O `id` sobrevive? |
| --- | --- | --- |
| A chave corresponde | `transactions/updated` | **Sim** — a transação armazenada é atualizada no local. |
| A chave não corresponde | `transactions/deleted` para a linha antiga, `transactions/created` para a nova | **Não** — a transação retorna com um novo `id`. |
Portanto, uma mudança na **descrição, valor ou data** de uma transação já armazenada é, por construção, uma transação diferente. É por isso que uma reavaliação em torno do fechamento de uma fatura pode chegar como uma exclusão seguida de uma criação, em vez de uma atualização.
Não há opção de manter o `id` original em uma exclusão e recriação, e a carga útil de `transactions/deleted` carrega apenas os ids que foram removidos — nenhum campo aponta de uma transação excluída para sua substituição. Qualquer integração que trate o `id` do Pluggy como uma chave primária permanente para uma transação de cartão de crédito irá se desviar.
## No que se ancorar em vez disso
**`providerId`** — o próprio id da transação da instituição — é o único identificador estável do lado do provedor que o Pluggy expõe, e é **retornado apenas para conectores de Open Finance**. Em um conector direto, ele é sempre `null`, independentemente de qual seja a instituição.
Isso é importante quando a mesma instituição é acessível de ambas as maneiras. O Itaú, por exemplo, possui tanto conectores diretos quanto de Open Finance: um cartão conectado através do conector direto nunca carrega `providerId`, o mesmo cartão conectado através do Open Finance o faz.
Se você não tiver `providerId`, reconciliar com os atributos da transação — `date` + `amount` + `description` — conforme descrito em [Transactions](/docs/products/transactions), e mantenha seu próprio mapeamento desses atributos para seu registro interno em vez de do `id` do Pluggy.
Veja [Open Finance vs Direct: field differences](/docs/connections/open-finance-vs-direct-fields) para a lista completa de campos que apenas um tipo de conexão preenche.
## Manipulação prática
- **Processar `transactions/deleted` de forma idempotente.** Uma transação pode desaparecer em uma sincronização e voltar em uma posterior, então uma exclusão não é necessariamente final.
- **Rebusque em vez de inferir.** Após qualquer evento de transação, leia o estado atual com [`GET /transactions`](/reference/transactions-list) para a conta afetada em vez de reconstruí-lo a partir do fluxo de eventos.
- **Espere que a janela da fatura seja ampla.** Algumas instituições atribuem uma parcela a uma fatura meses antes da compra, então uma transação de cartão de crédito datada no futuro não é necessariamente um erro.
Se uma linha parou de ser retornada pela instituição ou foi descartada durante a sincronização não é algo que você pode distinguir apenas pela resposta da API. Abra um ticket de suporte com o `itemId`, a conta e as datas envolvidas, e podemos verificar a execução — veja [Reporting issues](/docs/connections/reporting-issues).
## Transação
Source: https://docs.pluggy.ai/pt/docs/products/transactions.md
Recupere até 12 meses de dados de transações.
Os dados das transações das contas fornecem insights sobre o comportamento financeiro do usuário. Essas transações são recuperadas para o produto **Account** ao sincronizar o **item** pela primeira vez e podem ser listadas para todos os tipos de conta `CREDIT` (cartões de crédito e empréstimos) ou `BANK` (conta corrente e poupança).
Você pode revisar mais sobre como recuperar as transações no [endpoint de Transações](/reference/transactions-list-by-cursor). As transações são sempre recuperadas em páginas de 500, usando um mecanismo de paginação baseado em cursor.
Para transações que estão disponíveis em faturas "Abertas" ou são parcelas futuras, o `status` as retornará como `PENDING`, uma vez que a transação ainda não impactou o saldo devedor.
Em contas correntes, `PENDING` também abrange **pagamentos agendados**: instituições de Open Finance que os expõem (veja [Pagamentos agendados](/docs/open-finance/considerations-faq#scheduled-payments)) os retornam como transações `PENDING` cuja `data` está no futuro. Elas se tornam `POSTED` uma vez que o pagamento é liquidado.
| Propriedade | Tipo | Descrição | Obrigatório |
|-------------|------|-----------|-------------|
| date | date | Data de postagem da transação, formatada em ISO8601 (horário UTC). Se for necessário interpretá-la como horário brasileiro, você precisará convertê-la para GMT-3. | Sim |
| description | string | Descrição da transação, texto recuperado da instituição financeira. | Sim |
| descriptionRaw | string | Se disponível, descrição bruta fornecida pela instituição financeira. | |
| amount | number | Valor da transação. *Nota*: Para cartões de crédito, será positivo (débito) quando for uma despesa (acrescenta ao saldo), enquanto será negativo (crédito) quando a pessoa paga a fatura. | Sim |
| amountInAccountCurrency | number | Valor da transação na moeda da conta, se a transação for uma transação internacional. | |
| balance | number | Saldo após a transação ser realizada. *Somente retornado para instituições financeiras suportadas.* | |
| currencyCode | string | Código ISO da moeda da transação, ou seja, BRL, USD. | Sim |
| category | string | null | Categoria das transações, fornecida pelo nosso Categorizer de Enriquecimento. *Nota*: requer nível de assinatura **Pro**. | |
| providerCode | string | Se disponível, código da transação do provedor. | |
| status | string | Status da transação. *PENDING* (não liquidada ainda: uma compra em fatura aberta, uma parcela futura, uma transação de conta corrente bloqueada ou agendada) ou **POSTED** (liquidada). | Sim |
| type | string | Tipo da transação. *DEBIT* (saída) ou **CREDIT** (entrada) | Sim |
| paymentData | object | Dados relacionados ao pagamento/transferência. | |
| creditCardMetadata | object | Dados relacionados a uma transação de cartão de crédito. | |
| merchant | object | null | Dados relacionados ao comerciante associado à transação. *Nota*: requer recurso habilitado e nível de assinatura **Pro**. | |
| operationType | string | null | Tipo de operação classificada pela instituição. Em Open Finance, para transações de conta bancária, o valor pode ser um dos seguintes: `TED` `DOC` `PIX` `TRANSFERENCIA_MESMA_INSTITUICAO` `BOLETO` `CONVENIO_ARRECADACAO` `PACOTE_TARIFA_SERVIÇOS` `TARIFA_SERVIÇOS_AVULSOS` `FOLHA_PAGAMENTO` `DEPOSITO` `SAQUE` `CARTAO` `ENCARGOS_JUROS_CHEQUE_ESPECIAL` `RENDIMENTO_APLIC_FINANCEIRA` `PORTABILIDADE_SALARIO` `RESGATE_APLIC_FINANCEIRA` `OPERACAO_CREDITO` `OUTROS`. Para transações de cartão de crédito: `PAGAMENTO` `PAGAMENTO_FATURA` `TARIFA` `OPERACOES_CREDITO_CONTRATADAS_CARTAO` `ESTORNO` `CASHBACK` `OUTROS`. Exceção: o pagamento da fatura do cartão de crédito que a Pluggy constrói a partir dos dados da fatura quando a instituição não a reporta como uma transação (`Pagamento recebido`) carrega `PAGAMENTO_FATURA`, definido pela Pluggy em vez da instituição. | |
| providerId | string | null | Identificador do provedor para a transação. **Somente retornado para conectores de Open Finance.** | |
```json
{
"total": 1,
"totalPages": 1,
"page": 1,
"results": [
{
"id": "6ec156fe-e8ac-4d9a-a4b3-7770529ab01c",
"description": "Exemplo TED",
"descriptionRaw": null,
"currencyCode": "BRL",
"amount": 1500,
"date": "2021-04-12T00:00:00.000Z",
"balance": 3500,
"category": "Transferência",
"categoryId": "05000000",
"accountId": "03cc0eff-4ec5-495c-adb3-1ef9611624fc",
"providerCode": "123456",
"type": "CREDIT",
"status": "POSTED",
"paymentData": null,
"creditCardMetadata": {
"installmentNumber": 1,
"totalInstallments": 6,
"totalAmount": 9000
},
"merchant": null,
"providerId": null
}
]
}
```
### Convenção de Sinal para Transações de Cartão de Crédito
Transações de cartão de crédito usam a seguinte convenção de sinal para refletir mudanças no saldo do cartão:
- Valores positivos (+X) indicam débitos -- ou seja, novas cobranças que aumentam o saldo devedor (você deve mais).
- Valores negativos (-X) indicam créditos/pagamentos -- ou seja, fundos que reduzem o saldo devedor.
```json
// GET /transactions?from=2025-06-01&to=2025-06-30
[
{
"id": "txn_001",
"date": "2025-06-05",
"description": "Supermercado",
"amount": 75.00
},
{
"id": "txn_002",
"date": "2025-06-10",
"description": "Pagamento de Fatura",
"amount": -150.00
}
]
```
## Esquema de Dados de Pagamento de Transação
Algumas transações que são *Pagamentos* ou *Transferências* podem conter dados relacionados para entender de quem e para quem a operação foi feita, números de referência como Identificador PIX, a razão definida pelo usuário ou o método usado para realizar o movimento.
| Propriedade | Descrição |
|-------------|-----------|
| payer | A identidade do remetente da transferência. |
| receiver | A identidade do destinatário da transferência. |
| referenceNumber | O identificador da transação que é fornecido pela instituição. |
| receiverReferenceId | O identificador fornecido pelo destinatário para rastrear o pagamento. |
| paymentMethod | O tipo de transferência usada "PIX", "TED", "DOC". |
| reason | A descrição/motivo do pagador da transferência. |
| boletoMetadata | Informações do boleto associado ao pagamento. |
```json
{
"payer": {
"name": "Tiago Rodrigues Santos",
"branchNumber": "090",
"accountNumber": "1234-5",
"routingNumber": "001",
"routingNumberISPB": "00000000",
"documentNumber": {
"type": "CPF",
"value": "123.456.789-00"
}
},
"reason": "Taxa de serviço",
"receiver": {
"name": "Pluggy",
"branchNumber": "999",
"accountNumber": "9876-1",
"routingNumber": "002",
"routingNumberISPB": "27652684",
"documentNumber": {
"type": "CNPJ",
"value": "22.222.222/0001-22"
}
},
"paymentMethod": "TED",
"referenceNumber": "123456789",
"receiverReferenceId": "company-reference-id"
}
```
Cada participante do "PaymentData" terá referências à conta na qual a transferência foi originada ou recebida.
| Propriedade | Descrição |
|-------------|-----------|
| name | Nome do participante (Pagador ou Recebedor) |
| branchNumber | Número da agência |
| accountNumber | Número da conta, com dígito verificador. |
| routingNumber | Número de identificação do banco COMPE. A lista completa pode ser encontrada [aqui](https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf). |
| routingNumberISPB | Número de identificação do banco ISPB. A lista completa pode ser encontrada [aqui](https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf). |
| documentNumber | CPF ou CNPJ formatado do participante. |
## Metadados do Boleto
Se a transação estiver relacionada a um Boleto, as seguintes informações serão retornadas no objeto `boletoMetadata` (veja [instituições suportadas](/docs/paymentdata-coverage)).
| Propriedade | Descrição |
|-------------|-----------|
| digitableLine | Identificador do Boleto |
| barcode | Número do código de barras do Boleto |
| baseAmount | Valor original do Boleto sem considerar penalidades / juros / descontos |
| interestAmount | Valor de juros do Boleto |
| penaltyAmount | Valor de penalidade do Boleto |
| discountAmount | Valor de desconto do Boleto |
Descreve o boleto por trás de uma **transação liquidada** que já está no
extrato, portanto está sempre no passado. **A Pluggy não suporta DDA (Débito
Direto Autorizado): não há como consultar os boletos que uma pessoa ou empresa
ainda deve.** Nenhum endpoint, produto ou conector consulta o registro DDA, então
`boletoMetadata` não pode ser usado para descobrir boletos pendentes.
O que existe, e é uma coisa diferente em cada caso:
- [API de Gestão de Boletos](/docs/boleto/management-api) — **emissão** de boletos para
que alguém pague *você*.
- Iniciação de pagamento de boleto — **pagando** um boleto cuja linha digitável você
já possui; a Pluggy não encontra a linha para você.
```json
{
"payer": {
"name": "Francisco Souza",
"branchNumber": "1111",
"accountNumber": "11111-7",
"routingNumber": "341",
"documentNumber": {
"type": "CPF",
"value": "111.111.111-11"
},
"routingNumberISPB": "60701190"
},
"receiver": {
"name": "Pluggy Brasil Instituição de Pagamento LTDA",
"documentNumber": {
"type": "CNPJ",
"value": "37.943.755/0001-30"
}
},
"paymentMethod": "BOLETO",
"boletoMetadata": {
"baseAmount": 1520,
"digitableLine": "11190000111001113911100000021110600000000111000",
"discountAmount": 0,
"interestAmount": 10
},
"referenceNumber": "173631925"
}
```
estão disponíveis para nossos conectores diretos, consulte a [Página de Cobertura](/docs/paymentdata-coverage) para mais informações.
## Esquema de Metadados de Cartão de Crédito de Transação
Transações associadas a cartões de crédito podem conter dados adicionais, como o total de parcelas, o número da parcela e o valor total (a soma de todas as parcelas).
```json
{
"installmentNumber": 1,
"totalInstallments": 6,
"totalAmount": 9000,
"payeeMCC": 1234,
"cardNumber": "1234",
"billId": "03cc0eff-4ec5-495c-adb3-1ef9611624fc"
}
```
| Propriedade | Descrição |
|-------------|-----------|
| installmentNumber | O número da parcela associado à transação. |
| totalInstallments | O total de parcelas associado à transação. |
| totalAmount | O valor total (soma de todas as parcelas). *Somente disponível quando a compra foi feita em parcelas, e somente em conectores diretos — conectores de Open Finance não retornam este campo.* |
| payeeMCC | Código de categoria do comerciante do recebedor |
| purchaseDate | Data original da compra, para transações feitas com parcelas. |
| cardNumber | O número do Cartão de Crédito associado à transação pode ser diferente da conta se for feito por um cartão adicional ou virtual. |
| billId | Id da fatura associada à transação. *Somente disponível em conectores de Open Finance* |
## Esquema de Comerciante de Transação
Transações recuperadas podem conter informações extras sobre o comerciante/empresa associada à transação. Essas informações são o nome legal da empresa, número do CNPJ e a categoria associada aos comerciantes.
```json
{
"name": "Netflix",
"businessName": "NETFLIX ENTRETENIMENTO BRASIL LTDA.",
"cnpj": "00.000.000/0000-00",
"cnae": "5911100",
"category": "Streaming de Vídeo"
}
```
| Propriedade | Descrição |
|-------------|-----------|
| name | Nome simples do comerciante. |
| businessName | Nome legal registrado do comerciante. |
| cnpj | Número do CNPJ associado ao comerciante. |
| cnae | Número do CNAE associado ao comerciante. |
| category | Categoria do comerciante. Fornecida pelo nosso Categorizer de Enriquecimento. |
Veja [Transação](/reference/transaction) em nossa referência da API para mais informações.
## Como sincronizar e mesclar transações
*Pré-requisitos*:
- Configure webhooks para `transactions/updated`, `transactions/deleted` e `transactions/created`.
**Há algumas coisas a fazer:**
- Receba o evento de webhook `transactions/created`, e usando o `createdTransactionsLink` pague todas as transações disponíveis e insira-as em sua fonte de dados.
```json
{
"itemId": "de7bbf5a-abf2-47e4-94b1-586b36758423",
"event": "transactions/created",
"id": "de7bbf5a-abf2-47e4-94b1-586b36758423",
"eventId": "4e69d62d-b7c8-4f01-b591-a1d8a94710b9",
"accountId": "0d5a0de2-9c82-4ea2-af50-31643a632a33",
"transactionsCreatedAtFrom": "2025-02-13T17:21:53.719Z",
"createdTransactionsLink": "https://api.pluggy.ai/transactions?accountId=0d5a0de2-9c82-4ea2-af50-31643a632a33&createdAtFrom=2025-02-13T17:21:53.719Z"
}
```
- Receba o evento de webhook `transactions/updated`, e usando a lista de IDs recebidos, você deve paginar o endpoint [/transactions](/reference/transaction/transactions-list) por uma lista de `ids`, atualizando seus dados com isso.
```json
{
"event": "transactions/updated",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
"transactionIds": [
"5a14feae-eaa7-423a-820c-6b83837c35b7",
"786c7d98-6085-4879-9c7f-2255260e2436"
]
}
```
- Receba o webhook `transactions/deleted` e então exclua todas as transações que correspondem aos IDs especificados. O payload carrega **somente os IDs das transações** (não o valor, data ou descrição excluídos). Trate as exclusões de forma idempotente: uma transação pode ocasionalmente desaparecer de uma sincronização e **reaparecer** em uma posterior, então um evento `deleted` não é necessariamente permanente.
```json
{
"event": "transactions/deleted",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
"transactionIds": [
"5a14feae-eaa7-423a-820c-6b83837c35b7",
"786c7d98-6085-4879-9c7f-2255260e2436"
]
}
```
Quando a Pluggy sincroniza transações com a instituição financeira, calculamos um hash que nos permite **manter o mesmo `id` da transação em sincronizações**. A maioria das mudanças — incluindo a transição de `PENDING` → `POSTED` — chega como uma **atualização** no local (`transactions/updated`) que **preserva o `id`**.
Somente quando os dados mudam demais para confirmar que é a mesma transação — tipicamente `data`, `descrição` ou `valor` — fazemos **excluir a transação existente e criar uma nova** com um novo `id`. O payload **não** inclui um campo vinculando a transação excluída à sua substituição.
Para reconciliar em uma exclusão/criação, ancore-se em um identificador do lado do provedor: **`providerId`** (o id da transação do provedor, **somente retornado para conectores de Open Finance**) ou **`providerCode`** (um código da instituição como um NSU; o formato varia por instituição). Para conectores diretos (não-Open-Finance) não há um identificador estável garantido, então combine com atributos (`data` + `valor` + `descrição`).
**Reconectar uma conta** cria um **novo item**, cujas transações recebem **novos `id`s**; a Pluggy não desduplicará automaticamente transações entre itens. Reconcile do seu lado usando `providerId` (Open Finance) mais atributos da transação.
- Use um tamanho de página de 500 transações. (Desde 01/12/2025, este será o tamanho de página padrão ao recuperar transações).
- **500 é um máximo rígido, não um limite que é aplicado silenciosamente.** Um `pageSize` acima de 500 falha na validação e a API responde `400 Bad Request` -- não é *limitado* a 500. Para recuperar mais de 500 transações, mantenha `pageSize` em 500 ou abaixo e itere o parâmetro `page` até ter coberto `totalPages`.
- O mesmo teto se aplica ao filtrar pelo parâmetro `ids`: uma única resposta nunca retorna mais de 500 registros, então enviar mais de 500 ids em uma única solicitação não trará os extras de volta. Agrupe-os em grupos de 500.
## Saldo de Fim de Dia
Às vezes, para casos de conciliação, você deseja obter o saldo de uma conta no final de um determinado dia (normalmente é o dia anterior). O campo usual de **saldo** da conta não resolverá essa necessidade, pois pode já ter sido afetado pelas transações de hoje.
Nesses casos, você pode obter um saldo de fim de dia olhando para o **`saldo` da última transação** dentro daquele dia. Em nosso endpoint de Transações, é a **primeira** mostrada para aquele dia:
```json
{
"total": 1,
"totalPages": 1,
"page": 1,
"results": [
{
"description": "Transação exemplo 4",
"amount": -100,
"date": "2024-10-04T18:00:00.000Z",
"balance": 800
},
{
"description": "Transação exemplo 3",
"amount": -100,
"date": "2024-10-04T10:00:00.000Z",
"balance": 900
},
{
"description": "Transação exemplo 2",
"amount": -100,
"date": "2024-10-03T18:00:00.000Z",
"balance": 1000
},
{
"description": "Transação exemplo 1",
"amount": -100,
"date": "2024-10-03T10:00:00.000Z",
"balance": 1100
}
]
}
```
Isso é suportado apenas pelos conectores Diretos da Pluggy (Itau PJ, Sicredi PF & PJ, Bradesco PJ).
### Caso Santander PJ
Para esta instituição, sempre que possível, devemos confiar nos tipos de transação fornecidos pela Contamax para identificar e interpretar os movimentos da conta.
Essas transações não aparecem todos os dias no extrato. Em geral, são registradas apenas em dias úteis. Mesmo assim, pode haver dias úteis em que nenhuma transação é mostrada, por exemplo, se não houver atividade durante o dia.
No final de cada dia, apenas uma das duas operações pode ocorrer, dependendo do saldo da conta antes do fechamento diário:
- Saldo final positivo (acima de zero): Uma aplicação de investimento automática é executada com o saldo disponível.
- Saldo final negativo (abaixo de zero): Uma resgate automático é executado para cobrir o saldo negativo.
Ambas as operações nunca aparecerão no mesmo dia -- apenas uma aplicação ou um resgate, de acordo com o saldo final da conta no final do dia.
Nos casos em que essas transações aparecem no extrato, elas podem ser interpretadas como o resultado do saldo de fim de dia:
- Uma aplicação indica que o saldo final do dia foi positivo.
- Um resgate indica que o saldo final do dia foi negativo.
## Transações agregáveis do Itau PJ
Dentro da instituição Itau PJ, existem certas transações *agregáveis* (tipos `SISPAG` e `PIX TRANSF`). Essas transações agregáveis podem vir em uma de duas formas:
- Forma consolidada: muitas operações do mesmo tipo dentro do mesmo dia são representadas como uma única Transação
- Forma detalhada: cada operação é representada como uma Transação separada
Para nosso conector regulado do Itau PJ, elas sempre virão em forma detalhada.
Para nosso conector direto do Itau PJ, dependerá da configuração da empresa conectada do Item. Para forçar a visualização detalhada, o usuário precisa acessar o Internet Banking e ir para `Contas a pagar > Manutenção > Alteração de serviço` e mudar todos os extratos para Detalhado. Isso requer um token de acesso para mudar, e um usuário com permissões suficientes.
Se o Item tiver o produto Dados de Pagamento habilitado, nosso Conector Direto tentará desagregar transações SISPAG e PIX o máximo possível, mesmo que a empresa não tenha transações detalhadas habilitadas. No entanto, se você precisar de desagregação garantida, é recomendado usar o conector Regulamentado.
# Itau PJ SISPAG Suportado
Ao recuperar dados de pagamento para transferências SISPAG, existem certos subtipos específicos que nossa API manipula. Esses casos são:
- SISPAG FORNECEDORES (Fornecedores)
- SISPAG PIX
- SISPAG CONCESSIONARIA (Companhia de Utilidade)
- SISPAG MISMA TITULARIDADE (Mesma Titularidade)
# Limitação de cobertura do Santander PJ
Em contas empresariais do Santander, quando a conta está conectada através de um operador de conta, o histórico de transações disponível é limitado aos últimos 3 meses.
Além disso, se um único dia contiver mais de 400 transações, apenas as primeiras 400 serão recuperadas -- quaisquer transações além desse limite não serão retornadas.
Nesses casos, nossa recomendação geral é usar o conector regulamentado da instituição para evitar essa limitação.
## Classificação de Transações
Source: https://docs.pluggy.ai/pt/docs/products/transaction-categorization.md
A categorização de transações é um recurso onde classificamos suas Transações em categorias úteis (Restaurantes, Postos de Gasolina, Renda, etc.) usando nosso motor de IA de categorização. Isso permite que você resuma, agrupe e extraia rapidamente insights valiosos das transações dos seus itens logo de cara.
Por exemplo, você poderia entender quanto um usuário gastou no mês passado em alimentação, quanto em serviços, e assim por diante, e com isso mostrar a eles um resumo de suas despesas (como em nosso guia [Criando um caso de uso do zero](/docs/integration-checklist/use-case)), ou você pode usá-lo para criar qualquer tipo de soluções, desde perfil de cliente até análise de renda.
## Usando a categorização
Retornamos o resultado da nossa categorização no campo `category` de uma transação, esta é a categoria principal correspondente ao nosso modelo.
```json
{
"id": "6ec156fe-e8ac-4d9a-a4b3-7770529ab01c",
"description": "Exemplo de TED",
"amount": 1500,
"date": "2021-04-12T00:00:00.000Z",
// O nome da categoria é fornecido
"category": "Transfer - TED",
"categoryId": "05080000",
...
}
```
A categoria será uma string se uma categoria foi encontrada, ou `null` se não conseguimos interpretar nenhuma categoria conhecida.
A categorização está habilitada por padrão durante o período de teste. Depois disso, é um recurso premium opcional.
Se você não tiver o recurso de categorização de transações habilitado, `category` será `null` para todas as transações.
## Como as categorias são organizadas
Veja todas as categorias possíveis em nosso endpoint [GET /categories](/reference/categories-list). Podemos encontrar a categoria da transação nesta lista com seu `categoryId`:
```json
[
{
"id": "05080000",
"description": "Transfer - TED",
"descriptionTranslated": "Transferencia - TED",
"parentId": "05000000",
"parentDescription": "Transfers"
},
...
]
```
Podemos ver sua tradução para o português no campo `descriptionTranslated`.
Você pode notar que tem uma parentDescription `Transfers`. Isso significa que está sob uma categoria mais geral chamada Transfers:
```json
[
...
{
"id": "05000000",
"description": "Transfers"
},
...
]
```
As categorias são organizadas em uma **árvore**. Isso permite que você use categorias mais gerais ou específicas, dependendo de suas necessidades particulares. A Árvore de Categorias é detalhada no final deste guia.
## Precisão da categoria
Por mais que constantemente treinem nosso modelo de categorização, a categorização nunca é perfeita. Caso você encontre uma categoria errada em uma transação, pode corrigi-la usando nosso endpoint [Transaction Update](/reference/transactions-update), ou do Demo clicando no campo *Category*.
Depois de enviar uma correção de categoria, você receberá o campo `category` corrigido na transação e também fornecerá feedback sobre a anotação correta em nosso modelo, melhorando ainda mais a qualidade da categorização.
### Regras de Categoria
A Pluggy trabalha na melhoria contínua da precisão da categorização, para fornecer os melhores rótulos do mercado, mas às vezes podemos retornar rótulos que não estão alinhados às expectativas do cliente. As regras de categoria permitem que os clientes adicionem suas próprias regras antes da nossa solução de rotulagem e forneçam feedback instantâneo ao nosso modelo, que pode ser estabelecido como um ponto de dados em nosso modelo de ML.
As Regras de Categoria serão usadas no início do processo, para rotular as transações com a categoria desejada. As Regras de Categoria são específicas para o cliente e são válidas apenas para um `client_id` específico.
Transações que são recategorizadas criarão automaticamente uma **Regra de Categoria** para o cliente da transação.
#### Gerenciando regras
Crie uma regra com [POST /categories/rules](/reference/client-category-rules-create), passando a `description` da transação para corresponder e o `categoryId` a ser atribuído. A resposta é a regra armazenada, incluindo seu `id`:
```json
{
"id": "d5c3f6a2-7b1e-4f0c-9a8d-2e6b1c4f7a90",
"description": "pagamento uber",
"category": "Taxi e transporte por aplicativo",
"categoryId": "19050000",
"transactionType": "DEBIT",
"accountType": "CHECKING_ACCOUNT",
"matchType": "exact"
}
```
| Campo | Descrição |
|-------|-------------|
| `id` | Identificador da regra. Use-o para excluir a regra. |
| `description` | Texto que a regra corresponde à descrição da transação. A comparação é sem distinção entre maiúsculas e minúsculas. |
| `category` / `categoryId` | Categoria atribuída às transações correspondentes. |
| `transactionType` | `DEBIT` ou `CREDIT`, quando a regra se aplica a um tipo apenas; caso contrário, `null`. |
| `accountType` | `CHECKING_ACCOUNT` ou `CREDIT_CARD`, quando a regra se aplica a um tipo de conta apenas; caso contrário, `null`. |
| `matchType` | Como `description` é comparado: `exact` (padrão), `contains`, `startsWith` ou `endsWith`. |
Criar uma regra com a mesma `description`, `transactionType` e `accountType` que uma existente atualiza essa regra em vez de criar uma segunda, e retorna o `id` existente.
[GET /categories/rules](/reference/client-category-rules-list) lista suas regras em uma única página (`results`, `page`, `total`, `totalPages`), cada uma com seu `id`. Para remover uma regra, chame [DELETE /categories/rules/{id}](/reference/client-category-rules-delete) com esse `id`; ele responde `204` e a regra para de se aplicar a novas categorizations. Transações já categorizadas pela regra mantêm sua categoria.
## Árvore de Categorias
| Nível 1 | Nível 2 | Nível 3 |
|---------|---------|---------|
| Renda | Salário, Aposentadoria, Atividades empreendedoras, Auxílio governamental, Renda não recorrente | |
| Empréstimos e Financiamentos | Custos de atraso e cheque especial, Juros cobrados, Empréstimos | |
| | Financiamento | Financiamento imobiliário, Financiamento de veículos, Empréstimo estudantil |
| Investimentos | Investimento automático, Renda fixa, Fundos mútuos, Renda variável, Margem, Juros e dividendos de rendimentos, Pensão | |
| Transferência entre a mesma pessoa | Transferência entre a mesma pessoa - Dinheiro, Transferência entre a mesma pessoa - PIX, Transferência entre a mesma pessoa - TED | |
| Transferências | Transferência - Boleto, Transferência - Dinheiro, Transferência - Cheque, Transferência - DOC, Transferência - Câmbio, Transferência - Interna, Transferência - PIX, Transferência - TED, Pagamento com cartão de crédito | |
| | Transferências de terceiros | Boleto, Cartão de débito, DOC, PIX, TED |
| Obrigações legais | Saldos bloqueados, Pensão alimentícia | |
| Serviços | Telecomunicações | Internet, Móvel, TV |
| | Educação | Cursos online, Universidade, Escola, Jardim de infância |
| | Bem-estar e fitness | Academias e centros de fitness, Prática de esportes, Bem-estar |
| | Ingressos | Estádios e arenas, Monumentos e museus, Cinema, teatro e concertos |
| Compras | Compras online, Eletrônicos, Suprimentos para pets e veterinário, Roupas, Crianças e brinquedos, Livraria, Artigos esportivos, Materiais de escritório, Cashback | |
| Serviços digitais | Jogos, Streaming de vídeo, Streaming de música | |
| Supermercados | N/A | |
| Comida e bebidas | Comer fora, Entrega de comida | |
| Viagens | Aeroporto e companhias aéreas, Acomodação, Programas de milhagem, Passagens de ônibus | |
| Doações | | |
| Jogos de azar | Loteria, Aposta online | |
| Impostos | Impostos sobre a renda, Impostos sobre investimentos, Imposto sobre operações financeiras | |
| Taxas bancárias | Taxas de conta, Taxas de transferência e taxas de caixa eletrônico, Taxas de cartão de crédito | |
| Habitação | Aluguel, Utensílios domésticos, Imposto sobre terrenos e edificações urbanas | |
| | Utilidades | Água, Eletricidade, Gás |
| Saúde | Dentista, Farmácia, Optometria, Clínicas e laboratórios hospitalares | |
| Transporte | Táxi e transporte por aplicativo, Transporte público, Aluguel de carros, Bicicleta | |
| | Automotivo | Postos de gasolina, Estacionamento, Pedágios e pagamento em veículo, Impostos e taxas de propriedade de veículos, Manutenção de veículos, Multas de trânsito |
| Seguro | Seguro de vida, Seguro residencial, Seguro de saúde, Seguro de veículos | |
| Lazer | | |
## Investimento
Source: https://docs.pluggy.ai/pt/docs/products/investments.md
A entidade **Investimento** é recuperada não apenas de Corretores (XP, Clear), mas também de instituições bancárias de varejo e empresariais.
A lista de investimentos de uma instituição pode ser diferenciada com base no `tipo` do investimento. Cada tipo de investimento possui um conjunto de campos que se relacionam ao tipo específico de investimento.
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| name | string | Não | Nome no provedor. |
| code | string | Sim | Código associado ao investimento. No caso de Fundos de Investimento, é o CNPJ do Fundo. |
| isin | string | Sim | ISIN de 12 caracteres, um identificador único global. |
| number | string | Sim | Número do investimento, nem sempre fornecido. |
| owner | string | Sim | Proprietário/beneficiário associado ao investimento. |
| currencyCode | CurrencyCode | Sim | Código ISO da moeda da transação, ou seja, *USD*. |
| type | [InvestmentType](#investments-types--subtypes) | Não | Tipo de investimento. |
| subtype | [InvestmentSubType](#investments-types--subtypes) | Sim | Subtipo do investimento. |
| lastMonthRate | number | Sim | A taxa de desempenho do último mês. *Esse valor é retornado para fundos*. |
| lastTwelveMonthsRate | number | Sim | A taxa de desempenho dos últimos 12 meses. *Esse valor é retornado para fundos*. |
| annualRate | number | Sim | Taxa de desempenho do último ano. *Esse valor é retornado para fundos*. |
| date | Date | Sim | Data de referência do valor do ativo. ou seja, ao recuperar ativos durante o fim de semana, a data provavelmente será o último dia útil. |
| value | number | Sim | Valor atual da cota na `data`. |
| quantity | number | Sim | Quantidade de cotas à disposição. |
| amount | number | Não | Valor bruto do investimento (impostos incluídos). |
| taxes | number | Sim | Impostos de renda aplicados ao investimento. |
| taxes2 | number | Sim | Impostos financeiros aplicados ao investimento. |
| balance | number | Não | O valor líquido atual do investimento. Após a aplicação de taxas e impostos. |
| dueDate | Date | Sim | Data de vencimento. |
| rate | number | Sim | Percentual da taxa fixa aplicada ao investimento. |
| rateType | [string](#rate-types-for-fixed-income-assets) | Sim | Tipo de taxa fixa. (um dos `CDI` \| `SELIC` \| `DOLAR` \| `EURO` \| `IGPM` \| `IPCA` \| null) |
| fixedAnnualRate | number | Sim | Taxa anual de renda fixa (Exemplo: 10,50). |
| issuer | string | Sim | A entidade que emitiu o investimento. |
| issueDate | Date | Sim | A data em que a entidade emitiu o investimento. |
| amountProfit | number | Sim | Lucro líquido até a data sobre o investimento. Se negativo, é perda. |
| amountWithdrawal | number | Sim | O valor disponível para saque. |
| amountOriginal | number | Sim | Valor originalmente investido. |
| status | [InvestmentStatus](#investments-status) | Sim | Status atual do investimento. ATIVO, PENDENTE & RETIRADA_TOTAL |
| institution | [InvestmentInstitution](#investments-institution) | Sim | Corretora ou Instituição Financeira detentora do investimento. Isso é retornado apenas no Conector CEI B3. |
| *transactions* **(deprecated)** | [InvestmentsTransaction](/docs/products/investment-transactions) | Sim | Lista de Transações de Investimentos associadas a Aplicações ou Retiradas, que afetam o valor investido. Este campo não estará presente em Aplicações criadas após 21 de março de 2023. Use o [endpoint de Transações de Investimentos paginadas](/reference/investment-transactions-list) em vez disso. |
| metadata | [InvestmentMetadata](#investments-metadata) \| null | Sim | O objeto de metadados contém "Dados de Títulos" para portabilidade de Previdências Privadas. **Nota:** requer recurso habilitado e assinatura **Pro**. |
| gracePeriodDate | Date | Sim | Data em que o período de carência termina. Preenchido para investimentos de renda fixa (CDB, LCI, LCA, CRI, CRA, Debênture). null para todos os outros tipos de investimento. |
### Investimentos em conectores de Open Finance
Open Finance define quais dados de investimento uma instituição compartilha, portanto, alguns campos se comportam de maneira diferente dos conectores diretos:
- `amountProfit`, `annualRate`, `lastMonthRate` e `lastTwelveMonthsRate` não fazem parte dos dados que as instituições compartilham através do Open Finance e são retornados como `null`.
- `rate`, `rateType` e `fixedAnnualRate` descrevem a remuneração contratada de posições de renda fixa e tesouraria (por exemplo, 110% do CDI, ou uma taxa fixa de 12,5% ao ano). Eles não são uma taxa de desempenho medida, então não os leia como `annualRate`.
- `amountWithdrawal` é o valor menos o que a instituição relata como bloqueado: o valor líquido para renda fixa e tesouraria, o valor bruto para fundos e ações.
- `taxes` é o imposto de renda (IR) e `taxes2` o imposto sobre transações financeiras (IOF) que a instituição relata. Para fundos, são os valores provisionados.
## Status do Investimento
| Valor | Descrição |
|-------|-----------|
| ATIVO | Comprado e verificado |
| PENDENTE | Validando compra |
| RETIRADA_TOTAL | Vendido ou transferido |
## Instituição do Investimento
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| name | string | Sim | Nome completo da instituição. |
| number | string | Sim | Número identificador para o CNPJ da instituição / Outro. |
## Tipos & Subtipos de Investimento
Para entender a natureza de um investimento, você pode contar com os campos `tipo` e `subtipo` do investimento que têm relação precisa com os tipos de investimentos disponíveis no Pluggy.
| Tipo | Subtipo | Descrição |
|------|---------|-----------|
| RENDA_FIXA | CRI | Certificado de Recebíveis Imobiliários |
| RENDA_FIXA | CRA | Certificado de Recebíveis do Agronegócio |
| RENDA_FIXA | LCI | Letra de Crédito Imobiliário |
| RENDA_FIXA | LCA | Letra de Crédito do Agronegócio |
| RENDA_FIXA | LC | Letra de Câmbio |
| RENDA_FIXA | TESOURARIA | Tesouro Nacional |
| RENDA_FIXA | DEBÊNTURES | Dívida Corporativa |
| RENDA_FIXA | CDB | Certificado de Depósito Bancário |
| RENDA_FIXA | LIG | Letra Imobiliária Garantida |
| RENDA_FIXA | LF | Letra Financeira |
| TÍTULO | PREVIDÊNCIA | Previdência Privada |
| TÍTULO | PGBL | Previdência Privada |
| TÍTULO | VGBL | Previdência Privada |
| FUNDO_MUTUO | FUNDO_DE_INVESTIMENTO | Fundo de Investimento |
| FUNDO_MUTUO | FUNDO_DE_AÇÕES | Fundo de Ações |
| FUNDO_MUTUO | FUNDO_MULTIMERCADO | Fundo Multimercado |
| FUNDO_MUTUO | FUNDO_CAMBIAL | Fundo Cambial |
| FUNDO_MUTUO | FUNDO_DE_RENDA_FIXA | Fundo de Renda Fixa |
| FUNDO_MUTUO | FUNDO_FIP | Fundo FIP |
| FUNDO_MUTUO | FUNDO_OFFSHORE | Fundo Offshore |
| FUNDO_MUTUO | FUNDO_ETF | Fundo ETF |
| AÇÃO | AÇÕES | Ações, Papéis |
| AÇÃO | BDR | Brazilian Depositary Receipt |
| AÇÃO | FUNDO_IMOBILIÁRIO | Fundos Imobiliários |
| AÇÃO | DERIVATIVOS | Derivativos |
| AÇÃO | OPÇÃO | Opção |
| ETF | ETF | Fundos Negociados em Bolsa |
| COE | NOTA_ESTRUTURADA | Nota Estruturada |
Alguns bancos, como NuBank e PicPay, têm opções de investimento chamadas "Cofrinhos" e "Caixinhas", que se configuram como CDBs. Assim, eles estão cobertos pela conexão e devem aparecer na seção de investimentos também.
## Metadados do Investimento
O objeto de metadados contém as informações de Portabilidade de Investimento relacionadas a ativos de Títulos como Previdência Privada. Esses campos são usados para fornecer, por exemplo, "Portabilidade de Previdência".
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| taxRegime | string | Sim | Regime do imposto utilizado para o ativo. |
| proposalNumber | string | Sim | Identificação do número da proposta do ativo. |
| processNumber | string | Sim | Número de identificação do processo da instituição (`susep`). |
| fundName | string | Sim | Nome do fundo associado ao investimento em Títulos (pode ser diferente da propriedade `name` do investimento). |
| insurer | Company | Sim | A empresa seguradora do Fundo de Títulos, quando o número do processo é identificado, a seguradora sempre será retornada. |
Este conjunto de dados faz parte do serviço de Portabilidade de Previdência e não será retornado na resposta do investimento até ser habilitado. Entre em contato com [support@pluggy.ai](mailto:support@pluggy.ai) ou converse conosco para testar esse recurso.
## Tipos de Taxas para Ativos de Renda Fixa
Quando o tipo de ativo é `RENDA_FIXA`, recuperamos 3 campos associados ao retorno esperado do investimento. Estes são `rate`, `rateType` & `fixedAnnualRate`. Abaixo estão alguns exemplos de como os tipos de taxas são analisados.
| Exemplo | Taxa | Tipo de Taxa | Taxa Anual Fixa |
|---------|------|--------------|-----------------|
| 100% CDI + 5% | 100 | CDI | 5 |
| IPC-A + 10% | 100 | IPCA | 10 |
| Pré-Fixado 16,76% | | | 16.76 |
| 12% A.A | | | 12 |
## Exemplos de respostas
```json title="Previdência"
{
"id": "ded7d2f1-6b90-44a8-9ace-de747b9f5bfe",
"number": "123456-2",
"name": "Pluggy PREVIDÊNCIA",
"balance": 1359.39,
"currencyCode": "BRL",
"type": "SECURITY",
"subtype": "RETIREMENT",
"annualRate": 3.24,
"itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
"code": null,
"value": 500,
"quantity": 3,
"amount": 1500,
"taxes": 0,
"taxes2": 0,
"date": "2020-07-19T18:27:41.802Z",
"owner": "John Doe",
"amountProfit": 359.39,
"amountWithdrawal": 1310.5,
"status": "ACTIVE",
"metadata": {
"taxRegime": "Progressivo",
"proposalNumber": "000091322061",
"processNumber": "15414900845201686",
"insurer": {
"cnpj": "51.990.695/0001-37",
"name": "BRADESCO VIDA E PREVIDÊNCIA S.A."
}
},
"institution": {
"name": "BANCO BTG PACTUAL S/A",
"number": "30306294000145"
}
}
```
```json title="Fundo Mútuo"
{
"id": "f77eccf4-7714-498e-92a9-1bebe70335d9",
"number": null,
"name": "Bahia AM Advisory FIC de FIM",
"balance": 1359.39,
"currencyCode": "BRL",
"type": "MUTUAL_FUND",
"subtype": "INVESTMENT_FUND",
"lastMonthRate": 0.24,
"annualRate": 3.24,
"lastTwelveMonthsRate": 3,
"itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
"code": "12.345.678/0001-00",
"value": 500,
"quantity": 3,
"amount": 1500,
"taxes": 40.61,
"taxes2": 100,
"date": "2020-07-19T18:27:41.802Z",
"owner": "John Doe",
"amountProfit": null,
"amountWithdrawal": 1310.5,
"amountOriginal": 1000,
"status": "ACTIVE",
"transactions": [
{
"tradeDate": "2020-10-01T00:00:00.000Z",
"date": "2020-10-01T00:00:00.000Z",
"description": "Aplicação Fundo de Investimento Premium",
"quantity": 1.25,
"value": 2,
"amount": 5,
"type": "BUY"
}
]
}
```
```json title="CDB"
{
"id": "2a96b873-53bb-4d16-a3d8-385a57e78d7e",
"number": null,
"name": "CDB1194KL0Z - BANCO MAXIMA S/A",
"balance": 2000,
"currencyCode": "BRL",
"type": "FIXED_INCOME",
"subtype": "CDB",
"itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
"code": "0001-02",
"amount": 2500,
"taxes": null,
"taxes2": null,
"date": "2020-07-19T18:27:41.802Z",
"owner": "John Doe",
"rate": 30,
"rateType": "CDI",
"fixedAnnualRate": 10.5,
"amountProfit": null,
"amountWithdrawal": 2000,
"amountOriginal": 1000,
"dueDate": "2030-07-19T18:27:41.802Z",
"issuer": "Pluggy",
"issueDate": "2020-07-19T18:27:41.802Z",
"status": "ACTIVE"
}
```
```json title="Fundo Imobiliário"
{
"id": "5d80be62-d3a3-44e5-aaf7-85d33c7e9a7a",
"number": null,
"name": "GGRC11",
"balance": 118.4,
"currencyCode": "BRL",
"type": "EQUITY",
"subtype": "REAL_ESTATE_FUND",
"lastMonthRate": null,
"lastTwelveMonthsRate": null,
"annualRate": null,
"itemId": "80c05d1e-0ef7-4939-976d-f1509efd663a",
"code": "GGRC11",
"isin": "BRGGRCCTF002",
"metadata": null,
"value": 118.4,
"quantity": 1,
"amount": 118.4,
"taxes": null,
"taxes2": null,
"date": "2022-06-20T14:43:58.799Z",
"owner": null,
"amountProfit": null,
"amountWithdrawal": 118.4,
"amountOriginal": 119,
"transactions": [
{
"id": "76689151-2aff-4f32-8308-d9ecffb42254",
"amount": 134.99,
"description": null,
"value": 134.99,
"quantity": 1,
"tradeDate": "2021-08-15T00:00:00.000Z",
"date": "2021-08-15T00:00:00.000Z",
"type": "BUY",
"netAmount": null,
"brokerageNumber": "123456-1",
"expenses": {
"serviceTax": 0.1,
"brokerageFee": 0.04,
"incomeTax": 0.08,
"other": 0.04,
"tradingAssetsNoticeFee": 0.11,
"maintenanceFee": 0.12,
"settlementFee": 0.02,
"clearingFee": 0.1,
"stockExchangeFee": 0.1,
"custodyFee": 0.05,
"operatingFee": 0.03
}
}
],
"dueDate": null,
"issuer": "GGR COVEPI RENDA FDO INV IMOB",
"issueDate": null,
"rate": null,
"rateType": null,
"fixedAnnualRate": null,
"status": "ACTIVE",
"institution": null
}
```
```json title="ETF"
{
"id": "5af0bd99-b74f-440a-bab3-6ed9155283ee",
"number": null,
"name": "ISUS11 STOCK",
"balance": 2000,
"currencyCode": "BRL",
"type": "ETF",
"subtype": "ETF",
"lastMonthRate": 0.2,
"lastTwelveMonthsRate": null,
"annualRate": null,
"itemId": "80c05d1e-0ef7-4939-976d-f1509efd663b",
"code": "ISUS11",
"isin": "BRISUSCTF003",
"metadata": null,
"value": null,
"quantity": 1,
"amount": 2000,
"taxes": null,
"taxes2": null,
"date": "2022-06-20T14:43:58.799Z",
"owner": "John Doe",
"amountProfit": 0,
"amountWithdrawal": 2000,
"amountOriginal": 2000,
"transactions": [
{
"id": "7a102141-b04a-490e-83db-42f09d39c421",
"amount": 1499.99,
"description": null,
"value": 1499.99,
"quantity": 1,
"tradeDate": "2021-08-15T00:00:00.000Z",
"date": "2021-08-15T00:00:00.000Z",
"type": "BUY",
"netAmount": null,
"brokerageNumber": null,
"expenses": {}
}
],
"dueDate": null,
"issuer": "IT NOW ISE FUNDO DE ÍNDICE",
"issueDate": null,
"rate": null,
"rateType": null,
"fixedAnnualRate": null,
"status": "ACTIVE",
"institution": null
}
```
```json title="COE"
{
"id": "be7d7a0d-b411-4b88-b0a8-ede1a05aedbb",
"number": null,
"name": "SP 500 Ganho Garanti",
"balance": 5021.2,
"currencyCode": "BRL",
"type": "COE",
"subtype": "STRUCTURED_NOTE",
"lastMonthRate": null,
"lastTwelveMonthsRate": null,
"annualRate": null,
"itemId": "ed10736c-5330-4242-8a85-204397edb0cc",
"code": null,
"isin": null,
"metadata": null,
"value": 5027.35,
"quantity": 1,
"amount": 5027.35,
"taxes": null,
"taxes2": null,
"date": null,
"owner": "John Doe",
"amountProfit": null,
"amountWithdrawal": null,
"amountOriginal": 5000,
"transactions": [
{
"id": "b266fcda-b5ee-4181-80b5-273ecb4ff721",
"amount": 5000,
"description": null,
"value": 5000,
"quantity": 1,
"tradeDate": "2022-01-21T00:00:00.000Z",
"date": "2022-01-21T00:00:00.000Z",
"type": "BUY",
"netAmount": null,
"brokerageNumber": null,
"expenses": {}
}
],
"dueDate": "2027-01-27T00:00:00.000Z",
"issuer": null,
"issueDate": "2022-01-21T00:00:00.000Z",
"rate": null,
"rateType": null,
"fixedAnnualRate": null,
"status": "ACTIVE",
"institution": null
}
```
Veja [Investimento](/reference/investment) em nossa referência da API para mais informações.
## Transações de Investimento
Source: https://docs.pluggy.ai/pt/docs/products/investment-transactions.md
Cada investimento contém uma lista de transações correspondentes a Aplicações ou Retiradas. O esquema da transação contém um conjunto de detalhes dessa operação.
## Transação de Investimento
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| tradeDate | Data | Não | A data em que a transação foi liquidada. |
| date | Data | Não | A data em que a transação foi realizada. |
| quantity | número | Não | Quantidade de cotas investidas. |
| value | número | Não | Valor pelo qual foi adquirido. |
| amount | número | Não | O valor bruto da operação. |
| type | InvestmentTransactionType | Não | Tipo de movimento da transação. |
| description | string | Sim | Descrição da transação. |
| brokerageNumber | string | Sim | Número da nota de corretagem correspondente. |
| netAmount | número | Sim | Valor incluindo despesas. |
| agreedRate | número | Sim | Taxa acordada disponível apenas para aplicações de TESOURO. |
| expenses | Expenses | Sim | Impostos e taxas descritos nas notas de corretagem. |
## Tipo de Transação de Investimento
| Valor | Descrição |
|-------|-----------|
| BUY | Aplicação. |
| SELL | Retirada. |
| TAX | Impostos que diminuem o tamanho do investimento. |
| TRANSFER | Transferência entre investimentos. |
| INTEREST | Distribuições de renda: dividendos, renda de aluguel (FIIs), juros sobre capital (JCP), pagamentos de cupons. |
| AMORTIZATION | Retorno parcial do principal (amortização de cotas, amortização de títulos). |
## Despesas
Quando compramos um ativo negociado em uma bolsa de valores, geralmente através de uma corretora, a corretora emite uma nota comercial chamada **nota de corretagem**. A nota contém o valor total da transação, os ativos comprados e vendidos, as taxas relacionadas à bolsa de valores, o valor cobrado pelo corretor (taxa de corretagem) e a soma total. A nota de corretagem representa o status diário das operações de um investidor no mercado financeiro. Todos os impostos cobrados em cada operação são agrupados no objeto **Despesas**.
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| serviceTax | número | Sim | O imposto sobre serviços varia de acordo com o estado (ISS). |
| brokerageFee | número | Sim | Comissão cobrada pela corretora para realizar transações no mercado de ações. |
| incomeTax | número | Sim | Imposto de Renda Retido na Fonte é o valor pago à Receita Federal (IRRF). |
| other | número | Sim | Soma de outras despesas não definidas. |
| tradingAssetsNoticeFee | número | Sim | Uma taxa de Aviso de Negociação em Ativos (ANA). |
| maintenanceFee | número | Sim | Taxas cobradas pela BM&F Bovespa em negociações. |
| settlementFee | número | Sim | Taxa de liquidação para a liquidação de uma posição na data de vencimento ou a liquidação financeira de entrega física. |
| clearingFee | número | Sim | Taxa de compensação cobrada pela câmara de compensação. |
| stockExchangeFee | número | Sim | Taxas cobradas pela BM&F Bovespa como fonte de receita operacional. |
| custodyFee | número | Sim | Taxa cobrada pelos corretores para manter registros em seus sistemas de corretagem ou na mesa de operações. |
| operatingFee | número | Sim | Valor pago ao Operador pelo serviço de intermediação. |
Em conexões de Open Finance, a discriminação vem da nota de corretagem regulamentada, que reporta o imposto de renda retido (IRRF) por conta própria. Ele chega como `incomeTax`; todo outro imposto cobrado na operação — incluindo o imposto de renda de day-trade — é somado em `other`. Os dois nunca se sobrepõem, então somá-los dá o custo total de impostos da operação.
Exemplo de uma Transação:
```json
{
"total": 1,
"totalPages": 1,
"page": 1,
"results": [
{
"type": "BUY",
"description": "Aplicação Fundo de Investimento Premium",
"quantity": 1.25,
"value": 2,
"amount": 5,
"date": "2022-03-24T03:00:00.000Z",
"tradeDate": "2022-03-24T03:00:00.000Z",
"brokerageNumber": "47078992",
"expenses": {
"serviceTax": 0.05,
"brokerageFee": 0.1,
"incomeTax": 0.01,
"other": 0.01,
"tradingAssetsNoticeFee": 0,
"maintenanceFee": 0,
"settlementFee": 0.09,
"clearingFee": 0,
"stockExchangeFee": 0.05
}
}
]
}
```
Veja [Transações de Investimento](/reference/investment-transactions-list) em nossa referência da API para mais informações.
## Empréstimo
Source: https://docs.pluggy.ai/pt/docs/products/loans.md
A entidade **Empréstimo** é recuperada de instituições que suportam este produto. Ela representa um empréstimo contratado pelo usuário, incluindo dados como número do contrato, taxas, taxas de juros, garantias, parcelas, etc.
```json
{
"id": "658f07f1-8349-44cc-9590-e10fe9337060",
"itemId": "a9e42ebd-bddc-4d59-8895-140d8a809799",
"contractNumber": "000000721792794",
"ipocCode": "92792126019929279212650822221989319252576",
"productName": "Credito Pessoal Consignado",
"type": "CREDITO_PESSOAL_COM_CONSIGNACAO",
"kind": "LOAN",
"date": "2023-07-20T00:00:00.000Z",
"contractDate": "2022-08-01T00:00:00.000Z",
"disbursementDates": ["2018-01-15T00:00:00.000Z"],
"settlementDate": "2018-01-15T00:00:00.000Z",
"contractAmount": 50000,
"currencyCode": "BRL",
"dueDate": "2028-01-15T00:00:00.000Z",
"installmentPeriodicity": "MONTHLY",
"installmentPeriodicityAdditionalInfo": "",
"firstInstallmentDueDate": "2018-02-15T00:00:00.000Z",
"CET": 0.29,
"amortizationScheduled": "SAC",
"amortizationScheduledAdditionalInfo": "",
"cnpjConsignee": "60.500.998/0001-35",
"interestRates": [
{
"taxType": "EFFECTIVE",
"interestRateType": "SIMPLE",
"taxPeriodicity": "YEARLY",
"calculation": "21/252",
"referentialRateIndexerType": "PRE_FIXADO",
"referentialRateIndexerSubType": "TJLP",
"referentialRateIndexerAdditionalInfo": "",
"preFixedRate": 0.6,
"postFixedRate": 0.55,
"additionalInfo": ""
}
],
"contractedFees": [
{
"name": "Administracao de Operacoes",
"code": "ADM_OP",
"chargeType": "UNIQUE",
"charge": "MINIMUM",
"amount": 5,
"rate": 0
}
],
"contractedFinanceCharges": [
{
"type": "IOF_POR_ATRASO",
"additionalInfo": "",
"rate": 0.03
}
],
"warranties": [
{
"currencyCode": "BRL",
"type": "SEM_TIPO_GARANTIA",
"subtype": "ALIENACAO_FIDUCIARIA",
"amount": 500
}
],
"installments": {
"typeNumberOfInstallments": "MONTH",
"totalNumberOfInstallments": 120,
"typeContractRemaining": "MONTH",
"contractRemainingNumber": 55,
"paidInstallments": 65,
"dueInstallments": 55,
"pastDueInstallments": 0,
"balloonPayments": []
},
"payments": {
"contractOutstandingBalance": 25000,
"releases": [
{
"isOverParcelPayment": false,
"installmentId": "b1f0a5b4-1234-5678-9abc-def012345678",
"paidDate": "2023-07-15T00:00:00.000Z",
"currencyCode": "BRL",
"paidAmount": 680.5,
"overParcel": {
"fees": [],
"charges": []
}
}
]
}
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `id` | `string` | Não | Identificador primário |
| `itemId` | `string` | Não | Identificador do item vinculado ao empréstimo |
| `contractNumber` | `string` | Sim | Número do contrato fornecido pela instituição contratante |
| `ipocCode` | `string` | Sim | Número do contrato padrão - IPOC (Identificação Padronizada da Operação de Crédito) |
| `productName` | `string` | Não | Denominação/Identificação do nome da operação de crédito divulgada ao cliente |
| `type` | `string` | Sim | Tipo de empréstimo ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractProductSubTypeLoans)) |
| `kind` | `string` | Não | Família da operação de crédito à qual este contrato pertence. Um dos `LOAN`, `FINANCING`, `INVOICE_FINANCING`, `UNARRANGED_ACCOUNT_OVERDRAFT`. |
| `date` | `string` | Não | Data em que os dados do empréstimo foram coletados |
| `contractDate` | `string` | Sim | Data em que o empréstimo foi contratado |
| `disbursementDates` | `string[]` | Sim | Data de liberação do valor contratado |
| `settlementDate` | `string` | Sim | Data de liquidação do empréstimo |
| `contractAmount` | `number` | Sim | Valor contratado do empréstimo |
| `currencyCode` | `string` | Não | Código que referencia a moeda do empréstimo |
| `dueDate` | `string` | Sim | Data de vencimento do empréstimo |
| `installmentPeriodicity` | `string` | Sim | Frequência regular das parcelas. Um dos valores de [periodicidade das parcelas](#loan-installment-periodicity). |
| `installmentPeriodicityAdditionalInfo` | `string` | Sim | Campo obrigatório para complementar as informações sobre a frequência de pagamento regular quando a periodicidade das parcelas tem valor 'OUTROS' |
| `firstInstallmentDueDate` | `string` | Sim | Data de vencimento da primeira parcela |
| `CET` | `number` | Sim | CET - Custo Efetivo Total deve ser expresso como uma taxa percentual anual e incorpora todas as taxas e despesas incorridas nas operações de crédito (taxa de juros, mas também tarifas, impostos, seguros e outras despesas cobradas) |
| `amortizationScheduled` | `string` | Sim | Sistema de amortização ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractAmortizationScheduled)). Um dos valores de [sistema de amortização](#loan-amortization-system). |
| `amortizationScheduledAdditionalInfo` | `string` | Sim | Campo obrigatório para complementar as informações sobre a amortização programada quando tem valor 'OUTROS' |
| `cnpjConsignee` | `string` | Sim | CNPJ do consignatário |
| `interestRates` | array of [LoanInterestRate](#loan-interest-rate) | Sim | Taxas de juros aplicadas ao contrato. |
| `contractedFees` | array of [LoanContractedFee](#loan-contracted-fee) | Sim | Lista que traz as informações das tarifas acordadas no contrato. |
| `contractedFinanceCharges` | array of [LoanContractedFinanceCharge](#loan-contracted-finance-charge) | Sim | Lista que traz as cobranças acordadas no contrato |
| `warranties` | array of [LoanWarranty](#loan-warranty) | Sim | Garantias que garantem a operação de crédito. |
| `installments` | [LoanInstallments](#loan-installments) | Sim | Prazo restante e parcelas da operação. |
| `payments` | [LoanPayments](#loan-payments) | Sim | Dados de pagamento do contrato de empréstimo |
Veja [Empréstimo](/reference/loan) em nossa referência da API para mais informações.
## Periodicidade das parcelas do empréstimo
Frequência regular das parcelas
- `WITHOUT_REGULAR_PERIODICITY`
- `WEEKLY`
- `FORTNIGHTLY`
- `MONTHLY`
- `BIMONTHLY`
- `QUARTERLY`
- `SEMESTERLY`
- `YEARLY`
- `OTHERS`
## Sistema de amortização do empréstimo
Sistema de amortização ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractAmortizationScheduled))
- `SAC`
- `PRICE`
- `SAM`
- `WITHOUT_AMORTIZATION_SYSTEM`
- `OTHERS`
## Taxa de juros do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `taxType` | `string` | Sim | Tipo de taxa. Um dos valores de [tipo de taxa](#loan-tax-type). |
| `interestRateType` | `string` | Sim | Tipo de taxa de juros. Um dos valores de [tipo de taxa de juros](#loan-interest-rate-type). |
| `taxPeriodicity` | `string` | Sim | Periodicidade da taxa. Um dos valores de [periodicidade da taxa](#loan-tax-periodicity). |
| `calculation` | `string` | Sim | Base de cálculo |
| `referentialRateIndexerType` | `string` | Sim | Tipos de taxas de referência ou indexadores ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractReferentialRateIndexerType)). |
| `referentialRateIndexerSubType` | `string` | Sim | Subtipos de taxas de referência ou indexadores ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractReferentialRateIndexerSubType)). |
| `referentialRateIndexerAdditionalInfo` | `string` | Sim | Campo livre para complementar as informações sobre o tipo de taxa de referência ou indexador |
| `preFixedRate` | `number` | Sim | Taxa pré-fixada aplicada sob o contrato da modalidade de crédito. 1 = 100% |
| `postFixedRate` | `number` | Sim | Taxa pós-fixada aplicada sob o contrato da modalidade de crédito. 1 = 100% |
| `additionalInfo` | `string` | Sim | Texto com informações adicionais sobre a composição das taxas de juros acordadas |
## Tipo de taxa do empréstimo
- `NOMINAL`
- `EFFECTIVE`
## Tipo de taxa de juros do empréstimo
- `SIMPLE`
- `COMPOUND`
## Periodicidade da taxa do empréstimo
- `MONTHLY`
- `YEARLY`
## Taxa contratada do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `name` | `string` | Sim | Denominação da taxa acordada |
| `code` | `string` | Sim | Acrônimo identificando a taxa acordada |
| `chargeType` | `string` | Sim | Tipo de cobrança para a taxa acordada no contrato. Um dos valores de [tipo de cobrança](#contracted-fee-charge-type). |
| `charge` | `string` | Sim | Método de cobrança relacionado à tarifa acordada no contrato. Um dos valores de [cobrança](#contracted-fee-charge). |
| `amount` | `number` | Sim | Valor monetário da tarifa acordada no contrato |
| `rate` | `number` | Sim | Valor da taxa em percentual acordado no contrato |
## Tipo de cobrança da taxa contratada
Tipo de cobrança para a taxa acordada no contrato
- `UNIQUE`
- `BY_INSTALLMENT`
## Método de cobrança da taxa contratada
Método de cobrança relacionado à tarifa acordada no contrato
- `MINIMUM`
- `MAXIMUM`
- `FIXED`
- `PERCENTAGE`
## Cobrança contratada do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `type` | `string` | Sim | Tipo de cobrança acordada no contrato ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractFinanceChargeType)). |
| `additionalInfo` | `string` | Sim | Campo para informações adicionais |
| `rate` | `number` | Sim | Valor da cobrança em percentual acordado no contrato |
## Garantia do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `currencyCode` | `string` | Sim | Código que referencia a moeda da garantia |
| `type` | `string` | Sim | Denominação / Identificação do tipo de garantia que garante o tipo de operação de crédito contratada ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumWarrantyType)). |
| `subtype` | `string` | Sim | Denominação / Identificação do subtipo de garantia que garante o tipo de operação de crédito contratada ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumWarrantySubType)). |
| `amount` | `number` | Sim | Valor original da garantia |
## Parcelas do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `typeNumberOfInstallments` | `string` | Sim | Tipo de prazo total do contrato referente ao tipo de crédito informado. Um dos valores de [número de parcelas](#number-of-installments). |
| `totalNumberOfInstallments` | `number` | Sim | Prazo total de acordo com o tipo referente ao tipo de crédito informado |
| `typeContractRemaining` | `string` | Sim | Tipo de prazo restante do contrato referente ao tipo de crédito informado. Um dos valores de [tipo de contrato restante](#type-contract-remaining). |
| `contractRemainingNumber` | `number` | Sim | Prazo restante de acordo com o tipo referente ao tipo de crédito informado |
| `paidInstallments` | `number` | Sim | Número de parcelas pagas |
| `dueInstallments` | `number` | Sim | Número de parcelas devidas |
| `pastDueInstallments` | `number` | Sim | Número de parcelas em atraso |
| `balloonPayments` | array of [LoanInstallmentBalloonPayment](#loan-balloon-payment) | Sim | Lista que traz as datas de vencimento e valor das parcelas não regulares do contrato do tipo de crédito consultado |
## Número de parcelas
Tipo de prazo total do contrato referente ao tipo de crédito informado
- `DAY`
- `WEEK`
- `MONTH`
- `YEAR`
- `WITHOUT_TOTAL_PERIOD`
## Tipo de contrato restante
Tipo de prazo restante do contrato referente ao tipo de crédito informado
- `DAY`
- `WEEK`
- `MONTH`
- `YEAR`
- `WITHOUT_TOTAL_PERIOD`
- `WITHOUT_REMAINING_PERIOD`
## Pagamento balão do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `dueDate` | `string` | Sim | Data de expiração da parcela não regular a vencer do contrato da modalidade de crédito consultada |
| `amount` | [LoanInstallmentBalloonPaymentAmount](#balloon-payment-amount) | Sim | |
## Valor do pagamento balão
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `value` | `number` | Sim | Valor monetário da parcela não regular devida |
| `currencyCode` | `string` | Sim | Código que referencia a moeda da parcela |
## Pagamentos do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `contractOutstandingBalance` | `number` | Sim | Valor necessário para que o cliente quite a dívida |
| `releases` | array of [LoanPaymentRelease](#loan-payment-release) | Sim | Lista de pagamentos realizados no período |
## Liberação de pagamento do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `isOverParcelPayment` | `boolean` | Sim | Identifica se é um pagamento acordado (falso) ou um pagamento único (verdadeiro) |
| `installmentId` | `string` | Sim | Identificador da parcela, responsabilidade de cada Instituição transmissora |
| `paidDate` | `string` | Sim | Data efetiva do pagamento referente ao contrato da modalidade de crédito consultada |
| `currencyCode` | `string` | Sim | Código que referencia a moeda do pagamento |
| `paidAmount` | `number` | Sim | Valor do pagamento referente ao contrato da modalidade de crédito consultada |
| `overParcel` | [LoanPaymentReleaseOverParcel](#loan-payment-over-parcel) | Sim | |
## Pagamento sobre parcela do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `fees` | array of [LoanPaymentReleaseOverParcelFee](#over-parcel-fee) | Sim | Lista de taxas que foram pagas fora da parcela, apenas para pagamento único |
| `charges` | array of [LoanPaymentReleaseOverParcelCharge](#over-parcel-charge) | Sim | Lista de cobranças que foram pagas fora da parcela |
## Taxa sobre parcela do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `name` | `string` | Sim | Denominação da taxa acordada |
| `code` | `string` | Sim | Acrônimo identificando a taxa acordada |
| `amount` | `number` | Sim | Valor monetário da tarifa acordada no contrato |
## Cobrança sobre parcela do empréstimo
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| `type` | `string` | Sim | Tipo de cobrança acordada no contrato ([definição Open Finance](https://openbanking-brasil.github.io/openapi/swagger-apis/loans/?urls.primaryName=2.0.1#model-EnumContractFinanceChargeType)). |
| `additionalInfo` | `string` | Sim | Campo livre para preencher informações adicionais sobre a cobrança |
| `amount` | `number` | Sim | Valor do pagamento da cobrança paga fora da parcela |
## Identidade
Source: https://docs.pluggy.ai/pt/docs/products/identity.md
A entidade **Identidade** é recuperada de instituições que suportam este produto, acessando detalhes de informações pessoais relacionadas ao proprietário da conta da conexão. Recuperar este produto ajuda você a verificar as identidades dos usuários.
Para conectores de Open Finance, campos adicionais estão disponíveis, incluindo `investorProfile`, `qualifications`, `financialRelationships`, além de um conjunto mais rico de atributos PF (pessoa física) e PJ (pessoa jurídica) — `socialName`, `sex`, `maritalStatus`, `nationality`, `otherDocuments`, `passport`, `incorporationDate`, `parties`, `businessOtherDocuments` e `companiesCnpj`. Esses campos fornecem dados de clientes aprimorados para contas consentidas.
```json
{
"id": "42888436-62f5-49d2-8cf9-e312c7939509",
"fullName": "Francisco Sousa",
"companyName": "Pluggy Inc.",
"document": "123.456.789-00",
"taxNumber": "33.333.333/0001-33",
"documentType": "CPF",
"jobTitle": "Comercial",
"birthDate": "1991-05-01T00:00:00.000Z",
"investorProfile": "Moderate",
"establishmentCode": "001",
"establishmentName": "Pluggy Establishment",
"addresses": [
{
"fullAddress": "Av. Lucio Costa 1234, Copacabana, Rio de Janeiro, Brasil",
"country": "Brasil",
"state": "RJ",
"city": "Rio de Janeiro",
"additionalInfo": "Casa amarela",
"postalCode": "22620-171",
"primaryAddress": "Av. Lucio Costa, 1234",
"type": "Personal"
}
],
"phoneNumbers": [
{
"type": "Personal",
"value": "+54 911 12345678"
}
],
"emails": [
{
"type": "Personal",
"value": "hello@pluggy.ai"
}
],
"relations": [
{
"type": "CONJUGE",
"name": "Maria Sousa",
"document": "098.765.432-10"
}
]
}
```
Para conectores de Open Finance, a entidade Identidade carrega o conjunto de campos PF/PJ estendido:
```json title="Open Finance"
{
"id": "42888436-62f5-49d2-8cf9-e312c7939509",
"itemId": "9b59ab4b-2480-4dfc-9a0d-99b964ba578d",
"fullName": "Henrique Alexsander Eichstädt",
"socialName": "Henrique",
"companyName": "Tech Solutions LTDA",
"document": "12345678900",
"taxNumber": "33.333.333/0001-33",
"documentType": "CPF",
"jobTitle": "CEO",
"birthDate": "1985-03-15T00:00:00.000Z",
"sex": "MALE",
"maritalStatus": {
"code": "MARRIED"
},
"nationality": {
"hasBrazilianNationality": true
},
"otherDocuments": [
{
"type": "CNH",
"number": "12345678900",
"checkDigit": "P",
"additionalInfo": "SSP/SP",
"expirationDate": "2030-05-21T00:00:00.000Z"
}
],
"incorporationDate": "2010-01-01T00:00:00.000Z",
"parties": [
{
"type": "PARTNER",
"personType": "NATURAL_PERSON",
"documentType": "CPF",
"documentNumber": "12345678900",
"civilName": "Henrique Alexsander Eichstädt",
"startDate": "2010-01-01T00:00:00.000Z",
"shareholding": 0.51
}
],
"companiesCnpj": ["33333333000133"],
"addresses": [
{
"fullAddress": "Av. Paulista 1234, Bela Vista, 01310-100, São Paulo, Brasil",
"country": "Brasil",
"countryCode": "BRA",
"state": "SP",
"city": "São Paulo",
"district": "Bela Vista",
"ibgeTownCode": "3550308",
"postalCode": "01310-100",
"primaryAddress": "Av. Paulista, 1234",
"type": "Work",
"additionalInfo": "Sala 501",
"geographicCoordinates": {
"latitude": -23.5614,
"longitude": -46.6559
}
}
],
"phoneNumbers": [
{
"type": "Work",
"value": "+55 (11) 987654321",
"countryCallingCode": "55",
"areaCode": "11",
"extension": "501"
}
],
"emails": [
{
"type": "Work",
"value": "henrique@techsolutions.com.br"
}
],
"relations": [],
"investorProfile": "Moderate",
"qualifications": {
"companyCnpj": "33333333000133",
"occupationCode": "CBO",
"occupationDescription": "1234-5",
"informedIncome": {
"frequency": "ANUAL",
"amount": 250000,
"date": "2024-01-01T00:00:00.000Z"
},
"informedPatrimony": {
"amount": 1500000,
"year": 2024,
"date": "2024-12-31T00:00:00.000Z"
},
"economicActivities": [
{
"code": "6201501",
"isMain": true
}
],
"informedRevenue": {
"amount": 500000,
"frequency": "MONTHLY",
"year": 2024
}
},
"financialRelationships": {
"startDate": "2020-05-10T00:00:00.000Z",
"productsServicesType": [
"CONTA_DEPOSITO_A_VISTA",
"CONTA_POUPANCA",
"OPERACAO_CREDITO"
],
"procurators": [
{
"type": "PROCURADOR",
"cpfNumber": "45678912303",
"documentNumber": "45678912303",
"documentType": "CPF",
"civilName": "Roberto Carlos Mendes Silva",
"socialName": "Roberto"
}
],
"accounts": [
{
"compeCode": "237",
"branchCode": "0001",
"number": "123456",
"checkDigit": "7",
"type": "CONTA_DEPOSITO_A_VISTA",
"subtype": "INDIVIDUAL"
}
],
"portabilitiesReceived": [
{
"employerName": "Acme Inc",
"employerDocument": "60701190000104",
"paycheckBankDetainerCnpj": "60701190000204",
"paycheckBankDetainerIspb": "60701190",
"portabilityApprovalDate": "2021-03-15T00:00:00.000Z"
}
],
"paychecksBankLink": [
{
"employerName": "Acme Inc",
"employerDocument": "60701190000104",
"paycheckBankCnpj": "60701190000204",
"paycheckBankIspb": "60701190",
"accountOpeningDate": "2020-01-10T00:00:00.000Z"
}
]
},
"createdAt": "2020-09-30T14:38:12.724Z",
"updatedAt": "2024-12-12T10:30:00.000Z"
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| id | string | Não | Identificador primário. |
| fullName | string | Não | Nome completo do proprietário da conta. |
| companyName | string | Sim | Nome da empresa (para contas de negócios). |
| document | string | Não | Número do documento (CPF ou CNPJ). |
| taxNumber | string | Sim | Número de identificação fiscal. |
| documentType | string | Não | Tipo do documento (CPF, CNPJ). |
| jobTitle | string | Sim | Cargo do proprietário da conta. |
| birthDate | string | Sim | Data de nascimento. |
| investorProfile | string | Sim | Classificação do perfil do investidor (por exemplo, Conservador, Moderado, Agressivo). Disponível apenas para conectores de Open Finance. |
| establishmentCode | string | Sim | Código do estabelecimento. |
| establishmentName | string | Sim | Nome do estabelecimento. |
| addresses | array | Sim | Lista de endereços associados à identidade. |
| phoneNumbers | array | Sim | Lista de números de telefone. |
| emails | array | Sim | Lista de endereços de e-mail. |
| relations | array | Sim | Lista de pessoas relacionadas (por exemplo, cônjuge). |
| socialName | string | Sim | Nome social da pessoa física, se houver (apenas PF, Open Finance). |
| sex | string | Sim | Sexo da pessoa física — `FEMALE`, `MALE` ou `OTHER` (apenas PF, Open Finance). |
| maritalStatus | [MaritalStatus](#maritalstatus) | Sim | Estado civil da pessoa física (apenas PF, Open Finance). |
| nationality | [Nationality](#nationality) | Sim | Nacionalidade da pessoa física (apenas PF, Open Finance). |
| otherDocuments | array of [OtherDocument](#otherdocument) | Sim | Lista de outros documentos de identificação que a pessoa física possui — CNH, RG, NIF, RNE ou OUTRO (apenas PF, Open Finance). |
| passport | [Passport](#passport) | Sim | Metadados do passaporte — aplica-se quando a pessoa física é um não-residente que não precisa registrar um CPF (apenas PF, Open Finance). |
| incorporationDate | Date | Sim | Data em que a empresa foi incorporada (apenas PJ, Open Finance). |
| parties | array of [BusinessParty](#businessparty) | Sim | Sócios e administradores da empresa (apenas PJ, Open Finance). |
| businessOtherDocuments | array of [BusinessOtherDocument](#businessotherdocument) | Sim | Documentos adicionais para empresas com sede no exterior e que não precisam registrar um CNPJ (apenas PJ, Open Finance). |
| companiesCnpj | array of string | Sim | CNPJs das instituições financeiras responsáveis pelo cadastro do cliente (Open Finance, PF e PJ). |
| qualifications | [Qualifications](#qualifications) | Sim | Dados de qualificações do cliente. Disponível apenas para conectores de Open Finance. |
| financialRelationships | [FinancialRelationships](#financialrelationships) | Sim | Relacionamento do cliente com a instituição. Disponível apenas para conectores de Open Finance. |
## Endereço
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| fullAddress | string | Sim | String de endereço completo. |
| country | string | Sim | Nome do país. |
| countryCode | string | Sim | Código do país no formato alpha3 ISO-3166 (por exemplo, `BRA`). Apenas Open Finance. |
| state | string | Sim | Código do estado. |
| city | string | Sim | Nome da cidade. |
| district | string | Sim | Bairro. Apenas Open Finance. |
| ibgeTownCode | string | Sim | Código do município IBGE (7 dígitos). Os dois primeiros dígitos identificam a Unidade da Federação. Apenas Open Finance. |
| additionalInfo | string | Sim | Informações adicionais sobre o endereço. |
| postalCode | string | Sim | Código postal/ZIP. |
| primaryAddress | string | Sim | Endereço principal. |
| type | string | Sim | Tipo de endereço (Pessoal, Trabalho). |
| geographicCoordinates | object | Sim | Coordenadas geográficas em graus decimais, sistema de referência WGS84. Objeto com `latitude` e `longitude`. Apenas Open Finance. |
## Número de Telefone
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| type | string | Sim | Tipo de número de telefone (Pessoal, Trabalho ou Residencial). |
| value | string | Sim | Valor do número de telefone. |
| countryCallingCode | string | Sim | Código de discagem internacional (DDI). Preenchido quando diferente de `55`. Apenas Open Finance. |
| areaCode | string | Sim | Código de área (DDD) do telefone. Apenas Open Finance. |
| extension | string | Sim | Número da extensão, quando parte da identificação do telefone. Apenas Open Finance. |
| additionalInfo | string | Sim | Informações adicionais sobre o telefone, por exemplo, quando o tipo de origem não se encaixa nas categorias padrão. Apenas Open Finance. |
## E-mail
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| type | string | Sim | Tipo de e-mail (Pessoal, Negócios). |
| value | string | Sim | Valor do endereço de e-mail. |
## Relação
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| type | string | Sim | Tipo de relação (por exemplo, CONJUGE, PROCURADOR). |
| name | string | Sim | Nome da pessoa relacionada. |
| document | string | Sim | Número do documento da pessoa relacionada. |
## MaritalStatus
Estado civil da pessoa física (apenas PF, Open Finance).
```json
{
"code": "MARRIED",
"additionalInfo": "União civil"
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| code | string | Sim | `SINGLE`, `MARRIED`, `WIDOWED`, `JUDICIALLY_SEPARATED`, `DIVORCED`, `STABLE_UNION` ou `OTHER`. |
| additionalInfo | string | Sim | Complemento em texto livre. Deve ser definido quando `code` for `OTHER`. |
## Nacionalidade
Nacionalidade da pessoa física (apenas PF, Open Finance).
```json
{
"hasBrazilianNationality": false,
"otherNationalities": [
{
"countryCode": "ITA",
"documents": [
{
"type": "Passport",
"number": "YA1234567",
"country": "ITA",
"issueDate": "2020-05-30T00:00:00.000Z",
"expirationDate": "2030-05-30T00:00:00.000Z"
}
]
}
]
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| hasBrazilianNationality | boolean | Sim | Se o cliente possui nacionalidade brasileira. |
| otherNationalities | array | Sim | Outras nacionalidades que o cliente possui, se houver. |
Cada entrada `otherNationalities[]`:
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| countryCode | string | Sim | Código do país no formato alpha3 ISO-3166. |
| documents | array | Sim | Documentos de apoio para esta nacionalidade. Veja `NationalityDocument` abaixo. |
Cada entrada `documents[]` (`NationalityDocument`):
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| type | string | Sim | Tipo de documento (texto livre). Obrigatório quando a nacionalidade não é brasileira. |
| number | string | Sim | Número do documento. Obrigatório quando a nacionalidade não é brasileira. |
| country | string | Sim | Nome do país. |
| issueDate | Date | Sim | Data de emissão do documento. |
| expirationDate | Date | Sim | Data de expiração do documento. |
| additionalInfo | string | Sim | Complemento em texto livre. |
## OtherDocument
Outros documentos de identificação que a pessoa física possui (apenas PF, Open Finance). As siglas brasileiras são mantidas verbatim; `OTHER` cobre qualquer outro tipo.
```json
{
"type": "CNH",
"number": "12345678900",
"checkDigit": "P",
"additionalInfo": "SSP/SP",
"expirationDate": "2030-05-21T00:00:00.000Z"
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| type | string | Sim | `CNH`, `RG`, `NIF`, `RNE` ou `OTHER`. |
| typeAdditionalInfo | string | Sim | Complemento em texto livre. Deve ser definido quando `type` for `OTHER`. |
| number | string | Sim | Número do documento. |
| checkDigit | string | Sim | Dígito de verificação do documento, se houver. |
| additionalInfo | string | Sim | Complemento em texto livre, usado para registrar a autoridade emissora (por exemplo, `SSP/SP`) quando relevante. |
| expirationDate | Date | Sim | Data de expiração do documento. |
## Passaporte
Metadados do passaporte para a pessoa física (apenas PF, Open Finance). Aplica-se quando o cliente é um não-residente que não precisa registrar um CPF.
```json
{
"number": "YA1234567",
"country": "ITA",
"issueDate": "2020-05-30T00:00:00.000Z",
"expirationDate": "2030-05-30T00:00:00.000Z"
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| number | string | Sim | Número do passaporte. |
| country | string | Sim | País emissor no formato alpha3 ISO-3166. |
| issueDate | Date | Sim | Data de emissão do passaporte. |
| expirationDate | Date | Sim | Data de expiração do passaporte. |
## BusinessParty
Sócio ou administrador de uma empresa (apenas PJ, Open Finance). Sócios com menos de 25% de participação podem ser omitidos pela instituição.
```json
{
"type": "PARTNER",
"personType": "NATURAL_PERSON",
"documentType": "CPF",
"documentNumber": "12345678900",
"civilName": "Henrique Alexsander Eichstädt",
"startDate": "2010-01-01T00:00:00.000Z",
"shareholding": 0.51
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| type | string | Sim | `PARTNER` (sócio) ou `ADMINISTRATOR` (administrador). |
| personType | string | Sim | `NATURAL_PERSON` ou `LEGAL_ENTITY`. |
| documentType | string | Sim | `CPF`, `CNPJ`, `PASSPORT` ou `OTHER_TRAVEL_DOCUMENT`. |
| documentNumber | string | Sim | Número do documento de identificação (dígitos e dígito de verificação, se houver). |
| documentCountry | string | Sim | País emissor do documento, alpha3 ISO-3166. |
| documentExpirationDate | Date | Sim | Data de expiração do documento. |
| documentIssueDate | Date | Sim | Data de emissão do documento. |
| documentAdditionalInfo | string | Sim | Complemento em texto livre quando o documento contém informações de identificação que não se encaixam nos outros campos. |
| civilName | string | Sim | Nome civil da parte. Obrigatório quando `personType` é `NATURAL_PERSON`. |
| socialName | string | Sim | Nome social da parte pessoa física, se houver. |
| companyName | string | Sim | Nome da empresa da parte. Obrigatório quando `personType` é `LEGAL_ENTITY`. |
| tradeName | string | Sim | Nome comercial da parte pessoa jurídica, se houver. |
| startDate | Date | Sim | Data em que a participação da parte começou. |
| shareholding | number | Sim | Fração de participação entre 0 e 1 (por exemplo, `0.51` representa 51%, `1` representa 100%). Obrigatório quando `type` é `PARTNER` e a participação é de 25% ou mais. |
## BusinessOtherDocument
Documento adicional para empresas com sede no exterior e que não precisam registrar um CNPJ (apenas PJ, Open Finance).
```json
{
"type": "EIN",
"number": "128328453",
"country": "USA",
"expirationDate": "2030-05-21T00:00:00.000Z"
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| type | string | Sim | Tipo do documento (por exemplo, `EIN`). |
| number | string | Sim | Número do documento. |
| country | string | Sim | País emissor no formato alpha3 ISO-3166. |
| expirationDate | Date | Sim | Data de expiração do documento. |
## Qualifications
Dados de qualificações do cliente (Open Finance).
```json
{
"companyCnpj": "33333333000133",
"occupationCode": "CBO",
"occupationDescription": "1234-5",
"informedIncome": {
"frequency": "ANUAL",
"amount": 250000,
"date": "2024-01-01T00:00:00.000Z"
},
"informedPatrimony": {
"amount": 1500000,
"year": 2024,
"date": "2024-12-31T00:00:00.000Z"
},
"economicActivities": [
{
"code": "6201501",
"isMain": true
}
],
"informedRevenue": {
"amount": 500000,
"frequency": "MONTHLY",
"year": 2024
}
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| companyCnpj | string | Sim | CNPJ da empresa associada às qualificações. |
| occupationCode | string | Sim | `RECEITA_FEDERAL`, `CBO` ou `OUTRO`. |
| occupationDescription | string | Sim | Descrição da ocupação em texto livre. Contém o código da lista padronizada quando `occupationCode` é `RECEITA_FEDERAL` ou `CBO`; a descrição personalizada quando `OUTRO`. |
| informedIncome | object | Sim | Renda informada. Objeto com `frequency` (`DIARIA`, `SEMANAL`, `QUINZENAL`, `MENSAL`, `BIMESTRAL`, `TRIMESTRAL`, `SEMESTRAL`, `ANUAL`, `OUTROS`), `amount` e `date`. |
| informedPatrimony | object | Sim | Patrimônio informado. Objeto com `amount`, `year` e opcionalmente `date` (retornado no caminho de negócios PJ). |
| economicActivities | array | Sim | Códigos CNAE descrevendo as atividades econômicas da empresa (apenas PJ). Cada entrada tem `code` (CNAE de 7 dígitos) e `isMain` booleano. |
| informedRevenue | object | Sim | Receita (faturamento) informada pela empresa — o equivalente empresarial de `informedIncome` (apenas PJ). Objeto com `amount`, `frequency` opcional (`DAILY`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIANNUAL`, `ANNUAL`, `OTHER`), `frequencyAdditionalInfo` e `year`. |
## FinancialRelationships
Relacionamento do cliente com a instituição (Open Finance).
```json
{
"startDate": "2020-05-10T00:00:00.000Z",
"productsServicesType": ["CONTA_DEPOSITO_A_VISTA", "OPERACAO_CREDITO"],
"procurators": [
{
"type": "PROCURADOR",
"cpfNumber": "45678912303",
"documentNumber": "45678912303",
"documentType": "CPF",
"civilName": "Roberto Carlos Mendes Silva",
"socialName": "Roberto"
}
],
"accounts": [
{
"compeCode": "237",
"branchCode": "0001",
"number": "123456",
"checkDigit": "7",
"type": "CONTA_DEPOSITO_A_VISTA",
"subtype": "INDIVIDUAL"
}
],
"portabilitiesReceived": [
{
"employerName": "Acme Inc",
"employerDocument": "60701190000104",
"paycheckBankDetainerCnpj": "60701190000204",
"paycheckBankDetainerIspb": "60701190",
"portabilityApprovalDate": "2021-03-15T00:00:00.000Z"
}
],
"paychecksBankLink": [
{
"employerName": "Acme Inc",
"employerDocument": "60701190000104",
"paycheckBankCnpj": "60701190000204",
"paycheckBankIspb": "60701190",
"accountOpeningDate": "2020-01-10T00:00:00.000Z"
}
]
}
```
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| startDate | Date | Sim | Data em que o relacionamento com a instituição começou. |
| productsServicesType | array of string | Sim | Lista de produtos e serviços que o cliente consome (por exemplo, `CONTA_DEPOSITO_A_VISTA`, `CARTAO_CREDITO`, `OPERACAO_CREDITO`). |
| productsServicesTypeAdditionalInfo | string | Sim | Informações adicionais sobre os produtos e serviços. Preenchido quando `productsServicesType` inclui `OUTROS`. |
| procurators | array | Sim | Lista de procuradores. Cada entrada tem `type` (`REPRESENTANTE_LEGAL` ou `PROCURADOR`), `cpfNumber` (legado — pode conter um CNPJ em PJ), o par canônico `documentNumber` + `documentType` (`CPF` / `CNPJ`), `civilName` e opcionalmente `socialName`. |
| accounts | array | Sim | Lista de contas consentidas. Cada entrada tem `compeCode`, `branchCode`, `number`, `checkDigit`, `type` (`CONTA_DEPOSITO_A_VISTA`, `CONTA_POUPANCA`, `CONTA_PAGAMENTO_PRE_PAGA`) e `subtype` (`INDIVIDUAL`, `CONJUNTA_SIMPLES`, `CONJUNTA_SOLIDARIA`). |
| portabilitiesReceived | array | Sim | Portabilidades de salário recebidas pela instituição dos bancos de folha de pagamento anteriores do cliente (banco-folha). Apenas PF. Veja o esquema de entrada abaixo. |
| paychecksBankLink | array | Sim | Links de banco de folha de pagamento (banco-folha) para empregadores, ativos ou anteriormente ativos. Apenas PF. Veja o esquema de entrada abaixo. |
Cada entrada `portabilitiesReceived[]`:
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| employerName | string | Sim | Nome do empregador conforme recebido na mensagem de portabilidade. |
| employerDocument | string | Sim | Documento do empregador (CPF ou CNPJ) conforme recebido na mensagem de portabilidade. |
| paycheckBankDetainerCnpj | string | Sim | CNPJ do banco que detém a conta de pagamento (banco-folha). |
| paycheckBankDetainerIspb | string | Sim | ISPB do banco que detém a conta de pagamento. |
| portabilityApprovalDate | Date | Sim | Data em que a portabilidade foi aprovada. |
Cada entrada `paychecksBankLink[]`:
| Propriedade | Tipo | Opcional | Descrição |
|-------------|------|----------|-----------|
| employerName | string | Sim | Nome do empregador conforme registrado quando a conta de pagamento foi aberta. |
| employerDocument | string | Sim | Documento do empregador (CPF ou CNPJ) conforme registrado quando a conta de pagamento foi aberta. |
| paycheckBankCnpj | string | Sim | CNPJ da instituição contratada para fornecer o serviço de pagamento (banco-folha). |
| paycheckBankIspb | string | Sim | ISPB da instituição contratada para fornecer o serviço de pagamento. |
| accountOpeningDate | Date | Sim | Data em que a conta de pagamento foi aberta. |
Veja [Identidade](/reference/identity) em nossa referência da API para mais informações.
## Parcelas de Cartão de Crédito
Source: https://docs.pluggy.ai/pt/docs/products/credit-card-installments.md
Como as compras parceladas são capturadas, sincronizadas e entregues através da API Pluggy.
## Visão Geral
Esta página descreve como a Pluggy captura, processa e entrega transações de compras parceladas com cartão de crédito. O objetivo é ajudar as equipes de produto e desenvolvimento a entender o comportamento esperado da API, as limitações do ecossistema de Open Finance e as melhores práticas para lidar com esse tipo de dado.
A regulamentação de Open Finance (Banco Central do Brasil) exige que as instituições disponibilizem dados de compras parceladas, mas não especifica como esses dados devem ser formatados ou estruturados. Isso leva a comportamentos diferentes entre os bancos: alguns postam todas as parcelas de uma vez, outros as criam mês a mês, e outros retornam apenas a parcela atual.
A Pluggy está mapeando ativamente o comportamento de cada instituição e trabalhando em conjunto com o ecossistema de Open Finance para promover uma maior padronização.
## Fundamentos: Contas e Transações
### Como as transações de cartão de crédito chegam via API
Quando um usuário conecta uma conta de cartão de crédito, a Pluggy busca 12 meses de transações. Nas atualizações diárias subsequentes, os últimos 7 dias de transações recentes são buscados. Para cartões de crédito, há também um terceiro mecanismo: buscar transações por conta, explicado abaixo.
### Endpoint de Transações Recentes vs. Endpoint de Contas na API de Open Finance
A Pluggy utiliza a API de Open Finance, que possui dois fluxos distintos para capturar transações de cartão de crédito:
| Fluxo | Descrição |
|-------|-----------|
| Transações Recentes (`transactions-current`) | Busca os últimos 7 dias de transações. Todas as transações retornadas aqui aparecem com status `PENDING` e sem um `billId` associado. |
| Transações por Conta (`/bills/:billId/transactions`) | Busca todas as transações vinculadas a uma conta específica, passando o ID da conta como filtro. Este endpoint é chamado uma vez por dia e, consequentemente, quando uma nova conta vence e começa a ser retornada, é chamado novamente. |
### O ciclo de vida de uma transação de cartão
Toda transação de cartão de crédito passa pelo seguinte ciclo:
1. A transação aparece nas transações recentes com status `PENDING` e sem um `billId`.
2. Quando a conta vence, a Pluggy identifica a nova conta e chama o endpoint de transações com o ID daquela conta.
3. As transações daquela conta começam a retornar com um `billId` associado e o status muda para `POSTED`.
4. A Pluggy dispara um webhook com as transações atualizadas (status e `billId` preenchidos).
- **`PENDING`**: a transação pertence a uma conta que ainda está aberta. Não possui `billId`.
- **`POSTED`**: a transação pertence a uma conta que já está vencida. Possui um `billId` associado.
Atenção: ao buscar apenas os últimos 7 dias de atualizações, uma transação mais antiga que passou de `PENDING` para `POSTED` pode não aparecer. Para capturar essas mudanças, é essencial consumir o webhook de transações atualizadas (`transaction/updated`). Veja [Webhooks](/docs/developer-tools/webhooks-ref).
## Comportamento das Parcelas por Instituição
A falta de padronização em Open Finance significa que cada banco retorna parcelas de maneiras diferentes. A Pluggy está mapeando o comportamento de cada instituição. Abaixo estão os padrões gerais identificados até agora.
### Padrão A: Todas as parcelas postadas de uma vez
Algumas instituições postam todas as parcelas imediatamente após a compra, já nas transações recentes. Cada parcela aparece como uma transação separada.
- **1ª parcela:** retornada com a data da transação original (data da compra).
- **Parcelas restantes:** retornadas com a data de postagem da conta (`billPostDate`) — que corresponde ao mês de vencimento de cada parcela.
- **Quando a conta vence:** a parcela correspondente é atualizada e recebe um `billId`. A Pluggy dispara o webhook de transações atualizadas com o novo `billId`.
### Padrão B: Parcelas postadas mês a mês
Outras instituições criam parcelas gradualmente — uma nova parcela aparece cada vez que uma conta é fechada ou vence. Este é o comportamento mais comum entre os principais bancos.
A Pluggy busca as transações de cada nova conta vencida. As parcelas aparecem nesse momento, já com um `billId`.
Atenção: ao consultar apenas o endpoint de transações com um filtro de data, essas parcelas mais antigas podem não aparecer. Use o webhook de transações criadas (`transaction/created`) para garantir que nenhuma parcela seja perdida.
### Comportamento especial: Janela entre o fechamento e a data de vencimento
Em alguns bancos, há um período entre o fechamento da conta e sua data de vencimento (tipicamente de 7 a 10 dias). Durante essa janela, novas parcelas podem aparecer — ou seja, quando a conta fecha, o banco já gera a próxima parcela para a conta que ainda não está vencida.
*Isso significa que a Pluggy pode retornar, via o webhook de transações criadas, uma parcela associada a uma conta que existe no endpoint de contas, mas que pode não estar vencida ainda, apenas fechada. Esse comportamento foi identificado em pelo menos um banco e pode ocorrer em outros.*
## Campos de Parcelas Disponíveis
Cada transação de compra parcelada pode conter os seguintes campos (quando retornados pela instituição):
| Campo | Descrição |
|-------|-----------|
| `installmentNumber` | Número da parcela atual (ex: 1, 2, 3...) |
| `totalInstallments` | Número total de parcelas da compra |
| `totalAmount` | Valor total da compra (todas as parcelas combinadas). *Não retornado por Open Finance — apenas conectores diretos.* |
| `amount` | Valor daquela parcela específica |
| `date` | Data da transação (varia por banco — pode ser a data da compra ou a data de postagem da conta) |
| `billId` | ID da conta à qual a transação está vinculada (ausente se a conta ainda não estiver vencida) |
Além dos campos acima, a API de Open Finance retorna o campo `billPostDate` (a data em que a transação foi postada na conta), que a Pluggy usa internamente para compor o campo `date` das parcelas após a primeira. Este campo não é exposto diretamente na resposta JSON da API Pluggy.
Atualmente, o Open Finance não retorna um identificador único que agrupe todas as parcelas da mesma compra. Isso significa que, para identificar que duas transações pertencem ao mesmo plano de parcelas, você precisa usar heurísticas baseadas nos campos disponíveis (`installmentNumber`, `totalInstallments`, a `date` da primeira parcela, nome do comerciante, etc.).
A Pluggy está avaliando a abertura de um pedido de melhoria com o ecossistema de Open Finance para solicitar esse campo de agrupamento.
## Limites Operacionais e Seu Impacto nas Parcelas
O Open Finance define limites de chamadas por CPF/CNPJ por instituição, por mês. Esses limites afetam diretamente a capacidade de sincronizar dados de cartão de crédito, incluindo parcelas.
### Limites relevantes para cartões de crédito
| Operação | Limite |
|----------|--------|
| Transações recentes (últimos 7 dias) | 240 chamadas por mês |
| Transações históricas (além de 7 dias até 12 meses) | 4 chamadas por mês |
| Listagem de contas | 30 chamadas por mês (aprox. 1 por dia) |
| Listagem de contas e cartões | 4 chamadas por mês |
O limite de 4 chamadas/mês para transações históricas é o mais crítico. Se um usuário tentar conectar a mesma conta várias vezes (por exemplo, porque a conexão falhou parcialmente), esse limite pode ser alcançado rapidamente.
Quando o limite é atingido, a chamada retorna um erro de limite operacional e nenhuma nova busca de 12 meses é possível até o próximo mês.
Atenção: o limite é por CPF/CNPJ por instituição — não por item ou por cliente Pluggy. Se o usuário já compartilhou dados com outra plataforma no mesmo mês, o limite pode já ter sido parcialmente consumido.
### Melhores práticas para evitar esgotar o limite
- Evite criar múltiplas conexões com o mesmo CPF/CNPJ para o mesmo banco.
- Implemente controle de tentativas no frontend: se a conexão falhar, oriente o usuário a esperar antes de tentar novamente.
- Use o endpoint de verificação de status do item (`GET /items/{id}`) após a conexão para verificar se todos os produtos foram recuperados com sucesso, antes de solicitar uma nova sincronização.
## Webhooks e Atualizações de Parcelas
Para garantir que nenhuma atualização de parcela seja perdida, é essencial consumir os [webhooks](/docs/developer-tools/webhooks-ref) da Pluggy. As parcelas podem aparecer ou ser atualizadas em momentos assíncronos, fora da janela de 7 dias de transações recentes.
### Eventos relevantes para planos de parcelas
| Evento | Quando ocorre |
|--------|---------------|
| `transaction/created` | Uma nova parcela apareceu (ex: o banco postou a parcela do próximo mês após o fechamento da conta). |
| `transaction/updated` | Uma transação existente foi atualizada — por exemplo, uma parcela que estava `PENDING` se tornou `POSTED` e recebeu um `billId`. |
| `transaction/deleted` | Uma transação foi removida. Isso pode ocorrer em casos ocasionais em que o banco para de retornar uma transação por alguns dias e depois a retorna novamente com um novo ID. |
Em casos raros, um banco pode parar de retornar uma transação por 1 a 3 dias e depois retorná-la novamente. Quando isso acontece, a Pluggy remove a transação e dispara `transaction/deleted`. Quando ela volta, a Pluggy dispara `transaction/created` com um novo ID.
Isso pode acontecer, por exemplo, com transações de fim de semana ou durante instabilidades ocasionais na instituição. Não é um comportamento alarmante, mas deve ser tratado no lado do cliente.
## Recomendações para Equipes de Desenvolvimento
### Para garantir a completude das parcelas
- Sempre consuma os webhooks `transaction/created` e `transaction/updated` para capturar parcelas que aparecem fora da janela de 7 dias.
- Não confie exclusivamente no endpoint de transações recentes para construir o histórico de parcelas.
- Ao identificar uma conta vencida, verifique se as transações daquela conta (via o endpoint de transações filtrado por `billId`) correspondem ao valor total da [conta](/docs/products/credit-card-bills) — isso ajuda a detectar parcelas faltantes.
### Para identificar parcelas da mesma compra
- Use os campos `installmentNumber` e `totalInstallments` como o primeiro critério de agrupamento.
- Complete com a `date` da primeira parcela e nome do comerciante quando disponível.
- `totalAmount` não é retornado pelos conectores de Open Finance — está disponível apenas em conectores diretos, portanto não pode ser usado como uma chave de agrupamento aqui.
- Lembre-se de que o comportamento varia por banco: o mesmo conjunto de heurísticas pode não funcionar para todas as instituições.
- Siga o mapeamento por instituição que a Pluggy está desenvolvendo.
### Para relatar problemas de parcelas
- Abra um ticket com o suporte da Pluggy informando: banco, ID do item, período afetado e uma descrição do comportamento observado.
- Se possível, inclua evidências do usuário (extrato ou conta) mostrando a discrepância — isso é necessário para escalar o caso para a instituição financeira.
- Para casos estruturais (afetando múltiplos usuários), sinalize diretamente via Slack com a equipe de suporte da Pluggy para priorização.
## Glossário
| Termo | Definição |
|-------|-----------|
| `billId` | Identificador único de uma conta de cartão de crédito no ecossistema de Open Finance. |
| `billPostDate` *(API de Open Finance)* | Data em que uma transação foi postada em uma conta. Usado pela Pluggy para determinar a data das parcelas subsequentes. |
| `PENDING` | Status de uma transação que pertence a uma conta que ainda está aberta (não vencida). |
| `POSTED` | Status de uma transação vinculada a uma conta que já está vencida, com `billId` preenchido. |
| Limite Operacional | Limite de chamadas à API de Open Finance por CPF/CNPJ por instituição, definido pelo Banco Central. |
| Transações Recentes | Endpoint que retorna os últimos 7 dias de transações de uma conta ou cartão. |
| Transações Históricas | Busca de transações além de 7 dias (até 12 meses). Limitado a 4 chamadas por mês por CPF/CNPJ por banco. |
| Webhook | Notificação enviada pela Pluggy para o sistema do cliente quando um evento ocorre (ex: transação criada, atualizada ou deletada). |
*Para dúvidas, entre em contato com a equipe de Suporte via Slack.*
## Insights de Conexão
Source: https://docs.pluggy.ai/pt/docs/intelligence/connection-insights.md
Com base nas contas conectadas, você pode recuperar insights do usuário, livro de variáveis, análise de renda e padrões recorrentes.
Além dos insights úteis da [categorização de transações](/docs/transaction-categories), a Pluggy oferece uma **Insights API** para ajudá-lo a reunir insights sobre os dados dos seus Items para agrupar, filtrar ou agrupar rapidamente seus itens de acordo com seus **KPIs financeiros** ou seus **indicadores de renda**.
## KPIs financeiros do Item
Um recurso prático para construir rapidamente inteligência sobre seus Items é observar seus KPIs financeiros, que correspondem a estatísticas financeiras importantes, como fluxo de caixa, distribuição de transações de débito/crédito, etc.
Oferecemos uma API HTTP para calcular esses KPIs. Aqui está um exemplo de como usá-la:
1. Primeiro, [autentique-se](/docs/authentication) na API da Pluggy para obter uma chave de API
2. Execute a seguinte solicitação
```curl
curl --location --request POST 'https://insights-api.pluggy.ai/book?itemIds={your-item-id}' \
--header 'X-API-KEY: {YOUR-API-KEY}'
```
3. Aqui está um exemplo de resposta:
```json
{
"id": "b3b60afc-6a76-43ae-9c94-3457ce8952b2",
"status": "COMPLETED",
"book": {
"bankAccount": {
"percentage_transactions_debit_dates_1-5_M1": null,
"percentage_transactions_credit_dates_1-5_M1": null,
"count_transactions_debit_dates_1-5_M1": 0,
"count_transactions_credit_dates_1-5_M1": 0,
"amount_transactions_debit_dates_1-5_M1": 0,
"amount_transactions_credit_dates_1-5_M1": 0,
"percentage_transactions_debit_dates_6-10_M1": null,
"percentage_transactions_credit_dates_6-10_M1": null,
"count_transactions_debit_dates_6-10_M1": 0,
"count_transactions_credit_dates_6-10_M1": 0,
"amount_transactions_debit_dates_6-10_M1": 0,
"amount_transactions_credit_dates_6-10_M1": 0,
"diff_transactions_net_amount_M1": 0,
"count_transactions_credit_M1": 0,
"count_transactions_debit_M1": 0,
"min_transactions_balance_M1": null,
"max_transactions_balance_M1": null,
"sum_transactions_credit_M1": 0,
"sum_transactions_debit_M1": 0,
"ratio_transactions_creditdebit_M1": null,
"ratio_inflow_commitment_M1": null,
"avg_transactions_credit_M1": null,
"avg_transactions_debit_M1": null,
"avg_transactions_credit_balance_M1": null,
"avg_transactions_debit_balance_M1": null,
"max_transactions_debit_period_M1": "",
"max_transactions_credit_period_M1": "",
"diff_transactions_net_amount_alltime": 394,
"count_transactions_credit_alltime": 7,
"count_transactions_debit_alltime": 1,
"min_transactions_balance_alltime": null,
"max_transactions_balance_alltime": null,
"sum_transactions_credit_alltime": 520,
"sum_transactions_debit_alltime": 126,
"ratio_transactions_creditdebit_alltime": 4.13,
"ratio_inflow_commitment_alltime": 169.62,
"avg_transactions_credit_alltime": 74.29,
"avg_transactions_debit_alltime": 126,
"avg_transactions_credit_balance_alltime": 0,
"avg_transactions_debit_balance_alltime": 0,
"max_transactions_debit_period_alltime": "26-31",
"max_transactions_credit_period_alltime": "26-31",
"ratio_inflow_commitment_trend": null
},
"categories": [
{
"category": "Transfers",
"transactionType": "CREDIT",
"accountSubtype": "SAVINGS_ACCOUNT",
"M1": { "avg": null, "total": 0 },
"M2": { "avg": null, "total": 0 },
"M3": { "avg": null, "total": 0 },
"M6": { "avg": 68.5, "total": 137, "min": 59, "max": 78 },
"M12": { "avg": 68.5, "total": 137, "min": 59, "max": 78 }
},
{
"category": "Third party transfers",
"transactionType": "CREDIT",
"accountSubtype": "SAVINGS_ACCOUNT",
"M1": { "avg": null, "total": 0 },
"M2": { "avg": null, "total": 0 },
"M3": { "avg": null, "total": 0 },
"M6": { "avg": 96.5, "total": 193, "min": 57, "max": 136 },
"M12": { "avg": 96.5, "total": 193, "min": 57, "max": 136 }
}
],
"creditCard": {
"percentage_transactions_debit_dates_1-5_M1": null,
"percentage_transactions_credit_dates_1-5_M1": null,
"count_transactions_debit_dates_1-5_M1": 0,
"count_transactions_credit_dates_1-5_M1": 0,
"diff_transactions_net_amount_alltime": 0,
"count_transactions_credit_alltime": 0,
"count_transactions_debit_alltime": 0,
"ratio_transactions_creditdebit_alltime": null,
"ratio_inflow_commitment_alltime": null,
"ratio_inflow_commitment_trend": null,
"limit_commitment_trend": null
}
},
"metadata": {
"itemsIds": [
"786583d9-ab31-44d9-86d4-a468e1a41168"
]
}
}
```
**Notas:**
- `M1` representa o último mês, `M2` os últimos dois meses e `M12` doze meses.
- `dates_1-5` representa que está filtrado entre as datas nos primeiros dias do mês. `dates_16-20` representa entre o dia 16 e 20, ambos inclusos.
- `amount_200-500` representa transações com valores entre 200 e 500.
A resposta do livro também inclui dados de análise de renda:
```json
{
"status": "COMPLETED",
"itemId": "b3b60afc-6a76-43ae-9c94-3457ce8952b2",
"result": {
"totalIncomeStatistics": {
"daysCoveredWithIncome": 180,
"firstIncomeDate": "2021-11-01T00:00:00",
"lastIncomeDate": "2022-04-29T00:00:00",
"numIncomeTransactions": 17,
"averageMonthlyIncomeLast30Days": 821.51,
"averageMonthlyIncomeLast90Days": 3638.51,
"averageMonthlyIncomeLast180Days": 3727.7134,
"averageMonthlyIncomeLast360Days": 1863.8567
},
"irregularIncomeStatistics": {
"daysCoveredWithIncome": 5,
"firstIncomeDate": "2021-11-01T00:00:00",
"lastIncomeDate": "2022-02-01T00:00:00",
"numIncomeTransactions": 2,
"averageMonthlyIncomeLast30Days": 100.1,
"averageMonthlyIncomeLast90Days": 0,
"averageMonthlyIncomeLast180Days": 0,
"averageMonthlyIncomeLast360Days": 0
},
"incomeSources": [
{
"transactionDescription": "recebimento de proventos municipio de santa ines",
"incomeStatistics": {
"daysCoveredWithIncome": 151,
"firstIncomeDate": "2021-11-30T00:00:00",
"lastIncomeDate": "2022-04-29T00:00:00",
"numIncomeTransactions": 7,
"averageMonthlyIncomeLast30Days": 821.51,
"averageMonthlyIncomeLast90Days": 821.51,
"averageMonthlyIncomeLast180Days": 1017.5467,
"averageMonthlyIncomeLast360Days": 508.77335
},
"aggregatedIncomeStatistics": {
"averageMonthlyIncome": 941.23114,
"longevity": 45,
"regularity": 69,
"consistency": 66
}
},
{
"transactionDescription": "transferencia recebida #/# # #-# pref mun santa",
"incomeStatistics": {
"daysCoveredWithIncome": 101,
"firstIncomeDate": "2021-11-23T00:00:00",
"lastIncomeDate": "2022-03-03T00:00:00",
"numIncomeTransactions": 4,
"averageMonthlyIncomeLast30Days": 0,
"averageMonthlyIncomeLast90Days": 2733.6667,
"averageMonthlyIncomeLast180Days": 2518.5,
"averageMonthlyIncomeLast360Days": 1259.25
},
"aggregatedIncomeStatistics": {
"averageMonthlyIncome": 2473.4756,
"longevity": 27,
"regularity": 47,
"consistency": 42
}
},
{
"transactionDescription": "pix - recebido #/# #:# # rocleane pe",
"incomeStatistics": {
"daysCoveredWithIncome": 134,
"firstIncomeDate": "2021-11-01T00:00:00",
"lastIncomeDate": "2022-03-14T00:00:00",
"numIncomeTransactions": 6,
"averageMonthlyIncomeLast30Days": null,
"averageMonthlyIncomeLast90Days": 83.333336,
"averageMonthlyIncomeLast180Days": 191.66666,
"averageMonthlyIncomeLast360Days": 95.83333
},
"aggregatedIncomeStatistics": {
"averageMonthlyIncome": 101.36883,
"longevity": 36,
"regularity": 25,
"consistency": 0
}
}
],
"totalAggregatedIncomeStatistics": {
"averageMonthlyIncome": 3516.0754,
"longevity": 33,
"regularity": 52,
"consistency": 47
}
},
"createdAt": "2023-02-02T19:18:26.552Z"
}
```
## Detecção de padrões recorrentes (BETA)
Também fornecemos um serviço para analisar padrões recorrentes nas transações de um Item (por exemplo, pagamento de serviços ou depósitos de salário). Aqui está um exemplo de seu uso:
1. Autentique-se na API da Pluggy para obter uma chave de API
2. Execute a seguinte solicitação
```curl
curl --location --request GET 'https://insights-api.pluggy.ai/transactions/recurrency?itemId={itemId}' \
--header 'X-API-KEY: {YOUR-API-KEY}'
```
3. Aqui está um exemplo de resposta
```json
{
"itemId": "b3b60afc-6a76-43ae-9c94-3457ce8952b2",
"recurrentTransactions": [
{
"description": "Pagamento da fatura",
"type": "DEBIT",
"averageAmount": -831.4033333333333,
"frequency": "MONTHLY"
},
{
"description": "Pb*Badoo",
"type": "DEBIT",
"averageAmount": 5.8999999999999995,
"frequency": "WEEKLY"
},
{
"description": "Pagamento efetuado - TIM",
"type": "DEBIT",
"averageAmount": -68.04785714285715,
"frequency": "MONTHLY"
}
]
}
```
## Enriquecimento de Transações
Source: https://docs.pluggy.ai/pt/docs/intelligence/transaction-enrichment.md
A API de Enriquecimento é um serviço separado que, utilizando a mesma autenticação que os principais serviços da Pluggy, permite que clientes que já coletaram dados de Open Finance ou possuem dados existentes de sua base de clientes enriqueçam os dados transacionais, fornecendo categorização e informações sobre comerciantes.
Para habilitar a API de enriquecimento, você deve solicitar isso à equipe de vendas para habilitá-la para sua equipe.
## Como usar
1. Obtenha uma chave de API do nosso endpoint [Auth](/reference/auth-create).
2. Use o fluxo de categorização descrito em [Transaction Categorization](/docs/products/transaction-categorization) com a chave de API obtida e envie as transações para categorizar:
**Exemplo de conta corrente:**
```json
{
"transactions": [
{
"id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
"amount": -100,
"date": "2024-09-06T00:00:00-03:00",
"description": "MC DONALDS"
}
],
"clientUserId": "06199323-763c-4b15-9f65-3871d8b4d430",
"accountType": "CHECKING",
"isBusiness": false
}
```
**Conta corrente com dados de pagamento:**
```json
{
"transactions": [
{
"id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
"amount": -100,
"date": "2024-09-06T00:00:00-03:00",
"description": "MC DONALDS",
"paymentData": {
"payer": {
"name": "John Doe",
"documentNumber": { "value": "123.456.789-00", "type": "CPF" }
},
"receiver": {
"name": "MC DONALDS",
"documentNumber": { "value": "42.591.651/0001-43", "type": "CNPJ" }
}
}
}
],
"clientUserId": "06199323-763c-4b15-9f65-3871d8b4d430",
"accountType": "CHECKING",
"isBusiness": false
}
```
**Exemplo de cartão de crédito:**
```json
{
"transactions": [
{
"id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
"amount": -100,
"date": "2024-09-06T00:00:00-03:00",
"description": "MC DONALDS",
"creditCardMetadata": {
"payeeMCC": 1234
}
}
],
"clientUserId": "06199323-763c-4b15-9f65-3871d8b4d430",
"accountType": "CREDIT_CARD",
"isBusiness": false
}
```
O campo `creditCardMetadata` é opcional e melhora significativamente a precisão da categorização.
Você pode enviar até 5000 transações por solicitação.
O campo `accountType` é opcional e aceita `CHECKING` ou `CREDIT_CARD`. O campo `isBusiness` também é opcional e indica se esta é uma conta PJ ou PF.
3. A resposta será algo como isto:
```json
{
"results": [
{
"id": "76a87d4d-89f2-4544-a431-b5d8a45146c7",
"amount": -100,
"date": "2024-09-06T00:00:00-03:00",
"description": "MC DONALDS",
"type": "DEBIT",
"merchant": {
"name": "mc donalds",
"businessName": "ARCOS DOURADOS COMERCIO DE ALIMENTOS LTDA",
"cnpj": "42.591.651/0001-43"
},
"category": "Comer fora"
}
]
}
```
O campo `merchant` pode ser `null` se o comerciante for desconhecido. Veja os possíveis valores de categoria na nossa página de [Transaction Categorization](/docs/transaction-categories).
## Análise de Pagamentos Recorrentes
Source: https://docs.pluggy.ai/pt/docs/intelligence/recurring-payments.md
Oferecemos uma API de Pagamentos Recorrentes que permite identificar as despesas repetidas de um usuário (como aluguel, contas de serviços) e as receitas repetidas (como salário), útil para perfilamento financeiro. Você pode analisar as transações de um item e descobrir quais delas se repetem, quão regular essa repetição é e o valor médio da transação repetida.
Para usar esta API, você precisará do recurso de Categorização habilitado para seu cliente. Ele é habilitado por padrão durante o período de teste. Depois disso, é um recurso premium opcional.
Por favor, entre em contato com nossa equipe de Vendas se você quiser habilitá-lo!
## Usando a API de Pagamentos Recorrentes
1. Obtenha uma chave de API do nosso endpoint [Auth](/reference/auth-create).
2. Use o endpoint de pagamentos recorrentes com a chave de API obtida (como o cabeçalho `X-API-Key`), e especifique um ID de Item no corpo da solicitação:
```
POST https://enrichment-api.pluggy.ai/recurring-payments
```
```json
{
"itemId": "aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}
```
3. A resposta será algo como isto:
```json
{
"recurringPayments": [
{
"description": "debito aut conta agua e esgoto sabesp",
"averageAmount": -76.78,
"occurrences": [
"77777777-8888-9999-0000-111111111111",
"88888888-9999-0000-1111-222222222222",
"99999999-0000-1111-2222-333333333333"
],
"regularityScore": 0.997773784382727
},
{
"description": "ebn spotify",
"averageAmount": -21.9,
"occurrences": [
"aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"bbbbbbb1-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"ccccccc1-cccc-cccc-cccc-cccccccccccc",
"ddddddd1-dddd-dddd-dddd-dddddddddddd",
"eeeeeee1-eeee-eeee-eeee-eeeeeeeeeeee",
"fffffff1-ffff-ffff-ffff-ffffffffffff",
"11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"22222222-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"33333333-cccc-cccc-cccc-cccccccccccc",
"44444444-dddd-dddd-dddd-dddddddddddd",
"55555555-eeee-eeee-eeee-eeeeeeeeeeee",
"66666666-ffff-ffff-ffff-ffffffffffff"
],
"regularityScore": 0.9344445222642911
},
{
"description": "mp camisetadepre",
"averageAmount": -8.57,
"occurrences": [
"99999999-cccc-cccc-cccc-cccccccccccc",
"00000000-dddd-dddd-dddd-dddddddddddd",
"aaaaaaa3-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"bbbbbbb3-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"ccccccc3-cccc-cccc-cccc-cccccccccccc",
"ddddddd3-dddd-dddd-dddd-dddddddddddd"
],
"regularityScore": 0.9199999999999999
},
{
"description": "niazi chohfi textil",
"averageAmount": -20.12,
"occurrences": [
"eeeeeee3-eeee-eeee-eeee-eeeeeeeeeeee",
"fffffff3-ffff-ffff-ffff-ffffffffffff",
"11111113-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"22222222-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
],
"regularityScore": 0.9528595479208968
}
]
}
```
`regularityScore` é um valor entre 0 e 1, indicando quão consistentes os pagamentos são em termos de tempo e valor. Um escore mais alto significa pagamentos mais regulares.
## Considerações
- **Significado do Valor:** Valores negativos representam débitos (despesas), e valores positivos representam créditos (renda). Isso se aplica a **todos os tipos de conta**: os valores são normalizados antes da análise, então uma cobrança recorrente de cartão de crédito é retornada como um `averageAmount` negativo, mesmo que o valor bruto da transação em uma conta de cartão de crédito seja positivo. Você não precisa inverter nada com base na conta de onde o pagamento veio.
- **Normalização:** As descrições das transações são normalizadas convertendo para minúsculas e removendo caracteres especiais e espaços em branco extras.
- **Ocorrências Mínimas:** Um pagamento deve ocorrer pelo menos três vezes para ser considerado recorrente.
- **Consistência de Intervalo:** Os pagamentos devem ocorrer em intervalos consistentes (aproximadamente mensalmente, dentro de uma faixa de 30 +/-5 dias).
- **Variação de Valor:** A variação nos valores das transações deve ser menor ou igual a 10% para ser considerada consistente.
Se você estiver interessado em uma análise de usuário mais personalizada, entre em contato com nossa equipe de Vendas para que possamos trabalhar nisso juntos!
## Visão Geral dos Pagamentos
Source: https://docs.pluggy.ai/pt/docs/payments/overview.md
Com o Pluggy Payments, você pode facilmente criar links de pagamento para cobrar seus clientes e rastrear automaticamente seus pagamentos, aproveitando integrações OAuth seguras com instituições usando a infraestrutura de Iniciação de Pagamentos do Open Finance.
Você também pode realizar [Pagamentos Agendados](/docs/scheduled-payments), que podem ser usados para coisas como cobrança mensal pré-acordada.
Com [PIX por biometria](/docs/payments/pix-biometric), os pagadores vinculam sua conta bancária uma vez e confirmam cada pagamento posterior com a biometria de seu dispositivo, sem serem redirecionados para o banco.
Nossa solução de Pagamentos lida com três conceitos principais:
- **Destinatário do Pagamento**: uma conta bancária que recebe pagamentos
- **Solicitação de Pagamento**: um pedido para pagar um determinado valor a um destinatário. Ela possui um link de pagamento que você pode enviar ao seu cliente para efetuar o pagamento.
- **Intenção de Pagamento**: uma tentativa de pagar uma Solicitação de Pagamento. Ela é criada quando seu cliente clica em "Pagar" em nosso site de pagamento.
Os pagamentos devem ser habilitados especificamente para o seu cliente. Se você estiver interessado em usá-lo, entre em contato com nossa equipe de Vendas!
## Fluxo de exemplo
1. Primeiro, criamos um Destinatário do Pagamento para indicar qual conta bancária receberá o pagamento (você só precisará fazer isso uma vez por conta).
```json title="POST /payments/recipients (request)"
{
"taxNumber": "11111111111", // CPF ou CNPJ
"name": "John Doe",
"paymentInstitutionId": "37f43fff-30cb-4cb5-8213-6662ac08a8c6",
"account": {
"branch": "0001",
"number": "123456",
"type": "CHECKING_ACCOUNT"
}
}
```
**Resposta**
```json title="POST /payments/recipients (response)"
{
"type": "BANK_ACCOUNT",
"id": "36fcb10f-825c-1111-b67c-93d0e47f4e77",
"name": "John Doe",
"taxNumber": "11111111111",
"isDefault": false,
"paymentInstitution": {
"id": "37f43fff-30cb-4cb5-8213-6662ac08a8c6",
"name": "SWAP MEIOS DE PAGAMENTOS INSTITUICAO DE PAGAMENTO S.A.",
"tradeName": "SWAP MP IP SA",
"ispb": "31680151",
"compe": null,
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "*******",
"number": "****56",
"branch": "0001"
},
"pixKey": null,
"createdAt": "2025-06-25T14:09:44.717Z",
"updatedAt": "2025-06-25T14:09:44.717Z"
}
```
Nota: você pode obter os IDs das instituições [neste endpoint](/reference/payment-recipient/payment-recipients-institution-list).
2. Crie uma Solicitação de Pagamento com o valor que deseja cobrar de seu cliente, juntamente com o ID do destinatário da etapa anterior.
```json title="POST /payments/requests (request)"
{
"amount": 0.01,
"description": "Meu pedido de pagamento",
"recipientId": "ab276a3d-17ba-47eb-97bf-688475037ffe"
}
```
**Resposta**
```json title="POST /payments/requests (response)"
{
"id": "bb236f8d-caa5-47eb-97bf-688475037f3e",
"amount": 0.01,
"description": "Meu pedido de pagamento",
"status": "CREATED",
"createdAt": "2023-11-14T16:57:17.511Z",
"updatedAt": "2023-11-14T16:57:17.511Z",
"callbackUrls": null,
"paymentUrl": "https://pay.pluggy.ai/bb236f8d-caa5-47eb-97bf-688475037f3e"
}
```
3. Envie o `paymentUrl` da resposta para seu cliente.
4. O cliente visitará nosso site Pluggy Pagamentos.
O `paymentUrl` abre a página de pagamento do Pluggy. Ele não tem uma expiração fixa de cinco minutos; se pode ser usado depende do status e configuração da Solicitação de Pagamento. Após o cliente escolher uma instituição e clicar em **Pagar**, o Pluggy cria uma Intenção de Pagamento e retorna uma `consentUrl`. A `consentUrl` é a URL de autorização do banco e expira após cinco minutos. Essas são URLs diferentes com ciclos de vida diferentes.
## Reagindo a um pagamento
Você pode indicar para onde redirecionar o usuário após completar um pagamento usando o campo `callbackUrls`:
```json title="POST /payments/requests"
{
"amount": 0.01,
"description": "Transferência",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com",
"pending": "https://my-pending-url.com"
}
}
```
Também é possível reagir a um pagamento concluído para criar automações úteis, usando [webhooks](/docs/webhooks).
## Pré-preenchendo o CPF/CNPJ
O CPF/CNPJ do pagador é exigido pelo Open Finance para iniciar um pagamento. Para PF, é necessário CPF, e para PJ, são ambos CPF e CNPJ. Para melhorar a experiência de pagamento e reduzir erros do usuário, você pode pré-preencher criando um Cliente de Pagamento:
**Solicitação — PF**
```json title="POST /payments/customers (PF)"
{
"type": "INDIVIDUAL",
"cpf": "123.456.789-12"
}
```
**Solicitação — PJ**
```json title="POST /payments/customers (PJ)"
{
"type": "BUSINESS",
"cpf": "123.456.789-12",
"cnpj": "12.345.678/9012-34"
}
```
Agora, ao criar a Solicitação de Pagamento, inclua o campo `customerId` apontando para o Cliente de Pagamento criado anteriormente.
## Pré-selecionando a instituição do pagador
Você pode definir uma instituição pré-selecionada para o pagador ao iniciar o fluxo de iniciação de pagamento. Isso pode ser útil se você quiser guiar o usuário a usar uma instituição específica para efetuar o pagamento. Para fazer isso, você pode criar o cliente de pagamento fornecendo um `connectorId`:
```json title="POST /payments/customers"
{
"type": "INDIVIDUAL",
"cpf": "123.456.789-12",
"connectorId": 612
}
```
## Envolvendo um QR PIX existente
Se você quiser usar o Pluggy para pagar um QR PIX para permitir o rastreamento de seu pagamento, pode criar um Destinatário a partir do QR PIX:
```json title="POST /payments/recipients/pix-qr"
{
"pixQrCode": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20"
}
```
## Criando uma experiência de pagamento personalizada
Se você não quiser usar nosso fluxo `pay.pluggy.ai`, pode implementar sua experiência de pagamento personalizada usando nossa API.
Primeiramente, você precisa criar uma **Solicitação de Pagamento**. Lá, você especificará quanto dinheiro deseja receber. Além disso, você pode configurar uma descrição (a ser exibida ao usuário final no momento em que ele autoriza o pagamento) e um conjunto de URLs de callback para onde o usuário será redirecionado após a autorização do pagamento ser concluída. Os campos `description`, `callbackUrl` e `isSandbox` são opcionais.
```json title="Solicitação"
{
"amount": 100.50,
"description": "Transferência",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com",
"pending": "https://my-pending-url.com"
},
"isSandbox": true
}
```
**Resposta**
```json title="Resposta"
{
"id": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
"amount": 100.50,
"description": "Transferência",
"status": "CREATED",
"createdAt": "2023-11-06T13:03:45.689Z",
"updatedAt": "2023-11-06T13:03:45.689Z",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com"
},
"isSandbox": true
}
```
Você pode encontrar os detalhes do endpoint [aqui](/reference/payment-request-create).
### Criando uma Intenção de Pagamento
Após criar uma solicitação de pagamento, você precisa criar uma **Intenção de Pagamento**. Isso representa a intenção de uma pessoa de fazer aquele pagamento. Por exemplo, se você quiser cobrar um cliente R$10, primeiro precisa criar uma **Solicitação de Pagamento** para esse valor e, em seguida, uma **Intenção de Pagamento** quando o usuário quiser pagar.
Para criar uma **Intenção de Pagamento**, você precisa enviar o ID da instituição (`connectorId`) que o usuário usará para efetuar o pagamento. Você pode encontrar a lista de conectores usando nosso [endpoint de conectores](/reference/connectors-list) e filtrar aqueles com a propriedade `supportsPaymentInitiation` com valor `true`. Além disso, você precisa enviar as credenciais exigidas da instituição no campo `parameters`. Essas credenciais também podem ser encontradas no [endpoint de conectores](/reference/connectors-list).
Esta é a solicitação para criar uma **Intenção de Pagamento**.
**Solicitação — Conector Pessoal**
```json title="Solicitação Conector Pessoal"
{
"paymentRequestId": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
"connectorId": 601,
"parameters": {
"cpf": "76109277673"
}
}
```
**Solicitação — Conector Empresarial**
```json title="Solicitação Conector Empresarial"
{
"paymentRequestId": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
"connectorId": 618,
"parameters": {
"cpf": "76109277673",
"cnpj": "11111111111111"
}
}
```
**Resposta**
```json title="Resposta"
{
"id": "4316602b-8fb5-4bfd-92dc-32921b7414f1",
"status": "CONSENT_AWAITING_AUTHORIZATION",
"createdAt": "2023-11-09T20:10:42.706Z",
"updatedAt": "2023-11-09T20:10:42.706Z",
"paymentRequest": {
"id": "f6696d02-3583-47ae-b195-148d71b8ae9b",
"amount": 100.50,
"description": null,
"status": "IN_PROGRESS",
"createdAt": "2023-11-09T20:10:25.084Z",
"updatedAt": "2023-11-09T20:10:42.706Z",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com"
}
},
"connector": {
"id": 601,
"name": "Itaú",
"primaryColor": "48be9d",
"institutionUrl": "https://cdn.raidiam.io/directory-ui/brand/obbrazil/0.2.0.112/favicon.svg",
"country": "BR",
"type": "PERSONAL_BANK",
"credentials": [
{
"validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
"validationMessage": "CPF deve ter 11 números.",
"label": "CPF",
"name": "cpf",
"type": "number",
"placeholder": "",
"optional": false
}
],
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/itau.svg",
"hasMFA": false,
"oauth": true,
"health": {
"status": "ONLINE",
"stage": null
},
"products": [
"ACCOUNTS",
"TRANSACTIONS",
"IDENTITY",
"CREDIT_CARDS",
"PAYMENT_DATA",
"LOANS",
"INVESTMENTS"
],
"createdAt": "2023-07-24T14:29:32.140Z",
"isSandbox": true,
"isOpenFinance": true,
"updatedAt": "2023-11-09T19:17:08.495Z",
"supportsPaymentInitiation": true
},
"consentUrl": "https://consent-url.com"
}
```
Existem propriedades importantes no objeto de resposta:
- **status**: Neste ponto, terá o valor `CONSENT_AWAITING_AUTHORIZATION`. Isso significa que o usuário precisa autorizá-lo na instituição. Você pode verificar os outros valores possíveis [aqui](/docs/payment-intent-statuses).
- **consentUrl**: É a URL para onde você precisa redirecionar o usuário para autorizar o pagamento. Esta URL de autorização do banco expira após 5 minutos. Esta expiração se aplica apenas à `consentUrl`; não significa que o `paymentUrl` tenha uma expiração de cinco minutos. Após a conclusão do pagamento, o usuário será redirecionado para as URLs especificadas nos `callbackUrls` definidos anteriormente, ou para uma URL padrão fornecida pelo Pluggy se não tiver sido especificada.
Você pode encontrar os detalhes do endpoint [aqui](/reference/payment-intent-create).
## Testando pagamentos com o banco Sandbox
Você pode usar nosso aplicativo de testes [playground](https://playground.pluggy.ai) para testar o fluxo sem nenhuma configuração!
Para testar pagamentos Sandbox em nosso App, basta criar sua **Solicitação de Pagamento** com `isSandbox: true`. Em seguida, acesse:
`https://pay.pluggy.ai/`
A página detectará automaticamente o ambiente sandbox e listará apenas conectores sandbox para você completar o fluxo. Use o conector Sandbox com as seguintes credenciais:
```json
{
"cpf": "76109277673",
"user": "user-ok",
"password": "password-ok"
}
```
Use a credencial CPF na primeira entrada. Use **user** e **password** para fazer login no Mock Bank, e ele será redirecionado para a Página de Sucesso ou de Erro, dependendo do resultado do Pagamento.
### Testando através da API
Para executar o mesmo fluxo a partir do seu próprio código, sem o App de Pagamentos:
1. Crie um [Destinatário de Pagamento](/reference/payment-recipient/payment-recipient-create) e uma [Solicitação de Pagamento](/reference/payment-request-create) com `isSandbox: true`.
2. Crie uma [Intenção de Pagamento](/reference/payment-intent-create) com o conector sandbox **`600`** (Pluggy Bank) e o CPF sandbox:
```json title="POST /payments/intents"
{
"paymentRequestId": "{YOUR-SANDBOX-PAYMENT-REQUEST-ID}",
"connectorId": 600,
"parameters": {
"cpf": "76109277673"
}
}
```
3. Redirecione o usuário (ou você mesmo) para a `consentUrl` na resposta. Ela mostra o login do banco sandbox — `user-ok` / `password-ok` — e, em seguida, a tela de autorização. Aprove o pagamento.
4. O pagamento é concluído em segundos após a aprovação: a Intenção de Pagamento muda para `PAYMENT_COMPLETED`, a Solicitação de Pagamento para `COMPLETED`, e o navegador é redirecionado para seu `callbackUrl` de sucesso.
Crie a Solicitação de Pagamento com um `amount` de **`404.04`** para simular uma falha da instituição. O sandbox rejeita o pagamento assim que você cria a Intenção de Pagamento: `POST /payments/intents` retorna um erro e nenhuma `consentUrl` é emitida, para que você possa exercitar seu tratamento de erros sem esperar por uma interrupção real.
Uma solicitação de pagamento sandbox dispara webhooks exatamente como uma real — `payment_intent/created`, `payment_intent/completed`, `payment_intent/error`, `payment_request/updated` e os outros eventos de pagamento em [webhooks](/docs/webhooks) — para que você possa testar seu tratamento de webhook de ponta a ponta.
Para pagamentos agendados, Pix Automático e boletos no sandbox, veja [Testando pagamentos e boletos](/docs/guides/sandbox#testing-payments-and-boletos).
## Ciclo de Vida e Erros da Intenção de Pagamento
Source: https://docs.pluggy.ai/pt/docs/payments/intent-lifecycle.md
Aqui você pode encontrar os possíveis status de um **Payment Intent**.
Os possíveis status finais são:
- **PAYMENT_COMPLETED**: Crédito realizado na conta de destino.
- **CONSENT_REJECTED**: Pagamento rejeitado pelo usuário ou instituição.
- **PAYMENT_REJECTED**: Instrução de pagamento rejeitada.
- **ERROR**: Falha de validação ou erro de processo.
- **CANCELED**: Cancelado por qualquer outro meio.
- **EXPIRED**: O consentimento atingiu sua data de expiração.
- **PAYMENT_TIMEOUT**: A tentativa de autorização excedeu seu tempo limite. Tentativas de pagamento regulares expiram após 30 minutos; tentativas automáticas de PIX expiram após 60 minutos. A Solicitação de Pagamento retorna para `CREATED` e a Pluggy envia um webhook `payment_intent/error`.
Se o status for **PAYMENT_PARTIALLY_ACCEPTED**, isso significa que o pagamento requer uma autorização adicional (por exemplo, se você fizer o pagamento usando uma conta de operador, pode exigir a autorização de um usuário master).
## Possíveis Erros ao Criar um Payment Intent
Um resumo dos códigos de erro e suas descrições que podem ocorrer ao tentar processar um payment intent através da nossa API.
| Código | Código do Provedor | Detalhes do Provedor |
|--------|-------------------|---------------------|
| VALUE_ABOVE_LIMIT | VALOR_ACIMA_LIMITE | O valor (ou quantidade de transações) ultrapassa a faixa de limite parametrizada na detentora para permitir a realização de transações pelo cliente. |
| INVALID_VALUE | VALOR_INVALIDO | O valor enviado não é válido para o QR Code informado. |
| INVALID_CHARGE | COBRANCA_INVALIDA | Validação de expiração, validação de vencimento, Status Válido. |
| INVALID_CONSENT | CONSENTIMENTO_INVALIDO | Consentimento inválido (status não é "authorised" ou está expirado). |
| PARAMETER_NOT_INFORMED | PARAMETRO_NAO_INFORMADO | Parâmetro não informado. |
| INVALID_PARAMETER | PARAMETRO_INVALIDO | Parâmetro inválido. |
| NOT_INFORMED | NAO_INFORMADO | Não informada pela detentora de conta. (possivelmente foi barrado pelo anti-fraude da instituição) |
| PAYMENT_DIVERGENT_FROM_CONSENT | PAGAMENTO_DIVERGENTE_DO_CONSENTIMENTO | Dados do pagamento divergentes dos dados do consentimento. |
| INVALID_PAYMENT_DETAIL | DETALHE_PAGAMENTO_INVALIDO | Detalhe do pagamento inválido. |
| PAYMENT_REFUSED_BY_HOLDER | PAGAMENTO_RECUSADO_DETENTORA | Pagamento recusado pela detentora de conta. |
| PAYMENT_REFUSED_BY_SPI | PAGAMENTO_RECUSADO_SPI | Pagamento recusado no Sistema de Pagamentos Instantâneos (SPI). |
| IDEMPOTENCY_ERROR | ERRO_IDEMPOTENCIA | Erro idempotência. |
| CONSENT_PENDING_AUTHORIZATION | CONSENTIMENTO_PENDENTE_AUTORIZACAO | Consentimento pendente autorização de múltiplas alçadas (status "PARTIALLY_ACCEPTED") |
| INFRASTRUCTURE_FAILURE | FALHA_INFRAESTRUTURA | Descrição de qual falha na infraestrutura inviabilizou o processamento. |
| SPI_INFRASTRUCTURE_FAILURE | FALHA_INFRAESTRUTURA_SPI | Indica uma falha no Sistema de Pagamentos Instantâneos (SPI). |
| DICT_INFRASTRUCTURE_FAILURE | FALHA_INFRAESTRUTURA_DICT | Indica uma falha no Diretório de Identificadores de Contas Transacionais (DICT). |
| ICP_INFRASTRUCTURE_FAILURE | FALHA_INFRAESTRUTURA_ICP | Indica uma falha na Infraestrutura de Chaves Públicas (ICP). |
| RECEIVER_PSP_INFRASTRUCTURE_FAILURE | FALHA_INFRAESTRUTURA_PSP_RECEBEDOR | Indica uma falha na infraestrutura do Prestador de Serviço de Pagamento (PSP) que recebe o pagamento. |
| HOLDER_INFRASTRUCTURE_FAILURE | FALHA_INFRAESTRUTURA_DETENTORA | Indica uma falha na infraestrutura da instituição detentora das informações ou recursos. |
| SAME_ORIGIN_DESTINATION_ACCOUNTS | CONTAS_ORIGEM_DESTINO_IGUAIS | Indica uma tentativa de pagamento onde a conta origem e a conta de destino são iguais. |
| PAYMENT_SCHEDULING_FAILURE | FALHA_AGENDAMENTO_PAGAMENTOS | Falha ao agendar pagamentos. |
| UNKNOWN_ERROR | ERRO_DESCONHECIDO | Ocorreu um erro não identificado na instituição financeira ou detentora de conta. |
| PAYMENT_REQUEST_SANDBOX_CONNECTOR_ERROR | CONECTOR_INVALIDO_PARA_PAGAMENTO_SANDBOX | O pagamento está em sandbox, mas o conector não suporta sandbox, ou há incompatibilidade de ambientes. |
| PAYMENT_REQUEST_PRODUCTION_CONNECTOR_ERROR | CONECTOR_INVALIDO_PARA_PAGAMENTO_EM_PRODUCAO | O pagamento está em produção, mas o conector é sandbox, ou há incompatibilidade de ambientes. |
## Pagamentos Agendados (Pix Agendado)
Source: https://docs.pluggy.ai/pt/docs/payments/scheduled-payments.md
Com nossa funcionalidade de iniciação de pagamentos, você pode agendar pagamentos para ocorrer no futuro (também chamado de PIX RECORRENTE) usando qualquer um dos seguintes modos:
- **ÚNICO**: Agendar um pagamento para ocorrer em um momento específico no futuro.
- **DIÁRIO**: Agendar vários pagamentos para ocorrer todos os dias, a partir de uma data específica.
- **SEMANAL**: Agendar vários pagamentos para ocorrer todas as semanas, a partir de uma data específica.
- **MENSAL**: Agendar vários pagamentos para ocorrer todos os meses, a partir de uma data específica.
- **PERSONALIZADO**: Agendar vários pagamentos para ocorrer em datas específicas no futuro.
## Agendando um pagamento
1. Crie uma [Solicitação de Pagamento](/reference/payment-request-create) incluindo um objeto `schedule`:
```json title="POST /payments/requests"
{
"amount": 1333.33, // O valor a ser pago todos os dias/semanais/mensais/personalizados
"description": "Minha solicitação de pagamento 2",
"schedule": {
"type": "DIÁRIO",
"startDate": "2024-06-26", // Data do primeiro pagamento
"occurrences": 2 // Quantas vezes repetir
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
```
2. Autorize a Solicitação de Pagamento com nosso App de Pagamentos (visitando o `paymentUrl` na resposta).
3. Após o usuário escolher a instituição para pagar, inserir seu CPF/CNPJ e clicar em Pagar, um Intent de Pagamento com status CONSENT_AWAITING_AUTHORIZATION é criado. Isso aciona o webhook `payment_intent/created`. O usuário agora é redirecionado para sua instituição para autorizar o pagamento agendado.
4. Uma vez autorizado, o Intent de Pagamento mudará o status para `PAYMENT_COMPLETED`. Isso aciona o webhook `payment_intent/completed`. Agora, um ou mais Pagamentos Agendados (pagamentos a ocorrer no futuro) serão criados. Cada criação acionará o webhook `scheduled_payment/created`.
5. Você pode agora obter a lista de [Pagamentos Agendados](/reference/payment-schedules-list):
```json title="GET /payment-requests/{id}/schedules"
{
"total": 2,
"totalPages": 1,
"page": 1,
"results": [
{
"id": "9f12b911-a064-4310-89f2-8d411e10b160",
"status": "AGENDADO",
"scheduledDate": "2024-06-26",
"description": "Minha solicitação de pagamento 1/2"
},
{
"id": "1f1f04e8-0bcf-4baf-bbbd-8bedf8478503",
"status": "AGENDADO",
"scheduledDate": "2024-06-27",
"description": "Minha solicitação de pagamento 2/2"
}
]
}
```
6. Em cada uma das datas agendadas, um pagamento será acionado na instituição. Isso resultará na mudança de status do Pagamento Agendado para COMPLETO ou ERRO em caso de falha. Isso aciona o webhook `scheduled_payment/completed` ou `scheduled_payment/error`.
7. Se o usuário cancelar um Pagamento Agendado da instituição, ele mudará o status para CANCELADO e acionará o webhook `scheduled_payment/canceled`.
8. Após todos os Pagamentos Agendados serem COMPLETOS, a Solicitação de Pagamento mudará o status para COMPLETO.
## Modificando ou cancelando pagamentos agendados
Se o usuário ainda não autorizou um pagamento agendado, você pode modificá-lo usando o endpoint `PATCH /payment-requests/{id}`, ou excluí-lo usando o endpoint `DELETE /payment-requests/{id}`.
Após o usuário ter autorizado um Pagamento Agendado, você não pode adicionar ou editar os Schedules resultantes. No entanto, você pode excluir um schedule específico ou cancelar o pagamento inteiro.
O usuário autorizador também pode cancelar todos os schedules diretamente de seu banco. Você pode reagir a essa mudança com um webhook.
## Modos de Agendamento
Aqui estão exemplos de como configurar todos os diferentes modos de agendamento:
```json title="ÚNICO"
{
"amount": 1333.33,
"description": "Teste",
"schedule": {
"type": "ÚNICO",
"date": "2024-06-26"
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
```
```json title="DIÁRIO"
{
"amount": 1333.33,
"description": "Teste",
"schedule": {
"type": "DIÁRIO",
"startDate": "2024-06-26",
"occurrences": 2
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
```
```json title="SEMANAL"
{
"amount": 1333.33,
"description": "Teste",
"schedule": {
"type": "SEMANAL",
"startDate": "2024-06-26",
"dayOfWeek": "SEGUNDA",
"occurrences": 2
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
```
```json title="MENSAL"
{
"amount": 1333.33,
"description": "Teste",
"schedule": {
"type": "MENSAL",
"startDate": "2024-06-26",
"dayOfMonth": 1,
"occurrences": 2
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
```
```json title="PERSONALIZADO"
{
"amount": 1333.33,
"description": "Teste",
"schedule": {
"type": "PERSONALIZADO",
"dates": ["2024-06-26", "2024-06-28"]
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
```
## Usando uma UI personalizada
Se você quiser usar sua própria UI para implementar o fluxo de Pagamento Agendado em vez de nosso App de Pagamentos:
1. Crie a solicitação de pagamento, incluindo um `callbackUrl` para seu site:
```json title="POST /payments/requests"
{
"amount": 1333.33,
"description": "Minha solicitação de pagamento 2",
"schedule": {
"type": "DIÁRIO",
"startDate": "2024-06-26", // Data do primeiro pagamento
"occurrences": 2 // Quantas vezes repetir
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940",
"callbackUrls": {
"success": "/success",
"error": "/error"
}
}
```
2. Crie um [Intent de Pagamento](/reference/payment-intent-create) para essa Solicitação de Pagamento:
```json title="POST /payments/intents"
{
"paymentRequestId": "4f05247c-d9ee-4d5b-a0ea-c1c52cc30f69",
"connectorId": 600, // este é sandbox
"parameters": {
"cpf": "76109277673"
}
}
```
3. Redirecione o usuário para o `consentUrl` na resposta, que o levará à tela de Iniciação de Pagamento Open Finance da instituição para autorizar o pagamento.
4. Você será redirecionado de volta para o `callbackUrl` correspondente (sucesso ou erro).
## Testando no sandbox
Você pode executar o fluxo de UI personalizada acima de ponta a ponta contra o banco sandbox.
O PIX agendado usa seu próprio contrato de iniciação de pagamento, portanto, a iniciação de pagamento para pagamentos agendados deve estar habilitada em sua conta — no sandbox também. Sem isso, criar o Intent de Pagamento (`POST /payments/intents`) para uma Solicitação de Pagamento com um `schedule` retorna `403` com o código `PAYMENT_INITIATION_NOT_ALLOWED`, mesmo quando a solicitação tem `isSandbox: true`. Entre em contato com o suporte da Pluggy para habilitá-lo.
1. Crie a Solicitação de Pagamento com `isSandbox: true` e um `schedule` — por exemplo `ÚNICO` com uma `date` futura.
2. Crie o Intent de Pagamento com o conector **`600`** e o CPF sandbox `76109277673`, como no exemplo acima.
3. Abra o `consentUrl`, faça login com `user-ok` / `password-ok` e aprove.
O sandbox liquida uma solicitação de pagamento agendado **no momento do consentimento**, como um pagamento único datado de hoje, em vez de criar um pagamento por ocorrência e executar cada um em sua data. Use-o para verificar se sua integração cria a solicitação, envia o usuário pelo consentimento e lida com o webhook `scheduled_payment/completed`. Como as ocorrências individuais nunca são agendadas, o sandbox não envia `payment_intent/completed`, `scheduled_payment/created` ou `scheduled_payment/all_created`, e a Solicitação de Pagamento permanece em `AGENDADO` em vez de ser movida para `COMPLETO`. Valide essas etapas contra uma instituição real.
Um `amount` de **`404.04`** faz com que o sandbox rejeite o pagamento quando você cria o Intent de Pagamento, então você pode testar esse caminho de erro também. Veja [Testando pagamentos e boletos](/docs/guides/sandbox#testing-payments-and-boletos) para os outros tipos de pagamento.
## Webhooks de Pagamento Agendado
Source: https://docs.pluggy.ai/pt/docs/payments/scheduled-webhooks.md
Esta seção discutirá como cada webhook é acionado após a conclusão de cada etapa, afetando as entidades `PaymentRequest`, `PaymentIntent` e `SchedulePayment`.
## Fluxo de Webhooks de Agendamento
O fluxo geral funciona da seguinte forma: quando o pagador autoriza o consentimento, um webhook `payment_intent/created` é acionado, seguido por `payment_intent/completed` uma vez que a intenção é confirmada. Em seguida, um webhook `scheduled_payment/created` é acionado para cada pagamento agendado, e um webhook `scheduled_payment/all_created` uma vez que todos os agendamentos tenham sido registrados. À medida que cada pagamento agendado é executado na sua data, um webhook `scheduled_payment/completed` é acionado (ou `scheduled_payment/error` se falhar), e finalmente `scheduled_payment/all_completed` quando todos os agendamentos tiverem terminado.
## Exemplos de payloads de webhook
Aqui estão exemplos de payloads de webhook em um caso com dois pagamentos agendados, e ambos se tornando COMPLETOS:
**payment_intent/created**
```json title="payment_intent/created"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"paymentIntentId": "056b8046-2f7c-4d97-b5d5-f5f54005db51",
"event": "payment_intent/created",
"eventId": "aa8f7239-101c-4553-afdd-9689a4ac46cd"
}
```
**payment_intent/completed**
```json title="payment_intent/completed"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"paymentIntentId": "056b8046-2f7c-4d97-b5d5-f5f54005db51",
"event": "payment_intent/completed",
"eventId": "1ecfb159-e506-48a3-895e-aed5241db4d9"
}
```
**scheduled_payment/created (1)**
```json title="scheduled_payment/created (1)"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"event": "scheduled_payment/created",
"eventId": "5f519a62-87e1-45ce-be36-d2b185994c21",
"scheduledPaymentId": "65c6f9cd-e69f-46cd-8103-80b42dd61bfd"
}
```
**scheduled_payment/created (2)**
```json title="scheduled_payment/created (2)"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"event": "scheduled_payment/created",
"eventId": "c8e0dd66-5939-425d-bfd2-900ffa6921ae",
"scheduledPaymentId": "502b68b5-f82a-4d1c-bcb3-e1e61fadc48a"
}
```
**scheduled_payment/all_created**
```json title="scheduled_payment/all_created"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"event": "scheduled_payment/all_created",
"eventId": "4f45ca0a-3286-47b4-b8b3-195cd35cac01"
}
```
**scheduled_payment/completed (1)**
```json title="scheduled_payment/completed (1)"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"event": "scheduled_payment/completed",
"eventId": "1d5d1aab-fc1a-40d4-aeae-15e7b9c11a10",
"endToEndId": "E44471172202505211500U0d9ffa12345",
"scheduledPaymentId": "65c6f9cd-e69f-46cd-8103-80b42dd61bfd"
}
```
**scheduled_payment/completed (2)**
```json title="scheduled_payment/completed (2)"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"event": "scheduled_payment/completed",
"eventId": "9ebc222b-a94d-41e1-ad52-c0cf26f0357e",
"endToEndId": "E44471172202505211500U0d9ffa12345",
"scheduledPaymentId": "502b68b5-f82a-4d1c-bcb3-e1e61fadc48a"
}
```
**scheduled_payment/all_completed**
```json title="scheduled_payment/all_completed"
{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"event": "scheduled_payment/all_completed",
"eventId": "7a9426aa-2ac3-4d8e-a5a4-fe780f116c6b"
}
```
Se você configurou todos os webhooks, seguindo o exemplo acima de fluxo, isso acionará todos esses webhooks nessa ordem.
Você receberá:
- Dois webhooks `payment_intent` (criado e concluído).
- Cinco webhooks `scheduled_payment`.
- Como neste exemplo agendamos **dois pagamentos**, receberemos **dois para cada pagamento** que foi agendado (criado e concluído).
- Um webhook quando **todos os agendamentos** tiverem terminado.
### Erros de Webhook
Quando você receber um webhook `scheduled_payment/error`, pode ter um dos seguintes códigos de erro.
| Código de Erro | Significado | Descrição |
|----------------|-------------|-----------|
| `INSUFFICIENT_BALANCE` | Saldo Insuficiente | A conta não tem saldo suficiente para realizar o pagamento. |
| `EXCEEDED_LIMIT` | Limite Excedido | O valor do pagamento excede o limite permitido. |
| `INVALID_AMOUNT` | Valor Inválido | O valor do pagamento fornecido é inválido. |
| `INVALID_INVOICE` | Fatura Inválida | A fatura fornecida é inválida. |
| `INVALID_CONSENT` | Consentimento Inválido | O consentimento fornecido é inválido. |
| `PARAMETER_NOT_PROVIDED` | Parâmetro Não Fornecido | Um parâmetro obrigatório não foi fornecido. |
| `INVALID_PARAMETER` | Parâmetro Inválido | Um parâmetro fornecido é inválido. |
| `NOT_PROVIDED` | Parâmetro Não Fornecido | Um parâmetro obrigatório não foi fornecido. |
| `PAYMENT_DIFFERENT_FROM_CONSENT` | Pagamento Diferente do Consentimento | O pagamento difere do consentimento autorizado. |
| `INVALID_PAYMENT_DETAIL` | Detalhe de Pagamento Inválido | Os detalhes do pagamento fornecidos são inválidos. |
| `PAYMENT_REJECTED_BY_HOLDER` | Pagamento Rejeitado pelo Titular | O titular da conta rejeitou o pagamento. |
| `IDEMPOTENCY_ERROR` | Erro de Idempotência | Ocorreu um erro de idempotência, possivelmente devido a solicitações duplicadas. |
| `CONSENT_PENDING_AUTHORIZATION` | Consentimento Pendente de Autorização | O consentimento está pendente de autorização. |
| `INFRASTRUCTURE_FAILURE` | Falha na Infraestrutura | Ocorreu uma falha na infraestrutura. |
| `SAME_ACCOUNT_ORIGIN_DESTINATION` | Mesma Conta de Origem e Destino | As contas de origem e destino são as mesmas, o que não é permitido. |
| `PAYMENT_SCHEDULING_FAILURE` | Falha no Agendamento do Pagamento | Ocorreu uma falha ao agendar o pagamento. |
| `UNKNOWN_ERROR` | Erro Desconhecido | Ocorreu um erro desconhecido, seja na instituição de Open Finance ou no lado do titular da conta. |
## FAQ
Source: https://docs.pluggy.ai/pt/docs/payments/scheduled-faq.md
O objetivo desta página é responder a perguntas comuns sobre Pagamentos Agendados.
### 1. O que acontece se um dos pagamentos falhar devido a fundos insuficientes na conta do usuário?
- Você receberá o erro via **webhook** com o motivo (evento: `scheduled_payment/error`). O status do pagamento mudará para **ERROR**, e os pagamentos subsequentes **continuarão normalmente**. Pagamentos falhados não podem ser reprocessados devido a **Regulamentações do Banco Central**.
## PIX Automático
Source: https://docs.pluggy.ai/pt/docs/payments/pix-automatico.md
Bem-vindo à API Pix Automático da Pluggy—sua porta de entrada para pagamentos recorrentes automáticos e sem complicações no Brasil.
Pix Automático, lançado pelo Banco Central do Brasil, traz o poder da automação para o sistema de pagamento instantâneo Pix. Com a Pluggy, você pode integrar o Pix Automático ao seu produto em minutos, permitindo que seus usuários agendem, autorizem e gerenciem pagamentos recorrentes com a mesma velocidade, confiabilidade e experiência de desenvolvedor que você espera de APIs modernas.
---
## O que é Pix Automático?
Pix Automático é a camada de pagamentos recorrentes do Pix. Ele permite que você crie mandatos programaticamente para que seus usuários possam autorizar pagamentos automáticos e agendados—perfeito para assinaturas, contas de serviços públicos, pagamentos de empréstimos e muito mais.
**Principais características:**
- **Recorrência Automatizada:** Configure cronogramas de pagamento e deixe a Pluggy cuidar do resto—sem intervenção manual necessária.
- **Autorização do Usuário:** Cada pagamento recorrente é autorizado pelo pagador, garantindo confiança e transparência.
- **Liquidação Instantânea:** Os fundos se movem instantaneamente, 24/7, assim como qualquer transação Pix.
- **Alcance Universal:** Funciona em todas as instituições financeiras habilitadas para Pix.
---
## Por que construir com Pix Automático?
Pix Automático desbloqueia novas possibilidades para o seu produto:
- **Automatize Tudo:** Elimine a cobrança e a faturamento manuais com algumas linhas de código.
- **Aumente a Confiabilidade:** Garanta pagamentos pontuais e cronogramas reprogramáveis.
- **Encante os Usuários:** Ofereça aos seus clientes uma maneira sem atritos e segura de gerenciar pagamentos recorrentes.
- **Economize em Custos:** Aproveite as baixas taxas do Pix e a infraestrutura em tempo real.
---
## Opções de Integração
A Pluggy oferece duas maneiras flexíveis de integrar o Pix Automático ao seu aplicativo:
- **Gateway de Pagamento Pluggy:** A maneira mais rápida de começar. Use a interface de pagamento hospedada da Pluggy, que funciona perfeitamente, assim como PIS ou PIS Agendado. Esta opção permite que você ofereça o Pix Automático com um esforço de desenvolvimento mínimo e uma ótima experiência do usuário desde o início.
- **APIs Diretas:** Para clientes que desejam controle total sobre a experiência do usuário, a Pluggy fornece endpoints de API diretos. Construa sua interface e gerencie todo o fluxo do Pix Automático programaticamente.
Selecione o caminho de integração que melhor se adapta ao seu produto e requisitos de desenvolvimento.
## Começando
Source: https://docs.pluggy.ai/pt/docs/payments/pix-getting-started.md
Este guia irá orientá-lo pelos fundamentos da criação do seu primeiro pedido de pagamento Pix Automático usando o Gateway de Pagamento da Pluggy. Você aprenderá como configurar pedidos de valores fixos e variáveis, entender os métodos disponíveis e usar a URL de pagamento para proporcionar uma experiência perfeita aos seus usuários.
- **Crie** um `PaymentRecipient` — assim como outros métodos de pagamento, a conta destinatária é configurada como um PaymentRecipient.
- Prepare um callbackUrl para retornar ao seu aplicativo após o pagamento ter sido bem-sucedido / com erro.
- Configure **webhooks** para receber notificações de PaymentRequests, PaymentIntents ou PixAutomaticPayments.
- **Entenda** como a Pluggy gerencia **pedidos de pagamento**, para compartilhar com os usuários finais *Links de Autorização de Pagamento*.
## 1. Criando um Pedido de Pagamento
Para iniciar um pagamento Pix Automático, você precisará criar um pedido de pagamento (mandato) através da API da Pluggy. Este pedido define o pagador, a recorrência e os detalhes do pagamento.
### Exemplo: Criando um Pedido de Pagamento
```http title="HTTP"
POST /payments/requests/automatic-pix
Content-Type: application/json
{
"description": "Pix Automatico",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "WEEKLY",
"startDate": "2025-06-10",
"minimumVariableAmount": 0.01,
"maximumVariableAmount": 0.02,
"firstPayment": {
"date": "2025-06-08",
"amount": 0.03,
"description": "Primeiro mês"
}
}
```
O primeiro pagamento deve ser liquidado em um dia diferente de `startDate`. Quando `firstPayment.date` é omitido, o primeiro pagamento é liquidado no dia em que o usuário autoriza, então não defina `startDate` para esse dia. Por exemplo, para cobrar a inscrição hoje e iniciar uma recorrência mensal, envie `startDate` um mês à frente, ou qualquer data após hoje. Pedidos que quebram essa regra falham com `400` e `AUTOMATIC_PIX_INVALID_FIRST_PAYMENT_DATE`, tanto quando o pedido de pagamento é criado quanto quando uma intenção de pagamento é criada para ele.
---
## 2. Valores Fixos e Variáveis
A Pluggy suporta pedidos de pagamento tanto de **valor fixo** quanto de **valor variável**:
- **Valor Fixo:** O mesmo valor é cobrado em cada recorrência (por exemplo, uma assinatura).
- **Valor Variável:** O valor pode mudar para cada pagamento (por exemplo, contas de serviços públicos).
**Carga Útil de Valor Fixo**
```json title="Carga Útil de Valor Fixo"
{
"description": "Seu aluguel",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "MONTHLY",
"startDate": "2025-06-10",
"fixedAmount": 0.01,
"firstPayment": {
"date": "2025-06-08",
"amount": 100,
"description": "Aluguel"
}
}
```
**Carga Útil de Valor Variável**
```json title="Valor Variável"
{
"description": "Pix Automatico",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "WEEKLY",
"startDate": "2025-06-10",
"minimumVariableAmount": 100,
"maximumVariableAmount": 200,
"firstPayment": {
"date": "2025-06-08",
"amount": 300,
"description": "Primeiro mês"
}
}
```
Ao enviar pagamentos, você poderá enviar um valor entre **minimumVariableAmount** e **maximumVariableAmount**. Você não poderá enviar um valor fora desse intervalo sem criar outra autenticação.
Os pagamentos fixos não poderão submeter um **valor diferente** do que foi configurado.
Os valores do primeiro pagamento **podem ser diferentes e maiores do que a autorização** que foi solicitada. Isso não afeta os limites para aquele intervalo também.
---
## 3. Redirecionando o usuário para Autorizar
Uma vez que um pedido de pagamento é criado, a Pluggy gera uma **URL de pagamento**. Esta URL é onde seu usuário (pagador) revisará e autorizará o mandato Pix Automático.
- **Como funciona:** Redirecione ou envie a URL de pagamento para seu usuário. Eles serão guiados pelo processo de autorização, que está totalmente em conformidade com os requisitos do Banco Central do Brasil.
- **Exemplo de resposta:**
```json
{
"id": "req_abc123",
"paymentUrl": "https://pay.pluggy.ai/pix-automatico/req_abc123",
"status": "CREATED"
}
```
- **Melhores práticas:**
- Exiba a URL de pagamento em seu aplicativo ou envie-a por e-mail/SMS.
- Monitore o status do pedido de pagamento via webhooks ou consultando a API.
### API Direta
Para criar uma intenção de pagamento Pix Automático via API, você precisa enviar uma solicitação POST para `/payments/intents` com uma carga que inclua o paymentRequestId, o CPF/CNPJ do pagador e o nome.
```json
// https://api.pluggy.ai/payments/intents
{
"paymentRequestId": "req_abc123", // O ID do pedido de pagamento criado anteriormente
"connectorId": 123, // Placeholder: o id do conector da instituição do pagador (veja GET /connectors); para o fluxo de sandbox veja a seção 10
"parameters": {
"cpf": "12345678900", // Números de CPF
"name": "Maria Silva" // Nome completo do pagador
}
}
```
## 4. O que Acontece Após a Autorização?
- Uma vez que o usuário autoriza o pedido de pagamento através da `paymentUrl`, a Pluggy gerará uma **Intenção de Pagamento** para o `connectorId` específico (a instituição financeira ou banco selecionado pelo usuário).
- A Intenção de Pagamento representa o pagamento agendado real e pode ser rastreada através da API da Pluggy e webhooks.
- Você receberá atualizações em tempo real sobre o status da Intenção de Pagamento, Pedido de Pagamento e PIX Automático.
- Incluindo autorizações bem-sucedidas (`PAYMENT_COMPLETED`), rejeições (`CONSENT_REJECTED`) e expiração de consentimento (`EXPIRED`)
- Timeouts de autorização são relatados como `PAYMENT_TIMEOUT`
- Inclui notificações de primeiro pagamento e pagamentos futuros que estão sendo agendados
- Mudanças no status do pedido de pagamento são notificadas via webhook `payment_request/updated`
Se o processo de autorização do PIX Automático não for concluído dentro de 60 minutos, a Intenção de Pagamento é marcada como `PAYMENT_TIMEOUT` e a Pluggy envia um webhook `payment_intent/error`. Esse timeout é separado da expiração do `consentUrl`: a URL de autorização do banco expira após 5 minutos. A `paymentUrl` não é um link de cinco minutos; sua disponibilidade depende do status e configuração do Pedido de Pagamento.
## 5. Primeiro Pagamento
Automaticamente, após a autorização ter sido concedida, se o primeiro pagamento estiver agendado para o mesmo dia (pagamentos imediatos), você receberá notificações de que o pagamento foi agendado e está sendo processado, e você receberá uma segunda notificação de que o pagamento foi concluído.
**automatic_pix_payment/created**
```json title="automatic_pix_payment/created"
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"endToEndId": "E37943755202506111319U0da92d1b7e",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "automatic_pix_payment/created"
}
```
**automatic_pix_payment/completed**
```json title="automatic_pix_payment/completed"
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"endToEndId": "E37943755202506111319U0da92d1b7e",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "automatic_pix_payment/completed"
}
```
## 6. Cobrança do seu cliente
Uma vez que o pedido de pagamento é autorizado (o status do Pedido de Pagamento é `AUTHORIZED`), você pode agendar novos pagamentos para seu cliente usando a API da Pluggy.
Em vez de agendar manualmente cada pagamento via API, você pode habilitar o **Agendador de PIX Automático** ao criar seu pedido de pagamento. Com `schedulerConfiguration.enabled: true`, o sistema agenda automaticamente pagamentos em cada ciclo de recorrência dentro da janela permitida de D+2 a D+10 — sem chamadas de API ou jobs cron necessários do seu lado.
Esta é a abordagem recomendada, pois remove a complexidade de rastrear datas de pagamento e respeitar janelas de agendamento você mesmo.
Para detalhes completos, veja a [documentação do Agendador de PIX Automático](/docs/payments/pix-scheduler).
### Agendamento Manual
Se você preferir controlar quando cada pagamento é agendado, pode fazê-lo manualmente via API.
#### Agendando um Novo Pagamento
Para agendar um novo pagamento Pix Automático, faça uma solicitação `POST` para: `POST /payments/requests/{id}/automatic-pix/schedule`
Onde `{id}` é o ID do pedido de pagamento autorizado.
**Exemplo de solicitação**
```json title="Exemplo de solicitação"
// POST /payments/requests/req_abc123/automatic-pix/schedule
// Content-Type: application/json
{
"amount": 150.00,
"date": "2025-07-10",
"description": "Conta de serviços públicos de julho"
}
```
**Exemplo de resposta**
```json title="Exemplo de resposta"
{
"id": "66d503f1-0cfa-4d64-9f87-0782d959eba7",
"status": "SCHEDULED",
"amount": 150.00,
"description": "Conta de serviços públicos de julho",
"date": "2025-07-10",
"endToEndId": null,
"errorDetail": null
}
```
- O pedido de pagamento **deve** estar no status `AUTHORIZED`.
- A data agendada deve respeitar o intervalo e os limites definidos na autorização original (por exemplo, mensal, semanal).
- Apenas **um pagamento pode ser feito no intervalo**. Se você configurou o PaymentRequest para ser mensal, você poderá gerar apenas um pagamento mensal (mesmo dia do mês).
- Para mandatos de valor variável, o valor deve estar dentro da faixa mínima/máxima autorizada.
- Todas as validações de pagamento retornarão um erro HTTP 400 explicando por que o pagamento não será agendado.
- Você pode mudar a conta do destinatário enviando outro "recipientId" no corpo da solicitação. Esse destinatário deve ter o mesmo taxNumber que o destinatário original (caso contrário, falhará).
- Os pagamentos devem ser agendados entre 2 e 10 dias antes da data de pagamento. Por exemplo, se você quiser cobrar seu cliente no dia 15 de cada mês, precisará agendar o pagamento entre os dias 5 e 8 desse mês.
### Revisando pagamentos
- Você pode listar todos os pagamentos para um pedido usando:
```
GET /payments/requests/{id}/automatic-pix/schedules
```
Isso incluirá o primeiro pagamento também.
- Uma vez que você agenda um PIX Automático, nós o retornaremos na lista e enviaremos webhooks (`automatic_pix_payment/created`) quando ele for criado.
- Na data em que o pagamento foi agendado, ele tentará o pagamento e mudará para `COMPLETED`. Você poderá listá-lo e receber notificações de webhook também.
## 7. Como Repetir um Pagamento
Às vezes, um pagamento automático agendado pode falhar devido a fundos insuficientes, problemas de rede ou outros problemas temporários. Para garantir que seu fluxo de pagamento seja robusto, você precisa de um mecanismo de repetição para pagamentos falhados.
Primeiramente, a instituição fará o seguinte:
- Primeira tentativa: Entre 00:00 e 08:00 no dia agendado.
- Segunda tentativa: Se a primeira tentativa falhar (por exemplo, devido a fundos insuficientes), uma segunda tentativa é feita entre 18:00 e 21:00 no mesmo dia.
Se ambas as tentativas falharem, você tem duas opções:
### Recomendado: Repetições Automáticas
Recomendamos usar **[Repetições Automáticas](/docs/automatic-pix-automatic-retries)**. Quando você cria seu Pedido de Pagamento, você configura quais dias após uma falha a Pluggy deve tentar automaticamente novamente (por exemplo, 1, 3 e 5 dias depois). A Pluggy então cuida das repetições para você — sem chamadas de API extras, sem jobs cron e sem risco de perder a janela de repetição. Você só precisa ouvir os mesmos webhooks que já usa.
### Alternativa: Repetições Manuais
Se você preferir controlar as repetições você mesmo, pode chamar a API de repetição quando receber um webhook de erro:
1. **Identifique o Pagamento Falhado** — Monitore o status dos seus pagamentos agendados usando a API da Pluggy. Você receberá notificações de webhook para cada status de pagamento que mudar.
Para repetir um pagamento, ele deve ter sido agendado com sucesso e depois falhado na data de liquidação. Para verificar se um pagamento foi agendado corretamente, ele precisa ter um end_to_end_id definido. Além disso, o pagamento precisa estar no status `ERROR`.
2. **Inicie uma Repetição** — Para repetir um pagamento, use o endpoint da API para criar um novo pagamento, referenciando os detalhes do pagamento original. Você pode precisar fornecer o ID do pagamento original e atualizar quaisquer campos necessários (como a data agendada).
```http title="HTTP"
POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry
Content-Type: application/json
{
"date": "2024-07-01"
}
```
3. **Rastreie a Tentativa de Repetição** — Cada repetição gerará um novo registro de pagamento. Use a resposta para rastrear o status do novo pagamento.
Veja [FAQ do PIX Automático - Repetições](/docs/automatic-pix-faq#/retries) para mais detalhes.
#### Exemplo de Fluxo de Trabalho
- O pagamento agendado para 1º de julho falhou devido a fundos insuficientes.
- As instituições podem tentar novamente durante aquele dia após as 18hs.
- Se a segunda tentativa falhar, você agenda uma repetição para o dia seguinte.
- Após 3 repetições manuais falhadas, o pagamento pode ser considerado como não bem-sucedido.
### Erros Repetíveis
Nem todos os erros são elegíveis para repetições. Apenas os seguintes códigos de erro da instituição financeira acionam repetições automáticas:
- `UNKNOWN_ERROR` — Um erro desconhecido ocorreu na instituição Open Finance ou no titular da conta (por exemplo, fundos insuficientes)
- `PAGAMENTO_RECUSADO_DETENTORA` — Pagamento rejeitado pela instituição do titular da conta
- `PAGAMENTO_RECUSADO_SPI` — Pagamento rejeitado pelo SPI
- `FALHA_INFRAESTRUTURA_SPI` — Falha na infraestrutura do SPI
- `FALHA_INFRAESTRUTURA_ICP` — Falha na infraestrutura do ICP
- `FALHA_INFRAESTRUTURA_PSP_RECEBEDOR` — Falha na infraestrutura do PSP receptor
- `FALHA_INFRAESTRUTURA_DETENTORA` — Falha na infraestrutura da instituição do titular da conta
- `NAO_INFORMADO` — Não informado (por exemplo, detecção de fraude)
- `LIMITE_VALOR_TRANSACAO_CONSENTIMENTO_EXCEDIDO` — Limite de valor da transação de consentimento excedido
## 8. Monitorando repetições
Você pode rastrear todas as tentativas (originais e repetições) para um determinado agendamento usando o endpoint **Obter agendamento por ID**. Isso retorna o agendamento de pagamento mais um array `attempts` com o histórico completo de tentativas — uma entrada por tentativa (agendamento inicial mais cada repetição), ordenada da mais recente para a mais antiga.
**Endpoint:**
```http
GET /payments/requests/{requestId}/automatic-pix/schedules/{paymentId}
```
A resposta inclui o `status` atual do agendamento, `date`, `errorDetail` e um array `attempts`. Cada tentativa tem:
| Campo | Descrição |
|-------|-------------|
| `id` | Identificador único da tentativa |
| `status` | Status daquela tentativa (`SCHEDULED`, `COMPLETED`, `ERROR`, `CANCELED`, `IN_PROGRESS`) |
| `endToEndId` | ID de ponta a ponta da instituição (quando disponível) |
| `date` | Data da tentativa (YYYY-MM-DD) |
| `errorDetail` | Detalhes do erro se a tentativa falhou (por exemplo, `code`, `title`, `detail`) |
Use isso para:
- **Suporte:** Mostrar aos usuários o histórico completo do que aconteceu (por exemplo, "Falhou em 10 de julho (fundos insuficientes), repetido em 11 de julho, concluído em 12 de julho").
- **Dashboards:** Contar repetições, taxa de sucesso após repetições ou códigos de erro mais comuns.
- **Auditoria:** Manter um registro claro de cada tentativa para um determinado pagamento.
**Exemplo de resposta (agendamento com uma tentativa falhada e uma repetição bem-sucedida):**
```json
{
"id": "66d503f1-0cfa-4d64-9f87-0782d959eba7",
"status": "COMPLETED",
"amount": 150.00,
"description": "Conta de serviços públicos de julho",
"date": "2025-07-10",
"endToEndId": "E37943755202507101324U4bbaa85088",
"errorDetail": null,
"attempts": [
{
"id": "a1b2c3d4-...",
"status": "COMPLETED",
"endToEndId": "E37943755202507101324U4bbaa85088",
"date": "2025-07-11",
"errorDetail": null
},
{
"id": "e5f6g7h8-...",
"status": "ERROR",
"endToEndId": null,
"date": "2025-07-10",
"errorDetail": {
"code": "UNKNOWN_ERROR",
"title": "Um erro desconhecido ocorreu na instituição Open Finance ou titular da conta.",
"detail": "Um erro desconhecido ocorreu."
}
}
]
}
```
O `status` e `date` de nível superior do agendamento refletem o estado **atual** (por exemplo, `COMPLETED` e a data da repetição). O array `attempts` fornece a linha do tempo completa.
## 9. Cancelando Autorizações ou Pagamentos
### Cancelando uma Autorização
As autorizações permitem que pagamentos agendados sejam processados automaticamente. Se um usuário desejar interromper pagamentos futuros, ele pode cancelar a autorização a qualquer momento.
#### Como Cancelar uma Autorização
1. **Envie uma Solicitação de Cancelamento** — Use o endpoint da API para cancelar a autorização. Isso impedirá que futuros pagamentos sejam processados sob esta autorização.
```http
POST /payments/requests/{id}/automatic-pix/cancel
Content-Type: application/json
```
2. **Verifique o Status do Pedido de Pagamento** — A API retornará um 204 indicando que a solicitação de cancelamento foi aceita e que o banco procederá para processar o cancelamento.
3. **Ouça os Webhooks**: O status atualizado do pedido de pagamento será enviado como uma notificação via webhook `payment_request/updated`. Confirme que o status agora é `CANCELED` ou equivalente.
**Exemplo de Payload de Webhook:**
```json
{
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "payment_request/updated",
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"clientId": "client-123",
"status": "CANCELED"
}
```
- Pagamentos agendados para o dia seguinte ou primeiros pagamentos não serão cancelados.
- Uma vez que o pedido de pagamento é cancelado, não é possível autorizá-lo novamente. Nesse caso, você precisará criar um novo pedido de pagamento.
---
### Cancelando um Pagamento
Se um pagamento está agendado, mas ainda não foi processado, você pode cancelá-lo para evitar a transferência de fundos.
#### Como Cancelar um Pagamento
1. **Envie uma Solicitação de Cancelamento** — Use o endpoint da API para cancelar o pagamento.
```http
POST /payments/requests/{paymentId}/automatic-pix/schedules/{scheduleId}/cancel
Content-Type: application/json
```
Substitua `{paymentId}` pelo ID real do pagamento que você deseja cancelar.
2. **Verifique o Status do Pagamento Pix Automático Agendado** — A API retornará um 204 indicando que a solicitação de cancelamento foi aceita e que o banco procederá para processar o cancelamento.
3. **Ouça os Webhooks**: O status atualizado do agendamento de pagamento será enviado como uma notificação. Confirme que o status agora é `CANCELED` ou equivalente.
Pagamentos que já foram processados ou estão em um estado terminal (por exemplo, `COMPLETED`, `ERROR`) não podem ser cancelados.
Para cancelamentos feitos após a janela de tempo do dia anterior (22hs BRT), podem não ser cancelados.
Para mais detalhes, veja a [Referência da API Pluggy: Agendar pagamento automático PIX](/reference/payment-request-create-automatic-pix-schedule).
## 10. Testando no sandbox
Todo o fluxo do Pix Automático — consentimento, primeiro pagamento, cobranças agendadas e cancelamento — pode ser exercido contra o banco sandbox, sem conta real e sem dinheiro real.
Crie um [Payment Recipient](/reference/payment-recipient/payment-recipient-create) cujo `taxNumber` seja um **CNPJ** — o Pix Automático só paga empresas, no sandbox também. Em seguida, crie o pedido de pagamento com `isSandbox: true`, opcionalmente com um `firstPayment`.
O Pix Automático precisa do `cpf` **e** do `nome` do pagador:
```json title="POST /payments/intents"
{
"paymentRequestId": "{YOUR-SANDBOX-PAYMENT-REQUEST-ID}",
"connectorId": 600,
"parameters": {
"cpf": "76109277673",
"name": "Maria Silva"
}
}
```
Abra o `consentUrl` da resposta, faça login com `user-ok` / `password-ok` e autorize o mandato. Você recebeu `payment_intent/created` quando a intenção foi criada; agora a Intenção de Pagamento muda para `PAYMENT_COMPLETED`, o Pedido de Pagamento para `AUTHORIZED`, e você recebe `payment_intent/completed` e `payment_request/updated`.
Se o pedido tiver um `firstPayment` datado de hoje — a data atual em UTC — ou sem `date`, o sandbox o executa logo após o consentimento: você recebe `automatic_pix_payment/created` e `automatic_pix_payment/completed`. Um `firstPayment` datado no futuro é executado naquela data, no horário descrito abaixo. Em ambos os casos, a `startDate` do pedido deve ser um dia diferente do primeiro pagamento, como na produção (veja [Criando um Pedido de Pagamento](#1-criando-um-pedido-de-pagamento)).
Chame [POST /payments/requests/{id}/automatic-pix/schedule](/reference/payment-request-create-automatic-pix-schedule) com uma `date` e um `amount` (obrigatório). As mesmas regras da produção se aplicam: a data deve estar entre **D+2 e D+10** e respeitar o intervalo e limites de valor do mandato. Você recebe `automatic_pix_payment/created` quando ele é agendado e `automatic_pix_payment/completed` quando o sandbox o executa.
### Quando o sandbox executa pagamentos agendados
O banco sandbox liquida todos os pagamentos devidos em uma determinada data em uma única execução diária às **09:00 UTC (06:00 em Brasília)** naquela data — não há como fazer um pagamento agendado ser concluído mais cedo. Um pagamento agendado para D+2, portanto, é concluído dois dias depois, no início da manhã, e seu webhook `automatic_pix_payment/completed` chega então. A `date` que você envia é uma data do calendário (`YYYY-MM-DD`); a janela de D+2 a D+10 é contada a partir de hoje no horário de Brasília.
| O que você quer testar | Como produzir isso |
|---|---|
| Primeiro pagamento executado no consentimento | `firstPayment` com a data de hoje (UTC), ou sem `date`, e uma `startDate` posterior |
| Primeiro pagamento na data de início | Crie o pedido com `firstPayment.date` igual a `startDate`, ou com `date` ausente e `startDate` hoje: a API retorna um erro 400 com `AUTOMATIC_PIX_INVALID_FIRST_PAYMENT_DATE` |
| Pagamento agendado concluído | Agende um pagamento entre D+2 e D+10 e aguarde até 09:00 UTC naquela data |
| Falha da instituição no consentimento | Crie o pedido com um `firstPayment.amount` de `404.04`: `POST /payments/intents` falha e nenhuma `consentUrl` é emitida |
| Falha da instituição ao agendar | Agende um pagamento com um `amount` de `404.04`: a solicitação de agendamento é rejeitada |
| Data fora da janela | Agende para D+1 ou D+11: a API retorna um erro 400 |
| Consentimento cancelado | Chame [Cancelar Consentimento Automático do PIX](/reference/payment-request-cancel-automatic-pix-consent): o pedido muda para `CANCELED` e você recebe `payment_request/updated` |
O [Agendador de PIX Automático](/docs/payments/pix-scheduler) funciona no sandbox também; os pagamentos que ele agenda são executados pela mesma execução diária.
## Agendador de PIX Automático
Source: https://docs.pluggy.ai/pt/docs/payments/pix-scheduler.md
## Visão Geral
O **Agendador de PIX Automático** é uma extensão do recurso [PIX Automático](/docs/getting-started-with-pix-automático) da Pluggy que permite automatizar o agendamento de pagamentos recorrentes sem intervenção manual.
Em vez de chamar o endpoint de agendamento você mesmo para cada ciclo de pagamento, você pode habilitar o agendador ao criar a solicitação de pagamento. Assim que o pagador autorizar o consentimento, os pagamentos serão agendados automaticamente em cada ciclo de recorrência, sempre respeitando a janela de agendamento permitida (D+2 a D+10).
## Como funciona
Quando você cria uma solicitação de pagamento de PIX Automático com `schedulerConfiguration.enabled: true`, o sistema cuida do agendamento dos pagamentos para você. Após o pagador autorizar o consentimento, os pagamentos são agendados periodicamente de acordo com o `interval` e `startDate` configurados, dentro da janela permitida de D+2 a D+10. Isso continua automaticamente até que o consentimento expire ou seja cancelado.
## Configuração
Você configura o agendador no momento de criar a solicitação de pagamento de PIX Automático, através do objeto `schedulerConfiguration`:
```json
{
"schedulerConfiguration": {
"enabled": true,
"description": "Pagamento de assinatura mensal"
}
}
```
### Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `enabled` | `boolean` | Sim | Habilita o agendamento automático de pagamentos. |
| `description` | `string` | Não | Descrição para os pagamentos agendados (máx 140 caracteres). Se definido, substitui a `description` da solicitação de pagamento. |
| `valueForVariableAmount` | `number` | Condicional | **Obrigatório** quando o consentimento utiliza valores variáveis (`minimumVariableAmount` / `maximumVariableAmount`). Este é o valor padrão que será utilizado para cada pagamento agendado automaticamente. Deve estar dentro da faixa permitida. **Não permitido** quando o consentimento utiliza um `fixedAmount`. |
## Criando uma solicitação de pagamento com agendamento automático
### Exemplo de valor fixo
```bash
curl -X POST https://api.pluggy.ai/payments-requests/automatic-pix \
-H "X-API-KEY: {your-api-key}" \
-H "Content-Type: application/json" \
-d '{
"description": "Assinatura mensal",
"fixedAmount": 99.90,
"interval": "MONTHLY",
"startDate": "2025-07-01",
"recipientId": "{recipient-id}",
"schedulerConfiguration": {
"enabled": true,
"description": "Assinatura - Julho 2025"
}
}'
```
### Exemplo de valor variável
```bash
curl -X POST https://api.pluggy.ai/payments-requests/automatic-pix \
-H "X-API-KEY: {your-api-key}" \
-H "Content-Type: application/json" \
-d '{
"description": "Conta de serviços",
"minimumVariableAmount": 50.00,
"maximumVariableAmount": 500.00,
"interval": "MONTHLY",
"startDate": "2025-07-01",
"recipientId": "{recipient-id}",
"schedulerConfiguration": {
"enabled": true,
"valueForVariableAmount": 150.00
}
}'
```
## Lógica de agendamento
### Cálculo da data de pagamento
Cada pagamento é agendado no início de seu ciclo de recorrência. Por exemplo, um consentimento `MONTHLY` começando em 1º de julho terá pagamentos agendados para 1º de julho, 1º de agosto, 1º de setembro, etc.
De acordo com as regulamentações do Banco Central, os pagamentos devem ser agendados entre **D+2 e D+10**. Se a próxima data de pagamento já tiver passado D+2, o agendador ajusta para a data permitida mais próxima.
O agendador para automaticamente quando o consentimento expira (`expiresAt`) ou é cancelado. Em ambos os casos, um webhook `payment_request/updated` é enviado com o status da solicitação de pagamento definido como `EXPIRED` ou `CANCELED`, respectivamente.
## Regras de validação
| Cenário | Erro |
|---------|------|
| Consentimento de valor variável sem `valueForVariableAmount` na configuração do agendador | `AUTOMATIC_PIX_SCHEDULER_MISSING_VALUE_FOR_VARIABLE_AMOUNT` |
| `valueForVariableAmount` está fora da faixa de `minimumVariableAmount` / `maximumVariableAmount` | `AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_IN_RANGE` |
| `valueForVariableAmount` é fornecido, mas o consentimento utiliza um `fixedAmount` | `AUTOMATIC_PIX_SCHEDULER_VALUE_FOR_VARIABLE_AMOUNT_NOT_ALLOWED` |
## Intervalos suportados
O agendador suporta todos os intervalos do PIX Automático:
- `WEEKLY` — ciclos de 7 dias
- `MONTHLY` — ciclos de mês calendário
- `QUARTERLY` — ciclos de 3 meses
- `SEMESTER` — ciclos de 6 meses
- `ANNUAL` — ciclos de 12 meses
## Testando no sandbox
O agendador também funciona para solicitações de pagamento no sandbox (`isSandbox: true`, conector `600`). Ele agenda pagamentos dentro da mesma janela de D+2 a D+10, e o banco sandbox executa cada um às **09:00 UTC na data agendada**, quando o webhook `automatic_pix_payment/completed` é enviado. Espere que o primeiro pagamento agendado automaticamente seja concluído pelo menos dois dias após o consentimento. Veja [Testando no sandbox](/docs/payments/pix-getting-started#10-testing-in-sandbox) para o fluxo completo.
## Tentativas automáticas
Source: https://docs.pluggy.ai/pt/docs/payments/pix-retries.md
Quando um Pagamento Pix Automático falha (por exemplo, devido a fundos insuficientes), ele precisa ser refeito dentro de uma janela de tempo específica. Com **Tentativas Automáticas**, a Pluggy cuida disso para você — sem chamadas de API extras, sem polling, sem jobs cron do seu lado.
## Como funciona
Quando você cria uma Solicitação de Pagamento, pode incluir um objeto `automaticRetriesConfiguration` com um array `retryDays`. Cada valor representa o número de dias **após a data original do pagamento** quando a Pluggy deve tentar automaticamente refazer o pagamento se ele falhar.
Quando um pagamento entra no status `ERROR` com um erro recuperável, a Pluggy agendará automaticamente a próxima tentativa na primeira data futura disponível de sua configuração `retryDays`. Você receberá o webhook usual `automatic_pix_payment/created` quando a tentativa for agendada, e `automatic_pix_payment/completed` ou `automatic_pix_payment/error` quando for concluído.
Tentativas automáticas se aplicam apenas a pagamentos que foram agendados com sucesso e depois falharam na data de liquidação. Pagamentos que falham antes de serem agendados não são elegíveis para tentativas automáticas.
## Configurando Tentativas Automáticas
Adicione o campo `automaticRetriesConfiguration` ao criar sua Solicitação de Pagamento:
```json
POST /payments/requests/automatic-pix
{
"description": "Assinatura mensal",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "MONTHLY",
"startDate": "2025-07-01",
"fixedAmount": 49.90,
"isRetryAccepted": true,
"automaticRetriesConfiguration": {
"retryDays": [1, 3, 5]
}
}
```
Neste exemplo, se um pagamento agendado para 10 de julho falhar:
| Tentativa | Data | O que acontece |
|-----------|------|----------------|
| Original | 10 de julho | O pagamento falha devido a fundos insuficientes |
| Tentativa 1 | 11 de julho | A Pluggy tenta automaticamente (data original + 1 dia) |
| Tentativa 2 | 13 de julho | Se a tentativa 1 falhar, a Pluggy tenta novamente (data original + 3 dias) |
| Tentativa 3 | 15 de julho | Se a tentativa 2 falhar, a Pluggy tenta novamente (data original + 5 dias) |
Você receberá notificações de webhook para cada tentativa, para que possa manter seus usuários informados.
## Regras de configuração
### `retryDays`
Um array de inteiros (de 1 a 7) representando os dias após a data original do pagamento quando as tentativas devem ser feitas.
- Cada valor deve estar entre **1** e **7**.
- Um máximo de **3 tentativas** será feito por pagamento.
- Para intervalo `WEEKLY`, os dias de tentativa devem ser **5 ou menos** (para permanecer dentro do ciclo de recorrência).
### `isRetryAccepted`
Deve ser definido como `true` ao usar `automaticRetriesConfiguration`. Este campo faz parte do consentimento do Open Finance e sinaliza que o pagador autorizou as tentativas.
## Exemplos
### Assinatura mensal fixa com tentativas agressivas
Tente todos os dias por 3 dias consecutivos após uma falha:
```json
{
"description": "Associação à academia",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "MONTHLY",
"startDate": "2025-07-01",
"fixedAmount": 99.90,
"isRetryAccepted": true,
"automaticRetriesConfiguration": {
"retryDays": [1, 2, 3]
}
}
```
### Valor variável com tentativas espaçadas
Dê ao usuário mais tempo entre as tentativas:
```json
{
"description": "Conta de serviços públicos",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "MONTHLY",
"startDate": "2025-07-01",
"minimumVariableAmount": 50.00,
"maximumVariableAmount": 500.00,
"isRetryAccepted": true,
"automaticRetriesConfiguration": {
"retryDays": [1, 4, 7]
}
}
```
### Intervalo semanal
Para intervalos semanais, as tentativas devem estar dentro de 5 dias:
```json
{
"description": "Taxa de entrega semanal",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "WEEKLY",
"startDate": "2025-07-07",
"fixedAmount": 25.00,
"isRetryAccepted": true,
"automaticRetriesConfiguration": {
"retryDays": [1, 3, 5]
}
}
```
## Por que usar Tentativas Automáticas em vez de implementar tentativas você mesmo
### Tempo e conformidade
A regulamentação do Open Finance define regras específicas sobre quando e como os pagamentos Automáticos Pix podem ser refeito. As janelas de tentativas dependem do intervalo de recorrência, limites de ciclo e tipo de erro. As tentativas automáticas da Pluggy são construídas para cumprir essas regras desde o início, para que você não precise acompanhar datas de ciclo ou validar janelas de tentativas você mesmo.
### Tratamento de notificações de erro atrasadas
As instituições financeiras às vezes atrasam a comunicação do status final de um pagamento. Se um pagamento falhar na segunda-feira, mas a instituição só notificar o erro na quarta-feira, uma tentativa agendada para terça-feira já teria sido perdida. A Pluggy lida com isso de forma elegante — quando a notificação de erro chega, ela automaticamente escolhe a **próxima data de tentativa futura disponível** de sua configuração, pulando quaisquer datas que já estão no passado.
### Complexidade reduzida
Sem tentativas automáticas, você precisaria:
- Ouvir por webhooks `automatic_pix_payment/error`
- Determinar se o erro é recuperável
- Calcular a data correta da tentativa dentro da janela permitida
- Chamar `POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry` com a data correta
- Lidar com casos extremos como notificações atrasadas, limites de ciclo e limites máximos de tentativas
Com tentativas automáticas, tudo isso é tratado pela Pluggy. Você só precisa configurar `retryDays` uma vez ao criar a Solicitação de Pagamento.
### Confiabilidade
As tentativas automáticas são acionadas do lado do servidor imediatamente quando o erro é recebido. Não há dependência da sua infraestrutura estar disponível, nenhum risco de webhooks perdidos e nenhuma necessidade de implementar lógica de idempotência para chamadas de tentativas.
## Notificações de webhook
Você continuará a receber os mesmos eventos de webhook que com tentativas manuais:
| Evento | Quando |
|--------|--------|
| `automatic_pix_payment/error` | O pagamento (ou uma tentativa) falhou |
| `automatic_pix_payment/created` | Uma tentativa foi agendada |
| `automatic_pix_payment/completed` | Uma tentativa foi bem-sucedida |
## Erros recuperáveis
Veja [Erros recuperáveis](/docs/getting-started-with-pix-automático#retriable-errors) para a lista completa de códigos de erro que acionam tentativas automáticas.
Erros fora desta lista indicam um problema não transitório e **não** acionarão tentativas automáticas.
## Monitorando tentativas
Veja [Monitorando tentativas](/docs/getting-started-with-pix-automático#8-monitoring-retries) para detalhes sobre como rastrear todas as tentativas para um determinado pagamento.
## Perguntas Frequentes
Source: https://docs.pluggy.ai/pt/docs/payments/pix-faq.md
Common questions related to how Pix Automatico works.
### Criando um pedido de pagamento automático PIX
- **A autorização expira?**
O consentimento recorrente não tem uma data de expiração por padrão. Se necessário, você pode definir uma incluindo o campo `expiresAt` ao criar o pedido de pagamento. A tentativa inicial de autorização automática do PIX expira após 60 minutos se o pagador não a completar, e o `consentUrl` usado para autorização bancária expira após 5 minutos.
- **Quais são os campos `fixedAmount`, `minimumVariableAmount` e `maximumVariableAmount`?**
*Nota: O seguinte se aplica apenas a pagamentos agendados e não ao primeiro pagamento. Para detalhes sobre o primeiro pagamento, veja a próxima seção "Primeiro Pagamento."*
- Se `fixedAmount` for fornecido, todos os pagamentos agendados associados a este pedido de pagamento devem ter exatamente esse valor.
- Se `minimumVariableAmount` e `maximumVariableAmount` forem fornecidos, cada pagamento agendado deve ter um valor dentro dessa faixa. Uma vez que o consentimento é autorizado, esses valores não podem ser modificados. **Importante**: Algumas instituições (por exemplo, Nubank) permitem modificar o `maximumVariableAmount` quando o usuário autoriza o consentimento.
- **O que é o `interval`?**
Isso define a frequência do pagamento. Por exemplo, se o intervalo for definido como `MONTHLY`, apenas um pagamento por mês é permitido (excluindo o primeiro pagamento). O intervalo não pode ser alterado após a autorização do consentimento.
- **O que acontece se a `description` não for enviada?**
A instituição define uma descrição padrão.
- **Quais tipos de destinatários podem ser configurados no pedido de pagamento?**
Apenas empresas (CNPJ) podem ser configuradas como destinatários para pagamentos automáticos do Pix. O pagador pode ser uma pessoa física (CPF) ou uma empresa (CNPJ).
- **Posso mudar a conta do receptor?**
Sim, você pode fazer isso de duas maneiras:
- Editando o destinatário existente: [Atualizar Destinatário do Pagamento](/reference/payment-recipient-update#/)
- Criando e enviando um novo ao agendar um pagamento: [Agendar PIX Automático](/reference/payment-request-create-automatic-pix-schedule#/). A única restrição é que o novo destinatário deve ter o mesmo CNPJ que o destinatário original, caso contrário, o pagamento falhará.
### Primeiro pagamento
- **O valor pode exceder ou diferir do limite autorizado?**
Sim. O valor do primeiro pagamento é independente dos limites de pagamento autorizados. Por exemplo, se o usuário autorizou pagamentos entre R$100 e R$500, o primeiro pagamento ainda pode ser R$2.000.
- **Quando este pagamento é liquidado?**
Na `firstPayment.date`, se você a enviar. Se você omitir a data, o primeiro pagamento é liquidado imediatamente, no dia em que o usuário autoriza o pedido de pagamento.
- **O primeiro pagamento pode ser liquidado no mesmo dia que `startDate`?**
Não. O primeiro pagamento deve ser liquidado em um dia diferente de `startDate`, o início da recorrência. Se você enviar `firstPayment.date`, deve ser uma data diferente de `startDate`. Se você omitir, o primeiro pagamento é liquidado no dia em que o usuário autoriza (no horário de Brasília), então `startDate` não pode ser esse dia. Por exemplo, para cobrar a matrícula hoje e iniciar uma recorrência mensal, defina `startDate` um mês a partir de hoje.
Caso contrário, a API retorna `400`, tanto ao criar o pedido de pagamento quanto quando uma intenção de pagamento é criada para ele (`POST /payments/intents`):
```json
{
"code": 400,
"codeDescription": "AUTOMATIC_PIX_INVALID_FIRST_PAYMENT_DATE",
"message": "A data do primeiro pagamento deve ser diferente da data de início. Quando firstPayment.date não é fornecida, o primeiro pagamento é liquidado hoje."
}
```
- **É considerado parte dos limites de intervalo da autorização?**
Não. Por exemplo, se o usuário autorizou um pagamento por mês, o primeiro pagamento não afeta esse limite.
- **É obrigatório configurar um primeiro pagamento?**
Não, é completamente opcional.
### Agendando um pagamento
- **Quando um pagamento pode ser agendado?**
Após o pedido de pagamento ser autorizado, os pagamentos podem ser agendados entre D+2 e D+10 a partir de hoje, e somente se a periodicidade do pagamento permitir. Por exemplo, se a periodicidade for `WEEKLY` e um pagamento for agendado para quinta-feira, um novo pagamento pode ser agendado a partir da próxima quinta-feira (um pagamento por semana). O mesmo se aplica para outros tipos de intervalo (`MONTHLY`: mesmo dia todo mês, anualmente).
- **Como os ciclos de pagamento são calculados?**
Dependendo do tipo de intervalo selecionado, os ciclos de pagamento são calculados de maneira diferente, usando a `startDate` configurada como referência. Os pagamentos podem ser agendados em qualquer dia entre as datas de início e fim de cada ciclo (levando em conta as restrições D+2 e D+10 mencionadas anteriormente). Por exemplo:
Data de início do consentimento: 20/12/2025
- *WEEKLY*: Um novo ciclo começa a cada 7 dias
- Primeiro ciclo: 20/12/2025 - 26/12/2025
- Segundo ciclo: 27/12/2025 - 02/01/2026
- Etc.
- *MONTHLY*: Um novo ciclo começa no mesmo dia de cada mês. Se o dia não existir em um mês específico (por exemplo, 31/04), o ciclo começa no último dia disponível desse mês (neste caso, 30/04)
- Primeiro ciclo: 20/12/2025 - 19/01/2026
- Segundo ciclo: 20/01/2026 - 19/02/2026
- Etc.
- *QUARTERLY*: Mesmas regras que *MONTHLY*, mas a cada 3 meses:
- Primeiro ciclo: 20/12/2025 - 19/03/2026
- Segundo ciclo: 20/03/2026 - 19/06/2026
- Etc.
- *SEMESTER*: Mesmas regras que *MONTHLY*, mas a cada 6 meses:
- Primeiro ciclo: 20/12/2025 - 19/06/2026
- Segundo ciclo: 20/06/2026 - 19/12/2026
- Etc.
- *YEARLY*: Mesmas regras que *MONTHLY*, mas a cada 1 ano:
- Primeiro ciclo: 20/12/2025 - 19/12/2026
- Segundo ciclo: 20/12/2026 - 19/12/2027
- Etc.
- **O que acontece se o pagamento falhar?**
Veja a seção "Tentativas".
- **Um pagamento agendado pode ser modificado?**
Não, uma vez que um pagamento é agendado, ele não pode ser modificado. Se você precisar alterar a data, o valor ou a descrição, deve cancelá-lo e agendar um novo.
### Cancelando pagamentos e revogando consentimentos
- **Quais pagamentos podem ser cancelados?**
Apenas pagamentos com o status `SCHEDULED` podem ser cancelados. Uma vez que o pagamento é concluído, ele só pode ser reembolsado manualmente pelo destinatário. Veja: [Cancelar Agendamento de PIX Automático](/reference/cancel-automatic-pix-schedule)
- **Um consentimento automático do PIX pode ser revogado?**
Sim. Veja: [Cancelar Consentimento de PIX Automático](/reference/payment-request-cancel-automatic-pix-consent). Após revogar o consentimento, nenhum novo pagamento pode ser agendado sob esse pedido de pagamento. Este processo é assíncrono, então após receber uma resposta desse endpoint, alguns segundos podem passar até que o consentimento seja cancelado. Todos os pagamentos agendados (exceto aqueles a serem liquidadas no mesmo dia da cancelamento) também serão cancelados.
### Tentativas
- **Como implementar tentativas?**
Existem duas maneiras de implementar tentativas:
- Usando o sistema de tentativas automáticas da Pluggy (recomendado)
- Implementando um fluxo de tentativas personalizado. Mais informações aqui: [Como Tentar um Pagamento](/docs/getting-started-with-pix-automático#7-how-to-retry-a-payment)
- **Quantas vezes o banco tenta executar o pagamento?**
O banco tenta executar o pagamento duas vezes:
- Primeira tentativa: Entre 00:00 e 08:00 no dia agendado.
- Segunda tentativa: Se a primeira tentativa falhar (por exemplo, devido a fundos insuficientes), uma segunda tentativa é feita entre 18:00 e 21:00 no mesmo dia.
Depois disso, se o consentimento automático do PIX estiver configurado para permitir tentativas, até três tentativas adicionais podem ser feitas dentro de uma janela de 7 dias (5 para pagamentos semanais). Essas tentativas devem ser enviadas até 22:00 no dia anterior à nova data de pagamento agendada. Se o pedido de pagamento não permitir tentativas ou o número máximo de tentativas for alcançado, o pagamento receberá um status `ERROR` e não poderá ser tentado novamente.
Para tentar um pagamento, ele deve ter sido agendado com sucesso e depois falhado na data de liquidação.
> **Importante: se você perder a janela de 7 dias para agendar uma tentativa, esse pagamento não poderá mais ser tentado e você não poderá agendar novos pagamentos durante esse período. Além disso, a janela de 7 dias pode ser mais curta se o ciclo de pagamento terminar antes desse dia.**
### Sandbox
- **Como posso testar o Pix Automático sem uma conta bancária real?**
Use o banco sandbox: crie o pedido de pagamento com `isSandbox: true`, um destinatário CNPJ e uma intenção de pagamento com conector `600` e os parâmetros `cpf: "76109277673"` e `name`. Um `firstPayment` sem data ou datado para hoje é executado logo após o consentimento, desde que `startDate` seja um dia posterior; um `firstPayment` futuro e os pagamentos que você agenda (entre D+2 e D+10) são executados às 09:00 UTC na sua data. O valor `404.04` simula uma falha da instituição. Veja [Testando no sandbox](/docs/payments/pix-getting-started#10-testing-in-sandbox).
## Cobertura
Source: https://docs.pluggy.ai/pt/docs/payments/coverage.md
Usando nossa API autodocumentada, você pode acompanhar quais instituições suportam cada método de pagamento. Você pode recuperar a lista de instituições usando o endpoint [List Connectors](/reference/connectors-list).
Uma vez que você recupere uma instituição, você receberá um JSON semelhante a este:
```json title="Response"
{
"id": 601,
"name": "Itaú",
"primaryColor": "EC7000",
"institutionUrl": "https://www.itau.com.br/assets/dam/publisher/07_itau_empresas/13_open_banking/logos_regulatorio_bacen/opb_log_reg_bac_itau_img_01.svg",
"country": "BR",
"type": "PERSONAL_BANK",
"credentials": [
{
"validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
"validationMessage": "CPF deve ter 11 números.",
"label": "CPF",
"name": "cpf",
"type": "number",
"placeholder": "",
"optional": false
}
],
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/201.svg",
"hasMFA": false,
"oauth": true,
"health": {
"status": "ONLINE",
"stage": null
},
"products": [
"ACCOUNTS",
"TRANSACTIONS",
"IDENTITY",
"CREDIT_CARDS",
"PAYMENT_DATA",
"LOANS",
"INVESTMENTS"
],
"createdAt": "2023-09-01T18:05:09.145Z",
"isSandbox": false,
"isOpenFinance": true,
"updatedAt": "2024-07-16T15:34:08.028Z",
"supportsPaymentInitiation": true,
"supportsScheduledPayments": true,
"supportsSmartTransfers": true,
"supportsPixBiometric": true
}
```
**supportsPaymentInitiation**: Informa se a instituição suporta o uso da infraestrutura de Iniciação de Pagamento do Open Finance.
**supportsScheduledPayments**: Informa se a instituição implementou o Agendamento de Pagamentos do Open Finance através do Pix (*Pix Recorrente*).
**supportsSmartTransfers**: Informa se a instituição implementou Transferências Inteligentes do Open Finance (*Transferencias Inteligentes*).
**supportsPixBiometric**: Informa se os pagadores podem vincular uma conta na instituição para [PIX por biometria](/docs/payments/pix-biometric) (*Jornada Sem Redirecionamento*). Para listar apenas essas instituições, filtre com `GET /connectors?supportsPixBiometric=true`.
Para saber sobre novas instituições que foram adicionadas, você pode conferir nosso changelog ou usar o endpoint para trazer a lista mais atualizada de instituições.
## PIX por biometria
Source: https://docs.pluggy.ai/pt/docs/payments/pix-biometric.md
Com um [Pedido de Pagamento](/docs/payments/overview) regular, o pagador é redirecionado para seu banco a cada pagamento para aprová-lo. Com **PIX por biometria**, o pagador vai ao banco apenas uma vez, para vincular uma conta ao seu dispositivo. A partir de então, ele confirma cada pagamento na página de pagamento da Pluggy com Face ID, sua impressão digital ou o bloqueio de tela do dispositivo, sem sair da página.
PIX por biometria é a *Jornada Sem Redirecionamento* (JSR) do Open Finance. O pagamento ainda é um Pix iniciado através do Open Finance: ele é liquidado instantaneamente, e você o rastreia com os mesmos Pedidos de Pagamento, Intenções de Pagamento e webhooks que já utiliza.
Leia a [Visão Geral dos Pagamentos](/docs/payments/overview) primeiro. O PIX por biometria se baseia nos mesmos destinatários, pedidos de pagamento e intenções de pagamento.
## Como funciona
### O primeiro pagamento em um dispositivo
1. O pagador abre o `paymentUrl` e escolhe seu banco. Apenas instituições que suportam vinculação estão listadas.
2. A página explica o que significa vinculação, e o pagador é redirecionado para o banco. Lá, ele aprova o vínculo e define seus limites. Ele tem até 15 minutos para fazer isso.
3. De volta à página de pagamento, o pagador cria uma chave de acesso com as biometria ou bloqueio de tela do dispositivo. Isso completa o vínculo.
4. O pagador confirma o pagamento com biometria, e o Pix é enviado.
### Cada pagamento posterior
No mesmo dispositivo e navegador, a página de pagamento encontra a conta vinculada do pagador e a exibe ao lado dos detalhes do pagamento. O pagador confirma com biometria e o pagamento é enviado. Não há redirecionamento para o banco.
O pagador também pode optar por pagar com outro banco, o que inicia o caminho do primeiro pagamento para essa instituição.
## Conceitos
- **Pedido de Pagamento**: um por compra, criado com `POST /payments/requests/pix-biometric`. Você envia seu `paymentUrl` para o pagador, como em qualquer pedido de pagamento.
- **Intenção de Pagamento**: cada tentativa de pagar um pedido. As intenções de PIX por biometria têm `paymentMethod: "PIX_BIOMETRIC"` e um `enrollmentId`. Apenas a página de pagamento as cria.
- **Vinculação**: a conta vinculada. Ela liga a conta do pagador em uma instituição a um dispositivo e navegador. Apenas o pagador pode criá-la, na página de pagamento. Você pode listar, ler e revogar vinculações através da API. Veja [Gerenciando contas vinculadas](/docs/payments/pix-biometric-enrollments).
## Comparado a um pedido de pagamento regular
| | Pedido de Pagamento | PIX por biometria |
|---|---|---|
| Redirecionamento do banco | A cada pagamento | Apenas no primeiro pagamento em um dispositivo, para vincular a conta |
| Onde o pagador confirma | No aplicativo ou site do banco | Na página de pagamento da Pluggy, com biometria |
| Experiência de pagamento | Página de pagamento da Pluggy, ou sua própria UI através da API de Intenções de Pagamento | Apenas página de pagamento da Pluggy |
| Pagamentos agendados | Suportados ([Pix Agendado](/docs/payments/scheduled-payments)) | Não suportados: apenas pagamentos únicos |
| Sandbox | Disponível | Em desenvolvimento |
## Requisitos e limites
- **Iniciação de Pagamento** deve estar habilitada para seu cliente.
- **Instituições**: a instituição deve suportar vinculação. Verifique `supportsPixBiometric` no conector (veja [Cobertura](/docs/payments/coverage)).
- **Dispositivo**: o pagador precisa de biometria ou bloqueio de tela e um navegador que suporte chaves de acesso. Alguns navegadores embutidos em aplicativos não podem usar chaves de acesso; quando a página detecta um, ela pede ao pagador para abrir o link no navegador do dispositivo.
- **Um vínculo por dispositivo**: um vínculo pertence ao dispositivo e navegador onde a chave de acesso foi criada, ao CPF ou CNPJ do pagador, e ao seu cliente. Em outro dispositivo ou navegador, o pagador vincula novamente, o que cria uma nova vinculação.
- **Limites**: ao vincular, o pagador define um limite por pagamento e um limite diário no banco. A instituição rejeita um pagamento acima deles. O campo `limits` da vinculação os mostra.
- **Expiração**: cada vínculo tem uma data de expiração definida pela instituição (`expiresAt`). Após isso, o pagador vincula novamente.
- **Destinatários**: os pagamentos vão para destinatários de contas bancárias. Destinatários de contas inteligentes não são suportados.
## Compartilhando saldo (opcional)
Crie o pedido de pagamento com `linkedJourney: true` para permitir que o pagador também compartilhe seu saldo de conta e limite de cheque especial com você ao vincular, na mesma aprovação no banco. O compartilhamento é opcional para o pagador e desmarcado por padrão. Dura enquanto o vínculo, e você lê o saldo através da API antes de cobrar, para evitar pagamentos rejeitados por fundos insuficientes. Veja [Gerenciando contas vinculadas](/docs/payments/pix-biometric-enrollments#sharing-balance).
## Desvinculação
O pagador pode desfazer um vínculo a qualquer momento no aplicativo do banco. Você pode revogar um vínculo através da API. De qualquer forma, o próximo pagamento nesse dispositivo passa pelo banco novamente para criar um novo vínculo.
Veja [Introdução ao PIX por biometria](/docs/payments/pix-biometric-getting-started) para criar seu primeiro pedido de pagamento.
## Começando com PIX por biometria
Source: https://docs.pluggy.ai/pt/docs/payments/pix-biometric-getting-started.md
Este guia leva você de um destinatário a um pagamento concluído via PIX por biometria. Para saber o que é o PIX por biometria e como o pagador o experiencia, veja [PIX por biometria](/docs/payments/pix-biometric).
- Iniciação de Pagamento habilitada para seu cliente.
- Um [webhook](/docs/webhooks) registrado para eventos de pagamento, para que você saiba sobre pagamentos concluídos e contas vinculadas sem precisar fazer polling.
## 1. Criar um destinatário
O PIX por biometria paga os mesmos destinatários que qualquer solicitação de pagamento. Crie um destinatário de conta bancária conforme mostrado na [Visão Geral de Pagamentos](/docs/payments/overview), ou reutilize um que você já tenha. Destinatários de contas inteligentes não são suportados.
## 2. Identificar o pagador (recomendado)
Crie um Cliente de Pagamento com o CPF do pagador (e CNPJ para contas empresariais), conforme descrito em [Pré-preenchendo o CPF/CNPJ](/docs/payments/overview#pre-filling-the-cpfcnpj), e passe seu `customerId` ao criar a solicitação de pagamento. Duas coisas dependem disso:
- A página de pagamento usa o número de identificação fiscal do cliente e não o solicita. Sem um cliente, o pagador digita seu CPF.
- Você pode listar as contas vinculadas de um pagador pelo `customerId`. Veja [Gerenciando contas vinculadas](/docs/payments/pix-biometric-enrollments).
## 3. Criar a solicitação de pagamento
Crie uma solicitação de pagamento por compra:
```json title="POST /payments/requests/pix-biometric (request)"
{
"amount": 149.9,
"recipientId": "ab276a3d-17ba-47eb-97bf-688475037ffe",
"description": "Pedido 4821",
"customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
"clientPaymentId": "4821",
"linkedJourney": false,
"callbackUrls": {
"success": "https://my-store.com/orders/4821/paid",
"pending": "https://my-store.com/orders/4821/pending",
"error": "https://my-store.com/orders/4821/error"
}
}
```
| Campo | Obrigatório | Descrição |
|---|---|---|
| `amount` | Sim | Valor em BRL, com até duas casas decimais. Mínimo `0.01`. |
| `recipientId` | Sim | O destinatário que recebe o pagamento. Apenas destinatários de conta bancária. |
| `description` | Não | Exibido para o pagador. Até 140 caracteres. |
| `customerId` | Não | O Cliente de Pagamento que identifica o pagador. Recomendado. |
| `clientPaymentId` | Não | Seu próprio identificador para o pagamento. Até 200 caracteres. |
| `linkedJourney` | Não | `true` permite que o pagador também compartilhe seu saldo com você ao vincular. Veja [Compartilhando saldo](/docs/payments/pix-biometric-enrollments#sharing-balance). Padrão é `false`. |
| `callbackUrls` | Não | Para onde a página de pagamento envia o pagador quando o pagamento é bem-sucedido, fica pendente ou falha. Igual a qualquer solicitação de pagamento. |
Para cada campo e resposta, veja a [referência da API](/reference/pix-por-biometria/payment-request-create-pix-biometric).
A resposta é uma Solicitação de Pagamento regular com um objeto `pixBiometric`:
```json title="POST /payments/requests/pix-biometric (response)"
{
"id": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e",
"amount": 149.9,
"description": "Pedido 4821",
"status": "CREATED",
"createdAt": "2026-10-28T13:00:00.000Z",
"updatedAt": "2026-10-28T13:00:00.000Z",
"callbackUrls": {
"success": "https://my-store.com/orders/4821/paid",
"pending": "https://my-store.com/orders/4821/pending",
"error": "https://my-store.com/orders/4821/error"
},
"paymentUrl": "https://pay.pluggy.ai/5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e",
"clientPaymentId": "4821",
"pixBiometric": {
"linkedJourney": false,
"enrollment": null
}
}
```
`pixBiometric.enrollment` é `null` até que a solicitação seja paga. Veja [etapa 5](#5-track-the-payment).
O sandbox do PIX por biometria está em desenvolvimento. Até que esteja disponível, uma solicitação criada com `isSandbox: true` é rejeitada com `PIX_BIOMETRIC_SANDBOX_NOT_SUPPORTED`. Veja [Testando](#testing).
## 4. Enviar o pagador para a página de pagamento
Envie ao pagador a `paymentUrl`. A página de pagamento gerencia toda a jornada: escolhendo o banco, vinculando a conta no primeiro pagamento, criando a chave de acesso e confirmando o pagamento com biometria.
O pagador deve abrir o link em um navegador que suporte chaves de acesso. Alguns navegadores embutidos em aplicativos não conseguem usá-las; quando a página detecta um, pede ao pagador para abrir o link no navegador do dispositivo.
O primeiro pagamento começa em um navegador, continua no banco e retorna à página de pagamento. Se o banco enviar o pagador de volta para um navegador ou dispositivo diferente, a página pede que eles retornem ao ponto de partida ou vinculem novamente a partir de lá.
Você não pode criar intenções de pagamento via PIX por biometria através da API: `POST /payments/intents` responde `403` com `PIX_BIOMETRIC_INTENT_INTERNAL_ONLY` para essas solicitações. A página de pagamento as cria.
## 5. Rastrear o pagamento
A solicitação de pagamento e suas intenções passam pelos status habituais (veja [Ciclo de Vida e Erros da Intenção de Pagamento](/docs/payments/intent-lifecycle)), e você recebe os mesmos webhooks.
**Primeiro pagamento em um dispositivo** (o pagador vincula uma conta):
1. `payment_intent/created`
2. `payment_intent/waiting_payer_authorization`: o pagador está a caminho do banco para aprovar o vínculo.
3. `pix_biometric_enrollment/authorized`: o vínculo está completo.
4. `payment_intent/completed`
**Pagamentos posteriores** (o pagador já tem um vínculo naquele dispositivo):
1. `payment_intent/created`
2. `payment_intent/completed`
`payment_request/updated` é enviado sempre que o status da solicitação muda, como em qualquer solicitação de pagamento.
Uma vez que a solicitação é paga, ela mostra a conta vinculada com a qual foi paga:
```json title="GET /payments/requests/{id} (excerpt)"
{
"id": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e",
"status": "COMPLETED",
"pixBiometric": {
"linkedJourney": false,
"enrollment": {
"id": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
"status": "AUTHORIZED",
"connector": {
"id": 608,
"name": "Santander",
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/208.svg"
},
"debtor": {
"name": "John Doe",
"taxNumber": "***.456.789-**",
"bankAccount": {
"agency": "1234",
"account": "****4821",
"name": "Santander"
}
}
}
}
}
```
`enrollment.status` é o status atual do vínculo, portanto, muda se o vínculo for posteriormente revogado ou expirar. Permanece `null` quando a solicitação não foi paga, mesmo que o pagador tenha criado um vínculo ao longo do caminho: os webhooks `pix_biometric_enrollment/*` relatam esse vínculo.
Cada intenção de pagamento carrega `paymentMethod: "PIX_BIOMETRIC"` e o `enrollmentId` com o qual foi paga.
### Quando um pagamento falha
Além dos erros de pagamento em [Ciclo de Vida e Erros da Intenção de Pagamento](/docs/payments/intent-lifecycle), uma intenção de PIX por biometria pode terminar com um desses valores de `errorDetail.code`:
| Status da intenção | `errorDetail.code` | Significado |
|---|---|---|
| `CONSENT_REJECTED` | `ENROLLMENT_REJECTED` | A instituição ou o pagador rejeitaram o vínculo, portanto, o primeiro pagamento não foi realizado. |
| `CONSENT_REJECTED` | `ENROLLMENT_NOT_COMPLETED` | O vínculo expirou ou terminou antes que o pagador o completasse, por exemplo, porque ele não voltou do banco a tempo. |
| `CANCELED` | `PIX_BIOMETRIC_SUPERSEDED` | O pagador iniciou uma nova tentativa na mesma solicitação de pagamento, por exemplo, escolhendo outro banco. A nova tentativa continua. |
Uma tentativa falhada não fecha a solicitação de pagamento: o pagador pode tentar novamente a partir da mesma `paymentUrl`.
## Erros ao criar a solicitação de pagamento
| Status | `codeDescription` | Significado |
|---|---|---|
| `400` | `PIX_BIOMETRIC_SANDBOX_NOT_SUPPORTED` | `isSandbox` estava `true`. O sandbox do PIX por biometria está em desenvolvimento. |
| `400` | `PIX_BIOMETRIC_RECIPIENT_NOT_SUPPORTED` | O destinatário é uma conta inteligente. |
| `403` | `PAYMENT_INITIATION_NOT_ALLOWED` | A Iniciação de Pagamento não está habilitada para seu cliente. |
| `404` | `PAYMENT_RECIPIENT_NOT_FOUND` | O `recipientId` não existe para seu cliente. |
| `404` | `PAYMENT_CUSTOMER_NOT_FOUND` | O `customerId` não existe para seu cliente. |
## Testando
O sandbox do PIX por biometria está em desenvolvimento. Até que esteja disponível, testar significa um pagamento real em produção:
- Use um valor pequeno, como `0.01`.
- Pague de uma conta em uma instituição que suporte vinculação (`supportsPixBiometric`), em um telefone ou computador com biometria ou bloqueio de tela.
- Pague de uma conta diferente da do destinatário. Um pagamento para a mesma conta é rejeitado com `SAME_ORIGIN_DESTINATION_ACCOUNTS`.
- Quando terminar, revogue o vínculo de teste com `POST /pix-biometric/enrollments/{id}/revoke`, ou desfaça-o no aplicativo do banco.
Próximo: [Gerenciando contas vinculadas](/docs/payments/pix-biometric-enrollments).
## Gerenciando contas vinculadas
Source: https://docs.pluggy.ai/pt/docs/payments/pix-biometric-enrollments.md
Quando um pagador vincula uma conta na página de pagamento, a Pluggy armazena uma **inscrição**: o link entre sua conta em uma instituição e o dispositivo e navegador onde ele criou a chave de acesso. As inscrições são criadas apenas pelo pagador, durante um pagamento. Através da API, você pode listá-las, lê-las, ver os pagamentos feitos com elas e revogá-las.
Cada endpoint nesta página retorna apenas as inscrições do seu próprio cliente.
## A inscrição
```json title="Inscrição"
{
"id": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
"status": "AUTHORIZED",
"connector": {
"id": 608,
"name": "Santander",
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/208.svg"
},
"debtor": {
"name": "John Doe",
"taxNumber": "***.456.789-**",
"bankAccount": {
"agency": "1234",
"account": "****4821",
"name": "Santander"
}
},
"cpf": "***.456.789-**",
"cnpj": null,
"customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
"limits": {
"transaction": 1000,
"daily": 3000,
"dailyUsed": 149.9
},
"expiresAt": "2027-10-28T13:05:00.000Z",
"dataConsent": null,
"revokedBy": null,
"errorDetail": null,
"createdAt": "2026-10-28T13:02:00.000Z",
"updatedAt": "2026-10-28T13:05:00.000Z"
}
```
| Campo | Descrição |
|---|---|
| `id` | O id da inscrição. As intenções de pagamento referenciam como `enrollmentId`. |
| `status` | Veja a tabela abaixo. |
| `connector` | A instituição onde a conta está mantida. |
| `debtor` | A conta vinculada, conforme a instituição relatou. O número do CPF e o número da conta estão mascarados. |
| `cpf` / `cnpj` | O número do CPF do pagador, mascarado. Use o valor não mascarado para [filtrar a lista](#list-enrollments). |
| `customerId` | O Cliente de Pagamento da solicitação de pagamento onde o link foi criado, ou `null` quando o pagador digitou seu CPF. |
| `limits` | Os limites por pagamento (`transaction`) e `daily` que o pagador definiu no banco, e quanto do limite de hoje foi utilizado (`dailyUsed`), em BRL. Qualquer um deles pode ser `null` quando a instituição não o reporta. |
| `expiresAt` | Quando o link expira, conforme definido pela instituição. |
| `dataConsent` | A permissão de compartilhamento de saldo, ou `null` quando não foi solicitada. Veja [Compartilhando saldo](#sharing-balance). |
| `revokedBy` | Quem revogou o link: `BANK` (o pagador ou a instituição, no banco) ou `CLIENT` (você, através da API). `null` a menos que `status` seja `REVOKED`. |
| `errorDetail` | `{ code, description }` com o motivo que a instituição deu quando o link foi rejeitado, por exemplo, porque o pagador não o completou a tempo. Caso contrário, `null`. |
| `status` | Significado |
|---|---|
| `CREATED` | O pagador começou a vincular e não terminou: ele está no banco ou criando a chave de acesso. |
| `AUTHORIZED` | O link está ativo. Pagamentos nesse dispositivo precisam apenas de biometria. |
| `REJECTED` | O link não foi completado: a instituição ou o pagador o rejeitaram, ou o pagador não terminou a tempo. `errorDetail` diz qual. |
| `REVOKED` | O link foi revogado no banco ou através da API. |
| `EXPIRED` | O link atingiu sua data de expiração ou se tornou inativo na instituição. |
`REJECTED`, `REVOKED` e `EXPIRED` são finais. Para pagar com biometria novamente, o pagador precisa vincular novamente, o que cria uma nova inscrição.
## Listar inscrições
```
GET /pix-biometric/enrollments?customerId={customerId}&status=AUTHORIZED
```
| Parâmetro de consulta | Descrição |
|---|---|
| `customerId` | Inscrições criadas em solicitações de pagamento para este Cliente de Pagamento. |
| `cpf` | O CPF do pagador, apenas dígitos. |
| `cnpj` | O CNPJ do pagador, apenas dígitos. |
| `status` | Um dos status acima. |
| `page` / `pageSize` | Paginação. `pageSize` é no máximo `500`. |
A resposta utiliza a paginação usual:
```json title="GET /pix-biometric/enrollments (resposta)"
{
"total": 1,
"totalPages": 1,
"page": 1,
"results": [
{
"id": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
"status": "AUTHORIZED"
}
]
}
```
Um pagador pode ter várias inscrições: uma por dispositivo e navegador, e uma por instituição que ele vinculou. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollments-list).
## Recuperar uma inscrição
```
GET /pix-biometric/enrollments/{id}
```
Retorna a inscrição, atualizada pela instituição, de modo que um link revogado no banco apareça como `REVOKED` aqui mesmo antes que o webhook chegue. Um id que não existe para seu cliente responde `404` com `PIX_BIOMETRIC_ENROLLMENT_NOT_FOUND`. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-retrieve).
## Pagamentos feitos com uma inscrição
```
GET /payments/intents?enrollmentId={id}
```
Lista as intenções de pagamento feitas com aquele link, com a paginação usual. Cada uma carrega sua `paymentRequest`, para que você possa identificar quais compras o pagador fez com ela. Veja a [referência da API](/reference/payment-intent/payment-intents-list).
## Revogar uma inscrição
```
POST /pix-biometric/enrollments/{id}/revoke
```
Sem corpo. O link é revogado na instituição e a inscrição é retornada com `status: "REVOKED"` e `revokedBy: "CLIENT"`. Você também recebe um webhook `pix_biometric_enrollment/revoked`. Se o pagador ainda estava completando seu primeiro pagamento com aquele link, essa intenção de pagamento falha.
Revogar não pode ser desfeito: o pagador precisa vincular novamente para pagar com biometria. Revogar uma inscrição que já está `REJECTED`, `REVOKED` ou `EXPIRED` a retorna inalterada, então tentar novamente é seguro. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-revoke).
O pagador também pode desfazer o link a qualquer momento no aplicativo do banco. Você toma conhecimento disso através do webhook `pix_biometric_enrollment/revoked`, e a inscrição então mostra `revokedBy: "BANK"`.
## Compartilhando saldo
Quando a solicitação de pagamento foi criada com `linkedJourney: true`, o pagador também pode compartilhar seu saldo de conta e limite de cheque especial com você, na mesma aprovação no banco. É opcional para o pagador e dura enquanto o link estiver ativo. Leia o saldo logo antes de cobrar, para evitar um pagamento rejeitado por fundos insuficientes.
A inscrição carrega a permissão em `dataConsent`:
```json
{
"status": "AUTHORISED",
"rejectionReason": null,
"updatedAt": "2026-10-28T13:05:00.000Z"
}
```
| `dataConsent.status` | Significado |
|---|---|
| `AWAITING_AUTHORISATION` | O pagador ainda não aprovou. |
| `AUTHORISED` | O saldo pode ser lido. |
| `REJECTED` | O pagador ou a instituição rejeitaram. `rejectionReason` diz o porquê. |
| `REVOKED` | A permissão foi cancelada. |
`dataConsent` é `null` quando a solicitação não pediu por isso, ou o pagador optou por não compartilhar.
### Ler o saldo
```
GET /pix-biometric/enrollments/{id}/balance
```
Lê o saldo em tempo real da instituição. Os valores estão em BRL. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-balance-retrieve).
```json
{
"balance": 5.48,
"overdraft": {
"contracted": 1000,
"used": 0,
"available": 1000
}
}
```
`overdraft` é o limite de cheque especial da conta: quanto foi contratado, quanto está em uso e quanto ainda está disponível. É `null` quando a instituição não o compartilha.
| Status | `codeDescription` | Significado |
|---|---|---|
| `200` | | Saldo lido. |
| `403` | `PIX_BIOMETRIC_DATA_CONSENT_NOT_AVAILABLE` | O link não está `AUTHORIZED`, ou o pagador não compartilhou o saldo, ou a permissão foi cancelada. |
| `429` | `PIX_BIOMETRIC_RATE_LIMITED` | O limite de taxa da instituição foi atingido, por exemplo, a cota mensal de saldo da conta. |
Cada chamada lê o saldo da instituição, sem cache. O Open Finance limita as leituras de saldo por conta por mês (veja [Limites de Taxa Operacional](/docs/open-finance/rate-limits)). Leia o saldo logo antes de um pagamento, não em um cronograma.
### Parar de compartilhar o saldo
```
DELETE /pix-biometric/enrollments/{id}/data-consent
```
Cancela apenas a permissão de saldo: o link permanece `AUTHORIZED` e os pagamentos continuam funcionando. Retorna a inscrição com `dataConsent.status` definido como `REVOKED`. Cancelar uma permissão que já terminou retorna a inscrição inalterada, então tentar novamente é seguro. Um link criado sem a permissão responde `403` com `PIX_BIOMETRIC_DATA_CONSENT_NOT_AVAILABLE`. Veja a [referência da API](/reference/pix-por-biometria/pix-biometric-enrollment-data-consent-delete).
Revogar o link também encerra a permissão de saldo. Uma permissão não pode ser adicionada a um link existente: o pagador precisa vincular novamente a partir de uma solicitação de pagamento criada com `linkedJourney: true`.
## Webhooks
| Evento | Quando |
|---|---|
| `pix_biometric_enrollment/authorized` | O pagador completou um link. |
| `pix_biometric_enrollment/revoked` | O link foi revogado, no banco ou através da API. |
| `pix_biometric_enrollment/error` | O link não foi completado: foi rejeitado ou terminou antes que o pagador o finalizasse. |
```json title="pix_biometric_enrollment/authorized"
{
"event": "pix_biometric_enrollment/authorized",
"eventId": "8013240b-7c0a-409e-bf00-7fc586cc9196",
"enrollmentId": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
"customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
"paymentRequestId": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e"
}
```
`paymentRequestId` é a solicitação de pagamento onde o link foi criado, e `customerId` é `null` quando não havia cliente. Cada evento é enviado uma vez, quando a inscrição entra nesse status. Recupere a inscrição para os detalhes.
Um link que foi `AUTHORIZED` e depois atinge seu `expiresAt` não envia evento: verifique `expiresAt`, ou recupere a inscrição, para saber que terminou.
## Introdução
Source: https://docs.pluggy.ai/pt/docs/smart-transfers/introduction.md
A API de Smart Transfers da Pluggy torna os pagamentos instantâneos, fáceis e seguros. Aqui descrevemos de forma simples como você pode implementá-la.
Você deve ver nossa [documentação de Iniciação de Pagamentos](/docs/payments/overview) primeiro para entender o fluxo de pagamentos.
As principais diferenças entre esta API e a [Iniciação de Pagamentos](/docs/payments/overview) são:
- O usuário precisa dar o consentimento apenas uma vez (daqui em diante, **Pré-autorização de Smart Transfer**) por conta de devedor: Após o consentimento ser dado, você pode usar a API de Smart Transfers para enviar dinheiro desta conta para os destinatários autorizados (até que o consentimento expire ou seja revogado). Isso permite automatizar seu processo de pagamento sem interação do usuário.
- Todas as contas (devedor e destinatários) **devem pertencer ao mesmo proprietário (mesmo CPF para contas PF e mesmo CNPJ para contas PJ)**.
Veja a [próxima seção](/docs/smart-transfers/preauthorization) para saber como gerar uma **Pré-autorização de Smart Transfer**.
## Criando uma pré-autorização
Source: https://docs.pluggy.ai/pt/docs/smart-transfers/preauthorization.md
Nesta seção, você aprenderá como criar uma pré-autorização para realizar pagamentos sem interação do usuário.
## Criar um destinatário de pagamento
Primeiro, você precisa criar **Destinatários de Pagamento**. Estes serão os destinos permitidos para enviar transferências. Todos os destinatários devem pertencer ao mesmo proprietário.
```shell
curl --location 'https://api.pluggy.ai/payments/recipients' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ••••••' \
--data '{
"account": {
"type": "CHECKING_ACCOUNT",
"number": "1111111",
"branch": "0001"
},
"paymentInstitutionId": "abfd2a88-bc7b-407f-9fcc-395548ee6840",
"name": "John Doe",
"taxNumber": "11111111111"
}'
```
Verifique a [documentação da API](/reference/payment-recipient/payment-recipient-create) para saber como usar este endpoint. Para saber o `paymentInstitutionId`, você precisa usar este [endpoint](/reference/payment-recipient/payment-recipients-institution-list).
Isso retornará a seguinte resposta:
```json
{
"type": "BANK_ACCOUNT",
"id": "ded2e966-bd40-4e82-b467-d32fe4b4f40e",
"name": "John Doe",
"taxNumber": "11111111111",
"isDefault": false,
"paymentInstitution": {
"id": "abfd2a88-bc7b-407f-9fcc-395548ee6840",
"name": "Banco XP S.A.",
"tradeName": "BCO XP S.A.",
"ispb": "33264668",
"compe": "348",
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "CHECKING_ACCOUNT",
"number": "1111111",
"branch": "0001"
},
"pixKey": null,
"createdAt": "2024-08-01T16:32:29.276Z",
"updatedAt": "2024-08-01T16:32:29.276Z"
}
```
## Criar a Pré-autorização de Transferência Inteligente
Agora, você está pronto para criar uma pré-autorização de transferência inteligente. Para fazer isso, você precisa realizar a seguinte solicitação:
```shell
curl --location 'https://api.pluggy.ai/smart-transfers/preauthorizations' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ••••••' \
--data '{
"connectorId": 612,
"parameters": {
"cpf": "11111111111"
},
"recipientIds": [
"ded2e966-bd40-4e82-b467-d32fe4b4f40e"
],
"callbackUrls": {
"success": "https://my-success-page.com",
"error": "https://my-error-page.com"
},
"configuration": {
"transactionLimit": 100
},
"linkedJourney": true
}'
```
- O `connectorId` será aquele associado à instituição da sua conta devedora (por exemplo, se você quiser criar a pré-autorização no Nubank, você precisa enviar o id `612`).
- Você pode configurar os limites de transação enviando o campo `configuration` (veja a [seção de Configuração de limites de transação](#configuring-transaction-limits)).
- **linkedJourney** (opcional, padrão falso): também peça ao usuário, na mesma aprovação no banco, permissão para ler o saldo da conta de origem. Veja [Saldo da conta de origem](#source-account-balance).
Para mais detalhes sobre este endpoint, verifique nossa [documentação da API](/reference/smart-transfer/smart-transfer-preauthorization-create).
Para contas PF, você pode configurar apenas um destinatário por autorização. Apenas contas PJ podem configurar múltiplos destinatários para a mesma autorização.
Isso retornará a seguinte resposta:
```json
{
"id": "7e3e1dbb-8009-4966-9254-1eaab05ad18b",
"status": "CREATED",
"consentUrl": "https://this-is-the-consent-url.com",
"clientPreauthorizationId": null,
"callbackUrls": null,
"recipients": [
{
"type": "BANK_ACCOUNT",
"id": "ded2e966-bd40-4e82-b467-d32fe4b4f40e",
"name": "John Doe",
"taxNumber": "11111111111",
"isDefault": false,
"paymentInstitution": {
"id": "abfd2a88-bc7b-407f-9fcc-395548ee6840",
"name": "Banco XP S.A.",
"tradeName": "BCO XP S.A.",
"ispb": "33264668",
"compe": "348",
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "CHECKING_ACCOUNT",
"number": "1111111",
"branch": "0001"
},
"pixKey": null,
"createdAt": "2024-07-31T15:56:03.938Z",
"updatedAt": "2024-07-31T15:56:23.123Z"
}
],
"connector": {
"id": 612,
"name": "Nubank",
"primaryColor": "8a0fbe",
"institutionUrl": "https://nuapp.nubank.com.br/open-banking/logo.svg",
"country": "BR",
"type": "PERSONAL_BANK",
"credentials": [
{
"validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
"validationMessage": "CPF deve ter 11 numeros.",
"label": "CPF",
"name": "cpf",
"type": "number",
"placeholder": "",
"optional": false
}
],
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/212.svg",
"hasMFA": false,
"oauth": true,
"health": {
"status": "ONLINE",
"stage": null
},
"products": [
"ACCOUNTS",
"TRANSACTIONS",
"IDENTITY",
"CREDIT_CARDS",
"PAYMENT_DATA",
"LOANS",
"INVESTMENTS"
],
"createdAt": "2023-09-01T18:05:09.145Z",
"isSandbox": false,
"isOpenFinance": true,
"updatedAt": "2024-08-01T16:33:57.978Z",
"supportsPaymentInitiation": true,
"supportsScheduledPayments": true,
"supportsSmartTransfers": true
},
"dataConsent": {
"status": "AWAITING_AUTHORISATION",
"rejectionReason": null,
"updatedAt": "2026-10-07T18:43:08.390Z"
},
"createdAt": "2024-08-01T16:39:27.946Z",
"updatedAt": "2024-08-01T16:39:32.448Z"
}
```
Após a pré-autorização ser criada, você precisa redirecionar seu usuário para a `consentUrl` retornada na resposta. Lá, o usuário precisa aprovar a pré-autorização em sua instituição de pagamento. Após o consentimento ser dado, o usuário será redirecionado para a URL de callback `success` se tudo estiver ok, ou para a URL de callback `error` se o consentimento for rejeitado ou se ocorrer um erro no processo.
Nota: se você não definir um conjunto de `callbackUrls`, o usuário será redirecionado para uma página padrão da Pluggy.
Agora, se você verificar o status da pré-autorização usando [este endpoint](/reference/smart-transfer/smart-transfer-preauthorization-retrieve), você verá com um dos seguintes status:
- **COMPLETED**: A pré-autorização foi concluída e você está pronto para criar pagamentos.
- **REJECTED**: O usuário rejeitou a pré-autorização no fluxo de consentimento da instituição.
- **ERROR**: Ocorreu um erro no fluxo de consentimento da instituição.
Na [próxima seção](/docs/smart-transfers/creating-payment), você verá como criar um pagamento sem interação do usuário.
## Configurando limites de transação
Você pode configurar os limites de transação enviando o objeto `configuration`.
| Campo | Tipo | Opcional | Descrição |
|-------|------|----------|-------------|
| totalAllowedAmount | number | true | Valor máximo a ser alcançado pela soma de todas as transações que utilizam o consentimento autorizado pelo cliente. |
| transactionLimit | number | true | Valor máximo para cada transação de pagamento associada a este consentimento. |
| periodicLimits | object | true | Limites transacionais por período conforme determinado pelo usuário pagador. |
No objeto `periodicLimits`, você pode configurar os limites por período. Os períodos disponíveis são `day`, `week`, `month` e `year`, e para cada um você pode configurar:
| Campo | Tipo | Opcional | Descrição |
|-------|------|----------|-------------|
| quantityLimit | number | true | Número máximo de transações permitidas a ocorrer no período. |
| transactionLimit | number | true | Valor máximo a ser transacionado no período. |
Exemplo:
```json
{
"configuration": {
"totalAllowedAmount": 100.5,
"transactionLimit": 10,
"periodicLimits": {
"day": {
"quantityLimit": 2,
"transactionLimit": 5
},
"week": {
// limites semanais
},
"month": {
// limites mensais
},
"year": {
// limites anuais
}
}
}
}
```
No caso de algum limite ser atingido, você receberá um erro apropriado da API.
## Saldo da conta de origem
As Transferências Inteligentes são pagas da conta do usuário sem uma nova aprovação, portanto, uma transferência pode ser rejeitada por saldo insuficiente. Crie a pré-autorização com `linkedJourney: true` para também pedir ao usuário, na mesma aprovação no banco, permissão para ler o saldo da conta de origem. Nada mais muda no redirecionamento, no retorno ou nas transferências.
### Status da permissão
A pré-autorização carrega um objeto `dataConsent` enquanto a permissão existir. Ele é `null` quando `linkedJourney` não foi solicitado, e também pode ser `null` quando a permissão de saldo não está disponível para aquela instituição ou ambiente. Nesse caso, a pré-autorização é criada normalmente, sem a permissão.
| `status` | Significado |
|---|---|
| `AWAITING_AUTHORISATION` | O usuário ainda não aprovou. |
| `AUTHORISED` | O saldo pode ser lido. |
| `REJECTED` | Rejeitado, revogado, cancelado ou expirado. Não volta; `rejectionReason` diz o porquê. |
A permissão termina com a pré-autorização. Se o usuário revogar qualquer uma delas em seu banco, o endpoint de saldo responde `403`, e o status armazenado ainda pode ler `AUTHORISED` até que a instituição reporte a mudança.
`dataConsent` é atualizado pela instituição quando você recupera a pré-autorização pelo id. A lista retorna o último status conhecido. `updatedAt` é quando a Pluggy viu pela última vez a mudança de status.
### Ler o saldo
`GET /smart-transfers/preauthorizations/{id}/balance` lê o saldo da conta de origem em tempo real da instituição. Os valores estão em BRL.
```json
{
"balance": 5.48,
"overdraft": {
"contracted": 1000,
"used": 0,
"available": 1000
}
}
```
`overdraft` é o limite de cheque especial da conta: quanto foi contratado, quanto está em uso e quanto ainda está disponível. É `null` quando a instituição não o compartilha.
| Status | `codeDescription` | Significado |
|---|---|---|
| `200` | | Saldo lido. |
| `400` | `SMART_TRANSFER_DATA_CONSENT_NOT_REQUESTED` | A pré-autorização foi criada sem `linkedJourney`. |
| `403` | `SMART_TRANSFER_DATA_CONSENT_NOT_AVAILABLE` | A permissão está pendente, rejeitada ou revogada. |
| `429` | `BALANCE_OPEN_FINANCE_RATE_LIMIT` | O limite de taxa na instituição foi atingido, por exemplo, a cota mensal de saldo da conta. |
Cada chamada lê o saldo da instituição, sem cache. Open Finance limita as leituras de saldo por conta por mês (veja [Limites Operacionais de Taxa](/docs/open-finance/rate-limits)). Leia o saldo bem antes de uma transferência, não em um cronograma.
### Cancelar apenas a permissão
`DELETE /smart-transfers/preauthorizations/{id}/data-consent` cancela a permissão de saldo e retorna a pré-autorização com `dataConsent.status` definido como `REJECTED`. A pré-autorização permanece ativa e suas transferências continuam funcionando. Uma permissão não pode ser adicionada a uma pré-autorização existente: crie uma nova com `linkedJourney`.
| Status | `codeDescription` | Significado |
|---|---|---|
| `200` | | Permissão cancelada, ou já havia terminado. |
| `400` | `SMART_TRANSFER_DATA_CONSENT_NOT_REQUESTED` | A pré-autorização foi criada sem `linkedJourney`. |
| `403` | `SMART_TRANSFER_DATA_CONSENT_NOT_AVAILABLE` | A instituição não aceitou o cancelamento, por exemplo, porque o usuário ainda não aprovou a permissão. |
| `429` | `BALANCE_OPEN_FINANCE_RATE_LIMIT` | O limite de taxa na instituição foi atingido. |
Cancelar uma permissão que já terminou (rejeitada, revogada, ou sua pré-autorização revogada ou rejeitada) responde `200` com `status: REJECTED`, então tentar novamente é seguro.
## Criando um pagamento
Source: https://docs.pluggy.ai/pt/docs/smart-transfers/creating-payment.md
Nesta seção, você aprenderá como criar um pagamento associado a uma Pré-autorização de Transferência Inteligente.
Para criar um pagamento, você precisa fazer a seguinte solicitação:
```shell
curl --location 'https://api.pluggy.ai/smart-transfers/payments' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ••••••' \
--data '{
"preauthorizationId": "7e3e1dbb-8009-4966-9254-1eaab05ad18b",
"recipientId": "ded2e966-bd40-4e82-b467-d32fe4b4f40e",
"amount": 100,
"description": "Meu pagamento automático"
}'
```
Vamos analisar os campos que precisamos enviar:
- `preauthorizationId`: É o id da pré-autorização que criamos na [seção anterior](/docs/smart-transfers/preauthorization).
- `recipientId`: É um dos destinatários que autorizamos para a pré-autorização dada. Outros destinatários serão rejeitados.
- `amount`: O valor que você deseja enviar.
- `description`: Uma descrição opcional para enviar com a transferência.
Para mais detalhes sobre este endpoint, consulte a [documentação da API](/reference/smart-transfer/smart-transfer-payment-create).
Isso retornará o seguinte:
```json
{
"id": "b2b132f7-4c17-4707-bd5d-197d71d01385",
"preauthorizationId": "7e3e1dbb-8009-4966-9254-1eaab05ad18b",
"status": "CONSENT_AUTHORIZED",
"amount": 100,
"description": "Meu pagamento automático",
"recipient": {
"type": "BANK_ACCOUNT",
"id": "ded2e966-bd40-4e82-b467-d32fe4b4f40e",
"name": "John Doe",
"taxNumber": "11111111111",
"isDefault": false,
"paymentInstitution": {
"id": "abfd2a88-bc7b-407f-9fcc-395548ee6840",
"name": "Banco XP S.A.",
"tradeName": "BCO XP S.A.",
"ispb": "33264668",
"compe": "348",
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "CHECKING_ACCOUNT",
"number": "1111111",
"branch": "0001"
},
"pixKey": null,
"createdAt": "2024-07-31T15:56:03.938Z",
"updatedAt": "2024-07-31T15:56:23.123Z"
},
"createdAt": "2024-08-01T17:03:12.278Z",
"updatedAt": "2024-08-01T17:03:15.419Z",
"clientPaymentId": null
}
```
Você pode usar [este endpoint](/reference/smart-transfer/smart-transfer-paymentretrieve) para saber quando o pagamento é concluído (geralmente leva alguns segundos). Se tudo estiver ok, o status do pagamento será `PAYMENT_COMPLETED`.
As Transferências Inteligentes são categorizadas como um Pix Imediato entre diferentes contas do mesmo titular. Portanto, os limites definidos no consentimento para este produto devem ser tratados da mesma forma que a instituição aplica os limites do arranjo do Pix.
O cálculo do limite periódico disponível para o cliente deve seguir as diretrizes abaixo, considerando diferentes cenários e exemplos:
**Limite Diário (ex: R$ 100,00)**: Este limite controla transferências feitas dentro de um único dia, considerando o período de 00:00 a 23:59. Por exemplo, se um usuário transfere R$ 50,00 às 10:00, ele ainda terá R$ 50,00 disponíveis para transferências até a meia-noite do mesmo dia;
**Limite Semanal (ex: R$ 1.000,00)**: O limite semanal cobre o período de uma semana inteira, começando às 00:00 de domingo e terminando às 23:59 de sábado. Por exemplo, se um usuário transfere R$ 200,00 na terça-feira e R$ 500,00 na quinta-feira, ele ainda terá R$ 300,00 disponíveis para transferências até o final de sábado;
**Limite Mensal (ex: R$ 10.000,00)**: Este limite mensal é calculado do primeiro ao último dia de cada mês. Por exemplo, em um mês, se o usuário transfere R$ 2.000,00 na primeira semana e R$ 3.000,00 na segunda semana, ele ainda terá R$ 5.000,00 disponíveis para transferências pelo resto do mês;
**Limite Anual (ex: R$ 50.000,00)**: O limite anual conta do primeiro dia de janeiro até o último dia de dezembro. Por exemplo, se um usuário transfere R$ 10.000,00 até março, mais R$ 15.000,00 até junho, e mais R$ 20.000,00 até setembro, ele só poderá transferir mais R$ 5.000,00 até o final do ano.
Esses limites ajudam a gerenciar transferências de fundos, garantindo que não excedam os valores estabelecidos para cada período. Cada limite é independente e é recalculado à medida que sua respectiva janela de tempo se reinicia.
## Sandbox de Smart Transfers
Source: https://docs.pluggy.ai/pt/docs/smart-transfers/sandbox.md
A maneira mais fácil de experimentar este produto é usando o conector sandbox. Para fazer isso, você precisa criar uma pré-autorização de Smart Transfer usando o seguinte payload:
```shell
curl --location 'https://api.pluggy.ai/smart-transfers/preauthorizations' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: YOUR TOKEN' \
--data '{
"connectorId": 600,
"parameters": {
"cpf": "xxxxxxxx" // coloque um CPF válido aqui
},
"recipientIds": [
"xxxxxxxxxx" // coloque um id de destinatário válido aqui
]
}'
```
Para fazer login no banco simulado, você pode usar qualquer nome de usuário e senha -- qualquer combinação funcionará. Assim que a autorização estiver completa, você pode agendar todos os pagamentos que precisar.
## Conceitos básicos
Source: https://docs.pluggy.ai/pt/docs/developer-tools/basic-concepts.md
## Protocolos de segurança
A API da Pluggy exige o uso de HTTPS TLSv1.2 ou versões superiores por razões de segurança. Outros pedidos de versões TLS serão rejeitados. Toda comunicação deve ser feita em HTTPS.
## Verbos da API e Protocolos
A API da Pluggy é uma API RESTful baseada em solicitações e respostas JSON, portanto, todas as solicitações devem ter o cabeçalho `Content-Type` definido como `application/json`.
Seguimos os padrões RESTful e todos os verbos correspondem à sua ação específica para o recurso com o qual você estará se comunicando.
Evoluímos nossa API de uma maneira não quebrável, adicionando novos campos às respostas de nossos endpoints. Isso torna mais simples, uma vez que não há mecanismos complicados de versionamento, mas também significa que seu cliente HTTP deve suportar o recebimento de campos desconhecidos em uma resposta e ignorá-los. Na maioria das bibliotecas, isso é suportado por padrão, mas, por favor, revise seu caso particular para verificar se isso está configurado corretamente.
## Ambiente
Nosso ambiente de produção está aceitando solicitações no seguinte host:
```
https://api.pluggy.ai
```
## IDs de solicitação
Cada resposta da API da Pluggy carrega um cabeçalho `x-request-id` — um UUID
identificando aquela única solicitação:
```
x-request-id: 079482e5-8aa4-4708-9aaa-43c2f2792b4a
```
Está em cada resposta, bem-sucedida ou não, e é o único valor que nos permite
encontrar sua solicitação exata em nossos logs. Lê-lo não custa nada:
```bash
curl -i https://api.pluggy.ai/connectors \
-H 'X-API-KEY: YOUR_API_KEY' | grep -i x-request-id
```
**Registre-o junto com seus próprios erros.** Quando algo falha — um 4xx que você não
esperava, uma solicitação que expirou, uma resposta cujo conteúdo parece errado — nos envie
o `x-request-id` com seu relatório. Sem ele, procuramos por item, por janela de tempo
e por endpoint e frequentemente encontramos vários candidatos; com ele, vamos direto
para a solicitação que você viu, o que geralmente faz a diferença entre uma resposta no
mesmo dia e uma conversa que se estende por vários dias.
## Paginação
Algumas respostas da Pluggy podem gerar uma grande quantidade de dados, em cujos casos o tamanho da resposta é limitado e dividido em páginas.
Por exemplo, se você fizer uma solicitação para `/transaction?accountId={ACCOUNT_ID}`, você receberá um objeto como:
```json
{
"total": 200,
"totalPages": 15,
"results": [],
"page": 1
}
```
- **total**: o tamanho dos dados da solicitação
- **totalPages**: o número total de páginas abrangendo todos os registros disponíveis
- **results**: o conteúdo da página atual
- **page**: o número da página atual
Por exemplo, `/transaction?accountId={ACCOUNT_ID}&page=2` é a segunda página dos resultados de transações.
Ao recuperar `/transaction?accountId={ACCOUNT_ID}`, depois `/transaction?accountId={ACCOUNT_ID}&page=2`, e assim por diante, você pode acessar todos os dados disponíveis, uma página de cada vez.
Resumindo, para obter todos os dados de um endpoint paginado, após sua primeira solicitação, você deve iterar tantas vezes quanto `totalPages`, fazendo uma nova solicitação e alterando o parâmetro de consulta `page`.
## Executar no Postman
Source: https://docs.pluggy.ai/pt/docs/developer-tools/postman.md
## Executar no Postman
Você pode acessar nossa Coleção do Postman pelo link abaixo para testar todos os nossos endpoints. Você só precisa definir as variáveis de ambiente `CLIENT_ID` e `CLIENT_SECRET` na aba de Ambientes do Postman.
**[Executar no Postman](https://pluggy-official.postman.co/workspace/Pluggy---Public~c1b2c838-e81f-4544-9d4b-a06d80c58a39/collection/10111094-2ba022d3-1898-4d61-ac3d-221d59bac871?action=share&creator=16855841)**
O `CLIENT_ID` está na página da sua aplicação no [Dashboard do Pluggy](https://dashboard.pluggy.ai). O `CLIENT_SECRET` é exibido apenas uma vez, quando é gerado; se você não o tiver armazenado, gere um novo na página da aplicação (veja [Client ID e Client Secret](/docs/guides/dashboard-connectors#4-client-id-and-client-secret)).
### Configuração Inicial
1. Selecione a opção **"Open Postman"** e a coleção já será importada para o aplicativo.
2. Antes de começar, vamos preparar o ambiente para realizar as requisições. No aplicativo Postman, no canto esquerdo, selecione o menu **"Environments"**.
3. Em seguida, clique no botão **+ "create new environment"**.
4. Depois, nomeie seu ambiente e adicione as seguintes variáveis:
- `host` -- Endereço do servidor da aplicação: `https://api.pluggy.ai`
- `CLIENT_ID` -- Seu acesso de login
- `CLIENT_SECRET` -- Sua senha de acesso
5. Clique em **"Save"** para salvar as alterações.
Tudo pronto para começar a fazer chamadas à API Pluggy!
## Conectar uma conta
Source: https://docs.pluggy.ai/pt/docs/developer-tools/connect-account.md
Nesta seção, aprenderemos como conectar a API Pluggy com uma instituição financeira.
Cada entidade financeira terá um conector e payloads específicos necessários para a conexão que devem ser preenchidos no corpo da solicitação no Postman.
Esses payloads obrigatórios são encontrados na resposta da List Connectors (`GET /connectors`), no campo `credentials` dentro de cada objeto Connector. Cada uma dessas credenciais representa a definição da estrutura para cada parâmetro que precisa ser enviado, para resolver a etapa de login.
Existem conectores que também exigem um parâmetro adicional de Autenticação Multifatorial (MFA). Temos dois cenários possíveis aqui:
1. O parâmetro MFA pode ser resolvido pelo usuário sozinho, sem um prompt da instituição financeira, por exemplo, com o Google Authenticator. Nesse cenário, o parâmetro será encontrado dentro do payload `credentials`, terá o campo `"mfa": true` definido. Ele deve ser enviado na etapa inicial de login.
2. O parâmetro MFA só pode ser resolvido pelo usuário ao completar um desafio gerado pela instituição financeira, como um token enviado por e-mail ou SMS, escaneando um código QR ou respondendo a algum outro prompt. Os detalhes para resolver esse parâmetro serão encontrados após o login bem-sucedido, na resposta do Retrieve Item (`GET /items/:id`), no payload `parameter`. Em seguida, o valor do parâmetro deve ser enviado com o endpoint Send Item MFA (`POST /items/:id/mfa`).
Conectores com esse cenário podem ser distinguidos pelo campo `"mfa": true` na base da definição do payload do conector.
Portanto, dividiremos os conectores para facilitar a compreensão:
- Conectores sem código de verificação
- Conectores com código de verificação de uma etapa ("MFA 1-step")
- Conectores com código de verificação de duas etapas ("MFA 2-step")
## Conectores sem código de verificação
Para conectar uma conta que não precisa de um código de validação extra, basta acessar a Coleção Postman, expandir a pasta "Items" e selecionar a solicitação "Create Item".
Na aba "Body", insira suas credenciais nos elementos apresentados na solicitação "Create Item".
Listamos cada uma das instituições e suas especificidades abaixo:
### Itau PF
```json
{
"connectorId": 201,
"parameters": {
"agency": "",
"account": "",
"password": ""
},
"clientUserId": ""
}
```
Para o Itau PF recuperar Dados de Pagamento, é necessário atualizar o item pelo menos uma vez.
Para o Itau PF com conta conjunta, consulte abaixo (Fluxos de Exceção).
### Caixa PF
```json
{
"connectorId": 219,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
Para o Caixa PF, consulte abaixo (Fluxos de Exceção).
### Caixa PJ
```json
{
"connectorId": 216,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
### Santander PF
```json
{
"connectorId": 208,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
### Agora
```json
{
"connectorId": 220,
"parameters": {
"cpf": "",
"password": "",
"signature": ""
},
"clientUserId": ""
}
```
### Genial
```json
{
"connectorId": 213,
"parameters": {
"email": "",
"password": ""
},
"clientUserId": ""
}
```
### Sicredi PJ
```json
{
"connectorId": 227,
"parameters": {
"cnpj": "",
"user": "",
"password": ""
},
"clientUserId": ""
}
```
### Clear
```json
{
"connectorId": 223,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
### Sicoob PJ / Sicoob PF
```json
{
"connectorId": 228,
"parameters": {
"cooperativa": "",
"chaveAcesso": "",
"password": ""
},
"clientUserId": ""
}
```
## Conectores com código de verificação de uma etapa ("MFA 1-step")
Para conectar uma conta que solicita um código de validação extra em uma única etapa de login, basta acessar a Coleção Postman, expandir a pasta "Items" e selecionar a solicitação "Create Item with MFA".
Na aba "Body", suas credenciais para acessar a instituição devem ser inseridas junto com o código de verificação (token, SMS, etc), conforme apresentado nos elementos da solicitação "Create Item with MFA".
Você pode detectar quais instituições estão incluídas neste cenário, encontrando o valor `"mfa": true`, em um dos objetos `credentials`, dentro dos conectores na resposta da List Connectors.
### Inter
```json
{
"connectorId": 215,
"parameters": {},
"clientUserId": ""
}
```
### Modal Mais
```json
{
"connectorId": 204,
"parameters": {
"user": "",
"password": "",
"token": ""
},
"clientUserId": ""
}
```
### XP
```json
{
"connectorId": 202,
"parameters": {
"account": "",
"password": "",
"token": ""
},
"clientUserId": ""
}
```
### Rico
```json
{
"connectorId": 205,
"parameters": {
"user": "",
"password": "",
"token": ""
},
"clientUserId": ""
}
```
### Conta Simples
```json
{
"connectorId": 283,
"parameters": {
"email": "",
"password": "",
"token": ""
},
"clientUserId": ""
}
```
## Conectores com código de verificação de duas etapas ("MFA 2-step")
Neste fluxo, o parâmetro para inserir o código de verificação será solicitado após as credenciais do usuário serem validadas. Assim, é necessário enviar as credenciais e aguardar a validação para que o código de verificação possa ser enviado.
Você pode detectar quais instituições estão incluídas neste cenário, encontrando o valor `"mfa": true`, nas definições básicas de um Conector, encontradas na resposta da List Connectors.
Para verificar se as credenciais foram validadas e o código de verificação já deve ser enviado, basta acessar a Coleção Postman, expandir a pasta "Items", selecionar a solicitação "Specific Item" e inserir o `item_id` como um parâmetro da URL. Na resposta do serviço, o token deve ser enviado quando os elementos `status` e `executionStatus` tiverem o valor `WAITING_USER_INPUT`.
Neste ponto, o código de verificação deve ser enviado para que a conexão seja estabelecida. Para enviar o código, basta acessar a Coleção Postman, expandir a pasta "Items" e selecionar a solicitação "Send MFA Parameter user-triggered".
Na aba "Body", o código de verificação deve ser inserido conforme mostrado nos elementos da solicitação "Send MFA Parameter user-triggered" (token, sms, etc).
### Bradesco PJ
```json
{
"connectorId": 209,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
Enviar parâmetro MFA acionado pelo usuário:
```json
{
"token": ""
}
```
### B3 CEI
```json
{
"connectorId": 222,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
Enviar parâmetro MFA acionado pelo usuário:
```json
{
"code": ""
}
```
### BTG Pactual
```json
{
"connectorId": 214,
"parameters": {
"cpf": "",
"password": ""
},
"clientUserId": ""
}
```
Enviar parâmetro MFA acionado pelo usuário:
```json
{
"token": ""
}
```
### Safra
```json
{
"connectorId": 214,
"parameters": {
"agency": "",
"account": "",
"password": ""
},
"clientUserId": ""
}
```
Enviar parâmetro MFA acionado pelo usuário:
```json
{
"value": ""
}
```
Safra: o MFA será solicitado duas vezes na primeira execução do item. Depois, para atualizações do item, será solicitado apenas uma vez. Consulte abaixo "Safra" em Fluxos de Exceção.
### Avenue
```json
{
"connectorId": 230,
"parameters": {
"email": "",
"password": ""
},
"clientUserId": ""
}
```
Enviar parâmetro MFA acionado pelo usuário:
```json
{
"token": ""
}
```
### Genial
```json
{
"connectorId": 213,
"parameters": {
"email": "",
"password": ""
},
"clientUserId": ""
}
```
Enviar parâmetro MFA acionado pelo usuário:
```json
{
"mfa": ""
}
```
### Empiricus Investimentos
```json
{
"connectorId": 233,
"parameters": {
"cpf": "",
"password": ""
},
"clientUserId": ""
}
```
Enviar parâmetro MFA acionado pelo usuário:
```json
{
"value": ""
}
```
## Conectores com Seleção de Empresa
Os conectores empresariais podem exigir que você selecione qual empresa deseja conectar, dependendo se o usuário que está acessando tem acesso a mais de uma única empresa.
Nesses casos, após inicializar o item com os parâmetros iniciais, você será solicitado a um parâmetro adicional.
Esse parâmetro pode ser recuperado do endpoint "Specific Item", enviando o id criado, e será do tipo `select` -- isso significa que um dos valores da lista deve ser enviado de volta para nós para seleção.
### Sicoob PJ
```json
{
"id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
"status": "WAITING_USER_INPUT",
"executionStatus": "WAITING_USER_INPUT",
"lastUpdatedAt": null,
"error": null,
"paramater": {
"type": "select",
"name": "selectedCompany",
"label": "Qual e a sua empresa?",
"instructions": "Selecione a conta que deseja conectar",
"options": [
{
"value": "9025000",
"label": "902.500-0 One Company ltda"
},
{
"value": "9025001",
"label": "902.500-1 Second Company ltda"
}
],
"expiresAt": "2023-03-28T18:17:59.532Z"
}
}
```
Uma vez que o usuário tenha selecionado a empresa, envie-a de volta usando o Endpoint Send MFA:
```json
{
"selectedCompany": "9025000"
}
```
## Fluxos de Exceção
### Bradesco PF Conta Conjunta
O conector "Bradesco PF" está mapeado tanto para contas simples (individuais) quanto para contas conjuntas (Conta Conjunta).
Para conectar à conta conjunta, você pode simplesmente enviar qualquer valor "token" aleatório no endpoint "Create Item with MFA", por exemplo, `"000000"`, não importará porque a etapa de seleção da Conta, se aplicável, terá precedência e será resolvida primeiro.
```json
{
"connectorId": 203,
"parameters": {
"agency": "",
"account": "",
"password": "",
"token": "000000"
},
"clientUserId": ""
}
```
Faça chamadas no endpoint "Specific Item" passando o ItemId para verificar o status da conexão até que você obtenha o elemento `parameter` na resposta com o elemento `options` que contém a lista de contas registradas na instituição.
Em seguida, chame o endpoint "Send MFA Parameter user-triggered" com o valor da conta selecionada. Depois disso, o parâmetro token MFA precisará ser fornecido com o valor correto fornecido pelo usuário.
Continue fazendo chamadas no endpoint "Specific Item" até que o atributo `executionStatus` seja definido como `SUCCESS` (ou `PARTIAL_SUCCESS`), significando que sua conexão foi criada/atualizada com sucesso.
Como esta é uma conta conjunta, tenha em mente que a Pluggy coletará apenas os dados da conta selecionada pelo usuário na primeira etapa.
### Banco do Brasil PJ
No caso do Banco do Brasil Empresas, para que a conexão seja estabelecida, será necessário usar um computador que seja o mesmo já autorizado no internet banking. A conta utilizada para a conexão deve ter um celular registrado no Banco do Brasil, pois este receberá um link de confirmação a ser inserido no momento da conexão.
Primeiro, faça uma chamada no endpoint "Create Item":
```json
{
"connectorId": 217,
"parameters": {
"userJ": "",
"passwordJ": "",
"password": ""
},
"clientUserId": ""
}
```
Chame o endpoint "Specific Item" até que você obtenha `executionStatus` como `WAITING_USER_INPUT` e o atributo `parameter` com uma lista de celulares registrados na instituição. Selecione um telefone, em seguida, forneça a URL do token SMS recebida naquele telefone.
### Itau PF (Conta Conjunta)
Primeiro, faça uma chamada no endpoint "Create Item":
```json
{
"connectorId": 201,
"parameters": {
"agency": "",
"account": "",
"password": ""
},
"clientUserId": ""
}
```
Em seguida, chame o endpoint "Specific Item" até que você obtenha o `executionStatus` como `WAITING_USER_INPUT`. O elemento `parameter` incluirá uma lista de contas (operadores). Selecione uma e envie-a via o endpoint "Send MFA Parameter user-triggered".
Este parâmetro `operatorNumber` é solicitado apenas pela primeira vez que o Item é criado, depois é armazenado e reutilizado para quaisquer atualizações subsequentes da mesma instância do Item.
### Itau PF (com MFA)
Algumas contas do Itau PF exigem MFA. Crie o item com as credenciais padrão, em seguida, consulte o endpoint "Specific Item" até `WAITING_USER_INPUT` com `"name": "mfa"` no parâmetro. Envie o token MFA via o endpoint "Send MFA Parameter user-triggered".
### Itau PJ
O conector "Itau" está mapeado tanto para contas simples (individuais) quanto para contas conjuntas. Para conectar à conta conjunta, envie o nome do titular da conta via o endpoint "Send MFA Parameter user-triggered".
```json
{
"connectorId": 218,
"parameters": {
"agency": "",
"account": "",
"password": "",
"cpfOrOperator": ""
},
"clientUserId": ""
}
```
### XP (acesso CPF - conta conjunta)
O conector "XP" permite conectar tanto contas simples (acesso por número da conta) quanto contas conjuntas (com acesso CPF).
```json
{
"connectorId": 202,
"parameters": {
"account": "",
"password": "",
"token": ""
},
"clientUserId": ""
}
```
Consulte o endpoint "Specific Item" até `WAITING_USER_INPUT` com um parâmetro `selectedAccount`, em seguida, envie o valor da conta selecionada.
### Santander PJ
Para o Santander PJ, a conexão requer escanear um código QR e enviar um código de validação extra.
```json
{
"connectorId": 221,
"parameters": {
"agency": "",
"account": "",
"user": "",
"password": ""
},
"clientUserId": ""
}
```
Consulte o endpoint "Specific Item" até `WAITING_USER_INPUT`. O `parameter` conterá uma imagem de código QR codificada em base64 no atributo `data`. Exiba o código QR, escaneie-o com um telefone e envie o token resultante via o endpoint "Send MFA Parameter user-triggered".
### Inter PJ
Este conector utiliza a API OAuth 2 do banco. Você precisa primeiro gerar e obter `clientId`, `clientSecret`, os arquivos `API_Chave.key` e `API_Certificado.crt` da conta bancária do cliente.
A chave privada e o certificado devem ser fornecidos em base64 sem quebras de linha entre o cabeçalho e o rodapé de cada arquivo.
```json
{
"connectorId": 225,
"parameters": {
"clientId": "",
"clientSecret": "",
"privateKey": "",
"certificate": ""
},
"clientUserId": ""
}
```
### BTG Pactual, Empiricus e EQI
O conector "BTG" (Empiricus e EQI) está mapeado tanto para contas simples quanto para contas conjuntas. Para conectar à conta conjunta, envie o nome do titular da conta via o endpoint "Send MFA Parameter user-triggered".
### Caixa PF e PJ
Usar este conector requer que o usuário autorize um novo dispositivo (Pluggy) dentro de seu aplicativo móvel da Caixa.
Tenha em mente que, a partir do momento em que o usuário insere suas credenciais, pode levar até 30 minutos para concluir o processo de login.
Primeiro, use o endpoint "Create Item" e envie os parâmetros necessários para a conexão:
Caixa PF:
```json
{
"connectorId": 219,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
Caixa PJ:
```json
{
"connectorId": 216,
"parameters": {
"user": "",
"password": ""
},
"clientUserId": ""
}
```
Se tudo estiver ok, o conector retornará o status `USER_AUTHORIZATION_PENDING` e um nome de dispositivo.
Use o endpoint "Specific Item" (`GET /items/:id`) para verificar o status da conexão. Chame o endpoint até que o atributo de resposta `executionStatus` tenha o valor `USER_AUTHORIZATION_PENDING`, assim como no exemplo abaixo:
```json
{
"createdAt": "2022-12-29T17:42:43.926Z",
"updatedAt": "2022-12-29T17:42:46.836Z",
"status": "OUTDATED",
"executionStatus": "USER_AUTHORIZATION_PENDING",
"lastUpdatedAt": null,
"webhookUrl": null,
"error": {
"code": "USER_AUTHORIZATION_PENDING",
"message": "O usuário precisa conceder as permissões necessárias para sua conta.",
"providerMessage": "No Internet Banking, clique em > Senhas e Configurações > Computadores e Dispositivos > Gerenciar \n Você precisa ativar o seguinte dispositivo:",
"attributes": {
"deviceNickname": "nick-name",
"qrCodes": "cHJ1ZWJh,cHJ1ZWJhMg==,cHJ1ZWJhJJ=="
}
}
}
```
**Agora o usuário deve autorizar o novo dispositivo em seu aplicativo móvel da Caixa**, seguindo os passos abaixo:
1. Acesse o menu "Senhas e Configurações".
2. Selecione "Gerenciar Dispositivos" e depois "Dispositivos Registrados". Uma lista será retornada com os dispositivos registrados naquela conta. Procure na lista o dispositivo com o mesmo nome que foi retornado no campo `deviceNickname` da chamada anterior e selecione-o.
3. Clique no botão "Ativar dispositivo".
4. A tela "Ativar Dispositivo" será exibida; clique no botão "Continuar".
5. Escaneie os QRs recebidos no atributo `qrCodes` no payload anterior. Ele contém três QRs separados por vírgula que irão rotacionar a cada 5 segundos.
Assim que a etapa acima for concluída, aguarde 30 minutos para que a Caixa autorize o dispositivo, em seguida, faça uma chamada ao endpoint "Update Item" (`PATCH /items/:id`).
Informe o ItemId que você deseja atualizar no parâmetro do endpoint e faça a chamada com um corpo vazio (não é necessário reentrar as credenciais). O resultado esperado é `executionStatus: UPDATING`.
Tenha em mente que o status de execução pode mudar rapidamente, e você também pode encontrar um status `CREATED` ou até mesmo `LOGIN_IN_PROGRESS`.
Retorne ao endpoint "Specific Item" para que você possa verificar o status da conexão. O resultado esperado é `executionStatus: SUCCESS`.
```json
{
"createdAt": "2022-12-29T17:42:43.926Z",
"updatedAt": "2022-12-29T17:42:44.011Z",
"status": "UPDATED",
"executionStatus": "SUCCESS",
"lastUpdatedAt": null,
"webhookUrl": null,
"error": null,
"clientUserId": "client-usr-id",
"statusDetail": null,
"parameter": null
}
```
Neste ponto, você poderá recuperar os dados dos produtos para este Item.
Talvez você esteja se perguntando se a Pluggy pode atualizar automaticamente os Itens que têm o dispositivo autorizado — aqui está uma pequena explicação de como fazemos isso. Sinta-se à vontade para entrar em contato conosco se não estiver claro o suficiente.
Uma vez que o usuário autoriza o novo dispositivo, é necessário aguardar 30 minutos até que a Caixa o aprove. Então, podemos ter duas situações diferentes:
1. O usuário aciona uma atualização e, se tudo estiver ok, retornaremos `SUCCESS`.
2. Nosso sistema de atualização automática será executado a cada 6 horas (após os 30 minutos necessários para autorizar o dispositivo) a fim de obter `status: SUCCESS` nos Itens que tiveram o dispositivo autorizado, mas não tiveram os dados coletados (não foram atualizados após os 30 minutos). Esse fluxo roda por 48 horas até receber o status `SUCCESS`, depois disso não continua atualizando automaticamente.
Se o usuário não atualizou em nenhum momento, receberá `USER_AUTHORIZATION_NOT_GRANTED`.
### Safra
Para conectar uma conta, este conector requer que o usuário autorize um novo dispositivo (`Pluggy - yyyy-mm-dd hh-mm`) através do aplicativo móvel Safra.
Primeiro, use o endpoint "Create Item" e envie os parâmetros necessários para a conexão:
```json
{
"connectorId": 229,
"parameters": {
"agency": "",
"account": "",
"password": ""
}
}
```
Se tudo estiver ok, após inserir o token fornecido pelo aplicativo Safra, o conector retornará o `executionStatus` `WAITING_USER_ACTION`. Use o endpoint "Specific Item" (`GET /items/:id`) para verificar o status da conexão. Chame o endpoint até que o atributo de resposta `executionStatus` tenha o valor `WAITING_USER_ACTION`, assim como no exemplo abaixo:
```json
{
"id": "c33872c7-85dc-4d67-b262-6490d85ea2d3",
"connector": {
"id": 229,
"name": "Safra",
"primaryColor": "#00003C",
"institutionUrl": "https://www.safra.com.br/",
"country": "BR",
"type": "PERSONAL_BANK",
"credentials": [
{
"validation": "^\\d{3,3}\\d$",
"validationMessage": "O agência deve ter 4 números.",
"label": "Agência",
"name": "agency",
"type": "number",
"placeholder": "Exemplo: 1234",
"optional": false
},
{
"validation": "^\\d{6,6}-?\\d$",
"validationMessage": "A conta deve ter 7 números.",
"label": "Conta",
"name": "account",
"type": "number",
"placeholder": "Exemplo: 12345-6",
"optional": false
},
{
"validation": "^\\d{1,6}$",
"validationMessage": "A senha deve ter menos de 6 números.",
"label": "Senha",
"name": "password",
"type": "password",
"placeholder": "",
"optional": false
}
],
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/229.svg",
"hasMFA": true,
"health": {
"status": "ONLINE",
"stage": null
},
"products": [
"ACCOUNTS",
"TRANSACTIONS",
"INVESTMENTS"
],
"createdAt": "2022-11-04T21:12:51.716Z"
},
"createdAt": "2023-02-27T17:42:40.521Z",
"updatedAt": "2023-02-27T17:43:47.114Z",
"status": "WAITING_USER_ACTION",
"executionStatus": "WAITING_USER_ACTION",
"lastUpdatedAt": null,
"webhookUrl": null,
"error": null,
"clientUserId": null,
"statusDetail": null,
"parameter": null,
"userAction": {
"instructions": "O usuário precisa autorizar o dispositivo em seu aplicativo Safra",
"attributes": {
"deviceNickname": "Pluggy - 2023-02-27 17:42"
},
"expiresAt": "2023-02-27T17:45:46.237Z"
},
"nextAutoSyncAt": null
}
```
O Item permanecerá nesse estado até:
- O usuário autoriza o dispositivo no aplicativo Safra: nesse caso, o status do Item mudará automaticamente e um novo token será solicitado ao usuário.
ou
- O usuário não autoriza o dispositivo no aplicativo Safra: o Item retornará o status de execução `USER_AUTHORIZATION_NOT_GRANTED`.
ou
- A data atual é posterior à data `expiresAt` retornada na propriedade `userAction`: o Item retornará o status `USER_AUTHORIZATION_PENDING`. Nesse cenário, o usuário pode autorizar o dispositivo mais tarde, e após isso o Item pode ser atualizado.
Esse fluxo acontecerá apenas na criação do Item. Se o dispositivo foi autorizado e o Item é atualizado, ele solicitará apenas um token do usuário.
### Banco Inter PF
Usar este conector para um Item na primeira execução requer que o usuário autorize o login com o Inter escaneando um código QR com seu aplicativo móvel Inter.
Para isso, o usuário deve estar preparado para escanear o código QR fazendo login no aplicativo móvel e indo para Opções → iSafe e Internet Banking → Código QR.
Primeiro, use o endpoint "Create Item" — sem parâmetros necessários, já que todo o fluxo de login será por QR:
```json
{
"connectorId": 215,
"parameters": {}
}
```
Em seguida, retorne ao endpoint "Specific Item" para que você possa verificar o status da conexão. Logo após a criação, o Item atingirá um status `WAITING_USER_ACTION`. Neste ponto, o campo `userAction.attributes.data` do Item conterá um código QR em base64 a ser escaneado:
```json
{
"createdAt": "2023-02-27T12:46:25.707Z",
"updatedAt": "2023-02-27T12:46:33.365Z",
"status": "WAITING_USER_ACTION",
"executionStatus": "WAITING_USER_ACTION",
"lastUpdatedAt": null,
"webhookUrl": null,
"error": null,
"clientUserId": null,
"statusDetail": null,
"parameter": null,
"userAction": {
"instructions": "ESCANEIE O QR",
"expiresAt": 123456789,
"attributes": {
"name": "qr",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALkAAAC5CAAAAABRxsGAAAAByElEQVR42u3cUW6DMBAFQO5/6fYCwXnPtiKBx1+JEmCKxHq96/T6e+q4yMnJycnJycnJycnJyd8iv76P28NuX30689LVyMmPlt8/1B8+DYDpsemn5OTk97Fgoze9Gjk5+YT8Vjmey8nJyX8XW8YzeBp5yMnJd+bnqXflK+Tk5LM1ro2vflydIyd/sjxu1QyjzO2Fx6KfdLjIyZ8sT1fBafKdrsODiEJOTv7lb6hasv2NSWMQOfmx8mBN29ee0yZumhaQkx8rr2b15SLZuDNMTk4+MecnZeLm2Ikcgpz8aPk4mKw0i8ar6vjGkJOfKq9y8bTi3O+G2pS3kJO/TR7k4tXepjSFrxpI5OTHytOqcYXpfz5ATk4ex5Zqyq7CSrBjg5ycPD512kWaLDFvz8/Jyd8rD7YwVUvr4ARxgk9OTh489+mGqaAU3ZW2yclPlaejbxul+5LX+0Tk5O+VV79kC95WTeH4JpCTHy2vitKTqUK6cicnJ48bQ1UsCHY+VRVscnLyTfJ008RkKZqcnHz2vxRObmTcmZ+Tk58gX87ex4FjsrxFTk5+VQ9/uqE/neSX8nNy8pfLHzHIycnJycnJycnJycnJnzj+ATnf0jtEQEXdAAAAAElFTkSuQmCC"
}
},
"nextAutoSyncAt": null
}
```
Como retornamos a imagem em base64, você precisará renderizá-la para que o cliente possa escaneá-la. Assim que o usuário escanear com sucesso o login QR com seu aplicativo móvel, o fluxo de login continuará normalmente.
Tenha em mente que o código QR expira em 5 segundos, e as informações do Item serão atualizadas com um novo código QR. Assim, você precisará consultar o endpoint "Specific Item" para verificar atualizações no código. Dada a muito curta duração de expiração, é fácil renderizar um código QR expirado. Portanto, recomendamos consultar a cada 1 segundo até que o status do Item mude.
### XP Wealth
Este conector também permite que você especifique quais clientes deseja coletar dados financeiros. Para isso, você precisa enviar uma credencial `selectedCustomers` com todos os códigos de clientes que deseja conectar, separados por vírgulas.
```json
{
"connectorId": 248,
"parameters": {
"clientId": "clientId",
"clientSecret": "clientSecret",
"selectedCustomers": "409185,551175,176189"
},
"webhookUrl": "https://www.myapi.com/notifications"
}
```
Essa personalização não está disponível em nosso widget; você precisa criar o Item usando a API Pluggy.
### Mercado Bitcoin
Este conector requer a criação de uma Chave de API na conta da instituição. Para fazer isso, siga [este tutorial](https://suporte.mercadobitcoin.com.br/hc/pt-br/articles/360040781391-Como-gerar-uma-chave-de-API). Depois disso, use o client id e client secret para criar um Item.
## Conectores com OAuth
Conexões OAuth exigem que o usuário forneça autorização diretamente dentro do aplicativo da Instituição Financeira, portanto, há um fluxo de redirecionamento que precisa acontecer entre a Pluggy e a IF, de volta e para frente.
### OAuth v1
A primeira implementação que a Pluggy forneceu retorna um `oauthUrl` no endpoint [List Connectors](/reference/connectors-list) que é necessário para redirecionar o usuário para fornecer consentimento.
```json
{
"id": 206,
"name": "Mercado Pago",
"oauthUrl": "https://auth.mercadopago.com.br/authorization?client_id=3960514748228649&redirect_uri=https://api.pluggy.ai/connectors/206/oauth/callback&response_type=code&platform_id=mp&scopes=read,offline_access&state=27364b4a-354e-479d-89bd-05cef476e1f4"
}
```
Se o conector fornecer o `oauthUrl`, você será obrigado a redirecionar o usuário para essa página, e após ele autorizar a Pluggy, nós o redirecionaremos de volta para sua aplicação.
Isso afeta os conectores: "MercadoPago".
### OAuth v2
Após melhorar o fluxo da versão anterior, lançamos a integração diretamente através do Item, para fornecer melhor rastreamento das tentativas de conexão para nossos clientes. Agora os conectores não retornam a URL; em vez disso, eles não exigem nenhuma credencial para iniciar a execução e têm uma flag `oauth` para indicar que esses conectores se autenticam através do OAuth.
```json
{
"id": 200,
"name": "MeuPluggy",
"credentials": [],
"oauth": true
}
```
Uma vez que a execução tenha começado, forneceremos o `oauthUrl` como um parâmetro para que o usuário seja redirecionado. A URL pode não estar na resposta do `POST /items`; pode levar alguns segundos a mais para aparecer, então consulte [GET /items/\{id\}](/reference/items-retrieve) até que o parâmetro do item do tipo `oauth` a carregue:
```json
{
"id": "54a8d5e2-583a-40fd-a716-c9cee38a73dc",
"parameter": {
"label": "Oauth Code",
"name": "oauthCode",
"type": "oauth",
"instructions": "Faça login na página MeuPluggy para continuar",
"data": "https://?response_type=code&redirect_uri=https://api.pluggy.ai/items/oauth/callback&state=4eb2909b-c4c5-4f68-ba2b-84f2772fb15a",
"expiresAt": "2023-03-09T11:02:54.796Z"
}
}
```
O tipo do parâmetro `oauth` facilita entender que um fluxo OAuth é necessário, e o atributo `data` retorna a URL para redirecionar o usuário. Após o callback, o Item será criado.
Nas atualizações, o fluxo será o mesmo.
## Tutoriais
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials.md
Obtenha guias passo a passo sobre como conectar sua conta com instituições financeiras específicas.
### Caixa
- [Tutorial Caixa PF (Mobile)](/docs/developer-tools/tutorials/caixa-pf-mobile)
- [Tutorial Caixa PF (Web)](/docs/developer-tools/tutorials/caixa-pf-web)
- [Tutorial Caixa PJ](/docs/developer-tools/tutorials/caixa-pj)
### Inter
- [Tutorial Banco Inter MEI](/docs/developer-tools/tutorials/inter-mei)
- [Tutorial Banco Inter Empresas](/docs/developer-tools/tutorials/inter-pj)
### Sicredi
- [Tutorial Sicredi](/docs/developer-tools/tutorials/sicredi)
### Sicoob
- [Tutorial Sicoob PJ](/docs/developer-tools/tutorials/sicoob-pj)
### Santander
- [Como criar um usuário secundário para conectar uma conta Santander PJ](/docs/developer-tools/tutorials/santander-pj-secondary-user)
- [Tutorial Santander PJ](/docs/developer-tools/tutorials/santander-pj)
### Itaú
- [Tutorial Itaú PJ](/docs/developer-tools/tutorials/itau-pj)
- [Como criar um usuário sem token no Itaú Empresas](/docs/developer-tools/tutorials/itau-pj-user-without-token)
### Banco do Brasil
- [Tutorial Banco do Brasil PJ — autorização de dispositivo](/docs/developer-tools/tutorials/bb-pj-device-authorization)
- [Tutorial Banco do Brasil PJ](/docs/developer-tools/tutorials/bb-pj)
### Bradesco
- [Tutorial Bradesco Empresas — como habilitar o acesso ao aplicativo móvel](/docs/developer-tools/tutorials/bradesco-pj-mobile-access)
- [Tutorial Bradesco Empresas](/docs/developer-tools/tutorials/bradesco-pj)
- [Tutorial de Integração Open Finance Bradesco PF](/docs/developer-tools/tutorials/bradesco-pf-of)
### Efí Bank
- [Tutorial Efí Bank](/docs/developer-tools/tutorials/efi-pj)
## SDKs do Lado do Servidor
Source: https://docs.pluggy.ai/pt/docs/developer-tools/server-sdks.md
## SDKs do Lado do Servidor
Atualmente, temos bibliotecas de cliente disponíveis para as seguintes linguagens:
- [Node.js](https://github.com/pluggyai/pluggy-node)
- [.NET](https://github.com/pluggyai/pluggy-net)
- [Java](https://github.com/pluggyai/pluggy-java)
### Instalação
Para instalar a biblioteca de cliente, use o seguinte comando:
**Node.js (npm):**
```bash
npm install --save pluggy-sdk
```
**C# (.NET):**
```powershell
Install-Package Pluggy.SDK
```
**Java (Maven):**
Para instalar em Java, usando Maven, adicione uma dependência ao seu `pom.xml`:
```xml
ai.pluggypluggy-java1.5.0
```
Atualmente, o pacote está disponível no GitHub Packages, então certifique-se de ter a configuração do servidor GH Packages com seu Token de Acesso Pessoal do GH no seu arquivo `.m2/settings.xml`. Navegue até [este guia](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) para mais detalhes.
Você também pode fazer uma integração você mesmo, enviando requisições HTTP diretamente para nossa API.
Deixe-nos saber se você precisa ou se está interessado em contribuir com uma biblioteca para uma linguagem não representada aqui! Escreva para nós em hello@pluggy.ai
### Você também pode construir a sua própria!
Usando nosso `oas.json`, que está atualizado com todas as definições de endpoint mais recentes, você pode criar sua própria integração. Você pode conferir nosso OAS (Open API Specification) [aqui](https://api.pluggy.ai/oas3.json).
Alguns exemplos são impulsionados pela comunidade:
- [Python](https://github.com/diraol/pluggy-python)
## Integrações sem código
Source: https://docs.pluggy.ai/pt/docs/developer-tools/no-code.md
## Integrações sem Código
Aqui está uma lista de integrações que não requerem nenhum desenvolvimento para começar a usar o Pluggy.
- [Integrar com serviços no-code do Bubble](/docs/en/developer-tools/bubble)
## Bolha
Source: https://docs.pluggy.ai/pt/docs/developer-tools/bubble.md
## Guia Passo a Passo para Integrar o Pluggy Connect em uma Aplicação Bubble
### Pré-requisitos
- **Aplicação Bubble:** Certifique-se de que você tenha uma aplicação Bubble configurada.
- **Acesso à API Pluggy:** Você deve ter acesso à API Pluggy com as credenciais necessárias.
### Passo 1: Incluir o Script do Pluggy Connect
Primeiro, você precisa incluir a biblioteca JavaScript do Pluggy Connect em sua aplicação Bubble.
```html
```
Especifique os valores necessários no objeto window. Adicione o seguinte script ao cabeçalho HTML ou em um elemento HTML na sua página Bubble:
```html
```
- **Lista de Botões:** O array `buttons` deve conter uma entrada para cada botão em sua aplicação que aciona o Pluggy Connect. Se um valor `updateItem` for fornecido, o widget será aberto em "modo de atualização" para atualizar o item especificado. Caso contrário, ele abrirá o fluxo de conexão padrão.
- **Endpoint POST para Token:** O `connectTokenUrl` deve ser um endpoint POST que retorna o token de acesso no seguinte formato:
A resposta deve ser um objeto como o seguinte:
```json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### Passo 2: Criar o Endpoint do Connect Token
Sua aplicação deve ter um endpoint POST para gerar o token de conexão. Aqui está um exemplo de como você pode configurar esse endpoint usando Express.js:
```javascript
import express from 'express'
import cors from 'cors'
const app = express()
// Habilitar CORS para todas as rotas e todas as origens
app.use(
cors({
origin: '*',
})
)
app.use(express.json()) // para analisar corpos JSON
// criar uma rota para o endpoint do token
app.post('/my-connect-token-endpoint', async (req, res) => {
console.log('Recebido pedido para o endpoint /my-connect-token-endpoint')
const { itemId, clientUserId } = req.body
console.log('itemId:', itemId)
console.log('clientUserId:', clientUserId)
try {
const apiKeyResponse = await fetch('https://api.pluggy.ai/auth', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
clientId: process.env.PLUGGY_CLIENT_ID,
clientSecret: process.env.PLUGGY_CLIENT_SECRET,
}),
}).then((res) => res.json())
console.log('PluggyClient inicializado', apiKeyResponse)
const data = await fetch('https://api.pluggy.ai/connect_token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-KEY': apiKeyResponse.apiKey,
},
body: JSON.stringify({
itemId,
...(clientUserId ? { options: { clientUserId } } : {}),
}),
}).then((res) => res.json())
console.log('Token de conexão criado com sucesso:', data)
res.json({
accessToken: data.accessToken,
})
} catch (error) {
console.error('Erro em /my-connect-token-endpoint:', error)
res.status(500).json({ error: 'Erro interno do servidor' })
}
})
// iniciar o servidor
app.listen(3000, () => {
console.log('Servidor está rodando na porta 3000')
})
```
**Explicação:**
- Este código configura um servidor Express com um endpoint POST em `/my-connect-token-endpoint`.
- O servidor recebe `itemId` e `clientUserId` do corpo da requisição e os utiliza para solicitar um token de conexão da API do Pluggy.
- Se `itemId` for fornecido, ele atualizará o item existente. Se `clientUserId` for fornecido, ele associará o token ao usuário especificado.
### Passo 3: Injetar o JavaScript Principal
Inclua o JavaScript principal fornecido para gerenciar o widget do Pluggy Connect:
```html
```
### Passo 4: Adicionar um Botão à Sua Página Bubble
Crie um botão em sua aplicação Bubble e atribua a ele o nome da classe especificado em `window.pluggy.buttonClassName`.
```html
```
### Opções de Personalização
- **Modo Sandbox:** Se você quiser incluir o modo sandbox para testes, defina `includeSandbox` como `true` no objeto `window.pluggy`.
- **Tema:** Você pode personalizar o tema do widget do Pluggy Connect definindo a propriedade `theme`.
- **IDs de Produtos e Conectores:** Você pode especificar quais produtos e conectores incluir definindo as propriedades `products` e `connectorIds`.
### Tratamento de Erros
A função `openPluggyConnect` inclui um callback `onError` onde você pode implementar sua lógica para lidar com erros durante o processo de conexão.
### Testes
Certifique-se de que seu endpoint `connectTokenUrl` esteja configurado corretamente para retornar o token de acesso e que o `clientUserId` esteja sendo passado corretamente.
Este guia fornece uma maneira estruturada de integrar e personalizar o widget do Pluggy Connect dentro de sua aplicação Bubble. Ajuste os valores conforme as necessidades de sua aplicação e teste minuciosamente para garantir uma integração adequada.
## Códigos de Erro
Source: https://docs.pluggy.ai/pt/docs/developer-tools/error-codes.md
## Códigos de Erros
Os seguintes erros descrevem de forma geral o que você receberá para os diferentes endpoints disponíveis na Referência da API Pluggy.
| Código de Erro | Significado |
|----------------|-------------|
| 400 | Solicitação Inválida -- Sua solicitação é inválida. |
| 401 | Não Autorizado -- Sua chave da API está errada. |
| 403 | Proibido -- O recurso que você está tentando acessar, você não tem permissões. |
| 404 | Não Encontrado -- O recurso especificado não pôde ser encontrado. |
| 405 | Método Não Permitido -- O endpoint específico não suporta esse método. |
| 406 | Não Aceitável -- Você solicitou um formato que não é JSON. |
| 409 | Conflito -- A solicitação não pôde ser concluída devido a um conflito com o estado atual do recurso de destino. |
| 429 | Muitas Solicitações -- Você excedeu seu limite de cota. |
| 500 | Erro Interno do Servidor -- Tivemos um problema com nosso servidor. Tente novamente mais tarde. |
| 503 | Serviço Indisponível -- Estamos temporariamente offline para manutenção. Por favor, tente novamente mais tarde. |
## Limites de taxa
Source: https://docs.pluggy.ai/pt/docs/developer-tools/rate-limits.md
## Limites de taxa
A API da Pluggy implementa um limitador de taxa para maximizar sua estabilidade ao lidar com grandes picos de solicitações recebidas. O limitador de taxa mantém um contador da quantidade de solicitações que você fez a um determinado endpoint em um minuto a partir do mesmo IP, e se exceder a quantidade máxima permitida, retorna um erro 429.
### Limites de taxa por endpoint
Os seguintes limites de taxa se aplicam na API da Pluggy:
| Endpoint | Máx. solicitações por minuto por IP |
|----------|------------------------------------|
| `POST /auth` | 360 |
| `GET /accounts` ou `GET /accounts/{id}` | 360 |
| `GET /transactions` ou `GET /transactions/{id}` | 360 |
| `GET /investments` ou `GET /investments/{id}` | 360 |
| `GET /investments/{id}/transactions` | 360 |
| `PATCH /items` | 20 |
`PATCH /items` é limitado a 20 solicitações por minuto. Isso é destinado a atualizações acionadas pelo usuário. Se você precisar de atualizações de itens diariamente, deve usar nosso recurso de auto-sync.
Cada limite é aplicado independentemente dos outros, por exemplo, você pode atingir o limite em `POST /auth`, mas ainda conseguir usar `GET /transactions`. Se um limite abranger mais de um endpoint, as solicitações para qualquer um dos endpoints contam para o limite.
### Tratando erros de limitação de taxa
Quando você excede o número máximo de solicitações por minuto para um endpoint, você receberá um erro `429 Too Many Requests`:
```json
{
"message": "Too many requests. Please try again later (see Retry-After header in seconds)",
"code": 429
}
```
Qualquer solicitação subsequente falhará com o mesmo erro até que o contador do limitador de taxa seja redefinido, após um minuto.
Informações mais precisas são fornecidas nos cabeçalhos de resposta:
```json
{
"RateLimit-Limit": "360",
"RateLimit-Reset": "45",
"Retry-After": "60"
}
```
- **RateLimit-Limit:** O número máximo de solicitações por minuto para este endpoint.
- **RateLimit-Reset:** Quantos segundos restam até que o limite seja redefinido e você possa solicitar o endpoint novamente.
- **Retry-After:** Campo padrão para o comportamento de retry do cliente HTTP. Sempre retorna 60.
Ao ler esses cabeçalhos, você pode lidar com esse cenário aguardando `RateLimit-Reset` segundos e tentando novamente a solicitação.
Alguns clientes HTTP como [got](https://github.com/sindresorhus/got) vêm com um comportamento de retry padrão que lê o cabeçalho `Retry-After` quando recebem uma resposta 429 e espera esse número de segundos para tentar novamente, o que também funciona.
### Eu continuo atingindo o limite!
Se você estiver atingindo repetidamente o limite de taxa para um endpoint, certifique-se de verificar o seguinte:
- Se você estiver fazendo algum tipo de processo em lote, certifique-se de que não tenha muitas invocações paralelas do mesmo endpoint e tente adicionar esperas entre cada chamada para evitar sobrecarregar a API muito rapidamente.
- Se você atingir o limite durante a operação normal de seu aplicativo, certifique-se de que não está duplicando solicitações por engano e que está reutilizando corretamente as chaves da API entre as chamadas (para evitar atingir o limite de `/auth`).
- Se você ainda precisar de uma taxa de invocação mais alta do que permitimos para o funcionamento do seu aplicativo, entre em contato com nossa equipe de suporte para resolver seu caso específico.
## Página de Status da API
Source: https://docs.pluggy.ai/pt/docs/developer-tools/status-page-api.md
## Visão Geral
A página de status da Pluggy em [status.pluggy.ai](https://status.pluggy.ai) mostra a saúde ao vivo de cada conector, produto de pagamento e componente de infraestrutura, além do histórico de incidentes. Tudo que a página renderiza é JSON público que você pode consumir diretamente — sem autenticação necessária, sem chave de API.
Três endpoints, do maior para o menor:
| Endpoint | Use-o quando |
| --- | --- |
| [`/api/status`](#the-snapshot-endpoint) | Você quer tudo: conectores, 90 dias de histórico, cada incidente com sua linha do tempo |
| [`/api/connectors-incidents`](#active-incidents-by-connector) | Você só quer o que está quebrado agora, identificado pelo id do conector |
| [`/api/summary`](#embeddable-widget) | Você só quer um status geral, para um badge ou um check de saúde |
Se você já chama `GET /connectors`, pode não precisar de nenhum deles — veja [Sobre o objeto conector](#on-the-connector-object).
Se você só quer notificações, não precisa desta API: inscreva-se por e-mail na página de status, adicione o aplicativo **Pluggy Status** no Slack a um canal, ou use o [feed RSS](https://status.pluggy.ai/rss).
## O endpoint de snapshot
```
GET https://status.pluggy.ai/api/status
```
- **Sem autenticação.** CORS está aberto, então você pode chamá-lo de um aplicativo de navegador.
- **Cache por ~30 segundos.** Faça polling a cada 60 segundos ou mais lento — polling mais rápido apenas lê novamente o cache.
A resposta contém quatro coleções:
| Campo | O que contém |
| --- | --- |
| `institutions` | Cada conector com seu status atual, histórico de 90 dias e flags de suporte a produtos |
| `incidents` | Incidentes abertos e tudo resolvido nos últimos 90 dias, com suas linhas do tempo de atualização |
| `components` | Componentes de infraestrutura (API, Webhooks, Connect Widget, …) e seu status atual |
| `productStatus` | Sobrescritas manuais de status por instituição para produtos de pagamento |
## Instituições
```json
{
"pluggy_id": "601",
"name": "Itaú",
"type": "PERSONAL_BANK",
"logo_url": "https://cdn.pluggy.ai/assets/connector-icons/201.svg",
"status": "online",
"bars": "ooooooo…dxo",
"uptime": 99.51,
"supports_data": true,
"supports_pis": true,
"supports_pis_scheduled": true,
"supports_pix_auto": true,
"supports_smart_transfer": true
}
```
- `pluggy_id` é o mesmo `id` do conector que você usa em todos os outros lugares na API da Pluggy — faça a correspondência diretamente.
- `status` é um dos `online`, `degraded`, `offline`, `maintenance`.
- `bars` codifica os últimos 90 dias como um caractere por dia, do mais antigo para o mais recente: `o` online, `d` degradado, `p` interrupção parcial, `x` offline, `m` manutenção.
- `uptime` é uma porcentagem ponderada de 90 dias (dias degradados contam 25% de inatividade, parcial 50%, offline 100%).
- As flags `supports_*` informam quais produtos a instituição oferece (dados, iniciação de pagamento, pagamentos agendados, PIX automático, transferências inteligentes).
**Exemplo — ver a saúde de um conector:**
```bash
curl -s https://status.pluggy.ai/api/status \
| jq '.institutions[] | select(.pluggy_id == "601") | {name, status, uptime}'
```
## Incidentes
```json
{
"id": "4a8f1e80-…",
"kind": "incident",
"product": "pis",
"pluggy_id": "612",
"institution_name": "PagBank",
"severity": "degraded",
"state": "identified",
"apis": ["Criação de pagamento"],
"started_at": "2026-07-07T14:28:21Z",
"resolved_at": null,
"postmortem": null,
"updates": [{ "state": "identified", "body": "…", "created_at": "…" }]
}
```
- Um incidente está **aberto** enquanto `state != "resolved"`.
- `product` é um dos `dados`, `pis`, `pis-agendado`, `pixauto`, `smart`, `infra` (incidentes legados podem ter `pagamentos`, que mapeia para `pis`).
- `kind` é `incident` ou `maintenance`; manutenções têm `window_starts_at` / `window_ends_at`.
- Incidentes específicos de conectores incluem `pluggy_id`, para que você possa juntá-los à sua própria lista de conectores.
- Cada incidente tem uma página compartilhável em `https://status.pluggy.ai/incident/`.
**Exemplo — incidentes abertos que afetam um conector que você usa:**
```bash
curl -s https://status.pluggy.ai/api/status \
| jq '.incidents[] | select(.state != "resolved" and .pluggy_id == "612") | {title, state, severity}'
```
## Incidentes ativos por conector
O snapshot carrega tudo, o que o torna grande. Se tudo que você quer é "o que está errado com cada conector agora" — para sinalizar um banco afetado na sua própria tela de seleção de conectores antes que um usuário o escolha — faça polling disso em vez disso. É alguns kilobytes em vez de algumas centenas, porque não carrega histórico, incidentes resolvidos e linhas do tempo.
```
GET https://status.pluggy.ai/api/connectors-incidents
```
```json
{
"generatedAt": "2026-09-05T10:11:25.059Z",
"connectors": {
"602": [
{
"id": "78624c2c-bf55-466a-ba99-6b57e9bd9223",
"title": "XP Banking - Compras parceladas não sendo retornadas",
"description": null,
"type": "TRANSACTIONS_INSTALLMENTS_ISSUE",
"product": "dados",
"kind": "INCIDENT",
"severity": "DEGRADED",
"state": "IDENTIFIED",
"startedAt": "2026-07-23T13:40:41Z",
"updatedAt": "2026-08-18T16:30:09Z",
"url": "https://status.pluggy.ai/incident/78624c2c-bf55-466a-ba99-6b57e9bd9223"
}
]
}
}
```
As chaves são o mesmo `id` do conector que você obtém de `GET https://api.pluggy.ai/connectors`, então a junção é uma busca. Apenas conectores com pelo menos um incidente ativo aparecem, e cada lista é ordenada do pior para o melhor.
**Apenas incidentes que afetam um conector *neste momento* são listados.** Uma manutenção agendada é publicada dias antes, mas aparece aqui apenas uma vez que sua janela se abre, e desaparece quando se fecha. Um incidente que afeta várias instituições aparece sob cada um de seus ids de conector. Incidentes de infraestrutura não pertencem a nenhum conector e não são listados aqui — use o snapshot para esses.
### O campo `type`
`severity` diz quão grave é e `state` diz quão avançados estamos. `type` diz **o que está quebrado**, que é a parte que você não pode inferir de mais nada:
| Grupo | Valores |
| --- | --- |
| Disponibilidade | `CONNECTOR_UNAVAILABLE`, `CONNECTOR_DEGRADED`, `INSTITUTION_OUTAGE`, `SCHEDULED_MAINTENANCE` |
| Ciclo de vida da conexão | `CONSENT_ERROR`, `CONNECTION_NOT_UPDATING`, `PARTIAL_SUCCESS` |
| Qualidade dos dados | `ACCOUNTS_MISSING`, `BALANCE_INCORRECT`, `TRANSACTIONS_MISSING`, `TRANSACTIONS_INCORRECT`, `TRANSACTIONS_INSTALLMENTS_ISSUE`, `INVESTMENTS_MISSING`, `INVESTMENTS_INCORRECT`, `IDENTITY_MISSING`, `HISTORICAL_DATA_MISSING` |
| Plataforma Pluggy | `WEBHOOK_DELAY`, `PAYMENT_FAILURE` |
| Não classificado | `OTHER` |
Use-o para agrupar o mesmo problema entre instituições e para decidir quais incidentes valem a pena serem apresentados a um usuário: uma `SCHEDULED_MAINTENANCE` e um `TRANSACTIONS_MISSING` ambos são lidos como "degradado" de outra forma. `OTHER` significa que a Pluggy não classificou o incidente, não que nada está errado.
## Sobre o objeto conector
Você não precisa chamar a API de status. Os mesmos incidentes estão no objeto `health` de cada conector retornado por [`GET /connectors`](/reference/connector/connectors-list), então uma listagem que você já faz os carrega:
```json
{
"id": 602,
"name": "XP Banking",
"health": {
"status": "ONLINE",
"stage": null,
"incidents": [
{
"title": "XP Banking - Compras parceladas não sendo retornadas",
"type": "TRANSACTIONS_INSTALLMENTS_ISSUE",
"product": "dados",
"severity": "DEGRADED",
"state": "IDENTIFIED",
"url": "https://status.pluggy.ai/incident/78624c2c-…"
}
]
}
}
```
`health.incidents` está **ausente** quando o conector não tem incidente ativo, então sua presença é o sinal em si.
Note o `status: "ONLINE"` nesse exemplo. `health.status` responde *posso conectar de alguma forma*; `health.incidents` responde *o que está errado*. Um banco pode estar perfeitamente acessível e ainda assim não estar retornando parcelas, e apenas o segundo campo pode te dizer isso. Elas são perguntas diferentes — leia ambas.
`health.details` é uma terceira coisa, não relacionada: solicite com `?healthDetails=true` e descreve como **suas próprias** conexões com essa instituição têm se comportado, em vez da instituição em si.
## Widget embutido
Mostre o status ao vivo da Pluggy dentro do seu próprio aplicativo ou dashboard interno.
**Badge flutuante** — uma tag de script, renderiza uma pequena pílula (ponto de status + rótulo) no canto da página, vinculando à página de status. Atualiza a cada 60 segundos.
```html
```
- `data-lang`: `pt` (padrão), `es` ou `en`.
- `data-position`: `bottom-right` (padrão) ou `bottom-left`.
- `data-target`: um seletor CSS — renderiza o badge inline dentro desse elemento em vez de flutuar.
**Painel Iframe** — um painel compacto com status geral, componentes de infraestrutura e incidentes abertos:
```html
```
**Endpoint de resumo** — ambos são suportados por um pequeno resumo JSON que você também pode consumir diretamente (CORS aberto, cache ~30s). `\/api\/widget` serve o mesmo corpo e continua funcionando para embeds que já apontam para ele:
```
GET https://status.pluggy.ai/api/summary
```
```json
{
"status": "op",
"labels": { "pt": "…", "es": "…", "en": "Todos os sistemas operacionais" },
"openIncidents": 0,
"updatedAt": "2026-07-10T12:00:00.000Z"
}
```
`status` é `op` (operacional), `mn` (manutenção), `dg` (degradado), `pt` (interrupção parcial) ou `mj` (interrupção maior) — o pior entre conectores, produtos de pagamento e infraestrutura.
## Outros canais
| Canal | Como |
| --- | --- |
| Email | Inscreva-se na [página de status](https://status.pluggy.ai) — escolha produtos específicos ou tudo; opt-in duplo, cancelamento de inscrição com um clique |
| Slack | Instale o aplicativo **Pluggy Status** a partir do diálogo de inscrição da página, ou convide `@Pluggy Status` para um canal e ative-o |
| RSS | [`https://status.pluggy.ai/rss`](https://status.pluggy.ai/rss) — últimos 50 incidentes com suas linhas do tempo |
| Webhooks | Para mudanças de status de conectores que afetam **seus itens**, prefira os [webhooks padrão da Pluggy](/docs/developer-tools/webhooks-ref) (`connector/status_updated`) |
## Webhook
Source: https://docs.pluggy.ai/pt/docs/developer-tools/webhooks-ref.md
## Webhook
Neste guia, abordaremos os webhooks que são enviados pelo Pluggy para criar uma integração reativa a mudanças. Isso abrangerá tanto integrações de dados quanto de pagamentos.
Um Webhook é uma ferramenta que permite que você receba uma notificação para um determinado evento. Ele permite que você configure uma URL HTTPS em nossa plataforma para certos eventos, e você receberá um evento JSON POST nessa URL, com dados específicos do evento.
Para se inscrever em eventos de Webhook, você pode:
- Criar uma instância de Webhook diretamente, ou
- Especificar o parâmetro `webhookUrl` (com uma URL HTTPS válida), ao:
- criar um Item,
- criar um Connect Token, ou
- criar uma Solicitação de Pagamento
Se você criar uma instância de Webhook diretamente, estará se inscrevendo para todos os casos de eventos do tipo de evento especificado. Em vez disso, se você fizer isso especificando o `webhookUrl` ao criar um Item ou criar um Connect Token, você será notificado sobre todos os eventos, mas apenas relacionados a esse recurso específico. Ou seja, seja para aquele Item especificamente, ou para o(s) item(ns) relacionados criados usando aquele Connect Token.
## Eventos de Dados
Suportamos o registro para os seguintes eventos ao consumir os endpoints de dados do Pluggy.
| Evento | Descrição |
|-------|-------------|
| `item/created` | Um item foi criado e terminou de se conectar com sucesso. |
| `item/updated` | Um item foi atualizado e sincronizado com sucesso. |
| `item/deleted` | Um item foi excluído com sucesso. |
| `item/error` | Um item encontrou erros em sua execução. O caso de `USER_AUTHORIZATION_PENDING` também acionará este evento. |
| `item/waiting_user_input` | Um item está bloqueado aguardando a entrada do usuário para continuar. |
| `item/waiting_user_action` | Um item está bloqueado aguardando que o usuário aprove uma ação em seu dispositivo (por exemplo, autorizar acesso no aplicativo bancário ou escanear um código QR). |
| `item/login_succeeded` | Um item fez login com sucesso no provedor e está coletando os dados. |
| `connector/status_updated` | Um conector mudou de status (`ONLINE`/`UNSTABLE`/`OFFLINE`). Este evento informa o ID do conector afetado e o status atualizado. Verifique o endpoint de Conectores para ver todos os conectores e seus IDs. |
| `transactions/deleted` | IDs de transações excluídas após mesclar dados na atualização do item. |
| `transactions/created` | Receba este evento de webhook e use a página `createdTransactionsLink` para acessar todas as transações disponíveis e inseri-las em sua fonte de dados. |
| `transactions/updated` | IDs de transações atualizadas após mesclar dados na atualização do item. Após receber este webhook, é recomendável obter os dados completos das transações usando o endpoint de transações com o parâmetro `ids`. |
Os webhooks de transações são acionados apenas quando há uma mudança de dados. Se não houver transações, não será acionado um evento `transactions/created`.
## Eventos de Pagamento
Suportamos o registro para os seguintes eventos ao consumir os endpoints de pagamento do Pluggy.
### Intenção de Pagamento
| Evento | Descrição |
|-------|-------------|
| `payment_intent/created` | ID da intenção de pagamento criada pelo usuário, com `paymentRequestId`. |
| `payment_intent/completed` | ID da intenção de pagamento concluída com sucesso pelo usuário, com `paymentRequestId`. |
| `payment_intent/waiting_payer_authorization` | ID da intenção de pagamento quando precisa de autorização adicional. |
| `payment_intent/error` | ID da intenção de pagamento quando ocorre um erro durante o fluxo, com `paymentRequestId`. |
| `payment_request/updated` | O status da solicitação de pagamento foi alterado. |
### Pagamento Agendado
| Evento | Descrição |
|-------|-------------|
| `scheduled_payment/created` | IDs da autorização de pagamento agendado. |
| `scheduled_payment/completed` | Um pagamento único da autorização foi realizado. |
| `scheduled_payment/error` | Pagamento não concluído, finalizado com erro. |
| `scheduled_payment/canceled` | Pagamento cancelado pelo usuário ou pelo cliente. |
### Pagamento Automático PIX
| Evento | Descrição |
|-------|-------------|
| `automatic_pix_payment/created` | Um pagamento foi agendado para uma solicitação de pagamento automático PIX. |
| `automatic_pix_payment/completed` | Um pagamento agendado associado a uma solicitação de pagamento automático PIX foi concluído com sucesso. |
| `automatic_pix_payment/error` | Um pagamento agendado associado a uma solicitação de pagamento automático PIX terminou com erro. |
| `automatic_pix_payment/canceled` | Um pagamento agendado associado a uma solicitação de pagamento automático PIX foi cancelado. |
### Transferência Inteligente
| Evento | Descrição |
|-------|-------------|
| `smart_transfer_preauthorization/completed` | Uma pré-autorização de transferência inteligente foi aprovada por um usuário. |
| `smart_transfer_preauthorization/error` | Ocorreu um erro durante a aprovação da pré-autorização de transferência inteligente. Por exemplo, quando o usuário rejeita o consentimento. |
| `smart_transfer_payment/completed` | Um pagamento de transferência inteligente foi concluído. |
| `smart_transfer_payment/error` | Ocorreu um erro ao liquidar o pagamento de transferência inteligente. Por exemplo, quando a conta não tem saldo suficiente. |
### PIX por biometria
Os pagamentos PIX por biometria enviam os eventos de [Intenção de Pagamento](#payment-intent). Estes relatam as contas vinculadas do pagador (veja [Gerenciando contas vinculadas](/docs/payments/pix-biometric-enrollments)).
| Evento | Descrição |
|-------|-------------|
| `pix_biometric_enrollment/authorized` | O pagador concluiu a vinculação de uma conta. |
| `pix_biometric_enrollment/revoked` | Uma conta vinculada foi revogada, no banco ou através da API. |
| `pix_biometric_enrollment/error` | A vinculação não foi concluída: foi rejeitada ou terminou antes que o pagador a finalizasse. |
Para se registrar em um evento específico, você terá que enviar o evento desejado para ouvir apenas aqueles eventos de webhook.
Alternativamente, você pode apenas usar a opção `all` para receber todos os eventos associados.
Aceitamos apenas URLs HTTPS. URLs localhost não são permitidas; você terá que fornecer uma URL HTTPS usando ngrok ou outras ferramentas para fornecer URLs públicas e seguras.
Para testar essa funcionalidade, você pode usar [RequestCatcher](https://requestcatcher.com), que é uma ferramenta que apenas receberá nossa notificação e mostrará o payload. Você pode facilmente criar um catcher com apenas um nome em segundos.
## Parâmetros do Payload
Ao fazer a solicitação POST, todos os webhooks enviarão os seguintes parâmetros em formato JSON:
- **event:** nome do evento (`item/created`, `item/updated`, `item/error`, etc.)
- **eventId:** identificador do evento em si. Deve ser o mesmo para um evento quando enviado para muitos endpoints.
- **triggeredBy:** quem acionou o evento (para todos os eventos, exceto `item/deleted`, `connector/status_updated` e `transactions/deleted`). Valores possíveis:
- `USER`: um usuário final acionou o evento com um Connect Token (por exemplo, do Pluggy Connect)
- `CLIENT`: um cliente acionou o evento com uma API Key (por exemplo, executando PATCH em um Item)
- `SYNC`: Auto-sync acionou o evento
- `INTERNAL`: Foi acionado por alguém da equipe de suporte do Pluggy
Dependendo do tipo de evento, o ID da entidade é enviado. Por exemplo, para itens, `itemId`. Em transações, `transactionIds`, e em conectores, `connectorId`.
### `clientUserId` é enviado apenas em eventos `item/*`
`clientUserId` -- o identificador que você definiu ao [criar o Connect Token](/docs/authentication) -- está incluído no payload de **cada evento `item/*`**: `item/created`, `item/updated`, `item/error`, `item/deleted`, `item/login_succeeded`, `item/waiting_user_input` e `item/waiting_user_action`.
Não está **incluído** em eventos `transactions/*`. Esses payloads carregam `itemId`, `accountId` e os campos da transação, mas não `clientUserId`. Para atribuir um evento de transação a um usuário final, mantenha seu próprio mapeamento `itemId` -> usuário (que você já possui do evento `item/created` ou do callback `onSuccess` do widget) e resolva a partir de `itemId`.
A causa usual é que foi enviado na **raiz** do corpo do `POST /connect_token` em vez de dentro de `options`. A API descarta propriedades desconhecidas da raiz e ainda retorna `200`, então o valor nunca chega ao Item. Veja [Configurando um Connect Token](/docs/authentication). Você pode preencher os Itens afetados com [PATCH /items/{id}](/reference/items-update).
### Exemplos de Item
**item/created:**
```json
{
"event": "item/created",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"triggeredBy": "USER",
"clientUserId": "client-user-id"
}
```
**item/updated:**
```json
{
"event": "item/updated",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"triggeredBy": "USER",
"clientUserId": "client-user-id"
}
```
**item/deleted:**
```json
{
"event": "item/deleted",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"triggeredBy": "USER",
"clientUserId": "client-user-id"
}
```
**item/error:**
```json
{
"event": "item/error",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "d161a74a-8bc8-4093-88de-724312969b0d",
"error": {
"code": "USER_INPUT_TIMEOUT",
"message": "A entrada solicitada pelo usuário expirou",
"parameter": "token"
},
"triggeredBy": "USER",
"clientUserId": "client-user-id"
}
```
**item/waiting_user_input:**
```json
{
"event": "item/waiting_user_input",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
"triggeredBy": "USER",
"clientUserId": "client-user-id"
}
```
**item/waiting_user_action:**
```json
{
"event": "item/waiting_user_action",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
"triggeredBy": "USER",
"clientUserId": "client-user-id"
}
```
**item/login_succeeded:**
```json
{
"event": "item/login_succeeded",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"triggeredBy": "USER",
"clientUserId": "client-user-id"
}
```
### Exemplos de Conector
**connector/status_updated:**
```json
{
"id": "201",
"event": "connector/status_updated",
"eventId": "4552bee0-b87f-48b5-896b-c23113839319",
"connectorId": "201",
"data": {
"status": "UNSTABLE"
}
}
```
### Exemplos de Transação
**transactions/deleted:**
```json
{
"event": "transactions/deleted",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
"transactionIds": [
"5a14feae-eaa7-423a-820c-6b83837c35b7",
"786c7d98-6085-4879-9c7f-2255260e2436"
]
}
```
**transactions/updated:**
```json
{
"event": "transactions/updated",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
"transactionIds": [
"5a14feae-eaa7-423a-820c-6b83837c35b7",
"786c7d98-6085-4879-9c7f-2255260e2436"
]
}
```
**transactions/created:**
```json
{
"itemId": "de7bbf5a-abf2-47e4-94b1-586b36758423",
"event": "transactions/created",
"id": "de7bbf5a-abf2-47e4-94b1-586b36758423",
"eventId": "4e69d62d-b7c8-4f01-b591-a1d8a94710b9",
"accountId": "0d5a0de2-9c82-4ea2-af50-31643a632a33",
"transactionsCount": 332,
"transactionsMinDate": "2025-02-12T15:00:01.000Z",
"transactionsCreatedAtFrom": "2025-02-13T17:21:53.719Z",
"createdTransactionsLink": "https://api.pluggy.ai/transactions?accountId=0d5a0de2-9c82-4ea2-af50-31643a632a33&createdAtFrom=2025-02-13T17:21:53.719Z"
}
```
### Exemplos de Intenção de Pagamento
**payment_intent/created:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"paymentIntentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"event": "payment_intent/created",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0"
}
```
**payment_intent/completed:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"paymentIntentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"event": "payment_intent/completed",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"referenceId": "E33371172200009110200U70a27b2698"
}
```
**payment_intent/error:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"paymentIntentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"event": "payment_intent/error",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"referenceId": "E33371172200009110200U70a27b2698",
"error": {
"code": "REJECTED_BY_USER",
"description": "O consentimento foi rejeitado pelo usuário.",
"detail": "O usuário rejeitou a autorização do consentimento"
}
}
```
### Exemplos de Solicitação de Pagamento
**payment_request/updated:**
```json
{
"event": "payment_request/updated",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6",
"clientId": "client-123",
"status": "CANCELED"
}
```
### Exemplos de Pagamentos Agendados
**scheduled_payment/created:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "scheduled_payment/created"
}
```
**scheduled_payment/completed:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "scheduled_payment/completed"
}
```
**scheduled_payment/error:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "scheduled_payment/error",
"error": {
"title": "Título do erro",
"code": "Código do Erro",
"description": "Descrição do erro"
}
}
```
**scheduled_payment/canceled:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "scheduled_payment/canceled"
}
```
### Exemplos de Pagamentos Automáticos PIX
**automatic_pix_payment/created:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"endToEndId": "E37943755202506111319U0da92d1b7e",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "automatic_pix_payment/created"
}
```
**automatic_pix_payment/completed:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"endToEndId": "E37943755202506111319U0da92d1b7e",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "automatic_pix_payment/completed"
}
```
**automatic_pix_payment/error:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"endToEndId": "E37943755202506111319U0da92d1b7e",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "automatic_pix_payment/error",
"error": {
"title": "Título do erro",
"code": "Código do Erro",
"description": "Descrição do erro"
}
}
```
**automatic_pix_payment/canceled:**
```json
{
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
"automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
"endToEndId": "E37943755202506111319U0da92d1b7e",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "automatic_pix_payment/canceled"
}
```
### Exemplos de Transferências Inteligentes
**smart_transfer_preauthorization/completed:**
```json
{
"clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee8",
"event": "smart_transfer_preauthorization/completed",
"eventId": "8013240b-7c0a-409e-bf00-7fc586cc9196",
"smartTransferPreauthorizationId": "f84e6e06-e0f9-4ab3-89f2-da062be65e7c",
"status": "COMPLETED"
}
```
**smart_transfer_preauthorization/error:**
```json
{
"clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee8",
"event": "smart_transfer_preauthorization/error",
"eventId": "54ceeb25-b9f7-4b90-8124-0cff66d1b2c3",
"smartTransferPreauthorizationId": "3dd45002-52aa-44e8-a206-f6b99a293d9a",
"status": "REJECTED",
"error": {
"code": "REJECTED_BY_USER",
"description": "O consentimento foi rejeitado pelo usuário.",
"detail": "O usuário rejeitou a autorização do consentimento"
}
}
```
**smart_transfer_payment/completed:**
```json
{
"clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee8",
"event": "smart_transfer_payment/completed",
"eventId": "0dfa6e5d-aee4-42b6-bd3b-e27e9c591339",
"smartTransferPreauthorizationId": "f84e6e06-e0f9-4ab3-89f2-da062be65e73",
"smartTransferPaymentId": "2afc828e-0dc2-4195-a774-145f7d7fc46c",
"status": "PAYMENT_COMPLETED"
}
```
**smart_transfer_payment/error:**
```json
{
"clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee6",
"event": "smart_transfer_payment/error",
"eventId": "59ff7a4a-d804-499b-a31c-7865014ba0ef",
"smartTransferPreauthorizationId": "f84e6e06-e0f9-4ab3-89f2-da062be65e73",
"smartTransferPaymentId": "b546ab61-f1cd-4cd4-b5bf-0073d9a9ee3a",
"status": "PAYMENT_REJECTED",
"error": {
"code": "INSUFFICIENT_BALANCE",
"description": "A conta não tem saldo suficiente para realizar o pagamento.",
"detail": "Saldo insuficiente."
}
}
```
### Exemplos de PIX por biometria
**pix_biometric_enrollment/authorized:**
```json
{
"event": "pix_biometric_enrollment/authorized",
"eventId": "8013240b-7c0a-409e-bf00-7fc586cc9196",
"enrollmentId": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
"customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
"paymentRequestId": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e"
}
```
**pix_biometric_enrollment/revoked:**
```json
{
"event": "pix_biometric_enrollment/revoked",
"eventId": "54ceeb25-b9f7-4b90-8124-0cff66d1b2c3",
"enrollmentId": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
"customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
"paymentRequestId": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e"
}
```
**pix_biometric_enrollment/error:**
```json
{
"event": "pix_biometric_enrollment/error",
"eventId": "59ff7a4a-d804-499b-a31c-7865014ba0ef",
"enrollmentId": "3dd45002-52aa-44e8-a206-f6b99a293d9a",
"customerId": null,
"paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b"
}
```
`paymentRequestId` é a solicitação de pagamento onde o pagador criou o link. O evento não carrega status ou razão: recupere a matrícula com `GET /pix-biometric/enrollments/{id}` para obtê-los.
## Manipulando notificações
Quando enviamos uma notificação de webhook, uma de duas coisas acontece:
1. **Sua API responde com um status `2XX` dentro de 10 segundos** → sucesso
2. **Sua API responde com qualquer outro status, ou não responde dentro de 10 segundos** → falha
### Cronograma de Tentativas
Tentamos entregar cada webhook até **3 vezes**:
| Tentativa | Quando |
| --- | --- |
| 1ª | Imediatamente |
| 2ª | ~15 minutos após a 1ª tentativa falhar |
| 3ª | ~2 horas após a 2ª tentativa falhar |
Se a 3ª tentativa falhar, a notificação não será entregue novamente automaticamente.
### Respostas que não tentamos novamente
Algumas respostas nos dizem que a solicitação nunca terá sucesso como enviada. Nesses casos, paramos após a primeira tentativa e não agendamos novas tentativas:
`400` · `401` · `403` · `404` · `405`
Qualquer outro resultado não-2XX é tratado como temporário e recebe o cronograma completo de 3 tentativas acima, incluindo `408`, `429`, qualquer `5XX`, erros de conexão e timeouts.
Se seu endpoint responder `400` enquanto está **temporariamente** quebrado — um bug ao analisar o payload, um deploy que deixa seu manipulador rejeitando solicitações válidas — essas notificações são descartadas após uma única tentativa e não voltarão por conta própria. Retorne um `5XX` para problemas temporários ou inesperados do lado do servidor, e reserve `4XX` para solicitações que você nunca aceitará.
`item/waiting_user_input` e `item/login_succeeded` são sensíveis ao tempo: eles recebem 3 tentativas espaçadas em cerca de 6 minutos, e nunca usam o cronograma de 15 minutos / 2 horas. Após a 3ª tentativa, não são tentados novamente.
### Se todas as tentativas falharem
Você pode tentar uma notificação manualmente a partir do Dashboard. Uma tentativa manual inicia um novo ciclo de até 3 tentativas, com ~15 minutos de intervalo. A regra acima ainda se aplica: se seu endpoint continuar respondendo `400`, `401`, `403`, `404` ou `405`, a tentativa manual também para após uma tentativa — então conserte o endpoint primeiro, depois tente novamente.
### Respondendo a notificações
É obrigatório que sua API retorne 2XX logo após receber uma notificação e, em seguida, faça seu processamento após responder ao Pluggy. Dessa forma, se seu processamento levar mais de 10 segundos, não interpretaremos isso como uma falha, evitando assim tentativas indesejadas da mesma notificação.
Para todas as notificações de itens, esperamos que a primeira coisa que você faça ao processar o evento seja fazer um `GET /items/{id}` para recuperar as informações mais recentes relacionadas ao evento, em vez de processar a partir dos dados do payload do evento.
Se você deseja adicionar medidas de segurança extras para fornecer filtragem de IP para nossas solicitações, deve colocar na lista branca os seguintes IPs:
`52.67.145.81`
## Cabeçalhos do Webhook
Ao criar um webhook, você pode especificar um objeto `headers` para enviar cabeçalhos específicos em suas notificações de webhook. Isso pode ser útil, por exemplo, se sua URL de webhook estiver protegida com uma API Key. Você pode adicionar cabeçalhos ao seu webhook assim:
```json
{
"url": "example.com",
"event": "all",
"headers": {
"Authorization": "Minha chave da API",
"X-CLIENT-ID": "Alguma informação extra secreta"
}
}
```
Os cabeçalhos do webhook atualmente só podem ser configurados via API, pois podem conter dados sensíveis a serem expostos em nosso dashboard.
Para mais informações, veja Webhook em nossa referência da API.
## Configurar e Solucionar Problemas
Source: https://docs.pluggy.ai/pt/docs/developer-tools/webhook-troubleshoot.md
## Configurar e Solucionar Problemas
Visualize, crie e edite webhooks a partir do Dashboard, visualize quais webhooks foram enviados, seus payloads e reenvie-os para sincronizar os dados coletados.
### Visualizar, criar e editar webhooks a partir do Dashboard
Você também pode gerenciar os webhooks do seu aplicativo a partir do Dashboard.
1. Acesse [dashboard.pluggy.ai](https://dashboard.pluggy.ai)
2. Vá para a aba "Applications"
3. Acesse a página de configurações do aplicativo clicando no ícone de lápis no aplicativo onde você deseja gerenciar webhooks.
Aqui, você poderá visualizar os webhooks que já criou, editar a URL e os eventos aos quais está inscrito, excluí-lo ou até mesmo desativá-lo.
Apenas administradores ou proprietários da equipe podem editar webhooks.
- Você pode criar um máximo de 5 webhooks por evento. Se precisar registrar mais, considere consolidar seus endpoints ou usar uma única URL de webhook com roteamento interno.
- Webhooks apontando para ferramentas de teste conhecidas (como Request Catcher, ngrok ou URLs de desenvolvimento local semelhantes) são automaticamente excluídos após 90 dias.
### Monitorar Eventos de Webhook
Além de gerenciar as configurações de webhook, você pode monitorar a entrega de webhooks e solucionar problemas através da página de Eventos.
1. Navegue até [dashboard.pluggy.ai/events](https://dashboard.pluggy.ai/events)
2. Visualize todos os eventos de webhook enviados para seus aplicativos em tempo real
Use os filtros disponíveis para restringir os eventos de webhook:
- **Intervalo de Datas:** Filtrar eventos por data de criação
- **Tipo de Evento:** Selecionar tipos de eventos específicos ou visualizar todos os eventos
- **Pesquisar:** Pesquisar por ID do Cliente do Aplicativo, ID do Item ou qualquer texto
A página de eventos de webhook é atualizada automaticamente a cada minuto para mostrar os últimos eventos e seu status.
### Detalhes Avançados do Evento
Clique em qualquer linha de evento de webhook para visualizar informações detalhadas em um modal, incluindo:
- **Informações básicas:** Timestamp de Criação e Conclusão, Tipo de Evento, URL de Destino, ID do Conector/Item, Número de tentativas e Status de Entrega
- **Informações de erro** para eventos falhados
### Reenviar Eventos de Webhook
A funcionalidade de reenvio permite que você reenvie manualmente qualquer evento de webhook, independentemente de seu status atual. Isso é útil para testes, depuração ou para garantir a entrega de eventos importantes.
1. Clique na linha do evento para abrir o modal de detalhes
2. Clique no botão "Retry" para reenviar manualmente a entrega do webhook
3. O modal será fechado e o webhook será colocado na fila para reenvio
Para informações abrangentes sobre parâmetros de payload de webhook, tipos de eventos, manuseio de notificações e detalhes de implementação, consulte a [documentação completa de Webhook](/docs/developer-tools/webhooks-ref).
## Detectando falhas de autenticação
Source: https://docs.pluggy.ai/pt/docs/developer-tools/authentication-failures.md
## Qual evento eu preciso?
**`item/error`.** Não há um evento separado para um problema de autenticação: toda
execução que termina em um estado de erro — incluindo uma que falhou na etapa de
login — é entregue como `item/error`. A lista completa de eventos está em
[Webhook](/docs/developer-tools/webhooks-ref#data-events); nada mais nela é
específico de autenticação.
Registre-o como qualquer outro evento:
```http
POST https://api.pluggy.ai/webhooks
X-API-KEY: {apiKey}
Content-Type: application/json
{
"url": "https://example.com/pluggy",
"event": "item/error"
}
```
Não há um curinga por produto. Se você quiser cada evento de Item em um único endpoint,
registre `all` em vez de um webhook por evento.
## Distinguindo as falhas
A notificação carrega um objeto `error`, e seu `code` é o mesmo valor que o
Item expõe como `executionStatus`:
```json
{
"event": "item/error",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "d161a74a-8bc8-4093-88de-724312969b0d",
"error": {
"code": "INVALID_CREDENTIALS",
"message": "Credenciais inválidas"
},
"triggeredBy": "SYNC",
"clientUserId": "seu-id-de-usuario"
}
```
Os códigos que significam "a conexão não pôde autenticar" são:
| `error.code` | O que significa | O que o usuário final deve fazer |
| --- | --- | --- |
| `INVALID_CREDENTIALS` | As credenciais foram rejeitadas pela instituição. | Reinsira as credenciais. O `status` do Item se torna `LOGIN_ERROR` e ele **não será mais sincronizado automaticamente** até que novas credenciais sejam fornecidas. |
| `INVALID_CREDENTIALS_MFA` | A segunda etapa de login falhou: token MFA incorreto ou expirado. | Inicie uma nova tentativa de conexão e envie um token novo. |
| `USER_INPUT_TIMEOUT` | O token MFA nunca foi enviado a tempo. | Comece novamente e envie o token dentro do prazo. |
| `ALREADY_LOGGED_IN` | A instituição recusou uma nova sessão porque uma já está ativa. | Feche a sessão aberta na instituição e tente novamente. |
| `ACCOUNT_LOCKED` | A conta está bloqueada na instituição. | Entre em contato com a instituição para desbloqueá-la. |
| `ACCOUNT_CREDENTIALS_RESET` | A instituição está forçando um reset de credenciais (senha expirada, nova política de segurança). | Redefina a senha na instituição e reconecte. |
| `ACCOUNT_NEEDS_ACTION` | A instituição está bloqueando a coleta de dados até que o usuário faça algo (aceitar novos termos, completar um perfil). | Resolva isso na instituição e tente novamente. |
| `USER_AUTHORIZATION_NOT_GRANTED` | A autorização do dispositivo não foi concedida ao conector. | Autorize o dispositivo no aplicativo do banco e reconecte. |
| `USER_AUTHORIZATION_REVOKED` | O usuário revogou o compartilhamento de dados na instituição. | Reconsente — isso cria uma nova conexão. |
| `USER_NOT_SUPPORTED` | O tipo de conta que o usuário está conectando não é suportado para esse conector. | Use um tipo de conta suportado. |
Cada valor, incluindo os não relacionados à autenticação, é descrito em
[Item lifecycle](/docs/connections/item-lifecycle#final-states).
É um estado **intermediário**, não uma falha: o usuário precisa autorizar em
seu dispositivo ou na instituição, e a Pluggy retoma a coleta sozinha alguns
minutos depois. Trate esse código como "aguardando", não como "quebrado", ou você pedirá
ao usuário para reconectar uma conexão que estava prestes a ter sucesso.
Quando a falha ocorreu dentro da Pluggy ao armazenar dados já coletados, o
evento `item/error` ainda é acionado, mas não carrega um objeto `error` — esse código interno
não é exposto em superfícies voltadas para o cliente. Lide com a ausência de `error` sem
quebrar, e leia o `executionStatus` do Item com
[`GET /items/{id}`](/reference/items-retrieve) quando precisar do detalhe.
## O que *não* é um erro
Dois eventos parecem falhas e não são:
- **`item/waiting_user_input`** — o conector está pedindo um token MFA. O
login foi bem-sucedido; a execução está suspensa até que o token seja enviado com
[`POST /items/{id}/mfa`](/reference/items-send-mfa).
- **`item/waiting_user_action`** — o usuário deve agir em seu dispositivo (aprovar no
aplicativo do banco, escanear um código QR).
Nenhum deles encerra a execução, portanto, nenhum deve acionar uma mensagem de "sua conexão bancária
falhou" para o seu usuário.
## Obtendo o `itemId`
`itemId` está no payload de cada evento `item/*`, assim como o `clientUserId`
que você definiu ao [criar o Connect Token](/docs/authentication) — esses dois
campos são tudo o que você precisa para mapear a falha a um de seus usuários, sem chamada
API extra.
Se você nunca armazenou o `itemId` em primeiro lugar, veja
[Eu perdi um itemId. Como posso encontrá-lo novamente?](/docs/get-started/faq) — listar
itens é opt-in por equipe, então o caminho confiável é persistir o `itemId` do
callback `onSuccess` do widget ou do webhook `item/created`.
## Reagindo a isso
1. Procure seu usuário através do `clientUserId` (ou seu próprio mapeamento de `itemId`).
2. Se o código for um dos erros de credenciais acima, peça ao usuário para
reconectar. Reenviar as mesmas credenciais para um Item em `LOGIN_ERROR` sem
que o usuário as reinsira falhará novamente.
3. Atualize o Item existente em vez de criar um novo — veja
[Atualizando um Item](/docs/connect-widget/updating-item). Uma nova conexão significa
um novo `itemId` e um histórico fresco.
Responda ao webhook com um `2xx` **dentro de 10 segundos** e processe de forma assíncrona;
um manipulador lento conta como uma falha e será refeito. O cronograma de tentativas está em
[Webhook](/docs/developer-tools/webhooks-ref#handling-notifications).
## Servidor MCP
Source: https://docs.pluggy.ai/pt/docs/developer-tools/mcp.md
A **Model Context Protocol (MCP) server** da Pluggy permite que qualquer agente de IA leia a documentação, guias, referência da API, changelog, receitas e perguntas e respostas curadas da Pluggy diretamente em tempo de execução. Em vez de adivinhar a partir de dados de treinamento desatualizados, seu agente responde a perguntas e escreve código de integração baseado na documentação **live** — com citações.
O servidor está hospedado em:
```
https://mcp.pluggy.ai/mcp
```
É um servidor HTTP remoto: **sem instalação, sem chave de API.** Aponte qualquer cliente compatível com MCP para essa URL e funcionará.
O servidor agora vive em seu próprio endereço, então permanece o mesmo mesmo que o site da documentação se mova depois — `https://mcp.pluggy.ai/mcp` é a URL a ser usada a partir de agora. A anterior, `https://v2.docs.pluggy.ai/api/mcp`, continua funcionando, então qualquer coisa que você já configurou está bem como está.
**Uma URL, login opcional — o mesmo servidor para todos:**
- **Sem fazer login** → as ferramentas de documentação pública (docs, referência da API, changelog, receitas, perguntas e respostas).
- **Logado com sua conta do dashboard da Pluggy** → o acima **mais suas ferramentas de portal de desenvolvedor** — suas equipes, aplicações, conectores, itens e uso — limitados à sua equipe. O login é opcional; use anonimamente para docs, ou conecte-se aos seus dados.
O servidor MCP dá a um agente acesso ao vivo à documentação da Pluggy em tempo de execução. [Habilidades do Agente](/docs/developer-tools/ai-skills) dão ao agente o conhecimento — os padrões e melhores práticas — para construir com a Pluggy. Eles funcionam de forma independente, e ainda melhor juntos — a página [Construir com IA](/build-with-ai) configura ambos, além de llms.txt, em um só lugar.
## O que você pode fazer com isso
Uma vez conectado, peça ao seu agente para construir com a Pluggy e ele puxará a resposta exata e atual em vez de alucinar:
- **"Como eu crio um connect token e abro o Connect Widget?"** → passos fundamentados nos guias ao vivo.
- **"Mostre-me os detalhes do endpoint `createItem`."** → método, caminho, parâmetros e esquemas diretamente da especificação OpenAPI.
- **"O que mudou na última versão para webhooks?"** → a entrada real do changelog, não uma suposição.
- **"Por que meu item está preso em `WAITING_USER_INPUT`?"** → a pergunta e resposta curadas, verificadas por humanos, que responderam isso antes.
- **"Escreva o código para listar as transações de um usuário com paginação."** → código de integração que corresponde à API atual.
Como ele lê o mesmo conteúdo publicado neste site, as respostas permanecem corretas à medida que a documentação evolui — você nunca reensina seu agente.
## Ferramentas disponíveis
| Ferramenta | O que faz |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `query` | Faça uma pergunta em linguagem natural e obtenha uma resposta gerada **com citações**, combinando docs, changelog, receitas e referência da API |
| `search_docs` | Pesquise os guias de documentação (conceitos, quickstart, integração) com trechos classificados por relevância |
| `search_qa` | Pesquise as perguntas e respostas curadas, verificadas por humanos — a fonte de maior confiança para perguntas do tipo "como faço / por que X acontece" |
| `search_changelog` | Pesquise o changelog — notas de lançamento, mudanças significativas, notas de migração |
| `search_recipes` | Pesquise as receitas — padrões de integração, exemplos de código |
| `get_guide` | Recupere o conteúdo completo de um único guia de documentação por slug e localidade |
| `list_guides` | Liste todos os guias de documentação (slug, título, descrição, categoria) para uma localidade |
| `get_api_endpoint` | Obtenha detalhes completos de um endpoint da API por `operationId` — método, caminho, parâmetros, corpo da solicitação, respostas |
| `list_endpoints` | Liste todos os endpoints da API Pluggy da especificação OpenAPI, opcionalmente filtrados por tag |
| `submit_feedback` | Envie uma observação concreta sobre uma resposta incorreta, informação faltante, orientação confusa ou um problema de ferramenta para revisão pela Pluggy |
## Conecte-o à sua ferramenta
Escolha seu agente abaixo. Em todos os lugares que você vê, a URL do servidor é a mesma: `https://mcp.pluggy.ai/mcp`.
### Claude Code
```bash
claude mcp add --transport http pluggy-docs https://mcp.pluggy.ai/mcp
```
Adicione `-s user` para torná-lo disponível em todos os projetos: `claude mcp add -s user --transport http pluggy-docs https://mcp.pluggy.ai/mcp`.
### Claude Desktop
**Configurações → Conectores → Adicionar conector personalizado**, nomeie-o como `Pluggy Docs`, e cole `https://mcp.pluggy.ai/mcp`. Ou edite `claude_desktop_config.json`:
```json
{
"mcpServers": {
"pluggy-docs": {
"type": "http",
"url": "https://mcp.pluggy.ai/mcp"
}
}
}
```
### ChatGPT (OpenAI)
Em **Configurações → Conectores → Avançado → Modo desenvolvedor**, adicione um conector com a URL `https://mcp.pluggy.ai/mcp`. (Conectores MCP remotos personalizados estão disponíveis no ChatGPT Plus/Pro/Business/Enterprise.) Em um chat, ative o conector `Pluggy Docs` e pergunte.
### OpenAI Codex CLI
Adicione a `~/.codex/config.toml`:
```toml
[mcp_servers.pluggy-docs]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.pluggy.ai/mcp"]
```
Codex se comunica com servidores MCP locais (stdio), então `mcp-remote` faz a ponte para o servidor HTTP hospedado.
### Cursor
Adicione a `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (por projeto):
```json
{
"mcpServers": {
"pluggy-docs": {
"url": "https://mcp.pluggy.ai/mcp"
}
}
}
```
### VS Code (modo agente do GitHub Copilot)
Um comando:
```bash
code --add-mcp '{"name":"pluggy-docs","type":"http","url":"https://mcp.pluggy.ai/mcp"}'
```
Ou crie `.vscode/mcp.json` em seu espaço de trabalho:
```json
{
"servers": {
"pluggy-docs": {
"type": "http",
"url": "https://mcp.pluggy.ai/mcp"
}
}
}
```
### Windsurf
Adicione a `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"pluggy-docs": {
"serverUrl": "https://mcp.pluggy.ai/mcp"
}
}
}
```
### Gemini CLI
Adicione a `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"pluggy-docs": {
"httpUrl": "https://mcp.pluggy.ai/mcp"
}
}
}
```
### Zed
Adicione ao seu `settings.json` do Zed:
```json
{
"context_servers": {
"pluggy-docs": {
"command": {
"path": "npx",
"args": ["-y", "mcp-remote", "https://mcp.pluggy.ai/mcp"]
}
}
}
}
```
### Qualquer outro cliente MCP
Se seu cliente só suporta servidores locais (stdio), faça a ponte para o hospedado com [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
```bash
npx -y mcp-remote https://mcp.pluggy.ai/mcp
```
Clientes que suportam servidores **Streamable HTTP** remotos podem usar a URL diretamente.
## Teste sua configuração
Inicie um novo chat com seu agente e tente:
```
Usando os docs MCP da Pluggy, como eu crio um connect token e abro o Connect Widget?
```
ou
```
Liste os endpoints da API Pluggy para Itens e mostre-me os detalhes do createItem.
```
O agente deve chamar as ferramentas MCP e responder com citações da documentação ao vivo. Se nada acontecer, reinicie o cliente após adicionar o servidor e confirme se a URL é exatamente `https://mcp.pluggy.ai/mcp`.
## O que ele expõe
O servidor cobre tudo publicado neste site:
- **Guias de documentação** — conceitos, quickstart e guias de integração (EN e PT)
- **Referência da API** — cada endpoint da especificação OpenAPI, com parâmetros e esquemas
- **Changelog** — notas de lançamento, mudanças significativas e notas de migração
- **Receitas** — padrões de integração passo a passo e exemplos de código
- **Perguntas e respostas curadas** — perguntas reais de suporte respondidas e verificadas pela equipe da Pluggy
**Logado** (sua conta do dashboard da Pluggy), o mesmo servidor também expõe seu **portal de desenvolvedor**, limitado à sua equipe: liste suas equipes e aplicações, conectores, itens e estatísticas de uso. Seu token é validado e usado apenas para acessar os dados da sua própria equipe — nunca os de outro cliente, e nunca o conhecimento interno da Pluggy.
As ferramentas de documentação são públicas e somente leitura, exceto `submit_feedback`, que salva seu feedback para revisão humana. Não inclua credenciais ou dados pessoais no feedback. As ferramentas do portal de desenvolvedor requerem login. Para chamar a API do produto Pluggy diretamente, use a [Referência da API](/reference) com suas próprias credenciais.
## Seus próprios dados: as ferramentas do portal de desenvolvedor
Faça login e o agente pode responder perguntas sobre *sua* integração, não apenas sobre a documentação — por que um item está falhando, o que um webhook entregou, quanto você ingeriu no mês passado.
| Ferramenta | O que faz |
| --- | --- |
| `list_teams` | As equipes às quais sua conta pertence |
| `list_applications` | As aplicações de uma equipe, com seu ambiente |
| `select_application` | Define a equipe e a aplicação para o resto da conversa |
| `get_application` | Como uma aplicação está configurada — nome, ambiente (sandbox ou produção), habilitada, clientId, origens permitidas e branding. Nunca inclui o client secret |
| `list_connectors` | Os conectores disponíveis para uma aplicação |
| `get_stats` | Estatísticas do dashboard para uma equipe — itens, execuções, taxa de sucesso e volume e resultados de pagamentos |
| `get_item` | Um item por id: status atual e execuções recentes |
| `debug_item` | Por que um item está falhando, e o próximo passo para aquele usuário — credenciais expiradas, consentimento para re-autorização, MFA pendente, ou um incidente do lado do provedor |
| `get_execution_reports` | O que cada sincronização recente de um item trouxe — produtos com dados, vazios ou falhados, entidades retornadas, transações criadas por data. Para "a sincronização funcionou, mas os dados estão faltando" |
| `summarize_api_calls` | Como uma aplicação usou a API Pluggy ao longo de um período de até 7 dias — chamadas agrupadas por endpoint e status, com contagens e duração p95 |
| `list_api_calls` | Chamadas individuais da API de uma aplicação, da mais nova para a mais antiga — endpoint, status, código de erro, duração, o item que nomeou e o id da solicitação. Filtrar por classe de status, endpoint ou item |
| `summarize_of_calls` | Como as chamadas de Open Finance que a Pluggy fez para a instituição para um item ocorreram ao longo de um período de até 31 dias — por execução, endpoint e status, com contagens, tentativas e duração p95. Para "por que meu item falhou" ou "por que não trouxe transações" |
| `list_of_calls` | Chamadas individuais de Open Finance de um item, da mais nova para a mais antiga — execução, endpoint, status, código de erro, duração e tentativas. Filtrar por execução, classe de status ou endpoint |
| `check_incidents` | Incidentes atuais e recentemente resolvidos de [status.pluggy.ai](https://status.pluggy.ai), opcionalmente filtrados por conector |
| `list_webhooks` | Os webhooks registrados para uma aplicação e os eventos que eles disparam |
| `list_webhook_events` | Eventos entregues, com seu status |
| `get_webhook_event` | Um evento completo: payload, status, tentativas de entrega |
| `get_reports` | Relatórios de ingestão de transações ao longo de um intervalo de datas, diários ou resumidos |
| `get_billing_url` | Um link para o dashboard de faturamento da equipe |
| `create_support_ticket` | Abre um ticket de suporte — apenas para equipes com a integração de ticket de parceiro habilitada |
| `dev_portal_tools_introduction` | Como o agente deve encadear as ferramentas acima |
A primeira chamada pede que você faça login com a mesma conta que usa no
[Dashboard](https://dashboard.pluggy.ai), através do fluxo de autorização normal do seu cliente MCP. Não há chave de API para colar, e seu `clientSecret` nunca chega ao agente: as ferramentas leem o portal de desenvolvedor em nome do seu usuário, limitado às equipes que esse usuário já pode ver.
Uma sessão geralmente vai: `list_teams` → `list_applications` → `select_application`, e a partir daí as ferramentas de dados reutilizam essa equipe e aplicação. Pedir ao agente para "usar minha aplicação sandbox" é suficiente — ele faz essas chamadas por conta própria.
A autenticação é opcional neste servidor: as ferramentas de documentação funcionam anonimamente, então um cliente configurado para autenticar **apenas quando o servidor pedir** nunca é solicitado, e as ferramentas do portal de desenvolvedor respondem *"Não autenticado"* em vez de abrir o login. Defina o conector para autenticar **sempre** (no Claude, *Sempre necessário*) e o fluxo funcionará como esperado.
### O que perguntar
```
Por que o item 8a7c… está preso? Use as ferramentas do portal de desenvolvedor da Pluggy.
```
```
Liste os eventos de webhook que minha aplicação de produção entregou hoje e abra o último que falhou.
```
```
Quantas transações nós ingerimos no mês passado em comparação com o anterior?
```
## Quando algo não funciona
- **O agente nunca chama as ferramentas.** Reinicie o cliente após adicionar o servidor — a maioria só lê sua configuração MCP na inicialização — e verifique se a URL é exatamente `https://mcp.pluggy.ai/mcp`.
- **"Não autenticado" em uma ferramenta do portal de desenvolvedor.** O cliente está configurado para fazer login apenas sob demanda; veja a nota acima.
- **A resposta parece desatualizada.** As ferramentas leem o site publicado, então qualquer coisa que ainda não foi publicada também não é visível para elas. Verifique a página em si em [v2.docs.pluggy.ai](https://v2.docs.pluggy.ai).
- **Seu cliente só fala stdio.** Faça a ponte com `npx -y mcp-remote https://mcp.pluggy.ai/mcp`.
## Habilidades do Agente
Source: https://docs.pluggy.ai/pt/docs/developer-tools/ai-skills.md
**Habilidades do Agente** são pastas de instruções, melhores práticas e recursos que agentes de codificação de IA — como Claude Code, Cursor e GitHub Copilot — podem descobrir e carregar sob demanda. A Pluggy mantém um conjunto de habilidades oficiais para que, quando você pede ao seu agente para construir ou revisar uma integração Pluggy, ele siga os padrões documentados da Pluggy em vez de adivinhar.
As habilidades seguem o formato aberto de [Habilidades do Agente](https://agentskills.io/) e são de código aberto em [`pluggyai/agent-skills`](https://github.com/pluggyai/agent-skills).
O **[Servidor MCP](/docs/developer-tools/mcp)** dá a um agente acesso ao vivo à documentação e à referência da API da Pluggy em tempo de execução. **Habilidades** dão ao agente o know-how — os padrões, o que fazer e o que não fazer — para usar a Pluggy corretamente. Elas são independentes: as habilidades funcionam por conta própria, sem necessidade de MCP. Elas também funcionam muito bem juntas — o Pluggy Doctor, por exemplo, valida contra a documentação através do MCP quando está conectado (e recorre à documentação pública na web quando não está).
## Instalação
Instale todas as habilidades da Pluggy em seu projeto com um único comando:
```shell
npx skills add pluggyai/agent-skills
```
ou
```shell
pnpm dlx skills add pluggyai/agent-skills
```
Uma vez instaladas, as habilidades estão disponíveis automaticamente. Seu agente carrega a relevante sempre que detecta uma tarefa correspondente — você não precisa invocá-las manualmente. **Nenhum MCP é necessário** — as habilidades são autossuficientes.
conecte a [Pluggy Docs MCP](/docs/developer-tools/mcp) para que o revisor valide contra a documentação ao vivo. Se você pular isso, o Pluggy Doctor recorre à documentação pública na web.
```bash
claude mcp add --transport http pluggy-docs https://mcp.pluggy.ai/mcp
```
## Habilidades disponíveis
| Habilidade | O que faz | Use para… |
| ----------------------------------------------- | --------------------------- | -------------------------------------------------------------- |
| [`pluggy-integration`](#pluggy-integration) | Padrões de integração principais | Construir autenticação, o Connect Widget, Itens e webhooks |
| [`pluggy-open-finance`](#pluggy-open-finance) | Recuperação de dados de Open Finance | Buscar contas, transações, investimentos, empréstimos e identidade |
| [`pluggy-payments`](#pluggy-payments) | Iniciação de pagamentos | Implementar PIX, Boleto e Smart Transfers |
| [`pluggy-doctor`](#pluggy-doctor) | Revisão de código de integração | Diagnosticar uma integração existente antes de ir para produção |
---
## pluggy-integration
Padrões e melhores práticas de integração da Pluggy — a base para qualquer implementação.
**Use quando você estiver:**
- Configurando o SDK da Pluggy e autenticação
- Implementando o Connect Widget em um aplicativo frontend
- Criando, atualizando ou excluindo Itens (conexões)
- Configurando webhooks para sincronização de dados em tempo real
- Lidando com fluxos de MFA e erros de conexão
**Áreas cobertas:**
| Categoria | Impacto |
| --------------------------- | --------- |
| Autenticação & Chaves da API | Crítico |
| Integração do Connect Widget | Crítico |
| Configuração de Webhook | Crítico |
| Gerenciamento do Ciclo de Vida do Item | Alto |
| Tratamento de Erros | Médio |
**Exemplos de prompts:**
```
Ajude-me a integrar o Connect Widget da Pluggy no meu aplicativo React
Configure webhooks para sincronizar dados de transações
Como devo lidar com MFA quando um Item está WAITING_USER_INPUT?
```
---
## pluggy-open-finance
Melhores práticas para recuperar e gerenciar dados de Open Finance através da Pluggy.
**Use quando você estiver:**
- Selecionando o conector certo para uma instituição financeira
- Recuperando saldos e detalhes de contas
- Buscando e processando transações
- Acessando portfólios de investimento, empréstimos ou dados de identidade
- Projetando uma estratégia de sincronização de dados
**Áreas cobertas:**
| Categoria | Impacto |
| ---------------------------------- | --------- |
| Seleção de Conector | Crítico |
| Sincronização de Dados | Alto |
| Recuperação de Dados & Paginação | Alto |
| Tratamento de Transações & Enriquecimento | Alto |
| Gerenciamento de Contas | Médio |
**Exemplos de prompts:**
```
Busque e armazene transações com paginação para um Item
Enriqueça transações com categorias
Qual é a estratégia de sincronização correta após um webhook de item/atualizado?
```
---
## pluggy-payments
Iniciação de pagamentos com PIX, Boleto e Smart Transfers.
**Use quando você estiver:**
- Iniciando pagamentos PIX
- Criando e gerenciando Boletos
- Configurando Smart Transfers com pré-autorização
- Gerenciando o ciclo de vida da intenção de pagamento
- Lidando com pagamentos agendados (PIX Agendado)
**Áreas cobertas:**
| Categoria | Impacto |
| ------------------------- | --------- |
| Integração PIX | Crítico |
| Smart Transfers | Alto |
| Ciclo de Vida da Intenção de Pagamento | Alto |
| Gerenciamento de Boleto | Médio |
| Pagamentos Agendados | Médio |
**Exemplos de prompts:**
```
Implemente a iniciação de pagamento PIX de ponta a ponta
Configure uma Smart Transfer com pré-autorização
Acompanhe o status do pagamento com webhooks
```
---
## pluggy-doctor
Uma habilidade de revisor que **revisa o código de uma integração Pluggy existente** e informa se está pronta para produção. Ao contrário das outras habilidades (que ajudam você a *construir*), o Pluggy Doctor *avalia* o código que você já escreveu.
Ele diagnostica contra a **documentação oficial** da Pluggy — nunca de memória ou de uma lista de verificação congelada — e retorna um relatório estruturado com uma correção para cada problema. Ele lê a documentação através do [Pluggy MCP](/docs/developer-tools/mcp) quando está conectado, e **recorre à leitura da mesma documentação pública na web** quando não está — então **a habilidade funciona com ou sem o MCP**. Se não conseguir confirmar um critério contra a documentação, marca como "não verificado" em vez de adivinhar.
**Use quando você:**
- Quiser revisar ou validar uma integração existente
- Perguntar "isso está pronto para produção?"
- Quiser verificar a segurança das credenciais, tokens de conexão ou tratamento de webhooks
- Fazer upload de arquivos de integração (manipulador de webhook, geração de token de conexão, configuração) para diagnóstico
**Áreas cobertas:**
- Segurança das credenciais (`clientId`/`clientSecret` apenas no backend)
- Token de Conexão & `clientUserId`
- Webhooks — configuração
- Webhooks — tratamento correto (status do item, `PARTIAL_SUCCESS`, sincronização bidirecional)
- Estratégia de sincronização — confiar na sincronização automática, sem atualizações autônomas
- Ambiente (sandbox vs. produção)
**O que você recebe de volta:** um relatório por área classificando cada item como ✅ correto, ❌ problema (com arquivo, linha e uma correção pronta para colar), ⚠️ aviso, ou ➖ não aplicável — encerrando com um claro 🟢 pronto para produção ou 🔴 ainda não.
o relatório diagnóstico reflete a linguagem do desenvolvedor.
**Exemplos de prompts:**
```
Revise minha integração Pluggy antes de enviá-la
Verifique meu manipulador de webhook — está correto?
Esta integração é segura e está pronta para produção?
Analisa minha integração da Pluggy
```
---
## Agentes suportados
As habilidades usam a nomenclatura de ferramentas do Claude Code, mas funcionam com qualquer agente que suporte o formato de Habilidades do Agente, incluindo:
- **Claude Code**
- **Cursor**
- **GitHub Copilot**
## Recursos
- [Construir com IA](/build-with-ai) — uma página para conectar o MCP, instalar as habilidades e pegar llms.txt
- [Repositório de Habilidades do Agente (`pluggyai/agent-skills`)](https://github.com/pluggyai/agent-skills)
- [Servidor MCP da Pluggy](/docs/developer-tools/mcp)
- [Documentação da Pluggy](https://v2.docs.pluggy.ai)
- [Referência da API](/reference)
- [pluggy-js SDK](https://github.com/pluggyai/pluggy-js)
## Webhooks de Chamados de Suporte
Source: https://docs.pluggy.ai/pt/docs/developer-tools/support-ticket-webhooks.md
## Visão Geral
Se você abrir tickets através da [Referência da API de Suporte ao Parceiro](/partners), não precisa fazer polling em `GET /api/partners/tickets` para saber que um caso foi movido. Registre um endpoint HTTPS e nós iremos `POST` um evento JSON para ele sempre que um dos seus tickets mudar — uma mudança de status, uma resolução, uma resposta da nossa equipe de suporte, uma mudança de prioridade ou um novo título.
A API não desaparece. Ela continua sendo a autoridade: você continua usando-a para abrir tickets, postar acompanhamentos e reconciliar. O webhook é o caminho rápido, não o único.
```
POST https://your-endpoint.example.com/pluggy/tickets
Content-Type: application/json
X-Pluggy-Signature: t=1758202927,v1=6f9c…
X-Pluggy-Event-Id: 0f2b6c4e-7a1d-4a2e-9c3f-5b8d1e0a7c44
```
Nosso suporte mantém notas internas sobre os mesmos tickets. Elas nunca são emitidas. `ticket.message_added` carrega uma resposta escrita *para você* e nada mais — o filtro é positivo (uma resposta pública da nossa equipe), então qualquer coisa nova e interna é excluída por padrão, em vez de incluída até que alguém se lembre de excluí-la. Suas próprias mensagens também não são ecoadas de volta para você.
## Configurando
Você configura seus endpoints por conta própria, através da Referência da API de Suporte ao Parceiro e com a mesma chave da API que você usa para abrir tickets. Nenhuma dessas chamadas conta contra sua cota de tickets.
### 1. Registrar um endpoint
```bash
curl -X POST https://docs.pluggy.ai/api/partners/webhooks \
-H "Authorization: Bearer $PLUGGY_PARTNER_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.yourcompany.com/pluggy/tickets",
"description": "homologação",
"enabled": false
}'
```
```json
{
"endpoint": {
"id": "3f0b8c1e-6a2d-4c3b-9e1f-2a7d5b8c9e01",
"url": "https://hooks.yourcompany.com/pluggy/tickets",
"description": "homologação",
"enabled": false,
"secretRotatedAt": "2026-10-27T12:00:00.000Z",
"createdAt": "2026-10-27T12:00:00.000Z",
"updatedAt": "2026-10-27T12:00:00.000Z"
},
"secret": "whsec_8c1f0e5a3b9d4c7e2f6a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e",
"routed": true
}
```
A URL deve ser `https`, sem credenciais ou um `#fragment`, e em um nome de host público — endereços IP, `localhost` e nomes internos são recusados, e o erro informa qual regra a URL quebrou. `enabled` padrão é `true`; enviar `false` permite que você teste o endpoint antes que ele comece a receber eventos de tickets.
### 2. Armazenar o segredo
`secret` é o segredo de assinatura para este endpoint: `whsec_` seguido por 64 caracteres hexadecimais. Ele está nesta resposta **e em nenhum outro lugar** — não podemos lê-lo de volta para você depois, e `GET` nunca o retorna. Armazene-o como um segredo do seu lado antes de fazer qualquer outra coisa.
### 3. Enviar um evento de teste para você
```bash
curl -X POST https://docs.pluggy.ai/api/partners/webhooks/3f0b8c1e-6a2d-4c3b-9e1f-2a7d5b8c9e01/test \
-H "Authorization: Bearer $PLUGGY_PARTNER_KEY"
```
```json
{
"delivered": true,
"responseCode": 200,
"error": null,
"eventId": "5d2e9a7b-0c4f-4e1a-b3d6-8f9a0b1c2d3e",
"durationMs": 143
}
```
Nós enviamos um evento [`webhook.test`](#webhooktest) para o endpoint imediatamente, assinado exatamente como um evento de ticket, e informamos o que seu endpoint respondeu. Funciona em um endpoint desativado também. `delivered: false` vem com o código de status ou a razão — um timeout, um erro de conexão, um redirecionamento (não os seguimos). A chamada em si responde `200` de qualquer forma; é a tentativa que falhou, não a chamada. Execute até que seu endpoint verifique a assinatura e responda `2xx`.
### 4. Habilitá-lo
```bash
curl -X PATCH https://docs.pluggy.ai/api/partners/webhooks/3f0b8c1e-6a2d-4c3b-9e1f-2a7d5b8c9e01 \
-H "Authorization: Bearer $PLUGGY_PARTNER_KEY" \
-H "Content-Type: application/json" \
-d '{ "enabled": true }'
```
A partir desse momento, toda mudança em um ticket que pertence à sua conta produz um evento. Essa é toda a configuração.
Se uma resposta carregar `"routed": false` e um `warning`, seus endpoints estão salvos, mas os eventos de tickets ainda não podem alcançar sua conta — entre em contato conosco e nós terminaremos a configuração do nosso lado.
### Renovando um segredo
Se um segredo for perdido ou vazado, emita um novo:
```bash
curl -X PATCH https://docs.pluggy.ai/api/partners/webhooks/3f0b8c1e-6a2d-4c3b-9e1f-2a7d5b8c9e01 \
-H "Authorization: Bearer $PLUGGY_PARTNER_KEY" \
-H "Content-Type: application/json" \
-d '{ "rotateSecret": true }'
```
O novo segredo volta em `secret`, uma vez, como na criação. Ele substitui o antigo **imediatamente** — cada entrega a partir de então é assinada com ele — então faça a troca em um passo. Enviar `url` em um `PATCH` também emite um novo segredo, mesmo quando é a mesma URL que o endpoint já possui; mudar apenas `description` ou `enabled` mantém o atual.
### Mais de um endpoint
Você pode registrar até **10** endpoints — um por ambiente, ou um por sistema que consome os eventos. Cada um tem seu próprio segredo, então verifique cada entrega com o segredo do endpoint que a recebeu.
**Todo evento vai para cada endpoint habilitado.** Não há filtro por endpoint: um endpoint de homologação e um endpoint de produção recebem todos os eventos dos seus tickets. Um endpoint desativado não recebe nada, e eventos que acontecem enquanto ele está desativado não são mantidos para ele — habilitá-lo novamente só afeta o que acontece a seguir.
| Chamada | O que faz |
| --- | --- |
| `GET /api/partners/webhooks` | Seus endpoints, os eventos que recebem e se os eventos podem alcançar sua conta. Sem segredos. |
| `POST /api/partners/webhooks` | Registrar um endpoint. Retorna seu segredo, uma vez. |
| `GET /api/partners/webhooks/{id}` | Um endpoint. Sem segredo. |
| `PATCH /api/partners/webhooks/{id}` | Mudar `url`, `description` ou `enabled`, ou renovar o segredo com `rotateSecret`. |
| `DELETE /api/partners/webhooks/{id}` | Remover. Entregas que ainda estão esperando para serem reprocessadas são descartadas. Para pausar, em vez disso, `PATCH` com `enabled: false`. |
| `POST /api/partners/webhooks/{id}/test` | Enviar um `webhook.test` assinado para ele agora. |
Os esquemas completos estão na [Referência da API de Suporte ao Parceiro](/partners). Se você preferir não fazer isso sozinho, pergunte-nos — nós também podemos configurá-lo para você.
### Respondendo entregas
Seu endpoint deve responder a qualquer `2xx` assim que tiver aceitado duravelmente o evento — coloque-o em uma fila e processe de forma assíncrona. Nós aguardamos **8 segundos** por uma resposta; qualquer coisa mais lenta é tratada como uma entrega falhada e é reprocessada. Redirecionamentos não são seguidos: um `3xx` é uma entrega falhada, então registre a URL final.
## O payload
Todo evento de ticket tem o mesmo envelope (o evento [`webhook.test`](#webhooktest) que você pede é menor, veja abaixo):
| Campo | Significado |
| --- | --- |
| `eventId` | UUID, único por evento e **estável em reprocessamentos**. Sua chave de idempotência. Também enviado como o cabeçalho `X-Pluggy-Event-Id`. |
| `sequence` | Monotônico, atribuído quando o evento é criado. `sequence` crescente é a ordem de criação — **não** é a ordem de entrega, veja abaixo. |
| `event` | Um dos cinco tipos de eventos de ticket abaixo. |
| `occurredAt` | Quando observamos a mudança. Um reprocessamento não a move. |
| `ticket` | O ticket após a mudança: `key`, `number` (número do nosso suporte), `externalId`, `openedBy`, `title`, `state`, `status`, `updatedAt`, `portalUrl`, e `priority` onde sabemos. |
| `previous` | Presente apenas onde há um valor anterior — `state`/`status`, `priority` ou `title`. |
| `message` | Presente apenas em `ticket.message_added`. |
O bloco de ticket é deliberadamente pequeno. Ele informa o que mudou; `GET /api/partners/tickets/{key}` é a autoridade sobre tudo o mais.
`externalId` e `openedBy` são seus próprios: o id que você enviou quando abriu o ticket e quem você disse que o abriu, devolvidos exatamente na forma que `GET /api/partners/tickets/{key}` os retorna. Eles estão lá para que você possa juntar o evento ao seu próprio registro sem precisar analisar o título. Ambos estão sempre presentes e `null` quando não temos nenhum — um ticket aberto sem eles, ou antes de começarmos a armazená-los. Eles também são `null` em um ticket que outra organização abriu e compartilha com a sua: você ainda recebe seus eventos, mas seu `externalId` e `openedBy` são deles.
`state` é o bucket de ciclo de vida grosso e é um dos seguintes: `new`, `on_you`, `on_customer`, `on_hold` ou `closed`. `status` é o rótulo legível que o acompanha — `Novo`, `Em você`, `No cliente`, `Aguardando Detentora`, `Aguardando Engenharia`, `Fechado` — e um status que ainda não mapeamos chega como ele mesmo, então **combine com `state` e trate `status` como texto de exibição**.
Cada timestamp está em UTC, RFC 3339, com sufixo `Z`. `ticket.updatedAt` e `message.sentAt` se originam no sistema de tickets, que os reporta com um offset; nós os normalizamos antes de enviar, então um payload nunca carrega dois formatos.
## Verificando a assinatura
`X-Pluggy-Signature` é formatado como `t=,v1=`. A string assinada é `"{t}.{raw body}"` — o corpo da requisição **exatamente como chegou pela rede**, antes de qualquer análise JSON. Re-serializar o objeto analisado muda os bytes e a assinatura não corresponderá.
`t` é também o token anti-replay: rejeite uma requisição cujo `t` tenha mais de cinco minutos.
```js
import { createHmac, timingSafeEqual } from "node:crypto";
const TOLERANCE_SECONDS = 5 * 60;
export function verifyPluggySignature(rawBody, header, secret) {
// header: "t=1758202927,v1=6f9c…"
const parts = new Map(
String(header ?? "")
.split(",")
.map((part) => {
const i = part.indexOf("=");
return [part.slice(0, i).trim(), part.slice(i + 1).trim()];
}),
);
const timestamp = Number(parts.get("t"));
const received = parts.get("v1");
if (!Number.isFinite(timestamp) || !received) return false;
// Anti-replay: uma assinatura antiga ainda é uma assinatura válida.
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > TOLERANCE_SECONDS) return false;
const expected = createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(received, "utf8");
return a.length === b.length && timingSafeEqual(a, b);
}
```
Integrado em um aplicativo Express, mantendo o corpo bruto:
```js
import express from "express";
const app = express();
app.post(
"/pluggy/tickets",
express.raw({ type: "application/json" }),
(req, res) => {
const raw = req.body.toString("utf8"); // os bytes que assinamos
if (!verifyPluggySignature(raw, req.get("X-Pluggy-Signature"), process.env.PLUGGY_WEBHOOK_SECRET)) {
return res.status(401).end();
}
const event = JSON.parse(raw);
enqueue(event); // de-duplicar em event.eventId, depois processar
res.status(200).end();
},
);
```
Uma verificação funcional que você pode executar contra uma entrega que você capturou: `createHmac("sha256", secret).update(t + "." + rawBody).digest("hex")` deve ser igual ao valor `v1`, caractere por caractere.
## Eventos
### `ticket.status_changed`
O ticket se moveu no fluxo de trabalho — `state`, o status do portal, ou ambos. `previous` carrega o que eles eram.
```json
{
"eventId": "0f2b6c4e-7a1d-4a2e-9c3f-5b8d1e0a7c44",
"sequence": 1042,
"event": "ticket.status_changed",
"occurredAt": "2026-09-18T13:42:07.912Z",
"ticket": {
"key": "SUP2-1234",
"number": 418,
"externalId": "YOUR-1947",
"openedBy": { "email": "ana@yourcompany.com", "name": "Ana Souza" },
"title": "[YourOrg/Itaú] Transação não retornada (YOUR-1947)",
"state": "on_you",
"status": "Em você",
"updatedAt": "2026-09-18T13:41:58Z",
"portalUrl": "https://pluggy.atlassian.net/servicedesk/customer/portal/1/SUP2-1234"
},
"previous": { "state": "new", "status": "Novo" }
}
```
### `ticket.resolved`
O ticket foi fechado. Ele é enviado **em vez de** `ticket.status_changed`, nunca em adição: uma mudança no mundo real produz um evento, então um consumidor que age em ambos não age duas vezes. Não há bloco `previous`.
```json
{
"eventId": "7c1a55d2-3e64-4b0a-8f2d-9a0c6e4b21f7",
"sequence": 1043,
"event": "ticket.resolved",
"occurredAt": "2026-09-18T18:05:31.004Z",
"ticket": {
"key": "SUP2-1234",
"number": 418,
"externalId": "YOUR-1947",
"openedBy": { "email": "ana@yourcompany.com", "name": "Ana Souza" },
"title": "[YourOrg/Itaú] Transação não retornada (YOUR-1947)",
"state": "closed",
"status": "Fechado",
"updatedAt": "2026-09-18T18:05:12Z",
"portalUrl": "https://pluggy.atlassian.net/servicedesk/customer/portal/1/SUP2-1234"
}
}
```
### `ticket.message_added`
Uma resposta da nossa equipe de suporte foi publicada no ticket. Este é o único evento que carrega conteúdo: `message.text` é a resposta escrita, em texto simples.
`ticket.updatedAt` neste evento é o momento em que a mensagem foi enviada.
```json
{
"eventId": "b83f0c19-55ad-4c6e-9f41-2d7e8ab10c53",
"sequence": 1044,
"event": "ticket.message_added",
"occurredAt": "2026-09-18T15:20:44.881Z",
"ticket": {
"key": "SUP2-1234",
"number": 418,
"externalId": "YOUR-1947",
"openedBy": { "email": "ana@yourcompany.com", "name": "Ana Souza" },
"title": "[YourOrg/Itaú] Transação não retornada (YOUR-1947)",
"state": "on_you",
"status": "Em você",
"updatedAt": "2026-09-18T15:20:31Z",
"portalUrl": "https://pluggy.atlassian.net/servicedesk/customer/portal/1/SUP2-1234"
},
"message": {
"author": "Pluggy Support",
"text": "Identificamos a causa na coleta da fatura fechada e o ajuste entrou em produção hoje. Pode validar nos itens afetados e nos confirmar?",
"sentAt": "2026-09-18T15:20:31Z"
}
}
```
### `ticket.priority_changed`
A prioridade do ticket mudou. `previous.priority` é o valor que tinha antes.
O novo valor é `ticket.priority`, e `previous.priority` é o que era. Ambos são os próprios nomes do sistema de tickets (`Highest`, `High`, `Medium`, `Low`), que não são os rótulos `P0 — Crítico … P3 — Baixo` que o endpoint de criação aceita — o mesmo conceito em dois vocabulários, que preferimos informar a você do que fazer você descobrir.
A primeira vez que observamos uma prioridade em um ticket não é uma mudança e não produz evento.
```json
{
"eventId": "2ad9e5b7-1c08-49f3-b6a1-70c2d4e95f18",
"sequence": 1045,
"event": "ticket.priority_changed",
"occurredAt": "2026-09-18T14:02:19.377Z",
"ticket": {
"key": "SUP2-1234",
"number": 418,
"externalId": "YOUR-1947",
"openedBy": { "email": "ana@yourcompany.com", "name": "Ana Souza" },
"title": "[YourOrg/Itaú] Transação não retornada (YOUR-1947)",
"state": "on_you",
"status": "Em você",
"updatedAt": "2026-09-18T14:02:05Z",
"portalUrl": "https://pluggy.atlassian.net/servicedesk/customer/portal/1/SUP2-1234"
},
"previous": { "priority": "Medium" }
}
```
### `ticket.updated`
O título do ticket mudou. Não é enviado quando o ticket é fechado na mesma passagem — a resolução é o evento que importa ali.
```json
{
"eventId": "e40b7f36-9c52-4a8d-83b1-6f0a2c5d7e91",
"sequence": 1046,
"event": "ticket.updated",
"occurredAt": "2026-09-18T16:11:02.560Z",
"ticket": {
"key": "SUP2-1234",
"number": 418,
"externalId": "YOUR-1947",
"openedBy": { "email": "ana@yourcompany.com", "name": "Ana Souza" },
"title": "[YourOrg/Itaú] Transações do cartão não retornadas (YOUR-1947)",
"state": "on_you",
"status": "Em você",
"updatedAt": "2026-09-18T16:10:47Z",
"portalUrl": "https://pluggy.atlassian.net/servicedesk/customer/portal/1/SUP2-1234"
},
"previous": { "title": "[YourOrg/Itaú] Transação não retornada (YOUR-1947)" }
}
```
### `webhook.test`
Enviado apenas quando você chama `POST /api/partners/webhooks/{id}/test`, e apenas para aquele endpoint — nunca por conta própria, nunca porque um ticket se moveu. Ele carrega os mesmos cabeçalhos e a mesma assinatura que um evento de ticket, então prova sua verificação de ponta a ponta, mas não tem bloco `ticket`: `endpoint` diz a qual dos seus endpoints foi enviado.
Verifique-o, responda `2xx`, e não faça mais nada com ele. Um consumidor que roteia por `event` deve ignorar um tipo que não conhece em vez de falhar.
```json
{
"eventId": "5d2e9a7b-0c4f-4e1a-b3d6-8f9a0b1c2d3e",
"event": "webhook.test",
"occurredAt": "2026-10-27T12:05:00.000Z",
"endpoint": {
"id": "3f0b8c1e-6a2d-4c3b-9e1f-2a7d5b8c9e01",
"url": "https://hooks.yourcompany.com/pluggy/tickets"
}
}
```
Um teste é enviado uma vez e não é reprocessado: se falhar, conserte o endpoint e envie outro.
## Idempotência
**De-duplicate em `eventId`.** É um UUID, único por evento, e não muda quando reprocessamos — um reenvio do mesmo evento carrega o mesmo id. O mesmo id chegando duas vezes significa a mesma mudança, não duas mudanças.
Você verá repetições na operação normal. Dois caminhos independentes notam que um ticket se moveu (uma notificação ao vivo e uma comparação completa periódica, que é o que torna o espelho inegável), e um reenvio manual pela nossa equipe reutiliza o `eventId` original de propósito.
Trate um evento cujo id você já processou como um no-op e responda `2xx` — um `409` do seu lado parece uma entrega falhada para nós e é reprocessado.
## Ordenação
**A ordenação não é garantida.** Um evento reprocessado chega após eventos criados depois dele, e duas mudanças a segundos de diferença podem chegar em qualquer ordem. `sequence` informa qual evento foi *criado* primeiro, então você pode descartar um que já foi superado — mas não é a ordem de entrega, e você não deve reconstruir o estado a partir do stream. Quando importa, leia o ticket.
A regra que mantém um consumidor correto: **leia o ticket quando você receber um evento.** O evento informa que *algo* se moveu; `GET /api/partners/tickets/{key}` informa o que é verdade agora.
## Reprocessamentos
Uma entrega é bem-sucedida em qualquer `2xx`. Qualquer outro status, um erro de conexão, ou nenhuma resposta dentro de 8 segundos conta como uma falha e é reprocessada com backoff:
| Tentativa | Enviada |
| --- | --- |
| 1 | Imediatamente, quando o evento é criado |
| 2 | ~30 segundos depois |
| 3 | ~2 minutos depois |
| 4 | ~10 minutos depois |
| 5 | ~1 hora depois |
| 6 | ~6 horas depois |
**Seis tentativas no total.** Após a sexta falha, a entrega é marcada como falhada e não é reprocessada automaticamente — pergunte-nos e podemos reenviá-la manualmente, com o mesmo `eventId`.
Os atrasos são quando um reprocessamento se torna *devido*; a passagem de reprocessamento roda em uma programação própria, então as duas primeiras tentativas podem chegar um pouco mais tarde do que o atraso nominal. Cada tentativa é registrada do nosso lado — o que enviamos, o que voltou, e quantas vezes tentamos — então "você realmente enviou?" tem uma resposta que não é um palpite.
## Reconciliando uma entrega perdida
Se seu endpoint estiver fora do ar por mais tempo do que a janela de reprocessamento, ou se você quiser verificar se nada escapou, `GET /api/partners/tickets/{key}/events` retorna o histórico do ticket — mudanças de status, prioridade e prazo, nossas respostas públicas e a resolução, da mais antiga para a mais recente, cada uma com sua data. Ele usa os mesmos nomes de eventos que o webhook (`ticket.status_changed`, `ticket.priority_changed`, `ticket.message_added`, `ticket.resolved`), então você pode combinar o que recebeu com isso. Uma diferença a esperar: um status lá é o nome que o portal de suporte mostra — o mesmo que `GET /api/partners/tickets/{key}` retorna — não o bucket `state` do webhook, e seu tempo é quando a mudança foi feita em vez do nosso `occurredAt`. Como toda leitura, não conta contra sua cota de tickets.
## Lista de verificação antes de entrar em produção
- Verifique a assinatura sobre o **corpo bruto**, e rejeite em caso de discrepância.
- Rejeite um `t` mais velho que cinco minutos.
- De-duplicate em `eventId` antes de fazer qualquer trabalho.
- Responda `2xx` rapidamente, processe de forma assíncrona.
- Releia o ticket em vez de confiar na ordem dos eventos.
- Reconcile contra `GET /api/partners/tickets/{key}/events` após uma interrupção do seu lado.
- Envie um `webhook.test` para cada endpoint e veja-o verificado antes de habilitá-lo.
- Mantenha o segredo fora do controle de versão, e renove-o com `PATCH … { "rotateSecret": true }` se vazar.
## Criando um caso de uso do zero
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/use-case.md
## Propósito
Este artigo é um guia passo a passo para construir um aplicativo de exemplo simples que integra com o Pluggy. A ideia deste guia é juntar todos os conceitos importantes do Pluggy em um exemplo prático.
## O que vamos construir
Vamos construir uma aplicação PFM (gestão financeira pessoal) simples que mostra um relatório dos movimentos da sua conta bancária divididos por categorias.
Você pode conferir o código no [repositório do projeto](https://github.com/pluggyai/my-expenses).
## Passo 1: Criando uma conta Pluggy
Primeiro, precisaremos de uma conta Pluggy para poder conectar contas bancárias com nosso aplicativo e recuperar dados bancários com a Referência da API Pluggy. Precisamos nos inscrever no [dashboard](https://dashboard.pluggy.ai).
## Passo 2: Criando uma aplicação no dashboard
Uma vez que temos nossa conta, precisaremos criar uma aplicação no dashboard. Uma aplicação tem um conjunto de credenciais (**clientId** e **clientSecret**) que nosso aplicativo usará para interagir com a API.
## Passo 3: Testando a API
Para verificar se estamos configurados corretamente, vamos obter uma chave de API para interagir com a Referência da API Pluggy. Isso é feito através do endpoint [`/auth`](/reference/auth-create). Você pode baixar a [coleção do Postman](/docs/run-in-postman) e preencher o client id e o client secret da sua aplicação.
Com essa chave de API, podemos visualizar e gerenciar todos os dados do Pluggy para nossa aplicação (PluggyMyExpenses). Vamos testar nossa chave de API invocando o endpoint [`/connectors`](/reference/connectors-list), incluindo a chave no cabeçalho `X-API-KEY`. Para saber mais sobre Autenticação com a Referência da API Pluggy, confira [Autenticação](/docs/authentication).
## Passo 4: Criando nosso projeto
Neste aplicativo de exemplo, usaremos [Next.js com Typescript](https://nextjs.org/docs/basic-features/typescript), mas você pode usar qualquer tecnologia com a qual esteja mais familiarizado.
## Passo 5: Conectando uma conta bancária
Para permitir que os usuários conectem suas contas facilmente em nosso frontend, podemos usar o [Pluggy Connect Widget](/docs/pluggy-connect-introduction) e abri-lo com um botão em nossa página.
Antes de podermos instanciar o widget, precisaremos criar um **endpoint de Backend** que gera um Connect token para cada usuário que visita nossa página. Este connect token tem permissões e duração restritas por motivos de segurança. A lógica do nosso endpoint seria algo assim:
```typescript
import { PluggyClient } from 'pluggy-sdk'
const PLUGGY_CLIENT_ID = process.env.PLUGGY_CLIENT_ID || ''
const PLUGGY_CLIENT_SECRET = process.env.PLUGGY_CLIENT_SECRET || ''
// ...
const client = new PluggyClient({
clientId: PLUGGY_CLIENT_ID,
clientSecret: PLUGGY_CLIENT_SECRET,
});
const connectToken = await client.createConnectToken()
// ...
res.status(200).json(connectToken)
```
Para criar connect tokens facilmente, usamos o [Pluggy Node SDK](https://github.com/pluggyai/pluggy-node/).
**Não** armazene clientId e clientSecret no frontend. Se essas informações forem visíveis no código da sua página, um atacante pode roubar todos os dados bancários dos seus usuários.
Agora que temos nosso endpoint de connect token, podemos obtê-lo em nosso frontend e instanciar o widget quando o usuário clicar em um botão, assim:
```typescript
import { PluggyConnect } from 'react-pluggy-connect';
// Buscar connect token do backend e armazená-lo em 'connectToken'...
{isWidgetOpen ? (
setIsWidgetOpen(false)}
onSuccess={onSuccess}
/>
) : (
)}
```
Aqui usamos o [React Pluggy Connect SDK](https://www.npmjs.com/package/react-pluggy-connect).
Se você estiver tentando usar o widget de uma página Next.js, precisará mudar um pouco como o Widget carrega. Confira no código [aqui](https://github.com/pluggyai/my-expenses/blob/5a1b314d07052d3ac43fae17ab2ac44760de6eb4/pages/index.tsx#L6).
Agora, quando nosso usuário clicar em Conectar minha conta, um Connect token é obtido e o Connect Widget é instanciado com esse token e abre um modal para o usuário inserir suas credenciais.
Uma vez que a conta bancária se conecta com sucesso, seus dados bancários estarão disponíveis na Referência da API Pluggy para recuperação com as credenciais da nossa aplicação.
Se você quiser experimentar e conectar uma conta de teste, pode usar os [connectors de sandbox](/docs/sandbox). Agora, vamos fazer algo interessante com esses dados!
## Passo 6: Usando os dados bancários
Uma vez que o usuário conecta sua conta, podemos obter seus dados da API. Todos os dados recuperados do usuário estão associados a um [Item](/docs/item). Assim que o widget terminar, ele emite um evento onSuccess, com o id do Item recém-criado.
Para qualquer ação que você queira realizar no futuro com os dados bancários conectados, você precisará do ID do Item (esse valor não pode ser recuperado depois). Certifique-se de armazená-lo ouvindo o evento `onSuccess` do widget.
Podemos ouvir esse evento e informar ao backend para buscar os dados do usuário e criar o relatório para nosso PFM:
```typescript
const onSuccess = async (itemData: { item: any; }) => {
const reportResponse = await fetch('/api/report?itemId=' + itemData.item.id)
const {categoryBalances, startDate} = await reportResponse.json()
setIsWidgetOpen(false) // Fecha o widget
// ...
}
```
```typescript
import { PluggyClient } from 'pluggy-sdk';
const PLUGGY_CLIENT_ID = process.env.PLUGGY_CLIENT_ID || '';
const PLUGGY_CLIENT_SECRET = process.env.PLUGGY_CLIENT_SECRET || '';
const client = new PluggyClient({
clientId: PLUGGY_CLIENT_ID,
clientSecret: PLUGGY_CLIENT_SECRET,
});
// ...
// Neste exemplo, colocamos todas as transações de todas as contas em uma lista
const accounts = await client.fetchAccounts(req.query.itemId as string);
const transactions = [];
for (const account of accounts.results) {
const accountTransactions = await client.fetchAllTransactions(account.id);
transactions.push(...accountTransactions);
}
// Então podemos fazer o que precisamos com os dados e retornar a resposta
```
Do relatório de backend, podemos criar uma tabela bonita e mostrar ao usuário seus movimentos por categoria.
## Passo 7: Atualizando os dados bancários
Na primeira vez que um usuário conecta sua conta usando o Widget, o Pluggy tentará recuperar dados bancários de até 1 ano atrás (ou o quanto a instituição permitir). Se quisermos atualizar os dados bancários do usuário sem recuperá-los tudo novamente, apenas recuperando novas informações, podemos simplesmente atualizar o Item. Podemos fazer isso facilmente instanciando o widget com a prop updateItem definida
```typescript
setIsWidgetOpen(false)}
onSuccess={onSuccess}
updateItem={itemIdToUpdate} // ID do Item que obtivemos ao criar a conexão
/>
```
Uma vez que o item foi atualizado, o widget emite o evento onSuccess e podemos criar nosso relatório novamente, com o item atualizado.
## Passo 8: Armazenando dados bancários
Se precisarmos analisar os dados bancários de todos os nossos usuários conectados (isso é ideal para aplicativos de pontuação de crédito), acelerar o carregamento e fazer backup dos dados bancários em caso de uma falha na API, provavelmente precisaremos configurar nosso próprio banco de dados. Você pode usar qualquer tecnologia e abordagem que seu negócio precisar. No nosso código de exemplo, usamos Supabase (PostgreSQL) e salvamos os dados do item toda vez que a criação de um Item é bem-sucedida. Se você estiver interessado em como fizemos isso, dê uma olhada no [repositório do projeto](https://github.com/pluggyai/my-expenses).
## Passo 9: Reagindo a eventos da API
Até agora, reagimos ao onSuccess do widget para informar ao nosso backend que um Item foi criado. Mas e se o usuário sair da página antes que o Item seja criado? Ou e se quisermos manter nossos itens atualizados sem interação do usuário (para instituições que permitem isso)?
Se quisermos cobrir esses casos de uso, podemos usar os [webhooks](/docs/webhooks) do Pluggy.
Dessa forma, podemos configurar um endpoint em nosso backend que o Pluggy chamará sempre que um item for criado ou atualizado. Receberemos um payload que se parece com isso:
```json
{
"event":"item/updated",
"id":"a5c763cb-0952-457b-9936-630f79c5b016",
"itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
"triggeredBy": "USER"
}
```
E podemos manipulá-lo a partir do nosso endpoint `/items`.
Então precisamos criar o webhook usando o endpoint [POST /webhooks](/reference/webhooks-create) da Referência da API Pluggy.
```json
{
"event": "item/updated",
"url": "https://{YOUR_APP_URL}/api/items"
}
```
## Considerações finais
Parabéns! Você agora está pronto para usar sua aplicação alimentada pelo Pluggy!
## Checklist de Integração do Pluggy
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/overview.md
Este guia o ajudará no processo de integração do Pluggy em seu APP e fornecerá um conjunto de pontos que você deve seguir para uma integração bem-sucedida ao lançar o Pluggy em produção.
## Obtenha suas chaves da API
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/api-keys.md
Para começar a integrar com o Pluggy, inscreva-se para uma conta no [Dashboard](https://dashboard.pluggy.ai/).
Quando você fizer isso, você também criará uma **Equipe**, onde poderá convidar outras pessoas para colaborar também.
No Dashboard do Pluggy, você pode gerenciar tudo relacionado à sua integração com o Pluggy. Isso inclui visualizar os itens criados e seu status, consultar o status de nossos Connectors e mais.
## Criando sua primeira Aplicação
Na aba [Applications](https://dashboard.pluggy.ai/applications), crie sua primeira Aplicação.
Uma vez criada, você receberá um par de credenciais `CLIENT_ID` e `CLIENT_SECRET`.
Essas credenciais darão acesso aos dados financeiros dos usuários, portanto, é essencial tomar todas as medidas possíveis para armazená-las com segurança e nunca compartilhá-las publicamente.
Com esta Aplicação, você está pronto para começar a Criar Itens.
## Revise nossa Documentação
Neste ponto, recomendamos que você revise nosso [Glossary](/docs/glossary), onde explicamos os conceitos principais que usaremos daqui para frente.
## Crie seu primeiro Item
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/first-item.md
Com sua Aplicação recém-criada, você está pronto para criar seu primeiro Item.
### Aplicação de Demonstração
Para ter uma noção rápida de como nossa API funciona, você pode usar nossa aplicação **Demo** totalmente funcional imediatamente.
Para abri-la, basta ir para [Dashboard](https://dashboard.pluggy.ai/) → [Applications](https://dashboard.pluggy.ai/applications) → encontrar sua Aplicação e clicar no link "**Preview in Demo**".
Com esta aplicação, você pode ter uma compreensão rápida de como nossa API funciona, pois é um exemplo do potencial que uma integração com a Pluggy pode alcançar.
Aqui, você também pode revisar como os dados coletados pela nossa API na Instituição Financeira se parecem, tanto de uma maneira amigável ao usuário, quanto em formatos de arquivo JSON/CSV/XLS.
### Conta Sandbox
Se preferir, você pode criar um Item conectando uma conta usando nosso Connector Sandbox ("Pluggy Bank").
Para conectar uma conta com nosso Connector Sandbox, você pode usar nossos **Test Users**.
O conjunto básico de credenciais para um login bem-sucedido é:
Usuário: `user-ok`
Senha: `password-ok`
Token MFA / 2FA (se aplicável): `123456`
Ao usar um Connector Sandbox (Pluggy Bank), você pode testar qualquer um dos fluxos de login e cenários que também encontraria ao usar qualquer um dos Connectors Live disponíveis.
Isso cobre diferentes cenários, como erro de credenciais inválidas, site não disponível, fluxos de login MFA, etc. Todos os fluxos de login e credenciais do Sandbox podem ser encontrados [aqui](/docs/sandbox).
## Use nossos SDKs para Autenticar
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/sdk-auth.md
## Autentique-se com a Referência da API Pluggy
Usando suas credenciais de Aplicação `CLIENT_ID` e `CLIENT_SECRET`, é hora de configurar a autenticação.
Vamos criar uma `API key`! Com isso, você poderá acessar o restante dos endpoints disponíveis em nossa API, como recuperar dados de Connectors, criar um Connect Token, recuperar dados financeiros do usuário coletados de Items conectados, e [mais](/reference/auth).
Como todas essas credenciais são muito sensíveis, isso deve ser feito em uma aplicação Backend (lado do servidor). Sempre mantenha suas chaves seguras!
Para esta etapa, recomendamos usar um de nossos SDKs para ajudar a facilitar essa tarefa.
Na nossa [referência da API do endpoint Auth](/reference/auth-create), você encontrará exemplos de código para realizar essa solicitação, usando suas credenciais de Aplicação.
Crie um script em seu servidor que troque as credenciais da Aplicação por uma chave da API Pluggy.
Se feito corretamente, você deve obter uma resposta de chave da API (`accessToken`).
Para validar se você está efetivamente autenticado, tente usá-la para recuperar nossa lista de [Connectors](/reference/connector), chamando nosso [endpoint GET /connectors](/reference/connectors-list).
## Revise nossos SDKs
Fornecemos SDKs para diferentes plataformas que estão prontos para você usar. Usá-los pode economizar muito tempo e esforço! Em nossos SDKs, já resolvemos para você todos os detalhes relacionados à autenticação, formatos de solicitação/resposta e tratamento de erros; assim você pode se concentrar em trabalhar em sua integração imediatamente.
### Lado do Servidor
Revise se um de nossos SDKs já desenvolvidos funciona para a integração do backend da sua aplicação.
Você pode conferir esses em nossa [docs](/docs/server-side-sdks):
- NodeJS: [GitHub](https://github.com/pluggyai/pluggy-node) | [npmjs.com](https://www.npmjs.com/package/pluggy-sdk)
- C# .NET: [GitHub](https://github.com/pluggyai/pluggy-net) | [Nuget](https://www.nuget.org/packages/Pluggy.SDK/)
- Java: [GitHub](https://github.com/pluggyai/pluggy-java)
Se você precisar de um SDK que ainda não estamos fornecendo para algum outro idioma, por favor, nos avise!
Sinta-se à vontade para explorar a documentação fornecida pelo SDK e os exemplos que cada projeto contém como uma visão rápida de como implementá-lo.
### Sem um SDK
Se você deseja criar sua própria integração ou não há um SDK para seu idioma específico, você pode facilmente se conectar à nossa API usando solicitações HTTP REST.
Confira nossa [coleção Postman](https://app.getpostman.com/run-collection/e3c01977e43b12525b70) como um guia para começar, configurando seu `CLIENT_ID` e `CLIENT_SECRET` da Aplicação, e comece a fazer solicitações para nossa API.
Este [guia detalhado](/docs/run-in-postman) em nossa Docs também está disponível, para ajudá-lo a entender passo a passo como interagir com a coleção do Postman.
### Quickstarts
Para ajudá-lo a começar imediatamente com uma de nossas soluções pré-construídas, você pode usar um de nossos quickstarts, disponíveis em nosso repositório [GitHub quickstarts](https://github.com/pluggyai/quickstart).
Se você estiver usando `vercel` como seu provedor, pode fazer uma implantação com um clique para configurar um backend na nuvem.
## Configurar o Pluggy Connect Widget no seu aplicativo
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/setup-widget.md
O **Connect Widget** é a solução frontend plug & play da Pluggy que permite aos usuários conectar suas contas financeiras em um fluxo passo a passo, para que você só precise se preocupar em interagir com seus dados em vez de se preocupar com fluxos de login complicados.
Confira nossa documentação do Pluggy Connect Widget [docs](/docs/pluggy-connect-introduction) para mais informações!
## Criar um endpoint ConnectToken
Primeiro, você precisará configurar um endpoint em seu backend que será responsável por obter e fornecer um `Connect Token`. Este token será usado para conceder autorização ao PluggyConnect para acessar a API da Pluggy em nome de sua Aplicação.
Esse processo deve ser feito em seu backend, uma vez que o [Criar ConnectToken](/reference/connect-token-create) (`POST /connect_token`) requer autenticação na API da Pluggy (obtendo uma chave de API válida, usando o `CLIENT_ID` e `CLIENT_SECRET` de sua Aplicação).
### Início rápido com Vercel
Se você usar **Vercel**, fornecemos uma solução de um clique que você pode usar imediatamente, implantando este endpoint diretamente do nosso [exemplo em nossos Inícios Rápidos](https://github.com/pluggyai/quickstart/tree/master/examples/vercel-node-connect-token) repositório.
Você só precisará configurar as variáveis de ambiente `PLUGGY_CLIENT_ID` e `PLUGGY_CLIENT_SECRET`.
Pronto! Agora, você pode buscar seu Connect Token de `https://YOUR-APP-NAME.vercel.app/api/token`.
**Dica:** você também pode especificar opções do endpoint Connect Token, como especificar **clientUserId**, chamando este endpoint com `POST` em vez de `GET`, assim:
```tsx
// substitua YOUR-APP-NAME pela sua URL implantada
fetch('https://YOUR-APP-NAME.vercel.app/api/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
options: { clientUserId: 'user-123@mail.com' }
})
})
.then(response => response.json())
.then(data => console.log(data))
// o console irá registrar:
// {"accessToken":"eyJhbGciOiJSUzI1NiIsInR5c... "}
.catch(error => console.error(error));
```
## Configurar e Lançar PluggyConnect
Com seu endpoint Connect Token implantado, você está pronto para integrar o PluggyConnect em sua aplicação do lado do cliente.
### Revise nossos exemplos de Início Rápido
Temos um conjunto de exemplos documentados e totalmente funcionais [Exemplos de Frontend](https://github.com/pluggyai/quickstart/tree/master/frontend) que você pode clonar e começar a usar imediatamente e lançar nossa interface Pluggy Connect. Você só precisa substituir a URL do endpoint ConnectToken pela sua própria.
Você encontrará exemplos com frameworks e plataformas populares, como:
- React
- NextJS
- HTML+JS simples
- Flutter
- ReactNative
- iOS
### Opções e Configurações
Para personalizar melhor sua experiência, confira as diferentes configurações disponíveis em [nossa documentação](/docs/environments-and-configurations).
Você encontrará opções para filtrar tipos de conectores, definir o idioma do widget e se inscrever nos diferentes callbacks de eventos que seriam acionados com base em diferentes ações e eventos do usuário.
## Sincronização de dados: Atualizar um Item
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/data-sync.md
## Mantendo Conexões Sincronizadas
Quando você cria um Item, você terá uma referência aos dados financeiros do usuário, que inicialmente incluirá todos os dados da Instituição dos **últimos 365 dias**.
Para manter essas informações atualizadas, é possível **Atualizar** um Item, que sincronizará os dados da sua conexão armazenados no Pluggy com a Instituição Financeira até aquele momento. Cada Sincronização recuperará as informações transacionais da última data sincronizada (campo `lastUpdatedAt` do item), com uma janela de retrocesso que varia de acordo com o tipo de conector:
- **Conectores diretos:** 4 a 5 dias corridos a partir da última sincronização. Essa janela mais ampla garante que transações postadas em finais de semana ou feriados bancários - que podem parecer atrasadas - sejam capturadas nos dias úteis seguintes.
- **Conectores de Open Finance (regulados):** 7 dias corridos incluindo hoje (hoje + os 6 dias anteriores), de acordo com as regras de reconciliação do ecossistema regulado de Open Finance.
Para manter essas informações atualizadas, *Pluggy* sincronizará (**Atualizar**) seus dados automaticamente todos os dias, você não precisará se preocupar em criar um processo em lote ou qualquer rotina para manter os dados atualizados.
*Processos em lote são proibidos devido ao uso abusivo da API, o processo de sincronização é de responsabilidade e manutenção do Pluggy. Por favor, nos solicite qualquer personalização que você possa precisar para isso.*
Se um usuário requer uma Atualização em tempo real, você pode acionar uma **Atualização** manual que começará naquele exato momento. Essa ação pode ser realizada de duas maneiras:
## Atualizar o Item usando o Connect Widget do Pluggy
Para atualizar um Item existente usando o Pluggy Connect, basta fornecer o ID do item através do campo de configuração `itemId`. Isso abrirá o widget em "Modo de Atualização", acionando os passos necessários para iniciar o processo de atualização.
O Pluggy Connect, como uma solução totalmente funcional, já cobre todas as especificidades e cenários potenciais relacionados aos diferentes fluxos de login de todos os conectores, casos especiais e mais. Isso inclui cenários como:
- Se o item não requer um parâmetro MFA, então o PluggyConnect apenas iniciará o processo de atualização e a coleta de dados prosseguirá.
- Se requer um parâmetro MFA, então o PluggyConnect solicitará ao usuário. Após o usuário resolver, o processo de atualização começará e a coleta de dados prosseguirá.
- Se o Item teve um erro de credenciais inválidas, então o PluggyConnect pedirá as credenciais primeiro.
Você pode testar e validar todos os cenários mencionados, e mais, usando nossas Contas de Teste em nossos conectores [Sandbox](/docs/sandbox) (Pluggy Bank).
## Atualizar Item via API diretamente
Se o item não requer um parâmetro MFA, e não tem um erro de credenciais inválidas, então é possível atualizá-lo diretamente via API, uma vez que não são necessárias mais ações do usuário.
Caso contrário, a atualização do Item resultará em um estado de espera (para a ação do usuário). Essa ação deve ser solicitada ao usuário na interface do seu aplicativo, da mesma forma que o PluggyConnect faz, e resolvê-la de acordo com as ações do usuário, e então passá-las de volta para a API do Pluggy.
Confira nosso guia [Atualizando um Item](/docs/updating-an-item), onde fornecemos mais detalhes e insights sobre esse processo.
## Configurar sincronização bidirecional com Webhooks
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/webhooks-sync.md
## O que são Webhooks?
Webhooks permitem que a Pluggy notifique sua aplicação sobre eventos sem que você precise solicitar atualizações, mantendo você atualizado com as últimas mudanças nos itens que você criou.
## Configurando Webhooks
Você pode configurar Webhooks de duas maneiras:
- Usando o [Dashboard](https://dashboard.pluggy.ai/) da Pluggy: Vá para [Aplicações](https://dashboard.pluggy.ai/applications), em seguida clique no ícone "Editar" para sua aplicação. Role para baixo até a seção "Webhooks", onde você pode registrar novos webhooks e visualizar, editar ou excluir os existentes.
- Usando nossa API diretamente: Configure URLs de notificação específicas para cada evento particular ou configure um único ponto de escuta para todos os eventos usando um cliente HTTP como o Postman.
Por favor, consulte nosso [Guia de Webhooks](/docs/webhooks) para mais informações sobre como configurar Webhooks, payloads, tipos de eventos e solicitações disponíveis.
## Recebendo Notificações
Uma vez que você tenha configurado os webhooks, valide se todos os tipos de eventos estão sendo recebidos conforme esperado. É importante ter validado com sucesso que cada evento foi recebido.
Para testar isso, você pode usar ferramentas como [requestcatcher.com](http://requestcatcher.com/) para confirmar que as notificações estão sendo enviadas corretamente.
### Responda rapidamente com um código de status 2xx
Para reconhecer a recepção do evento de notificação, seu endpoint deve retornar um código HTTP `2xx` para a Pluggy. Se a Pluggy receber qualquer outro código de status, isso indicará que você não recebeu o evento.
Se a Pluggy não receber uma resposta bem-sucedida, a notificação do evento será tentada novamente. Após várias falhas ao enviar o evento, marcaremos a notificação como falhada e a notificação será perdida.
Como é muito importante confirmar a recepção do evento, seu endpoint deve retornar uma resposta de sucesso antes de realizar qualquer lógica de negócios que possa resultar em um erro.
## Gerenciamento de consentimento: Excluir um Item
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/consent-management.md
Cumprir esse processo é fácil: a partir do seu Backend, basta chamar o [endpoint Deletar Item](/reference/items-delete) da Pluggy (`DELETE /items/{itemId}`). Se bem-sucedido, uma resposta de status `204` será enviada. Isso confirma que o Item que contém todas as referências aos dados financeiros do usuário foi deletado.
Qualquer chamada subsequente ao endpoint `GET /items/{itemId}` para tentar recuperar os dados deste item, ou para qualquer endpoint que retornaria os produtos financeiros relacionados ao Item, retornará uma resposta HTTP `404 Not Found`.
Certifique-se de implementar essa opção em sua integração e mantê-la sempre disponível para seus usuários, a fim de estar em conformidade com as regulamentações de Open Banking.
## Inscreva-se na nossa Página de Status
Source: https://docs.pluggy.ai/pt/docs/integration-checklist/status-page.md
Confira nossa [página de status](https://status.pluggy.ai/) pública, onde postamos qualquer incidente e interrupções, para que você possa ficar ciente de quaisquer problemas existentes.
Além disso, por favor, inscreva-se usando o botão no topo para ser notificado sobre incidentes assim que eles acontecerem.
Estaremos postando incidentes quando ocorrerem, analisando impactos, conectores afetados e quanto tempo levará para voltar ao normal.
## Canais de anúncio do Slack
Também fornecemos atualizações ao vivo e anúncios de incidentes e mais via Slack.
Se você ainda não nos pediu para configurar uma colaboração direta em um canal do Slack, recomendamos fortemente que o faça! É a maneira mais eficiente e direta que temos de comunicar notícias, incidentes e fornecer ajuda.
## Atualizações de SDKs
Estamos sempre fornecendo correções e recursos para nossos SDKs. É importante estar atualizado com essas mudanças. Recomendamos que você se inscreva no repositório do GitHub do respectivo SDK, se estiver usando um deles.
## API de Gerenciamento de Boleto
Source: https://docs.pluggy.ai/pt/docs/boleto/management-api.md
A boleto é o comprovante de pagamento emitido por bancos no Brasil: você registra uma cobrança com um banco, o banco retorna um código de barras e uma linha digitável, e seu pagador o quita em qualquer banco, caixa eletrônico ou aplicativo. Registrar um boleto normalmente significa integrar-se com cada banco separadamente — diferentes autenticações, diferentes nomes de campos, diferentes noções de como um boleto "pago" se parece.
A API de Gerenciamento de Boletos é uma interface uniforme sobre todos eles. Você registra uma cobrança uma vez, em uma única forma, e nós a traduzimos para a instituição com a qual seu cliente tem conta.
Esta API está em BETA. Inter Empresas está disponível hoje; veja [Instituições suportadas](#supported-institutions) para o que está ativo e o que está por vir.
## Como tudo se encaixa
Dois objetos. Uma **Conexão de Boleto** contém as credenciais que nos permitem agir em uma instituição em nome do seu cliente, e é criada uma vez. Cada **Boleto** é então emitido contra essa conexão.
```mermaid
graph LR
subgraph Uma vez por cliente
A[Item conta bancária conectada] --> B[Conexão de Boleto]
A2[Credenciais brutas] --> B
end
subgraph Muitas vezes
B --> C[Boleto #1]
B --> D[Boleto #2]
B --> E[Boleto #3]
end
```
Você pode criar uma conexão a partir de um [Item](/docs/connect-widget/introduction) existente — o mesmo objeto que você já usa para dados — ou enviando [credenciais diretamente](/reference/boleto-connection-create) quando não há Item para reutilizar.
## O ciclo de vida de um boleto
Um boleto começa `ABERTO` e se move em uma direção. `PAGO` e `CANCELADO` são terminais: nada sai deles, e um boleto nunca retorna a `ABERTO`.
```mermaid
stateDiagram-v2
[*] --> ABERTO: criado
ABERTO --> PAGO: pagador quita
ABERTO --> VENCIDO: data de vencimento passa
ABERTO --> CANCELADO: você cancela
VENCIDO --> PAGO: pago atrasado
VENCIDO --> PROTESTADO: enviado para protesto
VENCIDO --> CANCELADO: você cancela
PROTESTADO --> PAGO: quitado após protesto
PROTESTADO --> CANCELADO: você cancela
PAGO --> [*]
CANCELADO --> [*]
```
| Status | O que significa |
|---|---|
| `ABERTO` | Registrado no banco e pagável. |
| `PAGO` | Quitado. `amountPaid` e `paymentOrigin` estão preenchidos. |
| `VENCIDO` | Atrasado e ainda pagável — a maioria dos bancos aceita pagamento atrasado. |
| `CANCELADO` | Retirado por você. Não pode mais ser pago. |
| `PROTESTADO` | Enviado para protesto após não ser pago. Ainda pode ser quitado. |
`amountPaid` é o que o pagador realmente pagou, e pode diferir de `amount` — um pagador pode quitar um boleto com desconto, ou com multa e juros aplicados após a data de vencimento. Sempre concilie contra `amountPaid`, nunca contra o valor que você solicitou.
## O fluxo de ponta a ponta
Emitir um boleto é uma única chamada. Saber que ele foi pago é um webhook — você não faz polling.
```mermaid
sequenceDiagram
autonumber
participant You as Seu sistema
participant Pluggy
participant Bank
actor Payer
You->>Pluggy: POST /boletos
Pluggy->>Bank: registrar a cobrança
Bank-->>Pluggy: nossoNumero, código de barras, linha digitável
Pluggy-->>You: 201 { id, status: ABERTO, ... }
Note over You,Payer: você entrega o boleto como preferir
Payer->>Bank: paga o boleto
Bank->>Pluggy: notificação de quitação
Pluggy->>You: webhook boleto/atualizado
You->>Pluggy: GET /boletos/{id}
Pluggy-->>You: { status: PAGO, amountPaid, paymentOrigin }
```
O webhook informa que *algo* mudou, não *o que*. Ele carrega o id do boleto, e você busca o boleto para ver seu novo estado. Isso mantém a notificação pequena e significa que um webhook que você recebe duas vezes é inofensivo.
## Começando
Chame [POST /auth](/reference/auth-create) com as credenciais do seu aplicativo.
```json
{
"clientId": "{YOUR-CLIENT-ID}",
"clientSecret": "{YOUR-CLIENT-SECRET}"
}
```
A partir de um Item existente, com [POST /boleto-connections/from-item](/reference/boleto-connection-create-from-item):
```json
{
"itemId": "{YOUR-ITEM-ID}"
}
```
A resposta traz o id contra o qual você emitirá:
```json
{
"id": "dc3537ad-13b4-4770-b248-e4578983899c",
"connectorId": 225,
"createdAt": "2023-01-01T00:00:00.000Z",
"updatedAt": "2023-01-01T00:00:00.000Z"
}
```
[POST /boletos](/reference/boleto-create). `amount` está em reais, `dueDate` é `YYYY-MM-DD`:
```json
{
"boletoConnectionId": "{YOUR-BOLETO-CONNECTION-ID}",
"boleto": {
"seuNumero": "1234567891",
"amount": 2.5,
"dueDate": "2025-03-01",
"payer": {
"taxNumber": "1234567890",
"name": "Nome de exemplo",
"addressState": "SP",
"addressZipCode": "01239030",
"addressCity": "Não informado",
"addressStreet": "Não informado"
}
}
}
```
`seuNumero` é *sua* referência para a cobrança — um número de fatura, um id de pedido. Ele retorna em cada leitura e na notificação de quitação, então use algo que você possa conciliar.
A resposta inclui tudo que um pagador precisa:
```json
{
"id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
"boletoConnectionId": "91d4d8d8-8477-423e-9888-0bbbde2da64a",
"amount": 2.5,
"status": "ABERTO",
"seuNumero": "1234567891",
"dueDate": "2025-03-01",
"pixQr": "00020126490014br.gov.bcb.pix0108dict-key...",
"digitableLine": "01120001161117012359902128847071234570777000110",
"nossoNumero": "10000004701",
"barcode": "01120001161117012359902128847071234570",
"amountPaid": null,
"paymentOrigin": null
}
```
`digitableLine` é o número de 47 dígitos que um pagador digita em seu aplicativo bancário, `barcode` é o que um scanner lê, e `pixQr` é um payload PIX para a mesma cobrança — a maioria dos bancos agora emite boletos pagáveis de qualquer forma.
Inscreva-se em `boleto/atualizado` em [webhooks](/docs/developer-tools/webhooks-ref) e você receberá:
```json
{
"boletoId": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
"eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
"event": "boleto/updated"
}
```
Então [GET /boletos/{id}](/reference/boleto-get). Um boleto quitado lê:
```json
{
"id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
"status": "PAGO",
"amount": 2.5,
"amountPaid": 2.5,
"paymentOrigin": "PIX",
"seuNumero": "1234567891"
}
```
Você pode cancelar um boleto não pago a qualquer momento com [POST /boletos/{id}/cancel](/reference/boleto-cancel).
## Instituições suportadas
Inter Empresas e o conector [Sandbox](/docs/boleto/sandbox) estão disponíveis hoje; Bradesco está em construção. Quais instituições estão ativas, como cada uma autoriza uma conexão e os comportamentos que vale a pena conhecer por banco estão todos em um só lugar: [Cobertura](/docs/boleto/coverage).
## Antes de você entrar em produção
- **Concilie com `amountPaid`, não com `amount`.** Multas, juros e descontos significam que eles diferem.
- **Trate webhooks como pelo menos uma vez.** O mesmo `boletoId` pode chegar duas vezes; `eventId` identifica a entrega se você quiser deduplicar.
- **Armazene `seuNumero` do seu lado.** É sua única ligação entre um boleto e o que quer que ele esteja pagando.
- **Não analise `nossoNumero` para significado.** Seu formato é do banco e difere entre instituições.
## Cobertura
Source: https://docs.pluggy.ai/pt/docs/boleto/coverage.md
Cada instituição na [Referência da API de Gestão de Boletos](/docs/boleto/management-api) fala a mesma API: uma solicitação para registrar uma cobrança, uma forma de resposta, um conjunto de status, um webhook `boleto/updated`. O que difere entre os bancos é como uma **Conexão de Boleto** é estabelecida — o que seu cliente precisa fornecer e se ele fornece a você ou ao banco.
A API está em BETA. Inter Empresas é o único banco real disponível hoje, e o Sandbox permite que você teste sem um; o restante desta página diz o que está por vir e o que mudará quando isso acontecer.
## Instituições
| Instituição | Status | Autenticação | Conectar via |
|---|---|---|---|
| Inter Empresas | **Live** | Client ID, Client Secret, chave privada e certificado, criados no Internet Banking do Inter — veja o [tutorial do Banco Inter Empresas](/docs/developer-tools/tutorials/inter-pj) | Um Item existente ([POST /boleto-connections/from-item](/reference/boleto-connection-create-from-item)), ou as credenciais enviadas diretamente ([POST /boleto-connections](/reference/boleto-connection-create)) |
| Bradesco | Em desenvolvimento | Nada do seu cliente — Pluggy é um parceiro do Bradesco. Cada empresa concede uma autorização única dentro do próprio ambiente do Bradesco, confirmada com uma chave de segurança. Não é possível através de uma API | Um redirecionamento para o Bradesco e de volta; o fluxo não está ativo |
| Sandbox | **Live** | Nenhuma — emite boletos que parecem reais e os move para o status que você escolher, pelos centavos do valor | [POST /boleto-connections](/reference/boleto-connection-create) com conector `8` e credenciais vazias |
IDs dos conectores, para [GET /connectors](/reference/connectors-list): Inter Empresas `225`, Bradesco `285`, Sandbox `8`.
## Inter Empresas
Inter é a implementação de referência: tudo abaixo acontece por trás dos mesmos endpoints descritos no guia da [Referência da API de Gestão de Boletos](/docs/boleto/management-api).
**Credenciais.** O Inter autentica com quatro artefatos — um Client ID, um Client Secret, uma chave privada e um certificado — criados dentro do próprio Internet Banking do Inter. Ao criar a integração no Inter, habilite os escopos **Boleto** e **Extrato**: uma credencial sem o escopo Boleto conecta com sucesso e depois falha na primeira tentativa de emissão, que é um lugar confuso para descobrir o problema.
**Duas maneiras de conectar.** Passar por um Item é o melhor padrão quando você já coleta dados da conta para o mesmo cliente: uma conexão, um conjunto de credenciais, e o cliente autoriza uma vez. Enviar as credenciais diretamente é para quando não há um Item para reutilizar.
**Uma Conexão de Boleto por integração.** O Inter aceita um único webhook de cobrança por integração, e o registramos para uma Conexão de Boleto específica, então cada par Client ID + Client Secret suporta exatamente uma conexão. Mais conexões precisam de mais integrações no Inter, cada uma com seu próprio Client ID, Client Secret e certificado. Excluir uma Conexão de Boleto não remove o webhook no Inter, então a integração permanece ocupada até que o webhook seja removido; veja [Inter Empresas](/docs/boleto/inter#one-boleto-connection-per-inter-integration).
```mermaid
graph TD
A[Credenciais do Inter] --> B[Conectar através do Pluggy Connect cria um Item]
A --> C[Enviar credenciais diretamente POST /boleto-connections]
B --> D[POST /boleto-connections/from-item]
C --> E[Conexão de Boleto]
D --> E
```
**Como o Inter reporta um pagamento.** O Inter nos notifica e traduzimos seu vocabulário nos status que a API expõe:
| `situacao` do Inter | Torna-se |
|---|---|
| `RECEBIDO` | `PAID` |
| `MARCADO_RECEBIDO` | `PAID` |
| `ATRASADO` | `OVERDUE` |
| `PROTESTO` | `PROTESTED` |
| `A_RECEBER` | ignorado — o boleto simplesmente ainda está aberto |
Quando um boleto se torna `PAID`, o Inter também reporta o que foi realmente pago e como, que vai para `amountPaid` e `paymentOrigin` (tipicamente `PIX` ou `BOLETO`).
**Notificações.** O Inter publica os intervalos de IP de onde suas notificações se originam, e aceitamos apenas callbacks desses endereços. Nada é exigido de você — o que você recebe é nosso próprio webhook `boleto/updated`, autenticado da mesma forma que todos os outros webhooks do Pluggy.
Um boleto que você cancela através de [POST /boletos/{id}/cancel](/reference/boleto-cancel) é marcado como `CANCELADO` imediatamente, como parte dessa chamada. Um boleto cancelado diretamente dentro do próprio portal do Inter não será atualizado do nosso lado — esse caminho não produz nenhuma mudança de status que você possa observar. Se sua equipe de operações cancela boletos no Inter em vez de através da API, trate nosso status como autoritativo apenas para boletos cancelados através da API.
**Vale a pena saber antes de você entrar ao vivo**
- **`nossoNumero` é do Inter, e seu formato é do Inter.** Não o analise ou assuma uma largura; ele diferirá do que outra instituição retorna pela mesma cobrança.
- **Um pagamento atrasado é normal.** O Inter aceita pagamento após a data de vencimento, então um boleto pode passar de `ABERTO → ATRASADO → PAGO`. Manipuladores que param de ouvir uma vez que um boleto está atrasado perdem receita real.
- **Reconcilie com `amountPaid`, não `amount`.** Descontos, multas e juros fazem com que eles diferem em ambas as direções.
## Bradesco
A emissão de boletos do Bradesco ainda não está disponível. O modelo que está sendo construído é descrito aqui para que você possa planejar; os endpoints e o fluxo de conexão não estão ativos, e os detalhes podem mudar à medida que a integração for finalizada.
Cada outra instituição nesta API funciona da mesma maneira: seu cliente entrega credenciais, nós as mantemos e agimos com elas. O Bradesco separa **identificar o chamador** de **autorizar a ação**:
```mermaid
graph TB
subgraph "Uma vez por empresa · dentro do Bradesco"
A[Representante legal da empresa] -->|faz login no Bradesco| B[Aceita os termos]
B -->|confirma com uma chave de segurança| C[Autorização registrada Pluggy pode agir por este CNPJ]
end
subgraph "Cada solicitação · servidor para servidor"
D[Pluggy atua como parceiro do Bradesco] --> E[Emite um boleto para aquele CNPJ]
C -.->|deve já existir| E
end
```
**A parceria** é nossa. Pluggy é um parceiro do Bradesco, e isso é o que identifica o chamador em cada solicitação — o mesmo para cada empresa para a qual atuamos. Não há nada aqui para você ou seu cliente fornecer, instalar ou renovar.
**A autorização** é concedida uma vez por empresa, por essa empresa, dentro do próprio ambiente do Bradesco. O Bradesco confirmou que isso não pode ser feito através de uma API: a pessoa que autoriza faz login no Bradesco, aceita os termos e confirma com uma chave de segurança gerada em seu próprio dispositivo. Nós nunca vemos a senha, a chave ou os termos que estão sendo assinados. Os dois são independentes e ambos são necessários: a autorização é o que uma empresa concede, a parceria é o que nos permite agir sobre isso. Nenhum dos dois emite algo por conta própria.
**O que isso significa para sua integração.** Conectar uma conta do Bradesco envolverá um redirecionamento: seu cliente sai da sua interface, autoriza no Bradesco e retorna. Essa é uma forma diferente do formulário de credenciais usado para o Inter, e introduz um estado que um fluxo apenas de credenciais nunca tem — uma conexão que existe, mas ainda não é utilizável. Vale a pena projetar isso agora se o Bradesco estiver no seu roadmap.
**Ainda sendo definido com o Bradesco:** o contrato exato do callback que confirma uma autorização; se uma autorização expira, e se revogá-la dentro do Bradesco produz alguma notificação; o caminho de integração para empresas que não são titulares de contas do Bradesco; como uma empresa com vários CNPJs autoriza para todos eles.
## Sandbox
Testar uma integração de boleto contra um banco real é lento e parcialmente impossível: você precisa de uma conta empresarial, um pagador real disposto a pagar uma cobrança real, e para qualquer coisa envolvendo uma data de vencimento você teria que esperar a data chegar. O conector Sandbox remove tudo isso: ele emite boletos que parecem reais e os move para o status que você escolher por conta própria, disparando os mesmos webhooks que um banco real faria.
Está disponível agora, com o ID do conector `8`. Seus boletos carregam uma linha digitável corretamente formatada, código de barras e payload de PIX para que sua análise e renderização sejam testadas, mas eles **não** são instrumentos de pagamento válidos — nada emitido lá pode ser pago em um banco real. Veja [Testando com o Sandbox](/docs/boleto/sandbox) para como os centavos do valor escolhem o cenário.
As formas de solicitação e resposta, o ciclo de vida do status e o webhook são os mesmos para cada instituição e estão documentados uma vez, no guia da [Referência da API de Gestão de Boletos](/docs/boleto/management-api). Esta página cobre apenas o que difere: quem está ativo e como cada banco nos permite agir pelo seu cliente.
## Testando com o Sandbox
Source: https://docs.pluggy.ai/pt/docs/boleto/sandbox.md
Testar uma integração de boleto contra um banco real é lento e parcialmente impossível. Você precisa de uma conta empresarial, um pagador real disposto a pagar uma cobrança real e, para qualquer coisa envolvendo uma data de vencimento, você teria que esperar a data chegar.
O conector Sandbox remove tudo isso. Ele emite boletos que parecem reais e os move pelo status que você escolher por conta própria, disparando os mesmos webhooks que um banco real faria.
Boletos do Sandbox possuem uma linha digitável, código de barras e carga PIX corretamente formatados — os comprimentos e a estrutura de campo corretos, para que seu parsing e rendering sejam realmente testados. Eles **não** são instrumentos de pagamento válidos: os dígitos de verificação não são calculados deliberadamente. Nada emitido aqui pode ser pago em um banco real.
## O que ele permite testar
```mermaid
graph TD
A[Criar um boleto] --> B{Os centavos do valor escolha o cenário}
B --> C[PAGO total ou parcial]
B --> D[VENCIDO sem esperar pela data]
B --> E[CANCELADO]
D --> F[PROTESTADO]
D --> C
C --> G[Seu manipulador de webhook é executado em cada caminho]
E --> G
F --> G
```
Você não envia nenhuma solicitação para mover um boleto. O Sandbox realiza cada etapa por conta própria, **5 minutos** de intervalo, e dispara um webhook `boleto/updated` toda vez, exatamente como uma notificação de liquidação de um banco.
As transições que a API real recusa também são recusadas aqui. Um boleto `PAGO` não pode ser cancelado, e nada retorna para `ABERTO` — portanto, um manipulador que assume que um status só pode avançar é validado em vez de passar acidentalmente.
## Escolhendo um cenário
O cenário é definido pelos **centavos do `valor` do boleto**:
| O valor termina em | O que acontece |
|---|---|
| `,00` (por exemplo, `100.00`) | Após 5 minutos → `PAGO` pelo valor total |
| `,01` | Após 5 minutos → `PAGO` pela metade do valor (pagamento parcial: `amountPaid` é menor que `amount`) |
| `,02` | Após 5 minutos → `VENCIDO`; 5 minutos depois → `PAGO` (pago após a data de vencimento) |
| `,03` | Após 5 minutos → `VENCIDO`; 5 minutos depois → `PROTESTADO` |
| `,04` | Após 5 minutos → `CANCELADO` |
| `,05` | Após 5 minutos → `VENCIDO`, e permanece assim |
| Qualquer outro centavo | Permanece `ABERTO` — use para testar seu próprio cancelamento com [POST /boletos/{id}/cancel](/reference/boleto-cancel) |
Cancelar um boleto antes que uma etapa programada ocorra interrompe seu cenário.
## Começando
O Dashboard da Pluggy faz tudo isso sem código, na seção [Boletos](https://dashboard.pluggy.ai/boletos) (Beta). Na [página de problemas](https://dashboard.pluggy.ai/boletos/new), use **Conectar uma nova conta** para criar uma conexão Sandbox, em seguida, emita um boleto com os centavos do cenário que você deseja. De volta à lista, abra o boleto para ver seus detalhes em um painel lateral e assista-o seguir seu cenário, um passo a cada 5 minutos. As solicitações abaixo são as mesmas que ele envia.
Use o conector `8` (Pluggy Bank Business) e [POST /boleto-connections](/reference/boleto-connection-create). Nenhuma credencial real está envolvida:
```json
{
"connectorId": 8,
"credentials": {}
}
```
Idêntico a qualquer outra instituição — mesma solicitação, mesma forma de resposta. Os valores estão em reais, e os centavos escolhem o cenário. Este termina em `,01`, então será pago curto:
```json
{
"boletoConnectionId": "{YOUR-SANDBOX-CONNECTION-ID}",
"boleto": {
"seuNumero": "TEST-001",
"amount": 123.01,
"dueDate": "2026-03-01",
"payer": {
"taxNumber": "12345678000199",
"name": "Example SA",
"addressState": "SP",
"addressZipCode": "01239030",
"addressCity": "São Paulo",
"addressStreet": "Rua Example"
}
}
}
```
Cinco minutos depois, o Sandbox liquida o boleto e um webhook `boleto/updated` chega ao seu endpoint, o mesmo que a notificação de um banco real produziria. Cenários com duas etapas enviam um segundo webhook cinco minutos após o primeiro.
[GET /boletos/{id}](/reference/boleto-get) retorna o boleto em seu novo estado, com `amountPaid`, `paidAt` e `paymentOrigin` preenchidos para boletos pagos — os mesmos campos, nos mesmos lugares, que um boleto liquidado em um banco real.
## Um teste que vale a pena escrever
O modo de falha que mais custa é um manipulador de webhook que reconcilia contra o campo errado ou assume que o pagamento é sempre integral. O Sandbox torna ambos baratos de cobrir:
| Caso | Como produzi-lo |
|---|---|
| Pago integralmente | Emitir com um valor terminando em `,00` |
| Pago curto | Emitir com um valor terminando em `,01` |
| Pago após a data de vencimento | Emitir com um valor terminando em `,02` |
| Protestado | Emitir com um valor terminando em `,03` |
| Cancelado pelo banco | Emitir com um valor terminando em `,04` |
| Vencido e não pago | Emitir com um valor terminando em `,05` |
| Cancelado por você antes do pagamento | Emitir com qualquer outro centavo, depois chamar [POST /boletos/{id}/cancel](/reference/boleto-cancel) |
| Webhook duplicado | Torne seu endpoint idempotente e entregue o mesmo evento a ele duas vezes você mesmo |
Quando seu manipulador sobreviver a todos esses, aponte o mesmo código para uma [conexão Inter](/docs/boleto/inter). Nada além do ID da conexão muda.
## Inter Empresas
Source: https://docs.pluggy.ai/pt/docs/boleto/inter.md
Inter Empresas é a primeira instituição disponível na Referência da API de Gestão de Boletos, e a implementação de referência: tudo nesta página acontece por trás dos mesmos endpoints descritos no guia da [Referência da API de Gestão de Boletos](/docs/boleto/management-api).
## Estabelecendo uma conexão
Inter se autentica com quatro artefatos — um Client ID, um Client Secret, uma chave privada e um certificado — criados dentro do próprio Internet Banking do Inter. O [tutorial do Banco Inter Empresas](/docs/developer-tools/tutorials/inter-pj) orienta sobre como produzi-los.
Ao criar a integração no Inter, ative os escopos **Boleto** e **Extrato**. Uma credencial sem o escopo Boleto conecta-se com sucesso e depois falha na primeira tentativa de emissão, que é um lugar confuso para descobrir o problema.
Existem duas maneiras de transformar essas credenciais em uma conexão:
```mermaid
graph TD
A[Credenciais do Inter] --> B[Conectar através do Pluggy Connect cria um Item]
A --> C[Enviar credenciais diretamente POST /boleto-connections]
B --> D[POST /boleto-connections/from-item]
C --> E[Conexão de Boleto]
D --> E
```
Passar por um Item é o melhor padrão quando você já coleta dados da conta para o mesmo cliente: uma conexão, um conjunto de credenciais, e o cliente autoriza uma vez. Enviar credenciais diretamente é para quando não há um Item para reutilizar.
## Uma Conexão de Boleto por integração do Inter
Inter aceita um único webhook de cobrança por integração, e registramos esse webhook para uma Conexão de Boleto específica. Portanto, **cada par de Client ID + Client Secret suporta exatamente uma Conexão de Boleto**, seja você a crie diretamente ou a partir de um Item.
Para executar mais de uma Conexão de Boleto na mesma conta do Inter (outra aplicação Pluggy, outro ambiente, outra equipe), **crie outra integração no Inter**, com seu próprio Client ID, Client Secret e certificado, seguindo o [tutorial do Banco Inter Empresas](/docs/developer-tools/tutorials/inter-pj). Baixar um novo certificado para a mesma integração não ajuda: o webhook pertence à integração, não ao certificado.
Se a integração já tiver um webhook de cobrança, de uma Conexão de Boleto anterior ou uma que você configurou, criar a conexão falha com:
```
Não foi possível criar a boleto connection: A integração já tem webhook de cobrança configurado. Por favor, exclua o webhook para criar uma Boleto Connection ou crie uma integração nova sem webhook.
```
[DELETE /boleto-connections/{id}](/reference/boleto-connection-delete) remove a conexão do nosso lado, mas **o webhook permanece registrado no Inter**, então a mesma integração ainda não pode suportar uma nova conexão. Para reutilizá-lo, o webhook deve ser removido primeiro: entre em contato com o suporte e nós o removeremos para você, ou chame o próprio `DELETE /cobranca/v3/cobrancas/webhook` do Inter com as credenciais dessa integração. Depois, crie a conexão novamente. Boletos emitidos na conexão antiga param de receber atualizações de status assim que seu webhook é removido.
## Como o Inter reporta um pagamento
Inter nos notifica, e traduzimos seu vocabulário nos status que a API expõe:
| Inter `situacao` | Torna-se |
|---|---|
| `RECEBIDO` | `PAID` |
| `MARCADO_RECEBIDO` | `PAID` |
| `ATRASADO` | `OVERDUE` |
| `PROTESTO` | `PROTESTED` |
| `A_RECEBER` | ignorado — o boleto simplesmente ainda está aberto |
Quando um boleto se torna `PAID`, o Inter também reporta o que foi realmente pago e como, que vai para `amountPaid` e `paymentOrigin`. `paymentOrigin` é tipicamente `PIX` ou `BOLETO`, refletindo como o pagador escolheu liquidar.
Um boleto que você cancela através do [POST /boletos/{id}/cancel](/reference/boleto-cancel) é marcado como `CANCELLED` imediatamente, como parte dessa chamada. Mas um boleto cancelado diretamente dentro do próprio portal do Inter não será atualizado do nosso lado — esse caminho não produz nenhuma mudança de status que você possa observar. Se sua equipe de operações cancela boletos no Inter em vez de através da API, trate nosso status como autoritativo apenas para boletos cancelados através da API.
## Autenticando as notificações
Inter publica os intervalos de IP de onde suas notificações se originam, e nós aceitamos apenas callbacks desses endereços. Nada é exigido de você — a notificação que você recebe é nosso próprio webhook `boleto/updated`, autenticado da mesma forma que todos os outros webhooks do Pluggy.
## Vale a pena saber antes de você entrar ao vivo
- **`nossoNumero` é do Inter, e seu formato é do Inter.** Não o analise ou assuma uma largura; ele difere do que outra instituição retornará para a mesma cobrança.
- **Um pagamento atrasado é normal.** O Inter aceita pagamento após a data de vencimento, então um boleto pode passar de `OPEN → OVERDUE → PAID`. Manipuladores que param de ouvir uma vez que um boleto está atrasado perdem receita real.
- **Teste o caminho de pagamento parcial.** `amountPaid` pode ser menor ou maior que `amount` uma vez que descontos, multas ou juros se aplicam. O [Sandbox](/docs/boleto/sandbox) o produz sob demanda: emita um boleto com um valor terminando em `,01` e ele será pago pela metade.
## Tutorial Caixa PF (Mobile)
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/caixa-pf-mobile.md
Para conectar sua conta pessoal da Caixa Econômica Federal com o Pluggy, você deve autorizar o dispositivo. Aqui está um vídeo tutorial mostrando como fazer isso:
1. Na tela de conexão da Caixa, insira o nome de usuário e a senha da sua conta;
2. Clique no botão "Conectar";
3. A seguinte tela será exibida: "Cadastro de dispositivo". Esta tela aparece porque, como medida de segurança, a Caixa exige que o titular da conta autorize a conexão. Para conceder essa autorização, siga os próximos passos.
Ainda na tela de "**Cadastro de dispositivo**", observe que na parte inferior há a frase "Você precisa ativar o seguinte dispositivo", seguida de um código — no nosso exemplo, "746". Anote esse código, pois o usaremos para conceder a autorização;
4. Não clique no botão "**Confirmo que ativei o dispositivo**" ainda — clicaremos nele mais tarde. Além disso, não feche esta janela/app; mantenha-a aberta em segundo plano, pois voltaremos a ela;
5. Abra o app da **Caixa Econômica Federal**;
6. Na tela inicial de login, toque no seu nome de usuário;
Nota: se você nunca usou sua conta no app antes, deve completar seu primeiro login através do app.
7. Insira sua senha;
8. Toque em "**Acessar sua conta**";
9. Na tela inicial da sua conta, encontre a opção "**Menu**" no canto inferior e toque nela;
10. No menu que aparece, toque em "**Meu Perfil**";
11. Encontre a opção "**Meus Dispositivos**" e toque nela;
12. Na lista que aparece, procure o mesmo código que você anotou no passo 3 deste tutorial e selecione-o;
13. Role até o final do menu e toque em "**Ativar Dispositivo**";
14. Na tela que aparece, toque em "**Continuar**";
15. A seguinte mensagem será exibida: "**Seu dispositivo foi ativado!**". Isso significa que o processo dentro do app da Caixa está completo;
16. Agora volte para a janela/app do widget Pluggy que você deixou aberta (veja o passo 4 deste tutorial). Clique no botão "**Confirmo que ativei o dispositivo**";
17. Pronto! Você não precisa fazer mais nada — apenas aguarde aproximadamente **30 minutos** e nós conectaremos seus dados **automaticamente**.
## Tutorial Caixa PF (Web)
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/caixa-pf-web.md
Para conectar sua conta pessoal da Caixa Econômica Federal com o Pluggy, você deve autorizar o dispositivo através do Internet Banking. Aqui está um vídeo tutorial mostrando como fazer isso:
1. Na tela de conexão da Caixa, insira seu **nome de usuário** e **senha**;
2. Clique no botão "**Conectar**";
3. A seguinte tela será exibida: "**Cadastro de dispositivo**". Esta tela aparece porque, como medida de segurança, a Caixa exige que o titular da conta autorize a conexão. Para conceder essa autorização, siga os próximos passos;
4. Não clique ainda no botão "Confirmo que ativei o dispositivo" — nós clicaremos nele mais tarde. Além disso, não feche esta janela/aba do navegador; mantenha-a aberta, pois voltaremos a ela;
5. Abra uma segunda aba do navegador e vá para o site da Caixa Econômica Federal: [https://www.caixa.gov.br/](https://www.caixa.gov.br/);
6. Na página inicial da Caixa, clique no botão "**Acessar minha conta**";
7. Na tela que aparece, insira seu nome de usuário no campo indicado;
8. Selecione o tipo da sua conta (**Pessoa Física** — individual; **Pessoa Jurídica** — empresarial; ou **Governo** — governo);
9. Clique em "**Continuar**";
10. Na tela que aparece, verifique se as iniciais mostradas acima do botão laranja correspondem ao seu nome. Se estiverem corretas, clique no botão laranja;
11. Use o teclado digital que aparece para digitar sua senha de conta;
12. Clique em "**Continuar**";
13. Na página inicial da sua conta, use as setas laranjas para encontrar o menu "**Senhas e Configurações**";
14. Clique em "**Senhas e configurações**";
15. No menu que se expande, encontre a seção "**Computadores e dispositivos**" e clique em "**Gerenciar**";
16. Na caixa de diálogo "**Alerta**" que aparece, clique em "**SIM**";
17. Na tela que aparece, procure na coluna "**Apelido**" o mesmo código que você anotou na tela de "**Cadastro de Dispositivo**" no widget (veja o passo 3 deste tutorial) e selecione-o;
18. Clique em "**Ativar dispositivo**";
19. Agora volte para a janela/aba do widget do Pluggy que você deixou aberta (veja o passo 4 deste tutorial). Clique no botão "**Confirmo que ativei o dispositivo**";
20. Pronto! Você não precisa fazer mais nada — apenas aguarde aproximadamente **30 minutos** e nós conectaremos seus dados **automaticamente**.
## Tutorial Caixa PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/caixa-pj.md
O conector **Caixa Empresas** solicita seu **USERNAME** ("Usuário") e **PASSWORD** ("Senha") — as mesmas credenciais usadas no Internet Banking e no aplicativo móvel da Caixa.
---
**Username ("Usuário"):** alfanumérico
**Password ("Senha"):** alfanumérico
## Tutorial do Banco Inter MEI
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/inter-mei.md
Para conectar sua conta MEI no Banco Inter, você deve fazer login no aplicativo Inter com seu **número da conta MEI**.
Uma vez autenticado com sua conta MEI, siga as instruções em nosso widget para escanear o código QR de acesso e conectar a conta.
**Tenha cuidado para não fazer login com sua conta pessoal (CPF) no aplicativo Inter — caso contrário, você conectará essa conta em vez da sua conta MEI.**
## Tutorial do Banco Inter Empresas
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/inter-pj.md
Para conectar sua conta do **Banco Inter Empresas** ao **Pluggy**, você primeiro precisa criar uma **autorização de compartilhamento de dados** dentro do próprio Internet Banking do Inter.
Essa autorização é feita criando uma **integração de API** dentro da sua conta.
Após criar essa integração, o Banco Inter fornecerá:
- **Client ID**
- **Client Secret**
- Arquivo **Key** ("Chave Key")
- **Certificate** ("Certificado")
Essas quatro informações serão usadas para conectar sua conta do **Inter Empresas** ao **Pluggy**.
**Informações necessárias para a conexão:**
- Client ID
- Client Secret
- Arquivo **Key (.key)**
- Arquivo **Certificate (.crt)**
(veja a figura):
## Como criar a integração no Banco Inter
Para criar sua aplicação e obter suas credenciais de acesso (Client ID, Client Secret, arquivo key e certificado), siga as instruções abaixo:
### Passo 1 — Acesse o Internet Banking
- Faça login na sua conta do Banco Inter Empresas [aqui](https://contadigital.bancointer.com.br/?t=pj);
- Após autenticar via QR code, você será levado à página inicial da sua conta.
### Passo 2 — Abra o menu de integrações
No menu superior da página inicial:
1. Clique em **Integrar**
2. Selecione **Integrações**
3. Clique em **Nova integração**
### Passo 3 — Crie a nova integração
Na tela de **Nova integração**, preencha os campos:
- **Nome da integração**
Digite um nome de sua escolha
- **Descrição**
Digite uma descrição de sua escolha
Em seguida, clique em: **Próximo**
### Passo 4 — Defina o escopo da integração
Na página de **Nova Integração via API**, você precisará selecionar as permissões da integração.
Expanda o menu:
**API Banking**
Selecione a opção:
- **Consultar extrato e saldo**
Em seguida, clique em: **Criar Integração**
**Funcionalidade opcional**
Se você também quiser emitir boletos através da API, selecione:
- **API Cobrança (Boleto + Pix)**
Uma integração com **API Cobrança** pode suportar **apenas uma Conexão de Boleto** no Pluggy: o Inter permite um único webhook de cobrança por integração. Se você precisar de mais de uma Conexão de Boleto, crie uma integração para cada uma, com seu próprio Client ID, Client Secret e certificado. Um novo certificado para uma integração existente não é suficiente. Veja [Inter Empresas](/docs/boleto/inter#one-boleto-connection-per-inter-integration).
### Passo 5 — Autenticação adicional
Uma tela de **autenticação adicional** será exibida.
O Banco Inter enviará um **código de 6 dígitos via SMS** para o telefone celular registrado.
Digite o código recebido para continuar.
### Passo 6 — Preencha o formulário de integração
Após autenticar, a seguinte mensagem aparecerá:
- **Integração criada com sucesso**
Clique em: **Preencher formulário**
O Banco Inter usa este formulário para entender melhor como a integração será utilizada.
Você precisará preencher informações sobre:
- **A atividade dos seus clientes**
- **Informações da empresa**
- **Campo de atuação da empresa**
Preencha os dados **de acordo com as informações reais da sua empresa**.
Quando terminar, envie o formulário.
### Passo 7 — Aguarde a análise do Banco Inter
Após o envio do formulário, o Banco Inter pode realizar uma **validação das informações**.
Nesse caso, uma mensagem será exibida informando que:
- **Seus dados estão em análise**
Clique em: **Acessar minhas integrações**
### Passo 8 — Baixe a chave e o certificado
Na tela de **Minhas integrações**:
1. Localize a integração que você criou (pelo **nome e descrição** definidos anteriormente).
2. Verifique o **status** da integração.
Possíveis status:
- **Em validação** → aguarde a aprovação
- **Novo** → as credenciais podem agora ser baixadas
Se o status for **Novo**:
1. Clique nos **três pontos**
2. Selecione a opção:
**Download chave e certificado**
### Passo 9 — Confirme o download das credenciais
Um aviso será exibido informando que:
- ⚠️ **A chave e o certificado podem ser baixados apenas uma vez.**
Após ler as instruções, clique:
**Sim, baixar**
### Passo 10 — Salve as credenciais
Após confirmar o download:
1. Uma **tela** será exibida:
1. **Client ID**
2. **Client Secret**
⚠️ **Salve essas informações imediatamente**, pois **não serão mostradas novamente**.
### Passo 11 — Extraia os arquivos da chave e do certificado
Um arquivo **ZIP** contendo os arquivos da integração também será baixado.
Extraia o arquivo **ZIP**.
Após a extração, você terá dois arquivos:
- `Inter_API_Chave.key` → chave da API
- `Inter_API_Certificado.crt` → certificado da API
**Esses arquivos serão usados na conexão com o Pluggy.**
A integração passará por um processo de validação; após alguns minutos, seu status será atualizado para **Ativo** e estará pronta para uso.
### Passo final — Conectar no Pluggy
Agora abra o **widget Pluggy** e insira os dados da integração.
Preencha os campos:
- **Client ID**
Cole o Client ID gerado
- **Client Secret**
Cole o Client Secret gerado
- **Key (.key)**
Faça o upload do arquivo:
`Inter_API_Chave.key`
- **Certificate (.crt)**
Faça o upload do arquivo:
`Inter_API_Certificado.crt`
Em seguida, clique no botão **Conectar**.
Sua conta do **Banco Inter Empresas** estará conectada ao **Pluggy**.
**Pronto! A integração foi concluída com sucesso.**
## Tutorial Sicredi
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/sicredi.md
O conector **Sicredi Empresas** solicita as seguintes informações:
1. **CNPJ**
2. **USERNAME** ("Usuário")
3. **PASSWORD** ("Senha")
🚩 Essas são as mesmas credenciais usadas no aplicativo Sicredi.
**CNPJ:**
**Nome de usuário ("Usuário"):**
**Senha ("Senha"):**
## Tutorial Sicoob PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/sicoob-pj.md
O conector **Sicoob Empresas** solicita as seguintes informações:
1. **COOPERATIVA** ("Cooperativa")
2. **CHAVE DE ACESSO** ("Chave de Acesso")
3. **SENHA** ("Senha")
🚩 Essas são as mesmas credenciais usadas no Internet Banking e no aplicativo móvel do Sicoob.
## Tutorial do Usuário Secundário Santander PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/santander-pj-secondary-user.md
Aqui está um vídeo mostrando como criar uma conta secundária no Santander; abaixo dele, você tem o guia passo a passo!
O conector **Santander Empresas** solicita:
1. **AGÊNCIA** (agência)
2. **CONTA** (conta)
3. **USUÁRIO** (nome de usuário) e
4. **SENHA** (senha)
As informações da agência e da conta são as mesmas para o usuário principal e o usuário secundário; no entanto, o nome de usuário e a senha são específicos para cada conexão individual.
Neste tutorial, vamos mostrar como criar um usuário secundário para que você possa conectar seus dados com o **Pluggy**.
1. Acesse o site do **Santander PJ**: [https://www.santander.com.br/empresas](https://www.santander.com.br/empresas)
2. Na página inicial, faça login com suas informações de **Agência** (agência) e **Conta** (conta)
3. Digite seu **Usuário** (nome de usuário) e **Senha** (senha):
4. Um **QR Code** será exibido para autenticar a conexão:
5. Abra o **aplicativo Santander no seu telefone** como mostrado nas imagens abaixo para obter a **senha do QR Code** ("Senha do QRCode"):
6. Digite o código exibido em **seu telefone** no campo "**Senha do QRCode**" (senha do QR Code) no seu navegador:
7. Na tela inicial da sua conta, selecione o menu "**Configurações e ID Santander**":
8. Na seção "**Usuário secundário**", selecione "**incluir**":
9. Na próxima página, preencha todas as informações indicadas e clique em "**Continuar**":
10. Verifique e selecione os campos conforme mostrado na imagem, em seguida, clique em "**Continuar**" no canto inferior direito:
11. Na página exibida, **revise as informações** e clique em "**Continuar**":
12. Na próxima página, **repita o mesmo processo** dos passos **4** a **6** para autenticação do QR Code.
13. A tela "**Inclusão finalizada. Veja seu comprovante**" será exibida
14. Agora, basta usar seu usuário secundário para **conectar** com o **Pluggy**.
Nota: **lembre-se** de que o **nome de usuário** e a **senha** do seu usuário secundário são aqueles que você criou no **passo 9 deste tutorial**.
## Tutorial Santander PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/santander-pj.md
O conector **Santander Empresas** solicita:
1. **AGÊNCIA** (branch)
2. **CONTA** (account)
3. **USUÁRIO** (username) e
4. **SENHA** (password)
**Essas são as mesmas credenciais usadas no Internet Banking e no aplicativo móvel do Santander.**
**Use um computador para realizar a conexão, pois é necessário ler um QR Code.**
---
**Agência (branch):**
**Conta (account):**
**Usuário (username):**
**Senha (password):**
## Tutorial Itaú PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/itau-pj.md
O conector **Itaú Empresas** solicita:
1. **AGÊNCIA** (agência)
2. **CONTA** (conta)
3. **SENHA** (senha) e
4. **CPF**
🚩 Essas são as mesmas credenciais usadas no Internet Banking e no aplicativo móvel do Itaú.
Se o usuário master não tiver **acesso básico** ("acesso básico") além do **acesso completo** ("acesso completo"), você deve criar um acesso **OPERADOR** (operador) que tenha acesso básico, para que a conexão possa ser concluída com sucesso.
---
**Agência e Conta (agência e conta):**
**Senha (senha):**
**CPF:**
---
### Melhores práticas para uma conexão bem-sucedida
1. Certifique-se de que este acesso tenha a opção "ACESSO BÁSICO" (acesso básico) habilitada.
2. Se o acesso não tiver "ACESSO BÁSICO" (acesso básico) habilitado, recomendamos criar um acesso "OPERADOR" (operador).
Vá para **Área do cliente > Operadores e perfis** (Área do cliente > Operadores e perfis) e clique no link **Gestão de operadores** (Gestão de operadores).
## Tutorial Itaú PJ — Usuário Sem Token
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/itau-pj-user-without-token.md
Como criar um usuário sem um token no Itaú Empresas.
### Passo 1 — Criar um perfil de acesso
1. No Internet Banking do Itaú, vá para o menu de gestão de operadores e perfis ("gestão de operadores e perfis").
2. Crie um novo perfil de acesso.
3. Insira um nome para o perfil ("Perfil Financeiro", por exemplo), selecione a opção "Operador" e adicione a conta disponível em "Conta do perfil".
4. Selecione as operações de serviços financeiros e defina as mesmas operações para todas as contas.
5. Selecione a conta disponível e as operações disponíveis: "**Selecionar todos**".
Você deve vincular apenas uma conta a este perfil de acesso para habilitar a integração bancária automática. Se precisar integrar mais de uma conta, a abordagem recomendada é criar perfis de acesso adicionais.
### Passo 2 — Adicionar um operador
1. Vá para o menu de gestão de operadores e perfis e crie um novo operador.
2. Permita que o operador inclua apenas operações.
3. Forneça um dos documentos — CPF (Cadastro de Pessoas Físicas), RNE (Registro Nacional de Estrangeiro) ou passaporte — e preencha os dados restantes.
O operador não poderá editar ou atribuir funções a outros usuários.
4. Continue o processo até que o operador seja criado com permissão para ler o saldo e as transações do extrato ("extrato").
### Passo 3 — Validar o operador que você criou
1. Faça login no Internet Banking do Itaú com as credenciais do operador recém-criado e altere a senha numérica.
Este passo deve ser feito via web para que o processo seja concluído.
2. Se a validação for feita através do aplicativo desktop ou móvel, o processo não funcionará, uma vez que cada cenário possui validações diferentes.
## Tutorial do Banco do Brasil PJ — Autorização de Dispositivo
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bb-pj-device-authorization.md
O conector **Banco do Brasil Empresas** solicita:
- **CHAVE J** (chave J, alfanumérica)
- **SENHA J** (senha J, alfanumérica) e
- **senha de 8 dígitos** ("Senha de 8 dígitos")
Essas são as mesmas credenciais usadas no Internet Banking e no aplicativo móvel do Banco do Brasil.
Use um dispositivo (computador e telefone) que esteja autorizado no Internet Banking do banco.
A conta utilizada na conexão deve ter um número de telefone celular registrado, pois receberá um link de confirmação a ser inserido no momento da conexão.
**Chave J (chave J):**
**Senha J (senha J):** alfanumérica
**Senha de 8 dígitos:** a senha usada após acessar o Internet Banking
### Como autorizar um dispositivo?
1. Na página inicial, abra o menu e vá para a seção ***"Autorizar e Consultar Smartphone/Tablet"*** (Autorizar e visualizar smartphone/tablet)
2. Na página exibida, selecione na lista o mesmo dispositivo que apareceu na tela do **Widget**. Após selecioná-lo, clique em ***"Detalhar"*** (Ver detalhes);
3. Na próxima página, clique em ***"Autorizar"*** (Autorizar), e na seguinte clique em ***"Continuar"*** (Continuar);
4. Uma tela com um **QR Code** será exibida, que você deve escanear com o telefone registrado no **Banco do Brasil**; escanear o **QR Code** dá acesso ao ***código de confirmação*** ("Código de Confirmação");
5. Para escanear o **QR Code**, abra o aplicativo do Banco do Brasil, toque no ícone **"Ler QR Code e BB Code"** (Escanear QR Code e BB Code) e escaneie o código. Toque em **"Confirmar"** (Confirmar) no seu telefone e o código de confirmação será exibido na tela do seu telefone. Insira este código no site do Banco do Brasil e clique em **"Confirmar"** (Confirmar).
6. Volte para o **Pluggy Widget** e clique em ***"Confirmo que ativei o dispositivo"*** (Eu confirmo que ativei o dispositivo).
## Tutorial do Banco do Brasil PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bb-pj.md
O conector **Banco do Brasil Empresas** solicita:
- **CHAVE J** (chave J, alfanumérica)
- **SENHA J** (senha J, alfanumérica) e
- **senha de 8 dígitos** ("Senha de 8 dígitos")
Essas são as mesmas credenciais usadas no Internet Banking e no aplicativo móvel do Banco do Brasil.
Use um dispositivo (computador e telefone) que esteja autorizado no Internet Banking do banco.
A conta utilizada na conexão deve ter um número de telefone celular registrado, pois receberá um link de confirmação a ser inserido no momento da conexão.
**Chave J (chave J):**
**Senha J (senha J):** alfanumérica
**Senha de 8 dígitos:** a senha usada após acessar o Internet Banking
### Como se conectar?
1. Após inserir as credenciais solicitadas, clique em "CONECTAR".
2. Selecione o número de telefone celular registrado e clique em "CONECTAR".
🚩 Para completar esta etapa, você deve ter um número de telefone celular registrado no Banco do Brasil.
3. Após a etapa 2, um token será enviado para o telefone escolhido. Copie e cole a URL que você recebeu no campo destacado. **Exemplo da URL recebida:** `https://www49.bb.com.br/sms/ato?c=aaaa1111bbbb`
---
### Melhores práticas para uma conexão bem-sucedida
1. Registre um número de telefone celular acessando o **ícone de perfil > atualização cadastral** (atualização de perfil)
2. **Certifique-se de que o mesmo número de telefone celular está registrado para receber SMS.**
Mova o cursor para a esquerda em direção aos ícones do menu e escolha **Segurança > Serviço SMS > Adesão** (Segurança > serviço SMS > Adesão).
3. **Certifique-se de que seu telefone (o mesmo com o aplicativo do banco instalado) está autorizado no Banco do Brasil.**
Para confirmar isso, abra o menu no lado esquerdo e escolha **Segurança > Cadastrar equipamentos > Autorizar e consultar smartphone/tablet** (Segurança > Cadastrar dispositivos > Autorizar e visualizar smartphone/tablet).
Uma lista com o modelo do seu telefone aparecerá — **selecione-o e clique no botão AUTORIZAR.**
## Tutorial Bradesco PJ — Habilitar Acesso ao Aplicativo Móvel
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bradesco-pj-mobile-access.md
Como habilitar o acesso ao aplicativo móvel para um usuário do **Bradesco Empresas**:
1. Faça login no Internet Banking usando um usuário **Master**.
2. Vá para a seção **Administração** e clique em **Consultar, Alterar, Bloquear/Desbloquear ou Excluir Usuários**
3. Clique no botão de editar para o usuário que você deseja alterar
4. Selecione **Acesso pelo celular** e **Liberar acesso ao Net Empresa pelo celular**
5. Salve as alterações
## Tutorial Bradesco PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bradesco-pj.md
O conector **Bradesco Empresas** primeiro solicita seu **USUÁRIO** (nome de usuário) e **SENHA** (senha), e após enviá-los, solicita a **CHAVE DE SEGURANÇA** (chave de segurança) — **as mesmas credenciais usadas no Internet Banking e no aplicativo móvel do Bradesco.**
**Para conectar com sucesso, você deve ter o aplicativo Bradesco no seu telefone para gerar a chave de segurança.**
---
**Usuário (username):** alfanumérico
**Senha (password):** numérica
**Chave de segurança (security key):** chave numérica exibida na tela do seu telefone
## Tutorial de Open Finance PF do Bradesco
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/bradesco-pf-of.md
**Para se conectar com sucesso, você deve ter o aplicativo Bradesco no seu telefone para gerar a chave de segurança.**
---
Para conectar sua conta pessoal (Pessoa Física, PF) do Bradesco, siga os passos abaixo:
**Passo 1 — Iniciar a conexão**
Na tela de conexão do Bradesco:
- Insira o **CPF do titular da conta**
- Clique no botão **"Conectar"**
**Passo 2 — Insira os detalhes da sua conta**
- Insira os detalhes da sua **agência e conta**
- Clique em **"Continuar"**
**Passo 3 — Escaneie o QR Code**
- Um QR Code será exibido na tela
- Para prosseguir, você deve **escanear** usando o **aplicativo Bradesco no seu telefone**
**Passo 4 — Gere o código no aplicativo Bradesco**
No aplicativo Bradesco, siga o caminho abaixo:
1. Abra a opção **"Chave de Segurança"**
2. Selecione **"Validação digital"**
3. Escaneie o **QR Code** mostrado na tela
4. Após escanear, um **código de validação** será gerado
**Passo 5 — Insira o código de validação**
- Insira o código gerado na tela de consentimento
- Clique em **"Continuar"**
**Passo 6 — Confirme com sua senha**
- Insira sua senha Bradesco de **4 dígitos**
- Clique em **"Continuar"**
**Passo 7 — Finalize o consentimento**
- Um resumo das informações a serem compartilhadas será exibido
- Revise os dados
- Clique em **"Continuar"** para confirmar
**Passo 8 — Conexão completa**
- Você será redirecionado automaticamente para a plataforma
- A conexão será concluída **com sucesso**
## Tutorial Efí Bank PJ
Source: https://docs.pluggy.ai/pt/docs/developer-tools/tutorials/efi-pj.md
Para conectar o Efí Bank Empresas com o Pluggy, você primeiro precisa criar uma "autorização" para compartilhar suas informações do Efí Bank com o Pluggy.
Essa "autorização" é concedida através de um "registro" que você deve criar dentro da sua conta do Efí Bank. Após criar esse "registro" — que o Efí Bank chama de "Integração" — você receberá o "nome de usuário e senha" (Client ID e Client Secret) para ele, bem como um "Certificado". Com essas três informações (Client ID, Client Secret e certificado) você conectará sua conta do Efí Bank Empresas com o Pluggy (veja a figura):
Para criar sua aplicação e obter suas credenciais de acesso (Client ID, Client Secret e certificado), siga as instruções abaixo:
**Passo a passo**
1. Faça login na sua conta do Efí Bank Empresas [aqui](https://login.sejaefi.com.br/);
2. Na página inicial da sua conta, abra a área "**API**" no menu à esquerda, vá para a opção **Introdução** e clique em "**Criar aplicação**";
3. Na página "**Criar aplicação**", insira um nome de sua escolha no campo "**Nome da aplicação**" e clique no botão "Continuar";
4. Na página "Selecione os escopos", você deve definir o escopo da integração. Para isso, expanda o menu "**API Extratos**" e selecione as opções mostradas na imagem, depois expanda o menu "**API Pix**" e selecione as opções: "Consultar saldo", "Solicitar relatórios" e "Consultar relatórios".
5. Após selecionar as opções, clique no botão "Continuar".
6. Uma tela de "**Assinatura eletrônica**" será exibida. Basta inserir o código e clicar no botão "Continuar".
7. Após inserir o código, a tela "**Sua aplicação foi criada.**" será exibida. Neste ponto, você pode copiar seu Client ID e Client Secret.
8. Para criar o certificado, abra a área "**Meus certificados**" no menu à esquerda e clique em "**Criar novo certificado**";
9. Na tela "**Criar novo certificado**", insira um nome de sua escolha no campo "**Nome do certificado**" e clique no botão "Criar certificado";
10. Após autenticar via QR Code, você poderá baixar o certificado no formato p12.
11. Agora, basta abrir o Pluggy Widget, colar o "Client ID" e "Client Secret" nos campos correspondentes, fazer o upload do arquivo de certificado p12 e clicar no botão laranja "Conectar" para conectar suas informações do Efí Bank Empresas com o Pluggy.
Devido a limitações do Efí Bank, as transações serão sincronizadas 1 dia após a conexão ser criada.
## Autenticação
Source: https://docs.pluggy.ai/pt/docs/reference/authentication.md
Cada solicitação carrega uma credencial no cabeçalho `X-API-KEY`. Existem dois tipos, emitidos por dois endpoints, e a diferença entre eles é o escopo.
| Credencial | Emitido por | Dura | Atinge |
| --- | --- | --- | --- |
| **API Key** | [`POST /auth`](/reference/auth/auth-create) | 2 horas | Cada endpoint. Somente do lado do servidor. |
| **Connect Token** | [`POST /connect_token`](/reference/auth/connect-token-create) | 30 minutos | O Item para o qual foi emitido e uma visão reduzida de suas Contas. Seguro para entregar a um cliente. |
## API Key
```http
POST https://api.pluggy.ai/auth
Content-Type: application/json
{ "clientId": "…", "clientSecret": "…" }
```
Resposta `200`:
```json
{ "apiKey": "…" }
```
`clientId` e `clientSecret` vêm do [Dashboard](https://dashboard.pluggy.ai). Eles identificam sua aplicação, então `POST /auth` deve estar no seu servidor e em nenhum outro lugar. Um `401` com `codeDescription` `CLIENT_KEYS_UNAUTHORIZED` significa que o par está errado; `CLIENT_DISABLED` significa que a aplicação está desligada.
A chave expira **2 horas** após ser emitida. Reutilize-a até lá — `POST /auth` tem seu próprio [limite de taxa](/reference/rate-limits), e solicitar uma chave por chamada é a maneira usual de atingi-lo.
## Connect Token
```http
POST https://api.pluggy.ai/connect_token
X-API-KEY: {apiKey}
Content-Type: application/json
{
"itemId": "…",
"options": {
"clientUserId": "…",
"webhookUrl": "https://…",
"oauthRedirectUri": "https://…",
"avoidDuplicates": true
}
}
```
Resposta `200`:
```json
{ "accessToken": "…" }
```
Tudo no corpo é opcional. `itemId` limita o token a um Item existente, para uma atualização. `options` são aplicadas a cada Item criado com o token:
| Opção | Efeito |
| --- | --- |
| `clientUserId` | Seu identificador para o usuário final, armazenado no Item e ecoado em cada webhook `item/*`. |
| `webhookUrl` | Onde os eventos desses Itens são entregues. |
| `oauthRedirectUri` | Onde o usuário aterrissa após um fluxo de conexão OAuth. |
| `avoidDuplicates` | Não criar um segundo Item para credenciais que já possuem um. |
As únicas chaves lidas na raiz do corpo são `itemId` e `options`. Um `clientUserId` enviado na raiz é descartado — a chamada ainda retorna `200`, e os Itens acabam com `clientUserId: null`. Preencha um Item afetado com [`PATCH /items/{id}`](/reference/items/items-update).
O token expira **30 minutos** após ser emitido. Emita um por conexão: um novo cada vez que você criar ou atualizar um Item.
## Escopo
Um Connect Token é enviado exatamente como uma API Key, em `X-API-KEY`. Ele pode chamar [`GET /items/{id}`](/reference/items/items-retrieve) para seu próprio Item e [`GET /accounts?itemId=`](/reference/account/accounts-list) com uma visão reduzida dos dados; qualquer outra coisa retorna `403`. Um token emitido para um Item não pode ler outro, incluindo Itens criados anteriormente com um token diferente.
## O fluxo, do início ao fim
1. Seu servidor chama `POST /auth` com `clientId` e `clientSecret` e mantém a API Key.
2. Seu servidor chama `POST /connect_token` com essa chave e entrega o `accessToken` ao seu cliente.
3. Seu cliente — o [Connect Widget](/docs/connect-widget/introduction) ou sua própria interface — cria ou atualiza o Item com o token.
4. Seu servidor lê os dados do Item com a API Key.
Leia o guia: [Authentication](/docs/authentication).
## Conceitos Básicos
Source: https://docs.pluggy.ai/pt/docs/reference/basic-concepts.md
## URL Base
```
https://api.pluggy.ai
```
Um ambiente. Teste contra os [conectores do Sandbox](/docs/guides/sandbox) em vez de um host separado.
## Transporte
HTTPS com TLS 1.2 ou posterior. Conexões que negociam uma versão TLS mais antiga são rejeitadas.
## Solicitações
REST sobre JSON. Envie `Content-Type: application/json` em cada solicitação com um corpo, e a credencial em `X-API-KEY` — veja [Autenticação](/reference/authentication). Os verbos significam o que dizem: `GET` lê, `POST` cria, `PATCH` atualiza, `DELETE` remove.
## Respostas
JSON. A API evolui sem versões **adicionando** campos às respostas; nada é removido ou renomeado. Seu cliente deve aceitar e ignorar campos que não conhece — a maioria das bibliotecas HTTP faz isso por padrão, um desserializador estrito pode não fazer.
Os erros compartilham uma forma, independentemente do endpoint:
```json
{
"code": 401,
"codeDescription": "CLIENT_KEYS_UNAUTHORIZED",
"message": "As chaves do cliente são inválidas"
}
```
`code` repete o status HTTP; `codeDescription`, quando presente, é o identificador estável para ramificar; `message` é para as pessoas. Alguns erros adicionam um objeto `data`. Os códigos de status estão listados em [Códigos de Erro](/reference/error-codes).
## Paginação
Dois modelos estão em uso. Os endpoints `v2` paginam com um cursor; todos os outros endpoints de lista ainda paginam por número de página.
Os cursores são como esta API pagina a partir de agora, e a paginação por número de página está sendo descontinuada. Onde um endpoint de cursor `v2` existe, escreva sua integração contra ele.
### Cursor (`endpoints v2`)
Peça a primeira página com seus filtros. A resposta carrega os registros e `next`: uma string de consulta pronta para a próxima página.
```http
GET https://api.pluggy.ai/v2/transactions
?accountId={ACCOUNT_ID}
X-API-KEY: {apiKey}
```
```json
{
"results": [],
"next": "?accountId={ACCOUNT_ID}&after={CURSOR}"
}
```
| Campo | Significado |
| --- | --- |
| `results` | Os registros desta página. |
| `next` | A string de consulta da próxima página, ou `null` na última. |
Para continuar, anexe `next` ao caminho do endpoint exatamente como recebido — já carrega seus filtros e o cursor `after`:
```http
GET https://api.pluggy.ai/v2/transactions
?accountId={ACCOUNT_ID}
&after={CURSOR}
X-API-KEY: {apiKey}
```
Nunca construa ou decodifique `after` você mesmo: o valor é opaco e só é válido como retornado. Um `next` `null` significa que não há mais nada para ler. A paginação por cursor está disponível em [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor) e [`GET /v2/items`](/reference/items/items-list-by-cursor) — este último é opcional por equipe; peça suporte para habilitá-lo.
### Número da página (outros endpoints de lista)
Investimentos, transações de investimento, contas de cartão de crédito (`GET /bills`), clientes de pagamento, destinatários e solicitações, e pré-autorização de Smart Transfer paginam por página:
```http
GET https://api.pluggy.ai/investments
?itemId={ITEM_ID}
&page=2
&pageSize=500
X-API-KEY: {apiKey}
```
```json
{
"total": 200,
"totalPages": 15,
"page": 1,
"results": []
}
```
| Campo | Significado |
| --- | --- |
| `total` | Registros que correspondem à solicitação, em todas as páginas. |
| `totalPages` | Páginas necessárias para ler todos. |
| `page` | A página nesta resposta. |
| `results` | Os registros desta página. |
Dois parâmetros de consulta dirigem isso: `page` (padrão `1`) e `pageSize` (padrão `500` onde o endpoint aceita — verifique o endpoint). Para ler tudo, solicite `page=1`, depois `page=2` … até `totalPages`.
Cada endpoint de lista fora do `v2` pagina dessa forma hoje, e espera-se que esses ganhem equivalentes de cursor. Mantenha a lógica de paginação em um só lugar em sua integração: mover um endpoint é então uma mudança em uma função em vez de em cada local de chamada.
A página baseada [`GET /transactions`](/reference/transaction/transactions-list) está disponível apenas até **2026-12-31**. Mova para [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor), que pagina por cursor como acima.
Leia o guia: [Conceitos básicos](/docs/developer-tools/basic-concepts).
## Códigos de Erro
Source: https://docs.pluggy.ai/pt/docs/reference/error-codes.md
## Corpo do erro
Todo erro, em todo endpoint, tem esta forma:
```json
{
"code": 404,
"codeDescription": "ITEM_NOT_FOUND",
"message": "Item não encontrado"
}
```
| Campo | Significado |
| --- | --- |
| `code` | O status HTTP, repetido. Sempre presente. |
| `message` | Uma frase para uma pessoa. Sempre presente; não estável. |
| `codeDescription` | Um identificador estável para o erro específico, quando o endpoint distingue vários. Baseie-se nisso, não em `message`. |
| `data` | Detalhe extra para alguns erros — por exemplo, os Items que já existem ao criar um que duplicaria uma conexão. |
## Códigos de status
| Status | Significado | Geralmente por causa de |
| --- | --- | --- |
| `400` Bad Request | A solicitação é inválida. | Um campo ausente ou malformado. |
| `401` Unauthorized | A credencial está ausente, errada ou expirada. | Uma API Key que passou de 2 horas, ou `clientId`/`clientSecret` errados em `POST /auth` (`CLIENT_KEYS_UNAUTHORIZED`, `CLIENT_DISABLED`). |
| `403` Forbidden | A credencial não pode acessar este recurso. | Um Connect Token usado fora de seu escopo — veja [Autenticação](/reference/authentication). |
| `404` Not Found | Nenhum recurso desse tipo. | Um `id` que não existe. |
| `405` Method Not Allowed | O endpoint não suporta este verbo. | |
| `406` Not Acceptable | Um formato diferente de JSON foi solicitado. | |
| `409` Conflict | A solicitação contradiz o estado atual do recurso. | Um conflito ao atualizar um Item — veja [`PATCH /items/{id}`](/reference/items/items-update). |
| `429` Too Many Requests | Um limite de taxa foi excedido. | Veja [Limites de Taxa](/reference/rate-limits) para os limites e o cabeçalho `Retry-After`. |
| `500` Internal Server Error | Algo falhou do nosso lado. | Tente novamente mais tarde. |
| `503` Service Unavailable | Temporariamente offline para manutenção. | Tente novamente mais tarde. |
A página de cada endpoint nesta referência lista os status que ele retorna e, onde a API os distingue, os valores de `codeDescription`.
## Criando e atualizando um Item
Esses retornam de [`POST /items`](/reference/items/items-create) e
[`PATCH /items/{id}`](/reference/items/items-update). Onde o texto abaixo mostra um
`:placeholder`, a mensagem real carrega o valor — uma frequência, uma espera, um
nome de parâmetro.
| `codeDescription` | Status | Mensagem | O que fazer |
| --- | --- | --- | --- |
| `PARAMETERS_NOT_PROVIDED` | `400` | parâmetros não foram fornecidos | Envie as credenciais da conexão para sincronizar o item. |
| `ITEM_ALREADY_UPDATING` | `400` | Uma atualização já está em andamento, aguarde até que a última execução termine | Este item está sincronizando. Aguarde a execução terminar — sucesso ou erro — antes de acionar outra. |
| `ITEM_IS_ALREADY_UPDATING` | `400` | Há um item ativo para o conjunto de credenciais que não terminou de executar | O mesmo conjunto de credenciais está sincronizando em outro item. Aguarde por ele, para que duas sessões não sejam abertas com a instituição ao mesmo tempo. |
| `CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCY` | `409` | Atualizações do cliente neste item são permitidas no máximo a cada :minUpdateFrequencyAllowedInHours horas. A última atualização foi em :lastUpdatedAt | Aguarde até que a frequência mínima tenha passado desde a última atualização. O limite é por equipe e ajustável — pergunte ao suporte se seu caso de uso precisar de um mais curto. |
| `LAST_EXECUTION_HAD_LOGIN_ERROR` | `400` | A última execução teve um erro de login, você deve atualizar os parâmetros | A última sincronização falhou ao fazer login. Envie novas credenciais antes de atualizar novamente. |
| `TOO_MANY_CONSECUTIVE_LOGIN_FAILURES` | `400` | deve aguardar pelo menos :readableBackoffTime após :maxConsecutiveFailedLoginAttempts erros de login consecutivos, a última tentativa foi em :lastExecutionEndedAt (pode tentar novamente após: :canRetryAfterDate) | Um cooldown após erros de login repetidos, para que a conta do usuário não seja bloqueada pela instituição. Tente novamente após o tempo na mensagem. |
| `TOO_MANY_CONSECUTIVE_ERRORS` | `400` | Houve mais de 5 sincronizações falhadas, entre em contato com o suporte | A conexão falhou muitas vezes seguidas. Relate ao suporte com o `itemId`. |
| `ITEM_IN_ERROR_COOLDOWN` | `409` | Este conjunto de credenciais falhou recentemente ao conectar e está em um período de cooldown, por favor, tente novamente mais tarde | Essas credenciais falharam recentemente e estão em um cooldown. Tente novamente após passar. |
| `CONNECTOR_OFFLINE` | `409` | este conector está offline neste momento | O conector não está aceitando execuções agora. Tente novamente mais tarde — veja [status.pluggy.ai](https://status.pluggy.ai). |
| `CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR` | `400` | O parâmetro :parameter é necessário para ser renovado para a atualização do item. | O conector agora requer esse parâmetro novamente. Envie-o para atualizar a conexão. |
| `ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT` | `409` | O Item foi originalmente conectado com uma conta diferente, por favor, use a conta original | As credenciais agora apontam para uma conta diferente da qual o item foi criado. Use a conta original ou crie um novo item. |
| `ITEM_CREATION_LIMIT_EXCEEDED` | `409` | O cliente excedeu o limite de criação de itens (:itemsLimit itens) para o nível de assinatura atual. | Você atingiu o limite de itens da sua assinatura. Exclua itens não utilizados ou entre em contato com o suporte. |
| `CLIENT_HAS_ITEM_UPDATES_DISABLED` | `409` | O cliente tem atualizações de itens desativadas | Atualizações foram desativadas para a equipe. Entre em contato com o suporte. |
| `CREATE_ITEMS_API_FREE_DISABLED` | `400` | A assinatura gratuita só pode criar itens através do nosso Connect Widget | Na assinatura gratuita, os itens são criados através do Connect Widget. |
| `SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED` | `400` | O nível de assinatura do cliente atual só pode atualizar itens do Sandbox (Pluggy Bank) | Seu nível de assinatura só permite atualizar itens do Sandbox (Pluggy Bank). |
## Erros de MFA
Retornados ao enviar um parâmetro de múltiplos fatores para um Item — veja
[Atualizando um Item](/docs/connect-widget/updating-item).
| `codeDescription` | Status | Mensagem | O que fazer |
| --- | --- | --- | --- |
| `ITEM_MFA_NOT_FOUND` | `404` | item não tem solicitação de entrada mfa | O item não está aguardando uma entrada de MFA, então nenhuma pode ser enviada. |
| `ITEM_MFA_ALREADY_PROVIDED` | `400` | item não tem solicitação de entrada mfa, já foi fornecida | Nada a fazer — o MFA já foi enviado. |
| `ITEM_MFA_EXPIRED` | `400` | O parâmetro MFA do Item expirou, por favor, inicie uma nova atualização | A janela de MFA fechou. Inicie uma nova atualização para sincronizar a conexão. |
| `ITEM_MFA_PARAMETER_EXPECTED_MISMATCH` | `400` | O Item está esperando o nome do parâmetro MFA ':parameter' | O item está aguardando um parâmetro diferente. Use o nome na mensagem. |
| `MFA_PARAMERTER_WAS_ALREADY_USED_ERROR` | `400` | O parâmetro MFA deve ser atualizado da última execução | O valor enviado é o que já foi usado na última execução. Peça ao usuário um novo. |
A grafia não é um erro de digitação nesta página: a API retorna `PARAMERTER`. Combine exatamente se você ramificar sobre isso.
Leia o guia: [Códigos de Erros](/docs/developer-tools/error-codes).
## Limites de Taxa
Source: https://docs.pluggy.ai/pt/docs/reference/rate-limits.md
Limites são contados **por endpoint, por IP, por minuto** — não por conta ou por chave da API, então cada servidor atrás do mesmo IP de saída compartilha um orçamento. Cada limite é independente: esgotar `POST /auth` não afeta `GET /transactions`. Onde um limite abrange dois endpoints, as requisições para qualquer um contam contra ele.
## Limites
| Endpoint | Requisições por minuto por IP |
| --- | --- |
| `POST /auth` | 360 |
| `GET /accounts`, `GET /accounts/{id}` | 360 |
| `GET /transactions`, `GET /transactions/{id}` | 360 |
| `GET /investments`, `GET /investments/{id}` | 360 |
| `GET /investments/{id}/transactions` | 360 |
| `PATCH /items/{id}` | 20 |
`PATCH /items/{id}` é dimensionado para atualizações acionadas pelo usuário. Atualizações diárias pertencem ao [auto-sync](/docs/connections/item#auto-sync), não a um loop de chamadas `PATCH`.
## A resposta 429
```json
{
"code": 429,
"message": "Muitas requisições. Por favor, tente novamente mais tarde (veja o cabeçalho Retry-After em segundos)"
}
```
Requisições adicionais para esse endpoint continuarão falhando até que a janela de um minuto seja redefinida. Três cabeçalhos informam quanto tempo:
| Cabeçalho | Significado |
| --- | --- |
| `RateLimit-Limit` | O limite para este endpoint, por minuto. |
| `RateLimit-Reset` | Segundos até que o contador seja redefinido e o endpoint aceite requisições novamente. |
| `Retry-After` | A dica padrão de nova tentativa. Sempre `60`. |
Aguarde `RateLimit-Reset` segundos e tente novamente. Clientes HTTP com comportamento de nova tentativa padrão (por exemplo, `got`) já respeitam `Retry-After` em um `429`.
## Quando você continua atingindo um limite
- Reutilize a chave da API por suas 2 horas em vez de chamar `POST /auth` por requisição — veja [Autenticação](/reference/authentication).
- Limite o paralelismo de trabalhos em lote contra um endpoint e espaçe as chamadas.
- Procure por requisições duplicadas em operação normal.
- Se a aplicação realmente precisar de mais, entre em contato com o suporte com o caso de uso.
Leia o guia: [Limites de taxa](/docs/developer-tools/rate-limits).
## Webhook
Source: https://docs.pluggy.ai/pt/docs/reference/webhooks.md
Um webhook é uma URL HTTPS sua que recebe um `POST` com um corpo JSON quando um evento acontece. Duas maneiras de se inscrever:
- **Um recurso Webhook** — [`POST /webhooks`](/reference/webhook/webhooks-create) com um `url` e um `event`. Entrega esse evento para cada recurso da aplicação.
- **`webhookUrl` em um recurso** — definido ao criar um Item, um Connect Token ou uma Solicitação de Pagamento. Entrega cada evento, mas apenas para esse recurso (ou os Items criados com esse token).
## Recurso Webhook
```http
POST https://api.pluggy.ai/webhooks
X-API-KEY: {apiKey}
Content-Type: application/json
{
"url": "https://example.com/pluggy",
"event": "item/updated",
"headers": { "X-CLIENT-ID": "…" }
}
```
| Campo | Obrigatório | Significado |
| --- | --- | --- |
| `url` | sim | Apenas HTTPS. `localhost` não é aceito — use um túnel como ngrok durante o desenvolvimento. |
| `event` | sim | Um evento das tabelas abaixo, ou `all` para tudo. Não há curinga por produto: para receber todos os eventos de Item, registre `all` ou um webhook por evento. |
| `headers` | não | Enviado com cada entrega para esta URL — a maneira de passar uma chave de API que seu endpoint requer. Apenas configurável através da API, nunca mostrado no dashboard. |
Endpoints: [`GET /webhooks`](/reference/webhook/webhooks-list), [`POST /webhooks`](/reference/webhook/webhooks-create), e recuperar, atualizar e deletar em [`/webhooks/{id}`](/reference/webhook).
## Eventos
**Dados**
| Evento | Dispara quando |
| --- | --- |
| `item/created` | Um Item foi criado e conectado com sucesso. |
| `item/updated` | Um Item foi atualizado e sincronizado com sucesso. |
| `item/deleted` | Um Item foi deletado. |
| `item/error` | Uma execução terminou em erro; `USER_AUTHORIZATION_PENDING` também dispara isso. |
| `item/waiting_user_input` | O Item precisa de input do usuário (MFA) para continuar. |
| `item/waiting_user_action` | O Item precisa que o usuário atue em seu dispositivo — autorize no aplicativo do banco, escaneie um código QR. |
| `item/login_succeeded` | O login na instituição foi bem-sucedido; a coleta de dados está em andamento. |
| `connector/status_updated` | Um conector mudou de status (`ONLINE`, `UNSTABLE`, `OFFLINE`). Transporta `connectorId`. |
| `transactions/created` | Novas transações após uma atualização; transporta `createdTransactionsLink` para buscá-las. |
| `transactions/updated` | Transações mudaram após uma atualização; transporta seus ids. |
| `transactions/deleted` | Transações removidas após uma atualização; transporta seus ids. |
Eventos de transação disparam apenas quando algo mudou; uma atualização sem novas transações não emite `transactions/created`.
**Pagamentos**
| Evento | Dispara quando |
| --- | --- |
| `payment_intent/created` | Uma intenção de pagamento foi criada para uma solicitação. |
| `payment_intent/waiting_payer_authorization` | A intenção precisa da autorização do pagador. |
| `payment_intent/completed` | A intenção foi concluída. |
| `payment_intent/error` | A intenção falhou. |
| `payment_request/updated` | Uma solicitação de pagamento mudou de status. |
| `scheduled_payment/created`, `/completed`, `/error`, `/canceled` | Um pagamento agendado de uma autorização foi movido. |
| `scheduled_payment/all_created`, `/all_completed` | Cada pagamento agendado de uma autorização foi criado / concluído. |
| `automatic_pix_payment/created`, `/completed`, `/error`, `/canceled` | Um pagamento de uma solicitação de PIX Automático foi movido. |
| `smart_transfer_preauthorization/completed`, `/error` | Uma pré-autorização de Smart Transfer foi aprovada ou falhou. |
| `smart_transfer_payment/completed`, `/error` | Um pagamento de Smart Transfer foi liquidado ou falhou. |
## Payload
Cada notificação carrega:
| Campo | Significado |
| --- | --- |
| `event` | O nome do evento. |
| `eventId` | Identifica o evento; o mesmo valor quando um evento é entregue a várias URLs. |
| `triggeredBy` | `USER` (um Connect Token, por exemplo, o widget), `CLIENT` (uma chave de API, por exemplo, um `PATCH`), `SYNC` (auto-sync) ou `INTERNAL` (suporte Pluggy). Ausente em `item/deleted`, `connector/status_updated` e `transactions/deleted`. |
| o id da entidade | `itemId` em eventos de Item, `transactionIds` em eventos de transação, `connectorId` em eventos de conector, e assim por diante por evento. |
| `clientUserId` | Somente em eventos `item/*` — o valor definido através das `options` do Connect Token. Não em `transactions/*`: mapeie esses para seu usuário através de `itemId`. |
```json
{
"event": "item/updated",
"eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
"itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
"triggeredBy": "SYNC",
"clientUserId": "your-user-id"
}
```
## Entrega e tentativas
Uma entrega é bem-sucedida quando seu endpoint responde `2xx` **dentro de 10 segundos**. Responda primeiro, processe depois — um manipulador lento é contado como uma falha e tentado novamente.
Em caso de falha: **até 3 tentativas** no total — imediatamente, ~15 minutos após a primeira falha, e então ~2 horas após a segunda. Depois disso, o evento é descartado. Status `400`, `401`, `403`, `404` e `405` nunca são tentados novamente. Exceção: `item/login_succeeded` e `item/waiting_user_input` recebem suas 3 tentativas ~6 minutos de intervalo, nunca a espera de 2 horas.
Leia o guia: [Webhook](/docs/developer-tools/webhooks-ref) — exemplos de payload por evento e solução de problemas.
## SDKs do Lado do Servidor
Source: https://docs.pluggy.ai/pt/docs/reference/server-sdks.md
Três bibliotecas oficiais do lado do servidor envolvem a API. Cada uma é um cliente leve sobre os mesmos endpoints nesta referência; nada está disponível em uma que não esteja disponível via HTTP.
| Linguagem | Pacote | Fonte |
| --- | --- | --- |
| Node.js | `pluggy-sdk` (npm) | [pluggyai/pluggy-node](https://github.com/pluggyai/pluggy-node) |
| .NET | `Pluggy.SDK` (NuGet) | [pluggyai/pluggy-net](https://github.com/pluggyai/pluggy-net) |
| Java | `ai.pluggy:pluggy-java` (GitHub Packages) | [pluggyai/pluggy-java](https://github.com/pluggyai/pluggy-java) |
## Instalar
**Node.js**
```bash
npm install --save pluggy-sdk
```
**.NET**
```powershell
Install-Package Pluggy.SDK
```
**Java (Maven)**
```xml
ai.pluggypluggy-java1.5.0
```
O pacote Java é publicado no GitHub Packages, então `~/.m2/settings.xml` precisa do servidor do GitHub Packages com um token de acesso pessoal — veja o [guia do registro Maven do GitHub](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry).
## Gere o seu próprio
O documento OpenAPI 3 que esta referência renderiza é público:
```
https://api.pluggy.ai/oas3.json
```
Aponte um gerador para ele para qualquer outra linguagem. Clientes da comunidade também existem, por exemplo [pluggy-python](https://github.com/diraol/pluggy-python); eles não são mantidos pela Pluggy.
Leia o guia: [SDKs do lado do servidor](/docs/developer-tools/server-sdks).
## Atualizações de Produto | Setembro/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.09
---
changes:
recursos-declarados-no-consentimento-get-items-id-resources:
endpoints: ["GET /items/{id}/resources", "GET /items/{id}"]
products: [open finance]
recursos-pendentes-de-autorizacao-hasresourcespendingauthori:
endpoints: ["GET /items/{id}", "GET /items/{id}/resources"]
products: [open finance]
cobertura-de-produtos-por-instituicao-productcoverage:
endpoints: ["GET /connectors"]
products: [open finance]
incidentes-ativos-por-conector-health-incidents:
endpoints: ["GET /connectors", "GET /connectors/{id}"]
operationtype-em-transacoes-de-cartao-de-credito:
endpoints: ["GET /transactions"]
products: [cartão de crédito, open finance]
novos-campos-em-transacoes-de-cartao-open-finance:
endpoints: ["GET /transactions"]
products: [cartão de crédito, open finance]
applies_to: transações sincronizadas a partir de 28/09/2026
impostos-em-transacoes-de-renda-variavel-open-finance:
endpoints: ["GET /investments/{id}/transactions"]
products: [open finance]
simulacao-de-falha-sincrona-no-pix-automatico-sandbox:
products: [pagamentos]
nova-tela-de-consentimento-da-pluggy-para-pix-simples-sandbo:
products: [pagamentos]
pix-automatico-limite-de-tentativas-no-agendamento:
products: [pagamentos]
compras-de-cartao-pendentes-nao-sao-mais-excluidas-perto-do:
connectors: [601, 612]
products: [cartão de crédito, open finance]
sicredi-consentimento-pendente-de-aprovacao-nao-e-mais-trata:
connectors: [661, 627]
products: [open finance]
bradesco-pj-open-finance-lancamentos-diarios-de-encargos-dup:
connectors: [609]
products: [open finance]
faturas-de-cartao-disponiveis-a-partir-do-fechamento-inter-p:
connectors: [823]
products: [cartão de crédito, open finance]
scr-na-referencia-da-api:
endpoints: ["GET /items/{id}/scr"]
products: [open finance]
---
## Confira as principais novidades e melhorias da Pluggy em setembro de 2026.
- **Parcelas futuras de cartão** de BTG e Mercado Pago passam a ter data futura e deixam de ser excluídas e recriadas a cada fechamento de fatura.
- **Novo endpoint `GET /items/{id}/resources`** e o campo `hasResourcesPendingAuthorization` no Item: saiba o que o consentimento cobre e o que ainda falta o usuário autorizar no banco.
- **`GET /connectors` mais informativo**: `productCoverage` diz quais sub-produtos cada instituição serve, e `health.incidents` traz os incidentes ativos. A página de status também pode ser consultada por API.
- **`operationType` em transações de cartão**, incluindo `PAGAMENTO_FATURA` para pagamentos de fatura.
- Correções sistêmicas em **exclusões indevidas de compras de cartão**, **consentimentos pendentes de aprovação no Sicredi** e **transações duplicadas no Bradesco PJ via Open Finance**.
## Breaking changes e depreciações
**Santander Cartões (798) deslistado do Open Finance.** O conector não aceita mais novos consentimentos nem a criação de novos items.
**Conector direto Splitwise descontinuado.**
---
**Relembrando — anunciado em junho: transição para cursor pagination no endpoint de transações.** Contas criadas a partir de junho de 2026 já usam por padrão o endpoint paginado por cursor, e o endpoint legado (v1) será descontinuado para essas contas em dezembro de 2026. Até lá, o prazo de migração continua aberto.
**O que fazer:** migre para o endpoint paginado por cursor. Contas criadas antes de junho de 2026 continuam sem ser afetadas, e vamos avisar com antecedência antes de qualquer mudança para elas.
---
## 🚀 Novas Features
- → **Recursos declarados no consentimento: `GET /items/{id}/resources`** — Novo endpoint que lista os recursos que a instituição declarou para o consentimento do item, exatamente como ela reportou (`resourceId`, `type` e `status`). O `status` usa o vocabulário do Open Finance: `AVAILABLE`, `UNAVAILABLE`, `TEMPORARILY_UNAVAILABLE` e `PENDING_AUTHORISATION`. Um recurso `UNAVAILABLE` ou `PENDING_AUTHORISATION` explica um produto ausente. O novo campo `resourcesCollectedAt` do Item indica se a lista já foi lida: se ele estiver preenchido e a lista vier vazia, a instituição não declarou recursos; se for `null`, a lista ainda não foi obtida. Só vale para Open Finance: itens de conectores diretos retornam uma página vazia, sem erro.
- → **Recursos pendentes de autorização: `hasResourcesPendingAuthorization`** — O Item passa a dizer se a instituição tem recursos esperando autorização, um caso típico de conta PJ que aguarda um segundo aprovador. `true` indica pelo menos um recurso `PENDING_AUTHORISATION`, `false` indica que a lista foi lida e nada está pendente, e `null` indica que a lista ainda não foi lida ou que o conector não é Open Finance. Para saber quais recursos estão pendentes, use `GET /items/{id}/resources?status=PENDING_AUTHORISATION`. No `statusDetail`, investimentos e empréstimos pendentes passam a gerar os avisos `INV_002` e `LOAN_002`. Já disponível nos SDKs Node (`pluggy-sdk` 0.91.0), Java (1.14.0) e .NET (0.43.0).
- → **Cobertura de produtos por instituição: `productCoverage`** — `GET /connectors` passa a informar quais sub-produtos cada instituição Open Finance serve, com os nomes do diretório do Open Finance (por exemplo `CREDIT_OPERATIONS:LOANS`, `INVESTMENTS:FUNDS`, `INVESTMENTS:BANK_FIXED_INCOMES`). `products` diz se a instituição serve investimentos; `productCoverage` diz quais. Quando o campo não vem, a cobertura é desconhecida, como nos conectores diretos.
- → **Incidentes ativos por conector: `health.incidents`** — `GET /connectors` e `GET /connectors/{id}` passam a trazer os incidentes ativos de cada conector, com título, tipo, produto afetado, severidade, estado e link para a página de status. O campo só aparece quando há incidente. Repare que `health.status` pode continuar `ONLINE` com incidentes abertos. Com isso, você pode avisar o usuário na tela de seleção de banco antes que ele tente conectar uma instituição com problema.
- → **Página de status consultável por API** — `status.pluggy.ai` agora responde em `GET /api/status`, com o snapshot completo (saúde de cada conector, histórico de 90 dias e incidentes com timeline), e em `GET /api/summary`, com o status geral. Não precisa de autenticação. O identificador de cada instituição é o mesmo `id` de `GET /connectors`.
- → **`operationType` em transações de cartão de crédito** — Transações de cartão via Open Finance passam a trazer em `operationType` o tipo de transação informado pela instituição, incluindo `PAGAMENTO_FATURA`. Os pagamentos de fatura que a Pluggy gera a partir das faturas, que antes vinham com `operationType: null`, também passam a vir como `PAGAMENTO_FATURA`. A partir de agora, `operationType` pode ser informado pela instituição ou inferido pela Pluggy.
- → **Novos campos em transações de cartão (Open Finance)** — `creditCardMetadata` passa a trazer `paymentType` (`A_VISTA` ou `A_PRAZO`), `billPostDate` (a data em que a instituição lançou a transação na fatura, como ela informou) e `transactionDateTime` (data e hora da transação, normalizadas em ISO-8601). `billPostDate` vem `null` quando a transação ainda não foi lançada em uma fatura ou quando a instituição não informa a data. Nas transações do tipo `OUTROS`, o detalhe informado pela instituição passa a vir em `operationTypeAdditionalInfo`. O campo `date` não muda. Os campos são preenchidos a partir das próximas atualizações, sem retroatividade: nas transações antigas a chave não aparece, e chave ausente e `null` significam o mesmo.
- → **Impostos em transações de renda variável (Open Finance)** — Os impostos informados pela instituição nas transações de investimentos de renda variável passam a vir em `expenses.other`. O IRRF continua em `incomeTax`.
---
## 💳 Pagamentos
- → **Simulação de falha síncrona no Pix Automático (sandbox)** — Use o valor R$ 404,04 em qualquer chamada de Pix Automático no conector Sandbox Open Finance (primeiro pagamento, autorização ou agendamento recorrente) para receber na hora o erro `SANDBOX_FORCED_SYNC_ERROR`. Nada é gravado e nenhum webhook é disparado, o que simula o caso em que o banco nunca responde. Assim você consegue testar esse fluxo, que é diferente de um erro de negócio como saldo insuficiente.
- → **Nova tela de consentimento da Pluggy para Pix simples (sandbox)** — No conector Pluggy Bank (sandbox), o Pix simples ganhou uma tela de consentimento da Pluggy, para você testar o fluxo de pagamento de ponta a ponta. O pagamento é concluído normalmente, sem ficar travado em `CONSENT_AWAITING_AUTHORIZATION`.
- → **Pix Automático: limite de tentativas no agendamento** — Quando a criação de um pagamento agendado falhava antes de a instituição responder, o agendador criava um novo pagamento com erro a cada poucos minutos, sem código de erro. Agora a falha vem com o código `AUTOMATIC_PIX_SCHEDULE_UNEXPECTED_ERROR` e há um limite de tentativas por ciclo. A correção vale para todos os conectores em produção.
---
## 🛠️ Incidentes resolvidos
- → **Bradesco Empresas (conector direto)** — O conector teve instabilidade recorrente, com indisponibilidade entre 04 e 06/09, e os items terminavam em `PARTIAL_SUCCESS` porque a etapa de dados de pagamento (`paymentData`) falhava em toda execução. As duas coisas foram corrigidas.
---
## 🐛 Correções
- → **Compras de cartão pendentes não são mais excluídas perto do fechamento da fatura** — No Itaú PF (601) e no Nubank (612), compras pendentes próximas da data de fechamento eram excluídas e reapareciam dias depois. Nos conectores Open Finance, uma parcela datada fora da sua fatura podia levar à exclusão de compras ainda abertas. Os dois casos foram corrigidos.
- → **Sicredi: consentimento pendente de aprovação não é mais tratado como erro de conexão** — No Sicredi PF (661) e no Sicredi Empresas (627), consentimentos de conta conjunta ou com múltiplos aprovadores que ainda esperam aprovação retornavam `CONNECTION_ERROR`, como se o consentimento tivesse sido revogado. Agora o item fica em `USER_AUTHORIZATION_PENDING`, e você pode orientar o usuário a concluir a aprovação no banco.
- → **Bradesco PJ (Open Finance): lançamentos diários de encargos duplicados** — O Bradesco PJ (609) reenvia diariamente com um novo identificador os lançamentos de encargos e tarifas ainda em aberto, e cada atualização gravava uma nova cópia. Novas duplicatas deixaram de ser criadas.
- → **Valor da parcela em compras parceladas no cartão (Open Finance)** — No Itaú, no Banrisul e no Inter, algumas compras parceladas vinham com o valor total da compra em cada parcela, em vez do valor da parcela. Agora cada parcela traz o seu próprio valor.
- → **Itaú Empresas (conector direto): saldo nos lançamentos AUT MAIS** — Para quem tem a recuperação de lançamentos AUT MAIS ativada, as aplicações e os resgates automáticos (`APL APLIC AUT MAIS` e `RES APLIC AUT MAIS`) passam a vir com `balance`, como os demais lançamentos do extrato.
- → **Faturas de cartão disponíveis a partir do fechamento (Inter PF)** — No Inter PF (823), as faturas de cartão via Open Finance passam a chegar assim que a instituição as publica no fechamento, e não mais só na data de vencimento. Os demais conectores Open Finance vão receber a mudança de forma progressiva.
---
## 📚 Documentação
- → **SCR na referência da API** — `GET /items/{id}/scr` agora está documentado na referência pública, com os schemas de resposta, os códigos de erro e um novo guia em Open Finance → SCR. O endpoint continua disponível para os times que têm o recurso habilitado.
## Atualizações de Produto | Agosto/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.08
---
changes:
listar-as-suas-conexoes-get-v2-items:
endpoints: ["GET /v2/items"]
products: [api]
applies_to: times com o recurso "List items" habilitado
janelas-de-atualizacao-configuraveis:
products: [api]
applies_to: configuração feita pela Pluggy sob demanda
open-finance-proxy-disponivel-para-conexoes-de-alto-volume:
products: [open finance]
applies_to: times com o recurso OF Proxy habilitado
transactions-updated-agora-e-enviado-em-blocos-de-ate-400-id:
endpoints: ["GET /transactions"]
products: [webhooks]
correcao-em-patch-webhooks-id:
endpoints: ["PATCH /webhooks/{id}"]
products: [webhooks]
mensagens-de-erro-mais-claras-no-payment-request:
products: [pagamentos]
melhorias-no-mecanismo-anti-exclusao-de-transacoes:
products: [webhooks]
fatura-de-cartao-duplicada-quando-o-billid-muda-de-provisori:
endpoints: ["GET /bills"]
products: [cartão de crédito, open finance]
bradesco-pj-connector-direto-transacoes-que-deixavam-de-ser:
endpoints: ["GET /transactions"]
products: [open finance]
sinal-do-valor-em-pagamentos-recorrentes-de-cartao-de-credit:
endpoints: ["POST /recurring-payments"]
products: [cartão de crédito]
itau-empresas-connector-directo-investimentos-voltando-a-sin:
products: [investimentos]
itau-lancamentos-aut-mais-em-tempo-real:
products: [open finance]
---
## Confira as principais novidades e melhorias da Pluggy em agosto de 2026.
Destaques de agosto
- **Novo piso de frequência de atualização** para client IDs novos — é um breaking change pequeno e defensivo, com ampliação sob demanda via Suporte.
- **Novo endpoint `GET /v2/items`** para listar as suas conexões com paginação por cursor, disponível sob acordo comercial.
- **Webhooks mais robustos**: `transactions/updated` agora é enviado em blocos de até 400 ids, e cada evento cabe em uma única chamada.
- **Janelas de atualização configuráveis** para casos que precisam de sincronização em horários específicos.
- Correções sistêmicas em **transações de Bradesco PJ, faturas duplicadas de cartão e proteção contra exclusões indevidas** durante instabilidade dos bancos.
## Breaking changes e depreciações
**Frequência mínima de atualização passa a ter um padrão para client IDs novos.** Client IDs criados a partir de agosto passam a ter um valor padrão de `minUpdateFrequencyAllowedInHours`. Ao pedir uma atualização antes desse intervalo, a API responde `CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCY`. É uma proteção contra sobrecarga, não um corte de escopo.
**O que fazer:** se a sua integração precisa de atualizações mais frequentes, fale com o Suporte — o limite é ajustável por time, caso a caso. **Client IDs já existentes não são afetados.**
**`GET /transactions` (v1) passa a rejeitar mais de 500 ids no parâmetro `ids`.** A chamada retorna `400 IDS_PARAMETER_EXCEEDS_MAX_LENGTH`, o mesmo comportamento que a v2 já tinha. Antes, o v1 aceitava a chamada sem validar.
**O que fazer:** divida a consulta em blocos de até 500 ids. Se você consome os `transactionIds` do webhook `transactions/updated`, isso já vem resolvido — veja a mudança em Webhooks.
---
**Relembrando — anunciado em junho: transição para cursor pagination no endpoint de transações.** Contas criadas a partir de junho de 2026 já usam por padrão o endpoint paginado por cursor, e o endpoint legado (v1) segue em descontinuação gradual para essas contas. Este é o terceiro aviso e o prazo de migração continua aberto.
**O que fazer:** migre para o endpoint paginado por cursor. Contas criadas antes de junho de 2026 continuam sem ser afetadas; avisaremos com antecedência antes de qualquer mudança para elas.
**Relembrando — anunciado em julho: conectores diretos para pessoa física em descontinuação.** Bradesco PF, Sicredi PJ e Itaú PF já foram deslistados e o XP segue o mesmo caminho. **As conexões afetadas serão removidas nos próximos meses** e nada foi removido até agora.
**O que fazer:** migre essas conexões para o conector de Open Finance equivalente. Não há migração automática — o usuário final precisa refazer a conexão, e o histórico do item direto não é transferido.
---
## 🚀 Novas Features
- → **Listar as suas conexões: `GET /v2/items`** — Até agora não era possível listar items pela API e cada integração precisava guardar os `itemId` na própria base. O novo endpoint devolve os items do seu time, do mais recente para o mais antigo, com paginação por cursor e os mesmos campos de `GET /items/{id}`. Aceita os filtros `clientUserId` e `connectorId`. **É opt-in:** vem desativado por padrão e, sem a liberação, a chamada responde `403 LIST_ITEMS_FEATURE_NOT_ENABLED` — listar permite enumerar todos os items do time, um acesso mais amplo do que buscar um item por id, então a habilitação passa por acordo comercial.
- → **Janelas de atualização configuráveis** — Agora é possível configurar em quais horários os seus items são atualizados automaticamente, em vez de depender apenas do ciclo padrão. Útil para quem precisa detectar movimentações em horários específicos do dia. A configuração é feita pela Pluggy sob demanda — fale com o Suporte com os horários que fazem sentido para o seu caso.
- → **Open Finance Proxy disponível para conexões de alto volume** — O Open Finance Proxy deixa de estar restrito a conexões que já tinham batido o limite de recursos da instituição (`RESOURCES_LIMIT_EXCEEDED`) e passa a atender também conexões elegíveis por volume. A elegibilidade é definida pela Pluggy e o acesso é habilitado por time, mediante avaliação. **O que fazer:** se você tem conexões com muitas contas ou um volume alto de transações e vê falhas de limite de recursos, fale com o Suporte para avaliarmos a habilitação para o seu time.
---
## 🔔 Webhooks
- → **`transactions/updated` agora é enviado em blocos de até 400 ids** — Em atualizações grandes, o webhook enviava todos os `transactionIds` em um único evento, e o array não cabia em uma chamada a `GET /transactions?ids=`. Agora 600 transações atualizadas geram dois webhooks (400 + 200), cada um com o seu `transactionsCount`, e cada evento cabe em uma única chamada, podendo ser consumido diretamente sem quebrar a lista.
- → **Correção em `PATCH /webhooks/{id}`** — O endpoint retornava `500` ao atualizar apenas os headers (mesmo assim aplicando a alteração) e `400` dizendo que o webhook já existia quando `url` ou `event` eram enviados, porque a validação de unicidade comparava o registro com ele mesmo.
---
## 💳 Pagamentos
- → **Mensagens de erro mais claras no payment request** — As mensagens retornadas quando uma solicitação de pagamento falha foram revisadas para indicar de forma mais direta o que aconteceu e o que fazer.
---
## 🐛 Correções
- → **Melhorias no mecanismo anti-exclusão de transações** — Quando uma instituição para de retornar temporariamente transações que já existiam, elas eram marcadas como excluídas e reapareciam dias depois, gerando buracos no extrato e webhooks de exclusão indevidos. A exclusão coordenada passa a ser suspensa nesses cenários, evitando que uma instabilidade do banco vire perda de dados no seu lado.
- → **Fatura de cartão duplicada quando o `billId` muda de provisório para definitivo** — Antes do fechamento, a instituição retorna um `billId` provisório baseado na data de vencimento projetada; após a consolidação, o definitivo. Quando a data de vencimento mudava nessa troca, as duas faturas não eram unificadas e a fatura aparecia duplicada. A comparação agora tolera pequenos ajustes de data.
- → **Bradesco PJ (Connector Direto): transações que deixavam de ser retornadas** — Corrigidos três casos que causavam perda de lançamentos: a consulta por período subcapturava o volume mensal e perdia transações já efetivadas em sincronizações históricas e parciais; lançamentos idênticos repetidos no mesmo dia eram descartados como duplicados; e uma transação que deveria aparecer três vezes era retornada uma só.
- → **Sinal do valor em pagamentos recorrentes de cartão de crédito** — Na API de Recurring Payments (`POST /recurring-payments`), uma cobrança recorrente de cartão vinha com `averageAmount` positivo e podia ser lida como receita. O valor agora segue a convenção bancária, como a documentação sempre indicou: despesa negativa. As mesmas recorrências continuam sendo detectadas — apenas o sinal muda.
- → **Itaú Empresas (Connector Directo): investimentos voltando a sincronizar** — Corrigida a falha em massa que impedia o retorno de investimentos desde o final de julho.
- → **Itaú: lançamentos AUT MAIS em tempo real** — Os lançamentos do AUT MAIS passam a ficar disponíveis em tempo real, sem o atraso que existia antes.
## Atualizações de produto | Julho/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.07
## Confira as principais novidades e melhorias da Pluggy em julho de 2026.
Destaques de julho
- **Grande expansão da cobertura de pagamentos**: 6 conectores novos e 30 instituições que já existiam para dados passaram a suportar iniciação de pagamento.
- Deprecação dos **conectores diretos para pessoa física**, com as conexões afetadas sendo removidas nos próximos meses.
- Novos campos `billForecastDate` e `billClosingDate` em transações e faturas de cartão de crédito, e novo endpoint para remover regras de categorização.
- Novo conector de dados via Open Finance: **Celcoin Baas** (PF, em BETA).
- Diversas correções de estabilidade em cartões, investimentos, sincronizações e conectividade, além do SDK React Native com OAuth no iOS.
## Breaking changes e depreciações
**Conectores diretos para pessoa física entram em descontinuação.** Bradesco PF e Itaú já foram deslistados e o XP segue o mesmo caminho. O acesso fica restrito a um conjunto limitado de aplicações; para as demais, o conector deixa de ser retornado.
**O que fazer:** migre essas conexões para o conector de Open Finance equivalente. **Não há migração automática** — o usuário final precisa refazer a conexão, e o histórico do item direto não é transferido. **As conexões afetadas serão removidas nos próximos meses**, então vale planejar a migração agora.
**Conector Dock (810) descontinuado.** A marca saiu do diretório de participantes do Open Finance e o conector foi deslistado.
***
**Relembrando — anunciado em junho: transição para cursor pagination no endpoint de transações.** Contas criadas a partir de junho de 2026 já usam por padrão o endpoint paginado por cursor, e o endpoint legado (v1) segue em descontinuação gradual para essas contas.
**O que fazer:** se a sua integração ainda usa o endpoint legado, migre para o paginado por cursor. Contas criadas antes de junho de 2026 continuam sem ser afetadas por enquanto — avisaremos com antecedência antes de qualquer mudança para elas.
## 📡 Novos Conectores
- **Grande expansão da cobertura de pagamentos** — 6 conectores novos, exclusivos de pagamento, com suporte a PIX imediato, agendado, Smart Transfer e Pix Automático: **Contabilizei** (PJ), **Nação BRB FLA** (PF), **BBC Digital** (PF), **Impact Bank** (PF), **Revolut** (PF) e **iFood Pago** (PJ).
- **30 instituições passaram a suportar pagamento** — Instituições que já existiam para dados agora aceitam PIX imediato e agendado. Para PF e PJ: 6P Bank, Apex, Axiis Bank, Banco BRB, BPO Bank, Ella Bank, Health Cash, Hiperbanco, Imobi Bank, Lothus, Meirelles, Nitybank, Ovni, PagueVeloz Serasa, Rapidium Bank, Resolve Bank, Rhiza Bank, Simpbank, Snob Bank, Uze e Won Bank. Somente PF: Conta Universal, CRB Money, ESBank, Get Conta by Getnet, HausBank, iHold, POWPAY e Rico. Somente PJ: XP Empresas.
- **Celcoin Baas (Open Finance, dados)** — Novo conector para pessoa física, em stage BETA, com suporte a Accounts, Transactions e Identity.
## 🚀 Novas Features
- **Cartão de crédito: novos campos `billForecastDate` e `billClosingDate`** — As transações e faturas de cartão de crédito passam a retornar a data prevista da fatura e a data de fechamento, conforme a especificação do Open Finance Brasil. **Atenção:** estes campos são retornados apenas para conexões criadas após a implementação; conexões anteriores não retornarão esses valores.
- **Novo endpoint para remover regras de categorização** — `DELETE /categories/rules/:id` permite excluir uma regra de categorização criada anteriormente, completando o ciclo de gerenciamento pela API.
- **Open Finance: recuperação automática de conexões com falha** — Conexões de Open Finance que acumulam 5 erros consecutivos passam a ser reprocessadas automaticamente uma vez por dia, até que uma sincronização bem-sucedida as recupere. Antes, essas conexões ficavam paradas e exigiam reconexão manual.
## 💳 Pagamentos
- **Pix Automático: cobrança com consentimento cancelado corrigida** — Corrigido um caso em que uma cobrança de Pix Automático podia ser processada mesmo após o consentimento ter sido cancelado.
## 🔔 Webhooks
- **Correção em retentativas em massa** — Corrigido um cenário em que um volume grande de retentativas deixava de ser enviado.
## 🖥️ Dashboard
- **Logo para o modo escuro** — Agora é possível enviar um logo específico para o modo escuro do Connect, além do logo principal. Se nenhum for enviado, o logo do modo claro é usado nos dois temas.
- **Apps de desenvolvimento e produção separados na lista de webhooks** — Corrigido um problema em que aplicações dos dois ambientes apareciam misturadas ao configurar webhooks.
- **Correções em Pagamentos** — Corrigidos a data exibida em Pix agendado, a criação de Pix Automático pelo dashboard e a listagem de recebedores.
## 🐛 Correções
- **Banco do Brasil: saldo do Rende Fácil** — Corrigido um caso em que o saldo aparecia zerado quando o valor estava aplicado no Rende Fácil. O BB retorna `availableAmount = 0` nessa situação, e agora o valor aplicado é considerado no saldo da conta, como já acontecia no Itaú.
- **Cartões de crédito: datas de fatura e isolamento de erros** — Corrigidas as datas de fechamento e vencimento quando a instituição retorna faturas fora de ordem cronológica, e corrigido um caso em que um cartão com erro esvaziava as transações dos demais cartões do mesmo item.
- **Investimentos** — Corrigida a falha em contas BBA do Itaú PJ e melhorado o tratamento de erros de rate limit no conector de investimentos.
- **Sincronizações mais resilientes** — Evitadas execuções infinitas em conexões com `CONNECTION_ERROR`; corrigidas as datas usadas em sincronizações parciais após um erro de mesclagem; adicionada retentativa inteligente para primeiras conexões do Sicoob que retornavam sem dados; corrigidas transações ausentes no Sicoob (OF), no sync diário do BB PJ quando `ACCOUNTS` não estava entre os produtos, e na Caixa PJ quando a data inicial era anterior à abertura da conta.
- **Itaú: lançamentos SISPAG desmembrados** — Corrigido o tratamento de lançamentos de salário do SISPAG que passavam a ser retornados de forma desmembrada após a habilitação do AUT MAIS.
- **Conectividade restaurada** — Estabilidade restaurada em Nubank PF (Open Finance), XP e Celcoin.
- **Connect Widget: botão de conectar** — Corrigidos casos em que o texto do botão de conectar não aparecia ou o botão não respondia.
- **SDK React Native: conexões OAuth no iOS** — `react-native-pluggy-connect@1.5.0` adiciona a prop `forceOauthInBrowser`. Com `false`, o OAuth abre em uma WebView dentro do app em vez do navegador do sistema, resolvendo conexões de conectores regulados que ficavam presas em `WAITING_USER_INPUT` até expirar no iOS. O padrão continua `true`, então a mudança é opt-in.
## Atualizações de produto | Junho/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.06
## Confira as principais novidades e melhorias da Pluggy em junho de 2026.
Destaques de junho
- Transição para **cursor pagination** no endpoint de transações em contas criadas a partir de junho, com descontinuação gradual do endpoint legado (v1).
- Open Finance mais completo, com novos campos em investimentos (isenção fiscal, classificação Anbima, nota de corretagem, cupom do Tesouro), em cartão de crédito (tipo de tarifa e de operação de crédito), código ISPB da contraparte, saldos reservados e data de carência em renda fixa.
- Pix Automático mais transparente, com dados da conta debitada, banco do recebedor, horários e identificadores de conciliação nas respostas, além de correções em retentativas e no ambiente sandbox.
- Evolução do Dashboard, com filtro por Customer ID em Payments e português como idioma padrão para novas contas.
- Diversas correções de estabilidade em conectores, faturas de cartão, sincronizações de Open Finance, empréstimos duplicados e no Connect Widget.
## Breaking changes e depreciações
**Transição para cursor pagination no endpoint de transações.** Contas criadas a partir de junho de 2026 passam a usar por padrão o endpoint de transações com cursor pagination. O endpoint legado (v1) está em descontinuação gradual para essas contas.
**O que fazer:** se a sua integração usa o endpoint legado, migre para o paginado por cursor. A documentação e os guias já refletem a mudança, e o SDK foi atualizado para suportá-lo.
Contas criadas antes de junho de 2026 não são afetadas neste momento.
## 🚀 Novas Features
- **Open Finance: novos campos de investimentos** — Novos campos disponíveis para investimentos via Open Finance, incluindo indicador de isenção fiscal (LCI/LCA/CRI/CRA), dados do devedor em CRI/CRA, periodicidade de remuneração, fator de preço para renda variável, classificação Anbima de fundos, número da nota de corretagem e informações de cupom para títulos do Tesouro Direto.
- **Open Finance: novos campos de cartão de crédito** — Novos campos de categorização em cartões de crédito, incluindo tipo detalhado de tarifa, tipo de operação de crédito, informação de bandeira quando classificada como "outras" e motivo de limite zerado.
- **Open Finance: novo código de contraparte em transações** — Transações de contas agora retornam o código ISPB da instituição de contraparte e uma descrição adicional para transações classificadas como "outros", melhorando a categorização.
- **Open Finance: suporte a saldos reservados** — Novo campo `hasReservedBalance` e endpoint dedicado para consultar valores bloqueados ou reservados em conta (ex.: bloqueios judiciais, Pix agendado), oferecendo uma visão mais precisa do saldo disponível.
- **Open Finance: campo `gracePeriodDate` para renda fixa** — Investimentos de renda fixa (CDB, LCI, LCA, CRI, CRA, Debêntures) agora retornam a data de carência via Open Finance.
- **Códigos de erro mais específicos no endpoint de saldo** — O endpoint de saldo (balance) agora retorna códigos de erro mais granulares, em vez de agrupar a maioria das falhas sob um erro genérico, facilitando o tratamento pela sua integração.
- **Limite do `clientUserId` padronizado** — O limite máximo do campo `clientUserId` foi padronizado em 500 caracteres em todos os endpoints da API (Item, Connect Token e Investments), eliminando inconsistências entre os limites anteriores.
## 💳 Pagamentos
- **Pix Automático: respostas de pagamento mais completas** — As respostas de autorização e pagamento do Pix Automático agora incluem mais informações: dados da conta debitada, banco do recebedor, horários de autorização e atualização, motivo detalhado de erros e identificadores para conciliação (`consentId`, `transactionIdentification`).
- **Pix Automático: correção na lógica de retentativas** — Corrigido o registro de datas em tentativas de retentativa com falha, que agora refletem a data de cada tentativa individual em vez da data original do pagamento. O sistema também passou a evitar novos agendamentos automáticos quando a instituição retorna erro de limite de período excedido.
- **Pix Automático: correções no ambiente sandbox** — Corrigidos o erro 500 ao cancelar um agendamento e a falha ao gerar um payment request via dashboard, ambos no modo sandbox.
- **Correção no status de pagamentos concluídos** — Corrigido um problema em que um pagamento já concluído podia ter seu status sobrescrito para erro quando uma tentativa (intent) subsequente expirava ou era rejeitada.
- **Smart Transfers: correção em preautorizações** — Corrigido um erro que impedia a geração de preautorizações de Smart Transfer para clientes que selecionam determinadas instituições recebedoras.
## 🖥️ Dashboard
- **Filtro por Customer ID em Payments** — A seção Payments > Customers agora permite filtrar registros diretamente pelo Customer ID, facilitando localizar pagamentos de um cliente específico.
- **Idioma padrão em português** — O idioma padrão do dashboard ao criar uma nova conta passou a ser português (pt-BR).
## 🐛 Correções
- **Conector Santander PJ: deduplicação de transações corrigida** — Corrigida uma falha que descartava indevidamente transações distintas que compartilhavam a mesma data, valor, descrição e saldo, tratando-as incorretamente como duplicatas.
- **Cartões de crédito (Open Finance): sincronização parcial aprimorada** — A busca de faturas em sincronizações parciais agora acompanha corretamente o período das transações, aumentando significativamente a proporção de transações corretamente associadas à fatura.
- **Confiabilidade nas sincronizações Open Finance** — Corrigidos casos de falso sucesso em sincronizações que na verdade indicavam instabilidade, e erros de mesclagem (MERGE_ERROR) causados por transações retornadas sem moeda definida.
- **Duplicação de empréstimos corrigida** — Corrigida a duplicação de dados de empréstimos (loans) em conexões Open Finance, incluindo a limpeza de duplicatas já existentes.
- **Conector Bradesco PJ: validação de usuário restaurada** — Corrigida a validação de usuários não suportados (USER_NOT_SUPPORTED), que havia deixado de funcionar corretamente.
- **Conector Bradesco: mensagens de erro com acentuação corrigida** — Corrigida a codificação de caracteres especiais nas mensagens de erro (ex.: credenciais inválidas), que exibiam caracteres inválidos ao usuário final.
- **Conectividade restaurada em conectores diretos** — Restaurada a conectividade em conectores diretos que estavam bloqueados (Sicredi PJ e Bradesco PF).
- **Connect Widget: filtro por tipo de conector corrigido** — Corrigido um bug que fazia com que determinadas combinações de tipos de conector informadas ao widget não exibissem os conectores esperados.
- **Connect Widget: modo de pessoa física/jurídica em pagamentos** — Corrigido um problema em que o widget não considerava corretamente o tipo de conta (pessoa física ou jurídica) do cliente ao iniciar um fluxo de pagamento, exigindo troca manual do modo.
- **Connect Widget: sobreposição de notificação corrigida** — Corrigida uma sobreposição entre mensagens de notificação e a lista de contas disponíveis no widget, que podia dificultar a seleção da conta correta.
## 📚 Documentação
- **SDK .NET: suporte a cursor pagination** — O SDK .NET foi atualizado para suportar cursor pagination, alinhando-o às capacidades atuais da API.
## Atualizações de Produto | Julho/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.07
## Confira as principais novidades e melhorias da Pluggy em julho de 2026.
Destaques de julho
- **Grande expansão da cobertura de pagamentos**: 6 conectores novos e 30 instituições que já existiam para dados passaram a suportar iniciação de pagamento.
- Deprecação dos **conectores diretos para pessoa física**, com as conexões afetadas sendo removidas nos próximos meses.
- Novos campos `billForecastDate` e `billClosingDate` em transações e faturas de cartão de crédito, e novo endpoint para remover regras de categorização.
- Novo conector de dados via Open Finance: **Celcoin Baas** (PF, em BETA).
- Diversas correções de estabilidade em cartões, investimentos, sincronizações e conectividade, além do SDK React Native com OAuth no iOS.
## Breaking changes e depreciações
**Conectores diretos para pessoa física entram em descontinuação.** Bradesco PF e Itaú já foram deslistados e o XP segue o mesmo caminho. O acesso fica restrito a um conjunto limitado de aplicações; para as demais, o conector deixa de ser retornado.
**O que fazer:** migre essas conexões para o conector de Open Finance equivalente. **Não há migração automática** — o usuário final precisa refazer a conexão, e o histórico do item direto não é transferido. **As conexões afetadas serão removidas nos próximos meses**, então vale planejar a migração agora.
**Conector Dock (810) descontinuado.** A marca saiu do diretório de participantes do Open Finance e o conector foi deslistado.
***
**Relembrando — anunciado em junho: transição para cursor pagination no endpoint de transações.** Contas criadas a partir de junho de 2026 já usam por padrão o endpoint paginado por cursor, e o endpoint legado (v1) segue em descontinuação gradual para essas contas.
**O que fazer:** se a sua integração ainda usa o endpoint legado, migre para o paginado por cursor. Contas criadas antes de junho de 2026 continuam sem ser afetadas por enquanto — avisaremos com antecedência antes de qualquer mudança para elas.
## 📡 Novos Conectores
- **Grande expansão da cobertura de pagamentos** — 6 conectores novos, exclusivos de pagamento, com suporte a PIX imediato, agendado, Smart Transfer e Pix Automático: **Contabilizei** (PJ), **Nação BRB FLA** (PF), **BBC Digital** (PF), **Impact Bank** (PF), **Revolut** (PF) e **iFood Pago** (PJ).
- **30 instituições passaram a suportar pagamento** — Instituições que já existiam para dados agora aceitam PIX imediato e agendado. Para PF e PJ: 6P Bank, Apex, Axiis Bank, Banco BRB, BPO Bank, Ella Bank, Health Cash, Hiperbanco, Imobi Bank, Lothus, Meirelles, Nitybank, Ovni, PagueVeloz Serasa, Rapidium Bank, Resolve Bank, Rhiza Bank, Simpbank, Snob Bank, Uze e Won Bank. Somente PF: Conta Universal, CRB Money, ESBank, Get Conta by Getnet, HausBank, iHold, POWPAY e Rico. Somente PJ: XP Empresas.
- **Celcoin Baas (Open Finance, dados)** — Novo conector para pessoa física, em stage BETA, com suporte a Accounts, Transactions e Identity.
## 🚀 Novas Features
- **Cartão de crédito: novos campos `billForecastDate` e `billClosingDate`** — As transações e faturas de cartão de crédito passam a retornar a data prevista da fatura e a data de fechamento, conforme a especificação do Open Finance Brasil. **Atenção:** estes campos são retornados apenas para conexões criadas após a implementação; conexões anteriores não retornarão esses valores.
- **Novo endpoint para remover regras de categorização** — `DELETE /categories/rules/:id` permite excluir uma regra de categorização criada anteriormente, completando o ciclo de gerenciamento pela API.
- **Open Finance: recuperação automática de conexões com falha** — Conexões de Open Finance que acumulam 5 erros consecutivos passam a ser reprocessadas automaticamente uma vez por dia, até que uma sincronização bem-sucedida as recupere. Antes, essas conexões ficavam paradas e exigiam reconexão manual.
## 💳 Pagamentos
- **Pix Automático: cobrança com consentimento cancelado corrigida** — Corrigido um caso em que uma cobrança de Pix Automático podia ser processada mesmo após o consentimento ter sido cancelado.
## 🔔 Webhooks
- **Correção em retentativas em massa** — Corrigido um cenário em que um volume grande de retentativas deixava de ser enviado.
## 🖥️ Dashboard
- **Logo para o modo escuro** — Agora é possível enviar um logo específico para o modo escuro do Connect, além do logo principal. Se nenhum for enviado, o logo do modo claro é usado nos dois temas.
- **Apps de desenvolvimento e produção separados na lista de webhooks** — Corrigido um problema em que aplicações dos dois ambientes apareciam misturadas ao configurar webhooks.
- **Correções em Pagamentos** — Corrigidos a data exibida em Pix agendado, a criação de Pix Automático pelo dashboard e a listagem de recebedores.
## 🐛 Correções
- **Banco do Brasil: saldo do Rende Fácil** — Corrigido um caso em que o saldo aparecia zerado quando o valor estava aplicado no Rende Fácil. O BB retorna `availableAmount = 0` nessa situação, e agora o valor aplicado é considerado no saldo da conta, como já acontecia no Itaú.
- **Cartões de crédito: datas de fatura e isolamento de erros** — Corrigidas as datas de fechamento e vencimento quando a instituição retorna faturas fora de ordem cronológica, e corrigido um caso em que um cartão com erro esvaziava as transações dos demais cartões do mesmo item.
- **Investimentos** — Corrigida a falha em contas BBA do Itaú PJ e melhorado o tratamento de erros de rate limit no conector de investimentos.
- **Sincronizações mais resilientes** — Evitadas execuções infinitas em conexões com `CONNECTION_ERROR`; corrigidas as datas usadas em sincronizações parciais após um erro de mesclagem; adicionada retentativa inteligente para primeiras conexões do Sicoob que retornavam sem dados; corrigidas transações ausentes no Sicoob (OF), no sync diário do BB PJ quando `ACCOUNTS` não estava entre os produtos, e na Caixa PJ quando a data inicial era anterior à abertura da conta.
- **Itaú: lançamentos SISPAG desmembrados** — Corrigido o tratamento de lançamentos de salário do SISPAG que passavam a ser retornados de forma desmembrada após a habilitação do AUT MAIS.
- **Conectividade restaurada** — Estabilidade restaurada em Nubank PF (Open Finance), XP e Celcoin.
- **Connect Widget: botão de conectar** — Corrigidos casos em que o texto do botão de conectar não aparecia ou o botão não respondia.
- **SDK React Native: conexões OAuth no iOS** — `react-native-pluggy-connect@1.5.0` adiciona a prop `forceOauthInBrowser`. Com `false`, o OAuth abre em uma WebView dentro do app em vez do navegador do sistema, resolvendo conexões de conectores regulados que ficavam presas em `WAITING_USER_INPUT` até expirar no iOS. O padrão continua `true`, então a mudança é opt-in.
## Atualizações de Produto | Junho/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.06
## Confira as principais novidades e melhorias da Pluggy em junho de 2026.
Destaques de junho
- Transição para **cursor pagination** no endpoint de transações em contas criadas a partir de junho, com descontinuação gradual do endpoint legado (v1).
- Open Finance mais completo, com novos campos em investimentos (isenção fiscal, classificação Anbima, nota de corretagem, cupom do Tesouro), em cartão de crédito (tipo de tarifa e de operação de crédito), código ISPB da contraparte, saldos reservados e data de carência em renda fixa.
- Pix Automático mais transparente, com dados da conta debitada, banco do recebedor, horários e identificadores de conciliação nas respostas, além de correções em retentativas e no ambiente sandbox.
- Evolução do Dashboard, com filtro por Customer ID em Payments e português como idioma padrão para novas contas.
- Diversas correções de estabilidade em conectores, faturas de cartão, sincronizações de Open Finance, empréstimos duplicados e no Connect Widget.
## Breaking changes e depreciações
**Transição para cursor pagination no endpoint de transações.** Contas criadas a partir de junho de 2026 passam a usar por padrão o endpoint de transações com cursor pagination. O endpoint legado (v1) está em descontinuação gradual para essas contas.
**O que fazer:** se a sua integração usa o endpoint legado, migre para o paginado por cursor. A documentação e os guias já refletem a mudança, e o SDK foi atualizado para suportá-lo.
Contas criadas antes de junho de 2026 não são afetadas neste momento.
## 🚀 Novas Features
- **Open Finance: novos campos de investimentos** — Novos campos disponíveis para investimentos via Open Finance, incluindo indicador de isenção fiscal (LCI/LCA/CRI/CRA), dados do devedor em CRI/CRA, periodicidade de remuneração, fator de preço para renda variável, classificação Anbima de fundos, número da nota de corretagem e informações de cupom para títulos do Tesouro Direto.
- **Open Finance: novos campos de cartão de crédito** — Novos campos de categorização em cartões de crédito, incluindo tipo detalhado de tarifa, tipo de operação de crédito, informação de bandeira quando classificada como "outras" e motivo de limite zerado.
- **Open Finance: novo código de contraparte em transações** — Transações de contas agora retornam o código ISPB da instituição de contraparte e uma descrição adicional para transações classificadas como "outros", melhorando a categorização.
- **Open Finance: suporte a saldos reservados** — Novo campo `hasReservedBalance` e endpoint dedicado para consultar valores bloqueados ou reservados em conta (ex.: bloqueios judiciais, Pix agendado), oferecendo uma visão mais precisa do saldo disponível.
- **Open Finance: campo `gracePeriodDate` para renda fixa** — Investimentos de renda fixa (CDB, LCI, LCA, CRI, CRA, Debêntures) agora retornam a data de carência via Open Finance.
- **Códigos de erro mais específicos no endpoint de saldo** — O endpoint de saldo (balance) agora retorna códigos de erro mais granulares, em vez de agrupar a maioria das falhas sob um erro genérico, facilitando o tratamento pela sua integração.
- **Limite do `clientUserId` padronizado** — O limite máximo do campo `clientUserId` foi padronizado em 500 caracteres em todos os endpoints da API (Item, Connect Token e Investments), eliminando inconsistências entre os limites anteriores.
## 💳 Pagamentos
- **Pix Automático: respostas de pagamento mais completas** — As respostas de autorização e pagamento do Pix Automático agora incluem mais informações: dados da conta debitada, banco do recebedor, horários de autorização e atualização, motivo detalhado de erros e identificadores para conciliação (`consentId`, `transactionIdentification`).
- **Pix Automático: correção na lógica de retentativas** — Corrigido o registro de datas em tentativas de retentativa com falha, que agora refletem a data de cada tentativa individual em vez da data original do pagamento. O sistema também passou a evitar novos agendamentos automáticos quando a instituição retorna erro de limite de período excedido.
- **Pix Automático: correções no ambiente sandbox** — Corrigidos o erro 500 ao cancelar um agendamento e a falha ao gerar um payment request via dashboard, ambos no modo sandbox.
- **Correção no status de pagamentos concluídos** — Corrigido um problema em que um pagamento já concluído podia ter seu status sobrescrito para erro quando uma tentativa (intent) subsequente expirava ou era rejeitada.
- **Smart Transfers: correção em preautorizações** — Corrigido um erro que impedia a geração de preautorizações de Smart Transfer para clientes que selecionam determinadas instituições recebedoras.
## 🖥️ Dashboard
- **Filtro por Customer ID em Payments** — A seção Payments > Customers agora permite filtrar registros diretamente pelo Customer ID, facilitando localizar pagamentos de um cliente específico.
- **Idioma padrão em português** — O idioma padrão do dashboard ao criar uma nova conta passou a ser português (pt-BR).
## 🐛 Correções
- **Conector Santander PJ: deduplicação de transações corrigida** — Corrigida uma falha que descartava indevidamente transações distintas que compartilhavam a mesma data, valor, descrição e saldo, tratando-as incorretamente como duplicatas.
- **Cartões de crédito (Open Finance): sincronização parcial aprimorada** — A busca de faturas em sincronizações parciais agora acompanha corretamente o período das transações, aumentando significativamente a proporção de transações corretamente associadas à fatura.
- **Confiabilidade nas sincronizações Open Finance** — Corrigidos casos de falso sucesso em sincronizações que na verdade indicavam instabilidade, e erros de mesclagem (MERGE_ERROR) causados por transações retornadas sem moeda definida.
- **Duplicação de empréstimos corrigida** — Corrigida a duplicação de dados de empréstimos (loans) em conexões Open Finance, incluindo a limpeza de duplicatas já existentes.
- **Conector Bradesco PJ: validação de usuário restaurada** — Corrigida a validação de usuários não suportados (USER_NOT_SUPPORTED), que havia deixado de funcionar corretamente.
- **Conector Bradesco: mensagens de erro com acentuação corrigida** — Corrigida a codificação de caracteres especiais nas mensagens de erro (ex.: credenciais inválidas), que exibiam caracteres inválidos ao usuário final.
- **Conectividade restaurada em conectores diretos** — Restaurada a conectividade em conectores diretos que estavam bloqueados (Sicredi PJ e Bradesco PF).
- **Connect Widget: filtro por tipo de conector corrigido** — Corrigido um bug que fazia com que determinadas combinações de tipos de conector informadas ao widget não exibissem os conectores esperados.
- **Connect Widget: modo de pessoa física/jurídica em pagamentos** — Corrigido um problema em que o widget não considerava corretamente o tipo de conta (pessoa física ou jurídica) do cliente ao iniciar um fluxo de pagamento, exigindo troca manual do modo.
- **Connect Widget: sobreposição de notificação corrigida** — Corrigida uma sobreposição entre mensagens de notificação e a lista de contas disponíveis no widget, que podia dificultar a seleção da conta correta.
## 📚 Documentação
- **SDK .NET: suporte a cursor pagination** — O SDK .NET foi atualizado para suportar cursor pagination, alinhando-o às capacidades atuais da API.
## Atualizações de produto | Maio/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.05
## Confira as principais novidades e melhorias da Pluggy em maio de 2026.
Destaques de maio
- Suporte ao novo CNPJ alfanumérico, garantindo compatibilidade com o novo padrão da Receita Federal sem necessidade de ajustes nas integrações.
- Expansão do Open Finance, com novos tipos de operações de crédito, dados de identidade mais completos e suporte a conexões com grande volume de contas.
- Evolução da API e do Dashboard, com novos filtros de transações, paginação por cursor, filtros avançados de webhooks e melhorias no upload de documentos.
- Melhorias no Connect Widget, incluindo suporte ao fluxo de Múltipla Alçada e orientações mais claras para cenários de limite de recursos.
- Diversas correções de estabilidade em conectores, transações, pagamentos, webhooks e sincronização, além de atualizações nos SDKs e na documentação.
## 🚀 Novas Features
- → **Suporte ao novo CNPJ alfanumérico** — A API Pluggy agora aceita e processa CNPJs no novo formato alfanumérico exigido pela Receita Federal, sem necessidade de ajustes no seu sistema de integração.
- → **Open Finance: novos tipos de operação de crédito disponíveis** — Agora você pode recuperar dados de financiamentos, financiamento de faturas e crédito em conta corrente via Open Finance, ampliando significativamente a cobertura de dados de crédito disponíveis para análise.
- → **Open Finance: campos de identidade ampliados** — Os dados de identificação, qualificação e relações financeiras do Open Finance agora retornam campos adicionais que anteriormente estavam ausentes, aumentando a completude das informações de identidade do usuário.
- → **API: novos parâmetros de filtro em transações** — Novos campos de filtro e opções de paginação foram adicionados à API de transações, permitindo consultas mais precisas e flexíveis ao histórico de dados.
- → **Open Finance: suporte a itens com alto volume de contas** — Conexões Open Finance com grande número de contas e recursos vinculados agora têm.
- dados acessíveis em todos os endpoints, eliminando lacunas de cobertura para clientes com carteiras amplas.
- → **Widget: tela de Múltipla Alçada** — O Connect Widget agora inclui uma tela dedicada ao fluxo de Múltipla Alçada, permitindo que usuários em processos que exigem aprovação de múltiplos responsáveis concluam a conexão sem atrito.
- → **Widget: orientação para o status **`RESOURCES_LIMIT_EXCEEDED` — O Connect Widget agora exibe uma mensagem clara e orientação ao usuário quando uma conexão Open Finance atinge o limite de recursos, melhorando a experiência em cenários de alto volume.
- → **Sandbox: maior volume de transações para testes** — O ambiente sandbox agora retorna um volume maior de transações históricas, facilitando o desenvolvimento e testes de funcionalidades que dependem de histórico transacional extenso.
***
## 📡 Novos Conectores
- → **Banrisul PJ disponível para todos os clientes** — O conector Banrisul para pessoa jurídica agora está disponível para todos os clientes da Pluggy, sem necessidade de habilitação manual pela equipe de suporte.
***
## 💳 Pagamentos
- → **PixAuto: erro explícito ao cancelar pagamento na mesma data** — Ao tentar cancelar um pagamento PixAuto agendado para o dia atual, a API agora retorna um erro claro e descritivo, evitando comportamento inesperado ou falha silenciosa.
***
## 🔔 Webhooks
- → **Correção no timing do evento **`item/created`** para Open Finance** — Corrigido um problema em que o evento `item/created` era disparado antes que a conexão Open Finance fosse aprovada pela instituição financeira, causando notificações prematuras no seu sistema.
***
## 🖥️ Dashboard
- → **Filtragem por data e hora nos webhooks** — O painel de webhooks agora permite filtrar eventos por data e hora com precisão de minutos, simplificando a investigação de eventos em janelas de tempo específicas.
- → **Limite de upload de documentos aumentado para 20 MB** — O formulário de Due Diligence agora aceita arquivos de até 20 MB, eliminando erros ao enviar documentos maiores como extratos e contratos.
- → **Paginação por cursor nas transações** — A listagem de transações no Dashboard passou a usar cursor pagination, tornando a navegação mais rápida e estável em contas com grande volume de dados.
***
## 🐛 Correções
- → **Reprocessamento histórico de dados Open Finance restaurado** — A funcionalidade de retry automático de dados históricos em conexões Open Finance foi reativada, garantindo maior completude nos dados retornados para itens recém-conectados.
- → **EnrichmentAPI: erros de autenticação corrigidos** — Corrigidos erros que ocorriam ao consultar a Enrichment API com determinadas combinações de credenciais.
- → **Widget de Pagamentos: lista de instituições PJ corrigida** — Corrigido um problema em que, ao iniciar um pagamento como pessoa jurídica, a lista de instituições exibida era de instituições PF.
- → **Banrisul: seleção de empresa e histórico de transações** — Corrigida a seleção incorreta de empresa no conector Banrisul e o retorno de transações no modo de sincronização histórica.
- → **Bradesco PF e Bradesco PJ: conectividade restaurada** — Resolvidas instabilidades que impediam usuários de conectar e atualizar contas Bradesco PF e Bradesco PJ.
- → **Itaú PJ: erros de conexão resolvidos** — Corrigidos erros intermitentes que impediam a atualização automática de contas Itaú PJ.
- → **XP: código SUSEP ausente em produtos de investimento** — Corrigida a ausência do código SUSEP no retorno de produtos de investimento do conector XP, afetando a classificação regulatória de ativos.
- → **Widget: botões de ação não exibidos corretamente** — Corrigido um problema de renderização em que os botões de ação desapareciam em determinadas telas do Connect Widget.
- → **Dados de transações corrigidos para múltiplas instituições** — Corrigidos problemas de retorno de transações de conta corrente, cartão de crédito e investimentos para as seguintes instituições: Bradesco, Santander, Itaú, Banco do Brasil, Nubank, BTG Pactual, Sicredi, Sicoob, Caixa Econômica Federal, Caixa Tem, Banrisul, XP Banking, InfinityPay, Inter e C6.
***
## 📚 Documentação
- → **SDK Node.js: cursor pagination completo** — O SDK Node.js foi atualizado com os campos de cursor que estavam ausentes, habilitando uso completo da cursor pagination em listagens de transações.
- → **SDK Java: suporte a cursor pagination** — O SDK Java foi atualizado para suportar cursor pagination, alinhando-o às capacidades atuais da API.
- → **Quickstart e dependências atualizados** — O guia de quickstart foi revisado com melhorias de conteúdo e as dependências do pluggy-sdk foram atualizadas para as versões mais recentes.
## Atualizações de Produto | Março/2026
Source: https://docs.pluggy.ai/pt/changelog#2026.03
## Confira as principais novidades e melhorias da Pluggy em março de 2026.
**Destaques de março**
* Expansão significativa das funcionalidades de pagamentos, com nova seção completa no dashboard e evolução da API.
* Avanços em Pix Automático e Smart Transfers, com melhorias de gestão, eventos e consistência dos fluxos.
* Atualizações e maior estabilidade em conectores, incluindo BB Prev e CaixaPrev.
* Evolução do dashboard com novo onboarding, analytics mais completos e melhorias na visualização de dados.
* Diversas correções e melhorias de estabilidade em sincronização, webhooks e qualidade dos dados.
⚠️ Algumas funcionalidades estão sendo liberadas aos poucos e podem variar dependendo da instituição, tipo de integração e ambiente (sandbox ou produção). Se algo não aparecer por aí ainda, é só chamar a gente.
## 💳 Pagamentos
Março trouxe uma expansão significativa das funcionalidades de pagamento, com uma seção completa no dashboard e novos recursos na API.
→ **Seção de Pagamentos no Dashboard **— Agora você pode gerenciar suas solicitações de pagamento diretamente pelo dashboard, com criação, busca, filtros, paginação e visualização detalhada de cada solicitação.
→ **Gestão de Recebedores **— Cadastre, edite e busque recebedores de pagamento por nome ou CPF/CNPJ, tudo pelo dashboard.
→** Gestão de Pagadores** — Cadastre e gerencie seus pagadores (customers) com uma interface dedicada no dashboard.
→ **Gestão de PIX Automático no Dashboard** — Gerencie seus agendamentos de PIX Automático diretamente pelo dashboard: visualize ocorrências, acompanhe o status de cada pagamento e cancele consentimentos ou agendamentos individuais.
→ **Smart Transfers** — Nova seção de Smart Transfers no dashboard para gerenciar transferências inteligentes.
→ **Endpoint /balance** — Novo endpoint para consultar o saldo disponível no iniciador de pagamentos.
→ **Metadados de boleto (Inter PJ)** — Transações de boleto do Inter PJ agora incluem metadados detalhados do pagamento.
→ **Webhook de expiração** — Você agora recebe um webhook quando uma solicitação de pagamento expira automaticamente.
→ **Evento CONSUMED no PIX Automático** — O evento CONSUMED agora é tratado corretamente no fluxo de PIX Automático.
→ **Correção no campo supportsAutomaticPix** — O campo supportsAutomaticPix agora retorna os valores corretos para cada instituição.
→ **Correção de caractere inválido** — Corrigido um problema com caracteres inválidos no nome do pagador em transações PIX Automático.
***
## 📡 Novos Conectores
→ **BB Prev (nova versão)** — O conector BB Prev foi migrado para uma versão mais moderna e estável.
→ **CaixaPrev (atualização)** — O conector CaixaPrev foi revisado e atualizado para maior confiabilidade.
***
## 🚀 Novas Features
→ **Transações pendentes (Open Finance)** — Transações com status "pendente" agora são automaticamente atualizadas para "postada" quando confirmadas pela instituição.
→ **BrasilPrev** — suporte a multifundos — Agora você pode visualizar investimentos separados por fundo no BrasilPrev.
→ **Ordenação alfabética no Widget** — As instituições no Pluggy Connect Widget agora são exibidas em ordem alfabética para facilitar a busca.
→ **Pagamentos no modelo de fatura (Open Finance)** — A lista de pagamentos agora é retornada no modelo de fatura via Open Finance.
→ **Banner de upgrade para v2** — Usuários do dashboard v1 agora veem um banner com convite para migrar para a nova versão.
***
## 🖥️ Dashboard
→ **Novo onboarding** — Experiência de boas-vindas redesenhada com etapas guiadas, convite de colaboradores e animações de entrada.
→ **Due Diligence em tela cheia** — O formulário de Due Diligence agora é um wizard multi-etapas em tela cheia, mais intuitivo e organizado.
→ **Checklist de Produção** — O checklist de prontidão para produção foi redesenhado como um card "Solicitar Acesso à Produção" com verificação automática de saúde da integração.
→ **Overview para Sandbox** — A página de visão geral foi redesenhada para usuários sandbox, com dicas de integração e página de analytics.
→ **Estatísticas do Syncer** — Novas métricas de sincronização com gráfico de retentativas, KPI de itens atualizáveis e deduplicação por item.
→ **Filtro por conector** — Agora você pode filtrar as estatísticas de sincronização por conector específico.
→ **Gráfico de itens por instituição** — Novo gráfico com visualização em lista ou gráfico e filtro multi-select de conectores.
→ **Lag por conector** — Gráfico de donut mostrando o atraso de atualização por conector, com cores da marca de cada instituição.
→ **Payload de eventos** — Agora você pode visualizar o payload completo de eventos de webhook diretamente no drawer de detalhes.
→ **Convites pendentes** — Nova interface para gerenciar convites de equipe pendentes.
***
## 🔔 Webhooks
→ **Correção de webhooks duplicados** — Webhooks do tipo transactions/created não são mais enviados quando a execução não cria uma transação realmente nova.
***
## 🐛 Correções
→ **Correções de dados em múltiplas instituições** — Corrigidos problemas de transações e contas não retornadas ou duplicadas em: Caixa Econômica Federal, Sicredi, Nubank, Santander, Inter, Banco do Brasil, C6, Banrisul, Mercado Pago, Bradesco, Wise, 99 Pay, Itaú e Sicoob.
→ **Retentativa automática para erros de merge** — Implementado mecanismo de retentativa para erros consistentes de merge, reduzindo falhas de sincronização.
→ **Itaú PJ — credenciais inválidas** — Corrigido erro que retornava uma mensagem genérica ao invés de indicar credenciais inválidas no Itaú PJ.
→ **Exclusão de itens** — A ação de excluir item agora remove corretamente o item via API.
→ **Investimentos Open Finance** — Corrigido problema onde investimentos eram misturados quando novos apareciam em ordem diferente.
→ **Transações Banrisul** — Corrigida a ordenação de transações que eram retornadas em ordem crescente pela instituição.
→ **Remoção do Banco Paulista** — O Banco Paulista foi removido da lista de conectores Open Finance por descontinuação.
***
## 📚 Documentação
→ **Playground atualizado** — O Playground foi atualizado para facilitar o teste de cada tipo de pagamento disponível.
## Atualizações de Produto | Fevereiro 2026
Source: https://docs.pluggy.ai/pt/changelog#2026.02
## Confira as principais novidades e melhorias da Pluggy em fevereiro de 2026.
**Destaques de fevereiro**
* Lançamento do novo Dashboard Pluggy, com ambientes separados, onboarding guiado e gestão de equipe.
* Novas capacidades de Pix recorrente via PixAuto, incluindo agendamento e retentativa automática.
* Expansão de conectores com Conta Bemol PF e Inter PJ para MEI.
* Melhorias em webhooks, incluindo retentativa via dashboard e autenticação personalizada.
* Diversas correções e melhorias de estabilidade em conectores e sincronização de dados.
***
## 🖥️ Novo Dashboard
Lançamos o **novo Dashboard Pluggy**, completamente redesenhado para facilitar a gestão da sua integração.
→ **Ambientes separados** — agora você pode alternar facilmente entre Development e Production direto no menu lateral. Suas aplicações, eventos e filtros se ajustam automaticamente ao ambiente selecionado.
→ **Onboarding guiado para novos usuários** — ao criar sua conta, você será guiado por 4 etapas práticas: gerar seu primeiro connect token, integrar o widget e configurar webhooks — tudo direto no dashboard.
→ **Tour interativo** — um tour passo a passo apresenta as principais áreas do dashboard para você começar a usar rapidamente.
→ **Visão geral completa** — acompanhe suas conexões diárias, status de execuções e distribuição por instituição com gráficos detalhados e filtros por conector e período.
→ **Due Diligence digital** — preencha e envie seu formulário de compliance diretamente pelo dashboard, com upload de documentos e acompanhamento de status.
→ **Personalização do widget** — visualize as alterações de marca em tempo real, faça upload do seu logo com drag-and-drop e veja um indicador visual quando houver alterações pendentes.
→ **Gestão de equipe** — convide colaboradores por email, defina papéis e gerencie convites pendentes.
→ **Retentativa de webhooks em lote** — selecione um intervalo de tempo e reenvie webhooks diretamente pelo dashboard.
→ **Alertas de conectores** — receba avisos automáticos quando conectores utilizados na sua integração estiverem offline ou instáveis.
***
## 💳 Pagamentos / PixAuto
→ **Agendamento de pagamentos Pix** — agora você pode agendar pagamentos Pix recorrentes via PixAuto.
→ **Retentativa automática** — pagamentos Pix que falharem serão retentados automaticamente, sem necessidade de intervenção manual.
→ **Identificação de primeiro pagamento** — a API agora indica quando um pagamento é o primeiro de uma série, facilitando o controle no seu sistema.
→ **Link de pagamento revogado** — links de pagamento são desativados automaticamente quando o consentimento do usuário é revogado, garantindo segurança.
***
## 📡 Novos Conectores
→ **Conta Bemol Física** — conecte contas de pessoa física do Conta Bemol via Open Finance.
→ **Inter PJ para MEI** — microempreendedores individuais agora são atendidos pelo conector regulado do Inter PJ.
***
## 🔔 Webhooks
→ **Headers de autenticação personalizados** — seus webhooks agora recebem os headers de autenticação que você configurar, facilitando a validação no seu servidor.
→ **Retentativa por intervalo de tempo** — reenvie webhooks de um período específico caso tenha perdido algum evento.
→ **Retentativa pelo dashboard** — reenvie webhooks diretamente pela interface, sem precisar usar a API.
→ **Desativação automática de URLs inativas** — URLs de webhook que não recebem eventos há um período prolongado são desativadas automaticamente para evitar chamadas desnecessárias.
→ **Limite de webhooks por evento** — agora há um limite configurável de webhooks por tipo de evento para melhor organização.
***
## 🚀 Novas Features
→ **Subtipo de conta (Open Finance)** — o campo `accountSubtype` agora é retornado na resposta da API, oferecendo mais detalhes sobre o tipo de conta conectada.
→ **Filtro por data de criação de transações** — filtre transações pela data em que foram detectadas pela Pluggy, útil para identificar novas transações desde a última sincronização.
→ **Prevenção de conexões duplicadas** — durante a seleção de conta com MFA, contas já conectadas são bloqueadas para evitar duplicidade.
→ **Validação de CNPJ (Bradesco PJ)** — o CNPJ informado no formulário é validado contra a instituição, evitando erros de conexão.
***
## 🐛 Correções
→ **Datas de transações** — corrigidas datas inválidas em transações de cartão de crédito (Caixa) e boletos (Bradesco PJ).
→ **Extrato PDF (Itaú PJ)** — download de extrato em PDF restaurado para contas Itaú PJ.
→ **Conexão Itaú PJ** — resolvido erro de conexão causado por expiração de permissões.
→ **Sincronização histórica** — corrigido loop infinito que podia ocorrer durante a sincronização de dados históricos via Open Finance.
→ **Transações duplicadas** — eliminada duplicação de transações com mesmo identificador em conectores Banrisul e Banco do Brasil.
→ **Entrega de webhooks** — corrigidos cenários em que webhooks de transação atualizada, exclusão de item e criação de conta não eram entregues corretamente (afetava Inter MEI e Santander).
→ **Correções de dados** — ajustes pontuais em transações de diversos conectores: Itaú, Bradesco, Santander, Banrisul, Banco do Brasil, Nubank, Sicredi, Caixa, BTG e Inter.
***
## 📚 Documentação
→ **Documentação para LLMs** — nossa documentação agora está otimizada para uso com modelos de linguagem (IA), facilitando integrações assistidas por IA.
→ **Smart Transfers** — documentação de Smart Transfers atualizada com os novos recursos.
→ **SDKs** atualizado para refletir as últimas funcionalidades da API.
## Atualizações de Produto | Setembro
Source: https://docs.pluggy.ai/pt/changelog#2025.09
> Outubro foi um mês cheio de avanços no ecossistema Pluggy! 🌟
>
> Tivemos melhorias importantes em conectores Open Finance, otimizações de performance e novos recursos que tornam as integrações mais estáveis, precisas e fáceis de usar.
> Entre os destaques estão ajustes em mensagens de aviso de cartões de crédito, correções de lógica em transações e saldos, suporte a deep links no OAuth e novos conectores disponíveis em BETA.
> Abaixo, você confere o resumo das principais atualizações que chegaram para deixar sua integração com a Pluggy ainda mais confiável. 👇
### [OF] Credit Card Warning
→ Avisos de cartão sem consentimento/indisponível sempre visíveis.
→ Mensagem separada por tipo: no consent ou unavailable.
### [Santander OF] Pagination Fix
→ Paginação ajustada: contagem correta mesmo com page-size=100.
→ Limite adaptativo (500 páginas / 200 k transações).
### [OF] Avoid Duplicates
→ Adicionados Nubank PF/PJ à whitelist de bloqueio de duplicidade (CPF/CNPJ).
→ Lista de instituições revisada e documentada.
### [Sandbox] Múltipla Alçada
→ Fluxo funcional no widget; permite teste com múltiplos CPFs.
→ statusDetail indica quando a conta precisa de autorização.
### [OF] Credit Card Future Transactions
→ Corrigido status incorreto de transações futuras.
→ Remove billId se billPostDate > data atual → marca como PENDING.
### [OF] Closing Balance
→ closingBalance = availableBalance + blockedBalance.
→ Agora reflete corretamente o saldo contábil.
### [API] Deep Links OAuth
→ oauthRedirectUri agora aceita deep links.
→ Facilita autenticação e retorno direto em apps mobile.
### [OF] New Connectors (BETA)
→ Dock PF – Accounts, Transactions, Identity
→ QI SCD PF – Accounts, Transactions, Loans, Identity
→ QI SCD PJ – Accounts, Transactions, Loans, Identity
[Veja a versão detalhada aqui.](https://docs.pluggy.ai/changelog/atualiza%C3%A7%C3%B5es-de-produto-detalhada-setembro#/)
## [Atualizações de Produto] Agosto-25
Source: https://docs.pluggy.ai/pt/changelog#2025.08
> A cada mês, evoluímos nossos conectores e SDKs para que você tenha mais confiabilidade, velocidade e precisão nas integrações financeiras. 🚀\
> Em agosto, avançamos em pontos estratégicos como redução de falhas em fluxos de criação, melhoria de performance em dados de pagamento e ajustes que trazem mais consistência aos conectores.
>
> No post de hoje, reunimos os principais destaques para você acompanhar de forma prática o que mudou e como essas melhorias impactam o seu dia a dia. Ao final, disponibilizamos um link com uma versão mais detalhada das mudanças.
### **🔄 EfiPay**
Contas retornadas já na criação do item (via PIX API).\
→ Precisa atualizar credenciais para novos escopos de token.\
📘 [Confira o passo a passo atualizado na documentação do EfiBank Empresas.](https://docs.pluggy.ai/docs/tutorial-efibank-empresas)
***
### **⚙️ Open Finance – Sicoob**
Retry automático no endpoint resources (status 202/503).\
→ Retenta até 5 min, reduz falhas na criação de item.\
📘[ Mais detalhes podem ser encontrados na documentação atualizada sobre o fluxo de sincronização.](https://docs.pluggy.ai/docs/item-lifecycle#synchronization-flow)
***
### **🛠️ Open Finance – Conectores**
Campo products agora reflete apenas recursos suportados (Investments, Loans, Credit Cards, Accounts, Identity).\
→ Evita confusão e tentativas de uso em features não suportadas.
***
### **🕒 Open Finance – Histórico**
Retry automático em syncs históricos que retornam vazio.\
→ Nova execução diária (até 1 ano), até dados completos serem recuperados.
***
### **🆔 Open Finance – Identity**
Filtro em financialRelationships.accounts → só contas com consentimento.\
→ Campo additionalInfo mapeado em endereço (ex.: ap/compl).\
📘 Mais detalhes disponíveis na [documentação de referência](https://docs.pluggy.ai/reference/identity-retrieve) e no [guia de identidades](https://docs.pluggy.ai/docs/identities).
***
### **📉 Rico**
Removidos fluxos de ACCOUNTS e TRANSACTIONS.\
→ Mantidos Identity e Investments (incl. Investment Transactions).\
[📘 Mais detalhes disponíveis na documentação de cobertura de conectores.](https://docs.pluggy.ai/docs/connectors-coverage)
***
### **💳 Bradesco PJ**
Melhorias em dados de pagamento:\
Boletos/PIX enviados: recuperação 10x mais rápida + match mais preciso.\
Correção do limite de 10K transações.
Quer ver uma versão mais detalhada do product updates, entendendo o que mudou e a importância das mudanças? [Acesse aqui.](https://docs.pluggy.ai/changelog/atualiza%C3%A7%C3%B5es-de-produto-detalhada-agosto-25)
## [Atualizações de Produto] Julho-25
Source: https://docs.pluggy.ai/pt/changelog#2025.07
Fique por dentro das novidades da Pluggy no mês de Julho!
# 📡 Novos Conectores Open Finance
### 🌟 Itaú Emps
* As instituições listadas abaixo já estão disponíveis, porém os conectores estão em BETA, o que significa que podem apresentar instabilidades e erros.
### 🌟 99PAY INSTITUICAO DE PAGAMENTO S.A.
### 🌟 BANCO C6 S.A.
### 🌟 BANCO CSF S/A
### 🌟 BANCO INTER S.A.
### 🌟 Banco Master S.A.
### 🌟 BANCO MERCANTIL DO BRASIL S.A.
### 🌟 BRB - BANCO DE BRASILIA S.A.
### 🌟 CREFISA S.A.-CREDITO, FINANCIAMENTO E INVESTIMENTOS
### 🌟 MIDWAY S.A. - CREDITO, FINANCIAMENTO E INVESTIMENTO
### 🌟 Pagseguro Internet Instituicao de Pagamento S.A.
**Interessado? Fale com nossa equipe!**
***
# 📡 Novas instituições disponíveis para Pagamentos
#### 🌟 Accredito Empresas
#### 🌟 Agibank Empresas
#### 🌟 Ailos Empresas
#### 🌟 Banco Arbi Empresas
#### 🌟 Banco da Amazônia Empresas
#### 🌟 Banco Genial Empresas
#### 🌟 Banco Guanabara Empresas
#### 🌟 Banco Ribeirão Preto
#### 🌟 Banco Ribeirão Preto Empresas
#### 🌟 Banco Semear Empresas
#### 🌟 Banese Empresas
#### 🌟 Banestes Empresas
#### 🌟 Bankly
#### 🌟 Bankly Empresas
#### 🌟 Banpará
#### 🌟 Banpará Empresas
#### 🌟 banQi
#### 🌟 Blu
#### 🌟 Brasil Card
#### 🌟 Brasil Card Empresas
#### 🌟 Cartos SCD
#### 🌟 Caruana SCF
#### 🌟 Caruana SCF Empresas
#### 🌟 Conta Bemol
#### 🌟 Conta Bemol Empresas
#### 🌟 Crefisa Empresas
#### 🌟 Cresol Empresas
#### 🌟 dLocal Empresas
#### 🌟 EBANX Empresas
#### 🌟 Efí Empresas
#### 🌟 FitBank Empresas
#### 🌟 Iugu Empresas
#### 🌟 Listo Empresas
#### 🌟 MoneyPlus
#### 🌟 MoneyPlus Empresas
#### 🌟 Parati
#### 🌟 Parati Empresas
#### 🌟 QI SCD Empresas
#### 🌟 Sefer Investimentos
#### 🌟 Sefer Investimentos Empresas
#### 🌟 Shopee
#### 🌟 Sisprime
#### 🌟 Sisprime Empresas
#### 🌟 SumUp Empresas
#### 🌟 Tribanco
#### 🌟 Tribanco Empresas
#### 🌟 U4C Empresas
#### 🌟 Uniprime Central Empresas
#### 🌟 Up.p
#### 🌟 Up.p Empresas
#### 🌟 WHG
#### 🌟 Will Bank
#### 🌟 Z1 Instituição de Pagamento
#### 🌟 J17 Bank Empresas
#### 🌟 Mercado Bitcoin
***
# ✨ Melhorias
## 🎲 Dados
### Melhorias no objeto paymentData
* Fizemos diversas melhorias no retorno de dados do objeto paymentData nos conectores Sicredi PJ, Bradesco PJ e Itaú PJ. Para mais detalhes, acesse nossa [documentação](https://docs.pluggy.ai/docs/transactions#transaction-payment-data-schema).
### Adicionamos o campo balance nas transações do Banco do Brasil PJ
* Agora, o conector BB PJ retorna o saldo atualizado nas transações de conta corrente (campo \_balance). Para mais detalhes, acesse nossa [documentação](https://docs.pluggy.ai/docs/transactions#end-of-day-balance).
### Melhorias no retorno de dados de previdência para BTG e XP
* Os conectores diretos BTG e XP agora estão retornando dados mais completos de previdência.
### Descontinuação de conectores
* O conector **ITI** (Open Finance, id 638) está sendo descontinuado pela instituição Itaú, logo, ele será deslistado de nossa solução a partir do dia 13/08.
* O conector **Rico** (Pluggy, id 205) está sendo descontinuado por conta de novas atualizações de segurança. Esse conector será deslistado de nossa solução a partir do dia 12/08. Essa instituição seguirá ativa apenas com o conector Open Finance (id 605)
\_Dúvidas? \_Fale com nossa equipe!\_\_
***
## [Atualizações de Produto] Junho-25
Source: https://docs.pluggy.ai/pt/changelog#2025.06
Fique por dentro das novidades da Pluggy no mês de Junho!
# 📡 Novos Conectores Open Finance
### 🌟 Incluímos 4 novos conectores regulados:
* Santander Corretora (812)
* Santander Corretora Empresas (813)
* PagueVeloz (Serasa) (814)
* PagueVeloz (Serasa) Empresas (815)
**Interessado? Fale com nossa equipe!**
***
# 🚀 Novas Features
## 🎲 Dados:
### Dados de comprovante (boleto pago)
Agora, é possível visualizar dados de comprovante de boleto pago em mais uma instituição:
* Santander PJ
Ao todo, retornamos dados de comprovante de pagamento de boleto (multa, juros e descontos) nas seguintes instituições:
* Santander PJ
* Itaú PJ
* Bradesco PJ
* Inter PJ
* Sicredi PJ
Mais detalhes em nossa [documentação](https://docs.pluggy.ai/docs/transactions#boleto-metadata)
***
## 💳 Pagamentos
### PIX Automático
Está disponível o produto de pix automático! Todas as informações para sua utilização estão em nossa documentação ([aqui](https://docs.pluggy.ai/docs/pix-automatico) e [aqui](https://docs.pluggy.ai/reference/payment-request-create-automatic-pix)).
Converse com nosso time de vendas e venha testar esse produto!
***
# ✨ Melhorias
## 🎲 Dados
### Descontinuação de conectores diretos (não-regulados)
* O conector **B3 CEI** está sendo descontinuado devido a medidas de segurança implementadas pela instituição.
* Este conector **não está disponível** no Open Finance regulado, dessa forma, não teremos mais acesso a conexões da plataforma B3 CEI.
### XP Investimentos
* Realizamos diversas melhorias neste conector, visnaod maior estabilidade e redução de inconsistências nos dados coletados
### SDK React Native
* Atualizamos nossa SDK de React Native para incluir parâmetros de Open Finance faltantes.
\_Dúvidas? \_Fale com nossa equipe!\_\_
***
## 💳 Pagamentos
### Diversas melhorias no produto Pix Automático:
* Inclusão de campo para que seja possível vincular um pagamento a um usuário (clientPaymentId)
* Possibilidade de cancelar um pagamento agendado específico ([documentação](https://docs.pluggy.ai/reference/cancel-automatic-pix-schedule))
* Possibilidade de cancelar uma autorização de pagamento realizada com sucesso ([documentação](https://docs.pluggy.ai/reference/payment-request-cancel-automatic-pix-consent))
* Melhorias em nosso app de pagamento para contemplar o fluxo de pix automático
* Inclusão de novos [webhooks](https://docs.pluggy.ai/docs/webhooks) para pix automático
***
# 📈 Bugs
### 🎲 Dados
* Portabilidade de Previdência:
* Corrigimos alguns bugs que estavam causando inconsistência na coleta de dados para o produto de portabilidade de previdência nos conectores XP e BTG.
* Dados de Empréstimo (OF):
* Corrigimos um defeito que estava causando um falso positivo nos dados de empréstimo.
## [Atualizações de Produto] Maio-25
Source: https://docs.pluggy.ai/pt/changelog#2025.05
Fique por dentro das novidades da Pluggy no mês de Maio!
# 📡 Novos Conectores Open Finance
### 🌟 Rede Celcoin (PF & PJ)
**Interessado? Fale com nossa equipe!**
***
# 🚀 Novas Features
## 🎲 Dados:
### Dados de comprovante (boleto pago)
Agora, é possível visualizar dados de comprovante de boleto pago em mais uma instituição:
* Sicredi PJ
Ao todo, retornamos dados de comprovante de pagamento de boleto (multa, juros e descontos) nas seguintes instituições:
* Itaú PJ
* Bradesco PJ
* Inter PJ
* Sicredi PJ
Mais detalhes em nossa [documentação](https://docs.pluggy.ai/docs/transactions#boleto-metadata)
***
### Gestão de webhooks via Dashboard Pluggy
Implementamos no Dashboard uma modificação que permite ao usuário ver **detalhes avançados** de um evento de webhook (como **status** e o **detalhe do erro**, em caso de falha), além da opção de **reenvio**.\
Abaixo, uma breve demonstração da nova feature:
***
## 💳 Pagamentos
### Novo campo: identificador do pagamento na instituição
Implementamos um novo campo para com o id do pagamento na instituição: `endToEndId`.
Esse campo será retornado na response de pagamentos agendados **concluídos** e também no evento de webhook `scheduled_payment/completed`, conforme exemplo\
`{
"paymentRequestId": "a0ed730e-5a44-491f-9a32-aa295c399fdf",
"event": "scheduled_payment/completed",
"eventId": "1d5d1aab-fc1a-40d4-aeae-15e7b9c11a10",
"endToEndId":"E44471172202505211500U0d9ffa12345",
"scheduledPaymentId": "65c6f9cd-e69f-46cd-8103-80b42dd61bfd"
}`
***
# ✨ Melhorias
## 🎲 Dados
### Descontinuação de conectores diretos (não-regulados)
* O conector **Genial Investimentos** está sendo descontinuado devido a medidas de segurança implementadas pela instituição.
* Este conector **não está disponível** no Open Finance regulado, dessa forma, não teremos mais acesso a conexões da instituição Genial até que se tornem participantes do Open Finance.
* O conector **Sicoob (PF & PJ)** está sendo descontinuado devido a medidas de segurança implementadas pela instituição.
* Este conector **está disponível** no Open Finance regulado, logo, para continuar tendo acesso ao compartilhamento de dados nessa instituição, será necessária uma migração para o conector regulado.
\_Dúvidas? \_Fale com nossa equipe!\_\_
***
## 💳 Pagamentos
### Novos filtros para pagamentos
Agora é possível realizar buscas mais refinadas utilizando múltiplos filtros e filtros simples para os endpoints de **Recipients, Customers e Requests**.
* Endpoint *Payment Recipient*\
Novos filtros disponíveis:
* `pixKey`
* `name`
📚 [Documentação](https://docs.pluggy.ai/reference/payment-recipients-list)
* Endpoint *Payment Customers*:\
Novos filtros disponíveis
* `name`
* `email`
* `cpf`
* `cnpj`
📚 [Documentação](https://docs.pluggy.ai/reference/payment-customers-list)
* Endpoint *Payment Request*:\
Novos filtros disponíveis
* `from` e `to`: intervalo de datas baseado no campo `createdAt`
* `customer`
* `pixKey`
📚 [Documentação](https://docs.pluggy.ai/reference/payment-requests-list)
### ⚠️ Importante:
* Os filtros aceitam **buscas parciais** e sem **diferenciação de maiúsculas/minúsculas**, usando a cláusula `ILIKE`, ou seja, uma busca por `john` retornará tanto `John Doe` quanto `john smith`;
* Os filtros podem ser combinados em uma única requisição para refinar os resultados.
***
# 📈 Bugs
### 🎲 Dados
* Itaú PJ: foram implementadas melhorias para:
* estabilização do conector;
* transações de cartão de crédito.
* Santander PJ: foram implementadas melhorias para:
* estabilização do conector;
* erros com data da transação.
* Bradesco PJ: corrigida lentidão para atualização de contas.
## [Atualizações de Produto] Abril-25
Source: https://docs.pluggy.ai/pt/changelog#2025.04
Fique por dentro das novidades da Pluggy no mês de Abril!
# 🚀 Features
### Dados de comprovante (boleto pago)
Agora, é possível visualizar dados de comprovante de boleto pago em mais uma instituição:
* Inter PJ
Ao todo, retornamos dados de comprovante de pagamento de boleto (multa, juros e descontos) nas seguintes instituições:
* Itaú PJ
* Bradesco PJ
* Inter PJ
Mais detalhes em nossa [documentação](https://docs.pluggy.ai/docs/transactions#boleto-metadata)
***
# ✨ Melhorias
### 🎲 Dados
* Atualizamos em nossa Widget as instruções para conexão com Inter PF:
* Itaú PJ: melhoria na performance do conector, o que representa uma redução de 15% no tempo de conexão.
* Clear Investimentos: Devido a diversas instabilidades que inviabilizaram o uso, tivemos que encerrar o suporte ao conector Clear não regulado.
* O conector continua disponível no acesso **regulado**;
* Mais informações sobre os conectores disponíveis, acesse nossa documentação:
* [conectores "regulado"](https://docs.pluggy.ai/docs/open-finance-regulated#institutions-supported-by-open-finance)
* [conetores "não regulado"](https://docs.pluggy.ai/docs/connectors-coverage)
### 💳 Pagamentos
* Adicionamos novas instituições para fluxos de pagamento:
* Dock
* 99pay
* Swap
* Azimut
* BMS Sociedade de Crédito Direto S/A
* ModalMais trader
* Listo
* Iugu
***
# 📈 Bugs
### 🎲 Dados
* Itaú PJ: foram resolvidos problemas referentes a:
* transações sem *payment data* e;
* conexões que não estavam sendo atualizadas diariamente.
* Bradesco PJ: corrigimos alguns erros no fluxo de recaptcha que estavam impactando as atualizações automáticas neste conector.
### 💳 Pagamentos
* Resolvemos um bug o qual inviabilizava o cancelamento de agendamentos futuros.
## [Atualizações de Produto] Março-25
Source: https://docs.pluggy.ai/pt/changelog#2025.03
Fique por dentro das novidades da Pluggy no mês de Março!
# 📡 **Novos Conectores Open Finance**
### 🌟 EQI Investimentos
**Interessado? Fale com nossa equipe!**
***
# ✨ Melhorias
### 🎲 Dados
* Ajustes visando a estabilização do conector Sicoob PJ
### 💳 Pagamentos
* Adicionamos informações de *juros* e *multa* em nossa api de emissão de boletos (feature disponível apenas para Inter PJ. Mais detalhes em nossa [documentação](https://docs.pluggy.ai/docs/boleto-management-api).
* Maior clareza dos erros retornados em nossa API de pagamentos.
* Melhorias diversas em nossa [documentação](https://docs.pluggy.ai/docs/payments-overview-1) de pagamentos.
* Por questões regulatórias, agora os dados de conta do recebedor não serão mais exibidos por completo. Essa alteração ocorre no objeto accounts do endpoint `/recipient`, o qual terá os dados exibidos com máscara.
* Dados a serem mascarados:
* agência,
* número da conta,
* tipo da conta,
* cpf completo,
* data de abertura da conta.
* Exemplo de como será retornada essa informação mascarada:
* `"account": {
"type": "****"
"number": "******112",
"branch": "**1"
}`
***
# 📈 Bugs
### 🎲 Dados
* Resolvemos casos de transações deletadas em Itaú PF, Itaú PJ, Bradesco PJ.
* Resolvemos diversos casos de investimentos não retornados na XP.
* Consertamos um erro do Open Finance onde algumas transações de cartão de crédito estavam consolidadas, porém sem vínculo com nenhuma fatura.
## [Atualizações de Produto] Fevereiro-25
Source: https://docs.pluggy.ai/pt/changelog#2025.02
# 🚀 Features
### Novos webhooks para gestão das transações:
* `transactions/created`: serão enviadas notificações sempre que novas transações forem coletadas na conta;
* `transactions/updated`: serão enviadas notificações sempre que houver mudanças nas transações existentes (descrição, valor etc). Serão informados os IDs de cada transação alterada;
* `transactions/deleted`: serão enviadas notificações sempre a instituição remover alguma transação. Serão informados os IDs de cada transação deletada.
Para maiores detalhes, acesse nossa documentação: 🔗 [Guia de Sincronização de Transações](https://docs.pluggy.ai/docs/transactions#how-to-synchronize-and-merge-transactions).
***
### Novidade sobre dados de pagamento de boletos!
* Agora, os conectores Itaú PJ e Bradesco PJ retornam dados referentes a comprovante de pagamento de boletos.
* Isso significa que, em transações relacionadas a boletos, retornaremos informações no objeto `boletoMetadata` como:
* Código de barras;
* Linha digitável do boleto;
* Status do boleto (pago, pendente, etc.);
* Dados de multas, juros, descontos etc.
Para maiores detalhes, acesse nossa documentação: 🔗 [dados de pagamento de boletos](https://docs.pluggy.ai/docs/transactions#transaction-payment-data-schema)
***
### Emissão de boletos (Inter PJ)!
* Temos uma nova API para emissão de boletos!
* Atualmente, está apenas disponível para Inter PJ.
Para maiores detalhes, acesse nossa documentação: 🔗 [API de emissão de boletos](https://docs.pluggy.ai/docs/boleto-management-api)
***
# ✨ Melhorias
* Agora, recuperamos as **transações** referentes a *Aplicação e Resgate Automáticos* no **Itaú PJ**;
* Aumentamos o tempo para realização do consentimento nas conexões Open Finance para 20 minutos;
* Adicionamos a mensagem de erro recebida do provedor nos eventos de webhooks do tipo *erro (item/error)* ;
* Implementamos um novo endpoint para reembolsos automáticos nos casos em que o dinheiro fica na smart account.
***
# 📈 Bugs
* Correções diversas na **API de Pagamentos**, visando maior estabilidade e visibilidade em cenários de erro;
* Resolvidos problemas com **Bradesco PF e XP Investimentos (não regulado)** que impactavam as conexões e atualizações de contas;
## [Atualizações de Produto] Janeiro-25
Source: https://docs.pluggy.ai/pt/changelog#2025.01
Fique por dentro das novidades da Pluggy no mês de Janeiro!
# 📡 **Novos Conectores Open Finance**
#### 🌟 Next Empresas
**Interessado? Fale com nossa equipe!**
***
# 🚀 Features
### Novo Webhook
Para melhorar a forma como nossos clientes sincronizam transações que são criadas, atualizadas ou excluídas na Pluggy, disponibilizamos um novo webhook chamado `transactions/created`.
Esse webhook permite que vocês se inscrevam em cada operação, facilitando a sincronização precisa e eficiente dos dados com seus data sources.
Para mais informações, acesse nossa documentação:\
🔗 [Guia de Sincronização de Transações](https://docs.pluggy.ai/docs/transactions#how-to-synchronize-and-merge-transactions).
***
## ✨ Melhorias
* O campo `email` na criação do `payment customer` agora é **opcional**. Para mais informações, acesse nossa [documentação](https://docs.pluggy.ai/reference/payment-customer).
***
## 📈 Bugs
***
Fique de olho nas próximas atualizações! Continuamos a evoluir nossa plataforma Open Finance para você. Seu feedback é sempre bem-vindo!
Se você ainda não testou o **[Meu Pluggy](https://meu.pluggy.ai/)**, aproveite e confira agora!
## [Atualizações de Produto] Dezembro-24
Source: https://docs.pluggy.ai/pt/changelog#2024.12
Fique por dentro das novidades da Pluggy no mês de Dezembro!
# 📡 **Novos Conectores**
### 🌟 Conector Open Finance: Neon
Adicionamos mais uma instituição à nossa lista de conexões Open Finance! Neon é um conector PF e retorna dados de conta, cartão de crédito, transações, investimentos e dados cadastrais. É possível a realização de *atualizações diárias*.
**Interessado? Fale com nossa equipe!**
### 🌟 Conector Open Finance: Player's Bank
Adicionamos mais uma instituição à nossa lista de conexões Open Finance! Player's Bank é um conector PF e retorna dados de conta, cartão de crédito, transações e dados cadastrais. É possível a realização de *atualizações diárias*.
**Interessado? Fale com nossa equipe!**
***
## 🚀 Features
O widget **Pluggy Connect** agora aceita CPF e CNPJ (`openFinanceParameters`) para evitar que o usuário precise preenchê-los manualmente quando o cliente já tiver essas informações armazenadas. Dessa forma, o usuário pode pular esses campos, reduzindo drasticamente o tempo necessário para conectar instituições de OF e melhorando a experiência geral.
[Ler mais](https://docs.pluggy.ai/docs/environments-and-configurations#available-configurations)
## ✨ Melhorias
* Aumentamos o escopo do status de resgate total (`TOTAL_WITHDRAWAL`) em nossos conectores de investimento do **XP Wealth**..
* Novos [cenários de erro](https://docs.pluggy.ai/docs/payment-intent-statuses) foram incluídos nas validações de pagamentos, visando maior segurança e melhor experiência.
* Criamos uma nova conexão com o Bradesco PJ que permite uma conexão com muito mais estabilidade.
* Ampliamos o escopo de paymentData para transações SISPAG no conector Itaú PJ.
* Conheça as novas seções em nossa documentação:
* [Payment data OF coverage](https://docs.pluggy.ai/docs/payment-data-open-finance-coverage)
* [Investments OF coverage](https://docs.pluggy.ai/docs/investments-open-finance-coverage)
* [Recurring payment analysis API guide](https://docs.pluggy.ai/docs/recurring-payments-1)
## 📈 Otimizações
* Realizamos melhorias para os conectores Open Finance no fluxo mobile.
* A comunicação das conexões OF que têm pendente a autorização para compartilhar dados de cartão de crédito foi aprimorada, adicionando avisos (warnings) quando necessário.
**Dúvidas? Fale com nossa equipe!**
***
Fique de olho nas próximas atualizações! Continuamos a evoluir nossa plataforma Open Finance para você. Seu feedback é sempre bem-vindo!
Se você ainda não testou o **[Meu Pluggy](https://meu.pluggy.ai/)**, aproveite e confira agora!
## [Atualizações de Produto] Novembro-24
Source: https://docs.pluggy.ai/pt/changelog#2024.11
Fique por dentro das novidades da Pluggy no mês de Novembro!
# 🧩 Novas features
### 🌟 Categorizador: dados de pagamentos recorrentes
Estamos lançando uma nova feature em nosso categorizador: agora é possível obter dados de pagamentos recorrentes a partir de análise das transações do usuário. Abaixo, segue exemplo de como esses dados são exibidos. Acesse os detalhes em nossa [documentação](https://docs.pluggy.ai/reference/recurring-payments)!
```Text json
{
"recurringPayments": [
{
"description": "debito aut conta agua e esgoto sabesp",
"averageAmount": -76.78,
"occurrences": [
"77777777-8888-9999-0000-111111111111",
"88888888-9999-0000-1111-222222222222",
"99999999-0000-1111-2222-333333333333"
],
"regularityScore": 0.997773784382727
},
{
"description": "ebn spotify",
"averageAmount": 21.9,
"occurrences": [
"aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"bbbbbbb1-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"ccccccc1-cccc-cccc-cccc-cccccccccccc"
],
"regularityScore": 0.9344445222642911
}
]
}
```
**Interessado? Fale com nossa equipe!**
### 🌟 Categorizador: crie suas próprias regras de categorização
Estamos lançando uma nova feature em nosso categorizador: agora é possível criar regras para uma categorização mais assertiva a partir do parâmetro `matchType`. Você pode definir que regras incidam em trechos da descrição das transações, dentre outras opções. Acesse os detalhes em nossa [documentação](https://docs.pluggy.ai/reference/client-category-rules-create)!
**Interessado? Fale com nossa equipe!**
### 🌟 Evite conexões duplicadas
Através dessa nova feature, fornecemos uma configuração no momento de criação da conta para validar se a mesma já está conectada em nossa base. Acesse os detalhes em nossa [documentação](https://docs.pluggy.ai/docs/item#avoiding-duplicates).
**Interessado? Fale com nossa equipe!**
***
# 📡 **Novos Conectores**
### 🌟 Conector Open Finance: Porto Bank
Adicionamos mais uma instituição à nossa lista de conexões Open Finance! Porto Bank é um conector PF e retorna dados de conta, cartão de crédito, transações, investimentos e dados cadastrais. É possível a realização de *atualizações diárias*.
**Interessado? Fale com nossa equipe!**
***
## 📈 Melhorias e Otimizações
* Conector Pluggy Itau PJ: foram realizadas melhorias na performance e estabilidade desse conector\
**Dúvidas? Fale com nossa equipe!**
***
Fique de olho nas próximas atualizações! Continuamos a evoluir nossa plataforma Open Finance para você. Seu feedback é sempre bem-vindo!
Se você ainda não testou o **[Meu Pluggy](https://meu.pluggy.ai/)**, aproveite e confira agora!
## [Atualizações de Produto] Outubro-24
Source: https://docs.pluggy.ai/pt/changelog#2024.10
# 🧩 Novas features
### 🌟 Dados de comprovante (boleto pago)
Agora, como parte de nosso *payment data*, retornamos dados de comprovante de pagamento de boleto, como multa, juros e descontos. Mais detalhes em nossa [documentação](https://docs.pluggy.ai/docs/transactions#transaction-payment-data-schema).
```Text json
{
"barcode": null,
"baseAmount": 10,
"discountAmount": 0,
"digitableLine": "0001112039230790051356783",
"interestAmount": 2,
"penaltyAmount": null
}
```
**Interessado? Fale com nossa equipe!**
***
### 🌟 Categorizador: análise de comportamento do usuário
Estamos lançando uma nova feature em nosso categorizador: a partir de uma conexão você consegue obter informações sobre padrões de gastos e investimentos dos seus usuários, como no exemplo abaixo:
```Text json
{
"behaviors": {
"hasCar": true,
"homeowner": false,
"frequentTraveler": false,
"highDiningExpenditure": false,
"investmentActivity": true,
"educationExpenses": false,
"healthcareNeeds": true,
"loanCommitments": false,
"insurancePolicies": true
},
"metrics": {
"transportation": {
"spending": 6862.91,
"transactionCount": 15
},
"travel": {
"spending": 1690.57,
"transactionCount": 4
},
...
}
}
```
**Interessado? Fale com nossa equipe!**
***
# 📡 **Novos Conectores**
### 🌟 Conector Pluggy: Mercado Bitcoin!
Disponibilizamos conexão com a corretora de criptmoedas Mercado Bitcoin! Esse é um conector Pluggy e retornamos dados de conta, investimentos e transações de investimentos. Nele, é possível a realização de atualizações diárias.
**Interessado? Fale com nossa equipe!**
***
### 🌟 Conector Pluggy: Conta Simples!
Disponibilizamos conexão com a plataforma digital Conta Simples! Esse é um conector Pluggy e retornamos dados de conta e transações. Nele, **não** é possível a realização de atualizações diárias.
**Interessado? Fale com nossa equipe!**
***
### 🌟 Conectores Open Finance!
Seguimos incluindo instituições à nossa lista de conexões Open Finance! Veja abaixo quais instituições incluímos nesse mês de Outubro e quais dados são retornados. Lembrando que, para as conexões Open Finance, é possível a realização de *atualizações diárias*.
#### Itaú BBA
* Retornado dados de contas, cartões, investimentos e dados cadastrais
#### Monte Bravo
* Retornado dados de contas, cartões, investimentos e dados cadastrais
#### Toro Investimentos
* Retornado dados de investimentos e dados cadastrais
#### Toro Investimentos Empresas
* Retornado dados de investimentos e dados cadastrais
#### Santander Cartões
* Retornado dados de cartão de crédito e dados cadastrais
#### Santander Cartões Empresas
* Retornado dados de cartão de crédito e dados cadastrais
**Interessado? Fale com nossa equipe!**
***
## 📈 Melhorias e Otimizações
* **Incluímos todos os tipos de transação nas conexões Open Finance**\
Passamos a retonar todos os tipos de transação disponíveis nas conexões Open Finance. Mais detalhes em nossa [documentação](https://docs.pluggy.ai/docs/transactions) (campo operationType).
* **Melhoramos a UX no fluxo de conexão Open Finance**\
Reduzimos cliques desnecessários para melhorar a experiência do usuário!
* **Melhoramos a UX no produto Pagamentos Agendados**\
Novo fluxo com telas mais intuitivas e melhor experiência. Venha testar!
**Interessado? Fale com nossa equipe!**
***
Fique de olho nas próximas atualizações! Continuamos a evoluir nossa plataforma Open Finance para você. Seu feedback é sempre bem-vindo!
Se você ainda não testou o **[Meu Pluggy](https://meu.pluggy.ai/)**, aproveite e confira agora!
## Q3 (Jun-Sep) 2024
Source: https://docs.pluggy.ai/pt/changelog#2024.Q3
🚀 **Destaques da Atualização:**
### 🌟 Transferências Inteligentes Agora Disponíveis!
Agora você pode mover dinheiro entre contas bancárias de um mesmo usuário (com o mesmo CNPJ), permitindo casos de uso incríveis como cobertura de cheque especial ou a transferência de fundos para a conta bancária de seus usuários no seu BAAS.
**Interessado neste produto? Fale com nossa equipe!**
### 💡 Melhorias na Categorização
Trabalhamos intensamente para alcançar uma precisão de 99.9% na categorização de transações. Isso significa que suas transações agora são mais precisas do que nunca, proporcionando uma experiência ainda mais eficiente.
#### 🏷️ Melhorias na Extração de Merchants
Agora, todas as transações com CNPJ fornecido são reconhecidas de maneira mais precisa, aprimorando a extração de comerciantes em nossas soluções.
### ⚠️ Orama deprecado
A Orama foi adquirida pelo BTG e suas operações passaram a fazer parte da mesma.
As contas da Orama foram migradas para o BTG ou para a Necton (Você deve ter recebido um e-mail com informações a respeito), ambos os conectores estão disponíveis no Pluggy para conectar através de nossos conectores diretos ou regulados. No caso de novas conexões, recomendamos usar diretamente o conector para o qual sua conta foi migrada.
Para o caso de conexões já existentes da Orama, há algumas que ainda podem ser mantidas ativas, e são aquelas que foram criadas utilizando o **CPF** como **usuário** e que foram migradas para o **BTG**. As conexões que cumprirem com esses requisitos poderão ser atualizadas.
No caso da conta ter sido migrada para a **Necton** ou ter sido criada utilizando o **e-mail como usuário**, deverá ser criada uma nova conexão na instituição correspondente.
**Dúvidas? Fale com nossa equipe!**
### Novo conector: Banco Rendimento
Criamos um novo conector Pluggy: Banco Rendimento. Esse conector é do tipo "pessoa física" e permite atualização automática. **Dúvidas? Fale com nossa equipe!**
### 🔍 Novos Dados em Identidade
Adicionamos novos dados ao recurso de Identity
**financialRelationships**: Informação que permite às instituições avaliar, caracterizar e classificar o cliente, com o objetivo de entender seu perfil de risco e sua capacidade econômico-financeira.Mais detalhes [aquí](https://docs.pluggy.ai/reference/identity-retrieve) .
***
## 📈 Melhorias e Otimizações
* **Melhorias no OAuth**\
Adicionamos o parâmetro “**oauthRedirectUri**” para redirecionar o usuário na jornada de OAuth, garantindo uma experiência end-to-end., ao utilizar dispositivos móveis, você pode redirecionar o usuário de forma mais fluida. Confira a documentação para mais detalhes: [Guia de Suporte OAuth](https://docs.pluggy.ai/docs/oauth-support-guide).
* **Estabilidade das Transações - Itaú PF**\
O desempenho nas transações do Itaú PF foi aprimorado, garantindo maior estabilidade.
* **Melhorias na Sincronização - Itaú PJ**\
Reduzimos significativamente o atraso na sincronização diária para contas Itaú PJ.
* **Mudanças no fluxo de conexão com a Caixa (PF e PJ)**\
Agora para conectar-se à Caixa (PF e PJ) é necessária a leitura de um código QR. Essa alteração impacta tanto os conectores Pluggy quanto Open Finance regulado.
* **SDK Flutter versão 3.0.0**\
Atualizamos nossa SDK Flutter para a versão 3.0.0. Mais detalhes [aqui](https://pub.dev/packages/flutter_pluggy_connect/changelog)!
***
Fique de olho nas próximas atualizações e melhorias à medida que continuamos a evoluir nossa plataforma Open Finance. Seu feedback é sempre bem-vindo!
Se você ainda não testou o Meu Pluggy, aproveite e confira agora!
## Q2 (Apr-Jun) 2024
Source: https://docs.pluggy.ai/pt/changelog#2024.Q2
# 🚀 INSS - New Data Source Available
We've launched this new connector called "INSS" that is returning new products associated with benefits from the user (Creditos Consignados, Benefit history, Pensions, etc).
Connector is available for tests and we are rapidly adding support for new products as customers require. Stay tuned!
# 🚀 Scheduled Payments!
Now through Payment Initiation, you can schedule PIX to be executed on a Date, Week, Month, or Custom configuration so it can automatically generate the PIX on your user's bank account.
## ✨ Features ✨
### Data
* We have created new Direct connectors:
* **Semear**: recovering accounts, transactions & identity.
* **BB Previdencia**: Recovering Previdencia Investments.
* We are providing the list of `consents` related to an `item`, it can be listed from our [API](https://docs.pluggy.ai/reference/consents-list).
### Payments
* We have added Pix QR & Pix Key as destinations for Bulk Payment & Single Payments.
* Bulk Payments APP has been improved to download payment receipts and can be also recovered through [API](https://docs.pluggy.ai/reference/payment-request-receipt-retrieve).
* Manage SmartAccount management methods to [withdraw pix received](https://docs.pluggy.ai/reference/smart-account-transfer-create) when needed.
## Q1 (Jan-Mar) 2024
Source: https://docs.pluggy.ai/pt/changelog#2024.Q1
# :exclamation: New Product Alert
Batch Payment is available for all customers to review. You can dig into this feature in [this docs](https://docs.pluggy.ai/docs/bulk-payment-step-by-step).
Now you can pay multiple Pix, Boletos, and Taxes on a single transaction to multiple destinations using Pluggy's Smart Accounts.
Smart Accounts are accounts created for businesses to make easy transactions for them.\
This resource is also used for Transactional PIX through Pix QR, allowing customers to confirm the PIX reception as an alternative to PIS (Payment Initiation).
## ✨ Features ✨
* [OAS 3 ](https://api.pluggy.ai/oas3.json) of Pluggy's API it's publicly available for SDKs to be autogenerated.
* We have added Sicoob PF to our pool of Direct connections supporting all types of investments.
* Bank Cora PJ now supports login with account selection.
* XP supports redemption transfers for investments.
* Advisor connectors were created for XP Wealth & BTG Wealth, returning accounts, transactions, investments & investments transactions for all the advisor's customers.
* New connectors have been added for Open Finance Regulado, for the latest list review the [GET /connectors?isOpenFinance=true](https://docs.pluggy.ai/reference/connectors-list)
* Regulado connectors retrieving Fixed Incomes now are enhanced with Investment Data from Pluggy's sources.
## 🛠 Technical Additions
* Open Finance connector now syncs their health status with the Central Bank, providing webhooks of `connector/update` when they are unhealthy.
## :bug: Improvements
* Regulado connectors have received an improved performance boost on the first connections that collect the hole data of the user.
* Many more improvements!
## Dezembro de 2023 (Atualização Mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.12
# 🚀 Test now our Payment Initiation product!
Now you can receive payments from any bank with only one api call!
Payments app
## ✨ New Features ✨
🌟 **Payment Initiation Product Now Available!**
* Explore our new Payment Initiation product. Check out the [documentation](https://docs.pluggy.ai/docs/payment-initiation-introduction) for more details.
### Credit Card Processor Connectors
* We've expanded our offerings to include support for Credit Card Processors connectors!
### Caixa Direct Connectors
* Added support for investment transactions in the Caixa direct connector.
### New Institution Connectors
* **Newly Added:**
* BTG Corporate
* Banco Paulista and Banco Paulista Empresas
* SafraPay and SafraPay Empresas
* Safra Financeira and Safra Financeira Empresas
* Citi Empresas
* Investimentos BB
* Uber Conta by Digio
* Banco do Nordeste do Brasil S.A. (PF & PJ)
* Ágora Investimentos
* Getnet (Credit Card Processor)
### Sandbox
* We have added `user-ok-acquiring` to test our Credit Card Processor data model.
## 🛠 Technical Additions
### Connectors Query Filters
* Added `isOpenFinance` and `supportsPaymentInitiation` flags to our GET `/connectors` endpoint for enhanced filtering.
### Credit Card Metadata Model
* New property added: `cardNumber` to our `creditCardMetadata` model.
### Performance Enhancements
* Improved performance for **Itau PF**.
***
Stay tuned for more updates and enhancements as we continue to evolve and expand our Open Finance platform. Your feedback is always welcome!
BTW, if you didn't test [Meu Pluggy](meu.pluggy.ai) check it out!
My Pluggy App
## December 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.12
# 🚀 Test now our Payment Initiation product!
Now you can receive payments from any bank with only one api call!
Payments app
## ✨ New Features ✨
🌟 **Payment Initiation Product Now Available!**
* Explore our new Payment Initiation product. Check out the [documentation](https://docs.pluggy.ai/docs/payment-initiation-introduction) for more details.
### Credit Card Processor Connectors
* We've expanded our offerings to include support for Credit Card Processors connectors!
### Caixa Direct Connectors
* Added support for investment transactions in the Caixa direct connector.
### New Institution Connectors
* **Newly Added:**
* BTG Corporate
* Banco Paulista and Banco Paulista Empresas
* SafraPay and SafraPay Empresas
* Safra Financeira and Safra Financeira Empresas
* Citi Empresas
* Investimentos BB
* Uber Conta by Digio
* Banco do Nordeste do Brasil S.A. (PF & PJ)
* Ágora Investimentos
* Getnet (Credit Card Processor)
### Sandbox
* We have added `user-ok-acquiring` to test our Credit Card Processor data model.
## 🛠 Technical Additions
### Connectors Query Filters
* Added `isOpenFinance` and `supportsPaymentInitiation` flags to our GET `/connectors` endpoint for enhanced filtering.
### Credit Card Metadata Model
* New property added: `cardNumber` to our `creditCardMetadata` model.
### Performance Enhancements
* Improved performance for **Itau PF**.
***
Stay tuned for more updates and enhancements as we continue to evolve and expand our Open Finance platform. Your feedback is always welcome!
BTW, if you didn't test [Meu Pluggy](meu.pluggy.ai) check it out!
My Pluggy App
## Setembro de 2023 (atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.09
### 🚀 **Open Finance Update: Bills, Investments & Identity Now Supported!**
#### Dive into the latest enhancements and additions we brought to you this month.
### ✨ **New Features** ✨
* 🌐 **Open Finance Flow Enhancements**:
* Introduced [Investments](https://docs.pluggy.ai/docs/investments).
* Rolled out [Bills](https://docs.pluggy.ai/docs/credit-card-bills).
* Launched support for [Loans](https://docs.pluggy.ai/docs/loans)
* Implement [Identity](https://docs.pluggy.ai/docs/identities) product.
* 🏦 **Connectors**:
* Enabled Mutual Funds and Fixed Income Investment Transactions for **Bradesco PJ** and **Banco do Brasil PJ**.
* Sold Investments are now marked as `TOTAL_WITHRAWAL` in **Itau PF** and **Inter PF**.
* Added Multiple Accounts support in **Ailos PF**.
* Welcomed **EQI** as our new Connector. Discover its range of supported products [here](https://docs.pluggy.ai/docs/connectors-coverage#investment).
* Added support for investment transactions in **Inter PF**
* Add account selection flow in the **XP Connector**.
* 🛠 **Technical Additions**:
* Enhanced our connector model with `isSandbox` and `isOpenFinance` flags.
* Added pagination for [Investments response](https://docs.pluggy.ai/reference/investments-list) using `page` and `pageSize` query parameters.
### 🛠 **Bug Fixes** 🛠
* Addressed LCA Investments response discrepancies in **Caixa** Connectors.
* Multiple fixes for **Rico Investimentos** product retrieval.
* Rectified Pix QR payment data anomalies in **Bradesco PJ**.
### ℹ️ **Important Notices** ℹ️
* 📢 Integration Update: The **Inter QR** and **Inter PF** connectors have been unified. The consolidated connector is now identifiable with an ID of 215.
## September 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.09
### 🚀 **Open Finance Update: Bills, Investments & Identity Now Supported!**
#### Dive into the latest enhancements and additions we brought to you this month.
### ✨ **New Features** ✨
* 🌐 **Open Finance Flow Enhancements**:
* Introduced [Investments](https://docs.pluggy.ai/docs/investments).
* Rolled out [Bills](https://docs.pluggy.ai/docs/credit-card-bills).
* Launched support for [Loans](https://docs.pluggy.ai/docs/loans)
* Implement [Identity](https://docs.pluggy.ai/docs/identities) product.
* 🏦 **Connectors**:
* Enabled Mutual Funds and Fixed Income Investment Transactions for **Bradesco PJ** and **Banco do Brasil PJ**.
* Sold Investments are now marked as `TOTAL_WITHRAWAL` in **Itau PF** and **Inter PF**.
* Added Multiple Accounts support in **Ailos PF**.
* Welcomed **EQI** as our new Connector. Discover its range of supported products [here](https://docs.pluggy.ai/docs/connectors-coverage#investment).
* Added support for investment transactions in **Inter PF**
* Add account selection flow in the **XP Connector**.
* 🛠 **Technical Additions**:
* Enhanced our connector model with `isSandbox` and `isOpenFinance` flags.
* Added pagination for [Investments response](https://docs.pluggy.ai/reference/investments-list) using `page` and `pageSize` query parameters.
### 🛠 **Bug Fixes** 🛠
* Addressed LCA Investments response discrepancies in **Caixa** Connectors.
* Multiple fixes for **Rico Investimentos** product retrieval.
* Rectified Pix QR payment data anomalies in **Bradesco PJ**.
### ℹ️ **Important Notices** ℹ️
* 📢 Integration Update: The **Inter QR** and **Inter PF** connectors have been unified. The consolidated connector is now identifiable with an ID of 215.
## Agosto 2023 (Atualização Mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.08
Hey! Welcome to the August updates! 🌸
Before we dive into the changelog, there's some news everyone should be aware of.
### 1️⃣ We now support Regulated Open Finance connections! 🎉
##### If you're interested and want to learn more, [check it out here](https://docs.pluggy.ai/docs/open-finance-regulated)!
### 2️⃣ On 01/10, we will deprecate our connector Inter Investimentos (with id 234) and will solely utilize the connector Inter (with id 215).
##### The connector will carry the same data. If you have any questions or need assistance with your integration, please reach out to us!
### ✨ Features
* We've introduced the **Ailos Cartões PJ** connector.
* We've added the **XP - Wealth** connector.
* You can now configure which products to execute within a Pluggy Connection using the Pluggy Connect Widget! Learn more about [Pluggy Connect configuration here](https://docs.pluggy.ai/edit/environments-and-configurations).
* We've added support for Fixed Income transactions made at Itau Corretora in the **Itau PF** connector.
* We've included the last transaction in Sold investments for the **Inter PF** connector.
* We've introduced support for Mutual Funds and Fixed Income in the **Bradesco PJ** connector.
* We've added the **Cora PJ** connector.
* We've added support for payment data regarding Pix QR transactions in Bradesco PJ.
* We've incorporated `status` and `holderType` fields for `Accounts`.
* We've added support for the Acquiring **Stone** connector with some modifications to our data model.
* We now display `TOTAL_WITHDRAWAL` for sold investments in **Itau PF**.
* We've introduced support for CPF access in the **XP** connector.
## ❤️ Improvements
* We've enhanced the UX for QR flow in Pluggy Connect.
* We've addressed login issues with Itau PJ.
## August 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.08
Hey! Welcome to the August updates! 🌸
Before we dive into the changelog, there's some news everyone should be aware of.
### 1️⃣ We now support Regulated Open Finance connections! 🎉
##### If you're interested and want to learn more, [check it out here](https://docs.pluggy.ai/docs/open-finance-regulated)!
### 2️⃣ On 01/10, we will deprecate our connector Inter Investimentos (with id 234) and will solely utilize the connector Inter (with id 215).
##### The connector will carry the same data. If you have any questions or need assistance with your integration, please reach out to us!
### ✨ Features
* We've introduced the **Ailos Cartões PJ** connector.
* We've added the **XP - Wealth** connector.
* You can now configure which products to execute within a Pluggy Connection using the Pluggy Connect Widget! Learn more about [Pluggy Connect configuration here](https://docs.pluggy.ai/edit/environments-and-configurations).
* We've added support for Fixed Income transactions made at Itau Corretora in the **Itau PF** connector.
* We've included the last transaction in Sold investments for the **Inter PF** connector.
* We've introduced support for Mutual Funds and Fixed Income in the **Bradesco PJ** connector.
* We've added the **Cora PJ** connector.
* We've added support for payment data regarding Pix QR transactions in Bradesco PJ.
* We've incorporated `status` and `holderType` fields for `Accounts`.
* We've added support for the Acquiring **Stone** connector with some modifications to our data model.
* We now display `TOTAL_WITHDRAWAL` for sold investments in **Itau PF**.
* We've introduced support for CPF access in the **XP** connector.
## ❤️ Improvements
* We've enhanced the UX for QR flow in Pluggy Connect.
* We've addressed login issues with Itau PJ.
## Julho 2023 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.07
Hey! Welcome to our July product updates! ❄️ Hope you're having a great winter!
## ✨ Features
* We've added support for Loans! See more information [here](https://docs.pluggy.ai/docs/loans).
* We've added Investment Transaction for our Inter PF connector!
* We've added the possibility to encrypt user credentials before sending them to our API and have added support for it in Pluggy Java!
* We've added the `receiverReferenceId` field to our `PaymentData` model and support for it in the Itaú PJ connector!
* We've added support for Fixed Income and Mutual Funds investments in Itau PJ!
* We've added support for BTG multiple accounts!
* We've introduced a new flow in Safra with device authorization!
* We've added a Loans preview on our [Demo page](https://demo.pluggy.ai/).
* We've added support for the `quantity` field in Real Estate Funds in our XP connector!
* We've added the Ailos Cartōes PJ connector!
* We've added the XP - Assessor connector!
## ❤️ Improvements
* We've improved the login flow of **Inter PJ** with enhanced certificate validation.
* We've improved product stability for the Caixa PJ and PF connectors.
* We've enhanced error handling in Pluggy Connect when an item is already updating to improve the UX.
* We've improved Santander PJ credit card stability.
## ℹ️ Information
* We've removed Warren from our list of connectors.
## July 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.07
Hey! Welcome to our July product updates! ❄️ Hope you're having a great winter!
## ✨ Features
* We've added support for Loans! See more information [here](https://docs.pluggy.ai/docs/loans).
* We've added Investment Transaction for our Inter PF connector!
* We've added the possibility to encrypt user credentials before sending them to our API and have added support for it in Pluggy Java!
* We've added the `receiverReferenceId` field to our `PaymentData` model and support for it in the Itaú PJ connector!
* We've added support for Fixed Income and Mutual Funds investments in Itau PJ!
* We've added support for BTG multiple accounts!
* We've introduced a new flow in Safra with device authorization!
* We've added a Loans preview on our [Demo page](https://demo.pluggy.ai/).
* We've added support for the `quantity` field in Real Estate Funds in our XP connector!
* We've added the Ailos Cartōes PJ connector!
* We've added the XP - Assessor connector!
## ❤️ Improvements
* We've improved the login flow of **Inter PJ** with enhanced certificate validation.
* We've improved product stability for the Caixa PJ and PF connectors.
* We've enhanced error handling in Pluggy Connect when an item is already updating to improve the UX.
* We've improved Santander PJ credit card stability.
## ℹ️ Information
* We've removed Warren from our list of connectors.
## Junho 2023 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.06
Hey! Welcome to our June product updates! ❄️
We are happy to announce that you can see your billing data from our [**Dashboard**](https://dashboard.pluggy.ai). Take control of your billing!
:sparkles: Features
* We added our Billing dashboard as you see above! It will be changing so you can have the best experience while using Pluggy ❤️.
* In Connect Widget, now we warn and prevent the user from blocking the account after 2 consecutive login errors.
* We have added support for multiple accounts in **Sicredi PJ**.
* We have added support for Pix QR code payment data support in **Itau PJ**.
* We have added support for no MFA accounts in **BTG**.
* We have added `issuerName` and `cnpj` in our **investments** data model.
* We have added support for non-existing accounts in **Genial** to improve the User Experience when a user is connecting his account and miss spells their user/email.
:heart_decoration: Improvements
* We improved the errors in Connect Widget to improve the Developer Experience while integrating the app.
* We improved the stability of the connections in **Santander PJ**.
* We improved the stability in transactions product in **Caixa**.
* We improved the User Experience in our **Caixa** connector when a user connects an account after **USER\_AUTHORIZATION\_NOT\_GRANTED** status.
* We have improved our `MOVE_SECURITY` step so moving securities will be less painful for all our users.
* We have improved our `login` step in our **Inter PJ** connect.
## June 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.06
Hey! Welcome to our June product updates! ❄️
We are happy to announce that you can see your billing data from our [**Dashboard**](https://dashboard.pluggy.ai). Take control of your billing!
:sparkles: Features
* We added our Billing dashboard as you see above! It will be changing so you can have the best experience while using Pluggy ❤️.
* In Connect Widget, now we warn and prevent the user from blocking the account after 2 consecutive login errors.
* We have added support for multiple accounts in **Sicredi PJ**.
* We have added support for Pix QR code payment data support in **Itau PJ**.
* We have added support for no MFA accounts in **BTG**.
* We have added `issuerName` and `cnpj` in our **investments** data model.
* We have added support for non-existing accounts in **Genial** to improve the User Experience when a user is connecting his account and miss spells their user/email.
:heart_decoration: Improvements
* We improved the errors in Connect Widget to improve the Developer Experience while integrating the app.
* We improved the stability of the connections in **Santander PJ**.
* We improved the stability in transactions product in **Caixa**.
* We improved the User Experience in our **Caixa** connector when a user connects an account after **USER\_AUTHORIZATION\_NOT\_GRANTED** status.
* We have improved our `MOVE_SECURITY` step so moving securities will be less painful for all our users.
* We have improved our `login` step in our **Inter PJ** connect.
## Maio 2023 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.05
:sparkles: Features
* We have added the product `MOVE_SECURITY` that allows users do Security Portability in a few minutes ⚡.
* We have added additional cads support to **Inter PF** connector.
* We have added support to split transactions related to "Sispag Fornecedores" on the Itau Business connector, providing granular payment data for each transaction associated with the grouped one. This provides a detailed view of consolidated transactions.
* We added the `consecutiveFailedLoginAttempts`to our `Item` response, that enable applications & Pluggy Connect to avoid blocking accounts due to multiple consecutive invalid credentials.
:heart_decoration: Improvements
* We have improved **Nubank** accounts response performance and stability.
* We have improved the **Bradesco PF** credit cards response fixing bill dates for installments.
* We have improved the stability of **Banco do Brasil PF** login.
* We have improved the stability of **Ailos PF** login.
* We have improved the credit card transactions with installments recalculating the date in **Santander PF**.
* We have improved the transactions response in **Santander PJ** supporting the `Provider Code`.
* We have improved credit cards response in **Banco do Brasil PF** by adding **balanceCloseDate**.
* We improved our Deel connector, providing a single access for Contractors & Businesses, to collect their financial data. Providing the Business with their employee's contracts & their payments.
## May 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.05
:sparkles: Features
* We have added the product `MOVE_SECURITY` that allows users do Security Portability in a few minutes ⚡.
* We have added additional cads support to **Inter PF** connector.
* We have added support to split transactions related to "Sispag Fornecedores" on the Itau Business connector, providing granular payment data for each transaction associated with the grouped one. This provides a detailed view of consolidated transactions.
* We added the `consecutiveFailedLoginAttempts`to our `Item` response, that enable applications & Pluggy Connect to avoid blocking accounts due to multiple consecutive invalid credentials.
:heart_decoration: Improvements
* We have improved **Nubank** accounts response performance and stability.
* We have improved the **Bradesco PF** credit cards response fixing bill dates for installments.
* We have improved the stability of **Banco do Brasil PF** login.
* We have improved the stability of **Ailos PF** login.
* We have improved the credit card transactions with installments recalculating the date in **Santander PF**.
* We have improved the transactions response in **Santander PJ** supporting the `Provider Code`.
* We have improved credit cards response in **Banco do Brasil PF** by adding **balanceCloseDate**.
* We improved our Deel connector, providing a single access for Contractors & Businesses, to collect their financial data. Providing the Business with their employee's contracts & their payments.
## Abril 2023 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.04
:sparkles: Features
* We have created the `USER_NOT_SUPPORTED` error code, to provide better UX for users that cannot connect to certain Financial Institutions.
* We have added support for **Transactions** & **Identity** on our *Iti connector*, removing it entirely from beta.
* We have launched the "Caixa Previdencia" connector, which allows Caixa users to share their previdencia information aligned with our Previdencia Portability product.
* We launched the [Income Report product](https://docs.pluggy.ai/docs/income-report-beta), which is right now available only for *XP Investmentos*.
* In Connect Widget, we have a new flow to alert the users when they introduce invalid credentials to prevent them from blocking their own accounts.
* In Connect Widget, we have added a new flag called `allowFullscreen` to decide how to display it on mobile devices, whether fullscreen or modal.
:heart_decoration: Improvements
* In Connect Widget, we improved the UI and UX OAuth flow, by providing specific errors with instructions to the user.
## April 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.04
:sparkles: Features
* We have created the `USER_NOT_SUPPORTED` error code, to provide better UX for users that cannot connect to certain Financial Institutions.
* We have added support for **Transactions** & **Identity** on our *Iti connector*, removing it entirely from beta.
* We have launched the "Caixa Previdencia" connector, which allows Caixa users to share their previdencia information aligned with our Previdencia Portability product.
* We launched the [Income Report product](https://docs.pluggy.ai/docs/income-report-beta), which is right now available only for *XP Investmentos*.
* In Connect Widget, we have a new flow to alert the users when they introduce invalid credentials to prevent them from blocking their own accounts.
* In Connect Widget, we have added a new flag called `allowFullscreen` to decide how to display it on mobile devices, whether fullscreen or modal.
:heart_decoration: Improvements
* In Connect Widget, we improved the UI and UX OAuth flow, by providing specific errors with instructions to the user.
## Março 2023 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.03
We are ending our Q1 with this news!!
:sparkles: Features
* We added `eventId` on our [webhooks payload](https://docs.pluggy.ai/docs/webhooks#payload-parameters). This field identifies the event itself univocally allowing our clients to be sure if the event is already processed.
* As part of our **Q1-2023 Hackathon**, we have shipped a lot of connectors that are in BETA and ready to get feedback for our users:
* Lemon Cash (Retail Bank)
* Iti (Retail Bank)
* Wise (Retail Bank)
* Warren Investimentos (Broker)
* Deel (Contractors & Business - Digital Economy)
* OnTop (Digital Economy)
* Stone (PSP)
* Splitwise (Personal Finance Management).
* MeuVivo (Telecommunication)
* ContaAzul (Invoicing)
* We are launching our [MeuPluggy](https://meu.pluggy.ai) consent management platform where all the users that shared their access through our platform can manage their consents, review their data and revoke any access that they want to restrict. **This is automatically provided for all our customers.**
* [OAuth v2](https://docs.pluggy.ai/docs/connect-an-account#oauth-v2) has been launched at Pluggy, for some new connectors provided in the news above. This new flow allows tracking the user's connection through the complete flow.
* We added `consecutiveFailedLoginAttempts` to our item entity in order to warn users when they’re about to cause ACCOUNT\_LOCKED on their own accounts.
* We launch [INCOME REPORTS](https://docs.pluggy.ai/docs/income-report-beta) new product for XP connector!!
* We have added the "Item's Execution" overview page to our dashboard, you can now go deeper into the item's health by analyzing the item by its ID.
* 
:heart_decoration: Improvements
* We have improved our [Categorization documentation](https://docs.pluggy.ai/docs/transaction-categories), providing more insights about this feature, and what else can be achieved from this.
:dizzy_face: Sad news
* To improve scalability and performance with Investment transactions, we are not deprecating the `transactions` field in `GET /investments` and `GET /investments/{id}` in favor of our paginated [Investment Transactions](https://docs.pluggy.ai/reference/investment-transactions-list) endpoint. We will no longer return the \`transactions´ field in Investments for new Applications, created from 21st March 2023 onward.
## March 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.03
We are ending our Q1 with this news!!
:sparkles: Features
* We added `eventId` on our [webhooks payload](https://docs.pluggy.ai/docs/webhooks#payload-parameters). This field identifies the event itself univocally allowing our clients to be sure if the event is already processed.
* As part of our **Q1-2023 Hackathon**, we have shipped a lot of connectors that are in BETA and ready to get feedback for our users:
* Lemon Cash (Retail Bank)
* Iti (Retail Bank)
* Wise (Retail Bank)
* Warren Investimentos (Broker)
* Deel (Contractors & Business - Digital Economy)
* OnTop (Digital Economy)
* Stone (PSP)
* Splitwise (Personal Finance Management).
* MeuVivo (Telecommunication)
* ContaAzul (Invoicing)
* We are launching our [MeuPluggy](https://meu.pluggy.ai) consent management platform where all the users that shared their access through our platform can manage their consents, review their data and revoke any access that they want to restrict. **This is automatically provided for all our customers.**
* [OAuth v2](https://docs.pluggy.ai/docs/connect-an-account#oauth-v2) has been launched at Pluggy, for some new connectors provided in the news above. This new flow allows tracking the user's connection through the complete flow.
* We added `consecutiveFailedLoginAttempts` to our item entity in order to warn users when they’re about to cause ACCOUNT\_LOCKED on their own accounts.
* We launch [INCOME REPORTS](https://docs.pluggy.ai/docs/income-report-beta) new product for XP connector!!
* We have added the "Item's Execution" overview page to our dashboard, you can now go deeper into the item's health by analyzing the item by its ID.
* 
:heart_decoration: Improvements
* We have improved our [Categorization documentation](https://docs.pluggy.ai/docs/transaction-categories), providing more insights about this feature, and what else can be achieved from this.
:dizzy_face: Sad news
* To improve scalability and performance with Investment transactions, we are not deprecating the `transactions` field in `GET /investments` and `GET /investments/{id}` in favor of our paginated [Investment Transactions](https://docs.pluggy.ai/reference/investment-transactions-list) endpoint. We will no longer return the \`transactions´ field in Investments for new Applications, created from 21st March 2023 onward.
## Fevereiro 2023 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.02
Happy Carnaval from Pluggy! :tada:\
This month we did a little more than enjoy the holidays, and here is just the summary of it.
:sparkles: Features
* We have added the `ACCOUNT_CREDENTIALS_RESET` execution error for users that face this situation forced by the financial institution to refresh due to expired credentials or new measures taken by the institution. No synchronization will happen until the item is updated with the new set of credentials.
* We are returning the `metadata` response for **Nuinvest**, **BTG Pactual** & **Orama** allowing Previdencia Portability for the financial institution.
* We added the `investorProfile` field to our `identity` product, which indicates the investor's personality and motivation for investing. This is already being recovered on **XP Investimentos** & **BTG Pactual**, adding it to more institutions for the next month.
* **XP Investimentos** & **Ailos** now supports the product **Credit Card** and it's **Transactions**, returning up to 12 months of historic data.
:heart_decoration: Improvements
* We have improved **Genial Investimentos** investment transaction's response with Taxes, Transfers & Sales operations.
* Warnings now have more details about the `code` related to the warning and, if provided, will return the `providerMessage` a user-friendly message directly from the financial institution.
From recent updates, all SDKs have been updated and are kept updated to the latest changes that our API occurs. Please visit the specific SDK public GitHub repository for more information.
:dizzy_face: Sad news
* We have deprecated our **C6 Connector** due to security restrictions from the financial institution. For the time being it won't be available, until something change in the future. All existing connections can still be recovered from our API.
## February 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.02
Happy Carnaval from Pluggy! :tada:\
This month we did a little more than enjoy the holidays, and here is just the summary of it.
:sparkles: Features
* We have added the `ACCOUNT_CREDENTIALS_RESET` execution error for users that face this situation forced by the financial institution to refresh due to expired credentials or new measures taken by the institution. No synchronization will happen until the item is updated with the new set of credentials.
* We are returning the `metadata` response for **Nuinvest**, **BTG Pactual** & **Orama** allowing Previdencia Portability for the financial institution.
* We added the `investorProfile` field to our `identity` product, which indicates the investor's personality and motivation for investing. This is already being recovered on **XP Investimentos** & **BTG Pactual**, adding it to more institutions for the next month.
* **XP Investimentos** & **Ailos** now supports the product **Credit Card** and it's **Transactions**, returning up to 12 months of historic data.
:heart_decoration: Improvements
* We have improved **Genial Investimentos** investment transaction's response with Taxes, Transfers & Sales operations.
* Warnings now have more details about the `code` related to the warning and, if provided, will return the `providerMessage` a user-friendly message directly from the financial institution.
From recent updates, all SDKs have been updated and are kept updated to the latest changes that our API occurs. Please visit the specific SDK public GitHub repository for more information.
:dizzy_face: Sad news
* We have deprecated our **C6 Connector** due to security restrictions from the financial institution. For the time being it won't be available, until something change in the future. All existing connections can still be recovered from our API.
## Janeiro 2023 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2023.01
Happy new year to all Pluggy's family that are part of our ecosystem! The year already started and we are already doing some noise.
:sparkles: Features
* We are shipping the **Empiricus Investimentos (former Vitreo)** connector this month, we are running the final tests and will be available as BETA by the end of the month. If you want to participate, please reach out!
* We launched in BETA the **Ethereum Network** connector, allowing users to share their Web3 Addresses, through Metamask in this first version, and providing a validated way to collect Web3 financial information.
* **XP Investimentos** is now returning the "Conta Digital" checking account with the last 12 months of transaction history. Providing not only asset activity but also bank account historic information.
* **Pluggy Connect** now allows to manually trigger the `hide` function of the widget for "Connection in Background" purposes. This empowers developers to create their own user journey hiding the widget when the login has been confirmed.
* On our [Dashboard](https://dashboard.pluggy.ai) you can now review all the Webhook's events sent to the configured listeners, filtering by events, items, or even applications.
* We have added the `nextAutoSyncAt` field in the [`GET /item/{id}`](https://docs.pluggy.ai/reference/items-retrieve) endpoint to allow clients to know when an Item is going to auto sync next, or if it has auto-sync enabled. More information on this field at our [auto sync docs](https://docs.pluggy.ai/docs/item#auto-sync).
* We have added [product warnings](https://docs.pluggy.ai/docs/errors-validations#product-warnings) in the `statusDetail` field of the Item, for cases when an empty product is returned and it is correct behaviour (for example, when the user does not have permission to see that product in the Institution)
* We have added new [Webhooks](https://docs.pluggy.ai/docs/webhooks) and are actively working on improving our docs. In this case, we have added the `transactions/deleted` event to [easily merge the transactions](https://docs.pluggy.ai/docs/transactions#how-to-syncronize-and-merge-transactions) after the item has been updated.
```json Event transactions/deleted payload
{
"event":"transactions/deleted",
"itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
"clientId":"90b4f38c-447a-4a08-8fcc-e58465056da8",
"accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
"transactionIds": [
"5a14feae-eaa7-423a-820c-6b83837c35b7",
"786c7d98-6085-4879-9c7f-2255260e2436"
]
}
```
:heart_decoration: Improvements
* Major improvements were delivered for ***BTG Pactual & XP Investimentos*** connectors providing an accelerated experience with the best data coverage in the market.
* All login flows can now be tested using our *Pluggy Bank* Sandbox connector that will allow the same experience that each of the financial institutions supported.
* Our **Pluggy Connect widget** keeps getting major performance and visual improvements. It's the best way for every developer to keep updated with the different connectors with a seamless experience.
* **Genial Investimentos** connector now supports a new flow with mobile token as a password, that its required for some specific users.
* **Sicoob PJ** now supports selecting which company the user wants to connect to. In this case, if the user needs to connect to all companies, multiple items should be created for each one.
* Our *Demo App* its now fully integrated with the Dashboard on a seamless login powered by Auth0.
Demo Login
## Pluggy WhatsApp 🤖
We introduced a new product that allows you to connect users' bank accounts via WhatsApp!\
We launched an open version that gives you insights about your bank data, you can use this demo by clicking [this link](https://api.whatsapp.com/send?phone=5491173603358\&text=Oi)!
If you are interested in this product, let us know!
## January 2023 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2023.01
Happy new year to all Pluggy's family that are part of our ecosystem! The year already started and we are already doing some noise.
:sparkles: Features
* We are shipping the **Empiricus Investimentos (former Vitreo)** connector this month, we are running the final tests and will be available as BETA by the end of the month. If you want to participate, please reach out!
* We launched in BETA the **Ethereum Network** connector, allowing users to share their Web3 Addresses, through Metamask in this first version, and providing a validated way to collect Web3 financial information.
* **XP Investimentos** is now returning the "Conta Digital" checking account with the last 12 months of transaction history. Providing not only asset activity but also bank account historic information.
* **Pluggy Connect** now allows to manually trigger the `hide` function of the widget for "Connection in Background" purposes. This empowers developers to create their own user journey hiding the widget when the login has been confirmed.
* On our [Dashboard](https://dashboard.pluggy.ai) you can now review all the Webhook's events sent to the configured listeners, filtering by events, items, or even applications.
* We have added the `nextAutoSyncAt` field in the [`GET /item/{id}`](https://docs.pluggy.ai/reference/items-retrieve) endpoint to allow clients to know when an Item is going to auto sync next, or if it has auto-sync enabled. More information on this field at our [auto sync docs](https://docs.pluggy.ai/docs/item#auto-sync).
* We have added [product warnings](https://docs.pluggy.ai/docs/errors-validations#product-warnings) in the `statusDetail` field of the Item, for cases when an empty product is returned and it is correct behaviour (for example, when the user does not have permission to see that product in the Institution)
* We have added new [Webhooks](https://docs.pluggy.ai/docs/webhooks) and are actively working on improving our docs. In this case, we have added the `transactions/deleted` event to [easily merge the transactions](https://docs.pluggy.ai/docs/transactions#how-to-syncronize-and-merge-transactions) after the item has been updated.
```json Event transactions/deleted payload
{
"event":"transactions/deleted",
"itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
"clientId":"90b4f38c-447a-4a08-8fcc-e58465056da8",
"accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
"transactionIds": [
"5a14feae-eaa7-423a-820c-6b83837c35b7",
"786c7d98-6085-4879-9c7f-2255260e2436"
]
}
```
:heart_decoration: Improvements
* Major improvements were delivered for ***BTG Pactual & XP Investimentos*** connectors providing an accelerated experience with the best data coverage in the market.
* All login flows can now be tested using our *Pluggy Bank* Sandbox connector that will allow the same experience that each of the financial institutions supported.
* Our **Pluggy Connect widget** keeps getting major performance and visual improvements. It's the best way for every developer to keep updated with the different connectors with a seamless experience.
* **Genial Investimentos** connector now supports a new flow with mobile token as a password, that its required for some specific users.
* **Sicoob PJ** now supports selecting which company the user wants to connect to. In this case, if the user needs to connect to all companies, multiple items should be created for each one.
* Our *Demo App* its now fully integrated with the Dashboard on a seamless login powered by Auth0.
Demo Login
## Pluggy WhatsApp 🤖
We introduced a new product that allows you to connect users' bank accounts via WhatsApp!\
We launched an open version that gives you insights about your bank data, you can use this demo by clicking [this link](https://api.whatsapp.com/send?phone=5491173603358\&text=Oi)!
If you are interested in this product, let us know!
## Dezembro 2022 (Atualização mensal)
Source: https://docs.pluggy.ai/pt/changelog#2022.12
Hello, and welcome to our **December** (Work in progress) changelog!\
Even though there is a World Cup, we delivered many features you can use to empower your applications.
:sparkles: Features
* We have delivered and it's in **BETA** the **Avenue Broker Connector**!\
You can now recover your checking account, transactions and investments (mutual funds, equities & ETFs).\
This is already available in our [dashboard](https://dashboard.pluggy.ai) for you to enable on your application.\
Feel free to reach out with any problems or doubts.
* **Genial Broker** keeps growing support for asset transactions, now we are returning transactions for assets of type Securities, Fixed Income & Equities.
* Pss it's coming home! **Portfolio Yield** is on public **BETA**. Providing a historic & whole view of your user's portfolio performance month over month. We are preparing the beta launch for *XP Investimentos* accounts.\
Reach out to [support@pluggy.ai](mailto:support@pluggy.ai) or chat with us, if you want to join the BETA!
* Did you know the [Opportunities](https://docs.pluggy.ai/docs/opportunity) product? It provides a great vision of what products are the financial institutions offering to your users. This provides a competitive battleground to deliver improved products to your users. Now available on the **Itau Business** connector as well!
* We have improved the `health` object that now provides **statistics about your recent connections on the connector and recent connection rate** (percentage of healthy connections) that can be recovered when listing the connectors, check it out under the [API Reference](https://docs.pluggy.ai/reference/connectors-list).
```json Connector's list response
{
"page": 1,
"total": 1,
"totalPages": 1,
"results": [
{
"id": 201,
"name": "Itaú",
"type": "PERSONAL_BANK",
"credentials": [],
"products": [],
"health": {
"status": "ONLINE",
"stage": null,
"details": {
"connectionRateLast6Hours": 94.3,
"connectionsLast6Hours": 53
}
}
}
]
}
```
:heart_decoration: Improvements
* We have sped up the process of recovering customized Terms & Conditions.\
Did you know that terms & conditions can be customized?
* Major improvement on **XP Investimentos**! After a significant blocker, and some weeks of instability, we launched the v2 of the connector improving the performance of the connection by more than 50%.\
Due to the blocker, we are not returning Equities & Securities transactions.
* **Banco do Brasil** it's returning future transactions as `PENDING` now available for all Credit Cards & Accounts.
* When a Connector requires [an MFA Token to execute an update](https://docs.pluggy.ai/reference/items-update) (ie. Bradesco PF), the API will require this input to be different from the previous one. If not, it will return an HTTP 400 error.
```json HTTP 400 error
{
"code": 400,
"message": "MFA parameter has to be updated from last execution"
}
```
* We have increased the "Sandbox" coverage for all the different flows available (yep, there are too many!!). It's important for you to test each one of those.
* Sandbox connectors can be found with `connectorId` lower than 99.
* If you are using the *Pluggy Connect* widget, you will have the following experience.
:ballot_box_with_check: Fixed
* Fixed `clientUserId` not being propagated to item connections for **MercadoPago** connector. This only affected *Pluggy Connect* connections.
## Remember, we are one text message away!
For any doubt, issues, or BETA access, please reach out through our chat. We will get back to you as soon as possible.\
Also, you can check out our latest Dashboard features that will improve your day-to-day.
## December 2022 (Monthly Update)
Source: https://docs.pluggy.ai/pt/changelog#2022.12
Hello, and welcome to our **December** (Work in progress) changelog!\
Even though there is a World Cup, we delivered many features you can use to empower your applications.
:sparkles: Features
* We have delivered and it's in **BETA** the **Avenue Broker Connector**!\
You can now recover your checking account, transactions and investments (mutual funds, equities & ETFs).\
This is already available in our [dashboard](https://dashboard.pluggy.ai) for you to enable on your application.\
Feel free to reach out with any problems or doubts.
* **Genial Broker** keeps growing support for asset transactions, now we are returning transactions for assets of type Securities, Fixed Income & Equities.
* Pss it's coming home! **Portfolio Yield** is on public **BETA**. Providing a historic & whole view of your user's portfolio performance month over month. We are preparing the beta launch for *XP Investimentos* accounts.\
Reach out to [support@pluggy.ai](mailto:support@pluggy.ai) or chat with us, if you want to join the BETA!
* Did you know the [Opportunities](https://docs.pluggy.ai/docs/opportunity) product? It provides a great vision of what products are the financial institutions offering to your users. This provides a competitive battleground to deliver improved products to your users. Now available on the **Itau Business** connector as well!
* We have improved the `health` object that now provides **statistics about your recent connections on the connector and recent connection rate** (percentage of healthy connections) that can be recovered when listing the connectors, check it out under the [API Reference](https://docs.pluggy.ai/reference/connectors-list).
```json Connector's list response
{
"page": 1,
"total": 1,
"totalPages": 1,
"results": [
{
"id": 201,
"name": "Itaú",
"type": "PERSONAL_BANK",
"credentials": [],
"products": [],
"health": {
"status": "ONLINE",
"stage": null,
"details": {
"connectionRateLast6Hours": 94.3,
"connectionsLast6Hours": 53
}
}
}
]
}
```
:heart_decoration: Improvements
* We have sped up the process of recovering customized Terms & Conditions.\
Did you know that terms & conditions can be customized?
* Major improvement on **XP Investimentos**! After a significant blocker, and some weeks of instability, we launched the v2 of the connector improving the performance of the connection by more than 50%.\
Due to the blocker, we are not returning Equities & Securities transactions.
* **Banco do Brasil** it's returning future transactions as `PENDING` now available for all Credit Cards & Accounts.
* When a Connector requires [an MFA Token to execute an update](https://docs.pluggy.ai/reference/items-update) (ie. Bradesco PF), the API will require this input to be different from the previous one. If not, it will return an HTTP 400 error.
```json HTTP 400 error
{
"code": 400,
"message": "MFA parameter has to be updated from last execution"
}
```
* We have increased the "Sandbox" coverage for all the different flows available (yep, there are too many!!). It's important for you to test each one of those.
* Sandbox connectors can be found with `connectorId` lower than 99.
* If you are using the *Pluggy Connect* widget, you will have the following experience.
:ballot_box_with_check: Fixed
* Fixed `clientUserId` not being propagated to item connections for **MercadoPago** connector. This only affected *Pluggy Connect* connections.
## Remember, we are one text message away!
For any doubt, issues, or BETA access, please reach out through our chat. We will get back to you as soon as possible.\
Also, you can check out our latest Dashboard features that will improve your day-to-day.
Esse é todo o processo de configuração. Uma vez instalado, convide o bot para qualquer canal onde você deseja usá-lo.
## Use-o
- **Mencione-o** em um canal onde ele está:
```
@Pluggy Docs como eu crio um connect token e abro o Connect Widget?
```
- **Envie uma mensagem direta** com uma pergunta — nenhum comando necessário:
```
Quais escopos o Connect Widget precisa?
```
O bot responde com uma resposta concisa baseada na documentação do Pluggy, com links para os guias relevantes.
## O que ele pode acessar (hoje)
Por enquanto, o bot responde apenas da **documentação pública** do Pluggy — o mesmo conteúdo disponível em [v2.docs.pluggy.ai](https://v2.docs.pluggy.ai): guias, referência da API, changelog, receitas e perguntas e respostas curadas. Ele **não** acessa sua conta Pluggy, aplicativos ou dados.