O que é uma Carteira de Cobrança
A Carteira de Cobrança é o cadastro que representa a "conta bancária" (ou o gateway de pagamento) usada pelo seu provedor para receber dos clientes. É nela que ficam os dados do banco, agência, conta, convênio e carteira bancária — ou, no caso de um gateway de pagamento, as chaves de integração. Sem uma Carteira de Cobrança cadastrada e configurada corretamente, o sistema não consegue gerar nenhum boleto, Pix ou cobrança de cartão: todo débito financeiro precisa estar vinculado, através do contrato do cliente, a uma configuração de cobrança (chamada tecnicamente de Carteira Modelo) que por sua vez pertence a uma Carteira. Se esse vínculo não existir ou estiver malfeito, o sistema não sabe "em nome de quem" e "com qual layout" emitir a cobrança — e é exatamente aí que aparecem os erros mais comuns de "layout de impressão" e "conta inválida" na hora de gerar o boleto.
Em resumo, existem dois cadastros que trabalham juntos:
-
Carteira — os dados cadastrais e bancários da "conta" (razão social, CNPJ, banco, agência, conta, convênio, carteira bancária).
-
Configuração para cobrança (Carteira Modelo) — dentro da Carteira, define como a cobrança vai se comportar: tipo de cobrança (boleto, Pix, cartão), juros, multa, desconto, instruções impressas no boleto, layout, e, se for o caso, as credenciais do gateway.
É essa Configuração para cobrança que depois é vinculada ao contrato do cliente, no campo "Forma de pagamento padrão".
Gateway/API × Remessa e Retorno (CNAB tradicional): qual escolher
O sistema Quaza suporta dois modelos bem diferentes de cobrança bancária. Entender a diferença antes de cadastrar evita configurar a carteira errada:
1. Gateway (API online)
O sistema se conecta diretamente à API do banco ou da instituição de pagamento (ex.: Sicredi, Sicoob, Banrisul, Banco do Brasil, Itaú, Asaas, Cielo, GalaxPay, Mercado Pago, Efí, entre outros) usando chaves de integração (Client ID, Client Secret, Token Público/Privado). O boleto, Pix ou cobrança de cartão é criado e consultado em tempo real pela internet, sem precisar de arquivos de remessa/retorno.
-
Vantagens: confirmação de pagamento automática (o sistema consulta o gateway periodicamente), não depende de baixar/subir arquivo no Internet Banking, suporta Pix e cartão nativamente, permite Pix Automático em alguns bancos (Sicredi e Efí).
-
Quando usar: é o modelo recomendado para a maioria dos provedores hoje em dia, principalmente se o banco oferecer integração via API.
2. Remessa e Retorno (CNAB tradicional / débito em conta)
É o modelo "clássico": o sistema gera um arquivo de remessa (CNAB 240, por exemplo) que você mesmo carrega manualmente no Internet Banking do seu banco, registrando os boletos ou débitos em conta. Depois, o banco devolve um arquivo de retorno, que precisa ser importado de volta no sistema para dar baixa (confirmar) os pagamentos.
-
Vantagens: funciona com bancos que ainda não têm integração via API disponível no sistema.
-
Desvantagens: processo manual (subir remessa, baixar retorno, importar retorno), confirmação de pagamento não é em tempo real.
-
Quando usar: quando o banco do provedor não está na lista de gateways disponíveis, ou quando o provedor já opera com débito em conta tradicional.
Na tela de cadastro, o campo Banco já deixa claro qual é qual: as opções que começam com "Gateway - ..." (ex.: "Gateway - Sicredi", "Gateway - Asaas", "Gateway - Banrisul") usam API; as opções sem o prefixo "Gateway" (ex.: "Sicredi", "Banco do Brasil", "Banrisul", "Itaú", "Bradesco", "Caixa Econômica Federal", "Santander", "Unibanco", "Safra", "Sicoob/Bancoop", "Cresol") usam o modelo tradicional de remessa/retorno. Também existe a opção "Caixa local", usada para cobrança sem banco (pagamento presencial, dinheiro em caixa).
Pré-requisitos: dados que o banco fornece
Antes de começar, tenha em mãos os dados fornecidos pelo seu banco (geralmente no contrato de cobrança/convênio firmado com o banco):
| Dado |
Para que serve |
| Código do banco |
Identifica o banco/gateway na lista de opções do sistema |
| Agência (e dígito) |
Agência bancária da conta de recebimento |
| Conta (e dígito) |
Conta bancária de recebimento |
| Convênio (e dígito) |
Número de convênio de cobrança junto ao banco (obrigatório para a maioria dos bancos tradicionais) |
| Carteira bancária |
Código da carteira de cobrança definido pelo banco (ex.: 09/06/03 no Bradesco, 175/174/178/104/109/157 no Itaú, "A" no Sicredi, CCB no Banrisul, SIGCB na Caixa) |
| Cedente (e dígito) |
Código do cedente, exigido por alguns bancos (ex.: Caixa) |
| Contrato |
Número do contrato/posto de cobrança (usado por alguns bancos, como o Sicredi) |
| Chaves de integração (só para Gateway) |
Client ID / Client Secret / Token Público / Token Privado, obtidos no painel do gateway ou fornecidos pelo banco ao habilitar a API |
Além disso, tenha em mãos os dados cadastrais que identificam a empresa que vai emitir a cobrança: Razão Social, Nome Fantasia e CNPJ (se forem diferentes da empresa principal já configurada no sistema).
Passo a passo: como cadastrar a Carteira de Cobrança
O cadastro é feito por um assistente (wizard) em 4 etapas. Acesse o menu Financeiro → Carteira e clique em "Adicionar" para abrir o assistente de Criação de carteira.
Etapa 1 — Configuração da carteira
-
Descrição: nome interno da carteira, para você identificar (ex.: "Sicredi - Boleto/Pix", "Caixa Local").
-
CNPJ: CNPJ da empresa cedente. Se em branco, o sistema usa o CNPJ da empresa principal.
-
Geração de notas: define quando a nota fiscal deve ser emitida para os débitos desta carteira — Manual, Conforme contrato (segue a configuração do contrato do cliente) ou Ao realizar o recebimento (a nota é gerada só quando o boleto é pago).
-
Criar modelo de carteira: deixe marcado (padrão "Sim") para que o assistente já crie, na sequência, a primeira Configuração para cobrança junto com a carteira. Se desmarcar, o assistente pula direto para o resumo e você cria a configuração de cobrança depois, manualmente.
-
Razão Social e Fantasia: dados da empresa que aparecem no boleto.
-
Banco: selecione o banco ou gateway (veja a seção anterior para escolher entre modelo Gateway/API ou Remessa/Retorno CNAB). Esta escolha é definitiva depois de a carteira ter movimentações — o campo fica bloqueado para edição assim que houver algum registro em Configurações para cobrança vinculado.
-
Contrato: número de contrato/posto de cobrança, se o banco exigir (ex.: Sicredi).
-
Carteira: código da carteira bancária (consulte a tabela de pré-requisitos acima ou a descrição exibida ao lado do campo Banco na tela, que lista as carteiras aceitas por banco).
-
Variação Carteira: variação da carteira, quando o banco exigir.
-
Conta e Conta (Dígito): número da conta bancária de recebimento.
-
Agência e Agência (Dígito): número da agência.
-
Convênio e Convênio (Dígito): número de convênio de cobrança.
-
Cedente e Cedente (Dígito): código do cedente (exigido por alguns bancos, como Caixa).
Clique em Avançar.
Etapa 2 — Configuração de cobrança
Esta etapa só aparece se "Criar modelo de carteira" estiver marcado como Sim na etapa anterior.
-
Descrição: nome da configuração de cobrança (ex.: "Boleto Sicredi 30 dias").
-
Espécie documento: espécie do título (padrão: Duplicata Mercantil).
-
Financeiro zerado: permite ou não gerar cobranças com valor R$ 0,00.
-
Local de pagamento: texto livre impresso no boleto (ex.: "Pagável em qualquer banco até o vencimento").
-
Período para operação: quantos dias úteis somar à data de pagamento para definir a data de operação (crédito) — deixe 0 se a data de operação deve ser igual à data de pagamento.
-
Tipo de identificador cliente e Tamanho mínimo identificador: definem como o cliente é identificado no arquivo/gateway (por ID do cliente no sistema, por CPF/CNPJ ou por um ID próprio).
-
Conta para Capital / Conta para juros-multa / Conta para desconto: contas contábeis financeiras para onde o valor recebido, os juros/multa e os descontos concedidos serão lançados.
-
Tipo de cobrança: a lista de opções muda automaticamente conforme o Banco escolhido na etapa 1 — por exemplo, "Gateway - Asaas" libera Boleto, Boleto/Pix e Pix; um banco tradicional como Bradesco libera Boleto e Boleto/Pix; gateways de Pix Automático (Sicredi Pix Automático, Efí Pix Automático) liberam somente Pix Automático.
-
Carteira Auxiliar: opcional — vincula uma segunda forma de cobrança "inversa" (ex.: se esta é Boleto, a auxiliar pode ser um Pix) para oferecer ao cliente uma opção extra de pagamento.
-
Tipo de emissão (CNAB) e Tipo de cobrança (CNAB): aplicáveis a bancos com registro (CNAB), definem se quem emite o boleto é o próprio banco ou o sistema, e o tipo de cobrança no arquivo.
-
Tipo de registro: Sem registro, Registrado (Débito em conta) ou Registrado (CNAB 240) — só o Sicoob aceita mais de 30 dias de protesto com registro CNAB 240; os demais bancos ficam limitados a 2–30 dias.
-
Layout: Simples (1 boleto por página) ou Carnê (3 por página) — para Pix, a lista de layouts muda automaticamente.
-
Adicionar tarifa no boleto e Tarifa do boleto: se marcado, soma um valor fixo de tarifa bancária ao valor cobrado do cliente.
-
Faixa do boleto: usado na composição do nosso número (padrão 2).
-
Chave Pix: chave Pix usada para gerar o QR Code em carteiras próprias, ou como chave em alguns gateways. Use somente números para CPF/CNPJ (sem pontuação) e o formato +55CódigoNúmero para telefone. Deixe em branco para não gerar Pix.
-
Baixa de títulos: permite que o sistema dê baixa automática (confirme pagamento) por esta carteira.
-
Dias de expiração do boleto: quantos dias após o vencimento o boleto ainda pode ser pago/registrado.
-
Multa (Tipo de cálculo, Valor/taxa e Prazo para aplicação): tipo Percentual = percentual mensal; tipo Valor = valor monetário mensal fixo.
-
Negativar sem protestar e Protesto dias: regras de negativação/protesto — o campo "Negativar sem protestar" só é editável para o banco Sicoob.
-
Juros (Tipo de cálculo e Valor/taxa): tipo Percentual = percentual mensal; tipo Valor = valor monetário diário.
-
Cobrança de débito em conta: para carteiras com débito automático, define se o valor debitado é o original, com juros, com desconto, ou com juros e desconto.
-
Desconto antecipado (Tipo e Taxa/Valor): concede desconto por pagamento antecipado, em percentual ou valor fixo.
-
Instrução 1 a 4: textos livres impressos no corpo do boleto (ex.: "Não receber após o vencimento", "Multa de 2% após o vencimento").
Clique em Avançar.
Etapa 3 — Gateway
Esta etapa só é relevante se o Banco escolhido na etapa 1 for uma opção "Gateway - ...". Se for um banco tradicional (remessa/retorno) ou "Caixa local", pode simplesmente avançar sem preencher nada.
-
Integração Gateway: já vem pré-selecionada de acordo com o banco escolhido na etapa 1.
-
Ambiente: Produção ou Homologação/Sandbox — use Homologação para testar antes de operar com clientes reais, se o gateway oferecer essa opção.
-
Chave Principal (Client ID) e Chave Secreta (Client Secret): credenciais fornecidas pelo gateway/banco no cadastro da aplicação/integração.
-
Token Público e Token Privado: tokens de autenticação exigidos por alguns gateways.
Importante: essas credenciais são específicas de cada gateway — consulte a documentação do banco/gateway escolhido (ex.: painel do Asaas, painel do Sicredi, Efí) para saber exatamente quais campos preencher. Guarde essas chaves com segurança, pois dão acesso à movimentação financeira.
Etapa 4 — Resumo
Revise todos os dados preenchidos nas etapas anteriores. Se algo estiver errado, use o botão Voltar para corrigir. Estando tudo certo, clique em Finalizar. O sistema vai criar a Carteira e, se marcado, a Configuração para cobrança, e te redirecionar para a tela de edição da carteira recém-criada.
Erros comuns
1. "O layout de impressão não foi definido"
Esse erro aparece ao tentar imprimir/gerar o boleto e significa que o sistema não conseguiu determinar qual layout de impressão usar para o banco selecionado na carteira. Isso acontece quando o campo Banco da carteira está com um código de banco que o sistema não reconhece na geração de boletos (por exemplo, "Unibanco" não possui um layout de impressão mapeado no gerador de boletos do sistema) ou quando a Configuração para cobrança não tem o campo Layout preenchido. Solução: confira se o Banco escolhido na carteira é realmente suportado para emissão de boleto (prefira as opções com integração via Gateway, que cobrem a geração de layout automaticamente) e revise o campo Layout na Configuração para cobrança.
2. "Conta inválida!"
Ocorre ao salvar a carteira quando o Banco não é "Caixa local" e o campo Conta está em branco. Solução: preencha a Conta bancária de recebimento — só é permitido deixá-la vazia quando a carteira é do tipo Caixa local (cobrança presencial, sem banco).
3. "Convênio X não está cadastrado no sistema" / "A conta X não está cadastrada no sistema"
Acontece quando um retorno bancário (arquivo CNAB) chega com um número de convênio ou conta que não bate com nenhuma carteira cadastrada e habilitada (situação ativa). Isso costuma indicar convênio/conta digitados errado no cadastro da carteira, ou uma carteira que foi desabilitada mas ainda recebe retornos do banco. Solução: confira se o Convênio (e dígito) e a Conta (e dígito) da carteira batem exatamente com o que consta no arquivo de retorno do banco, e se a carteira está com Situação ativa.
4. Não é possível desabilitar a carteira
Ao tentar desabilitar (Situação = Não) uma carteira ou uma Configuração para cobrança, o sistema bloqueia se: (a) a configuração está definida como carteira padrão do sistema ou padrão de cartão nas Configurações gerais; ou (b) existem contratos ativos ainda vinculados a essa carteira/configuração como forma de pagamento. Solução: primeiro migre os contratos vinculados para outra Configuração para cobrança (o botão "Migrar clientes", dentro da tela da carteira, faz essa migração em lote) e, se for a carteira padrão, troque a configuração padrão do sistema antes de desabilitar.
5. Banco escolhido errado para o modelo de cobrança desejado
É comum confundir a opção de banco tradicional (ex.: "Sicredi") com a opção Gateway equivalente (ex.: "Gateway - Sicredi"). Escolher a opção errada resulta em uma carteira configurada para remessa/retorno CNAB quando, na verdade, o objetivo era usar a API do banco (ou vice-versa) — e as opções de Tipo de cobrança disponíveis mudam completamente entre uma e outra. Solução: releia a seção "Gateway/API × Remessa e Retorno" deste manual antes de escolher o Banco na etapa 1, e lembre-se que, depois que a carteira tiver alguma Configuração para cobrança vinculada, o campo Banco fica bloqueado para edição.
6. Campo Banco bloqueado e não é possível trocar depois de criada
Depois que já existe pelo menos uma Configuração para cobrança (ou algum financeiro/débito) vinculada à carteira, os campos bancários (Banco, Contrato, Convênio, Agência, Conta, Carteira, Variação, Cedente) ficam travados para edição, para não corromper cobranças já emitidas. Solução: se o banco realmente mudou, use o botão "Copiar carteira" (disponível na tela de edição da carteira) para criar uma nova carteira com o novo banco, reaproveitando os demais dados, e depois migre os contratos para a nova configuração de cobrança.
Depois de criar a carteira
-
Vincule a carteira ao(s) contrato(s) do cliente: no cadastro do contrato, o campo "Forma de pagamento padrão" deve apontar para a Configuração para cobrança criada. Esse é o vínculo que efetivamente diz ao sistema qual carteira usar para gerar as cobranças daquele cliente. Você também pode definir uma configuração de cobrança como padrão geral do sistema (Configurações → parâmetro "carteiraModeloPadrao"), que será sugerida automaticamente em novos contratos.
-
Cadastre a Forma de Liquidação (aba "Forma de Liquidação" dentro da tela da carteira), vinculando as contas contábeis de recebimento de capital, juros/multa e desconto às formas de pagamento aceitas (dinheiro, cartão, etc.), se ainda não tiver feito isso na etapa 2 do assistente.
-
Teste a geração de um boleto: gere um débito financeiro de teste (ou use um já existente) vinculado a essa carteira e utilize a opção "Imprimir financeiro" na tela de Financeiro para emitir o boleto/Pix. Confira se o layout, o código de barras/linha digitável (ou QR Code Pix) e os dados bancários impressos estão corretos antes de liberar a carteira para uso em produção com todos os clientes.
-
Se for Gateway, verifique a integração: confirme se as credenciais estão corretas gerando uma cobrança de teste no ambiente de Homologação (se disponível) antes de trocar para Produção.
-
Acompanhe os primeiros recebimentos: use a aba "Movimentações" e "Extrato carteira" (botão na tela da carteira) para conferir se os pagamentos estão sendo reconhecidos e baixados corretamente.