Caixa (104): boleto por WebService, sem Pix e sem webhook
A Caixa é o banco mais simples de configurar e o mais limitado: só precisa do Código Beneficiário, sem credencial nem certificado, mas faz apenas boleto - sem Pix, sem extrato e sem webhook. Este artigo mostra o que pedir ao gerente, o que preencher e como resolver o erro 54.
Quando usar
Use ao configurar a conta Caixa pela primeira vez, ao receber o erro 54 na emissão, ou para entender por que a baixa do boleto pago demora.
Antes de começar
- Serviço de WebService de Cobrança ativado pelo gerente da Caixa PJ.
- Código Beneficiário de 7 dígitos, vinculado ao convênio.
O que esperar da Caixa
A Caixa é o único banco integrado que não usa API moderna: ela mantém um serviço antigo, com autenticação por código calculado em vez de credencial. Isso tem um lado bom e um ruim. O bom é que não há Client ID, Client Secret nem certificado para gerenciar. O ruim é que o escopo é só boleto.
| Recurso | Como funciona |
|---|---|
| Boleto | Registrar, consultar, alterar vencimento ou valor, e baixar. |
| PDF do boleto | O banco devolve um endereço e o Hap baixa o arquivo automaticamente. |
| Pix | Não suportado. |
| Extrato e saldo | Não suportados. Use o arquivo OFX em Caixas e Contas. |
| Webhook | Não existe. A baixa depende de consulta periódica. |
O que pedir ao gerente
Não há portal de desenvolvedor nem cadastro de aplicação. Contate o gerente da Caixa PJ e solicite a ativação do serviço de WebService de Cobrança. Ele fornece o Código Beneficiário de 7 dígitos, vinculado ao convênio - é a única informação necessária.
| Campo no formulário | O que preencher |
|---|---|
| Número do convênio (obrigatório) | O Código Beneficiário de 7 dígitos fornecido pelo gerente. |
| Ambiente (obrigatório) | Sandbox para testes ou Produção. |
| Próximo nosso número | O sequencial usado pelo Hap para numerar os títulos. |
Problemas comuns
- Erro 54, hash divergente: é sempre preenchimento com tamanho errado. Confira o Código Beneficiário com 7 dígitos, o nosso número com 17, a data no formato dia-mês-ano sem separadores, o valor em centavos com 15 dígitos e o CNPJ com 14. Qualquer um fora do tamanho gera hash diferente.
- O sandbox parou de responder: a Caixa desativa o ambiente de testes assim que o primeiro boleto de produção é emitido. Não há como reverter - por isso todo teste precisa ser feito antes.
- O boleto foi pago e continua aberto: a Caixa não envia notificação. O sistema consulta periodicamente para detectar a liquidação, então há um intervalo até a baixa.
- Preciso de Pix ou extrato na Caixa: não existe pela API. O extrato é por arquivo OFX, importado em Caixas e Contas.
- A Caixa não me atende sobre a integração: é conhecido - o banco não oferece suporte técnico para integração por API. O caminho é o gerente da conta.