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

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 Pagamentos 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 terminou de ser executada.

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`	Houve 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.
`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 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:

Se tudo correr bem, o status final do Item será UPDATED, e o executionStatus relacionado será SUCCESS.
Se algo der errado, mas pelo menos alguns dos dados dos produtos puderem 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.
Se algo der 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 estiverem 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

Nesse 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 do dispositivo inicial 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 termine 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.

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