# 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 requerem um parâmetro adicional de Autenticação Multifatorial (MFA). Temos dois cenários possíveis aqui:

1. 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.

2. 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

```json
{
  "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

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

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

### Caixa PJ

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

### Santander PF

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

### Agora

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

### Genial

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

### Sicredi PJ

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

### Clear

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

### Sicoob PJ / Sicoob PF

```json
{
  "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

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

### Modal Mais

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

### XP

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

### Rico

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

### Conta Simples

```json
{
  "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, encontradas 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).

### Bradesco PJ

```json
{
  "connectorId": 209,
  "parameters": {
    "user": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Enviar parâmetro MFA acionado pelo usuário:

```json
{
  "token": ""
}
```

### B3 CEI

```json
{
  "connectorId": 222,
  "parameters": {
    "user": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Enviar parâmetro MFA acionado pelo usuário:

```json
{
  "code": ""
}
```

### BTG Pactual

```json
{
  "connectorId": 214,
  "parameters": {
    "cpf": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Enviar parâmetro MFA acionado pelo usuário:

```json
{
  "token": ""
}
```

### Safra

```json
{
  "connectorId": 214,
  "parameters": {
    "agency": "",
    "account": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Enviar parâmetro MFA acionado pelo usuário:

```json
{
  "value": ""
}
```

> Safra: o MFA será solicitado duas vezes na primeira execução do item. Depois, para atualizações de item, será solicitado apenas uma vez. Consulte abaixo "Safra" em Fluxos de Exceção.

### Avenue

```json
{
  "connectorId": 230,
  "parameters": {
    "email": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Enviar parâmetro MFA acionado pelo usuário:

```json
{
  "token": ""
}
```

### Genial

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

Enviar parâmetro MFA acionado pelo usuário:

```json
{
  "mfa": ""
}
```

### Empiricus Investimentos

```json
{
  "connectorId": 233,
  "parameters": {
    "cpf": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Enviar parâmetro MFA acionado pelo usuário:

```json
{
  "value": ""
}
```

## Conectores com Seleção de Empresa

Os conectores empresariais podem exigir que você selecione qual empresa deseja conectar, dependendo se o usuário que está acessando tem acesso a mais de uma única empresa.

Nesses casos, após inicializar o item com os parâmetros iniciais, você será solicitado a um parâmetro adicional.

Esse parâmetro pode ser recuperado do endpoint "Specific Item", enviando o id criado, e será do tipo `select` -- isso significa que um dos valores da lista deve ser enviado de volta para nós para seleção.

### Sicoob PJ

```json
{
  "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
  "status": "WAITING_USER_INPUT",
  "executionStatus": "WAITING_USER_INPUT",
  "lastUpdatedAt": null,
  "error": null,
  "paramater": {
    "type": "select",
    "name": "selectedCompany",
    "label": "Qual e a sua empresa?",
    "instructions": "Selecione a conta que deseja conectar",
    "options": [
      {
        "value": "9025000",
        "label": "902.500-0 One Company ltda"
      },
      {
        "value": "9025001",
        "label": "902.500-1 Second Company ltda"
      }
    ],
    "expiresAt": "2023-03-28T18:17:59.532Z"
  }
}
```

Uma vez que o usuário tenha selecionado a empresa, envie-a de volta usando o Endpoint Send MFA:

```json
{
  "selectedCompany": "9025000"
}
```

## Fluxos de Exceção

### Bradesco PF Conta Conjunta

O conector "Bradesco PF" está mapeado tanto para contas simples (individuais) quanto para contas conjuntas (Conta Conjunta).

Para conectar à conta conjunta, você pode simplesmente enviar qualquer valor "token" aleatório no endpoint "Create Item with MFA", por exemplo, `"000000"`, não importará porque a etapa de seleção da Conta, se aplicável, terá precedência e será resolvida primeiro.

```json
{
  "connectorId": 203,
  "parameters": {
    "agency": "",
    "account": "",
    "password": "",
    "token": "000000"
  },
  "clientUserId": ""
}
```

Faça chamadas no endpoint "Specific Item" passando o ItemId para verificar o status da conexão até que você obtenha o elemento `parameter` na resposta com o elemento `options` que contém a lista de contas registradas na instituição.

Em seguida, chame o endpoint "Send MFA Parameter user-triggered" com o valor da conta selecionada. Depois disso, o parâmetro token MFA precisará ser fornecido com o valor correto fornecido pelo usuário.

Continue fazendo chamadas no endpoint "Specific Item" até que o atributo `executionStatus` seja definido como `SUCCESS` (ou `PARTIAL_SUCCESS`), significando que sua conexão foi criada/atualizada com sucesso.

> **Dados recuperados:** Como esta é uma conta conjunta, tenha em mente que a Pluggy só coletará os dados da conta selecionada pelo usuário na primeira etapa.

### Banco do Brasil PJ

No caso do Banco do Brasil Empresas, para que a conexão seja estabelecida, será necessário usar um computador que seja o mesmo que já foi autorizado no internet banking. A conta utilizada para a conexão deve ter um celular registrado no Banco do Brasil, pois este receberá um link de confirmação a ser inserido no momento da conexão.

Primeiro, faça uma chamada no endpoint "Create Item":

```json
{
  "connectorId": 217,
  "parameters": {
    "userJ": "",
    "passwordJ": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Chame o endpoint "Specific Item" até que você obtenha `executionStatus` como `WAITING_USER_INPUT` e o atributo `parameter` com uma lista de celulares registrados na instituição. Selecione um telefone, em seguida, forneça o URL do token SMS recebido nesse telefone.

### Itau PF (Conta Conjunta)

Primeiro, faça uma chamada no endpoint "Create Item":

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

Em seguida, chame o endpoint "Specific Item" até que você obtenha o `executionStatus` como `WAITING_USER_INPUT`. O elemento `parameter` incluirá uma lista de contas (operadores). Selecione uma e envie-a via o endpoint "Send MFA Parameter user-triggered".

> Este parâmetro `operatorNumber` é solicitado apenas na primeira vez que o Item é criado, depois é armazenado e reutilizado para quaisquer atualizações subsequentes da mesma instância de Item.

### Itau PF (com MFA)

Algumas contas do Itau PF requerem MFA. Crie o item com as credenciais padrão, depois consulte o endpoint "Specific Item" até `WAITING_USER_INPUT` com `"name": "mfa"` no parâmetro. Envie o token MFA via o endpoint "Send MFA Parameter user-triggered".

### Itau PJ

O conector "Itau" está mapeado tanto para contas simples (individuais) quanto para contas conjuntas. Para conectar à conta conjunta, envie o nome do titular da conta via o endpoint "Send MFA Parameter user-triggered".

```json
{
  "connectorId": 218,
  "parameters": {
    "agency": "",
    "account": "",
    "password": "",
    "cpfOrOperator": ""
  },
  "clientUserId": ""
}
```

### XP (acesso CPF - conta conjunta)

O conector "XP" permite conectar tanto contas simples (acesso por número da conta) quanto contas conjuntas (com acesso CPF).

```json
{
  "connectorId": 202,
  "parameters": {
    "account": "",
    "password": "",
    "token": ""
  },
  "clientUserId": ""
}
```

Consulte o endpoint "Specific Item" até `WAITING_USER_INPUT` com um parâmetro `selectedAccount`, em seguida, envie o valor da conta selecionada.

### Santander PJ

Para o Santander PJ, a conexão requer escanear um código QR e enviar um código de validação extra.

```json
{
  "connectorId": 221,
  "parameters": {
    "agency": "",
    "account": "",
    "user": "",
    "password": ""
  },
  "clientUserId": ""
}
```

Consulte o endpoint "Specific Item" até `WAITING_USER_INPUT`. O `parameter` conterá uma imagem de código QR codificada em base64 no atributo `data`. Exiba o código QR, escaneie-o com um telefone e envie o token resultante via o endpoint "Send MFA Parameter user-triggered".

### Inter PJ

Este conector usa a API OAuth 2 do banco. Você precisa primeiro gerar e obter `clientId`, `clientSecret`, os arquivos `API_Chave.key` e `API_Certificado.crt` da conta bancária do cliente.

A chave privada e o certificado devem ser fornecidos em base64 sem quebras de linha entre o cabeçalho e o rodapé de cada arquivo.

```json
{
  "connectorId": 225,
  "parameters": {
    "clientId": "",
    "clientSecret": "",
    "privateKey": "",
    "certificate": ""
  },
  "clientUserId": ""
}
```

### BTG Pactual, Empiricus e EQI

O conector "BTG" (Empiricus e EQI) está mapeado tanto para contas simples quanto para contas conjuntas. Para conectar à conta conjunta, envie o nome do titular da conta via o endpoint "Send MFA Parameter user-triggered".

### Caixa PF e PJ

Usar este conector requer que o usuário autorize um novo dispositivo (Pluggy) dentro de seu aplicativo móvel da Caixa.

Tenha em mente que, a partir do momento em que o usuário insere suas credenciais, pode levar até 30 minutos para concluir o processo de login.

Primeiro, use o endpoint "Create Item" e envie os parâmetros necessários para a conexão:

Caixa PF:

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

Caixa PJ:

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

Se tudo estiver ok, o conector retornará o status `USER_AUTHORIZATION_PENDING` e um nome de dispositivo.

Use o endpoint "Specific Item" (`GET /items/:id`) para verificar o status da conexão. Chame o endpoint até que o atributo de resposta `executionStatus` tenha o valor `USER_AUTHORIZATION_PENDING`, assim como no exemplo abaixo:

```json
{
  "createdAt": "2022-12-29T17:42:43.926Z",
  "updatedAt": "2022-12-29T17:42:46.836Z",
  "status": "OUTDATED",
  "executionStatus": "USER_AUTHORIZATION_PENDING",
  "lastUpdatedAt": null,
  "webhookUrl": null,
  "error": {
    "code": "USER_AUTHORIZATION_PENDING",
    "message": "O usuário precisa conceder as permissões necessárias para sua conta.",
    "providerMessage": "No Internet Banking, clique em > Senhas e Configurações > Computadores e Dispositivos > Gerenciar \n Você precisa ativar o seguinte dispositivo:",
    "attributes": {
      "deviceNickname": "nick-name",
      "qrCodes": "cHJ1ZWJh,cHJ1ZWJhMg==,cHJ1ZWJhJJ=="
    }
  }
}
```

**Agora o usuário deve autorizar o novo dispositivo em seu aplicativo móvel da Caixa**, seguindo os passos abaixo:

1. Acesse o menu "Senhas e Configurações".
2. Selecione "Gerenciar Dispositivos" e depois "Dispositivos Registrados". Uma lista será retornada com os dispositivos registrados naquela conta. Pesquise na lista o dispositivo com o mesmo nome que foi retornado no campo `deviceNickname` da chamada anterior e selecione-o.
3. Clique no botão "Ativar dispositivo".
4. A tela "Ativar Dispositivo" será exibida; clique no botão "Continuar".
5. Escaneie os QRs recebidos no atributo `qrCodes` no payload anterior. Ele contém três QRs separados por vírgula que irão rotacionar a cada 5 segundos.

Assim que a etapa acima for concluída, aguarde 30 minutos para que a Caixa autorize o dispositivo, em seguida, faça uma chamada ao endpoint "Update Item" (`PATCH /items/:id`).

Informe o ItemId que você deseja atualizar no parâmetro do endpoint e faça a chamada com um corpo vazio (não é necessário reentrar as credenciais). O resultado esperado é `executionStatus: UPDATING`.

> **Nota:** Tenha em mente que o status de execução pode mudar rapidamente, e você também pode encontrar um status `CREATED` ou até mesmo `LOGIN_IN_PROGRESS`.

Retorne ao endpoint "Specific Item" para que você possa verificar o status da conexão. O resultado esperado é `executionStatus: SUCCESS`.

```json
{
  "createdAt": "2022-12-29T17:42:43.926Z",
  "updatedAt": "2022-12-29T17:42:44.011Z",
  "status": "UPDATED",
  "executionStatus": "SUCCESS",
  "lastUpdatedAt": null,
  "webhookUrl": null,
  "error": null,
  "clientUserId": "client-usr-id",
  "statusDetail": null,
  "parameter": null
}
```

Neste ponto, você poderá recuperar os dados dos produtos para este Item.

Talvez você esteja se perguntando se a Pluggy pode atualizar automaticamente os Itens que têm o dispositivo autorizado — aqui está uma pequena explicação de como fazemos isso. Sinta-se à vontade para entrar em contato conosco se não estiver claro o suficiente.

Uma vez que o usuário autoriza o novo dispositivo, é necessário aguardar 30 minutos até que a Caixa o aprove. Então, podemos ter duas situações diferentes:

1. O usuário aciona uma atualização e, se tudo estiver ok, retornaremos `SUCCESS`.
2. Nosso sistema de atualização automática será executado a cada 6 horas (após os 30 minutos necessários para autorizar o dispositivo) a fim de obter `status: SUCCESS` nos Itens que tiveram o dispositivo autorizado, mas não tiveram os dados coletados (não foram atualizados após os 30 minutos). Esse fluxo roda por 48 horas até receber o status `SUCCESS`, depois disso não continua atualizando automaticamente.

Se o usuário não atualizou em nenhum momento, receberá `USER_AUTHORIZATION_NOT_GRANTED`.

### Safra

Para conectar uma conta, este conector requer que o usuário autorize um novo dispositivo (`Pluggy - yyyy-mm-dd hh-mm`) através do aplicativo móvel da Safra.

Primeiro, use o endpoint "Create Item" e envie os parâmetros necessários para a conexão:

```json
{
  "connectorId": 229,
  "parameters": {
    "agency": "",
    "account": "",
    "password": ""
  }
}
```

Se tudo estiver ok, após inserir o token fornecido pelo aplicativo Safra, o conector retornará o `executionStatus` `WAITING_USER_ACTION`. Use o endpoint "Specific Item" (`GET /items/:id`) para verificar o status da conexão. Chame o endpoint até que o atributo de resposta `executionStatus` tenha o valor `WAITING_USER_ACTION`, assim como no exemplo abaixo:

```json
{
  "id": "c33872c7-85dc-4d67-b262-6490d85ea2d3",
  "connector": {
    "id": 229,
    "name": "Safra",
    "primaryColor": "#00003C",
    "institutionUrl": "https://www.safra.com.br/",
    "country": "BR",
    "type": "PERSONAL_BANK",
    "credentials": [
      {
        "validation": "^\\d{3,3}\\d$",
        "validationMessage": "O agência deve ter 4 números.",
        "label": "Agência",
        "name": "agency",
        "type": "number",
        "placeholder": "Exemplo: 1234",
        "optional": false
      },
      {
        "validation": "^\\d{6,6}-?\\d$",
        "validationMessage": "A conta deve ter 7 números.",
        "label": "Conta",
        "name": "account",
        "type": "number",
        "placeholder": "Exemplo: 12345-6",
        "optional": false
      },
      {
        "validation": "^\\d{1,6}$",
        "validationMessage": "A senha deve ter menos de 6 números.",
        "label": "Senha",
        "name": "password",
        "type": "password",
        "placeholder": "",
        "optional": false
      }
    ],
    "imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/229.svg",
    "hasMFA": true,
    "health": {
      "status": "ONLINE",
      "stage": null
    },
    "products": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "INVESTMENTS"
    ],
    "createdAt": "2022-11-04T21:12:51.716Z"
  },
  "createdAt": "2023-02-27T17:42:40.521Z",
  "updatedAt": "2023-02-27T17:43:47.114Z",
  "status": "WAITING_USER_ACTION",
  "executionStatus": "WAITING_USER_ACTION",
  "lastUpdatedAt": null,
  "webhookUrl": null,
  "error": null,
  "clientUserId": null,
  "statusDetail": null,
  "parameter": null,
  "userAction": {
    "instructions": "O usuário precisa autorizar o dispositivo em seu aplicativo Safra",
    "attributes": {
      "deviceNickname": "Pluggy - 2023-02-27 17:42"
    },
    "expiresAt": "2023-02-27T17:45:46.237Z"
  },
  "nextAutoSyncAt": null
}
```

O Item permanecerá nesse estado até:

- O usuário autoriza o dispositivo no aplicativo Safra: nesse caso, o status do Item mudará automaticamente e um novo token será solicitado ao usuário.

ou

- O usuário não autoriza o dispositivo no aplicativo Safra: o Item retornará o status de execução `USER_AUTHORIZATION_NOT_GRANTED`.

ou

- A data atual é posterior à data `expiresAt` retornada na propriedade `userAction`: o Item retornará o status `USER_AUTHORIZATION_PENDING`. Nesse cenário, o usuário pode autorizar o dispositivo mais tarde, e após isso o Item pode ser atualizado.

Esse fluxo acontecerá apenas na criação do Item. Se o dispositivo foi autorizado e o Item é atualizado, ele solicitará apenas um token do usuário.

### Banco Inter PF

Usar este conector para um Item na primeira execução requer que o usuário autorize o login com o Inter escaneando um código QR com seu aplicativo móvel do Inter.

Para isso, o usuário deve estar preparado para escanear o código QR fazendo login no aplicativo móvel e indo para Opções → iSafe e Internet Banking → Código QR.

Primeiro, use o endpoint "Create Item" — sem parâmetros necessários, já que todo o fluxo de login será por QR:

```json
{
  "connectorId": 215,
  "parameters": {}
}
```

Em seguida, retorne ao endpoint "Specific Item" para que você possa verificar o status da conexão. Logo após a criação, o Item atingirá um status de `WAITING_USER_ACTION`. Neste ponto, o campo `userAction.attributes.data` do Item conterá um código QR em base64 a ser escaneado:

```json
{
  "createdAt": "2023-02-27T12:46:25.707Z",
  "updatedAt": "2023-02-27T12:46:33.365Z",
  "status": "WAITING_USER_ACTION",
  "executionStatus": "WAITING_USER_ACTION",
  "lastUpdatedAt": null,
  "webhookUrl": null,
  "error": null,
  "clientUserId": null,
  "statusDetail": null,
  "parameter": null,
  "userAction": {
    "instructions": "ESCANEIE O QR",
    "expiresAt": 123456789,
    "attributes": {
      "name": "qr",
      "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALkAAAC5CAAAAABRxsGAAAAByElEQVR42u3cUW6DMBAFQO5/6fYCwXnPtiKBx1+JEmCKxHq96/T6e+q4yMnJycnJycnJycnJyd8iv76P28NuX30689LVyMmPlt8/1B8+DYDpsemn5OTk97Fgoze9Gjk5+YT8Vjmey8nJyX8XW8YzeBp5yMnJd+bnqXflK+Tk5LM1ro2vflydIyd/sjxu1QyjzO2Fx6KfdLjIyZ8sT1fBafKdrsODiEJOTv7lb6hasv2NSWMQOfmx8mBN29ee0yZumhaQkx8rr2b15SLZuDNMTk4+MecnZeLm2Ikcgpz8aPk4mKw0i8ar6vjGkJOfKq9y8bTi3O+G2pS3kJO/TR7k4tXepjSFrxpI5OTHytOqcYXpfz5ATk4ex5Zqyq7CSrBjg5ycPD512kWaLDFvz8/Jyd8rD7YwVUvr4ARxgk9OTh489+mGqaAU3ZW2yclPlaejbxul+5LX+0Tk5O+VV79kC95WTeH4JpCTHy2vitKTqUK6cicnJ48bQ1UsCHY+VRVscnLyTfJ008RkKZqcnHz2vxRObmTcmZ+Tk58gX87ex4FjsrxFTk5+VQ9/uqE/neSX8nNy8pfLHzHIycnJycnJycnJycnJnzj+ATnf0jtEQEXdAAAAAElFTkSuQmCC"
    }
  },
  "nextAutoSyncAt": null
}
```

Como retornamos a imagem em base64, você precisará renderizá-la para que o cliente possa escaneá-la. Assim que o usuário escanear com sucesso o QR de login com seu aplicativo móvel, o fluxo de login continuará normalmente.

> **Informações importantes e recomendações**
>
> Tenha em mente que o código QR expira em 5 segundos, e as informações do Item serão atualizadas com um novo código QR. Assim, você precisará consultar o endpoint "Specific Item" para verificar atualizações no código. Dado o tempo de expiração muito curto, é fácil renderizar um código QR expirado. Portanto, recomendamos consultar a cada 1 segundo até que o status do Item mude.

### XP Wealth

Este conector também permite que você especifique quais clientes deseja coletar dados financeiros. Para fazer isso, você precisa enviar uma credencial `selectedCustomers` com todos os códigos de clientes que deseja conectar, separados por vírgulas.

```json
{
  "connectorId": 248,
  "parameters": {
    "clientId": "clientId",
    "clientSecret": "clientSecret",
    "selectedCustomers": "409185,551175,176189"
  },
  "webhookUrl": "https://www.myapi.com/notifications"
}
```

> **Importante**
>
> Esta personalização não está disponível em nosso widget; você precisa criar o Item usando a API Pluggy.

### Mercado Bitcoin

Este conector requer a criação de uma Chave de API (chave de API) na conta da instituição. Para fazer isso, siga [este tutorial](https://suporte.mercadobitcoin.com.br/hc/pt-br/articles/360040781391-Como-gerar-uma-chave-de-API). Depois disso, use o client id e client secret para criar um Item.

## Conectores com OAuth

Conexões OAuth exigem que o usuário forneça autorização diretamente dentro do aplicativo da Instituição Financeira, portanto, há um fluxo de redirecionamento que precisa acontecer entre a Pluggy e a IF, de volta e para frente.

### OAuth v1

A primeira implementação que a Pluggy forneceu retorna um `oauthUrl` no endpoint [List Connectors](/reference/connectors-list) que é necessário para redirecionar o usuário para fornecer consentimento.

```json
{
  "id": 206,
  "name": "Mercado Pago",
  "oauthUrl": "https://auth.mercadopago.com.br/authorization?client_id=3960514748228649&redirect_uri=https://api.pluggy.ai/connectors/206/oauth/callback&response_type=code&platform_id=mp&scopes=read,offline_access&state=27364b4a-354e-479d-89bd-05cef476e1f4"
}
```

Se o conector fornecer o `oauthUrl`, você será obrigado a redirecionar o usuário para essa página, e após ele autorizar a Pluggy, nós o redirecionaremos de volta para sua aplicação.

Isso afeta os conectores: "MercadoPago".

### OAuth v2

Após melhorar o fluxo da versão anterior, lançamos a integração diretamente através do Item, para fornecer melhor rastreamento das tentativas de conexão para nossos clientes. Agora os conectores não retornam a URL; em vez disso, não requerem nenhuma credencial para iniciar a execução e têm uma flag `oauth` para indicar que esses conectores se autenticam através do OAuth.

```json
{
  "id": 240,
  "name": "Splitwise",
  "credentials": [],
  "oauth": true
}
```

Uma vez que a execução tenha começado, forneceremos o `oauthUrl` como um parâmetro para que o usuário seja redirecionado:

```json
{
  "id": "54a8d5e2-583a-40fd-a716-c9cee38a73dc",
  "parameter": {
    "label": "Oauth Code",
    "name": "oauthCode",
    "type": "oauth",
    "instructions": "Faça login na página do Splitwise para continuar",
    "data": "https://secure.splitwise.com/oauth/authorize?response_type=code&client_id=I351UBINPK5b5psYXToACr90XVD5g5GuBdvg4SG4&redirect_uri=https://api.pluggy.ai/items/oauth/callback&scope=&state=4eb2909b-c4c5-4f68-ba2b-84f2772fb15a",
    "expiresAt": "2023-03-09T11:02:54.796Z"
  }
}
```

O tipo do parâmetro `oauth` facilita entender que um fluxo OAuth é necessário, e o atributo `data` retorna a URL para redirecionar o usuário. Após o callback, o Item será criado.

Nas atualizações, o fluxo será o mesmo.