Atualizar item / renovar autorização

curl --request PATCH \
  --url https://api.malvo.io/items/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "parameters": {
    "cpf": "12345678901"
  },
  "products": [
    "ACCOUNTS",
    "TRANSACTIONS"
  ]
}
'

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({parameters: {cpf: '12345678901'}, products: ['ACCOUNTS', 'TRANSACTIONS']})
};

fetch('https://api.malvo.io/items/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.malvo.io/items/{id}"

payload = {
    "parameters": { "cpf": "12345678901" },
    "products": ["ACCOUNTS", "TRANSACTIONS"]
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.malvo.io/items/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'parameters' => [
        'cpf' => '12345678901'
    ],
    'products' => [
        'ACCOUNTS',
        'TRANSACTIONS'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "id": "a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a",
  "connector": {
    "id": 612,
    "name": "Nubank",
    "type": "PERSONAL_BANK",
    "imageUrl": "https://malvo.io/connectors/nubank.svg",
    "primaryColor": "820AD1",
    "isOpenFinance": true,
    "isSandbox": false
  },
  "status": "UPDATING",
  "executionStatus": "CREATED",
  "createdAt": "2025-01-01T12:00:00.000Z",
  "updatedAt": "2025-01-02T09:00:00.000Z",
  "lastUpdatedAt": "2025-01-02T08:00:00.000Z",
  "nextAutoSyncAt": "2025-01-03T08:00:00.000Z",
  "clientUserId": "my-user-42",
  "webhookUrl": "https://your.app/webhooks/malvo",
  "products": [
    "ACCOUNTS",
    "TRANSACTIONS"
  ],
  "consentExpiresAt": null,
  "consecutiveFailedLoginAttempts": 0,
  "statusDetail": null,
  "error": null,
  "parameter": null,
  "userAction": null,
  "oauthRedirectUri": null
}

{
  "code": 400,
  "message": "Invalid parameters",
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "cpf must match pattern ^\\d{11}$",
      "parameter": "cpf"
    }
  ]
}

{
  "code": 404,
  "message": "Item not found",
  "codeDescription": "ITEM_NOT_FOUND"
}

{
  "code": 409,
  "message": "Item is already being updated",
  "codeDescription": "ITEM_IS_ALREADY_UPDATING",
  "data": {}
}

{
  "code": 429,
  "message": "Too many requests. Please try again later (see Retry-After header in seconds)",
  "codeDescription": "TOO_MANY_REQUESTS",
  "data": {}
}

Items

Atualizar item / renovar autorização

Dispara uma atualização do item. Todos os campos são opcionais; um corpo {} dispara um re-sync simples. Use parameters para enviar os identificadores ou seleções anunciados em connector.credentials e/ou valores de MFA, products para ajustar o conjunto de produtos coletados daqui em diante, webhookUrl para alterar o destino de webhook e clientUserId para atualizar o vínculo. Quando a atualização inicia um novo consentimento, a resposta inclui a URL efêmera em connector.oauthUrl.

Um item Open Finance saudável reaproveita o consentimento vigente: a atualização vira um re-sync simples e a resposta não traz connector.oauthUrl. Para um botão de “reconectar” acionado pelo usuário, envie reconsent: true — assim um novo consentimento é emitido mesmo quando o item ainda parece ativo aqui, o que cobre o consentimento derrubado no banco que ainda não foi observado.

Rate limit: 20 requisições/min por IP — o limite mais baixo da API. Este endpoint é apenas para atualizações disparadas pelo usuário; fluxos de atualização em massa/lote não são permitidos e são limitados (ITEM_CREATION_LIMIT_EXCEEDED). Atualizações periódicas devem usar o auto-sync. Se o banco exigir autenticação nova ou MFA, o item transiciona para WAITING_USER_INPUT até o usuário responder.

PATCH

items

{id}

Atualizar item / renovar autorização

curl --request PATCH \
  --url https://api.malvo.io/items/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "parameters": {
    "cpf": "12345678901"
  },
  "products": [
    "ACCOUNTS",
    "TRANSACTIONS"
  ]
}
'

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({parameters: {cpf: '12345678901'}, products: ['ACCOUNTS', 'TRANSACTIONS']})
};

fetch('https://api.malvo.io/items/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.malvo.io/items/{id}"

payload = {
    "parameters": { "cpf": "12345678901" },
    "products": ["ACCOUNTS", "TRANSACTIONS"]
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.malvo.io/items/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'parameters' => [
        'cpf' => '12345678901'
    ],
    'products' => [
        'ACCOUNTS',
        'TRANSACTIONS'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "id": "a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a",
  "connector": {
    "id": 612,
    "name": "Nubank",
    "type": "PERSONAL_BANK",
    "imageUrl": "https://malvo.io/connectors/nubank.svg",
    "primaryColor": "820AD1",
    "isOpenFinance": true,
    "isSandbox": false
  },
  "status": "UPDATING",
  "executionStatus": "CREATED",
  "createdAt": "2025-01-01T12:00:00.000Z",
  "updatedAt": "2025-01-02T09:00:00.000Z",
  "lastUpdatedAt": "2025-01-02T08:00:00.000Z",
  "nextAutoSyncAt": "2025-01-03T08:00:00.000Z",
  "clientUserId": "my-user-42",
  "webhookUrl": "https://your.app/webhooks/malvo",
  "products": [
    "ACCOUNTS",
    "TRANSACTIONS"
  ],
  "consentExpiresAt": null,
  "consecutiveFailedLoginAttempts": 0,
  "statusDetail": null,
  "error": null,
  "parameter": null,
  "userAction": null,
  "oauthRedirectUri": null
}

{
  "code": 400,
  "message": "Invalid parameters",
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "cpf must match pattern ^\\d{11}$",
      "parameter": "cpf"
    }
  ]
}

{
  "code": 404,
  "message": "Item not found",
  "codeDescription": "ITEM_NOT_FOUND"
}

{
  "code": 409,
  "message": "Item is already being updated",
  "codeDescription": "ITEM_IS_ALREADY_UPDATING",
  "data": {}
}

{
  "code": 429,
  "message": "Too many requests. Please try again later (see Retry-After header in seconds)",
  "codeDescription": "TOO_MANY_REQUESTS",
  "data": {}
}

Authorizations

X-API-KEY

string

header

required

Chave de API (apiKey, TTL ~2h) obtida via POST /auth. Enviada no header X-API-KEY.

Path Parameters

string<uuid>

required

Identificador (UUID) do item.

Body

application/json

Corpo de atualização de item (PATCH /items/{id}). Todos os campos são opcionais; {} dispara um re-sync simples.

parameters

object

Identificadores ou seleções anunciados em connector.credentials e/ou valores de MFA. Na primeira adoção de um snapshot importado, CPF/CNPJ omitido pode ser recuperado das contas quando houver um único documento compatível; casos ambíguos continuam exigindo o campo explícito.

webhookUrl

string<uri>

Atualiza o destino de webhook do item.

oauthRedirectUri

string<uri>

Atualiza o destino final do OAuth. HTTPS ou deep link seguro.

connectorId

integer

Conector Open Finance para adoção/reconexão de snapshot importado; não use para trocar uma conexão nativa de banco.

reconsent

boolean

Força um novo consentimento Open Finance mesmo que o item ainda pareça saudável, retornando uma nova connector.oauthUrl. Use quando o usuário final pedir para reconectar: um consentimento derrubado no banco pode continuar lendo como ativo aqui até a releitura no detentor confirmar o contrário, e sem esta flag o PATCH degrada para um re-sync simples e responde sem URL de autorização. Ignorado em conectores sandbox/diretos, que não emitem consentimento.

Response

Item agora em UPDATING ou, quando um novo consentimento foi iniciado, em LOGIN_IN_PROGRESS com a URL efêmera em connector.oauthUrl. O corpo é o objeto Item completo (§4.1).

Objeto Item completo (§4.1).

string<uuid>

required

Identificador do item. Sempre inclua-o ao reportar problemas — o suporte não investiga sem ele.

connector

object

required

Connector embutido no Item. Na criação/reconsentimento OAuth, oauthUrl contém a URL efêmera de autorização.

Show child attributes

Example:

{
  "id": 612,
  "name": "Nubank",
  "type": "PERSONAL_BANK",
  "imageUrl": "https://malvo.io/connectors/nubank.svg",
  "primaryColor": "820AD1",
  "isOpenFinance": true,
  "isSandbox": false
}

status

enum<string>

required

Estado do item (nível do item).

CREATING: registro criado, execução ainda não iniciada (não terminal).
UPDATING: conexão sincronizando com o provedor (não terminal).
LOGIN_IN_PROGRESS: autenticando na instituição (não terminal).
WAITING_USER_INPUT: pausado aguardando uma entrada do usuário, tipicamente token MFA.
WAITING_USER_ACTION: pausado aguardando uma ação fora do formulário, como aprovar no aplicativo da instituição.
UPDATED: último sync concluído com sucesso (possivelmente parcial — verifique executionStatus e statusDetail); terminal até o próximo sync.
OUTDATED: parâmetros validados mas a execução falhou; retriável; terminal até nova tentativa.
LOGIN_ERROR: credenciais inválidas; o usuário deve reautenticar; terminal até atualizar as credenciais.

Available options:

CREATING,

UPDATING,

LOGIN_IN_PROGRESS,

WAITING_USER_INPUT,

WAITING_USER_ACTION,

UPDATED,

OUTDATED,

LOGIN_ERROR

executionStatus

enum<string>

required

Estado detalhado da última execução.

Transitivos (em andamento): CREATED (execução na fila), LOGIN_IN_PROGRESS (autenticando, até 5 minutos), LOGIN_MFA_IN_PROGRESS (validando token MFA), ACCOUNTS_IN_PROGRESS (coletando contas), CREDITCARDS_IN_PROGRESS (coletando cartões), TRANSACTIONS_IN_PROGRESS (coletando transações), INVESTMENT_TRANSACTIONS_IN_PROGRESS (coletando transações de investimento), PAYMENT_DATA_IN_PROGRESS (coletando metadados de pagamento das transações — ainda agregação de dados, NÃO iniciação), IDENTITY_IN_PROGRESS (coletando identidade), MERGING (analisando e armazenando dados coletados).

Intermediários (bloqueados): WAITING_USER_INPUT (aguardando entrada do usuário — tipicamente token MFA), WAITING_USER_ACTION (aguardando ação na instituição) e USER_AUTHORIZATION_PENDING (aguardando autorização — aprovação de dispositivo ou redirect regulado ainda não concluído).

Finais — sucesso: SUCCESS (todos os produtos solicitados recuperados), PARTIAL_SUCCESS (alguns produtos falharam — inspecione statusDetail por produto).

Finais — erro: ERROR (erro de conexão inesperado), MERGE_ERROR (dados coletados mas falha ao armazenar/mesclar), INVALID_CREDENTIALS (autenticação falhou), INVALID_CREDENTIALS_MFA (token MFA incorreto ou expirado), USER_INPUT_TIMEOUT (a entrada pedida ao usuário expirou), ALREADY_LOGGED_IN (sessão ativa na instituição bloqueia novo login), SITE_NOT_AVAILABLE (instituição fora do ar), ACCOUNT_LOCKED (conta bloqueada na instituição), ACCOUNT_NEEDS_ACTION (ação manual necessária na instituição — veja userAction), ACCOUNT_CREDENTIALS_RESET (instituição força reset de senha), USER_NOT_SUPPORTED (tipo de conta não suportado pelo connector), CONNECTION_ERROR (não foi possível alcançar a instituição), USER_AUTHORIZATION_NOT_GRANTED (usuário rejeitou o consentimento), USER_AUTHORIZATION_REVOKED (usuário revogou o consentimento na instituição).

Available options:

CREATED,

LOGIN_IN_PROGRESS,

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,

WAITING_USER_INPUT,

WAITING_USER_ACTION,

SUCCESS,

PARTIAL_SUCCESS,

ERROR,

MERGE_ERROR,

INVALID_CREDENTIALS,

INVALID_CREDENTIALS_MFA,

USER_INPUT_TIMEOUT,

ALREADY_LOGGED_IN,

SITE_NOT_AVAILABLE,

ACCOUNT_LOCKED,

ACCOUNT_NEEDS_ACTION,

ACCOUNT_CREDENTIALS_RESET,

USER_NOT_SUPPORTED,

CONNECTION_ERROR,

USER_AUTHORIZATION_PENDING,

USER_AUTHORIZATION_NOT_GRANTED,

USER_AUTHORIZATION_REVOKED

createdAt

string<date-time>

required

Horário de criação do item.

updatedAt

string<date-time>

required

Última mutação do registro do item.

products

string[]

required

Produtos que este item coleta.

Contagem de execuções de login que falharam consecutivamente; volta a 0 em login bem-sucedido. Usado pelos clientes para parar de insistir e solicitar ação ao usuário.

lastUpdatedAt

string<date-time> | null

Horário de conclusão do último sync bem-sucedido; null até o primeiro sucesso. Âncora do delta-sync.

nextAutoSyncAt

string<date-time> | null

Próximo auto-sync agendado; null quando o auto-sync está desativado para este item/plano.

clientUserId

string | null

Eco do identificador de usuário fornecido pelo caller.

webhookUrl

string<uri> | null

Destino de webhook específico do item.

Expiração conhecida do consentimento/sessão. No fluxo internacional, respeita a validade máxima informada pelo ASPSP.

statusDetail

object | null

Detalhamento por produto (§4.4). null até a primeira execução completar.

Show child attributes

error

object | null

Presente quando a última execução terminou em erro. null caso contrário.

Show child attributes

Example:

{
  "code": "INVALID_CREDENTIALS",
  "message": "The provided credentials are incorrect",
  "providerMessage": "Senha inválida. Você tem mais 2 tentativas.",
  "attributes": { "remainingAttempts": "2" }
}

parameter

object | null

Descritor da credencial pendente quando status = WAITING_USER_INPUT. null caso contrário.

userAction

object | null

Presente quando a instituição exige uma ação externa para continuar; null caso contrário.

Show child attributes

oauthRedirectUri

string | null

Eco da URI de redirect quando fornecida (fluxos OF).

Visão geral

Autenticação & Conectores

Items

Webhooks

Contas & Faturas

Transações & Categorias

Investimentos, Crédito & Identidade

Inteligência & Enriquecimento

Tabelas de referência

Atualizar item / renovar autorização

Authorizations

Path Parameters

Body

Response