Atualizando um Item

Visão Geral#

Após criar um Item com sucesso, você pode continuar a coletar dados de produtos que aparecem nos dias seguintes, acionando uma atualização para sua referência de Item existente, em vez de criar um novo Item do zero.

Atualizar um Item existente é mais econômico, pois apenas recupera os dados dos produtos da instituição gerados após o último processo de coleta.

Como Atualizar um Item#

Para atualizar um Item existente usando o Pluggy Connect, siga estas etapas:

1. Crie um Connect Token com o ID do Item#

Crie um novo Connect Token, especificando o parâmetro itemId da conexão do Item correspondente que você deseja atualizar. Isso é necessário para permitir que o Pluggy valide corretamente que você está autorizado a acessar e atualizar este Item específico.

curl --request POST \
  --url https://api.pluggy.ai/connect_token \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "itemId": "ITEM_ID_TO_UPDATE"
  }'

2. Passe o Connect Token e o ID do Item para o Widget#

Passe para o Connect tanto o connectToken recém-criado quanto o id do Item correspondente através da propriedade updateItem:

import PluggyConnect from 'pluggy-connect-sdk';
 
const pluggyConnect = new PluggyConnect({
  connectToken: 'your-connect-token',
  updateItem: 'ITEM_ID_TO_UPDATE',
  onSuccess: (itemData) => {
    console.log('Item atualizado com sucesso!', itemData);
  },
  onError: (error) => {
    console.error('Erro na atualização:', error);
  },
});
 
pluggyConnect.init();

Ou com React:

import { PluggyConnect } from 'react-pluggy-connect';
 
function UpdateWidget({ connectToken, itemId }) {
  return (
    <PluggyConnect
      connectToken={connectToken}
      updateItem={itemId}
      onSuccess={({ item }) => console.log('Atualizado!', item.id)}
      onError={({ message }) => console.error(message)}
    />
  );
}

Comportamento do Widget Durante a Atualização#

• Se nenhuma entrada adicional do usuário for necessária, o Pluggy Connect iniciará automaticamente o processo de atualização.
• Caso contrário, quando novas credenciais e/ou um parâmetro MFA forem necessários, o Pluggy Connect solicitará ao usuário que os complete antes que o processo de atualização comece.

Exemplo de Código

Confira um exemplo completo em HTML em nossa receita: Atualizar um Item usando Pluggy Connect.

Quando a Entrada do Usuário é Necessária#

Na maioria dos casos, você pode simplesmente iniciar o processo de atualização do Item sem problemas ou entrada adicional do usuário. No entanto, existem alguns cenários em que isso não é possível, devido a limitações relacionadas a requisitos de autenticação adicionais da instituição (como um requisito de MFA) ou devido ao Item ter um estado de credenciais inválidas que requer a entrada de novas credenciais do usuário.

Esses cenários são os seguintes:

• Itens que não puderam ser bem-sucedidos devido a um problema com suas credenciais (status do Item: INVALID_CREDENTIALS).
• Itens que não podem ser sincronizados automaticamente pelo Pluggy em nosso processo de sincronização diário, devido à conexão precisar de uma entrada adicional do usuário, como um parâmetro MFA.

Caso: INVALID_CREDENTIALS#

Isso acontece quando:

• As credenciais fornecidas pelo usuário não estavam corretas, por exemplo, devido a uma entrada incorreta.
• As credenciais estavam corretas, mas quando tentamos sincronizar automaticamente o Item reutilizando as últimas credenciais válidas, encontramos um erro de login inválido.

Para qualquer uma dessas situações, o usuário precisará usar o Pluggy Connect para atualizar este Item e fornecer novas credenciais.

Após isso, se a etapa de login for bem-sucedida, qualquer atualização adicional deste Item reutilizará as novas credenciais fornecidas, e nosso processo de sincronização automática voltará a funcionar.

Caso: Item Não Sincronizável Automaticamente#

Este é o caso para instituições que requerem uma etapa de login MFA adicional.

Nesse cenário, a única opção para que o Item seja atualizado é que o usuário abra o Pluggy Connect configurado para o Item correspondente e resolva o desafio MFA necessário.

Alguns exemplos são:

• XP
• Bradesco
• Easynvest

Você pode encontrar na lista completa de Conectores quais requerem um MFA.

Nota

Existem algumas instituições que apenas requerem uma verificação inicial ou autorização de dispositivo como um MFA pela primeira vez. Após isso, nenhuma entrada manual adicional é necessária do usuário, então poderemos sincronizar automaticamente esses Itens também.

Forçando a Reentrada de Credenciais com forceAskForCredentials#

Por padrão, ao atualizar um Item que já está em um estado válido/conectado, o widget pode tentar reexecutar a conexão automaticamente — sem mostrar o formulário de credenciais — uma vez que as credenciais já estão armazenadas.

Definir forceAskForCredentials: true substitui esse comportamento e sempre apresenta o formulário de credenciais ao usuário, exigindo que eles reentrem explicitamente suas credenciais antes que a atualização prossiga.

Nota

forceAskForCredentials só tem um efeito significativo quando updateItem também está definido. É destinado exclusivamente para fluxos de atualização de Item, não para a criação de novos Itens.

pluggyConnect.init({
  updateItem: "<item-id>",
  forceAskForCredentials: true,
  // ...outras opções
});

Quando Usar Esta Opção#

Resumo do Comportamento#

Limitações ao Atualizar Itens Através da API#

Quando novos usuários criam equipes e aplicativos, esses IDs de cliente têm um limite para atualizar Itens diretamente através da API com o endpoint PATCH /items: atualizações não podem ser realizadas mais de uma vez por hora.

Essa limitação não afeta atualizações manuais feitas através do widget — não há limitações nesse caso. Além disso, quando você estiver prestes a mover seu aplicativo para produção, recomendamos conversar com nossa equipe de suporte para remover essa limitação.

Atualizações Automáticas#

O Pluggy fornece atualizações automáticas de Itens para aplicativos de Produção, a cada 24, 12 ou 8 horas, dependendo do seu plano.

Conclusão e Webhooks#

Uma vez que uma atualização foi concluída:

1. O Item muda seu status para UPDATED
2. O webhook item/updated é acionado
3. Espera-se que os clientes implementem um processo de sincronização após o webhook para sincronizar os dados

Melhores Práticas#

• Sempre crie um novo Connect Token com o itemId específico antes de acionar uma atualização
• Escute o callback onSuccess para confirmar que a atualização foi concluída
• Implemente manipuladores de webhook para processar dados atualizados de forma assíncrona
• Use o evento de webhook item/updated para acionar seu processo de sincronização de dados