Items

Um Item representa uma conexão entre um usuário e um Connector (instituição financeira). É o ponto de entrada para os produtos anunciados por aquele conector e mantém o vínculo com os consentimentos do Open Finance/Open Banking. Cada Item é identificado por um 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, parameters carrega CPF/CNPJ conforme connector.credentials; no fluxo internacional ele pode ser {} e recomenda-se um clientUserId está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 (1, 2 ou 3× ao dia). Configure o padrão da aplicação com PATCH /auto-sync/defaults ou um item com PATCH /items/{id}/auto-sync, usando API key. Novos itens herdam o padrão da aplicação. A configuração também está no Syncer; veja Configurar sincronização automática. nextAutoSyncAt indica a próxima execução. Use PATCH /items/{id}/disable-auto-sync ou autoSyncEnabled: false para desligá-lo; o campo passa a null.
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-After do ASPSP. Veja Frequência de atualização.

Nunca recrie um Item para renovar consentimento, atualizar credenciais ou forçar uma nova sincronização. Renovação e re-autenticação acontecem no mesmo Item via PATCH /items/{id} ou Connect Widget em modo de atualização. Isso preserva IDs e histórico; no Brasil, evita também multiplicar o consumo das cotas mensais.

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.

                        POST /items
                             │
                             ▼
                         CREATING
                             │  execução inicia
                             ▼
        ┌───────────────  UPDATING  ◄──────────────────────────────┐
        │                    │                                     │
        │                    ▼                                     │
        │            LOGIN_IN_PROGRESS  (≤ 5 min)                  │
        │              │      │      │                             │
	        │  creds ruins │      │      │ MFA / autorização OF        │
	        │              ▼      │      ▼              necessária     │
	        │        LOGIN_ERROR  │   WAITING_USER_INPUT ──────────────┤
	        │                     │   WAITING_USER_ACTION ─────────────┤
	        │                     │      │                             │
	        │                     │      │ MFA via endpoint ou ação    │
	        │                     │      │ no app da instituição       │
	        │                     │      ▼                             │
	        │                     │  (retoma)                          │
        │                     ▼                                    │
        │       fases de coleta de produtos                        │
        │   (ACCOUNTS_IN_PROGRESS → CREDITCARDS_IN_PROGRESS →      │
        │    TRANSACTIONS_IN_PROGRESS → ... → MERGING)             │
        │              │                    │                      │
        │  erro exec   │                    │ sucesso/parcial      │
        │              ▼                    ▼                      │
        │           OUTDATED             UPDATED                   │
        │                                                          │
        └── PATCH /items/{id} / POST /items/{id}/refresh / auto-sync

Status do Item

O campo status descreve o estado de alto nível da conexão.

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

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.

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

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

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

Os parâmetros eram válidos, mas a execução não terminou com sucesso. Retriável sem trocar credenciais.

executionStatus

Enquanto status é 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)

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)

WAITING_USER_INPUT — aguardando entrada do usuário (token de MFA, autorização de dispositivo ou redirecionamento de Open Finance).

Final — sucesso

SUCCESS — todos os produtos solicitados foram recuperados.PARTIAL_SUCCESS — alguns produtos falharam; inspecione statusDetail produto a produto.

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.

`executionStatus`	Ação do cliente
`SUCCESS`	Leia os produtos; ainda assim verifique `statusDetail.*.warnings`.
`PARTIAL_SUCCESS`	Leia os produtos disponíveis; exiba as falhas por produto a partir de `statusDetail`.
`INVALID_CREDENTIALS` / `INVALID_CREDENTIALS_MFA`	Peça ao usuário para se re-autenticar (fluxo de atualização).
`CONNECTION_ERROR` / `SITE_NOT_AVAILABLE`	Tente mais tarde; consulte a página de status.
`USER_AUTHORIZATION_PENDING`	Peça ao usuário para refazer o fluxo de consentimento/MFA.
`USER_AUTHORIZATION_REVOKED` / `USER_AUTHORIZATION_NOT_GRANTED`	Dispare a renovação de consentimento (via `PATCH`) ou exclua o Item.

statusDetail por produto

O campo statusDetail 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:

{
  "isUpdated": true,
  "lastUpdatedAt": "2025-01-02T08:00:00.000Z",
  "warnings": [
    { "code": "ACCT_003", "message": "Account temporarily unavailable at the institution", "providerMessage": "..." }
  ]
}

Chaves possíveis (camelCase, exatas): 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.

Warnings aparecem em dois cenários: (a) o produto falhou ao atualizar (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.

Produto	Faixa de códigos	Tópicos
Accounts	`ACCT_001`–`ACCT_006`	Permissões, autorização pendente, indisponibilidade, limites
Credit Cards	`CC_001`–`CC_007`	Permissões, autorização pendente, indisponibilidade, limites ausentes
Transactions	`TXN_001`–`TXN_006`	Permissões, limites de taxa, disponibilidade de conta
Loans	`LOAN_001`–`LOAN_006`	Permissões, status, falhas de sync
Investments	`INV_001`–`INV_005`	Permissões, limites de taxa, produtos não suportados
Identity	`ID_001`–`ID_004`	Permissões, subprodutos, limites de taxa

Conta ou cartão fora do consentimento

No Open Finance Brasil, uma conta (accounts) ou um cartão (creditCards) já sincronizado pode sair do consentimento ou ficar suspenso na instituição. A Malvo deixa de buscar esse recurso, mantém os dados já recebidos e não avança o updatedAt da conta. A família fica com isUpdated: false e o Item termina PARTIAL_SUCCESS com um destes avisos:

`code`	Significado	Ação do cliente
`RESOURCE_NO_LONGER_SHARED`	A instituição deixou de compartilhar a conta ou o cartão neste consentimento.	Reconecte o Item (`PATCH /items/{id}`) e peça ao usuário para selecionar o recurso na instituição.
`RESOURCE_TEMPORARILY_UNAVAILABLE`	A instituição suspendeu o recurso temporariamente.	Aguarde. A coleta volta sozinha quando a instituição liberar o recurso.

A message vem em português e cita os quatro últimos dígitos do número quando ele existe, por exemplo: “A instituição deixou de compartilhar a conta final 7654 neste consentimento. Para voltar a receber os dados, reconecte a conta.” Quando o recurso volta, o aviso some e a coleta continua de onde parou. Não há evento novo: o aviso chega no item/updated da sincronização. Detalhes para cartões em Cartões de crédito e faturas.

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.

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.

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": "..." } }.

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.

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.

Padrões de MFA afetam o auto-sync: conexões sem MFA e de MFA de etapa única (token enviado no parameters inicial) permitem auto-sync; MFA de duas etapas (pausa em WAITING_USER_INPUT) geralmente desativa o auto-sync, com exceções específicas por instituição.

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.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Invariantes do Item

Ciclo de vida — máquina de estados

Status do Item

executionStatus

executionStatus → ação do cliente

statusDetail por produto

Warnings vs errors

Conta ou cartão fora do consentimento

Caminhos de recuperação

Próximos passos

Connect Widget — modo de atualização

Referência da API

​Invariantes do Item

​Ciclo de vida — máquina de estados

​Status do Item

​executionStatus

​executionStatus → ação do cliente

​statusDetail por produto

​Warnings vs errors

​Conta ou cartão fora do consentimento

​Caminhos de recuperação

​Próximos passos

Connect Widget — modo de atualização

Referência da API

Invariantes do Item

Ciclo de vida — máquina de estados

Status do Item

executionStatus

executionStatus → ação do cliente

statusDetail por produto

Warnings vs errors

Conta ou cartão fora do consentimento

Caminhos de recuperação

Próximos passos