POST/items

Criar

Cria um item e sincroniza todos os produtos com a instituição financeira, usando como credenciais os parâmetros enviados.

Para enviar as credenciais do connector, vamos montar um objeto de credenciais. Esse objeto contém cada credencial necessária para executar o connector, conforme detalhado em GET /connectors, que retorna um array credentials.

O objeto é criado como pares chave-valor: o name da credencial é a chave, e o que o usuário informou é o valor.

Exemplo:

{
	 "credentials": [
     {
       "label": "Agência",
       "name": "agency",
       "type": "number",
       "placeholder": "Agência",
       "validation": "^\\d{4}$",
       "validationMessage": "O agencia deve ter 4 dígito"
     },
     {
       "label": "Conta",
       "name": "account",
       "type": "number",
       "placeholder": "Conta",
       "validation": "^\\d{4,6}$",
       "validationMessage": "O conta deve ter 6 dígito"
     },
     {
       "label": "Senha",
       "name": "password",
       "type": "number",
       "placeholder": "Senha",
       "validation": "^\\d{6}$",
       "validationMessage": "O senha deve ter 6 dígito"
     }
	 ]
}

{
  "agency": "1234",
  "account": "123456",
  "password": "123456"
}

Credenciais criptografadas

Ao criar um Item, você pode enviar os parâmetros (credenciais do usuário) criptografados. Isso dá aos nossos clientes a possibilidade de adicionar mais uma camada de segurança ao conectar contas.

Para isso, primeiro solicite ao nosso time de operações a criação de uma chave pública RSA para a sua aplicação. Depois, na sua linguagem de programação e usando essa chave pública, criptografe o objeto parameters, codifique o resultado em Base64 e envie essa string como parameters no lugar do objeto.

A mesma lógica vale para atualizações, no caso de atualização de credenciais.

Considerações técnicas: o padding usado para criptografar/descriptografar é RSA_PKCS1_OAEP_PADDING

Request Body

required

object

Create Item Request

connectorIdrequirednumber

Identificador principal do conector

parametersrequiredobject

Credenciais do conector que são necessárias para executar em um objeto Key-Value ou uma string se estiverem criptografadas

<key>string

One of:

option 1object

option 2string

webhookUrlstring (uri)

Url para ser notificado sobre mudanças de item

clientUserIdstring

Identificador externo do cliente para o usuário, pode ser um ID, UUID ou até mesmo um e-mail. Isso é livre para os clientes usarem.

oauthRedirectUristring (uri)

URI de redirecionamento necessária para o fluxo Oauth

productsstring[]

Produtos a serem coletados na conexão

itemsstring

ACCOUNTSCREDIT_CARDSTRANSACTIONSPAYMENT_DATAINVESTMENTSINVESTMENTS_TRANSACTIONSIDENTITYBROKERAGE_NOTEMOVE_SECURITYLOANS

avoidDuplicatesboolean

Evita criar um novo item se já houver um com as mesmas credenciais

Example

json

{
  "connectorId": 2,
  "parameters": {
    "user": "user-ok",
    "password": "password-ok"
  },
  "webhookUrl": "https://example.com/webhook"
}

Responses

200Item criado

object

Item object

idrequiredstring

Identificador principal

connectorobject

Connector object

idrequirednumber (integer)

Identificador principal

namestring

Nome da instituição

institutionUrlstring

Página inicial da instituição

imageUrlstring

Imagem do logotipo hospedado pelo Pluggy

primaryColorstring

Cor primária

typestring

Tipo de instituição

countrystring

País localizado

credentialsobject[]

Parâmetros necessários para iniciar a conexão

hasMFAboolean

O conector requer um MFA para ser executado?

productsstring[]

Produtos suportados pelo conector

productCoveragestring[]

Which sub-products the institution serves, in the Open Finance directory's own vocabulary (for example INVESTMENTS:TREASURE_TITLES, CREDIT_OPERATIONS:INVOICE_FINANCINGS). Where products says whether the connector serves investments at all, this says which ones: a connector listing INVESTMENTS may serve one of the five investment resources or all five. Absent for direct connectors, which have no Open Finance participant.

oauthboolean

Se 'true', o conector requerirá um fluxo Oauth para ser executado

oauthUrlstring

URL para realizar o fluxo Oauth, se necessário

resetPasswordUrlstring

URL para a instituição financeira para redefinir a senha

healthobject

Connector health status

isOpenFinanceboolean

Indica se o conector utiliza as APIs regulamentadas de Open Finance

isSandboxboolean

Indica se o conector é um conector de sandbox, destinado a testes em vez de uma instituição real

supportsPaymentInitiationboolean

Indica se o conector suporta a API de iniciação de pagamento

supportsScheduledPaymentsboolean

Indica se o conector suporta pagamentos agendados

supportsSmartTransfersboolean

Indica se o conector suporta transferências inteligentes

supportsBoletoManagementboolean

Indica se o conector suporta gerenciamento de boleto

supportsAutomaticPixboolean

Indica se o conector suporta Pix automático

createdAtstring (date-time)

Data de criação

updatedAtstring (date-time)

Data da última modificação

statusrequiredstring

Status do Item

executionStatusrequiredstring

Status da execução da sincronização

errorobject

Mensagem de erro detalhada

coderequiredstring

Error code

messagerequiredstring

Detailed error message

providerMessagestring

Information provider by the institution mainly when user needs to perform an action

attributesobject

'{ [key]:[value] }'. Additional information necessary for future executions, used for example in some device authorization flow

parameterobject

Credential details for a connector

namerequiredstring

Nome da chave

labelrequiredstring

Rótulo para entrada

typerequiredstring

Tipo de credencial necessária

textpasswordnumberimageselect

assistiveTextstring

Texto para ajudar o usuário ao preencher a entrada

datastring

Usado para retornar imagens em base64

placeholderstring

Texto de exemplo para a entrada

validationstring

Validação de regex para a entrada do usuário

validationMessagestring

Mensagem de validação quando a entrada não corresponde à expressão regular

mfaboolean

A Credencial é um parâmetro MFA e deve ser atualizada a cada execução.

optionsobject[]

Lista de valores possíveis para a entrada

optionalrequiredboolean

Se a credencial pode ser deixada em branco. Sempre presente; padrão é falso.

instructionsstring

Instruções para ajudar o usuário a obter esta credencial

expiresAtstring (date-time)

Data de expiração do valor da credencial, quando a instituição define uma.

userActionobject

User action details for an item

instructionsrequiredstring

Instruções relacionadas à ação do usuário

attributesobject

'{ [key]:[value] }'. Informações adicionais relacionadas à ação do usuário, por exemplo, em algum fluxo de autorização de dispositivo

expiresAtstring (date-time)

Data de expiração da ação do usuário

typerequiredstring

Tipo de ação que o usuário deve realizar: escanear um código QR ou autorizar o acesso no aplicativo da instituição.

qrauthorize-access

webhookUrlstring

Url para ser notificado sobre mudanças de item

createdAtstring (date-time)

Data de criação

updatedAtstring (date-time)

Data da última modificação

lastUpdatedAtstring (date-time)

Data da última sincronização

statusDetailobject

Detailed status of the item. This field will be present when the status is PARTIAL_SUCCESS or when a product in the item has warnings

accountsobject