Ligar a cobrança integrada com o banco

Com a cobrança integrada, o sistema registra o boleto ou o Pix no banco quando uma venda é faturada, e baixa o título sozinho quando o cliente paga. Ligar isso pede três configurações, nesta ordem: a conta bancária, o tipo de título e a parcela do tipo de negociação.

Se a operação emite nota fiscal, o título só vai ao banco depois que a nota é autorizada. Veja Quando a operação emite nota fiscal.

1. A conta bancária

Em Financeiro › Cadastros › Contas Bancárias, abra a conta (duplo clique) e vá à aba Integração bancária.

Os campos, cada um com a dica do sistema em Contas Bancárias:

• Provedor da Cobrança Integrada — Nenhum, Santander, Pix (Banco Central) ou Simulado. O Simulado só funciona fora de produção, para ensaiar a jornada inteira sem um banco de verdade.
• Banco da API, Ambiente da API (Produção ou Sandbox, de homologação) e as URLs de API e de token, com os Escopos OAuth.
• Chave Pix, Convênio e Carteira, quando o banco exige.
• Validade do Pix (dias) — os dias após o vencimento em que o Pix ainda pode ser pago. Vazio, vale 30.
• Integração Ativa — liga a cobrança e a baixa automática da conta. Título negociado antes da ativação não retroage.

As credenciais secretas — o client id, o client secret e o certificado — não ficam nessa tela. Grave-as em Acompanhamento de Boletos, na aba Contas; veja configurar as credenciais da conta bancária integrada.

Depois de salvar, selecione a conta na grade e abra Mais ações › Ações da tela:

• Testar conexão confirma que o sistema alcança o banco.
• Gerar URL do webhook cria o endereço pelo qual o banco avisa os pagamentos, e o cadastra no banco. A URL anterior deixa de valer.

As duas ações exigem permissão para alterar Contas Bancárias. Veja mais sobre o webhook do Santander adiante.

O campo Ativada em

Ao gravar a conta (inclusão ou alteração), o sistema preenche o campo Ativada em com a data e a hora do momento, desde que a Integração Ativa esteja ligada e Ativada em esteja vazio. O campo não é editável: você não digita a data.

A cobrança automática exige essa data. Sem ela, nenhum título da conta vai ao banco sozinho.

• A primeira ativação vale para sempre. Salvar a conta de novo não move a data, porque ela só é preenchida quando está vazia.
• Conta inativa não recebe a data. Com a integração desligada, o campo continua vazio.
• Conta que já estava ativa e com Ativada em vazio passa a ter a data preenchida na próxima vez que for salva. Basta salvá-la uma vez.

O preenchimento acontece depois da gravação, na inclusão, na alteração e na edição em lote.

Para ativar uma conta:

1. Abra a conta bancária e ligue Integração Ativa.
2. Salve a conta.
3. Abra a conta de novo e confira que Ativada em está preenchido.

O convênio do Santander

O Convênio é o código de cobrança que o banco informa para a conta. A dica do campo na tela cita só o Banco do Brasil como exemplo de banco que exige convênio; ela não fala do Santander nem dos zeros à esquerda. Na conta Santander, vale o que está aqui.

O convênio vale pelo número, com ou sem zeros à esquerda, com até 9 dígitos. O sistema tira os zeros à esquerda antes de enviar ao banco. Por exemplo, 001234567 vai ao banco como 1234567; por isso 001234567 e 1234567 valem o mesmo.

A mesma regra vale para tudo o que o sistema pede ao banco com o convênio:

• o registro do boleto;
• o PDF do boleto;
• a consulta;
• a baixa;
• o cadastro do webhook.

Se o convênio estiver vazio, só com zeros ou com mais de 9 dígitos, o sistema recusa a cobrança sem chamar o banco, com a mensagem: “Informe o convênio de cobrança da conta (até 9 dígitos).” Antes, o convênio do Santander precisava ter exatamente 7 dígitos. O limite de 9 existe porque o convênio do Sandbox do banco vem com 9 dígitos.

O motivo de o sistema sempre tirar os zeros: uma conta cadastrada com 000412704 e um boleto enviado com 412704 davam o erro de convênio não encontrado (COVENANT_NOT_FOUND) em produção. Hoje o banco recebe o mesmo número, sem zeros, em todas as chamadas, e os dois jeitos de digitar funcionam.

Se você mudar o convênio da conta, gere a URL do webhook de novo, porque o convênio também vai ao banco no cadastro do webhook e a configuração gravada da conta vale por convênio. Veja a próxima seção.

Gerar a URL do webhook na conta Santander

Para gerar o webhook, a conta precisa ter a integração ativa e o provedor definido. Se não tiver, a mensagem é: “Ative a integração e o provedor antes de gerar o webhook.”

Gerar o webhook troca a URL anterior: gere de novo só quando mudar a conta, o ambiente ou o convênio. A URL completa aparece uma única vez, e o sistema guarda só o hash dela. Se o banco recusar, o hash anterior é restaurado.

Na conta Santander, Gerar URL do webhook configura no banco dois produtos, cada um por si:

• Cobrança, que só é configurada se a conta tem Convênio;
• Pagamentos, que só é configurado se a conta tem agência e conta.

Se o banco aceita um e recusa o outro, o que foi aceito continua configurado: a recusa de um não desfaz o outro. Você pode ter só um dos dois preenchidos; a conta precisa ter pelo menos um.

O que a mensagem diz:

• Se o banco aceita a cobrança e recusa os pagamentos, a mensagem começa por “Webhook configurado para Cobrança.” e segue com “Pagamentos: “ mais o motivo da recusa do banco.
• Se os dois são recusados, a mensagem lista “Cobrança: …” e “Pagamentos: …”, cada um com o seu motivo.
• Se um dos dois falha, a mensagem diz qual falhou e avisa que o outro ficou com a URL nova.

O endereço do webhook e o token só são mostrados quando o banco aceita tudo, e o token aparece uma única vez: copie-o na hora. Numa recusa parcial, o diálogo mostra só a mensagem de erro, sem o endereço. Mesmo assim, a nova chave de validação da URL é mantida, porque o produto que o banco aceitou já aponta para a URL nova.

Além dos casos acima, o sistema recusa a conta antes de configurar o webhook nestes casos:

• sem convênio e sem agência/conta: “Informe o convênio (cobrança) ou agência/conta (pagamentos) da conta.”;
• agência com mais de 4 posições;
• conta com dígito com mais de 12 posições.

A configuração do Santander continua gravada depois de uma atualização

Ao configurar a conta, o banco devolve o identificador da configuração Santander da conta (o “workspace”). O sistema grava esse identificador no cofre da conta, junto das credenciais, e não só na memória. Em produção, a consulta ao banco volta vazia, e o dado guardado só em memória se perdia a cada atualização do sistema: depois dela, toda ação Santander pedia para gerar a URL do webhook de novo. Hoje isso não acontece, e você não precisa gerar a URL do webhook de novo depois de uma atualização.

Nada muda nas telas nem nos campos; o efeito é o erro de configuração deixar de aparecer depois das atualizações.

O que depende dessa configuração:

• Registrar boleto e enviar instrução no boleto (baixar, prorrogar, desconto, protesto e semelhantes) dependem da configuração de cobrança da conta. Sem ela, o sistema recusa com a mensagem: “Workspace do Santander não encontrado para esta conta – use “Configurar webhook” na conta para criá-lo.” A mensagem cita “Configurar webhook”; a ação que cria a configuração no menu da conta é a Gerar URL do webhook, descrita acima.
• A conferência de pagamento do boleto consulta o boleto direto pelo convênio e pelo nosso número, sem exigir essa configuração da conta.

Como o sistema encontra a configuração: procura primeiro na memória, depois no que está gravado na conta e só então na listagem do banco. Se a acha na listagem, grava na conta.

• Contas que já estavam configuradas passam a ter o dado gravado na primeira ação aceita pelo banco ou na próxima vez que você gerar a URL do webhook.
• A configuração gravada vale por conta, ambiente (Sandbox ou Produção), tipo (cobrança ou pagamentos) e convênio. Trocar o ambiente ou o convênio da conta não reaproveita a configuração anterior: gere a URL do webhook de novo.
• Se o banco disser que a configuração gravada não existe mais (HTTP 404), ao gerar a URL do webhook de novo o sistema esquece a gravada, cria uma nova e grava no lugar.

O PDF do boleto emitido pelo banco

Na conta Santander, o PDF do boleto é o arquivo que o próprio banco emite. O sistema pede ao banco o link do PDF e baixa o arquivo. Isso vale só para título com boleto registrado; sem registro, a mensagem é: “Este título não tem boleto registrado no banco.”

O que o sistema confere no download:

• o link só é aceito se for https e do domínio santander.com.br;
• quando o link aponta para o endereço da própria API do banco, o download usa a credencial da conta (em produção, esse link voltava 403 sem a credencial);
• o arquivo precisa ser um PDF e ter no máximo 5 MB.

Por isso você pode ver estas mensagens:

• “O arquivo devolvido pelo banco não é um PDF.”
• “O arquivo devolvido pelo banco passa do tamanho máximo aceito para o boleto.”
• “Não foi possível baixar o PDF do boleto no banco (HTTP 403, host boletos.santander.com.br).” Ela informa o status e o endereço (host) do banco que recusou, e não repete o link, que é assinado. O status e o host mudam conforme a resposta do banco.

O PDF traz os dados enviados ao banco: a multa, os juros e o No. do Documento. Esse número segue a regra de O número impresso no boleto: o da nota autorizada (na NFS-e, o número da nota, não o da DPS) e, sem nota, o número do título.

A rota que entrega o PDF exige permissão de alterar em TBLFIN e de consultar em TBLPAR, porque o PDF traz os dados do pagador. Sem essas permissões, a pessoa recebe o erro 403.

No envio da nota por e-mail, o sistema gera um PDF por título com boleto registrado, para anexar ao e-mail. Se o banco falhar em algum título, o PDF desse título fica de fora: o envio não é bloqueado e a falha de um título não derruba os outros. Nesse caminho você não vê a mensagem de erro detalhada, só percebe que o anexo não veio.

Veja também baixar o PDF de um boleto registrado e enviar o boleto em PDF no e-mail do documento.

Para conferir o boleto registrado, use Acompanhamento de Boletos, no menu Financeiro › Rotinas.

2. O tipo de título

Em Financeiro › Cadastros › Tipo de Título, o campo Forma de Cobrança Integrada decide como os títulos do tipo são cobrados. A dica do sistema diz: “Opcional. Boleto ou Pix: o sistema registra no banco os títulos a receber confirmados deste tipo, numa conta com integração bancária ativa. Em branco, vale Pix; escolha Nenhuma para os títulos deste tipo não serem registrados no banco.” Os campos estão em Tipos de Título.

Na prática:

Forma de Cobrança Integrada	O que o sistema faz
Boleto	Registra o título como boleto.
Pix	Registra o título como Pix.
Em branco	Registra como Pix.
Nenhuma	Não integra o título com o banco.

Para o boleto automático, o tipo de título precisa ter a forma Boleto. Um tipo de título deixado em branco manda o título como Pix, e isso não é erro de cadastro: é o que o sistema entende por “em branco”.

No Santander, o Pix puro é recusado, com a mensagem: “Na conta Santander a cobrança vai como boleto com QR Pix — use a forma Boleto.” Para os títulos de uma conta Santander, use a forma Boleto no tipo de título.

Se o tipo de título estiver como Nenhuma, o registro é recusado com a mensagem: “O tipo de título deste título está configurado para não integrar com o banco.”

3. A parcela

No tipo de negociação, a parcela ganha a Conta de Cobrança: a conta que cobra a parcela. O título que nasce da parcela herda a conta. Sem conta, a cobrança integrada não inclui o título. Os campos estão em Parcelas da Negociação.

Quando um título vai ao banco sozinho

O título vai ao banco sozinho quando todas estas condições são verdadeiras:

• é um título a receber;
• é firme (não é provisão);
• tem saldo;
• está numa conta com Integração Ativa e provedor diferente de Nenhum;
• o tipo de título não tem a forma de cobrança Nenhuma;
• a conta tem Ativada em preenchido;
• a data de negociação do título é igual ou posterior à data de ativação;
• se a operação (TOP) emite documento fiscal, a nota fiscal já foi autorizada.

A comparação com Ativada em é por dia, não por hora. Um título negociado no próprio dia da ativação, depois dela, também entra. Um título negociado antes da data de ativação não vai ao banco sozinho.

Quando a operação emite nota fiscal

Quando a TOP da operação está configurada para gerar documento fiscal (NF-e, NFC-e, NFS-e ou CT-e), faturar não basta: o título só é elegível para ir ao banco quando o documento tem a nota com situação Autorizado. Antes, o registro no banco espera. Se o boleto não apareceu depois do faturamento, ele pode estar esperando a autorização da nota.

• Operação sem documento fiscal continua registrando o boleto na hora.
• Nota Pendente, Rejeitada, Cancelada ou com Falha não libera o título. Só a nota autorizada libera.
• A espera vale para o título que iria ao banco sozinho em geral, e não só para o boleto: na leitura do código, o Pix de uma operação com nota também espera. A regra é aplicada antes da decisão entre boleto e Pix.
• Depois da autorização, o boleto vai ao banco sozinho, sem ação sua. A transmissão fiscal dispara o registro da cobrança assim que a nota é autorizada (e só depois de gravada). Nota rejeitada não dispara. A rotina periódica aplica a mesma regra ao que ficou pendente.
• O registro manual segue a mesma regra. Em Contas a Pagar e Receber, a ação Registrar no banco (em Mais ações), antes da autorização da nota, é recusada com a mensagem: “O título só vai ao banco depois que a nota fiscal do documento for autorizada.” Depois da autorização, o mesmo registro funciona.

Enquanto espera a nota, o título ainda não tem registro no banco e, por isso, não aparece em Acompanhamento de Boletos.

Para acompanhar a nota, veja acompanhar e retransmitir notas.

O número impresso no boleto

O campo No. do Documento do boleto usa, nesta ordem de prioridade:

1. o número da nota fiscal autorizada;
2. o número do documento (NUMDOC) do próprio título;
3. o número do documento (NUMDOC) da operação;
4. o número de controle do título (NUFIN).

Na NFS-e, vale o número da NFS-e emitido pela prefeitura; nas demais notas, vale o número da nota. Por exemplo, para uma NFS-e de número 121, o boleto sai com “121” no No. do Documento, e não com o número interno do título. Antes dessa mudança, o boleto era registrado no faturamento e saía com o número do título.

O e-mail da operação espera o boleto

Quando a configuração de e-mail da operação pede o boleto, o e-mail não sai sem o PDF do boleto. Se o título ainda não foi registrado no banco (por exemplo, porque espera a nota), se o boleto está Pendente ou se o PDF ainda não veio do banco, o sistema considera a falha transitória e tenta de novo, com a mensagem: “Aguardando o registro do boleto no banco; o e-mail sai com todos os anexos.”

O passo a passo do envio, e o que fazer com o e-mail em erro, estão em enviar o boleto em PDF no e-mail do documento.

• As novas tentativas acontecem em intervalos crescentes: 1, 5, 15, 60 e 180 minutos. Depois da 5ª retentativa, o e-mail passa a ERRO.
• Se o banco recusar o boleto (Rejeitado), o e-mail vai direto a ERRO, com a mensagem: “O banco recusou o boleto de um título deste documento; o e-mail não sai sem ele. Corrija o registro e reenvie.”
• Se o banco da conta não oferece o PDF do boleto, o e-mail também vai a ERRO: “O banco desta conta não oferece o PDF do boleto; o e-mail não sai sem ele.”
• Erro de configuração vai a ERRO direto, sem nova tentativa.

O bloco de cobrança no corpo do e-mail (o marcador $BOLETO, com a linha digitável e o link) só aparece quando a configuração da operação marca o envio do boleto. O texto padrão, quando não há modelo, também só leva a seção “Cobrança” nesse caso.

O que acontece depois

O envio automático acontece de duas formas:

• Logo depois de efetivar ou faturar o documento, em segundo plano. Se essa tentativa falhar, a falha não aparece para você: ela só fica no log do sistema. Em operação com nota fiscal, o registro espera a autorização da nota.
• Por uma rotina periódica, que registra o que ficou pendente. O intervalo padrão da rotina é de 2 minutos. Ela usa a mesma condição de elegibilidade acima, incluindo a data Ativada em e a nota autorizada.

Ao faturar a venda pelo portal numa operação sem nota fiscal, o título nasce com a conta e o tipo de título da parcela e vai ao banco; poucos segundos depois ele já aparece registrado, com nosso número, linha digitável e código de barras. Numa operação com nota, isso acontece depois da autorização da nota. Quando o cliente paga, o banco avisa, o sistema confere o pagamento e baixa o título — com o lançamento na conta e a situação Pago no banco.

Acompanhe tudo em acompanhar boletos e Pix.

Reenviar um título que o banco recusou

Nem toda falha é recusa. Falha de rede, tempo esgotado ou erro do lado do banco (5xx) não são recusa: o registro fica Pendente, com a mensagem do banco, e o sistema tenta de novo depois. Só a recusa de verdade do banco (4xx) deixa o registro Rejeitado, e é esse o estado que o reenvio manual corrige.

O caso típico: o tipo de título estava em branco, o título saiu como Pix e a conta Santander o recusou. Para corrigir:

1. Em Tipo de Título, ponha a Forma de Cobrança Integrada como Boleto no tipo usado na negociação.
2. Em Acompanhamento de Boletos, na aba Cobranças, ache o título com situação Rejeitado e reenvie o registro dele.
3. Confira se o título passou a Registrado, com nosso número, linha digitável e código de barras.

O reenvio usa a forma de cobrança que o tipo de título tem agora, e não a da primeira tentativa. Ele reaproveita o mesmo registro de cobrança do título, sem criar outro; se o banco aceita, a situação passa a Registrado.

Regras do reenvio:

• A troca vale só de Pix recusado para Boleto. Um boleto Rejeitado continua boleto no reenvio, mesmo que o tipo de título tenha virado Pix: ele pode estar vivo no banco, e trocar de forma causaria cobrança em dobro.
• O que já está registrado no banco não muda. A correção do tipo de título só afeta o título recusado.
• Com o tipo de título em Nenhuma, o reenvio é recusado com a mensagem de que o tipo não integra com o banco.

Problemas comuns

Faturei, mas o boleto não apareceu. Se a operação emite nota fiscal, o título espera a autorização da nota. Confira a situação da nota; quando ela estiver Autorizada, o boleto vai ao banco sozinho. Se a nota estiver rejeitada, cancelada ou com falha, o título não é registrado.

“O título só vai ao banco depois que a nota fiscal do documento for autorizada.” Você tentou registrar o título antes da autorização da nota. Espere a autorização; o registro acontece sozinho, ou você pode registrar de novo depois.

O título não foi ao banco sozinho. Confira, nesta ordem: se a conta tem Integração Ativa e Ativada em preenchido; se a data de negociação do título é igual ou posterior à data de ativação; se o tipo de título não está com forma Nenhuma; se a parcela tem Conta de Cobrança; se o título é a receber, firme e com saldo; e, em operação com nota fiscal, se a nota já foi autorizada.

A conta está ativa, mas Ativada em está vazio. Salve a conta uma vez; o campo é preenchido na gravação.

“Na conta Santander a cobrança vai como boleto com QR Pix — use a forma Boleto.” O tipo de título está com a forma Pix (ou em branco). Troque para Boleto e reenvie o título.

Corrigi o tipo de título, mas o título continua recusado. Confira se o título saiu como Pix e agora o tipo está como Boleto: é a única troca que o reenvio faz. Um boleto recusado continua como boleto.

“Informe o convênio de cobrança da conta (até 9 dígitos).” Corrija o Convênio da conta: ele precisa ter de 1 a 9 dígitos, com ou sem zeros à esquerda, e não pode ser só zeros.

Mudei o convênio ou o ambiente da conta Santander. Gere a URL do webhook de novo: a configuração gravada vale por ambiente e convênio, e o convênio também vai ao banco no cadastro do webhook. Isso troca a URL anterior.

“Workspace do Santander não encontrado para esta conta – use “Configurar webhook” na conta para criá-lo.“ Registrar boleto e enviar instrução no boleto precisam da configuração de cobrança da conta, e ela não está gravada (conta ainda não configurada, ou ambiente ou convênio trocado). Use Gerar URL do webhook na conta. Depois de configurada, a conta não pede isso de novo a cada atualização do sistema. Se o banco disser que a configuração gravada não existe mais, gerar a URL do webhook de novo cria uma nova e grava no lugar.

“Ative a integração e o provedor antes de gerar o webhook.” A conta ainda não tem a Integração Ativa ou o Provedor da Cobrança Integrada definido. Corrija os dois, salve e gere a URL de novo.

“Webhook configurado para Cobrança.” seguido de “Pagamentos: …”. O banco aceitou a cobrança e recusou os pagamentos. A cobrança continua configurada. Corrija o que o banco apontou (por exemplo, agência e conta da conta) e gere a URL do webhook de novo.

“Não foi possível baixar o PDF do boleto no banco (HTTP 403, host …).” O banco recusou a entrega do PDF. A mensagem traz o status e o endereço do banco que respondeu; ela não traz o link, que é assinado.

“Este título não tem boleto registrado no banco.” O PDF só existe para título com boleto registrado. Confira em Acompanhamento de Boletos se o título já foi registrado.