# Sandbox 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 são atualizadas diariamente e teste todas as possíveis conexões válidas e fluxos errôneos. > **Aviso** > > Todos os itens do sandbox que não forem atualizados por mais de **30 dias** serão excluídos sem possibilidade de recuperação no futuro. **Você encontrará diferentes fluxos:** 1. Fluxo básico (também incluímos um fluxo especial da Caixa) 2. Fluxo básico para Negócios 3. MFA 1 etapa 4. MFA 2 etapas 5. Contas conjuntas (fluxo 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": "416.799.495-00", "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 outros lugares. ``` ### 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 > **Nota** > > 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 isso no campo de erro do item `providerMessage`. | | `CONNECTION_ERROR` | `user-connection-error` | Houve um erro de conexão interno com o provedor (ou seja, problema de Proxy). | | `INVALID_CREDENTIALS` | qualquer outra coisa | As credenciais de usuário/senha eram inválidas. | | `PARTIAL_SUCCESS` | `user-ok-account-error` | Erro ao recuperar o produto da conta. | | `SUCCESS` com avisos | `user-ok-account-warning` | Aviso no produto da conta. | | `ACCOUNT_CREDENTIALS_RESET` | `user-account-credentials-reset` | O usuário precisa atualizar algumas de suas credenciais na instituição. | | `USER_NOT_SUPPORTED` | `user-not-supported` | O usuário não tem permissão para realizar login na instituição através da Pluggy. | | `SUCCESS` com dados de duas contas correntes | `user-ok-two-checking-accounts` | Sucesso, mas retorna um exemplo de duas contas correntes. | ### Ampliar dados de resultado Nos casos em que é necessário testar grandes quantidades de transações no resultado, você pode usar o nome de usuário `user-ok-perf` ou `user-ok-perf-XXx` para recriar essa situação. `XX` representa o multiplicador para o número de transações a serem recuperadas. Por exemplo, se você escolher 1000 como XX, o nome de usuário resultante seria `user-ok-perf-1000x`, a fim de multiplicar o resultado por esse número. O limite desse multiplicador é 5000, então se você usar um número maior, o multiplicador será apenas 5000. ### Fluxo Básico | Status de Autorização Pendente (fluxo da Caixa) Este é um caso especial que emula o fluxo da Caixa. Consiste em três possíveis status de execução a serem retornados. Quando um usuário se conecta pela primeira vez, a execução esperada retornada será para confirmar o dispositivo do usuário mostrado (ou seja, "1234-5678"). Assim, a primeira execução (após o usuário confirmar o dispositivo do lado dele) retornará `USER_AUTHORIZATION_PENDING` e uma mensagem que informa o tempo que o usuário deve esperar até que a autorização seja concedida pela Caixa. Uma vez que esta etapa é concluída, existem dois cenários possíveis: 1. Se o usuário atualizar o item dentro do tempo a ser aguardado, o resultado da execução será `USER_AUTHORIZATION_NOT_GRANTED` e uma mensagem para lembrar o tempo a ser aguardado até que a autorização seja concedida pela Caixa (no caso do Sandbox, o tempo é de 2 minutos). 2. Se o usuário atualizar o item após o tempo de espera, os dados da conta serão recuperados com sucesso e o relatório de execução será `SUCCESS`. Veja a tabela abaixo para mais detalhes: | Status de execução | Nome de usuário | Descrição | |---|---|---| | `USER_AUTHORIZATION_PENDING` | `user-ok-auth-pending` | Isso reportará um status `USER_AUTHORIZATION_PENDING`, e uma mensagem para esperar 2 minutos até que a instituição conceda autorização. Então, você pode atualizar o item para recuperar os dados após esses 2 minutos, ou obter uma mensagem de autorização ainda não concedida (por favor, leia as próximas linhas). | | `USER_AUTHORIZATION_NOT_GRANTED` | reutilizar credenciais (atualizar) | Se o item for atualizado antes que a instituição conceda autorização, o status reportado será `USER_AUTHORIZATION_NOT_GRANTED` e você será solicitado a esperar novamente os 2 minutos após a primeira execução. | | `SUCCESS` | reutilizar credenciais (atualizar) | Se o item for atualizado uma vez que a autorização da instituição for concluída, então os dados devem ser recuperados e o relatório de status será `SUCCESS`. | ## 3- MFA 1 etapa | Cenário | Nome de usuário | MFA | Descrição | |---|---|---|---| | Login Ok | `user-ok` | `123456` | Conexão bem-sucedida. | | `INVALID_CREDENTIALS_MFA` | `user-ok` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. | ## 4- MFA 2 etapas | Cenário | Nome de usuário | MFA | Descrição | |---|---|---|---| | Login Ok | `user-ok` | `123456` | Conexão bem-sucedida. | | `INVALID_CREDENTIALS_MFA` | `user-ok` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. | | Login Ok (MFA com imagem QR) | `user-ok-img` | `123456` | Conexão bem-sucedida. | | `INVALID_CREDENTIALS_MFA` (MFA com imagem QR) | `user-ok-img` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. | | Login Ok (MFA com opções para selecionar) | `user-ok-select` | qualquer | Conexão bem-sucedida. | | Login OK (com seleção de telefone antes do MFA) | `user-ok-phone` | `123456` | Conexão bem-sucedida. | | `INVALID_CREDENTIALS_MFA` (com seleção de telefone antes do MFA) | `user-ok-phone` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. | | Login Ok (com seleção de empresa após o MFA) | `user-ok-multi-company` | `123456` | Conexão bem-sucedida. | | `INVALID_CREDENTIALS_MFA` | `user-ok-multi-company` | ≠ `123456` | O parâmetro MFA fornecido estava incorreto. | | `UNEXPECTED_ERROR` | `user-ok-mfa-error` | `123456` | O conector teve um erro aleatório. | | `ACCOUNT_LOCKED` | `user-ok-mfa-locked` | `123456` | A conta do usuário está bloqueada, precisa de ação manual para ser desbloqueada. | | `SITE_NOT_AVAILABLE` | `user-ok-mfa-unavailable` | `123456` | O site do provedor não estava disponível. | | `CONNECTION_ERROR` | `user-ok-mfa-connection-error` | `123456` | Houve um erro de conexão interno com o provedor (ou seja, problema de Proxy). | | `ALREADY_LOGGED_IN` | `user-ok-mfa-logged` | `123456` | O usuário já 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/developer-tools/connect-account), o usuário será apresentado para escolher primeiro entre uma "Conta única" ou uma "Conta conjunta". - Se o usuário selecionar **"Conta única"**, ele será solicitado a fornecer credenciais bancárias e MFA no mesmo passo das credenciais. - Se o usuário selecionar **"Conta conjunta"**, ele será solicitado apenas a fornecer credenciais bancárias. Em seguida, será perguntado qual conta deseja conectar, e depois disso, o MFA será necessário. Se o MFA estiver correto, a conta será conectada com sucesso. ### 2- Testando via Postman - Ao testar "conta única", a solicitação é a mesma que a MFA 1 etapa do sandbox. As credenciais bancárias e o MFA são enviados juntos. - Ao testar "conta conjunta", você deve incluir um parâmetro de MFA 1 etapa, com o valor simulado: `000000`. Note que isso é o mesmo que o fluxo do widget Connect. Quando o usuário seleciona o fluxo "conta conjunta", a interface do usuário 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: `ralph.bragg@gmail.com` - Senha: `P@ssword01` ### Como funciona o fluxo de autorização múltipla (múltipla alçada)? Esse fluxo simula um cenário onde, para recuperar os 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.