Boletos via API Direta com Bancos
O TryERP permite a geração de boletos diretamente pela API dos bancos Sicredi e Sicoob. Os boletos são registrados em tempo real e o PDF é obtido automaticamente.
Este manual orienta a configuração da conta bancária e o uso das funcionalidades de geração, consulta e gestão de boletos registrados via API direta.
1. Configuração da Conta Bancária
Acesse Banco > Consultar Contas e selecione (ou crie) a conta que será utilizada para emissão de boletos via API.
1.1. Selecionar a Administradora
No campo Administradora Boleto Online, selecione o banco desejado:
- Sicredi — para cooperativas de crédito Sicredi
- Sicoob — para cooperativas de crédito Sicoob
Ao selecionar a administradora, uma aba específica do banco será exibida com os campos de configuração.
1.2. Configuração Sicredi
Ao selecionar Sicredi, a aba "Sicredi" será exibida com os seguintes campos:
| Campo | Obrigatório | Descrição |
|---|---|---|
| Username | Sim | Código de acesso fornecido pelo Sicredi (ex: 123450100). Corresponde ao username da autenticação OAuth2. |
| Password | Sim | Senha/código de acesso fornecido pelo Sicredi. O campo exibe asteriscos por segurança. |
| API Key | Sim | Chave de API (x-api-key) fornecida pelo Sicredi ao cadastrar o aplicativo no portal de desenvolvedores. |
| Cooperativa | Sim | Código da cooperativa (4 dígitos). Este campo utiliza internamente o campo Agência da conta. |
| Posto | Não | Código do posto/agência dentro da cooperativa (2 dígitos). Utiliza internamente o campo DV Agência. |
| Cód. Beneficiário | Sim | Código do beneficiário/cedente no Sicredi (5 dígitos). Utiliza internamente o campo Cód. Cedente. |
| Tipo Cobrança | Não | Define se o boleto terá QR Code PIX: • NORMAL — Boleto convencional (sem PIX) • HIBRIDO — Boleto com QR Code PIX integrado |
| Ambiente | Sim | • Produção — Gera boletos reais registrados no banco • Homologação — Ambiente de testes (sandbox) do Sicredi |
Nota: Os campos Cooperativa, Posto e Cód. Beneficiário são informados pelo Sicredi no momento do credenciamento. Os campos Username, Password e API Key são obtidos no portal de desenvolvedores do Sicredi.
1.3. Configuração Sicoob
Ao selecionar Sicoob, a aba "Sicoob" será exibida com os seguintes campos:
| Campo | Obrigatório | Descrição |
|---|---|---|
| Client ID | Sim | Identificador do aplicativo criado no Portal Developers do Sicoob. Usado como client_id na autenticação OAuth2 e como header em todas as chamadas. |
| Nº Cliente | Sim | Número do cliente/beneficiário na cooperativa. Este código é informado pela cooperativa ao aderir ao serviço de cobrança registrada. |
| Conta Corrente | Sim | Número da conta corrente na cooperativa (somente números). |
| Emitente (Cert.) | Sim (Produção) | Selecione o emitente que possui o certificado digital ICP-Brasil A1 vinculado. O Sicoob utiliza o mesmo certificado da NF-e para autenticação mTLS. Na homologação, este campo não é necessário. |
| Tipo Cobrança | Não | Define se o boleto terá QR Code PIX: • PADRAO — Padrão da cooperativa • COM_PIX — Boleto com QR Code PIX • SEM_PIX — Boleto sem PIX |
| Ambiente | Sim | • Produção — Gera boletos reais (requer certificado digital) • Homologação — Ambiente sandbox (não requer certificado) |
| Token (Sandbox) | Somente Homologação | Token fixo fornecido na seção "Sandbox" do Portal Developers do Sicoob. Utilizado apenas para testes em ambiente de homologação. |
Importante — Certificado Digital: O Sicoob utiliza autenticação por certificado digital ICP-Brasil (mTLS). É o mesmo certificado A1 utilizado para emissão de NF-e. O certificado deve estar cadastrado no TryERP e vinculado ao emitente selecionado no campo Emitente (Cert.). O Sicoob nunca solicita a chave privada separadamente.
Importante — Portal Developers: O Client ID é obtido ao criar um aplicativo no Portal Developers do Sicoob. No momento da criação, é necessário vincular a chave pública do certificado digital (.PEM, .CRT ou .CER) ao aplicativo.
1.4. Campos Comuns da Conta (Ambos os Bancos)
Além dos campos específicos de cada banco, os seguintes campos da conta bancária são utilizados na geração de boletos via API:
| Campo | Descrição |
|---|---|
| % Juros Mensais | Percentual de juros ao mês. Para o Sicredi, o sistema converte automaticamente para diário (÷ 30). Para o Sicoob, a taxa mensal é enviada diretamente. |
| % Taxa Multa | Percentual de multa por atraso. |
| Dias Protesto | Quantidade de dias para protesto automático. |
| Ind. Protestar/Negativar | Define a ação após vencimento: Protestar (corrido ou úteis) ou Negativar. |
| Máx. Dias Pagamento Após Vencimento | Dias de validade do boleto após o vencimento. O banco rejeita pagamentos após esta data. |
| Espécie Documento | Tipo do documento (DM, DS, NP, RC, etc.). O sistema converte automaticamente para o formato de cada banco. |
| Instruções Boleto | Texto livre com instruções impressas no boleto. Cada linha é enviada como um informativo separado. |
| Exibir Boleto ao Gravar | Quando marcado, o PDF do boleto é aberto automaticamente após o registro. |
1.5. Diferenças Rápidas entre Sicredi e Sicoob
| Aspecto | Sicredi | Sicoob |
|---|---|---|
| Autenticação | Username + Password + API Key | Certificado digital ICP-Brasil (mesmo da NF-e) |
| Credenciais necessárias | Username, Password, API Key, Cooperativa, Posto, Cód. Beneficiário | Client ID, Nº Cliente, Conta Corrente, Certificado Digital |
| PIX no Boleto | NORMAL ou HIBRIDO | PADRAO, COM_PIX ou SEM_PIX |
| PDF do Boleto | Obtido por endpoint separado | Retornado junto com o registro do boleto |
| Sandbox (testes) | Usa credenciais de teste + autenticação | Usa token fixo do portal (sem certificado) |
2. Geração de Boletos
Os boletos podem ser gerados por dois caminhos:
2.1. Via Tela de Geração de Boletos
Acesse Banco > Geração de Boletos. O wizard de 3 etapas permite selecionar as parcelas e gerar os boletos. Ao gravar, o sistema detecta automaticamente que a conta utiliza API direta e envia os boletos para registro no banco.
2.2. Via Emissão de Documentos
Ao emitir uma nota fiscal com fatura vinculada a uma conta configurada com Sicredi ou Sicoob, os boletos são gerados automaticamente via API do banco durante o processo de emissão.
2.3. O que acontece ao gerar
- O sistema autentica na API do banco com as credenciais configuradas.
- Para cada boleto, envia os dados (valor, vencimento, pagador, juros, multa, etc.) para o banco.
- O banco retorna a linha digitável, código de barras, nosso número e, quando habilitado, o QR Code PIX.
- Os dados são salvos no boleto do sistema.
- Se a opção "Exibir Boleto ao Gravar" estiver marcada, o PDF é aberto automaticamente.
- Toda a comunicação (JSON enviado e JSON recebido) é registrada no log de atividades para rastreabilidade.
Nota: Caso ocorra erro em algum boleto, uma mensagem é exibida com os detalhes do erro retornado pelo banco. O boleto ficará com status Rejeitado e pode ser retransmitido posteriormente pela tela de consulta.
3. Consulta de Boletos Online
Acesse Banco > Consulta de Boletos (Online) para gerenciar os boletos gerados via API.
3.1. Pesquisar Boletos
Utilize os filtros disponíveis para localizar os boletos:
- Conta — Conta bancária de origem
- Parceiro — Cliente/sacado
- Período — Data de geração (de/até)
- Status — Pendente, Liquidado, Baixado, Rejeitado
Clique em Pesquisar para listar os boletos.
3.2. Imprimir Boletos
Selecione os boletos desejados na grid e clique em Imprimir Boletos. O sistema obtém o PDF diretamente da API do banco e abre no leitor de PDF padrão.
3.3. Verificar Status dos Boletos
Selecione os boletos pendentes e clique em Verificar Status dos Boletos. O sistema consulta a API do banco para cada boleto e atualiza o status no sistema.
Os possíveis status retornados são:
| Status no Sistema | Significado |
|---|---|
| Pendente | Boleto registrado, aguardando pagamento. |
| Liquidado | Boleto pago. O sistema oferece a liquidação automática da fatura vinculada, calculando juros e multa pela diferença entre o valor pago e o valor original. |
| Baixado | Boleto cancelado/baixado no banco. |
| Rejeitado | Boleto rejeitado pelo banco (dados inválidos). Pode ser corrigido e retransmitido. |
| Processando | Boleto em processamento no banco. |
Liquidação automática: Quando o status muda para Liquidado, o sistema calcula automaticamente a diferença entre o valor pago e o valor original como juros/multa e abre a tela de recebimento para confirmar a liquidação da fatura.
3.4. Enviar por E-mail
Selecione os boletos e clique em Enviar por E-mail. O PDF do boleto é obtido via API do banco e enviado por e-mail ao parceiro cadastrado.
3.5. Baixar / Cancelar Boletos
Para cancelar um boleto registrado no banco, selecione-o e clique em Baixar/Cancelar Boletos. O sistema envia a instrução de baixa diretamente para a API do banco.
Atenção: Boletos já pagos ou em processamento não podem ser baixados. A baixa é uma instrução de cancelamento do registro junto ao banco.
3.6. Retransmitir Boleto
Boletos com status Rejeitado ou Erro podem ser reenviados ao banco. Selecione os boletos e clique em Retransmitir Boleto. Os dados são enviados novamente para registro.
Antes de retransmitir, verifique os motivos da rejeição no campo Mensagem de Status do boleto e corrija os dados se necessário (dados do parceiro, valores, etc.).
3.7. Excluir Boletos
Clique em Excluir Boletos para remover os boletos selecionados do sistema. Esta ação remove apenas o registro no TryERP — caso o boleto já esteja registrado no banco, é recomendado utilizar Baixar/Cancelar primeiro.
3.8. Liquidados do Dia
Clique em Liquidados do Dia para abrir a tela de consulta de boletos pagos via API do banco.
Esta funcionalidade permite:
- Selecionar uma data e clicar em Consultar para buscar os boletos liquidados no banco naquele dia.
- O sistema cruza automaticamente os boletos retornados pelo banco com os boletos registrados no TryERP.
- Cada boleto é classificado com uma situação:
| Situação | Cor | Significado |
|---|---|---|
| Pendente | Branco | Boleto encontrado no sistema e ainda não quitado. Pode ser liquidado. |
| Já Quitado | Cinza | Boleto já foi liquidado anteriormente no sistema. |
| Não Encontrado | Vermelho claro | Retornado pelo banco, mas não encontrado na conta selecionada no sistema. |
- Marque os boletos Pendentes desejados e clique em Liquidar Selecionados para realizar a liquidação em lote.
A grid exibe as seguintes colunas:
| Coluna | Descrição |
|---|---|
| Selecionado | Checkbox para marcar o boleto para liquidação |
| Nosso Número | Número do boleto no banco |
| Seu Número | Número do documento/referência no sistema |
| Parceiro | Nome do cliente/sacado |
| Valor Original | Valor registrado no boleto |
| Valor Pago | Valor efetivamente pago pelo sacado |
| Diferença | Diferença entre pago e original (juros/multa ou desconto) |
| Dt Pagamento | Data em que o pagamento foi realizado |
| Dt Crédito | Data em que o valor foi creditado na conta |
| Situação | Pendente, Já Quitado ou Não Encontrado |
Nota (Sicredi): A funcionalidade de Liquidados do Dia utiliza o endpoint dedicado do Sicredi. Para o Sicoob, esta funcionalidade ainda não está disponível pois o banco utiliza um mecanismo diferente (Movimentações assíncronas).
Nota (Sicoob): Para acompanhar pagamentos no Sicoob, utilize a funcionalidade Verificar Status dos Boletos, que consulta individualmente a situação de cada boleto.
4. Envio Automático por E-mail
Quando a configuração "Enviar boletos automaticamente por e-mail" estiver habilitada nas configurações do sistema, os boletos gerados via API são enviados automaticamente por e-mail ao parceiro após o registro.
O PDF do boleto é obtido diretamente da API do banco e anexado ao e-mail. Caso a nota fiscal possua múltiplos boletos, os PDFs são concatenados em um único arquivo.
5. Log de Atividades
Todas as chamadas de API são registradas no log de atividades do sistema, incluindo:
- JSON de Request — os dados exatos enviados ao banco
- JSON de Response — a resposta completa retornada pelo banco
- Mensagem de erro — em caso de falha, o detalhe do erro
Estes logs ficam vinculados ao boleto e podem ser consultados para diagnóstico de problemas. O JSON de request pode ser copiado e testado diretamente no Swagger/portal de desenvolvedores do banco.
6. Dados do Parceiro (Sacado)
Para o registro correto dos boletos, o cadastro do parceiro (sacado) deve conter:
| Campo | Sicredi | Sicoob |
|---|---|---|
| CPF/CNPJ | Obrigatório | Obrigatório |
| Nome / Razão Social | Obrigatório | Obrigatório |
| Logradouro | Obrigatório | Obrigatório |
| Bairro | Opcional | Obrigatório |
| Cidade | Obrigatório | Obrigatório |
| UF | Obrigatório | Obrigatório |
| CEP | Obrigatório | Obrigatório |
| Opcional | Opcional | |
| Telefone | Opcional | — |
Atenção (Sicoob): O campo Bairro é obrigatório para o Sicoob. Boletos com parceiros sem bairro cadastrado serão rejeitados pelo banco.
7. Perguntas Frequentes
O boleto foi rejeitado. O que faço?
Verifique a mensagem de erro na tela de consulta (coluna Mensagem Status). Corrija os dados indicados (parceiro, valores, datas) e utilize o botão Retransmitir Boleto. Você também pode consultar o JSON de request no log de atividades para diagnosticar o problema.
O Sicoob exige certificado digital?
Sim, em produção. O Sicoob utiliza o mesmo certificado digital ICP-Brasil A1 da NF-e. O certificado deve estar cadastrado no TryERP e vinculado ao emitente. Em homologação (sandbox), basta informar o token fixo fornecido no Portal Developers.
O boleto pode ter QR Code PIX?
Sim. Configure o campo Tipo Cobrança como HIBRIDO (Sicredi) ou COM_PIX (Sicoob). O banco retorna o QR Code EMV na resposta, que fica armazenado no boleto.
Como saber se um boleto foi pago?
Utilize o botão Verificar Status dos Boletos na tela de consulta. O sistema consulta o banco em tempo real e, se o boleto estiver pago, oferece a liquidação automática no sistema. Para o Sicredi, também é possível usar o botão Liquidados do Dia para consultar todos os pagamentos de uma data específica.
Posso usar Sicredi e Sicoob ao mesmo tempo?
Sim. Cada conta bancária é configurada independentemente. Você pode ter uma conta configurada com Sicredi e outra com Sicoob no mesmo sistema.
O que é o campo "Nosso Número"?
É o número de controle do boleto no banco. Para o Sicredi, o sistema envia com exatamente 9 dígitos (preenchido com zeros à esquerda). Para o Sicoob, o banco pode gerar automaticamente se o campo estiver zerado.
Última atualização: Fevereiro/2026