Item

Como introduzimos anteriormente, um Item é a representação de uma conexão com um Conector específico de uma Instituição e serve como o ponto de entrada para acessar o conjunto de produtos recuperados do usuário que deu seu consentimento para coletar seus dados.

Criando um Item: fluxo de autenticação da Instituição#

Para criar um Item, a maneira mais fácil, polida, testada em batalha e menos propensa a erros para um usuário é interagir com nosso Pluggy Connect Widget, onde eles podem fornecer consentimento, seguir os passos de autenticação da Instituição e rapidamente ter seus produtos disponíveis em nossa API.

Caso contrário, você pode desenvolver um aplicativo que implemente o fluxo de criação de Item por conta própria, embora isso possa ser uma tarefa assustadora, complexa e difícil de acertar; portanto, não é a escolha preferida que recomendamos.

Quando um Item é criado e a sincronização da instituição é concluída com sucesso, recuperaremos todos os dados dos produtos financeiros mais recentes, de até os últimos 365 dias.

Acessando os dados coletados do Item#

Para acessar os dados dos produtos coletados do Item, você terá que interagir com nossa API usando os endpoints relacionados. Para ajudar a reduzir os tempos de desenvolvimento, fornecemos vários SDKs do lado do servidor. Se nenhum deles atender às suas necessidades, por favor, nos avise! Ficaremos felizes em ajudar.

Evite reinventar a roda, use nossos SDKs!

Recomendamos fortemente que, se houver um SDK existente para sua linguagem, você o utilize, pois é totalmente suportado por nossa equipe de desenvolvimento e à prova de erros.

Se você acabar criando sua própria integração, não forneceremos suporte para essa implementação específica.

Produtos#

Quando Pluggy cria um Item, ele coleta automaticamente todos os produtos solicitados como uma execução passo a passo, puxando as informações da FI e armazenando-as em nosso banco de dados. Por padrão, coletará todos os produtos habilitados na assinatura da sua equipe.

Ao recuperar um item, você encontrará a lista de produtos habilitados para este item, e você pode especificar esse valor também na criação.

Para personalizar quais produtos você deseja coletar para um item específico, você pode enviar o parâmetro products (usando o tipo de produto em maiúsculas) ao criar o item (se você integrar através da API) ou na configuração do widget usando a propriedade products.

Atualizando um Item#

O processo para atualizar um Item é bastante semelhante ao de criação. A maneira recomendada de fazê-lo também é usando nosso widget Pluggy Connect, conforme explicado aqui. Também pode ser feito via API: Atualizar um Item (também revise: Item Enviar MFA).

Quando uma atualização de Item é bem-sucedida, recuperamos todos os dados dos produtos desde a última vez que fizemos uma coleta de dados e mesclamos com os dados coletados anteriormente.

Além disso, dados de até 4 dias antes da última data de atualização bem-sucedida também serão coletados e mesclados, para compensar quaisquer possíveis mudanças ou adições que possam ter ocorrido nos dados da instituição e não perder o controle deles.

Auto-sincronização#

Uma vez criado, um Item terá uma referência aos parâmetros e credenciais do usuário armazenados necessários para executar a coleta de dados da instituição. Observe que todas as credenciais são criptografadas e nunca podem ser recuperadas da API.

Isso permite que Pluggy execute nosso processo de auto-sincronização, que implica que a cada 24/12/8 horas (com base na sua assinatura), estaremos coletando os dados de transação dos últimos dias e adicionando automaticamente ao conjunto de dados coletados existentes.

Dessa forma, você sempre terá acesso atualizado aos dados dos produtos da Instituição conectada, e não será necessário configurar nenhum processo em lote para atualizar suas conexões, apenas ouvir as notificações de webhook de novas atualizações.

Quando há um erro em uma atualização de auto-sincronização, duas coisas podem acontecer:

• Se foi um LOGIN_ERROR (por exemplo, quando as credenciais são inválidas), a atualização não será tentada novamente e o Item não será mais atualizado por auto-sincronização. A auto-sincronização só será retomada quando o cliente conectar o Item com sucesso novamente.
• Se foi um erro diferente, tentamos a atualização a cada 1 hora até 5 tentativas, após isso, o Item também é removido da auto-sincronização.

O nextAutoSyncAt no endpoint GET /items/{id} indica quando será a próxima atualização de auto-sincronização para o Item, ou nulo se não tiver auto-sincronização. Lembre-se de que esta é a data mínima em que a próxima atualização de auto-sincronização será executada: pode ser ligeiramente atrasada dependendo da carga do conector da instituição no momento.

Recurso Premium

O recurso de auto-sincronização está disponível apenas para aplicações Produção. Pode ser configurado para rodar a cada 24, 12 ou 8 horas com base na sua assinatura.

Se você precisar manter as conexões em sincronia, a única maneira seria usar nossa Auto-Sincronização, o processo de atualização em lote será mitigado e nunca deve ser criado.

Notificações de Webhook#

É possível ouvir Notificações de Webhook para recuperar todos os eventos relacionados a um Item específico. Para isso, você só precisará fornecer uma URL válida no parâmetro webhookUrl, seja ao criar um Connect Token, ou na própria solicitação de criação de Item.

Você pode encontrar mais informações na seção Webhook.

Múltiplos webhooks

Se você criar múltiplos webhooks para um item usando o webhookUrl e a configuração de Webhook em nível de cliente, você receberá múltiplas notificações.

Evitando duplicatas#

Para evitar que um usuário conecte mais de uma vez sua conta no Pluggy, fornecemos uma configuração ao criar sua conexão, que validará se as credenciais já existem antes de passar pelo processo de autenticação.

Usando essa configuração, o usuário receberá um erro da API especificando que já existe um Item criado para essas credenciais.

Você pode configurá-lo de duas maneiras:

• Se você estiver usando Pluggy Connect, pode criar o token com as opções do item para avoidDuplicates como verdadeiro, e todos os itens gerados com esse connectToken serão validados.
• Se você estiver conectado diretamente através da API, você pode criar o item com a mesma opção no payload.

Ao criar um item que já existe, será recuperado um erro HTTP 400.

{
  "codeDescription": "ITEM_USER_ALREADY_EXISTS",
  "message": "Existem outros itens com as mesmas credenciais, você não pode criar um novo"
}

Esses conectores suportam o recurso Evitar duplicatas:

• Conectores diretos do Pluggy: todos
• Conectores de Open Finance:
  • Nubank

Referenciando seu usuário#

Quando você cria um Item, pode usar o clientUserId como um identificador externo dos seus sistemas. Isso ajudará você a identificar um item com seu usuário.

Você pode configurar isso de duas maneiras:

• Usando nosso widget Pluggy Connect, você pode criar um connectToken com o valor para clientUserId. Todos os itens criados com esse token de conexão terão esse valor.
• Ao criar Itens através de nossa API, o payload tem um parâmetro clientUserId para receber essa referência.

Buscando e listando itens#

Listar conexões existentes não é fornecido por razões de segurança. Solicitamos a todos os nossos clientes que rastreiem todas as suas conexões na fonte de dados referenciando o itemId do Pluggy. A responsabilidade é do cliente manter essas referências em sincronia.