# 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.

```bash
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`:

```javascript
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:

```jsx
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](/recipes/update-an-item-using-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 estar em 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 futura 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](/docs/connections/connectors-coverage) 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.

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

### Quando Usar Esta Opção

| Cenário | Como `forceAskForCredentials` ajuda |
|---------|-------------------------------------|
| O usuário mudou sua senha bancária | Garante que a nova senha seja capturada em vez de tentar novamente com credenciais desatualizadas |
| Seu fluxo requer confirmação explícita de credenciais por conformidade ou segurança | Garante que o usuário reentre ativamente as credenciais, criando uma etapa de reautorização intencional |
| Você suspeita que as credenciais armazenadas podem estar desatualizadas | Força uma nova entrada em vez de confiar em uma tentativa de reconexão automática que pode falhar |

### Resumo do Comportamento

| `forceAskForCredentials` | Estado do Item | Comportamento do Widget |
|--------------------------|----------------|-------------------------|
| `false` (padrão) | Válido / conectado | Pode pular o formulário de credenciais e tentar reconexão automaticamente |
| `true` | Válido / conectado | Sempre mostra o formulário de credenciais antes de prosseguir |
| `true` ou `false` | Qualquer | Sem efeito se `updateItem` não estiver definido |

## 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](/docs/connections/item#auto-sync) 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
- Ouça 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