APIs de Cobrança

Este manual irá guiá-lo através das configurações necessárias para utilizar as APIs de cobrança dos bancos integrados ao sistema. Cada banco possui particularidades em sua configuração, mas o processo geral é semelhante.

Acesso à tela de configuração

A configuração é feita na tela de "Tipo de Cobrança Bancária".

Para acessar:

1. No menu principal, vá até o menu Financeiro > Cadastro > Cobrança Bancária
2. Abra a tela Tipo de Cobrança Bancária

Imagem 1 - Caminho Tipo Cobrança Bancária

• Nessa tela, você vê a lista de “tipos de cobrança” já cadastrados (ex.: Banco do Brasil, Sicredi, Sicoob, etc.).

• Para configurar o Sicredi, você pode:
  • Incluir um novo tipo de cobrança; ou
  • Alterar um tipo existente para usar o Sicredi.

Configuração API - Sicredi

Visão Geral da Tela

A tela de configuração do Tipo de Cobrança é dividida em abas. Para configurar a API do Sicredi, você precisará preencher as três abas:

• Aba Dados: Dados bancários e configurações gerais. Nesta aba temos o Layout Arquivo, que será essencial configurar para utilizar a API.

• Aba Dados Bancários: Configuração de dados como agência, conta, convênio, necessárias para o funcionamento das rotinas.
• Aba Conexões Externas: Credenciais e URLs de acesso à API

Aba Dados (Configuração Básica)

Imagem 2 - Aba dados do cadastro do tipo de cobrança bancária

Preencha os seguintes campos:

• Código: Número que identificará este tipo de cobrança
  • Exemplo: 401, 501, etc.

• Nome: Nome descritivo para identificar esta configuração
  • Exemplo: Sicredi API, Sicredi Cobrança Web

• Banco: Selecione o banco Sicredi (748)
  • Use o botão de busca ao lado do campo para localizar

• Módulo Cobrança: Escolha uma das opções do Sicredi:
  • Sicredi Com Registro: Para boletos com registro
  • Sicredi Sem Registro: Para boletos sem registro
  • Sicredi Débito em Conta: Para débitos automáticos em conta

• Modelo Boleto: Escolha o modelo de boleto que será utilizado. Por padrão é código 2 - Boleto.
• Tipo Emissão: Geralmente utiliza-se a emissão própria.
• Espécie: Geralmente é configurado com DM (Duplicata Mercantil).
• Layout Arquivo: Forma de comunicação do sistema com o banco.
  • Arquivos de remessa/retorno CNAB:
    • Código 1 - 240 Posições
    • Código 2 - 400 Posições
  • Api Cobrança: Deve estar selecionada para utilizar a integração da API.

Juros e Multa

Esses campos definem como o boleto vai se comportar em caso de atraso ou desconto, e essas informações são enviadas para o Sicredi. Juros, multa e desconto influenciam na cobrança via API.

• Juros ao dia
  • Campo de percentual, como “% Juros ao Dia”.
  • O que fazer: informar o percentual de juros que será cobrado por dia de atraso.
  • Observação: o sistema não aceita esse campo zerado.

• Tipo de juros
  • Campo com código e descrição do tipo de juros (por exemplo, “percentual ao dia”).
  • O que fazer: escolher o tipo que corresponde à forma de cobrança combinada com o banco.

• Multa
  • Campos de tipo de multa, percentual de multa e quantidade de dias para início da multa (N° Dias para Multa).
  • O que fazer:
    • Definir se haverá multa;
    • Informar o percentual de multa (ex.: 2%);
    • Definir a partir de quantos dias após o vencimento a multa passa a ser cobrada.

• Desconto por antecipação
  • Campos de tipo de desconto, valor/percentual de desconto e dias de desconto.
  • O que fazer: preencher caso ofereça desconto para pagamento antes do vencimento.

Protesto

• Tipo de Protesto:
  • ATENÇÃO: Para Sicredi, NÃO selecione "Dias Úteis" para o módulo cobrança Sicredi Com Registro ou Sem Registro.
  • Use "Dias Corridos" ou outra opção.

• Dias para Protesto: Ex: 5 (protestar após 5 dias)

Aba Dados Bancários

Imagem 3 - Aba Dados bancários do cadastro do tipo de cobrança bancária

Na tela de cadastro de tipo de cobrança, primeiro ajuste os dados básicos do banco. Eles são usados tanto na impressão do boleto quanto na comunicação com o Sicredi.

• Banco
  • Campos normalmente chamados de “Cód. Banco” e “Nome Banco”.
  • O que fazer: escolher o Sicredi na pesquisa.

• Agência e dígito da agência
  • Campos como “Agência” e “Dígito” (Mais à esquerda).
  • Importante: A Sicredi identifica o campo de "Agência" como Código da Cooperativa.
  • O que fazer: preencher com a agência do Sicredi e o dígito, exatamente como informado pelo banco.

• Conta corrente e dígito da conta
  • Campos como “Conta” e “Dígito” (Mais à direita).
  • O que fazer: informar a conta corrente e seu dígito, conforme cadastro no Sicredi.

• Convênio de cobrança
  • Campo "Convêncio" desta aba.
  • Importante: A Sicredi identifica este campo como Código do beneficiário.
  • O que fazer: informar o código de convênio fornecido pelo Sicredi, somente com números (sem pontos ou traços).

• Carteira de cobrança
  • Campo chamado de “Carteira”.
  • O que fazer: informar a carteira usada pelo Sicredi para seus boletos. Esse campo é obrigatório.

• Nome da empresa (beneficiário)
  • Campo como “Nome Empresa”.
    • O que fazer: informar o nome que aparecerá como beneficiário no boleto (normalmente o nome da sua empresa, conforme registro no banco).

• Instruções do boleto
  • Campos como “Instrução 1” e “Instrução 2”.
  • O que fazer: colocar observações que devem aparecer no boleto (ex.: “Após o vencimento, cobrar multa de X% e juros de Y% ao dia”).

Aba Conexões Externas - Credenciais de Acesso

Esta aba contém as informações de acesso à API do banco.

Imagem 4 - Aba Conexões Externas do cadastro do tipo de cobrança bancária

Na Tabela 1 abaixo são explicados os campos da Imagem 4 acima:

Tabela 1

Campo	Descrição	Precisa para Sicredi?
URL Produção	Ambiente real (boletos oficiais)	❌ Não é obrigatório pois é definido internamente
URL Homologação	Ambiente de teste	❌ Não é obrigatório pois é definido internamente
Dev Key (BB)	Chave do desenvolvedor para o Banco do Brasil	❌ NÃO - Deixe em branco
Authorization / Api Key	Access token gerado no portal do desenvolvedor	✅ SIM - Obrigatório
Client ID / User	Código do beneficiário + Código da Cooperativa	✅ SIM - Obrigatório
Client Secret	Código de Acesso gerado no Internet Banking	✅ SIM - Obrigatório (é como uma senha)

Para preencher o Cliente ID / User, deve ser concatenados o código do beneficiário e o código da cooperativa, ou seja, o convênio e a agência. Seguindo o exemplo da imagem 4, o campo "Client ID /User" é a junção do convênio 12345 com a agência 6789 da imagem 3, que resulta em 123456789 no campo de "Cliente ID / User". O campo de Authorization / Api Key é fornecida pela Mérito através do portal do desenvolvedor. O Client Secret é o código de acesso que pode ser gerado conforme descrito abaixo.

Geração do código de acesso (password / Client Secret): A empresa ou pessoa associada deve acessar o Internet Banking, pela conta vinculada ao seu convênio de Cobrança, e selecionar a opção de menu no: Cobrança >> Código de Acesso >> Gerar - Esse menu é apresentado exclusivamente para os beneficiários que possuem a modalidade API (Cobrança Online) habilitada no convênio. A chave será gerada após informado o dispositivo de segurança.

Na Imagem 5 abaixo é exibido o caminho para geração do código de acesso para utilizar no campo Client Secret.

Imagem 5 - Internet Banking

Envio de Boleto para a API

No PDV (Ponto de Venda)

• Ao fechar uma venda escolhendo "Boleto" como forma de pagamento.

• O sistema automaticamente:

1. Cria o boleto
2. Envia para a API do Sicredi
3. Imprime o boleto
4. Cliente já pode pagar

Como usar:

1. Faça a venda normalmente no PDV
2. Na hora de finalizar, escolha a forma de pagamento "Boleto"
3. Confirme a venda
4. O sistema envia automaticamente para o banco e imprime

No Faturamento de Clientes

• Caminho no menu: Financeiro > Faturamento > Faturar - Geral
• Ao gerar o faturamento mensal de clientes

• O sistema:

1. Cria os boletos de todas as vendas/serviços do período
2. Imprime automaticamente e envia para a API do Sicredi.

O mesmo ocorre para o faturamento de cliente em Financeiro > Faturamento > Faturar - Geral.

Retorno Boletos

No painel de retorno é possível realizar consulta à API da Sicredi para obter atualizações do boletos.

Imagem 6 - Painel Retorno

Para isso:

• Abrir programa do Painel Retorno
  • No menu: Financeiro > Documentos de Cobrança > Transferência de Arquivos > Retorno > Painel Retorno Boletos
• Selecionar a aba API
• Informar o tipo de cobrança criado ou alterado para utilizar a API da Sicredi.
• Informar o período de consulta à API.

• Clicar em "Processar Retorno"

OBS: Em princípio, a consulta ainda não foi automatizada pois há limites de requisições para a API. O status do documento pode ser verificado em Financeiro > Documentos de Cobrança > Consulta Doc Cob após o "Processar Retorno", e caso necessário terá opção exclusiva para administradores para atualizar o status do documento de cobrança buscando na API da Sicredi. No passado, a própria Sicredi já comunicou sobre a existência dos limites para as requisições e recomendação para manter no mínimo de requisições, no entanto, futuramente pode ser revisada a possibilidade de realizar a automatização.