Utilizando o registro via Web Service Bancário com o BTG – Central de Atendimento

Solicitando dados necessários

Para integrar sua aplicação com o Banco BTG Pactual e realizar emissões via Web Service (WS), siga os passos abaixo:

1. Criar uma Conta no BTG Pactual Empresas

Antes de tudo, é necessário possuir uma conta administradora ( corporativa ) no BTG Pactual Empresas. Essa conta será utilizada tanto para acessar o internet banking quanto para os processos de autenticação nas APIs.

2. Registrar um Usuário Desenvolvedor

Após criar sua conta, é importante registrar um usuário com perfil de desenvolvedor. Isso permitirá que você crie e gerencie aplicativos para interagir com as APIs do BTG. Para mais detalhes sobre como realizar esse registro, consulte o guia Registre um Usuário Desenvolvedor.

3. Criar um Aplicativo

Com o usuário desenvolvedor registrado, o próximo passo é criar um aplicativo que consumirá as APIs do BTG Pactual Empresas.

Primeiramente, será necessário preencher alguns dados da aplicação
- Nome do aplicativo
- Tipo: Confidencial
- Descrição do aplicativo
- URI's de redirecionamento: https://plugboleto.com.br/api/v1/email/callback
- Modelo de integração: First party - Consumir recursos de contas próprias
- Selecione todos os escopos possíveis.
- Confira se os dados estão corretos

4. Obtendo as credenciais

Ao acessar o aplicativo, acesse o opção Chaves, lá estará disponível os dados para que possamos seguir para a próxima etapa.

5. Testar no Ambiente Sandbox

5.2 Via GUI

Antes de mover para o ambiente de produção, é recomendável testar sua integração no ambiente Sandbox fornecido pelo BTG Pactual. Esse ambiente permite simular operações e garantir que sua aplicação esteja funcionando conforme o esperado.

Para realizar os testes, acesse https://homologacao.plugboleto.com.br para que possa cadastrar sua conta e convênio.

Acessando o ambiente de testes, cadastre sua conta selecionando o banco BTG e em seguida preencha com seus dados bancários

Assim que for cadastrado, acesse o menu de convênios, preencha os dados obrigatórios e siga para a aba Configurações do convênio

Habilite o Registro instantâneo e preencha os dados abaixo

OBS: o campo Código de autorização - BTG será preenchido com um token retornado executando o processo seguinte

Para ter acesso ao Código de Autorização do BTG, selecione o link Gerar código de autorização.

Caso opte por gerar esta URL via API, siga os passos abaixo.

5.2 Via API

Gerar Código de Autorização:

Homologação:

POST
https://homologacao.plugboleto.com.br/api/v1/oauth2/connect

Produção:

POST
https://plugboleto.com.br/api/v1/oauth2/connect

Body (produção e homologação):

{
    "convenioId": "", //Identificador numérico disponível após o cadastro do convênio
    "apiId": "client-id-fornecido-pelo-banco"
}

Response:

{
    "_status": "sucesso",
    "_dados": {
        "oauth2_url": "https://id.sandbox.btgpactual.com/oauth2/authorize?client_id=app-teste&response_type=code&redirect_uri=https://plugboleto.com.br/api/v1/email/callback&scope=openid%20brn:btg:empresas:companies.readonly%20empresas.btgpactual.com/accounts%20empresas.btgpactual.com/accounts.readonly%20empresas.btgpactual.com/bank-slips%20empresas.btgpactual.com/bank-slips.readonly%20brn:btg:empresas:apps:webhooks%20brn:btg:empresas:banking:collections.readonly%20brn:btg:empresas:banking:collections&prompt=consent",
        "ambiente": "sandbox"
    }
}

O ambiente de desenvolvedor será disponibilizado para que possa seguir com a criação do código ( Lembre-se, uma conta desenvolvedora deve existir para que consiga acessar o ambiente ).

Acessando o ambiente, os produtos e o escopos selecionados serão disponibilizados.

Siga para selecionar o CNPJ de sua empresa ( Em Sandbox, será obrigatório escolher a opção BANCO BTG PACTUAL S.A.

6. Inclusão do Código de Autorização

Assim que seguir em frente, seja através da GUI ou API, você será redirecionado para a URL cadastrada anteriormente contendo o código para o cadastro em nossa API

Após obter o token de autenticação, insira ele no campo Código de Autorização - BTG e, caso todos os dados estiverem preenchidos, salve o convênio.

Via API é necessário editar o convênio inserindo o Código de Autorização. Além disso, verifique se os campos foram preenchidos: conveniobtgcodigoautorizacao, convenioapiid e convenioapisecret.

Observações Finais

Ao criar ou editar o convênio, uma requisição de autenticação será enviada ao banco para obtermos o access_token e refresh_token. O refresh token tem uma duração de 10 dias e, toda vez que é utilizado, tem sua duração redefinida para 10 dias.

Portanto, esses dados são cruciais para garantir as emissões sem a necessidade de refazer os fluxos anteriores, evitando acionamentos aos clientes finais para autenticação.

Em caso de falha ao autenticar no banco, será exibida uma mensagem de erro na interface informando que ocorreu algum problema.

O que fazer?

Primeiramente, podem refazer o processo de obter o código de autorização revisando o ambiente que está sendo executado (sandbox ou produção).
Inserir os dados novamente nos campos API - ID, Segredo e Código de autorização - BTG e tentar salvar novamente o convênio.
Caso o erro persista, recomendamos acessar o chat para obter mais informações e ajuda do nosso time técnico.