Pular para conteúdo

Configurações Santander (Boletos e Pix)

Tela para configurar, de forma simples, a integração do seu sistema com o Banco Santander. Aqui você cadastra as credenciais, dados bancários e webhooks usados para emissão de boletos e para o PIX.

Observação: Acesso restrito a usuários com perfil SuperAdmin.

O que você pode fazer

  • Cadastrar/editar a integração de Boletos Santander.
  • Cadastrar/editar a integração do PIX Santander.
  • Informar dados do recebedor (agência, conta e convênio).
  • Definir URLs de webhooks (notificações) para o PIX.
  • Visualizar a "Última atualização" da configuração.
  • Mostrar/ocultar campos sensíveis (segredos) ao digitar.

Passo a passo

Antes de começar

Tenha em mãos: - Client ID e Client Secret do Santander (credenciais da sua aplicação). - Arquivo de certificado (.pfx) e a senha, se sua integração usar certificado. - Dados bancários do recebedor (Agência, Conta e Convênio). - URLs públicas (HTTPS) para receber webhooks (PIX e/ou boletos, se aplicável).

1) Acessar a tela

  • Entre com um usuário SuperAdmin.
  • Se você não tiver permissão, verá a mensagem "Acesso restrito ao SuperAdmin".

2) Configurar Boletos

  1. Na seção "Editar Configuração Boleto":
  2. Preencha Client ID e Client Secret. Use o ícone de olho para mostrar/ocultar o segredo.
  3. Informe a URL Produção da API (campo obrigatório).
  4. Se necessário, informe o Caminho do Certificado (.pfx) e a Senha do Certificado.
  5. Preencha Convênio, Agência do Recebedor e Conta do Recebedor.
  6. Se você usa notificações para boletos, informe a Webhook URL (endereço público HTTPS).
  7. Clique em Salvar.
  8. O botão indica carregamento e, ao concluir, aparece uma mensagem de sucesso.
  9. A data de "Última atualização" é atualizada no topo da tela.

Importante: Para Boletos, as informações são salvas no ambiente de produção.

3) Configurar PIX

  1. Na seção PIX:
  2. Preencha Client ID e Client Secret.
  3. Base URL: já vem com um valor padrão; ajuste conforme seu ambiente.
  4. Informe Caminho do Certificado (.pfx) e Senha do Certificado, se aplicável.
  5. Preencha Convênio, Agência e Conta do recebedor.
  6. Clique em Salvar Configuração PIX.
  7. Você verá uma confirmação de sucesso e a configuração ativa será carregada.

4) Configurar Webhooks do PIX

  1. Webhook de recorrência:
  2. Informe a URL pública (HTTPS) onde seu sistema receberá os eventos.
  3. Clique em Configurar webhook de recorrência.
  4. Webhook de cobrança recorrente:
  5. Informe a URL para eventos de cobrança recorrente.
  6. Clique em Configurar webhook de cobrança recorrente.
  7. Se a URL estiver vazia, o sistema avisa que é obrigatória. Em caso de sucesso, você recebe uma confirmação.

Campos e botões importantes

  • Client ID: Identificador da sua aplicação junto ao Santander.
  • Client Secret: Segredo da aplicação. Use o ícone de olho para mostrar/ocultar enquanto digita.
  • URL Produção / Base URL: Endereço da API do Santander que seu sistema irá usar.
  • Caminho do Certificado: Local do arquivo .pfx no servidor (ex.: cert.pfx).
  • Senha do Certificado: Senha do arquivo .pfx.
  • Convênio: Código do convênio de cobrança fornecido pelo banco.
  • Agência do Recebedor: Agência vinculada ao recebimento.
  • Conta do Recebedor: Conta vinculada ao recebimento.
  • Webhook URL (Boletos): Endereço HTTP(S) para receber notificações relacionadas a boletos.
  • Webhook de recorrência (PIX): URL para eventos de recorrência PIX.
  • Webhook de cobrança recorrente (PIX): URL para eventos de cobranças recorrentes PIX.
  • Salvar / Salvar Configuração PIX: Grava as alterações. O botão fica desabilitado enquanto salva.
  • Última atualização: Mostra quando a configuração foi alterada pela última vez.
  • Mensagens de confirmação/erro: Aparecem informando o resultado de cada ação (sucesso ou erro).

Dicas e observações

  • Permissões: Apenas SuperAdmin acessa esta tela. Se necessário, peça a um administrador para ajustar seu perfil.
  • Ambiente de Boletos: A configuração é salva como produção. Revise a URL antes de salvar.
  • Uma configuração por vez: O sistema considera uma configuração ativa por tipo (Boleto e PIX). Evite manter múltiplas variações.
  • Segurança:
  • Não compartilhe Client Secret e a senha do certificado.
  • Prefira colar dados sensíveis quando necessário e ocultá-los após conferir.
  • Use URLs de webhook com HTTPS e acessíveis pela internet.
  • Certificado:
  • O arquivo .pfx precisa existir no servidor onde o sistema está rodando.
  • Informe o caminho exato e a senha correta para evitar falhas de conexão.
  • Erros comuns:
  • Webhook sem URL: ao configurar, a tela avisará que a URL é obrigatória.
  • Campos obrigatórios em branco (Client ID, Client Secret, URL da API) impedem o salvamento.
  • Certificado/senha inválidos podem bloquear a comunicação com o banco.
  • Salvamento não é automático: Após qualquer alteração, clique em Salvar.

Exemplos do mundo real

  • URLs de webhook:
  • https://minhaempresa.com.br/api/webhooks/santander
  • https://minhaempresa.com.br/api/webhooks/pix/recorrencia

  • https://minhaempresa.com.br/api/webhooks/pix/cobranca-recorrente

  • Troca de convênio ou conta:

  • Atualize Convênio, Agência e Conta nos campos correspondentes.
  • Clique em Salvar.
  • Faça um teste (boletos/PIX) para confirmar que tudo está funcionando.

FAQ

1) Não consigo acessar a tela. O que fazer? - Verifique se seu usuário tem o papel SuperAdmin. Se não tiver, solicite ao administrador.

2) Onde consigo o Client ID e o Client Secret? - São fornecidos pelo Santander ao registrar sua aplicação. Consulte seu gerente de conta ou o portal de desenvolvedores do banco.

3) Preciso, obrigatoriamente, do certificado .pfx? - Se a sua integração exigir autenticação por certificado, sim. Tenha o arquivo e a senha corretos.

4) Posso testar em ambiente de homologação/sandbox? - Para Boletos, a configuração é salva como produção. Use um ambiente/instância de testes separado e aponte a URL correspondente. Para PIX, ajuste a Base URL conforme o ambiente que estiver usando.

5) Como sei que salvou? - Você verá uma mensagem de sucesso e a "Última atualização" exibirá a nova data e horário. Para webhooks, faça um teste e verifique se seu sistema recebe a notificação.