Sandbox

O Sandbox da Malvo reproduz o ciclo de vida de um Item sem conectar contas reais e sem gerar cobrança. Ele inclui conectores mockados locais e pode incluir conectores AIS internacionais quando essa modalidade está habilitada no ambiente SANDBOX.

O Sandbox usa o mesmo host https://api.malvo.io; o isolamento vem de uma aplicação Malvo com environment: SANDBOX e seu próprio clientId/clientSecret. Não há subdomínio ou base URL de API separados.

Opt-in: como ligar o Sandbox

Uma aplicação SANDBOX enxerga somente conectores com isSandbox: true. Em listagens feitas com uma aplicação de produção, os mocks locais ficam ocultos por padrão e podem ser incluídos explicitamente para desenvolvimento. Os conectores PJ de Open Finance (8 e 20–22) são a exceção: só funcionam em aplicações SANDBOX, veja Empresas (PJ).

Onde	Como ativar
`GET /connectors` (server-side)	Parâmetro de query `sandbox=true`
Connect Widget	Opção de configuração `includeSandbox: true`

curl "https://api.malvo.io/connectors?sandbox=true" \
  -H "X-API-KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const connect = new MalvoConnect({
  connectToken,
  includeSandbox: true,
});

Mantenha sandbox/includeSandbox desligado em produção. Os conectores de sandbox só devem aparecer em ambientes de teste e desenvolvimento.

Conectores mockados locais

A faixa de IDs 0–99 é reservada para conectores locais de sandbox. Os ativos são 0 a 8 (conectores Malvo), 10 a 19 (bancos brasileiros de pessoa física) e 20 a 22 (bancos brasileiros de pessoa jurídica). Todos têm isSandbox: true.

ID	Nome	Tipo de fluxo	`type`	`isOpenFinance`
0	Malvo Bank	Fluxo básico (user/pass + 1 campo de MFA)	`PERSONAL_BANK`	false
1	Malvo Bank Caixa-style	Fluxo básico, variante Caixa	`PERSONAL_BANK`	false
2	Malvo Bank Business	Conta empresarial legada (user/pass); gera dados de empresa, veja Empresas (PJ)	`BUSINESS_BANK`	false
3	Malvo Bank MFA-1	MFA de fator único (token no formulário inicial, credencial `mfa: true`)	`PERSONAL_BANK`	false
4	Malvo Bank MFA-2	MFA em dois passos (QR + seleção; pausa em `WAITING_USER_INPUT`)	`PERSONAL_BANK`	false
5	Malvo Bank Joint	Contas conjuntas (estilo “Conta Conjunta”)	`PERSONAL_BANK`	false
6	Malvo Bank QR	Login via QR	`PERSONAL_BANK`	false
7	Malvo Bank Open Finance	Fluxo Open Finance (só CPF → redirect OAuth para banco mock)	`PERSONAL_BANK`	true
8	Malvo Bank Empresas Open Finance	Fluxo Open Finance de empresa (CNPJ + CPF do representante → redirect)	`BUSINESS_BANK`	true

Os conectores 0–6 usam um fluxo de credenciais no campo parameters do POST /items — apenas para exercitar cenários de teste (MFA, conta conjunta, QR etc.) no sandbox. Os conectores 7 (pessoa física) e 8 (empresa) simulam o fluxo de redirecionamento do Open Finance, que é como todas as conexões de produção funcionam.

Credenciais default

Use estes valores para todos os conectores de fluxo básico:

Campo	Valor
Password	`password-ok`
MFA token	`123456`

Qualquer password diferente de password-ok resulta em INVALID_CREDENTIALS → LOGIN_ERROR. Qualquer MFA token diferente de 123456 resulta em INVALID_CREDENTIALS_MFA.

Gatilhos por username

O username enviado controla o desfecho da execução. É assim que você reproduz, sob demanda, cada estado terminal do Item.

Username	Desfecho
`user-ok`	Conexão bem-sucedida → `UPDATED` / `SUCCESS`
`user-locked`	`LOGIN_ERROR` com `executionStatus: ACCOUNT_LOCKED`
`user-unavailable`	`OUTDATED` com `executionStatus: SITE_NOT_AVAILABLE`
`user-error`	`OUTDATED` com `executionStatus: ERROR`
`user-ok-perf-XXx`	Sucesso com XX× o volume normal de transações (máx. `5000x`) — para testes de carga

Testar uma conexão no sandbox

Liste os conectores de sandbox

Chame GET /connectors?sandbox=true para ver os conectores de sandbox e escolher o fluxo que quer testar.

curl "https://api.malvo.io/connectors?sandbox=true" \
  -H "X-API-KEY: <apiKey>"

Crie um Item com as credenciais de teste

Use o gatilho user-ok com a password default para uma conexão bem-sucedida no conector 0.

curl -X POST "https://api.malvo.io/items" \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": 0,
    "parameters": { "user": "user-ok", "password": "password-ok" },
    "products": ["ACCOUNTS", "TRANSACTIONS"]
  }'

Responda ao MFA, se houver

Em conectores de MFA de duas etapas (ex. 4), o Item pausa em WAITING_USER_INPUT. Leia item.parameter para saber o campo esperado e envie o token default.

curl -X POST "https://api.malvo.io/items/{id}/mfa" \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "token": "123456" } }'

Faça polling até o estado final

Consulte GET /items/{id} (ou consuma webhooks) até o status sair de UPDATING/LOGIN_IN_PROGRESS. Com user-ok, o Item chega a UPDATED / SUCCESS e você já pode ler contas e transações.

Reproduza erros à vontade

Repita a criação trocando o username (user-locked, user-unavailable, user-error) para exercitar os caminhos de recuperação da sua integração.

Sandbox de Open Finance (conector 7)

O conector 7 simula o fluxo regulado de Open Finance, com redirecionamento e consentimento:

Informe apenas o CPF

O conector 7 não pede user/password no formulário inicial — apenas o CPF.

curl -X POST "https://api.malvo.io/items" \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": 7,
    "parameters": { "cpf": "12345678901" },
    "oauthRedirectUri": "https://your.app/oauth/callback"
  }'

Autorize no banco mock

O usuário é redirecionado para a página de login de um banco mock. Use as credenciais do banco mock:

Campo	Valor
E-mail	`test@malvo.io`
Password	`P@ssword01`

Volte pelo oauthRedirectUri

Após autorizar, o usuário é redirecionado de volta pelo oauthRedirectUri, o Item executa e chega a UPDATED. O fluxo exercita o consentimento completo: autorizar → redirect → executar.

Empresas (PJ)

Os conectores de empresa geram um dataset de pessoa jurídica: identidade com CNPJ e sócios, conta corrente empresarial e movimentações B2B com contrapartes estáveis, para você validar folha de pagamento, pagamento de fornecedores, recebimentos e conciliação antes de ir para produção.

Conectores PJ

ID	Nome	`isOpenFinance`	Credenciais	`products`
8	Malvo Bank Empresas Open Finance	true	`cnpj` + `cpf`	ACCOUNTS, TRANSACTIONS, CREDIT_CARDS, IDENTITY, INVESTMENTS, LOANS
20	Itaú Empresas	true	`cnpj` + `cpf`	ACCOUNTS, TRANSACTIONS, CREDIT_CARDS, IDENTITY, LOANS
21	Bradesco Empresas	true	`cnpj` + `cpf`	ACCOUNTS, TRANSACTIONS, CREDIT_CARDS, IDENTITY, LOANS
22	Banco do Brasil Empresas	true	`cnpj` + `cpf`	ACCOUNTS, TRANSACTIONS, CREDIT_CARDS, IDENTITY, LOANS
2	Malvo Bank Business (legado)	false	`user` + `password`	ACCOUNTS, TRANSACTIONS, CREDIT_CARDS, IDENTITY

Todos têm type: BUSINESS_BANK. Os conectores 8 e 20–22 pedem as mesmas credenciais dos conectores PJ de Open Finance de produção, com a mesma validação:

Credencial	Conteúdo	Validação
`cnpj`	CNPJ da empresa (`businessEntity` do consentimento)	`^\d{2}\.?\d{3}\.?\d{3}/?\d{4}-?\d{2}$` — “CNPJ deve ter 14 dígitos”
`cpf`	CPF do representante que autoriza em nome da empresa (`loggedUser`)	`^\d{3}\.?\d{3}\.?\d{3}-?\d{2}$` — “CPF deve ter 11 dígitos”

Sem cnpj ou sem cpf, POST /items responde 400 com codeDescription VALIDATION_ERROR e a mesma mensagem da produção, por exemplo Parameter cnpj is required.

curl -X POST "https://api.malvo.io/items" \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": 8,
    "parameters": { "cnpj": "11.222.333/0001-81", "cpf": "529.982.247-25" },
    "oauthRedirectUri": "https://your.app/oauth/callback"
  }'

Os conectores 8 e 20–22 só funcionam em aplicações SANDBOX. Com uma aplicação PRODUCTION, eles não aparecem em GET /connectors (nem com sandbox=true/includeSandbox=true), GET /connectors/{id} responde 404, e POST /items, PATCH /items/{id} (inclusive com connectorId de um deles), POST /items/{id}/refresh e o Connect Widget respondem 400 com codeDescription CONNECTOR_NOT_SUPPORTED. Nenhum Item é criado. Um Item desses conectores que já exista numa aplicação PRODUCTION não sincroniza mais: a execução falha sem gravar dados e o Item vai para OUTDATED com error.code CONNECTOR_NOT_SUPPORTED.

No Connect Widget, os conectores 8 e 20–22 seguem o mesmo redirect simulado do conector 7. O conector 2 aceita os mesmos gatilhos por username dos demais conectores de fluxo básico.

Credenciais de teste

Use CNPJs e CPFs sintéticos com dígitos verificadores válidos. Estes servem para qualquer conector PJ:

Uso	Valor
CPF do representante	`529.982.247-25`
CNPJ, empresa pequena (padrão)	`11.222.333/0001-81`
CNPJ, MEI	`11.222.333/9001-74`
CNPJ, empresa pequena	`11.222.333/9002-55`
CNPJ, empresa média	`11.222.333/9003-36`

O CNPJ informado vira o document da identidade e o taxNumber da conta. Se ele tiver dígitos verificadores inválidos, o sandbox usa um CNPJ válido gerado para o Item. O CPF informado aparece entre os sócios em relations.

Porte da empresa

O porte define o tamanho da empresa simulada. Ele é escolhido pela ordem do CNPJ (os quatro dígitos depois da barra) ou, no conector legado 2, pelo sufixo do user:

Porte	Ordem do CNPJ	`user` no conector 2	Funcionários	Fornecedores	Clientes
MEI	`9001`	`user-ok-mei`	0 a 1	3	8
Pequena (padrão)	`9002` ou qualquer outra	`user-ok`	8 a 12	6	16
Média	`9003`	`user-ok-media`	70 a 90	10	40

O porte também muda o volume diário de recebimentos e de vendas no cartão, o saldo médio, os valores de pró-labore, folha, fornecedores e empréstimos, e os tributos gerados.

Dados gerados

Tudo é determinístico por Item: os mesmos sócios, funcionários, fornecedores e clientes aparecem todo mês, com os mesmos documentos e dados bancários, e os ids seguem as regras de IDs estáveis.

Recurso	O que vem
Identidade	`companyName` e `fullName` com a razão social, `document`/`taxNumber` com o CNPJ formatado, `documentType: CNPJ`, `establishmentCode` (ordem do CNPJ), `establishmentName` (nome fantasia), endereço, telefone e e-mails `Work`, e `relations` com os sócios (`Partner`) e administradores (`Administrator`), cada um com nome e CPF. `birthDate` e `jobTitle` vêm `null`.
Conta	`CHECKING_ACCOUNT` “Conta Empresarial”, com `owner` igual à razão social e `taxNumber` igual ao CNPJ.
Cartão	Cartão corporativo com compras de empresa (combustível, software, passagens, hotel, papelaria, locadora), no mesmo ciclo de fatura dos demais conectores.
Empréstimos	Capital de giro (`CAPITAL_GIRO_PRAZO_VENCIMENTO_SUPERIOR_365_DIAS`), com parcelas mensais, e conta garantida (`CONTA_GARANTIDA`).
Investimentos	Só no conector `8`: o CDB da aplicação automática e um CDB empresarial.

Movimentações da conta

Seguem a convenção de sinal da conta: débito negativo, crédito positivo.

Movimentação	Quando	`operationType`	Descrição
Pró-labore	Até o 5º dia útil salarial: no último dia útil bancário do prazo	`TED`	`Pró-labore – <sócio>`
Folha de pagamento	Até o 5º dia útil salarial, um débito por funcionário: `PIX` no próprio 5º dia útil (inclusive sábado); `TED` no último dia útil bancário até ele	`PIX` ou `TED`	`Pagamento de salário – <funcionário>`
Adiantamento salarial	Dia 20, para parte dos funcionários	`PIX` ou `TED`	`Adiantamento salarial – <funcionário>`
Fornecedores	Todo mês, no mesmo dia por fornecedor	`BOLETO`, `TED` ou `PIX`	`Pagamento a fornecedor – <razão social>`
Recebimentos	Dias úteis	`PIX` ou `BOLETO`	`PIX recebido – <cliente>`, `Liquidação de boleto – <cliente>`
Adquirência	Dias úteis	`TED`	`Crédito de vendas no débito (D+1) – <Cielo, Stone, Rede ou PagSeguro>`, `Crédito de vendas no crédito (D+30) – …`, `Antecipação de recebíveis – …`
FGTS	Dia 20, no dia útil igual ou anterior	`PIX`	`FGTS – Guia do FGTS Digital (GFD)`, em todas as empresas com funcionários
Tributos	Dia 20 (e dia 25 e trimestrais na média), no dia útil igual ou anterior	`CONVENIO_ARRECADACAO`	MEI: `DAS – Simples Nacional (MEI)`; pequena: `DAS – Simples Nacional`; todas com funcionários: `DARF – Contribuição previdenciária (DCTFWeb)`; média: também `DARF – IRRF sobre salários`, `DARF – PIS`, `DARF – COFINS`, `DARF – IRPJ (lucro presumido)` e `DARF – CSLL (lucro presumido)`
Tarifas	Pacote no 1º dia útil; TED e liquidação de boleto a cada operação	`PACOTE_TARIFA_SERVICOS`, `TARIFA_SERVICOS_AVULSOS`	`Tarifa – Pacote de serviços PJ`, `Tarifa – TED`, `Tarifa – Emissão de boletos de cobrança`, `Tarifa – Liquidação de boleto`
Investimento automático	Fim do dia útil, conforme o saldo	`APLICACAO_FINANCEIRA`, `RESGATE_APLIC_FINANCEIRA`	`Aplicação automática – CDB DI`, `Resgate automático – CDB DI`
Distribuição de lucros	Último dia útil, quando há excedente aplicado	`TED`	`Distribuição de lucros – <sócio>`
Crédito	Na contratação e todo dia 10 (dia útil seguinte)	`OPERACAO_CREDITO`	`Liberação de crédito – Capital de giro <contrato>`, `Parcela capital de giro – <contrato> (n/N)`
Fatura do cartão	Dois dias antes do vencimento	`TRANSFERENCIA_MESMA_INSTITUICAO`	`Pagamento de fatura – Cartão corporativo`

Os valores de tributos são sintéticos: percentuais fixos sobre a folha e a receita do mês anterior, só para que a conciliação tenha lançamentos realistas. Eles não são cálculo tributário.

As parcelas de capital de giro têm o mesmo valor e o mesmo contractNumber do empréstimo em GET /loans. O pagamento da fatura tem o mesmo valor e data do payments da fatura em GET /bills.

`paymentData`

Toda movimentação PIX, TED ou BOLETO traz paymentData.payer e paymentData.receiver. Um dos lados é a própria empresa e o outro é a contraparte. Cada participante tem:

Campo	Conteúdo
`name`	Nome ou razão social
`documentNumber.type`	`CPF` ou `CNPJ`
`documentNumber.value`	Documento formatado (`000.000.000-00` ou `00.000.000/0000-00`), com dígitos verificadores válidos
`routingNumber` / `routingNumberISPB`	Código COMPE e ISPB do banco
`branchNumber` / `accountNumber`	Agência e conta

Boletos trazem paymentData.boletoMetadata com barcode (44 dígitos), digitableLine (47 dígitos) e baseAmount. Os tributos CONVENIO_ARRECADACAO (DAS e DARF) não têm payer nem receiver: trazem só boletoMetadata.barcode (44 dígitos) e digitableLine (48 dígitos) de arrecadação. A GFD do FGTS Digital é recolhida só por Pix (Portaria MTE nº 240/2024, art. 27). No sandbox, ela vem como PIX, sem boletoMetadata: o payer é a empresa e o receiver é a Caixa Econômica Federal, agente operador do FGTS, com CNPJ, COMPE e ISPB, sem agência e conta. Nenhuma guia ou pagamento real é gerado.

{
  "id": "<transactionId>",
  "accountId": "<accountId>",
  "description": "Pagamento de salário – Fernanda Martins Ferreira",
  "descriptionRaw": "Pagamento de salário – Fernanda Martins Ferreira",
  "currencyCode": "BRL",
  "amount": -3683.21,
  "date": "2026-09-05T10:00:00.000Z",
  "balance": 50145.09,
  "status": "POSTED",
  "type": "DEBIT",
  "operationType": "PIX",
  "paymentData": {
    "payer": {
      "documentNumber": { "type": "CNPJ", "value": "11.222.333/0001-81" },
      "name": "Indústria Têxtil Pereira Ltda",
      "accountNumber": "8939812-1",
      "branchNumber": "0843",
      "routingNumber": "999",
      "routingNumberISPB": "99999999"
    },
    "receiver": {
      "documentNumber": { "type": "CPF", "value": "701.080.831-79" },
      "name": "Fernanda Martins Ferreira",
      "accountNumber": "1156358-5",
      "branchNumber": "5479",
      "routingNumber": "001",
      "routingNumberISPB": "00000000"
    },
    "paymentMethod": "PIX"
  }
}

{
  "id": "<transactionId>",
  "accountId": "<accountId>",
  "description": "Pagamento a fornecedor – Nuvem Ribeiro Sistemas de Gestão Ltda",
  "descriptionRaw": "Pagamento a fornecedor – Nuvem Ribeiro Sistemas de Gestão Ltda",
  "currencyCode": "BRL",
  "amount": -850.08,
  "date": "2026-09-15T10:00:00.000Z",
  "balance": 47953.26,
  "status": "POSTED",
  "type": "DEBIT",
  "operationType": "BOLETO",
  "paymentData": {
    "payer": {
      "documentNumber": { "type": "CNPJ", "value": "11.222.333/0001-81" },
      "name": "Indústria Têxtil Pereira Ltda",
      "accountNumber": "8939812-1",
      "branchNumber": "0843",
      "routingNumber": "999",
      "routingNumberISPB": "99999999"
    },
    "receiver": {
      "documentNumber": { "type": "CNPJ", "value": "91.173.795/0001-95" },
      "name": "Nuvem Ribeiro Sistemas de Gestão Ltda",
      "accountNumber": "8372233-4",
      "branchNumber": "4133",
      "routingNumber": "001",
      "routingNumberISPB": "00000000"
    },
    "paymentMethod": "BOLETO",
    "boletoMetadata": {
      "digitableLine": "00193559657187129790061804639906315700000085008",
      "barcode": "00193157000000850083559671871297906180463990",
      "baseAmount": 850.08
    }
  }
}

{
  "id": "<transactionId>",
  "accountId": "<accountId>",
  "description": "FGTS – Guia do FGTS Digital (GFD)",
  "descriptionRaw": "FGTS – Guia do FGTS Digital (GFD)",
  "currencyCode": "BRL",
  "amount": -3598.24,
  "date": "2026-09-18T10:10:00.000Z",
  "balance": 46163.68,
  "status": "POSTED",
  "type": "DEBIT",
  "operationType": "PIX",
  "paymentData": {
    "payer": {
      "documentNumber": { "type": "CNPJ", "value": "11.222.333/0001-81" },
      "name": "Indústria Têxtil Pereira Ltda",
      "accountNumber": "8939812-1",
      "branchNumber": "0843",
      "routingNumber": "999",
      "routingNumberISPB": "99999999"
    },
    "receiver": {
      "documentNumber": { "type": "CNPJ", "value": "00.360.305/0001-04" },
      "name": "Caixa Econômica Federal",
      "routingNumber": "104",
      "routingNumberISPB": "00360305"
    },
    "paymentMethod": "PIX"
  }
}

Os nomes, documentos e valores dos exemplos variam de Item para Item. Os documentos são sintéticos e não pertencem a pessoas ou empresas reais, exceto os CNPJs públicos das adquirentes.

Dias úteis

Os tributos, os fornecedores, os recebimentos e as tarifas seguem os dias úteis bancários: não caem em sábados, domingos, feriados nacionais (inclusive 20 de novembro, desde 2024), Carnaval (segunda e terça), Sexta-feira Santa e Corpus Christi. A folha segue o prazo salarial: até o 5º dia útil do mês seguinte ao trabalhado (CLT, art. 459, § 1º). Nessa contagem o sábado é dia útil (MTE, dúvidas frequentes); domingos e feriados nacionais (inclusive Sexta-feira Santa) não contam, e Carnaval e Corpus Christi contam. O salário por PIX cai no próprio 5º dia útil, mesmo num sábado. Como TED só liquida em dia útil bancário, salários por TED e o pró-labore são antecipados para o último dia útil bancário até o prazo. Em setembro de 2026, o 5º dia útil é sábado, 05/09: os PIX saem em 05/09 e as TED em sexta, 04/09. Feriados estaduais e municipais não são considerados.

Sandbox internacional

Quando o ambiente internacional está em modo SANDBOX, o catálogo inclui ASPSPs de simulação. Eles aparecem como conectores isOpenFinance: true, isSandbox: true, sem credenciais bancárias no objeto e com os produtos ACCOUNTS e TRANSACTIONS.

O sandbox internacional contém apenas uma amostra de ASPSPs e pode ter limitações ou instabilidades próprias de cada banco. Ele valida assinatura RSA, redirect, sessão, paginação e mapeamento de dados, mas não comprova a cobertura nem o comportamento de produção. Descubra a lista em runtime e não copie IDs do sandbox para produção.

Ciclo do cartão de crédito no sandbox

Os conectores mockados locais geram cartões com um ciclo de fatura fixo, no fuso America/Sao_Paulo:

Regra	Valor
Fechamento	Dia `8` de cada mês
Vencimento	Dia `15` do mesmo mês
Período coberto	A fatura que vence em 15/MM cobre as compras feitas depois do dia 8 do mês anterior até o dia 8/MM, inclusive

Ciclo aberto e ciclo fechado

	Ciclo aberto (ainda não fechou)	Ciclo fechado
`status` da transação	`PENDING`	`POSTED`
`creditCardMetadata.purchaseDate`	Preenchido	Preenchido
`creditCardMetadata.billId`	Ausente	`id` da fatura do ciclo
Fatura em `GET /bills`	Não aparece	Aparece, com `totalAmount` igual à soma dos `amount` do ciclo

Quando o ciclo fecha, as mesmas transações (mesmo id) passam de PENDING para POSTED e recebem o billId. A transição dispara o webhook transactions/updated. O Bill.totalAmount é a soma dos amount das transações do ciclo, com compras positivas e pagamentos ou estornos negativos, conforme a convenção de sinal do cartão. Por exemplo, uma compra de 173.90 e um estorno de -10.00 no mesmo ciclo dão totalAmount: 163.90. Isso segue o Open Finance Brasil: só uma fatura já fechada é informada (Credit Cards API 2.4.0-beta.1, GET /accounts/{creditCardAccountId}/bills; PRD de Cartão de Crédito v2.4.0, §3.4.1).

Diferença em relação a produção. Em produção, as transações PENDING de cartão vêm da janela de transações correntes, que cobre só os últimos 7 dias. No sandbox, todo o ciclo aberto aparece como PENDING, do dia seguinte ao último fechamento até hoje. Não use o sandbox para testar o comportamento da janela de 7 dias.

Fechar a fatura agora

Para não esperar o dia 8, feche o ciclo aberto sob demanda com POST /items/{id}/sandbox/close-bill. A chamada usa o mesmo X-API-KEY do POST /items/{id}/refresh e não tem corpo.

curl -X POST "https://api.malvo.io/items/{id}/sandbox/close-bill" \
  -H "X-API-KEY: <apiKey>"

A resposta 200 traz o Item, como no refresh. O calendário simulado do Item avança até o dia seguinte ao próximo fechamento (dia 9) e uma sincronização entra na fila. Quando ela termina:

as transações do ciclo que estava aberto ficam POSTED, com o billId da nova fatura, e você recebe transactions/updated;
a nova fatura aparece em GET /bills?accountId={accountId}.

Cada chamada fecha mais um ciclo: a primeira avança até o dia 9 do mês do próximo fechamento, a segunda até o dia 9 do mês seguinte, e assim por diante. O avanço vale para todo o calendário do Item, então os dias entre hoje e o dia 9 também aparecem na sincronização, com os mesmos ids que teriam quando esses dias chegassem.

Status	`codeDescription`	Quando
`200`	—	Aplicação `SANDBOX` e Item de conector mockado local (`0`–`99`).
`403`	`SANDBOX_ONLY`	A aplicação é `PRODUCTION`. Nada é gravado e nenhuma sincronização é disparada.
`400`	`ITEM_NOT_SANDBOX`	O conector do Item está fora da faixa `0`–`99`. Nada é gravado.
`404`	`ITEM_NOT_FOUND`	O Item não existe ou é de outra aplicação.
`409`	`CLIENT_HAS_ITEM_UPDATES_DISABLED`	As atualizações de Items estão desligadas na aplicação.
`409`	`SANDBOX_CLOSE_BILL_CONFLICT`	Outra chamada concorrente fechou a fatura deste Item primeiro. Consulte o Item e chame de novo se precisar fechar mais um ciclo.

Os erros usam o envelope padrão da API: code é o status HTTP numérico, codeDescription traz o identificador da tabela e requestId identifica a requisição. Por exemplo, com uma aplicação PRODUCTION:

{
  "code": 403,
  "message": "Bill closing is only available to sandbox applications",
  "codeDescription": "SANDBOX_ONLY",
  "requestId": "<id da requisição>"
}

IDs estáveis e janela de 365 dias

O refresh (POST /items/{id}/refresh) e a sincronização automática não criam id novo para uma transação que já existe. Rodar de novo no mesmo dia não cria transações; no dia seguinte, só as transações do novo dia são criadas.
Cada sincronização emite as transações dos últimos 365 dias. Uma transação que sai dessa janela continua gravada e pode ser lida normalmente.

Valores em reais

amount, creditCardMetadata.totalAmount e Bill.totalAmount são números decimais em reais, com até duas casas. R$ 173,90 (17.390 centavos) chega no JSON como 173.90, e não como o inteiro 17390. A unidade é a mesma no sandbox e em produção. Em produção, um valor que a instituição envia como "184.2700" chega como 184.27.

O que o sandbox não simula

A janela de 7 dias das transações correntes de cartão em produção (veja a nota acima).

Garantias do Sandbox

O Sandbox nunca gera cobrança. Nenhuma chamada a conector de sandbox toca em bancos reais nem na rede de Open Finance, e nada é faturado.

Items de sandbox inativos por mais de 30 dias são permanentemente removidos por garbage collection. Não conte com a persistência de longo prazo de Items de teste.
Não há ITP, pagamentos ou iniciação de qualquer tipo no Sandbox — assim como na API de produção, esses recursos não existem na Malvo.

Próximos passos

Connectors

A convenção de IDs e o shape do objeto Connector.

Items

A máquina de estados e os caminhos de recuperação que você vai exercitar no sandbox.

Connect Widget

Ative includeSandbox para testar o fluxo completo na UI.

Quickstart

Conecte um banco de teste de ponta a ponta em minutos.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Opt-in: como ligar o Sandbox

Conectores mockados locais

Credenciais default

Gatilhos por username

Testar uma conexão no sandbox

Sandbox de Open Finance (conector 7)

Empresas (PJ)

Conectores PJ

Credenciais de teste

Porte da empresa

Dados gerados

Movimentações da conta

`paymentData`

Dias úteis

Sandbox internacional

Ciclo do cartão de crédito no sandbox

Ciclo aberto e ciclo fechado

Fechar a fatura agora

IDs estáveis e janela de 365 dias

Valores em reais

O que o sandbox não simula

Garantias do Sandbox

Próximos passos

Connectors

Items

Connect Widget

Quickstart

​Opt-in: como ligar o Sandbox

​Conectores mockados locais

​Credenciais default

​Gatilhos por username

​Testar uma conexão no sandbox

​Sandbox de Open Finance (conector 7)

​Empresas (PJ)

​Conectores PJ

​Credenciais de teste

​Porte da empresa

​Dados gerados

​Movimentações da conta

​paymentData

​Dias úteis

​Sandbox internacional

​Ciclo do cartão de crédito no sandbox

​Ciclo aberto e ciclo fechado

​Fechar a fatura agora

​IDs estáveis e janela de 365 dias

​Valores em reais

​O que o sandbox não simula

​Garantias do Sandbox

​Próximos passos

Connectors

Items

Connect Widget

Quickstart

Opt-in: como ligar o Sandbox

Conectores mockados locais

Credenciais default

Gatilhos por username

Testar uma conexão no sandbox

Sandbox de Open Finance (conector 7)

Empresas (PJ)

Conectores PJ

Credenciais de teste

Porte da empresa

Dados gerados

Movimentações da conta

`paymentData`

Dias úteis

Sandbox internacional

Ciclo do cartão de crédito no sandbox

Ciclo aberto e ciclo fechado

Fechar a fatura agora

IDs estáveis e janela de 365 dias

Valores em reais

O que o sandbox não simula

Garantias do Sandbox

Próximos passos