Conecte uma conta

Nesta seção, aprenderemos como conectar a API Pluggy com uma instituição financeira.

Cada entidade financeira terá um conector e payloads específicos necessários para a conexão que devem ser preenchidos no corpo da solicitação no Postman.

Esses payloads obrigatórios são encontrados na resposta da List Connectors (GET /connectors), no campo credentials dentro de cada objeto Connector. Cada uma dessas credenciais representa a definição da estrutura para cada parâmetro que precisa ser enviado, para resolver a etapa de login.

Existem conectores que também exigem um parâmetro adicional de Autenticação Multifatorial (MFA). Temos dois cenários possíveis aqui:

O parâmetro MFA pode ser resolvido pelo usuário sozinho, sem um prompt da instituição financeira, por exemplo, com o Google Authenticator. Nesse cenário, o parâmetro será encontrado dentro do payload credentials, terá o campo "mfa": true definido. Ele deve ser enviado na etapa inicial de login.
O parâmetro MFA só pode ser resolvido pelo usuário ao completar um desafio gerado pela instituição financeira, como um token enviado por e-mail ou SMS, escaneando um código QR ou respondendo a algum outro prompt. Os detalhes para resolver esse parâmetro serão encontrados após o login bem-sucedido, na resposta do Retrieve Item (GET /items/:id), no payload parameter. Em seguida, o valor do parâmetro deve ser enviado com o endpoint Send Item MFA (POST /items/:id/mfa).

Conectores com esse cenário podem ser distinguidos pelo campo "mfa": true na base da definição do payload do conector.

Portanto, vamos dividir os conectores para facilitar a compreensão:

Conectores sem código de verificação
Conectores com código de verificação de uma etapa ("MFA 1-step")
Conectores com código de verificação de duas etapas ("MFA 2-step")

Conectores sem código de verificação #

Para conectar uma conta que não precisa de um código de validação extra, basta acessar a Coleção Postman, expandir a pasta "Items" e selecionar a solicitação "Create Item".

Na aba "Body", insira suas credenciais nos elementos apresentados na solicitação "Create Item".

Listamos cada uma das instituições e suas especificidades abaixo:

Itau PF #

{
  "connectorId": 201,
  "parameters": {
    "agency": "",
    "account": "",
    "password": ""
  },
  "clientUserId": ""
}

Para o Itau PF recuperar Dados de Pagamento, é necessário atualizar o item pelo menos uma vez. Para o Itau PF com conta conjunta, consulte abaixo (Fluxos de Exceção).

Caixa PF #

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

Para o Caixa PF, consulte abaixo (Fluxos de Exceção).

Caixa PJ #

{
  "connectorId": 216,
  "parameters": {
    "user": "",
    "password": ""
  },
  "clientUserId": ""
}

Santander PF #

{
  "connectorId": 208,
  "parameters": {
    "user": "<cpf>",
    "password": ""
  },
  "clientUserId": ""
}

Agora #

{
  "connectorId": 220,
  "parameters": {
    "cpf": "",
    "password": "",
    "signature": ""
  },
  "clientUserId": ""
}

Genial #

{
  "connectorId": 213,
  "parameters": {
    "email": "",
    "password": ""
  },
  "clientUserId": ""
}

Sicredi PJ #

{
  "connectorId": 227,
  "parameters": {
    "cnpj": "",
    "user": "",
    "password": ""
  },
  "clientUserId": ""
}

Clear #

{
  "connectorId": 223,
  "parameters": {
    "user": "",
    "password": ""
  },
  "clientUserId": ""
}

Sicoob PJ / Sicoob PF #

{
  "connectorId": 228,
  "parameters": {
    "cooperativa": "",
    "chaveAcesso": "",
    "password": ""
  },
  "clientUserId": ""
}

Conectores com código de verificação de uma etapa ("MFA 1-step")#

Para conectar uma conta que solicita um código de validação extra em uma única etapa de login, basta acessar a Coleção Postman, expandir a pasta "Items" e selecionar a solicitação "Create Item with MFA".

Na aba "Body", suas credenciais para acessar a instituição devem ser inseridas junto com o código de verificação (token, SMS, etc), conforme apresentado nos elementos da solicitação "Create Item with MFA".

Conector "MFA 1-step"

Você pode detectar quais instituições estão incluídas neste cenário, encontrando o valor "mfa": true, em um dos objetos credentials, dentro dos conectores na resposta da List Connectors.

Inter #

{
  "connectorId": 215,
  "parameters": {},
  "clientUserId": ""
}

{
  "connectorId": 204,
  "parameters": {
    "user": "<cpf>",
    "password": "",
    "token": ""
  },
  "clientUserId": ""
}

XP #

{
  "connectorId": 202,
  "parameters": {
    "account": "<account number or CPF>",
    "password": "",
    "token": ""
  },
  "clientUserId": ""
}

Rico #

{
  "connectorId": 205,
  "parameters": {
    "user": "",
    "password": "",
    "token": ""
  },
  "clientUserId": ""
}

Conta Simples #

{
  "connectorId": 283,
  "parameters": {
    "email": "<email>",
    "password": "",
    "token": ""
  },
  "clientUserId": ""
}

Conectores com código de verificação de duas etapas ("MFA 2-step")#

Neste fluxo, o parâmetro para inserir o código de verificação será solicitado após as credenciais do usuário serem validadas. Assim, é necessário enviar as credenciais e aguardar a validação para que o código de verificação possa ser enviado.

Conector "MFA 2-step"

Você pode detectar quais instituições estão incluídas neste cenário, encontrando o valor "mfa": true, nas definições básicas de um Conector, encontrado na resposta da List Connectors.

Para verificar se as credenciais foram validadas e o código de verificação já deve ser enviado, basta acessar a Coleção Postman, expandir a pasta "Items", selecionar a solicitação "Specific Item" e inserir o item_id como um parâmetro da URL. Na resposta do serviço, o token deve ser enviado quando os elementos status e executionStatus tiverem o valor WAITING_USER_INPUT.

Neste ponto, o código de verificação deve ser enviado para que a conexão seja estabelecida. Para enviar o código, basta acessar a Coleção Postman, expandir a pasta "Items" e selecionar a solicitação "Send MFA Parameter user-triggered".

Na aba "Body", o código de verificação deve ser inserido conforme mostrado nos elementos da solicitação "Send MFA Parameter user-triggered" (token, sms, etc).