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 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: em um cronograma acordado com você, coletaremos os dados de transação dos últimos dias e os adicionaremos 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.

Escolhendo um cronograma#

A auto-sincronização pode seguir um de dois cronogramas. Ambos são configurados pela Pluggy em seu aplicativo — entre em contato com seu gerente de conta para configurar um ou alterá-lo.

• A cada N horas. As sincronizações ocorrem em um intervalo fixo, contado a partir do final da sincronização anterior. Os intervalos disponíveis são 6, 8, 12, 24, 30, 48 e 96 horas. Opcionalmente, podemos ancorar o ciclo diário a uma hora de início, para que a primeira sincronização de cada dia ocorra perto de um horário que você escolher. Como cada sincronização é contada a partir de quando a anterior terminou, o horário exato do dia varia. Se você precisar que as sincronizações ocorram em horários previsíveis, use a opção abaixo.
• Em horários específicos do dia. As sincronizações ocorrem em até 4 horários fixos por dia — por exemplo, 09:00, 11:00, 13:00 e 18:00. Esta é a melhor opção quando seu produto depende de dados atualizados em momentos específicos — por exemplo, reconciliando durante o horário comercial ou verificando transferências recebidas antes de um corte diário. Dentro de cada janela, as sincronizações individuais são distribuídas ao longo da hora, em vez de todas serem acionadas no minuto exato. Em uma conta com muitas conexões, espere que elas sejam concluídas progressivamente ao longo da janela, em vez de todas de uma vez.

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

Conexões Meu Pluggy são um caso separado#

Meu Pluggy é um serviço autônomo para usuários finais conectando suas próprias contas, e possui suas próprias regras. Conexões feitas dentro do Meu Pluggy são atualizadas automaticamente a cada 24 horas, gratuitamente — essa cadência pertence ao serviço em si e não depende da assinatura de nenhum aplicativo.

Isso é importante quando seu aplicativo se conecta através do conector MeuPluggy, porque existem então dois Itens distintos:

Portanto, ambas as afirmações são verdadeiras ao mesmo tempo e não estão em conflito: "As conexões Meu Pluggy são atualizadas diariamente" (o Item original) e "Itens proxy MeuPluggy não são auto-sincronizados" (o Item proxy). Eles são objetos diferentes.

Para qualquer outro conector, o Item em seu aplicativo segue as regras de auto-sincronização descritas acima.

Lendo nextAutoSyncAt

nextAutoSyncAt é retornado apenas quando a aplicação tem auto-sincronização habilitada. Um null lá significa "esta aplicação não tem auto-sincronização configurada", não "a conexão está quebrada".

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ó precisa fornecer uma URL válida no parâmetro webhookUrl, seja ao criar um Connect Token, ou na própria solicitação de criação do 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 sua conta mais de uma vez 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, pode criar o item com a mesma opção no payload.

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

{
  "code": 400,
  "codeDescription": "ITEM_USER_ALREADY_EXISTS",
  "message": "Existem outros itens com as mesmas credenciais, você não pode criar um novo",
  "data": {
    "items": [
      "d0f8a8c0-e8e3-11e9-b210-d663bd873d93",
      "d0f8a8c0-e8e3-11e9-b210-d663bd873d94"
    ]
  }
}

O array data.items contém os ids dos itens existentes que já utilizam essas credenciais, para que você possa direcionar seu usuário para a conexão que ele já possui em vez de pedir que ele tente novamente. Observe que os ids estão aninhados sob data — eles não são retornados na raiz do corpo da resposta.

Esses conectores suportam o recurso Evitar duplicatas:

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

Referenciando seu usuário#

Quando você cria um Item, pode usar o clientUserId como um identificador externo de 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 possui um parâmetro clientUserId para receber essa referência.

Buscando e listando itens#

Você pode recuperar as conexões que pertencem à sua conta com GET /v2/items, os mais recentemente criados primeiro. Os resultados podem ser filtrados com clientUserId — o identificador externo que você atribuiu ao criar o Item — ou com connectorId, para listar apenas as conexões a uma determinada instituição.

Este endpoint é opt-in e desativado por padrão. Listar permite que uma chave de API enumere cada conexão que você possui, o que é um nível de acesso mais amplo do que recuperar um Item conhecido pelo seu id, portanto, é habilitado por acordo: entre em contato com o suporte se você quiser isso para sua equipe. Até lá, o endpoint responde 403 com LIST_ITEMS_FEATURE_NOT_ENABLED.

As respostas são paginadas por cursor. Em vez de um número de página, cada resposta carrega um valor next apontando para a próxima página: anexe-o como está ao caminho do endpoint e pare assim que voltar null. Quaisquer filtros que você enviou já fazem parte de next, portanto, não há necessidade de repeti-los.

let next = ''
const items = []
 
do {
  const response = await fetch(`https://api.pluggy.ai/v2/items${next}`, {
    headers: { 'X-API-KEY': apiKey },
  })
  const page = await response.json()
 
  items.push(...page.results)
  next = page.next
} while (next !== null)

O parâmetro after aceita apenas o valor do cursor. Enviar a string completa next como after é rejeitado com INVALID_CURSOR.

Listar é uma conveniência, não um substituto para seu próprio controle: ainda recomendamos rastrear suas conexões em sua fonte de dados pelo seu itemId, e manter essas referências em sincronia.