Configurar as credenciais da conta bancária integrada e testar a conexão

Para que a conta bancária converse com o banco (emitir boleto com QR Pix, pagar titulos, gerar a URL do webhook), o Kryia One precisa das credenciais da aplicação que você cadastrou no portal do banco. Bancos que exigem certificado digital, como o Santander, pedem também o arquivo .pfx. Este artigo mostra como salvar essas credenciais, como o sistema confere o certificado ao salvar e como testar a conexão.

Antes de começar

• A conta já deve estar cadastrada; veja cadastrar uma conta bancária.
• A conta precisa ter o ambiente da API informado (Sandbox ou Produção). Sem ele, o teste de conexão responde: “Informe o ambiente da API da conta (Sandbox ou Produção).”
• Para emitir boleto com QR Pix e pagar títulos pelo Santander, o provedor da conta deve ser Santander. A dica do campo diz: “Selecione Santander para emitir boleto com QR Pix e pagar títulos pelo Santander, ou Pix (Banco Central) para cobrança Pix nos demais bancos. Nenhum desliga a integração; Simulado só funciona fora de produção.” Os campos da conta estão em Contas Bancárias; a ligação da cobrança está em ligar a cobrança integrada.
• Quem salva as credenciais precisa de permissão para alterar Contas Bancárias.
• Tenha à mão o certificado da aplicação cadastrada no portal do banco: há um por ambiente (Sandbox ou Produção).
• Se o certificado for .pfx (ou .p12), tenha também a senha dele.

1. Abra a configuração de credenciais

1. Vá em Financeiro › Rotinas › Acompanhamento de Boletos e abra a aba Contas.
2. No menu ⋮ da conta, escolha Configurar credenciais. O item fica ao lado de Gerar URL do webhook e Testar conexão.

O diálogo abre com o título “Credenciais de” seguido do nome da conta.

2. Informe e salve

Informe o Client ID, o Client Secret, o arquivo .pfx e a senha do certificado, e use o botão Salvar. No diálogo, os campos aparecem como “Client ID”, “Client secret”, “Certificado (.pfx)” (aceita arquivo .pfx ou .p12) e “Senha do certificado”.

• Client ID e Client Secret são obrigatórios. Sem eles o sistema responde: “Informe client_id e client_secret.”
• O certificado (.pfx) e a senha dele são opcionais no salvamento: o sistema registra se a conta tem certificado ou não. Salvar só com Client ID e Client Secret, sem certificado, continua funcionando. Para um banco que exige certificado, como o Santander, informe-o; sem ele o teste de conexão não funciona.
• Quando você envia um certificado, o sistema o confere antes de gravar (veja a próxima seção).
• Se a conta não existe mais, a resposta é “Conta bancária não encontrada.”

O segredo é gravado cifrado e nunca volta para a tela. Ao reabrir a configuração, o sistema informa apenas se a conta está configurada e se tem certificado; para trocar uma credencial, informe-a de novo.

O certificado é conferido ao salvar

A conferência vale para qualquer conta cujo salvamento traga certificado .pfx, não só para Pix. Ela faz três verificações, nesta ordem:

1. O arquivo precisa ser um certificado legível.
2. O custo de proteção declarado no arquivo não pode passar do teto aceito.
3. A senha precisa abrir o arquivo, e o arquivo precisa trazer a chave privada.

Se alguma falhar, o salvamento é recusado com uma destas mensagens:

Mensagem	Quando aparece
“Não foi possível abrir o certificado: senha incorreta ou arquivo inválido.”	O arquivo não é um certificado válido, ou a senha não o abre
“O arquivo do certificado não contém a chave privada.”	O certificado abre, mas não traz a chave privada
“O arquivo do certificado declara um custo de proteção acima do aceito. Exporte o certificado novamente com as configurações padrão.”	O custo de proteção declarado no arquivo passa do teto aceito

Quando o salvamento é recusado, nada é gravado: nem o Client ID nem o Client secret. A mensagem aparece numa linha de alerta dentro do diálogo e os campos não são limpos, para você corrigir a senha ou trocar o arquivo e salvar de novo. Se a API não devolver mensagem, o texto é “Não foi possível salvar as credenciais.” Só depois de um salvamento com sucesso o formulário é esvaziado.

E o certificado que já estava gravado?

Um certificado gravado antes dessa conferência e que não a passe faz a chamada ao banco falhar com a mesma mensagem. O erro é terminal: não há nova tentativa automática. A conferência é feita ao montar a conexão com o banco, tanto no Pix quanto no Santander. Para resolver, salve as credenciais de novo com um certificado que passe na conferência.

3. Teste a conexão

No mesmo menu ⋮ da conta, use Testar conexão. Se tudo certo, o sistema mostra “Conexão com o banco confirmada.”

No Santander, o teste obtém o token usando o certificado e consulta os workspaces de cobrança e de pagamento. Se falhar, a tela mostra a mensagem do erro.

As mensagens do banco

Quando o banco recusa ou não responde, a tela mostra o motivo, em vez de uma mensagem técnica genérica. Isso vale para o teste de conexão e para as ações que falam com o banco, como gerar a URL do webhook, registrar boleto e pagar pelo banco.

Mensagem	Quando aparece
“O banco recusou a requisição (HTTP status)”, seguida do código e do motivo do banco, quando existem	O banco recusou a requisição com erro 4xx
“Credencial recusada pelo banco.”	O banco respondeu 401 ou 403
“O banco não respondeu a tempo.”	A resposta do banco demorou além do limite
“O banco está indisponível no momento.”	Falha de rede ou erro 5xx do banco

Problemas comuns

“Não foi possível abrir o certificado: senha incorreta ou arquivo inválido.” Confira a senha do certificado e se o arquivo é mesmo um .pfx ou .p12 exportado com a chave privada. Corrija e use Salvar de novo; os campos continuam preenchidos.

“O arquivo do certificado não contém a chave privada.” Exporte o certificado de novo incluindo a chave privada e envie o novo arquivo.

“O arquivo do certificado declara um custo de proteção acima do aceito. …” Siga a orientação da própria mensagem: exporte o certificado novamente com as configurações padrão.

A chamada ao banco falha com uma dessas mensagens, mas o salvamento antigo deu certo. O certificado foi gravado antes da conferência existir. Salve as credenciais de novo com um certificado válido.

“Credencial recusada pelo banco.” Confira se o Client ID, o Client Secret e o certificado são da aplicação do mesmo ambiente (Sandbox ou Produção) da conta, e salve de novo.

“O banco recusou a requisição (HTTP …)”. O motivo vem do banco, depois do código. Leia-o: ele costuma indicar o dado que o banco não aceitou.

“Informe o ambiente da API da conta (Sandbox ou Produção).” Preencha o ambiente da API no cadastro da conta e teste de novo.

“Erro interno.” ao salvar com certificado. Era uma limitação do espaço reservado ao segredo cifrado, pequeno demais para caber o certificado. A correção ampliou esse espaço e não altera nenhuma credencial já salva. Se o erro persistir, procure o suporte da Kryia.