# 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 ## 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. ## 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, suporte Meu Pluggy 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. ## Security - [Visão geral de segurança](https://docs.pluggy.ai/pt/docs/security/overview.md): As práticas de segurança que toda integração Pluggy deve seguir: onde suas credenciais estão, o que o front end pode conter, como confiar em um webhook, quem na sua equipe pode mudar o que e como lidar com os dados dos seus usuários. - [Credenciais e chaves da API](https://docs.pluggy.ai/pt/docs/security/credentials.md): O que são o ID do cliente, o secret do cliente e a chave da API, onde cada um pode estar, como armazenar e rotacionar o secret do cliente e o que fazer quando uma credencial vaza. - [Connect Tokens](https://docs.pluggy.ai/pt/docs/security/connect-tokens.md): Por que o front end só recebe um Connect Token, como emitir um do seu backend, a que ele pode acessar, quanto tempo dura e as opções que importam para a segurança. - [Lista de IPs permitidos](https://docs.pluggy.ai/pt/docs/security/ip-allowlist.md): Restringir quais endereços IP podem chamar a Referência da API do Pluggy com as credenciais de uma aplicação, para que um client secret ou chave da API vazados não possam ser usados de qualquer outro lugar. Como funciona, como configurá-lo no Dashboard, o que cobre e como solucionar um 403 CLIENT_IP_NOT_ALLOWED. - [Acesso da equipe](https://docs.pluggy.ai/pt/docs/security/team-access.md): As funções de uma equipe do Dashboard Pluggy, o que cada uma pode fazer com suas aplicações, secrets e webhooks, e como manter o acesso às pessoas que precisam. - [Proteção de dados](https://docs.pluggy.ai/pt/docs/security/data-protection.md): Como lidar com as credenciais bancárias, consentimento e dados financeiros dos seus usuários em uma integração Pluggy: mantenha as credenciais fora dos seus servidores, permita que os usuários desconectem, reaja a exclusões e armazene apenas o que você usa. ## 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 opções de configuração para o Pluggy Connect, 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. - [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 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. - [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 conector 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 conector 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 conector em relação ao produto 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 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): 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. - [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ção](https://docs.pluggy.ai/pt/docs/products/transactions.md): Recupere até 12 meses de dados de transações. Os dados de transações das contas fornecem insights sobre o comportamento financeiro do usuário. - [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. - [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ê precisa 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 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. - [Customização da Tela de Pagamento](https://docs.pluggy.ai/pt/docs/payments/customization.md): Do Dashboard, personalize a tela de pagamento que seus clientes veem: nome da empresa, logo e cores, para toda a equipe ou para cada aplicação. - [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 Pluggy com uma instituição financeira, incluindo conectores 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 a partir do 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 Ticket 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. - [Segurança do Webhook](https://docs.pluggy.ai/pt/docs/developer-tools/webhook-security.md): Como confiar em um webhook do Pluggy: HTTPS, IPs de origem, um cabeçalho de autenticação, a assinatura HMAC e a nova busca dos dados, e o que cada um protege e não protege. ## 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}/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 - [Authenticate webhook notifications with a header secret](https://docs.pluggy.ai/pt/recipes/authenticate-webhook-notifications-with-a-header-secret.md): Register your webhook with a secret header, reject requests without it, check the clientId, and read the data with your API key instead of trusting the payload. - [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. - [Issue Connect Tokens from your backend](https://docs.pluggy.ai/pt/recipes/issue-connect-tokens-from-your-backend.md): Keep your client secret and API key on your server, and give the front end only a short-lived Connect Token for the user who is signed in. - [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. - [Rotate your client secret](https://docs.pluggy.ai/pt/recipes/rotate-your-client-secret.md): Replace an application's client secret with no downtime, keeping the previous secret working while you deploy, or cut a leaked one off at once. - [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 | Outubro/2026](https://docs.pluggy.ai/pt/changelog#2026.10): Published 2026-10-31 - [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 --- ## 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): Adicionar ao Slack 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. ## 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. ### Formato do segredo do cliente Novos segredos de cliente começam com o prefixo `pluggy_sk_` e têm 56 caracteres de comprimento. O prefixo e um checksum embutido tornam os segredos Pluggy reconhecíveis por scanners de segredos, então um segredo acidentalmente comprometido em um repositório pode ser detectado imediatamente. Segredos criados antes dessa mudança não têm o prefixo e permanecem válidos. A autenticação não muda: continue enviando seu `clientId` e `clientSecret` para `POST /auth`. Quando você gerar um novo segredo no [Dashboard](https://dashboard.pluggy.ai), ele usará o formato `pluggy_sk_`. Trate seu segredo de cliente como uma senha: armazene-o em um gerenciador de segredos ou em uma variável de ambiente, e nunca o comprometa ou exponha em código do lado do cliente. ## 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": "Meu 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 é descartado silenciosamente { "clientUserId": "Meu App UserId", "options": { "avoidDuplicates": true } } // ✅ Correto { "options": { "clientUserId": "Meu 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 está no guia Meu Pluggy em [meu.pluggy.ai/api-guide](https://meu.pluggy.ai/api-guide). Para um problema com sua conta ou uma de suas conexões, escreva para **[meu-suporte@pluggy.ai](mailto:meu-suporte@pluggy.ai)** a partir do e-mail da sua conta Meu Pluggy. Dúvidas sobre uso pessoal vão para o mesmo endereço. ## 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. Até que o acesso a dados reais seja aprovado para seu teste, a lista de teste inclui apenas os conectores Sandbox (Pluggy Bank) e [MeuPluggy](/docs/guides/meu-pluggy-personal-use); uma vez aprovado, todos os conectores estão disponíveis. ## 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. Conectar contas reais também requer um plano pago: aplicações gratuitas podem apenas criar itens nos conectores Sandbox (Pluggy Bank) e MeuPluggy, e qualquer outro conector retorna `400 CLIENT_PLAN_REAL_CONNECTORS_NOT_ALLOWED` — veja [Códigos de Erro](/reference/error-codes#creating-and-updating-an-item). ## 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 - **Cada aplicação 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 chamar 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 do 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 do fechamento de uma conta, e vai para o Oficial 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 no 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), envie essas solicitações de proteção de dados para [dpo@pluggy.ai](mailto:dpo@pluggy.ai) do e-mail da sua conta Meu Pluggy; qualquer outro problema com a conta deve ser enviado para [meu-suporte@pluggy.ai](mailto:meu-suporte@pluggy.ai). ## 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. ## Visão geral de segurança Source: https://docs.pluggy.ai/pt/docs/security/overview.md Seu credenciais Pluggy alcançam os dados financeiros de seus usuários. O Pluggy executa as conexões com as instituições, mantém as credenciais e dados de cada Item, e entrega seus webhooks, assinados uma vez que você ativa a assinatura. Seu lado da integração é sua responsabilidade: suas credenciais, os tokens que você entrega ao front end, seu endpoint de webhook, sua equipe e os dados que você copia para seus próprios sistemas. Cada seção abaixo é um resumo com um link para a página que contém os detalhes. A [lista de verificação](#checklist) no final resume tudo. ## Credenciais permanecem em seu servidor O secret do cliente de sua aplicação e as chaves da API que seu servidor cria com ele têm acesso total à API Pluggy. Mantenha-os em um gerenciador de segredos ou em uma variável de ambiente do servidor, reutilize cada chave da API até que expire e use aplicações separadas para desenvolvimento e produção. Um novo secret do cliente pode manter o anterior funcionando por 24 horas, então uma rotação não precisa de tempo de inatividade; quando um secret vaza, gire sem essa opção para que o antigo pare imediatamente. Uma rotação não revoga chaves da API criadas antes dela. Detalhes: [Credenciais e chaves da API](/docs/security/credentials). Receita: [Gire seu secret do cliente](/recipes/rotate-your-client-secret). ## Limite onde suas credenciais funcionam Uma aplicação pode ter uma lista de IPs permitidos: uma vez que tenha uma, `POST /auth` e cada solicitação feita com suas chaves da API são aceitas apenas dos IPs que você listar, então um secret ou chave da API vazados são inúteis em qualquer outro lugar. Solicitações feitas com um Connect Token, e assim o Pluggy Connect, não estão restritas. Detalhes: [Lista de IPs permitidos](/docs/security/ip-allowlist). ## O front end recebe um Connect Token, nunca uma chave da API Seu backend cria um Connect Token para um usuário autenticado, e o front end abre o Pluggy Connect com ele. Ele dura 30 minutos, alcança apenas os Itens criados com ele e não pode ler dados do produto. Defina `clientUserId` como um identificador opaco e mantenha `includeSandbox` desativado em produção. Detalhes: [Connect Tokens](/docs/security/connect-tokens). Receita: [Emita Connect Tokens do seu backend](/recipes/issue-connect-tokens-from-your-backend). ## Verifique cada notificação de webhook Seu endpoint de webhook é público, então trate cada solicitação como não confiável até que passe por suas verificações. Combine as camadas: um endpoint HTTPS, um secret nos `headers` do webhook e a assinatura HMAC **`X-Pluggy-Signature`**, que prova que o Pluggy enviou a notificação e que seu corpo não foi alterado. Em seguida, verifique `clientId` e leia o estado atual com sua chave da API em vez de confiar na carga útil. O filtro de IP de origem é uma camada extra, nunca a única. Detalhes: [Segurança do webhook](/docs/developer-tools/webhook-security). Receita: [Autentique notificações de webhook com um secret no cabeçalho](/recipes/authenticate-webhook-notifications-with-a-header-secret). ## Apenas as pessoas certas gerenciam suas aplicações Uma equipe tem três papéis. Proprietários e Administradores geram secrets do cliente e gerenciam webhooks; apenas Proprietários desativam ou excluem aplicações e gerenciam o secret de assinatura do webhook. Mantenha `OWNER` e `ADMIN` para as pessoas que precisam deles e gire os secrets quando alguém que poderia vê-los sair. Detalhes: [Acesso da equipe](/docs/security/team-access). ## Os dados e consentimento de seus usuários Deixe o Pluggy Connect coletar credenciais bancárias, para que nunca passem pelos seus servidores. Deixe os usuários desconectarem e exclua o Item quando o fizerem: isso apaga suas credenciais, revoga o consentimento e exclui seus dados. Remova sua própria cópia em `item/deleted` e armazene apenas o que seu produto usa. Detalhes: [Proteção de dados](/docs/security/data-protection). ## Relatar uma vulnerabilidade Se você encontrar uma vulnerabilidade de segurança no Pluggy, escreva para [security@pluggy.ai](mailto:security@pluggy.ai). O mesmo contato é publicado em nosso [`security.txt`](https://docs.pluggy.ai/.well-known/security.txt). ## Lista de verificação | Área | Verificação | | --- | --- | | Credenciais | O secret do cliente vive apenas em um gerenciador de segredos ou variável de ambiente do servidor. | | Credenciais | Nenhum secret do cliente ou chave da API está no código do front-end, aplicativos móveis, repositórios ou logs. | | Credenciais | Seu servidor reutiliza cada chave da API até que expire. | | Credenciais | Desenvolvimento e produção usam aplicações separadas. | | Credenciais | Você sabe como gerar um novo secret do cliente, onde implantá-lo e como desativar a aplicação se uma chave da API vazar. | | Credenciais | Se seus servidores tiverem IPs de saída estáticos, sua aplicação de produção tem uma lista de IPs permitidos com eles. | | Front end | O front end recebe apenas Connect Tokens, criados pelo seu backend para um usuário autenticado. | | Front end | `clientUserId` é um identificador opaco, não dados pessoais. | | Front end | `includeSandbox` está desativado em produção. | | Webhooks | Seu endpoint verifica `X-Pluggy-Signature` sobre o corpo bruto, com uma tolerância de 5 minutos. | | Webhooks | Webhooks criados com `POST /webhooks` carregam um cabeçalho secreto que seu endpoint requer. | | Webhooks | Seu endpoint ignora notificações para outros `clientId`s, responde `2xx` rapidamente e lê os dados com sua chave da API. | | Acesso | Apenas as pessoas que precisam são `OWNER` ou `ADMIN` de sua equipe. | | Acesso | Membros que saem são removidos, e os secrets que poderiam ver são girados. | | Dados | Usuários podem se desconectar, e desconectar exclui o Item. | | Dados | Você remove sua cópia dos dados em `item/deleted`. | ## Credenciais e chaves da API Source: https://docs.pluggy.ai/pt/docs/security/credentials.md Toda aplicação no [Dashboard](https://dashboard.pluggy.ai) possui suas próprias credenciais e, juntas, elas alcançam cada Item dessa aplicação. Esta página cobre onde cada uma pode estar e o que fazer quando uma delas é exposta. ## As três credenciais | Credencial | O que é | Onde pode estar | | --- | --- | --- | | Client ID | Identifica a aplicação. Exibido no Dashboard a qualquer momento. | Seu servidor. Não é um segredo por si só, mas é útil apenas junto com o client secret. | | Client secret | Prova que você possui a aplicação. Exibido **uma vez**, quando é gerado. | Apenas no seu servidor: um gerenciador de segredos ou uma variável de ambiente. | | API key | Criada pelo seu servidor com [`POST /auth`](/reference/auth-create) a partir do client ID e do secret. Tem **acesso total** a cada endpoint da Pluggy API. | Apenas no seu servidor, na memória. | O front end nunca recebe nenhuma delas. Ele recebe um [Connect Token](/docs/security/connect-tokens), que seu backend cria para um usuário. ## Armazene o client secret como uma senha - Mantenha-o em um gerenciador de segredos ou em uma variável de ambiente do seu servidor. Nunca o comite, nunca o registre e nunca o coloque em código de front-end, um aplicativo móvel, um ticket ou uma mensagem de chat. - Leia-o de um único lugar. Assim, uma rotação é uma atualização e um redeploy, não uma busca por repositórios. - Novos client secrets começam com `pluggy_sk_` e carregam um checksum, para que scanners de segredos possam reconhecer um que acabe em um repositório. Veja [Formato do client secret](/docs/authentication#client-secret-format). - O secret não pode ser visualizado novamente após o diálogo que o exibe ser fechado: nem no Dashboard e nem através da API. Se você o perder, gere um novo. ## Use a API key apenas do seu servidor - Crie uma API key com `POST /auth` e reutilize-a até que expire, em vez de chamar `POST /auth` em cada requisição. A [vida útil](/docs/authentication#create-an-api-key) e o [limite de taxa de `POST /auth`](/reference/rate-limits) estão em suas próprias páginas. Quando uma requisição responde `401` porque a chave expirou, crie uma nova. - O SDK Node.js (`pluggy-sdk`) cria a API key e a reutiliza para você. - Nunca envie uma API key para um navegador ou um aplicativo móvel, e nunca a registre: qualquer um que a possua tem o mesmo acesso que seu servidor até que expire. ## Restringir os IPs que podem usá-las Dê à aplicação uma [lista de IPs permitidos](/docs/security/ip-allowlist) e `POST /auth`, e cada requisição feita com suas API keys será aceita apenas dos IPs do seu servidor. Um secret ou API key que vazar não poderá ser usado de nenhum outro lugar. Requisições feitas com um Connect Token não são restritas, então o Pluggy Connect continua funcionando nos dispositivos dos seus usuários. ## Separe desenvolvimento, produção e inquilinos - **Uma aplicação por ambiente.** Cada aplicação tem seu próprio client ID e client secret, então um secret de desenvolvimento que vazar não alcança dados de produção. Veja [Ambientes e produção](/docs/get-started/faq#environments-and-production). - **Uma aplicação por inquilino**, se você atender várias empresas: Itens só são acessíveis com as credenciais da aplicação sob a qual foram criados, então um secret vazado ou rotacionado afeta apenas um inquilino. Veja [Uma aplicação, ou uma por cliente?](/docs/get-started/multi-tenant-applications). - **Ir para produção rotaciona o secret.** Quando uma aplicação é movida para produção, seu secret é rotacionado e o Dashboard pede a um Owner ou Admin para gerar um novo. Essa rotação nunca mantém o secret anterior funcionando, então planeje o deploy do novo secret para aquele momento. ## Rotacione o client secret Clique em **Gerar novo secret** na página da aplicação no Dashboard. Apenas Owners e Admins de uma equipe podem fazer isso (veja [Acesso da equipe](/docs/security/team-access)). A confirmação tem a opção **Manter o secret anterior funcionando por 24 horas**, marcada por padrão: - **Marcada**: o novo secret funciona imediatamente, e o anterior continua funcionando com `POST /auth` por 24 horas, depois para por conta própria. Uma rotação não precisa de downtime: gere o novo secret, implemente-o em cada serviço, e você está feito. - **Desmarcada**: o secret anterior para de funcionar **imediatamente**. Qualquer serviço que precise de uma nova API key falha até que tenha o novo secret. Use isso quando o secret pode ter sido exposto. Enquanto o secret anterior ainda for válido, a página da aplicação mostra quando ele para de funcionar e um botão **Revogar agora** que encerra imediatamente. Clique nele assim que cada serviço usar o novo secret, ou deixe-o expirar. - Uma aplicação tem no máximo **dois secrets válidos**: o atual e o anterior. Gerar outro secret durante essas 24 horas invalida o mais antigo, e gerar um sem a opção invalida todos os secrets anteriores. - A opção não é oferecida quando o Pluggy requer um novo secret por segurança, como após a aplicação ser movida para produção ou após o Pluggy rotacionar um secret encontrado exposto. - O novo secret é exibido **uma vez**. Armazene-o em seu gerenciador de segredos antes de fechar o diálogo. - Gerar um novo secret, ou clicar em **Revogar agora**, **não revoga as API keys criadas antes dele**. Elas continuam funcionando até expirarem. Receita, com um script que verifica o novo secret antes de você redeployar: [Rotacione seu client secret](/recipes/rotate-your-client-secret). ## Se uma credencial vazar **Um client secret.** Gere um novo imediatamente com **Manter o secret anterior funcionando por 24 horas** desmarcado, para que o secret vazado pare de funcionar de imediato (se você já gerou um mantendo-o, clique em **Revogar agora**). Implemente o novo secret e remova o valor antigo de onde quer que tenha sido exposto (histórico do repositório, logs, tickets). Depois, verifique o que foi feito com a aplicação enquanto o secret era válido. **Uma API key**, ou um secret que foi usado para criar API keys que você não controla. Um novo client secret não para essas chaves. Para cortá-las antes que expirem, um Owner pode **desativar a aplicação** no Dashboard: enquanto estiver desativada, a API rejeita suas API keys e Connect Tokens, e `POST /auth` responde `401` com `CLIENT_DISABLED`. Tudo que usa a aplicação para. Se a aplicação tiver uma [lista de IPs permitidos](/docs/security/ip-allowlist), uma API key ou secret vazado só funciona dos IPs nela, o que lhe dá tempo. Isso não substitui a rotação do secret. Desativar não revoga uma API key: bloqueia a aplicação. Quando você a habilita novamente, cada API key que ainda não expirou funciona novamente, incluindo uma vazada. Gere um novo client secret enquanto a aplicação estiver desativada e habilite-a apenas após as API keys criadas antes da rotação terem expirado. ## Não protege contra - Um secret roubado de um servidor que você controla: a rotação limita quanto tempo ele permanece útil, mas seu gerenciador de segredos e acesso ao servidor são seus para proteger. - Uma API key em código de front-end: rotacionar o secret não a revoga. Mantenha as chaves no servidor. Próximo: [Lista de IPs permitidos](/docs/security/ip-allowlist). ## Connect Tokens Source: https://docs.pluggy.ai/pt/docs/security/connect-tokens.md Browsers e aplicativos móveis não são um lugar seguro para um secret: qualquer coisa enviada para eles pode ser lida. Portanto, o front end nunca recebe seu client secret ou uma chave da API. Ele recebe um **Connect Token**, uma credencial de curta duração que seu backend cria para um usuário e uma conexão. ## Emita-o do seu backend, para um usuário autenticado 1. Seu servidor cria uma chave da API com `POST /auth` (veja [Credenciais](/docs/security/credentials)). 2. Seu servidor cria um Connect Token com [`POST /connect_token`](/reference/connect-token-create), de um endpoint que apenas seus **usuários autenticados** podem chamar. 3. O front end recebe o Connect Token e abre [Pluggy Connect](/docs/connect-widget/introduction) com ele. Proteja esse endpoint com sua própria autenticação. Qualquer um que puder chamá-lo pode abrir o Pluggy Connect em seu nome e conectar contas à sua aplicação. Receita: [Emitir Connect Tokens do seu backend](/recipes/issue-connect-tokens-from-your-backend). Detalhes: [Autenticação do Pluggy Connect](/docs/connect-widget/authentication). ## O que um Connect Token pode acessar - Os Itens criados com esse token, através de [`GET /items/{id}`](/reference/items-retrieve), e uma visão reduzida de suas contas, através de `GET /accounts?itemId=`. - Nada criado com outro Connect Token. - Nenhum dado de produto: transações, investimentos, identidade e qualquer outro produto requer uma chave da API. Um Connect Token recebe `403 Forbidden`. Portanto, um Connect Token que vaza expõe no máximo as conexões feitas com ele, e apenas até que expire. ## Quanto tempo dura Um Connect Token é válido por **30 minutos**. Crie um novo para cada conexão em vez de armazená-lo em cache ou compartilhá-lo entre usuários. Enquanto uma aplicação estiver [desativada](/docs/security/credentials#if-a-credential-leaks), seus Connect Tokens também serão rejeitados. ## Opções que importam para a segurança As opções vão dentro de `options` no corpo de `POST /connect_token`; uma propriedade enviada na raiz é ignorada. Veja [Configurando um Connect Token](/docs/authentication#configuring-a-connect-token). | Opção | O que fazer | | --- | --- | | `clientUserId` | Defina como um identificador opaco do seu sistema, não um endereço de e-mail ou um CPF. Ele é armazenado no Item e enviado em cada payload de webhook `item/*`. | | `itemId` (na raiz) | Escopo o token para um Item existente, para atualizá-lo. Verifique se o Item pertence ao usuário autenticado antes de criar o token. Veja [Atualizando um Item](/docs/connect-widget/updating-item). | | `webhookUrl` | Deve ser uma URL pública HTTPS. Não envia cabeçalhos personalizados, então proteja-o com a [assinatura](/docs/developer-tools/webhook-security#4-verify-the-signature), ou use um webhook criado com `POST /webhooks` em vez disso. | | `oauthRedirectUri` | Deve ser HTTPS ou um link profundo para seu aplicativo. Veja [Guia de Suporte OAuth](/docs/connect-widget/oauth-support). | No widget, deixe `includeSandbox` desativado em produção: conectores Sandbox são para testes. Veja [Ambientes e Configurações](/docs/connect-widget/environments). ## Não protege contra - Um endpoint que emite Connect Tokens para qualquer um: o token é tão seguro quanto a autenticação à sua frente. - Atualizar o Item do usuário errado: a API escopo o token para o `itemId` que você passa, mas apenas seu backend sabe qual usuário possui qual Item. Próximo: [Segurança do webhook](/docs/developer-tools/webhook-security). ## Lista de IPs permitidos Source: https://docs.pluggy.ai/pt/docs/security/ip-allowlist.md Um segredo de cliente ou uma chave de API que vaza pode ser usado por qualquer pessoa que a possua, de qualquer lugar. Uma **lista de IPs permitidos** restringe isso: você lista os endereços IP dos quais seus servidores chamam o Pluggy, e a API recusa as credenciais dessa aplicação de qualquer outro endereço. A lista de permitidos é opcional e desativada por padrão. Uma aplicação sem uma aceita solicitações de qualquer IP, como sempre fez. ## Como funciona Cada aplicação tem sua própria lista. Quando a lista não está vazia, a API verifica o IP público de cada solicitação: - `POST /auth`, que troca o ID do cliente e o segredo do cliente por uma chave de API, é aceito apenas de um IP listado. - Cada solicitação autenticada com uma chave de API dessa aplicação (`X-API-KEY`) é aceita apenas de um IP listado. Isso inclui a criação de um Connect Token com `POST /connect_token`. Uma solicitação de qualquer outro IP é recusada com `403` e `CLIENT_IP_NOT_ALLOWED` (veja [O erro](#o-erro)). A mudança entra em vigor assim que você a salva. Solicitações autenticadas com um **Connect Token** não são verificadas. O Pluggy Connect roda nos navegadores e telefones dos seus usuários, cujos IPs você não pode conhecer, então o widget continua funcionando onde quer que seus usuários estejam. ## O que é e o que não é restrito | Solicitação | Restrito pela lista de permitidos | | --- | --- | | `POST /auth` com o ID do cliente e o segredo do cliente da aplicação | Sim | | Qualquer solicitação com uma chave de API da aplicação em `X-API-KEY` | Sim | | `POST /connect_token` (é chamado com uma chave de API) | Sim | | Solicitações feitas com um Connect Token, incluindo Pluggy Connect | Não | | Um Connect Token que já foi emitido | Não: continua funcionando até expirar | | O [Dashboard](https://dashboard.pluggy.ai) | Não: você pode sempre editar ou remover a lista lá | ## Configure Apenas `OWNER`s e `ADMIN`s de uma equipe podem editar a lista. `MEMBER`s a veem como somente leitura (veja [Acesso à equipe](/docs/security/team-access)). 1. Abra o [Dashboard](https://dashboard.pluggy.ai), vá para **Aplicações** e abra a aplicação. 2. Encontre o cartão **IPs Permitidos**, entre as credenciais e os webhooks. Ele está disponível para cada aplicação, em desenvolvimento e em produção. 3. Adicione os IPs públicos dos quais seus servidores chamam o Pluggy: endereços únicos ou intervalos CIDR, IPv4 ou IPv6. Você pode colar vários de uma vez, separados por vírgulas, espaços ou novas linhas. 4. Salve e confirme. A lista se aplica imediatamente, então certifique-se de que todos os servidores que usam as credenciais dessa aplicação estejam nela antes de confirmar. Para desativar a restrição, use **Remover restrição** no mesmo cartão. A lista é limpa e a aplicação aceita qualquer IP novamente. ### O que você pode listar | Regra | Detalhe | | --- | --- | | Formatos | Endereços IPv4 ou IPv6, ou intervalos CIDR: `203.0.113.10`, `198.51.100.0/24`, `2001:db8::/32`. | | Tamanho | Até 50 entradas por aplicação. | | Não aceito | Intervalos `/0` (`0.0.0.0/0`, `::/0`): eles permitiriam todos os endereços. | | Duplicatas | Eliminadas. | | Normalização | A lista armazenada é normalizada: um intervalo escrito com bits de host definidos é salvo como seu endereço de rede, então `10.0.0.5/8` é armazenado como `10.0.0.0/8`. | Cada alteração na lista é registrada no log de atividades da sua equipe, com quem a fez. ## Qual IP listar A API vê o IP **público** do qual sua solicitação chega ao Pluggy, não o endereço da máquina que a fez. - Se seus servidores saem para a internet através de um gateway NAT, um proxy ou a saída do seu provedor de nuvem, liste os IPs de saída (por exemplo, um IP estático ou elástico do gateway NAT). - Endereços privados (`10.x`, `172.16.x`–`172.31.x`, `192.168.x`) nunca chegam ao Pluggy, então listá-los não tem efeito. - Se seus servidores não têm um IP público fixo, configure um antes de ativar a lista de permitidos. Com um endereço que muda, a próxima alteração bloqueia seus servidores. Para encontrar o IP de saída, chame um serviço de eco de IP do próprio servidor ou verifique os IPs estáticos do seu gateway NAT ou proxy no console do seu provedor de nuvem. ## O erro Uma solicitação de um IP que não está na lista recebe: ```json { "code": 403, "codeDescription": "CLIENT_IP_NOT_ALLOWED", "message": "O endereço IP da solicitação não está na lista de IPs permitidos configurados para esta aplicação." } ``` Baseie-se em `codeDescription`, não em `message`. Tentar novamente do mesmo IP retorna o mesmo erro: a solução é chamar de um IP listado ou adicionar o IP à lista. Veja também [Códigos de erro](/reference/error-codes#authentication-and-access). ## Boa prática - **Use IPs de saída estáticos.** Uma lista de permitidos é tão estável quanto os endereços nela. - **Adicione o novo IP antes de migrar.** Quando você se mudar para uma nova região, conta de nuvem ou gateway NAT, adicione seus IPs primeiro, implemente e remova os antigos apenas depois que o tráfego tiver mudado. - **Uma aplicação por ambiente, uma lista por aplicação.** Seus servidores de CI ou staging usam sua própria aplicação com sua própria lista, então a lista de produção permanece curta. Veja [Credenciais e chaves de API](/docs/security/credentials#separate-development-production-and-tenants). - **Combine com as outras camadas.** Uma lista de permitidos limita onde uma credencial vazada funciona; não substitui manter segredos fora do código e rotacioná-los ([Rotacionar o segredo do cliente](/docs/security/credentials#rotate-the-client-secret)), nem verificar seus webhooks ([Segurança do webhook](/docs/developer-tools/webhook-security)). ## Solução de problemas ### Estou recebendo `403 CLIENT_IP_NOT_ALLOWED` A aplicação tem uma lista de permitidos e a solicitação veio de um IP que não está nela. Encontre o IP público do qual o servidor realmente sai (veja [Qual IP listar](#qual-ip-listar)), e peça a um `OWNER` ou `ADMIN` para adicioná-lo no cartão **IPs Permitidos**. As causas usuais são um novo servidor, uma mudança de gateway NAT ou região, uma implantação em uma plataforma sem IPs de saída fixos, ou um script executado de um laptop. ### Qual IP eu listarei? O IP público do qual seus servidores alcançam o Pluggy: o IP de saída do seu gateway NAT, proxy ou rede de nuvem, não um endereço privado. Veja [Qual IP listar](#qual-ip-listar). ### Isso afeta o widget Connect? Não. Solicitações feitas com um Connect Token não são restritas, então o Pluggy Connect continua funcionando de qualquer dispositivo do usuário. Criar o Connect Token é restrito: seu backend chama `POST /connect_token` com uma chave de API, então precisa ser executado de um IP listado. ### Eu me bloqueei O Dashboard nunca é bloqueado pela lista de permitidos. Um `OWNER` ou `ADMIN` pode abrir a aplicação, adicionar o IP ausente ou usar **Remover restrição**, e a mudança se aplica imediatamente. ### Isso é o mesmo que permitir os IPs do webhook do Pluggy? Não, é a direção oposta. Esta página restringe quem pode chamar a API do Pluggy com suas credenciais. Para aceitar notificações de webhook apenas do Pluggy, veja [Permitir apenas os IPs de origem do Pluggy](/docs/developer-tools/webhook-security#2-allow-only-pluggys-source-ips). ## Não protege contra - Uma credencial usada de um dos seus próprios servidores listados: se um atacante controla uma máquina na lista, a lista de permitidos não os impede. - Um Connect Token que vaza: Connect Tokens não são restritos por IP. Eles têm vida curta e escopo limitado, veja [Connect Tokens](/docs/security/connect-tokens). Próximo: [Connect Tokens](/docs/security/connect-tokens). ## Acesso da equipe Source: https://docs.pluggy.ai/pt/docs/security/team-access.md Os membros da sua equipe gerenciam as aplicações que contêm suas credenciais, então quem está na equipe e com qual função faz parte da sua segurança. Uma equipe tem três funções: `OWNER`, `ADMIN` e `MEMBER`. ## O que cada função pode fazer | Ação no Dashboard | `OWNER` | `ADMIN` | `MEMBER` | | --- | :-: | :-: | :-: | | Ver aplicações e listar seus webhooks | Sim | Sim | Sim | | Criar aplicações e editar seu nome, descrição e origens | Sim | Sim | Não | | Gerar um novo secret de cliente | Sim | Sim | Não | | Editar ou remover a [lista de IPs permitidos](/docs/security/ip-allowlist) de uma aplicação (membros veem como somente leitura) | Sim | Sim | Não | | Criar, atualizar e deletar webhooks | Sim | Sim | Não | | Definir os cabeçalhos personalizados de um webhook | Sim | Não | Não | | Gerar, regenerar ou remover o secret de assinatura do webhook | Sim | Não | Não | | Habilitar ou desabilitar uma aplicação | Sim | Não | Não | | Deletar uma aplicação | Sim | Não | Não | | Alterar a customização do Pluggy Connect | Sim | Sim | Não | | Convidar membros, mudar suas funções e removê-los | Sim | Sim, exceto `OWNER`s | Não | | Tornar alguém um `OWNER` | Sim | Não | Não | | Ver faturamento e enviar a devida diligência | Sim | Sim | Não | | Deletar a equipe | Sim | Não | Não | Um `ADMIN` pode convidar e gerenciar `ADMIN`s e `MEMBER`s, mas não pode convidar ou promover ninguém a `OWNER`, e não pode mudar a função de um `OWNER` existente ou remover um. Essas regras se aplicam ao Dashboard. Qualquer pessoa que possua o secret de cliente da aplicação ou uma chave da API pode fazer tudo que a API permite, independentemente de sua função: veja [Credenciais](/docs/security/credentials). ## Menor privilégio - **Dê `OWNER` a poucas pessoas.** Um `OWNER` pode desabilitar e deletar aplicações, gerenciar o secret de assinatura do webhook e conceder `OWNER` a outros. - **Dê `ADMIN` às pessoas que operam a integração.** Um `ADMIN` pode gerar um novo secret de cliente e, com isso, ler o novo secret. - **Todos os outros são `MEMBER`.** Um `MEMBER` pode acompanhar a integração no Dashboard sem mudar aplicações, secrets ou webhooks. - **Mantenha pelo menos dois `OWNER`s** se sua equipe deve sobreviver à saída de uma pessoa. Uma equipe cujo último `OWNER` fecha sua conta Pluggy é deletada junto com ela; veja [Deletando sua conta Pluggy](/docs/get-started/delete-account). ## Quando alguém sai 1. **Remova-o da equipe** no Dashboard. Para remover um `OWNER`, outro `OWNER` precisa fazer isso. 2. **Rotacione o secret de cliente** de cada aplicação cujo secret eles poderiam ter visto: um `OWNER` ou `ADMIN` que gerou um, ou qualquer um que pudesse ler seu gerenciador de secrets. Remover um membro não altera as credenciais da aplicação. Desmarque **Manter o secret anterior funcionando por 24 horas** se eles ainda puderem usar o secret antigo. Veja [Rotacionar o secret de cliente](/docs/security/credentials#rotate-the-client-secret). 3. **Regenerar o secret de assinatura do webhook** e o secret nos cabeçalhos dos seus webhooks se eles tiveram acesso a eles. Veja [Rotacionando o secret](/docs/developer-tools/webhook-security#rotating-the-secret). As chaves da API criadas antes de uma rotação continuam funcionando até expirarem. Se você precisar cortá-las antes, veja [Se uma credencial vazar](/docs/security/credentials#if-a-credential-leaks). ## Não protege contra - Um secret copiado do Dashboard: as funções controlam quem pode gerar ou alterá-lo, não para onde ele vai depois. - Acesso através da API: é governado por suas credenciais, não por funções da equipe. Próximo: [Proteção de dados](/docs/security/data-protection). ## Proteção de dados Source: https://docs.pluggy.ai/pt/docs/security/data-protection.md Os dados financeiros dos seus usuários chegam aos seus sistemas através do Pluggy. O que o Pluggy armazena para cada Item e quando o exclui está documentado abaixo com links para os detalhes. O que você copia para seus próprios sistemas é sua responsabilidade proteger. ## Mantenha credenciais bancárias fora dos seus servidores Com [Pluggy Connect](/docs/connect-widget/introduction), seus usuários digitam suas credenciais bancárias no widget, que as envia para o Pluggy com o Connect Token: elas nunca passam pelo seu backend. Prefira isso a construir seu próprio formulário de credenciais. Se você coletar credenciais em sua própria interface e criar Itens através da API, criptografe os `parameters` com a chave pública RSA da sua aplicação, que você obtém do Pluggy: apenas o Pluggy pode descriptografá-los. Receita: [Criptografar parâmetros](/recipes/encrypt-parameters). ## O titular da conta dá o consentimento A pessoa que autoriza uma conexão é o titular da conta, no ambiente de sua própria instituição. Uma empresa que atende outras empresas não pode autorizar em nome delas. Veja [O consentimento permanece com o titular da conta](/docs/get-started/multi-tenant-applications#the-consent-stays-with-the-account-holder). Quando um consentimento expira ou o usuário o revoga, os endpoints de dados do Item retornam dados vazios. Apenas o usuário pode renová-lo, conectando-se novamente. Veja [Consentimentos e expiração](/docs/connections/consents#consent-expiration--revocation). ## Deixe os usuários desconectar Dê aos seus usuários uma maneira de desconectar uma conta a qualquer momento e exclua o Item quando o fizerem, com [`DELETE /items/{id}`](/reference/items-delete) do seu backend. Excluir um Item: - apaga suas credenciais armazenadas, - revoga o consentimento de Open Finance, onde se aplica, e expira autorizações OAuth, - exclui permanentemente seus dados (contas, transações e o resto). Depois disso, o Item e seus produtos respondem `404`. Veja [Gerenciamento de consentimento](/docs/integration-checklist/consent-management) e a receita [Excluindo seus Dados](/recipes/deleting-your-data). ## Reaja quando o Pluggy excluir um Item O Pluggy também exclui Itens por conta própria, por exemplo, Itens Sandbox não utilizados por 30 dias, e cada Item de um conector 30 dias após o conector ser descontinuado. Cada exclusão emite o webhook `item/deleted`. Inscreva-se nele e remova sua cópia dos dados quando chegar. Veja [Retenção de dados e limpeza automática](/docs/connections/item-lifecycle#data-retention-and-automatic-cleanup). ## Armazene apenas o que você usa - **Mantenha o que seu produto precisa**, e exclua-o quando o usuário sair ou desconectar. Sua chave da API pode ler os dados novamente enquanto o Item existir. - **Use identificadores opacos.** Defina `clientUserId` como um id interno, não um endereço de e-mail ou um CPF: ele é armazenado no Item e enviado nos payloads do webhook. - **Mantenha dados pessoais fora de logs e relatórios de erro.** Dados financeiros e campos de identidade (nomes, CPF ou CNPJ, números de conta) não pertencem a uma linha de log, um evento de análise ou um ticket de suporte. - **Restrinja quem pode lê-los** em seus próprios sistemas, da mesma forma que você restringe quem pode ler seu segredo de cliente. ## Solicitações de proteção de dados Uma solicitação de um **usuário final** para acessar, corrigir ou apagar seus dados vai para o produto pelo qual se conectaram, que possui a conexão: isso é você. Exclua seus Itens para remover os dados que o Pluggy possui para eles. Solicitações sobre seus **próprios** dados pessoais como cliente do Pluggy vão para o Encarregado de Proteção de Dados do Pluggy. Veja [Solicitações de proteção de dados (LGPD)](/docs/get-started/delete-account#data-protection-requests-lgpd). ## Não protege contra - Cópias que você fez: excluir um Item remove os dados do Pluggy, não o que seus sistemas armazenaram. Essa parte é sua responsabilidade. Próximo: [Checklist de visão geral de segurança](/docs/security/overview#checklist). ## 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 de autorização de dispositivo) 2. Fluxo básico para Negócios 3. MFA 1 etapa 4. MFA 2 etapas 5. Contas conjuntas (fluxo 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 de 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_CREDITO: { "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á tem 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 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 de autorização de dispositivo) Este é um caso especial que emula um conector que requer que o usuário autorize um dispositivo. 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 instituição. 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 instituição (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á tem 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 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 no mesmo passo das credenciais. - Se o usuário selecionar **"Conta conjunta"**, será solicitado apenas que forneça 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 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 (tipicamente 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 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**. ![Página de Customização, aba Conectores](/docs/images/dashboard/customization-connectors-tab.png) 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. ![Buscando um conector e ativando-o](/docs/images/dashboard/customization-connector-search.png) 5. Use **Prévia** à 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**. ![Página Demo com o botão Conectar Conta](/docs/images/dashboard/demo-connect-account.png) 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*. ![Pluggy Connect aberto a partir do Dashboard](/docs/images/dashboard/demo-widget.png) ## 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. ![Detalhe do Item com o botão de copiar itemId](/docs/images/dashboard/demo-item-id.png) 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** é mostrado **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 secrets 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. Com **Manter o secret anterior funcionando por 24 horas** marcado (o padrão), o secret anterior continua funcionando por 24 horas enquanto você atualiza cada integração que o utiliza; desmarcado, ele para de funcionar imediatamente. Veja [Rotacionar o client secret](/docs/security/credentials#rotate-the-client-secret). 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 que um Owner ou Admin gere um novo; essa rotação não mantém o secret anterior funcionando. ## 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** está ativado: **Customização → Conectores**, pesquise `MeuPluggy` e abra a aba **Conectores Diretos** do grupo *Pessoal* ([como](/docs/guides/dashboard-connectors#1-choose-which-connectors-pluggy-connect-shows)). 3. Abra **Aplicações → sua aplicação → 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. ![Escolhendo o conector MeuPluggy no Pluggy Connect](/docs/images/dashboard/meupluggy-connector.png) 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 do banco 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 da sua aplicação. O Client Secret é mostrado apenas uma vez, quando é gerado — se você não o armazenou, gere um novo na página da aplicação ([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 sua aplicação a ler as conexões que você tem lá. Essa autorização é o que os itens MeuPluggy leem através dela, 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 → sua aplicação → 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 Para um problema com sua conta ou uma de suas conexões, escreva para [meu-suporte@pluggy.ai](mailto:meu-suporte@pluggy.ai) do e-mail da sua conta do Meu Pluggy. Perguntas sobre uso pessoal vão para o mesmo endereço. ## 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.