Autenticação

Pluggy usa dois tipos de credenciais, dependendo de onde a solicitação é feita:

• API Key -- usada para solicitações do lado do servidor. Ela dá acesso total a todos os endpoints da API Pluggy.
• Connect Token -- usada em aplicações do lado do cliente (ou seja, o Connect Widget). Seu acesso é limitado em escopo.

O acesso do Connect Token é limitado apenas aos dados do recurso Item gerado (GET /items/:idAPI), e um acesso reduzido aos dados das Contas recuperadas (GET /accounts?itemId=API).

Portanto, por exemplo, um Connect Token recém-criado não pode ser usado para acessar informações que foram criadas anteriormente com um Connect Token diferente.

Para qualquer outro tipo de solicitação, como recuperar todos os dados de produtos relacionados ao Item, configurar webhooks, e maisAPI, você precisará fazer solicitações do lado do servidor usando sua API Key.

Criar uma API Key#

Primeiro, você precisará se autenticar com a API Pluggy, usando seu CLIENT_ID e CLIENT_SECRET, para criar uma API KeyAPI via POST /auth.

Observe que essas credenciais são extremamente sensíveis, então, por favor, certifique-se de fazer esta etapa apenas em seu servidor seguro.

Esta API Key expira após 2 horas e lhe dará acesso total a todos os endpoints da API Pluggy.

Criar um Connect Token#

Em seguida, com sua API Key, você terá que fazer uma chamada para POST /connect_tokenAPI.

O uso deste Connect Token é idêntico ao da API Key: basta passá-lo no cabeçalho de autenticação da solicitação, e a API Pluggy cuidará de validar seu escopo.

Configurando um Connect Token#

Ao criar um Connect Token, você pode fornecer algumas ItemOptions que serão passadas para todos os Itens criados usando o mesmo Connect Token. Elas devem ser enviadas aninhadas dentro do atributo options do corpo da solicitação -- este é o payload completo:

{
  "options": {
    "webhookUrl": "https://example.com/webhook",
    "clientUserId": "My App UserId",
    "oauthRedirectUri": "https://pluggy.ai/demo",
    "avoidDuplicates": true
  }
}

• webhookUrl: URL onde você receberá todos os eventos dos Itens criados com este token.
• clientUserId: Você pode usar este campo para vincular um Item ao identificador do seu usuário.
• oauthRedirectUri: URL para redirecionar o usuário após o fluxo de conexão.
• avoidDuplicates: Evita criar um novo Item se já houver um com as mesmas credenciais.

O único outro atributo aceito na raiz do corpo é itemId, usado quando o widget atualiza um Item existente (veja Atualizando um Item).

// ❌ Errado -- clientUserId é silenciosamente descartado
{ "clientUserId": "My App UserId", "options": { "avoidDuplicates": true } }
 
// ✅ Correto
{ "options": { "clientUserId": "My App UserId", "avoidDuplicates": true } }

Criando um Item#

Para resumir, o fluxo para criar um Item usando um connectToken é:

1. Seu servidor se autentica com CLIENT_ID e CLIENT_SECRET para obter uma API Key.
2. Seu servidor cria um Connect Token e o envia para sua aplicação cliente.
3. Sua aplicação cliente usa o Connect Token para criar o Item.

Se você estiver usando nosso Connect Widget, você só precisará se preocupar em fornecer o Connect Token -- o resto será tratado por nós.

Mantendo uma referência de conexão#

Ao inicializar o Connect Widget para seu usuário, você pode querer rastrear a qual usuário a conexão criada pertence. Isso pode ser feito de algumas maneiras:

• Evento onSuccess do Connect Widget: Quando a conexão é criada e retornada, você pode recuperar o itemId para armazenar do seu lado.
• Webhooks: Após o Item ter sido criado e sincronizado com sucesso, você receberá eventos. Veja Webhooks.
• Vinculando seu identificador de usuário a um Item: Se você precisar vincular o Item ao seu usuário, pode armazenar uma referência em nosso Item usando o clientUserId. Este valor pode ser fornecido ao criar o connectToken ou ao criar um Item diretamente através do endpoint de Itens.