# Ciclo de vida do Item

Se você decidir usar nosso Connect Widget da Pluggy, não será necessário entrar em mais detalhes sobre o fluxo - já cobrimos tudo para você.

## Status do Item

Para entender o status atual de um item, devemos revisar seu campo `status`. Isso dará uma primeira visão sobre a saúde da conexão.

| Valor | Descrição | Significado |
|---|---|---|
| `UPDATING` | A conexão está sincronizando com o provedor. | Um processo de atualização está em andamento e será atualizado em breve. |
| `LOGIN_ERROR` | O processo de sincronização terminou com erros. | A conexão deve ser atualizada para ser executada novamente. Não acionaremos atualizações automáticas até que novos parâmetros de credenciais sejam fornecidos. |
| `OUTDATED` | O processo de sincronização terminou com erros. | Os parâmetros foram validados corretamente, mas houve um erro na última execução. Pode ser tentado novamente. |
| `WAITING_USER_INPUT` | O processo de sincronização precisa da entrada do usuário para continuar. | A conexão requer a entrada do usuário para continuar o processo de sincronização, isso é comum para conectores de autenticação MFA. |
| `UPDATED` | O processo de sincronização foi concluído com sucesso. | O último processo de sincronização foi concluído com sucesso e todos os novos dados estão disponíveis para coleta. |

Como mencionado acima, quando acionamos uma atualização, o status da conexão será definido como `UPDATING`. Este é um status em andamento, o que significa que você precisará verificá-lo novamente em alguns segundos.

Se as credenciais enviadas forem inválidas, você encontrará um status `LOGIN_ERROR` e será necessário atualizá-lo, fornecendo novas credenciais.

Caso ocorra um erro inesperado, você encontrará o status `OUTDATED`, e terá que revisar o campo `executionStatus` para mais detalhes.

Finalmente, o cenário mais comum é o status `UPDATED`, que significa que a conexão foi sincronizada com sucesso com a instituição.

## Status de Execução passo a passo

Cada item é criado ou atualizado através de uma execução, que, assim como o item, passa por diferentes estados à medida que é executada.

Cada status de Item está associado a um conjunto de possíveis valores de `executionStatus`, de acordo com o diagrama a seguir.

![Diagrama de fluxo de execução do item](/docs/images/item-lifecycle-execution-flow.png)

Essas combinações de status fornecem informações específicas não apenas sobre os passos que estão sendo executados enquanto o Item está sendo atualizado, mas também sobre o resultado final da execução. Assim, por exemplo, se o status do item for `OUTDATED`, podemos verificar o valor relacionado de `executionStatus` para saber a causa específica de não ter terminado com sucesso.

Você pode revisar o status de execução atual detalhado do Item através deste campo, `executionStatus`.

Esse valor indica o passo atual em que a execução se encontra, que pode ser um estado transitório (em andamento) ou um estado final.

### Estados Transitórios

Os seguintes estados representam que a execução do Item ainda está em andamento, portanto, é provável que continue a mudar por conta própria.

| Valor | Descrição |
|---|---|
| `CREATED` | A conexão foi iniciada com sucesso. |
| `LOGIN_IN_PROGRESS` | A conexão está atualmente na etapa de autenticação de Login. |
| `LOGIN_MFA_IN_PROGRESS` | A conexão está atualmente na segunda etapa de autenticação de Login. Este estado ocorre após o envio de um parâmetro de token MFA apenas. |
| `ACCOUNTS_IN_PROGRESS` | Coletando dados de Contas atualmente. Implica que a etapa de Login foi concluída. |
| `CREDITCARDS_IN_PROGRESS` | Coletando dados de Cartões de Crédito atualmente. Implica que a etapa de coleta de Contas foi concluída (ou pulada). |
| `TRANSACTIONS_IN_PROGRESS` | Coletando dados de Transações de Contas e Cartões de Crédito atualmente. Implica que a etapa de coleta de Cartões de Crédito foi concluída (ou pulada). |
| `INVESTMENT_TRANSACTIONS_IN_PROGRESS` | Coletando Transações de Investimento atualmente. Implica que a etapa de coleta de Transações foi concluída (ou pulada). Nota: apenas alguns conectores suportam este produto. |
| `PAYMENT_DATA_IN_PROGRESS` | Coletando dados de Pagamento de Transações atualmente. Implica que a etapa de coleta de Transações de Investimento foi concluída (ou pulada). Nota: apenas alguns conectores suportam este produto. |
| `IDENTITY_IN_PROGRESS` | Coletando dados de Identidade atualmente. Implica que as etapas de Transações (e Dados de Pagamento, se houver) foram concluídas (ou puladas). |
| `MERGING` | Analisando e armazenando todos os dados coletados. Implica que todos os dados disponíveis da Instituição foram coletados. |

### Estados Finais

Esses estados representam uma Execução que foi concluída.

Podemos distinguir dois tipos possíveis de estados finais:

- Um estado final, seja com um resultado de sucesso ou erro.
- Um estado intermediário, que significa que mais entrada do Usuário é necessária. Nesse caso, uma nova Execução precisa ser iniciada cumprindo as ações necessárias.

#### Estados de Sucesso

| Valor | Descrição |
|---|---|
| `SUCCESS` | A execução foi concluída com sucesso, os produtos foram coletados. |
| `PARTIAL_SUCCESS` | A execução foi concluída com sucesso, os produtos foram coletados, mas alguns deles falharam. Verifique o atributo `statusDetail` do Item para mais informações. |

#### Estados de Erro

| Valor | Descrição |
|---|---|
| `ERROR` | Ocorreu um erro inesperado na conexão. |
| `MERGE_ERROR` | A conexão foi concluída com sucesso e os dados foram coletados, mas tivemos um erro inesperado ao armazená-los em nossos registros. |
| `INVALID_CREDENTIALS` | Não foi possível autenticar a conta da instituição do usuário devido a credenciais incorretas. |
| `ALREADY_LOGGED_IN` | Não foi possível fazer login porque há uma sessão ativa e a Instituição não permitiu a criação de uma nova. |
| `SITE_NOT_AVAILABLE` | Falha ao obter uma resposta do site da Instituição. Possivelmente entrou em manutenção, fora de serviço ou temporariamente indisponível. |
| `INVALID_CREDENTIALS_MFA` | A segunda etapa de login falhou devido a um parâmetro de token MFA incorreto ou expirado fornecido. |
| `USER_INPUT_TIMEOUT` | A segunda etapa de login foi abortada após a solicitação do parâmetro MFA ter expirado. |
| `ACCOUNT_LOCKED` | Não foi possível fazer login porque a conta do usuário foi bloqueada. O usuário precisa entrar em contato com a Instituição para desbloqueá-la. |
| `ACCOUNT_NEEDS_ACTION` | Não foi possível prosseguir com a coleta de dados porque uma ação manual do usuário é necessária, como resolver uma solicitação da Instituição para aceitar novos Termos de Uso, fornecer mais/informações pessoais novas, ou outra coisa. |
| `USER_NOT_SUPPORTED` | A Pluggy atualmente não suporta o tipo de conta que o usuário está tentando conectar, para a instituição selecionada. Por exemplo, uma conta "Operador" no conector Caixa Business. |
| `ACCOUNT_CREDENTIALS_RESET` | A instituição financeira está solicitando a redefinição das credenciais do usuário, isso pode acontecer devido a uma senha expirada ou novas medidas de segurança implementadas pela instituição. |
| `CONNECTION_ERROR` | Falha ao estabelecer uma conexão com o site da Instituição. |
| `USER_AUTHORIZATION_NOT_GRANTED` | Não foi possível prosseguir com a coleta de dados porque o Usuário não concedeu autorização de Dispositivo ao Conector Pluggy. |
| `USER_AUTHORIZATION_REVOKED` | O usuário removeu o consentimento para compartilhar seus dados na Instituição Financeira. |

#### Estados Intermediários

| Valor | Descrição |
|---|---|
| `WAITING_USER_INPUT` | Após uma etapa de login inicial bem-sucedida, a Instituição está esperando uma entrada adicional do usuário para continuar a execução, ou seja, um parâmetro de token MFA extra. Mais informações [aqui](/reference/items-send-mfa). |
| `USER_AUTHORIZATION_PENDING` | Um caso especial, semelhante ao `ACCOUNT_NEEDS_ACTION`, mas neste cenário o Usuário precisa fornecer autorização manual em seu Dispositivo ou conta da Instituição. Uma vez que o usuário resolva isso, a Pluggy prosseguirá com a coleta de dados automaticamente alguns minutos depois, nenhuma ação externa adicional é necessária. |

> Veja [Itens em nossa referência de API](/reference/items) para mais informações.

## Fluxo de Sincronização

Durante o processo de criação ou atualização de um Item, ele passará por diferentes estados até que a coleta de dados seja concluída.

Quando o processo começa, o status será definido como `UPDATING` e, a partir daí, há alguns valores de estado possíveis que detalharemos abaixo, com base no fluxo de login específico do Conector.

Existem 3 possibilidades de fluxo de login específico do Conector: quando o conector não requer um parâmetro MFA, quando o conector requer um MFA que é acessível pelo usuário anteriormente (ou seja, usando o Google Authenticator), ou quando o conector requer um MFA que é gerado/solicitado ao usuário logo após a etapa inicial de login ter sido concluída.

### 1- Conectores sem parâmetro MFA

Este é o caso mais simples. O fluxo de login prosseguirá apenas com as credenciais do usuário.

**A- Se as credenciais do usuário estiverem corretas**, então a conexão prosseguirá e tentará recuperar os dados dos produtos. Então:

1. Se tudo correr bem, o status final do Item será `UPDATED`, e o `executionStatus` relacionado será `SUCCESS`.
2. Se algo deu errado, mas pelo menos alguns dos dados dos produtos puderam ser recuperados, o status do Item também será `UPDATED`, e o `executionStatus` relacionado será `PARTIAL_SUCCESS`. Mais informações sobre o que falhou estarão disponíveis no campo `executionReport` do Item.
3. Se algo deu muito errado com a conexão, como um erro inesperado, e nenhum dado puder ser recuperado, o status do Item será `OUTDATED` e o `executionStatus` relacionado será `ERROR`.

> Nos casos acima, todos os itens são considerados atualizáveis, uma vez que as credenciais iniciais estavam corretas.
> Por padrão, os Itens atualizáveis são sincronizados automaticamente por nós, uma vez por dia.

**B- Se as credenciais do usuário não estiverem corretas**, então o status do Item será `LOGIN_ERROR`.

> **Aviso**
>
> Neste caso, o Item não é considerado atualizável. O usuário terá que acionar manualmente uma atualização e recomeçar fornecendo um novo conjunto de credenciais.

> **Aviso**
>
> O status `LOGIN_IN_PROGRESS` pode levar até 5 minutos, pois algumas instituições podem levar esse tempo para começar a retornar os dados da conta do usuário, portanto, considere essa janela de tempo em sua implementação.

### 2- Conectores com etapa de verificação de 1 passo

Este caso de Conector pode ser identificado encontrando em um dos valores de campo de credenciais do conector, uma credencial que tem o campo `mfa` definido como `true`.

O mesmo fluxo da etapa anterior ocorrerá.

> **Aviso**
>
> Aqui, os Itens não são atualizáveis, uma vez que uma entrada extra fornecida pelo usuário é necessária para cada execução de conexão.
>
> **Exceções**
> Existem algumas exceções, como Banco do Brasil PJ, que nos permite continuar sincronizando com a instituição (sem mais solicitações de MFA), uma vez que a autorização inicial do dispositivo foi concedida.

Nos casos em que o parâmetro MFA é enviado repetidamente entre as execuções, a API retornará um pedido ruim com a mensagem específica sem executar o conector.

### 3- Conectores com uma etapa de verificação de 2 passos

Este caso de Conector pode ser identificado verificando o campo `mfa` dos dados base do conector, definido como `true`.

Assim, após fornecer as credenciais iniciais do usuário, se elas estiverem corretas, o Item saltará para um estado diferente: `WAITING_USER_INPUT`.

Neste estado, a conexão será suspensa, até que o usuário envie o código de validação. Assim que o usuário enviar o novo parâmetro, se o parâmetro enviado estiver correto, a execução será retomada como nos cenários anteriores até que o item finalize a execução em um dos três possíveis estados finais `UPDATED`, `OUTDATED` ou `LOGIN_ERROR`.

> **Aviso**
>
> Este caso de Itens não é atualizável, uma vez que uma entrada extra fornecida pelo usuário é necessária para cada execução de conexão.
>
> A única exceção é o Nubank, que pode ser atualizado após uma autorização inicial do dispositivo.

## Resumo

O seguinte diagrama de estado resume o fluxo de conexão do Item.

![Diagrama de máquina de estados do item](/docs/images/item-lifecycle-state-machine.png)

## Retenção de dados e limpeza automática

A Pluggy remove automaticamente os dados armazenados assim que não são mais necessários. As três políticas abaixo são executadas como trabalhos em segundo plano e se aplicam a todos os itens, independentemente de como foram criados.

> Sempre que um item é removido por qualquer um desses processos, o evento de webhook `item/deleted` é emitido. Veja [Webhooks](/docs/developer-tools/webhooks-ref) para o payload.

| Cenário | Quando é acionado | O que acontece |
|---|---|---|
| Item excluído pelo cliente | Imediatamente, em `DELETE /items/{id}` | O item é marcado como excluído, as credenciais armazenadas são apagadas, o consentimento de Open Finance é revogado (quando aplicável) e as autorizações OAuth são expiradas. Os dados do item (contas, transações, etc.) são permanentemente excluídos. |
| Item do Sandbox não utilizado | Quando `updatedAt` é mais antigo que **30 dias** | O item e todos os seus dados relacionados são permanentemente removidos. Recrie o item para continuar testando. |
| Conector descontinuado pela Pluggy | **30 dias** após o conector ser descontinuado | Cada item ainda vinculado a esse conector é automaticamente excluído, seguindo o mesmo processo de uma exclusão iniciada pelo cliente (`item/deleted` webhook emitido). Os dados são então permanentemente removidos, de acordo com a política acima. |

### O que isso significa para você

- **A descontinuação do conector lhe dá uma janela de 30 dias.** Quando a Pluggy anuncia a descontinuação de um conector, incentive os usuários finais afetados a se reconectar através de um conector ainda suportado antes do prazo de 30 dias. Após essa janela, o item é excluído e as credenciais armazenadas e os dados históricos se tornam inacessíveis.
- **Inscreva-se no `item/deleted`** se precisar reagir a exclusões automáticas em seu sistema (por exemplo, para atualizar seu próprio estado de usuário, remover dados em cache ou notificar o usuário final).
- **Credenciais e dados armazenados nunca são retidos além do que é estritamente necessário.** Uma vez que um item entra em qualquer um dos fluxos de exclusão acima, suas credenciais são limpas antes de qualquer processamento adicional.

> Itens do Sandbox seguem um cronograma mais rigoroso porque existem apenas para testes — itens de produção nunca são removidos apenas devido à inatividade.