> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://maisretorno.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Conectar carteiras do BTG no PRO

A integração com o BTG Pactual conecta as contas da sua assessoria diretamente à Mais Retorno. Depois de conectada, cada carteira passa a se atualizar sozinha: posições, patrimônio e movimentações entram automaticamente, sem você lançar transação na mão nem reconciliar extrato no fim do mês.

Este guia mostra o passo a passo completo da ativação.

## Antes de começar

Você vai precisar de:

- Uma conta **BTG Pactual Empresas** com parceria ativa.
- Acesso ao **portal do desenvolvedor** do BTG.
- Ser o **usuário Master** da conta no BTG. Só o usuário Master consegue gerar a chave de API e cadastrar os webhooks.

No Mais Retorno, a área de Conexões fica disponível para o plano PRO.

## Visão geral do fluxo

A ativação tem três partes:

1. Gerar a chave de API no portal do BTG.
2. Conectar essa chave no Mais Retorno PRO.
3. Cadastrar os webhooks no portal do BTG e finalizar.

## Parte 1: gerar a chave de API no BTG

1. Acesse o portal do desenvolvedor: [https://developer-partner.btgpactual.com/login](https://developer-partner.btgpactual.com/login)
2. Entre na área de **Autorização**.

![Seção de autorização no portal BTG](https://pro.maisretorno.com/images/btg/auth-section-identifier.png)

3. Clique em **Gerar novas chaves**.

![Botão gerar novas chaves](https://pro.maisretorno.com/images/btg/new-key-button.png)

4. O BTG vai gerar duas chaves: **Cliente_ID** e **Cliente_Secret**. Guarde as duas, você vai colar no Mais Retorno no próximo passo.

## Parte 2: conectar no Mais Retorno PRO

1. No PRO, abra o menu **Conexões**.
2. Clique em **Nova conexão** e selecione **BTG Pactual**.
3. Defina um **nome para a conexão**. Esse nome não pode ser alterado depois do cadastro.
4. Cole a chave **Cliente_ID** e a chave **Cliente_Secret** nos campos correspondentes.
5. Clique em **Conectar**.

O Mais Retorno valida as credenciais com o BTG. Se as chaves estiverem corretas, você avança para a configuração dos webhooks.

## Parte 3: configurar os webhooks no BTG

Os webhooks são o que permite o BTG enviar seus dados para o Mais Retorno de forma contínua. São 4, e todos precisam ser cadastrados.

1. No portal do desenvolvedor do BTG, vá em **Webhooks > Manutenção**.

![Menu Webhooks e Manutenção](https://pro.maisretorno.com/images/btg/menu.png)

2. Clique em **Cadastrar Webhook**.

![Botão cadastrar webhook](https://pro.maisretorno.com/images/btg/webhook-button.png)

3. Cadastre os 4 webhooks, um a um. Para cada um:
   - Selecione o tipo de autenticação **API Key**.
   - Preencha a **URL do webhook** (lista abaixo).
   - Selecione o **serviço correspondente**.
   - Cole a **chave de API** no campo API Key.

![Formulário de cadastro de webhook](https://pro.maisretorno.com/images/btg/webhook-form.png)

### Os 4 webhooks necessários

- **Relatório de Posição** (`rm-reports-position`)
  URL: `https://btgpositionwebhook-rctxdexdwq-rj.a.run.app/`
- **Relatório de Movimentação** (`rm-reports-movement`)
  URL: `https://btgpositionwebhook-rctxdexdwq-rj.a.run.app/`
- **Fechamento de Movimentação Mensal** (`rm-reports-monthly-movement`)
  URL: `https://btgmonthlymovementwebhook-rctxdexdwq-rj.a.run.app/`
- **Posições por Conta V2** (`positions-by-account-v2`)
  URL: `https://btgunitpriceswebhook-rctxdexdwq-rj.a.run.app/`

4. Confira os nomes dos webhooks ao configurá-los.

![Nomes dos webhooks](https://pro.maisretorno.com/images/btg/webhook-names.png)

Se algum desses webhooks não estiver disponível para cadastro no seletor, o BTG Pactual ainda não liberou todos os recursos que precisamos para integrar suas contas. Entre em contato com o gestor da sua parceria BTG Pactual Empresas para liberar.

Depois de criados, os webhooks aparecem assim na aba **Webhooks > Manutenção**:

![Lista de webhooks configurados](https://pro.maisretorno.com/images/btg/webhook-list.png)

5. De volta ao Mais Retorno, marque a opção **Configurei e verifiquei os webhooks no painel BTG** e clique em **Conectar**.

## Parte 4: aguardar a sincronização

Pronto. A partir daqui o Mais Retorno lê seus dados e monta as carteiras. Esse processo inicial pode levar de **45 minutos a 2h30**. Você pode fechar a janela, avisamos quando tudo estiver pronto.

## O que acontece depois de conectado

- As carteiras vinculadas ao BTG passam a se atualizar automaticamente.
- Se uma conta ainda não tiver carteira, o Mais Retorno cria uma para você ao ativar.
- Na lista de carteiras aparece um ícone de integração, com a corretora conectada.
- Você pode filtrar as carteiras por corretora na própria lista.

## Problemas comuns

**Credenciais inválidas.** Confira se copiou o Cliente_ID e o Cliente_Secret completos, sem espaços. Se persistir, gere novas chaves no portal do BTG e tente de novo.

**Um dos webhooks não aparece no seletor.** Se algum dos 4 webhooks não estiver disponível para cadastro, o BTG Pactual ainda não liberou todos os recursos necessários. Fale com o gestor da sua parceria BTG Pactual Empresas.

**A sincronização parece travada.** O primeiro carregamento é demorado, até 2h30. Se passar muito disso, refaça a verificação na tela de Conexões ou fale com o suporte.

## Precisa de ajuda?

Nossa equipe configura a integração para você. Fale com um especialista pelo botão **Solicitar assistência** na própria tela de conexão, ou pelo suporte do Mais Retorno.