id (UUID). Sempre inclua o id ao reportar problemas — o suporte não consegue investigar uma conexão sem ele.
Um Item é vinculado ao seu próprio identificador de usuário através do campo
clientUserId. Guarde os id dos Items do seu lado, indexados por clientUserId — a Malvo não expõe um endpoint público de listagem (GET /items). Os Items são endereçados por id.Invariantes do Item
- Na criação bem-sucedida, o Item busca o maior histórico aplicável: no Brasil, até 365 dias; no Open Banking internacional, a janela efetiva depende do ASPSP.
- O usuário autentica no próprio banco e a Malvo não armazena senhas bancárias. No Brasil,
parameterscarrega CPF/CNPJ conformeconnector.credentials; no fluxo internacional ele pode ser{}e recomenda-se umclientUserIdestável. - Cada sincronização seguinte é incremental (delta): usa uma sobreposição para capturar lançamentos tardios (aproximadamente 7 dias no Brasil e 90 dias no fluxo internacional). No AIS internacional, uma reconciliação completa também é tentada a cada 30 dias quando o ASPSP aceita a janela máxima de histórico.
- O auto-sync atualiza o Item automaticamente a cada 24h / 12h / 8h conforme a frequência configurada por item (1, 2 ou 3× ao dia, no Syncer);
nextAutoSyncAtindica a próxima execução. UsePATCH /items/{id}/disable-auto-syncpara desligá-lo; o campo passa anull. - No Brasil, cada tipo de dado tem uma frequência máxima de atualização para respeitar as
cotas mensais. No Open Banking internacional, a Malvo segue o scheduler do Item e os limites/
Retry-Afterdo ASPSP. Veja Frequência de atualização.
Ciclo de vida — máquina de estados
O diagrama abaixo mostra todas as transições possíveis de um Item, da criação ao estado final de cada execução.Status do Item
O campostatus descreve o estado de alto nível da conexão.
CREATING — registro criado, execução ainda não iniciou
CREATING — registro criado, execução ainda não iniciou
Estado inicial logo após
POST /items. Não terminal. A execução começa quando o worker assume o Item.UPDATING — sincronizando com a instituição
UPDATING — sincronizando com a instituição
O Item está coletando dados do provedor. Não terminal. Faça polling em
GET /items/{id} (ou consuma webhooks) até o status sair de UPDATING/LOGIN_IN_PROGRESS.LOGIN_IN_PROGRESS — autenticando na instituição
LOGIN_IN_PROGRESS — autenticando na instituição
Autenticação em andamento. Pode levar até 5 minutos. Não terminal.
WAITING_USER_INPUT — pausado aguardando o usuário
WAITING_USER_INPUT — pausado aguardando o usuário
O Item está bloqueado esperando uma ação do usuário (token de MFA ou autorização de Open Finance). Leia
item.parameter para saber qual entrada é esperada. Bloqueia até receber a entrada ou expirar.WAITING_USER_ACTION — ação externa necessária
WAITING_USER_ACTION — ação externa necessária
A instituição exige uma ação fora do formulário. Leia
item.userAction.instructions e, quando presente, item.userAction.expiresAt. Não invente um MFA: mantenha o polling ou aguarde item/waiting_user_action até a instituição confirmar a ação.UPDATED — última sincronização concluída
UPDATED — última sincronização concluída
Estado de sucesso (terminal até a próxima sincronização). A conclusão pode ser parcial — sempre verifique
executionStatus e statusDetail.OUTDATED — parâmetros validados, mas a execução falhou
OUTDATED — parâmetros validados, mas a execução falhou
Os parâmetros eram válidos, mas a execução não terminou com sucesso. Retriável sem trocar credenciais.
LOGIN_ERROR — credenciais inválidas
LOGIN_ERROR — credenciais inválidas
O login falhou; o usuário precisa se re-autenticar. Permanece nesse estado até que novas credenciais sejam enviadas.
executionStatus
Enquantostatus é o estado de alto nível, executionStatus descreve em detalhe a execução mais recente. Abaixo, os valores principais agrupados por fase.
Em progresso (transitivos)
Em progresso (transitivos)
CREATED, LOGIN_IN_PROGRESS (pode levar até 5 min), LOGIN_MFA_IN_PROGRESS, ACCOUNTS_IN_PROGRESS, CREDITCARDS_IN_PROGRESS, TRANSACTIONS_IN_PROGRESS, INVESTMENT_TRANSACTIONS_IN_PROGRESS, PAYMENT_DATA_IN_PROGRESS, IDENTITY_IN_PROGRESS, MERGING (analisando e armazenando os dados coletados).Bloqueado (intermediário)
Bloqueado (intermediário)
WAITING_USER_INPUT — aguardando entrada do usuário (token de MFA, autorização de dispositivo ou redirecionamento de Open Finance).Final — sucesso
Final — sucesso
SUCCESS — todos os produtos solicitados foram recuperados.PARTIAL_SUCCESS — alguns produtos falharam; inspecione statusDetail produto a produto.Final — erro
Final — erro
ERROR, MERGE_ERROR, INVALID_CREDENTIALS, INVALID_CREDENTIALS_MFA, ALREADY_LOGGED_IN, SITE_NOT_AVAILABLE, ACCOUNT_LOCKED, ACCOUNT_NEEDS_ACTION (ação manual na instituição — veja userAction), ACCOUNT_CREDENTIALS_RESET, USER_NOT_SUPPORTED, CONNECTION_ERROR, USER_AUTHORIZATION_PENDING, USER_AUTHORIZATION_NOT_GRANTED, USER_AUTHORIZATION_REVOKED.executionStatus → ação do cliente
Use esta tabela para decidir o que fazer ao final de cada execução.statusDetail por produto
O campostatusDetail traz o detalhamento da última execução por família de produto. Cada chave é null (produto não coletado por este Item) ou um objeto:
accounts, creditCards, transactions, investments, identity, paymentData, loans, investmentsTransactions.
Warnings vs errors
A distinção é doutrinária e importa para a sua lógica:- Errors (
item.error) significam que a requisição inteira falhou e nenhum dado foi recuperado. - Warnings (
statusDetail.<produto>.warnings) significam que a requisição teve sucesso, mas alguns dados podem estar incompletos ou indisponíveis.
isUpdated: false); (b) o produto atualizou (isUpdated: true), mas uma ação extra do usuário melhoraria os dados.
Causas comuns: permissões de Open Finance ausentes, consentimento expirado, recurso pendente / temporária ou permanentemente indisponível, limites de taxa da instituição, ou dados servidos como fallback de uma sincronização anterior.
No Open Finance Brasil, limites mensais aparecem como warning
423 dentro de
PARTIAL_SUCCESS. No Open Banking internacional, falhas parciais são normalizadas como
PROVIDER_PARTIAL e respeitam Retry-After/backoff. Preserve sempre os dados válidos e use
providerMessage apenas para diagnóstico server-side.No Brasil, uma leitura que falha por rede ou
5xx recebe até 3 tentativas no total, separadas
por 10 segundos. O mesmo vale para a propagação inicial do consentimento. Persistindo a falha
em apenas uma família, a execução fica PARTIAL_SUCCESS, preserva o que foi importado e
dispara item/updated; consulte statusDetail e a política completa em Open Finance e Open
Banking.Caminhos de recuperação
Todo Item que termina em um estado bloqueado ou de erro tem um caminho claro de recuperação. Implemente e exponha todos eles.1
LOGIN_ERROR — credenciais inválidas
O usuário fornece credenciais novas:
PATCH /items/{id} com parameters, ou um connect token com itemId + o Connect Widget em modo de atualização.O contador consecutiveFailedLoginAttempts aumenta a cada login falho e zera no sucesso. Pare de tentar automaticamente e force a ação do usuário antes que a conta seja bloqueada na instituição.2
WAITING_USER_INPUT — aguardando MFA/autorização
Leia
item.parameter (o descritor do campo esperado, que pode trazer um expiresAt), colete a entrada do usuário e envie via POST /items/{id}/mfa com { "parameters": { "token": "..." } }.3
WAITING_USER_ACTION — ação no app/site da instituição
Mostre
item.userAction.instructions ao usuário e continue acompanhando o Item. Essa etapa não envia parameters; a sincronização retoma quando a instituição confirma a ação.4
OUTDATED — simplesmente retriável
Sem troca de credenciais:
POST /items/{id}/refresh ou PATCH /items/{id}.Se o OUTDATED foi causado por revogação/expiração de consentimento, o fluxo disparado pelo PATCH leva o usuário à re-autorização no banco e gera um novo consentimento no MESMO Item — nunca crie um Item novo para renovar.Próximos passos
Connect Widget — modo de atualização
Como re-autenticar, coletar MFA e renovar consentimento no mesmo Item.
Referência da API
Endpoints completos de Items: criar, ler, atualizar, desativar auto-sync, refresh, MFA e excluir.