Skip to content

Pluggy API Connect

Documentação para colaborar e facilitar a integração e desenvolvimento das interfaces ligadas ao ecossitema do Open Finance.

O documento abordará a estrutura dos endpoints disponíveis no serviço da Pluggy, assim como explicações para alguns pontos que merecem um pouco mais de atenção.

Informações mais detalhadas podem ser encontradas no Guia da Pluggy

Ambiente e Configurações

O widget da Pluggy pode ser configurado de acordo com a necessidade do projeto, além de poder ser customizado com as cores e com as imagens da VLGI. Os principais atributos que podem ser configurados são:

  • includeSandbox: para mostrar o conector de teste
  • allowFullScreen: Para ser mostrado na tela inteira ou como uma modal
  • connectorIds: Para restringir as instituições mostradas
  • theme: Para determinar o tema do widget
  • Alguns callbacks estão disponíveis (onSuccess, onError, onOpen, onClose, onHide, onEvent): Os eventos podem ser obtidos a partir do Webhook.

Segurança

É necessário realizar requisições HTTPS TLSv1.2 para ser aceito pelo servidor da Pluggy. Outras versões do TLS serão recusadas.

OBS: Outras configuraçõs podem ser encontradas no guia

Comunicação com o servidor da Pluggy

Utilizam webhooks para realizar uma comunicação com o servidor da Pluggy, o que pode ser necessário para escutar eventos e receber atualizações sobre novos dados.

Authentication

Inicialmente, a API da Pluggy trabalha com quatro principais variáveis de configuração e permissão.

  • CLIENT_ID: Utilizada para criar um Connect Token. Disponível no dashboard da equipe.
  • CLIENT_SECRET: Utilizada para criar um Connect Token. Disponível no dashboard da equipe.
  • Connect Token: Utilizado pelo lado do cliente. O seu uso tem acesso a apenas os endpoints de informações do 'Item' ( explicado mais à frente ) e uma parte limitada das informações de conta. Validade de 30 minutos.
  • API_KEY: Utilizada pelo servidor no Header das requisições. Validade de 2 horas.

Rotas

  • POST (/auth): Criação de API_KEY.
  • POST (/connect_token): Criação de Connect Token.

Connectors

Os 'Connectors' são as instituições disponíveis para conexão, assim é possível verificar todos os 'Connectors' disponíveis na API. Existem rotas para pegar todos, assim como um connector em específico.

Dados Obrigatórios

Dentro do contexto dessas instituições, as seguintes informações são sempre disponibilizadas:

  • ID
  • Informações das credenciais necessárias ( quais os campos para login ) -> inclui os placeholders e mensagens de validação na hora de conectar nesta instituição.

Dados opcionais

Dentro do contexto dessas instituições, as seguintes informações podem ser disponibilizadas:

  • Nome
  • Cor primária
  • Link da instituição
  • País
  • Tipo da Instituição
  • Logo da instituição
  • Utilização de MFA
  • Informações sobre a saúde daquele conector ( Connection Error )
  • Produtos disponíveis ( ACCOUNT, TRANSACTIONS, IDENTITY )...

Rotas

  • GET (/connectors): Todos os connectors disponíveis na Pluggy.
  • Para acessar o sandbox também, conector teste, basta passar 'sandbox=true' como query params.

  • É possível acessar conectores de um país em específico, utilizando o params 'countries[]'.

  • GET (/connectors/:connectorId): Informações de um conector em específico.

Items

Um item é uma representação de uma conexão com um conector de alguma instituição, sendo o ponto de entrada para acessar os dados dos produtos presentes nesta determinada instituição.

A maneira mais fácil de criar esse item é a partir do Pluggy Conect Widget oferecido por eles. Esse widget fica responsável por realizar todo o flow de consentimento, credencial e autenticação da instituição, mas se necessário isso pode ser feito por nós.

Ao criar um item, os dados dos produtos dos últimos 365 dias são disponibilizados.

A atualização dos dados de um determinado item-id é feito tanto pelo auto-sync disponibilizado pela Pluggy, ou passando o connectToken e um 'updateItem' para o Connect, assim ele fará um merge dos dados já disponíveis com os novos dados que estão chegando, o que acaba sendo bem mais eficiente do que criar um item toda vez.

  • Existem algumas ocasiões em que esse fluxo tem alguns detalhes a mais, como por exemplo quando a instituição tem MFA, sendo necessário enviar esse token também para que o login seja bem sucedido.

O item-id é responsável por apontar as credenciais de um usuário em determinada instituição ( credenciais armazenadas no servidor da Pluggy ). Por conta disso, eles possuem um recurso de auto-sync em que os itens são atualizados a cada 24/12/8 horas, a depender da configuração no dashboard, o que torna não necessário o processo de batch para atualizar as informações dos produtos disponíveis nessa instituição.

OBS: Auto-sync disponível apenas em produção, não sendo possível testar.

Entretanto, pode ser que seja necessário uma atualização fora do período mencionado acima, o que também é possível ser feito via API.

Para receber as notificações e os eventos relacionados à atualização de determinado item é utilizado Webhook Notifications.

  • O Lifecycle dos itens, assim como os erros e validações podem ser encontrados no guia da Pluggy.

Rotas

  • POST (/items): Cria um novo item.

  • 'connectorId' e 'parameters' contendo as credenciais necessárias para o login em determinada instituição são obrigatórios.

  • GET (/item/:itemId): Informações de um item em específico.

  • PATCH (/item/:itemId): Atualiza as informações de um item em específico.
  • Se a instituição tiver MFA é necessário enviar o token dentro do 'parameters'.
  • DELETE (/item/:itemId): Deleta um item em específico.
  • POST (/item/:itemId/mfa): Envia o MFA token quando o status é WAITING_USER_INPUT.

Accounts

Simboliza a conta bancária, podendo ser de alguns tipos diferentes, como por exemplo uma conta poupança, ou algo do tipo, ou então uma conta de uma cartão de crédito. A depender do tipo de conta as informações retornadas na response mudam.

Dados Obrigatórios

As informações que sempre são retornadas, independente do tipo de conta são:

  • Id da conta
  • Tipo (BANK/CREDIT)
  • Subtipo (CHECKING ACCOUNT / SAVING ACCOUNT / CREDIT_CARD)
  • Número: Para BANK retorna o número da conta, para CREDIT os últimos 4 dígitos do cartão
  • Nome da conta
  • Saldo : Para BANK o saldo da conta, para CREDIT o valor da fatura que está em aberto
  • Código: Código utilizado, podendo ser USD ou EUR.
  • ID do item

Como comentado anteriormente, se a conta for do tipo CREDIT ela retorna junto um 'creditData' e se for do tipo BANK retorna um bankData.

BANK DATA:

  • Número de transferência: COMPE / Agência / Conta
  • Saldo atual

CREDIT DATA:

  • Limite disponível
  • Limite total
  • Flag se o cartão é ilimitado
  • Data de vencimento do crédito
  • Data de fechamento da fatura
  • Marca do cartão (Mastercard, Visa, Elo...)
  • Level do cartão (Black, Signature...)

Dados Opcionais

As informações que podem ser retornadas são:

  • Market Name da conta
  • Nome do dono
  • Tax Number do dono

Rotas

  • GET (/accounts): Retorna todas as contas de um determinado item
  • GET (/accounts/{id}): Retorna os dados de uma determinada conta

Transactions

As transações de um usuário são importantes por terem informações valiosas sobre o perfil financeiro do cliente. As transações utilizam um categorizador própio da Pluggy

Dados Obrigatórios

As informações que sempre retornadas são:

  • Id da transação
  • Data de postagem da transação
  • Descrição oferecida pela instituição
  • Código da moeda da transação (BRl, USD, ARS)
  • Valor da transação

Dados Opcionais

As informações que podem ser retornadas são:

  • Descrição bruta oferecida pela instituição
  • Categoria (feito pela Pluggy)
  • Código de transação do provedor
  • Status da transação (POSTED / PENDING)
  • Tipo da transação (CREDIT / DEBIT)
  • Dados do pagamento
    • Razão da transferência (indicada pelo cliente)
    • Número de referência
    • Método de pagamento (TED / DOC / PIX)
    • Dados do pagador
      • Número do documento
      • Nome completo do participante
      • Número da conta
      • Número da agência
      • Número COMPE do banco
      • Número ISPB do banco
    • Dados do recebedor (mesmos dados retornados no objeto do pagador acima)
  • Dados relativos ao estabelecimento comercial associado à transação.
    • Nome Fantasia
    • Nome empresarial
    • CNPJ
    • CNAE
    • Categoria

Rotas

  • GET (/transactions): Retorna as transções de uma determinada conta
  • GET (/transactions/{id}): Retorna os dados de uma transação em específico
  • POST (/transactions/{id}) Como comentado anteriormente, as transações possuem uma categoria que é definida pelo próprio sistema da Pluggy. A rota em questão permite atualizar a categoria da transação passando um 'categoryId' diferente como parâmetro.

Transaction Categorization

Como comentado, a Pluggy possui um serviço baseado em inteligência artificial para categorizar uma determinada transação, o que permite agrupar os gastos de um determinado usuário de acordo com a categoria. Entretando, existe algumas trasações (em teste tinham algumas), que o serviço deles não consegue categorizar, retornando 'null' no campo referente à categoria.

As categorias são organizadas em uma árvore, tendo níveis mais gerais e níveis mais específicos. Para melhor visualização das categorias disponíveis basta visualizar o final do documento neste link

A API oferece autonomia para criar novas categorias e regras para clientes específicos, assim, se for necessário, é possível criar as próprias categorias e ter mais controle sobre este aspecto.

Rotas

  • GET (/categories): Retorna todas as categorias
  • GET (/categories/{id}): Retorna uma categoria específica
  • GET (/categories/rules): Retorna todas as regras de um cliente específico
  • POST (/categories/rules): Cria uma regra para um cliente específico
  • GET (/categories/rules/{id}): Retorna regra específica
  • POST (/categories/rules/batch): Cria uma única regra

Investments

Os investimentos são retornados dos Brokers e dos Business Bank.

A lista de investimentos é diferente de acordo com o tipo de investimento que cada instituição possui.

Dados Obrigatórios

Os dados retornados para os investimentos são:

  • Id do Investimento
  • Nome do investimento no provedor
  • Tipo (InvestmentType)
  • Valor do investimento
  • Código da moeda de transação (USD...)
  • Data da cota do valor

Dados Opcionais

Os dados que podem ser retornados são:

  • Código do investimento
  • ISIN
  • Número do investimento
  • Beneficiário do investimento
  • Subtipo (Subinvestment Type)
  • Taxa de desempenho do investimento no último mês
  • Taxa de desempenho do investimento no último ano
  • Valor da cota na data retornada
  • Quantidade de cotas
  • Imposto de renda aplicado ao investimento
  • Imposto financeiro aplicado ao investimento
  • Saldo líquido do investimento
  • Data de expiração
  • Percentual de taxa fixa aplicada ao investimento.
  • Tipo da taxa fixa (CDI / SELIC / DOLAR ...)
  • Taxa anual de renda fixa
  • Entidade que emitiu o investimento
  • Data de emissão
  • Lucro líquido até o momento ( ou prejuízo )
  • Quantidade disponível para saque
  • Valor originalmente investido
  • Status (ACTIVE / PENDING / TOTAL_WITHDRAW)
  • Instituição
  • Metadado (O objeto de metadados contém "Dados de Títulos" para portabilidade de Previdência Privada.)
  • Provider id

Descrições sobre "Investment Status", "Investment Institution", "Investment Types & Subtypes" e "Investment Metadata" podem ser encontrados no guia

Rotas

  • GET (/investments): Retorna todos os investimentos de um determinado 'itemId'
  • GET (/investments/{id}): Retorna um investimento em específico

Investments Transactions

Dentro de um investimento existem transações de aplicação e de saque. Essas transações possuem informações obirgatórias como:

  • Tipo (BUY / SELL / TAX / TRANSFER)
  • Data em que a transação foi liquidada

Exisatem informações que também podem ser retornadas como:

  • Data em que a trasação foi realizada
  • Quantidade de cotas
  • Valor pelo qual foi adquirido
  • Valor da transação
  • Descrição da transação
  • Número do broker
  • Valor incluindo despesas
  • Despesas (Expenses)

Expenses

Dados referentes à nota de corretagem quando se é comprado ativos negociados na bolsa de valores, que representa a situação diária de um investidor no mercado financeiro. Os impostos cobrados em cada operação são agrupados nesse objetos.

Dados

Os dados presentes nesse objeto são todos opcionais:

  • Taxa de serviço
  • Taxa do Broker
  • Taxa de imposto de renda
  • Outros impostos não definidos
  • Taxa de Aviso de Negociações de Ativo (ANA)
  • Taxa de Manutenção
  • Taxa de Liquidação
  • Taxa de Registro
  • Taxa de Exchange
  • Taxa de custódia
  • Taxa de operação

Identity

Essa entidade é responsável por retornas dados pessoais do titular da conta. Esses dados são armazenados pelas instituições. Ela ajuda a verificar a identidade do usuário

Dados

Os dados disponibilizados são todos opcionais:

  • Nome Completo
  • Nome da empresa (para business conector)
  • Documento
  • Tipo do documento
  • CNPJ associado (em caso de conta empresarial)
  • Profissão
  • Data de aniversário
  • Endereços
  • Números de telefone
  • Emails
  • Relações
  • Perfil do Investidor (Conservative, Moderate or Aggressive)

Schema de Endereço

  • Endereço completo
  • País
  • Estado
  • Cidade
  • Código postal
  • Endereço primário
  • Tipo (Personal, Work)

Schema de Email

  • Tipo (Personal, Work)
  • Email

Schema de telefone

  • Tipo (Personal, Work, Residencial)
  • Telefone

Schema de Relação

  • Tipo (Father, Mother, Spouse)
  • Nome completo

Rotas

  • GET (/identity): Retorna a identidade do proprietário de determinado item
  • GET (/identity/{id}): Retorna uma identidade a partir de um 'identityId'

Opportunity (BETA)

As oportunidades são todas as ofertas oferecidas pelos bancos para obter um crédito de diferentes tipos, essas ofertas podem ser cartões de crédito pré-aprovados, empréstimos pessoais, empréstimos comerciais, entre outros.

Dados

  • Limite total
  • Limite utilizado
  • Limite disponível
  • Quantidade máxima de cotas
  • Tipo das cotas (OpportunityDateType)
  • Taxa de juros
  • Tipo da taxa de juros (OpportunityDateType)
  • Tipo (OpportunityType)
  • Nome comercial
  • Descrição
  • Data
  • Código da moeda (USD, BRL...)

OpportunityDateType: MONTHLY / YEARLY

OpportunityType: CREDIAT_CARD / PERSONAL_LOAN / BUSINESS_LOAN / MORTAGE_LOAN / VEHICLE_LOAN / OVERDRAFT / OTHER_LOAN / OTHER

Rotas

  • GET (/opportunities): Retorna as oportunidades de um determinado item

Portfolio Yield (BETA)

Portfolio Yield é a entidade relacionada ao rendimento da carteira. A recuperação deste produto permitirá uma fácil compreensão do desempenho de todos os ativos do usuário em períodos específicos, fornecendo um status atual consolidado.

Existem dois objetos distintos para o rendimento de carteira: Carteira Agregada e Carteira Mensal

Aggregated Portfolio Schema

Possui dados dos últimos 12 meses ou do último ano do usuário.

Dados

  • Saldo total
  • Rendimento percentual durante o período
  • Valor do rendimento durante o período
  • Moeda do valor acima
  • Data em que a carteira foi capturada
  • Data de referência da carteira
  • Porcentagem de rendimento de desempenho em relação ao tipo de índice
  • Período: CURRENT_YEAR / LAST_TWELVE_MONTHS

Rotas

  • GET (/portfolio/{itemId}): Traz a carteira agregada de um determinado item

Monthly Portfolio Schema

Traz os dados do rendimento da carteira mensal de todos os ativos que o usuário possui. É retornado a quantidade de relatórios mensais que o banco disponibiliza.

Dados

  • Saldo total
  • Rendimento percentual durante o período
  • Valor do rendimento durante o período
  • Moeda do valor acima
  • Porcentagem de rendimento de desempenho em relação ao tipo de índice
  • Flag de currentMonth se for o mês atual
  • Primeiro dia do mês de referência

Rotas

  • GET (/portfolio/{itemId}/monthly): Carteira Mensal de um determinal item

Income Report (BETA)

Entidade responsável pelo Relatório de Renda. A partir dessa entidade os usuários tem acesso às informações necessárias para apresentar no Imposto de Renda Anual

É responsável por retornar os metadados dos documentos. A URL retornada no schema tem validade de apenas 1 hora

Dados

  • URL
  • Ano que o documento pertence

Rotas

  • GET (/income-reports): Retorna os documentos de um item, se disponíveis.