Safra (422): boleto pela API de Cobranças
Como ligar a cobrança do Safra no Hap: as credenciais do Safra Negócios (Client ID, Username e Password), os campos do convênio, e por que a baixa do boleto pago demora alguns minutos - o Safra não tem webhook e a baixa depende de consulta periódica. Explica também o que o Hap faz quando o banco demora a confirmar, recusa o boleto por duplicidade ou quando se cancela um boleto que pode estar registrado.
Quando usar
Use ao configurar a conta Safra pela primeira vez ou quando o cliente reclamar que o boleto pago demorou a dar baixa no sistema.
Antes de começar
- Credenciais do Safra Negócios solicitadas ao gerente, pelo portal de desenvolvedores.
- Conta Safra cadastrada no Hap.
O que essa integração faz
Com o convênio Safra configurado, o Hap emite, consulta e baixa boletos pela API do Safra Negócios, e baixa o PDF do boleto direto do banco. É uma integração mais enxuta que a dos outros bancos: não há Pix, não há extrato e não há webhook.
| Recurso | Como funciona |
|---|---|
| Boleto | Emitir, consultar, alterar e baixar pela API do Safra Negócios. |
| PDF do boleto | Baixado direto do banco. |
| Webhook | Não existe. A baixa depende de consulta periódica do sistema. |
| Pix | Não suportado. |
| Extrato | Não suportado. Use o arquivo OFX em Caixas e Contas. |
Antes de começar: o que pedir ao Safra
- 1
Solicite ao gerente do Safra Negócios o acesso ao portal de desenvolvedores.
- 2
O Safra entrega o Client ID, o Username e o Password do parceiro, usados para gerar o token.
- 3
Confirme para qual ambiente as credenciais valem. Elas são separadas entre HOM e PROD.
Preencher o convênio no Hap
| Campo no formulário | O que preencher |
|---|---|
| Client ID (obrigatório) | O identificador informado pelo Safra para o OAuth. |
| Username (obrigatório) | O usuário do parceiro, usado para gerar o token. |
| Password (obrigatório) | A senha do parceiro, usada para gerar o token. |
| Ambiente (obrigatório) | HOM para homologação, PROD para produção. As credenciais são diferentes em cada um. |
| Número | O código do beneficiário fornecido pelo Safra. |
| Carteira | A carteira fornecida pelo Safra. |
| Correlation ID fixo | Opcional. Identificador enviado em todas as chamadas, útil para rastrear nos registros. |
Quando o Safra demora a confirmar o boleto
Ao emitir, o Hap envia o boleto ao Safra e, assim que o banco aceita, já guarda o registro (nosso número e código de barras). A confirmação completa - a linha digitável e o Pix - vem numa consulta logo em seguida. Se essa consulta demora ou falha, o boleto não vai mais para Falha na emissão: ele fica registrado, com o aviso "Boleto registrado no Safra. A confirmação (linha digitável e PIX) não voltou a tempo e será buscada de novo automaticamente.", e o Hap volta a consultar o banco sozinho até completar.
O Consultar do Painel de Boletos também encontra no Safra um boleto que ficou sem nosso número (pelo número enviado na emissão) e grava o registro. É o caminho para recuperar um boleto antigo que ficou em Falha na emissão embora o banco o tivesse aceitado.
Recusa por duplicidade
O Safra não aceita dois boletos do mesmo título com o mesmo valor e vencimento. Quando ele recusa por isso, o Hap procura entre as tentativas anteriores do mesmo título o boleto que ficou registrado no banco. Achando um boleto vivo e confirmado como deste título, o boleto atual passa a usar esse registro, e a tentativa antiga fica cancelada no Hap com a observação "Registro no Safra assumido pelo boleto ...". Assim o título fica com um boleto só, igual ao do banco.
| Mensagem (início) | O que fazer |
|---|---|
| "O Safra recusou: já existe um boleto deste título com o mesmo valor e vencimento que foi baixado..." | O banco ainda conta o boleto baixado. Altere o vencimento do título e emita de novo. |
| "O Safra recusou: já existe um boleto deste título... e ele não foi encontrado entre as tentativas do Hap." | Confira o boleto no internet banking do Safra ou altere o vencimento do título. |
| "O Safra informou que já existe um boleto deste título, mas a consulta para localizar o registro não respondeu." | Tente de novo em alguns minutos. Não altere o vencimento antes de confirmar. |
| "O Safra já tem o boleto deste título e o registro já está com outro boleto do Hap." | Confira os boletos do título antes de emitir de novo: outro boleto já representa o do banco. |
Cancelar um boleto que pode estar no banco
Um boleto em Falha na emissão (ou Aberto) que chegou a ser enviado ao Safra pode ter sido registrado sem que a resposta voltasse. Cancelar só no Hap deixaria um boleto pagável no banco sem título no sistema. Por isso, ao clicar em Cancelar nesse boleto, o Hap consulta o Safra antes:
| Resposta do banco | O que acontece |
|---|---|
| O boleto está registrado | Nada é cancelado ainda: o boleto volta para a aba Boleto Registrado. Para tirá-lo do banco, use Cancelar Boleto no Banco nessa aba. |
| O boleto não existe no banco | O boleto é cancelado no Hap, como antes. |
| O boleto já foi pago ou baixado | O boleto não é cancelado; a mensagem informa a situação dada pelo banco. |
| Sem resposta, ou resposta sem os dados que confirmam o boleto | Nada é cancelado: "Não foi possível confirmar no Safra se este boleto chegou a ser registrado... tente de novo em alguns minutos." |
| A consulta nem saiu (convênio ou credencial com problema) | Nada é cancelado: "Não foi possível consultar o Safra (confira o convênio e a credencial da conta)." |
Troca de vencimento
Quando o vencimento do título muda, os boletos antigos costumam ser cancelados para emitir o novo. No Safra, o boleto que pode estar registrado no banco não é cancelado só no Hap: ele continua como está, com o aviso "O vencimento do título mudou, mas este boleto pode estar registrado no Safra e não foi cancelado automaticamente. Use Cancelar no boleto (ele consulta o banco antes) e emita de novo." Siga o aviso: o Cancelar confere o banco e indica o caminho certo.
Problemas comuns
- O boleto foi pago e o título continua aberto: é esperado por alguns minutos. O Safra não tem webhook, então a baixa depende de uma consulta periódica do sistema.
- Testar credenciais falha logo na autenticação: confira se o Ambiente casa com as credenciais. O Safra entrega conjuntos diferentes para HOM e para PROD, e trocá-los faz o token ser recusado.
- O extrato do Safra não aparece: o Safra não tem API de extrato de conta corrente. Importe o arquivo OFX em Caixas e Contas.
- Um boleto antigo ficou em Falha na emissão, mas o Safra tinha aceitado: no Painel de Boletos, aba Falha na emissão, use Consultar no boleto. O Hap busca o boleto no banco pelo número enviado na emissão e, achando, grava o registro. Não reemita antes de consultar.
- Ao emitir de novo, o Safra recusou por duplicidade: o banco não aceita dois boletos do mesmo título com o mesmo valor e vencimento. O Hap procura o boleto que já está registrado e passa a usá-lo; se a mensagem disser que o boleto existente foi baixado, altere o vencimento do título e emita de novo.
- Cliquei em Cancelar e o boleto voltou para a aba Boleto Registrado: a consulta achou o boleto vivo no Safra. Para tirá-lo do banco, use Cancelar Boleto no Banco nessa aba.
- Apareceu "Não foi possível confirmar no Safra se este boleto chegou a ser registrado": o banco não respondeu a tempo, e o Hap não cancela sem saber. Tente de novo em alguns minutos.
- Mudei o vencimento do título e o boleto antigo não foi cancelado: no Safra, o boleto que pode estar registrado no banco não é cancelado só no Hap. Use Cancelar no boleto (ele consulta o banco antes) e emita o novo.