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 do Pluggy.
• Connect Token -- usada a partir de 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/:id), e um acesso reduzido aos dados das Contas recuperadas (GET /accounts?itemId=).

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 mais, 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 do Pluggy, usando seu CLIENT_ID e CLIENT_SECRET, para criar uma API Key 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 do Pluggy.

Criar um Connect Token#

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

Importante

O connectToken é válido apenas por 30 minutos. O uso recomendado é 1 por conexão, então sugerimos criar um novo sempre que você quiser criar ou atualizar um Item.

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 do Pluggy cuidará de validar seu escopo.

Aviso

Tentativas de acessar dados detalhados de produtos usando um Connect Token (em vez de uma API Key) resultarão em uma resposta da API 403 Forbidden.

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": "Meu 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).

Aviso

Qualquer outra propriedade enviada na raiz do corpo é ignorada. Enviar clientUserId na raiz em vez de dentro de options ainda retorna 200 OK, mas o valor é descartado: os Itens criados com esse token terão clientUserId: null, e o campo também será null nos payloads de webhook item/created, item/updated e item/error.

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

Se você já tiver Itens criados dessa forma, pode preencher o valor com PATCH /items/.

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.