Santander (033): boleto, Pix, Workspace e extrato
O Santander é o banco que exige mais configuração, por causa do Workspace - um agrupador de convênios que o banco exige em toda chamada. Este artigo mostra como gerar as credenciais no Portal do Desenvolvedor, por que só certificado ICP-Brasil A1 é aceito, e como o Hap cria e recupera o Workspace sozinho.
Quando usar
Use ao configurar a conta Santander pela primeira vez, quando o certificado for recusado, ou quando a emissão falhar com erro de Workspace não encontrada.
Antes de começar
- Conta no Portal do Desenvolvedor Santander, com os dados da conta PJ.
- Certificado digital ICP-Brasil A1 da empresa. Certificado SSL de site não serve.
- Convênio de cobrança contratado com o parâmetro Entrada Online habilitado.
O que essa integração faz
O Santander é, junto com o Bradesco, a integração mais completa do Hap: boleto comum e híbrido, Pix, pagamentos de vários tipos, extrato, saldo e PDF do boleto pela API. Em compensação é a que exige mais preparo, por causa do Workspace.
| Recurso | Como funciona |
|---|---|
| Boleto | Emitir, consultar e alterar por instruções: vencimento, valor, protesto e baixa. |
| Boleto híbrido | Sim, com QR Code Pix embutido. |
| PDF do boleto | Sim, pela própria API. |
| Pix | Cobrança imediata e com vencimento, e devolução. |
| Pagamentos | Boleto, código de barras, Pix, DARF e GPS. Em duas etapas: iniciar e autorizar. |
| Extrato e saldo | Sim, com paginação. |
| Webhook | Configurado dentro do Workspace, automaticamente. |
Gerar as credenciais
- 1
Acesse o Portal do Desenvolvedor Santander com os dados da conta PJ.
- 2
Suba a parte pública do certificado ICP-Brasil A1. É o upload que libera a geração das credenciais.
- 3
O portal gera o Client ID e o Client Secret.
- 4
Contrate o convênio de Cobrança com o parâmetro Entrada Online habilitado - sem ele a emissão pela API não funciona.
- 5
Se for usar pagamentos, crie uma aplicação separada, com o produto de Pagamento de Contas.
O Workspace, e por que você não precisa se preocupar com ele
Workspace é um conceito só do Santander: um agrupador que reúne um ou mais convênios de cobrança junto com a configuração de webhook. Todas as chamadas de boleto, Pix e pagamento passam por ele - sem um Workspace válido, nada funciona.
Na prática você não precisa criar nem informar nada. Na primeira emissão depois de salvar a conta, o Hap procura um Workspace do seu convênio; se existir, reutiliza; se não existir, cria. E se um dia o Workspace for removido no banco, o Hap detecta a recusa, procura outro, cria se preciso e refaz a emissão - tudo na mesma tentativa.
Preencher o convênio no Hap
| Campo no formulário | O que preencher |
|---|---|
| Client ID (obrigatório) | Gerado no Portal do Desenvolvedor Santander. |
| Client Secret (obrigatório) | Gerado no portal, junto com o Client ID. |
| Ambiente (obrigatório) | Sandbox para testes ou Produção. |
| Arquivo .crt e .key (obrigatório) | O certificado ICP-Brasil A1 em PEM, ou o .pfx convertido pela aba Certificado PEM. |
| Senha do certificado | Apenas se o certificado tiver senha. |
| Número do Convênio (obrigatório) | O código de beneficiário fornecido pelo Santander, de até 9 dígitos. |
Problemas comuns
- O certificado foi recusado: o Santander aceita apenas ICP-Brasil A1. Certificado SSL de domínio de site, mesmo válido, é recusado.
- A emissão falha dizendo que a Workspace não foi encontrada: o Hap se recupera sozinho disso - limpa o identificador inválido, procura outro workspace do mesmo convênio e, se não achar, cria um novo, tudo na mesma tentativa. Se o erro persistir, confira se o convênio foi contratado com Entrada Online habilitado.
- Quero criar o Workspace manualmente: pode. Crie no portal do Santander e o Hap o encontra sozinho na primeira emissão - não é preciso informar o identificador em lugar nenhum.
- Pagamentos não saem: o Santander faz pagamento em duas etapas, iniciar e autorizar. O Hap faz as duas, mas confira o status para ver se alguma foi recusada.
- Preciso de pagamentos além de cobrança: é uma aplicação separada no portal, com o produto de Pagamento de Contas.