ESTRITAMENTE CONFIDENCIAL

Introdução à API Pluggy via Postman

Bem-vindo à Pluggy!

Agora que você já tem suas credenciais de acesso, falta pouco para
começar a utilizar a nossa API. Basta seguir o passo a passo descrito neste
manual, o qual está organizado em:

Setup inicial 2

Conectar uma conta 5

Conectores sem código verificador 5
Conectores sem código verificador uma etapa 7
Conectores com código verificador em duas etapas 8
Teste de conexão 15
ClientUserId 16

Realizar chamadas para obtenção de uma conta 17

Realizar chamadas para obtenção de transações por conta 19

Realizar chamadas para obtenção de transações de investimento 22

Realizar chamadas para obtenção da identidade 24

Webhook 25
Criação de webhook: 25
Atualização de webhook: 27
Deleção de webhook: 28

1
Pluggy API via Postman Collection

1. Setup inicial

Vamos iniciar conectando uma conta através do Postman, ferramenta

utilizada para realizar chamadas em APIs.

É necessário obter o conjunto de requisições disponíveis para acessar a API

Pluggy (Postman Collection), disponível neste link.

Selecione a opção "Abrir Postman" e a coleção já será importada para o

aplicativo:

2
Antes de começar, vamos preparar o ambiente para realizar as requisições.
No aplicativo Postman, no canto esquerdo, selecione o menu
"Environments":

Em seguida, clique no botão + (“create new environment”),

3
Em seguida, dê um nome ao seu ambiente e adicione as seguintes
variáveis:

i. “host”
a. Endereço do servidor da aplicação: [Link]
ii. “CLIENT_ID”
a. Seu login de acesso
iii. “CLIENT_SECRET”
a. Sua senha de acesso

Clique em "Save" para salvar as alterações.

Tudo pronto para começar a realizar chamadas na API Pluggy!

4
2. Conectar uma conta

Nesta seção, vamos aprender a conectar a API Pluggy com uma instituição
financeira.

Cada instituição financeira terá um conector e elementos específicos para

serem preenchidos no corpo da requisição no Postman. Dividiremos os
conectores em três fluxos para facilitar o entendimento:

- Conectores sem código verificador

- Conectores com código verificador em uma etapa
- Conectores com código verificador em duas etapas

2.1 Conectores sem código verificador

Para conectar uma conta que não necessita de um código de validação
extra, basta acessar a coleção de requisições (Postman Collection),
expandir a pasta "Items" e selecionar a requisição "Create Item".

Na aba "Body", deverão ser inseridos suas credenciais nos elementos

apresentados na requisição "Create Item". Cada instituição apresenta
elementos específicos (payloads), necessários para a conexão. Listamos
cada uma das instituições e suas especificidades abaixo:
a) Conta Sandbox (Pluggy Bank)

Utilizando a conta Sandbox (Pluggy Bank) você pode testar a sua

implementação sem precisar efetuar movimentações financeiras reais.
Com ele, você pode testar diversos cenários sem afetar a sua conta de
produção. Abaixo, seguem as credenciais utilizadas para conectar com o
Pluggy Bank:

- User: user-ok
- Password: password-ok

5
 - Pluggy Bank:
{
"connectorId": 2,
"parameters": {
"user": "",
"password": ""
},
"webhookUrl": ""
}

b) Instituições Financeiras

- Itaú:
{
"connectorId": 201,
"parameters": {
"agency": "",
"account": "",
"password": ""
},
"webhookUrl": ""
}

- Banco do Brasil:
{
"connectorId": 211,
"parameters": {
"agency": "",
"account": "",
"password": ""
},
"webhookUrl": ""
}

- Caixa Econômica Federal:

{
"connectorId": 219,
"parameters": {
"user": "",
"password": ""
},
"webhookUrl": ""
}

- Santander PF:
{
"connectorId": 208,
"parameters": {
"user": "cpf",
"password": ""
},
"webhookUrl": ""
}

6
 2.2 Conectores com código verificador uma etapa

Alguns conectores solicitam um código de verificação extra ao se conectar

com uma instituição financeira. Esta é uma solicitação da instituição
financeira para que os dados possam ser acessados com segurança.

Neste fluxo, o código verificador será enviado juntamente das credenciais

de acesso à conta.

Para conectar uma conta que solicita um código de validação extra em

uma etapa, basta acessar a coleção de requisições (Postman Collection),
expandir a pasta "Items" e selecionar a requisição "Create Item with MFA".

Na aba "Body", deverão ser inseridas as suas credenciais de acesso à

instituição juntamente do código verificador (token, sms etc), conforme
apresentado nos elementos da requisição "Create Item with MFA". Cada
instituição apresenta elementos específicos (payloads), necessários para a
conexão. Listamos cada uma das instituições relativas a este fluxo e suas
especificidades abaixo:

a) Conta Sandbox (Pluggy Bank)

Utilizando a conta Sandbox (Pluggy Bank) você pode testar a sua

implementação sem precisar efetuar movimentações financeiras reais.
Com ele, você pode testar diversos cenários sem afetar a sua conta de
produção. Abaixo, seguem as credenciais utilizadas para conectar com o
Pluggy Bank:

- User: user-ok
- Password: password-ok
- Token: 123456
7
 - Pluggy Bank:
{
"connectorId": 4,
"parameters": {
"user": "",
"password": "",
"token":""
},
"webhookUrl": ""
}

b) Instituições Financeiras

- Bradesco:
{
"connectorId": 203,
"parameters": {
"agency": "",
"account": "",
"password": "",
"token": ""
},
"webhookUrl": ""
}

2.3 Conectores com código verificador em duas etapas

Utilizando a conta Sandbox (Pluggy Bank) você pode testar a sua

implementação sem precisar efetuar movimentações financeiras reais.
Com ele, você pode testar diversos cenários sem afetar a sua conta de
produção. As credenciais que devem ser enviadas junto ao payload abaixo,
estão disponíveis neste link.

Neste fluxo, o parâmetro para inserção de código verificador será

solicitado após as credenciais do usuário serem validadas. Dessa forma, é
necessário enviar as credenciais e aguardar a validação para que seja
possível o envio do código verificador.

8
Nota: Para checar se as credenciais foram validadas e o código verificador
já deve ser enviado, basta acessar a coleção de requisições (Postman
Collection), expandir a pasta "Items", selecionar a requisição “Specific
Item” e inserir o item_id como parâmetro da URL. Na resposta do serviço,
o token deve ser enviado quando os elementos "status" e
”executionStatus” apresentarem o valor "WAITING_USER_INPUT".
"status": "WAITING_USER_INPUT",

"executionStatus": "WAITING_USER_INPUT"

Neste momento, o código verificador deve ser enviado para que a conexão
seja estabelecida. Para enviar o código, basta acessar a coleção de
requisições (Postman Collection), expandir a pasta "Items" e selecionar a
requisição “Send MFA Parameter user-triggered”.

Na aba "Body", o código verificador deverá ser inserido conforme

apresentado nos elementos da requisição "Send MFA Parameter
user-triggered" (token, sms etc):

9
Cada instituição apresenta elementos específicos (payloads), necessários
para a conexão. Listamos cada uma das instituições relativas a este fluxo e
suas especificidades abaixo:

a) Conta Sandbox (Pluggy Bank)

Utilizando a conta Sandbox (Pluggy Bank) você pode testar a sua

implementação sem precisar efetuar movimentações financeiras reais.
Com ele, você pode testar diversos cenários sem afetar a sua conta de
produção. Abaixo, seguem as credenciais utilizadas para conectar com o
Pluggy Bank:

- User: user-ok
- Password: password-ok
- SMS: 123456

- Pluggy Bank:
{ "connectorId": 5,
"parameters": {
"user": "",
"password": ""
},
"webhookUrl": ""
}

● Send MFA Parameter user-triggered:

{
"sms": ""
}

10
 b) Instituições Financeiras
- Nubank:
{
"connectorId": 212,
"parameters": {
"cpf": "",
"password": ""
},
"webhookUrl": ""
}

● Send MFA Parameter user-triggered:

{
"code": ""
}

2.4 Teste de conexão

Neste manual, iremos conectar uma conta do banco "Itaú" pessoa física.
Logo, serão utilizados os seguintes elementos:
i. "agency": "número de sua agência"
ii. "account": "<número de sua conta>"
iii. "password": "<senha internet banking>"

11
Agora, basta inserir o id do conector de sua instituição financeira no
elemento "connectorId" e clicar no botão "Send" para que a conexão seja
estabelecida.
Pronto! A conexão com a instituição financeira foi estabelecida.

Na resposta da requisição, copie o id do item (conexão) criado. Este

identificador será utilizado para realizar as chamadas na conta conectada.

2.5 ClientUserId
O atributo clientUserId é um parâmetro que deve ser enviado pelo nosso
cliente para a API, visando identificar qual dos seus usuários está

12
realizando uma conexão. Em outras palavras, é um identificador único do
usuário. Pode ser qualquer ID interno do cliente que possa ajudá-lo a
associar a conexão criada (item id) ao usuário que a criou.

Dessa forma, temos a possibilidade de vincular a criação de um item_id

(conexão com uma instituição) com o usuário que realizou a conexão.

Este parâmetro diz respeito ao identificador que o usuário final possui na

sua base do nosso cliente, ou seja, o id a ser enviado é o mesmo usado no
controle interno do cliente, usado para identificar cada cliente.

Para envio do clientUserId através da API, basta enviar este parâmetro no

payload de criação de item (POST Create Item).

3. Realizar chamadas para obtenção de uma conta

Nesta seção, vamos aprender a realizar uma chamada e obter resposta

com informações sobre cada conta que o usuário mantém com a
instituição financeira conectada.

Na coleção de requisições (Postman Collection), expandir a pasta

"Accounts" e selecionar a requisição "Accounts by Item ID";

Na URL da requisição, incluir o id do item obtido no fluxo de conexão de conta

no parâmetro "itemId", localizado ao final da URL

13
Clicar no botão "Send".

Na resposta da requisição serão apresentados todos os vínculos do usuário

com a instituição financeira conectada.

Serão apresentados os ids de cada conta, usados para obter as transações

nelas realizadas, além do nome e tipo da conta, balanço e outras
informações.

Nota: Salvar o id das contas para utilização nas chamadas de transação

14
15
4. Realizar chamadas para obtenção de transações por
conta

Nesta seção, vamos aprender a realizar uma chamada e obter os dados de

transações de até 12 meses em cada conta vinculada à instituição
financeira conectada.

Na coleção de requisições (Postman Collection), expandir a pasta

"Transactions" e selecionar a requisição "Transaction by Account ID".

Na URL da requisição, incluir o id da conta a qual se quer obter os dados.

É possível filtrar os resultados da chamada através dos parâmetros

inseridos na URL, como:
i. "from": define a data inicial dos dados retornados (ex.:
"from=2020-01-01");
ii. "to": define a data final dos dados retornados (ex.:
"to=2020-02-01")
iii. "page": define a página a ser exibida (ex.: "page=1");
iv. "pageSize": define quantos dados serão exibidos por página
(ex.: "pageSize=50");

Caso queira mostrar todos os dados disponíveis na conta, não é necessário

o preenchimento de todos os parâmetros da URL.

Apenas insira o id da conta (accountId) desejada e clique no botão "Send".

16
Retorno de transações da conta corrente:

Retorno de transações de crédito:

17
18
5. Realizar chamadas para obtenção de transações de
investimento

Nesta seção, vamos aprender a realizar uma chamada e obter os dados

relacionados a transações de investimento.

Os dados de investimento serão obtidos através do id do item (conta

conectada).

Na coleção de requisições (Postman Collection), expandir a pasta

"Investiments" e selecionar a requisição "Investiments by Item ID";

Na URL da requisição, incluir o id do item:

Na resposta da requisição, serão encontrados todos os dados referentes

aos investimentos existentes na instituição financeira conectada:

19
20
6. Realizar chamadas para obtenção da identidade

Nesta seção, vamos aprender a realizar uma chamada para obter os dados
relacionados ao titular da conta conectada com a API Pluggy.

Cada conexão com uma instituição financeira irá trazer os dados pessoais
de identificação do titular da conta, como nome, telefone, e-mail.

Na coleção de requisições (Postman Collection), expandir a pasta

"Identities" e selecionar a requisição "Identity by Item ID";

Na URL da requisição, incluir o id do item:

21
7. Webhook
Também chamado de “retorno de chamada web”, webhook é um recurso
utilizado para que dados sejam retornados automaticamente, em tempo
real, sempre que um evento ocorrer.

Desta forma, sempre que um determinado evento ocorrer, os dados serão

automaticamente atualizados e enviados para a URL informada e você será
notificado sem a necessidade de realizar uma chamada.

Atualmente, os eventos disponíveis são:

i. item/created: criação de novo item, ou seja, nova conexão com
instituição financeira realizada com sucesso;
ii. item/updated: conexão com instituição financeira atualizada e
sincronizada com sucesso;
iii. item/error: erro encontrado em conexão com instituição
financeira;
iv. item/waiting_user_input: usuário necessita informar algum
dado para que conexão com instituição financeira seja concluída;
v. all: Receber todos os eventos;

O evento desejado deve ser informado na criação de um novo webhook.

Criação de webhook:

Cria um webhook vinculado ao evento e URL informados

Na coleção de requisições (Postman Collection), expandir a pasta

"Webhook" e selecionar a requisição "Create Global Webhook".

22
No corpo da requisição (aba "Body"), informar os dados do webhook nos
elementos:
i. "event": Tipo de evento desejado;
ii. "url": Endereço para ser notificado dos eventos realizados;

Após clicar no botão "Send" será retornada a resposta da requisição, na

qual irá conter o id do webhook criado.

Nota: o Id do webhook será utilizado para atualização ou deleção do

webhook criado.

23
 Atualização de webhook:
Na coleção de requisições (Postman Collection), expandir a pasta
"Webhook" e selecionar a requisição "Update Webhook".

É necessário informar o id do webhook na URL da requisição.

No corpo da requisição (aba "Body"), informar os dados a serem

atualizados no webhook nos elementos:
i. "event": Tipo de evento desejado;
ii. "url": Endereço para ser notificado dos eventos realizados;

24
Após clicar no botão "Send", serão exibidos os dados de confirmação da
atualização.

Deleção de webhook:
Na coleção de requisições (Postman Collection), expandir a pasta
"Webhook" e selecionar a requisição "Delete Webhook ".

É necessário informar o id do webhook a ser deletado na URL da

requisição.

25
Após clicar no botão "Send", serão exibidos os dados de confirmação da
deleção.

Pronto! Agora você já pode começar a testar suas

chamadas na API Pluggy via Postman!

26