Sistema em Laravel para geração, envio e gestão de boletos, Pix e NF-e integrado ao Banco Inter e a provedores de NF-e, com recursos de automação, cache e notificações (e-mail, sms, ligação e WhatsApp via Notifish).
- Licença
- FAQ – Boleto Inter Pro
- Principais funcionalidades
- Requisitos
- Arquitetura do sistema
- Instalação
- Docker (produção)
- Geração automática de boletos
- Comandos Artisan (detalhado)
- Screenshots
- Créditos
- Este projeto é útil para você? Aceito um café ☕
Este projeto é disponibilizado sob uma licença proprietária de uso não comercial.
Você pode:
- Usar o código
- Estudar e modificar o código
- Utilizar em projetos pessoais, educacionais ou internos
Você NÃO pode:
- Vender o software, no todo ou em parte
- Sublicenciar o código
- Oferecer o software ou versões derivadas como serviço pago (SaaS, suporte, revenda, etc.)
- Comercializar versões modificadas sem autorização expressa do autor
Uso comercial
Qualquer uso comercial, direto ou indireto, exige licenciamento comercial prévio.
Para licenciamento comercial, entre em contato
Observação importante
Este projeto é fornecido "como está", sem garantias. O autor não se responsabiliza por danos diretos ou indiretos decorrentes do uso do software.
Este projeto foi desenvolvido para atender às minhas próprias necessidades, com base em cenários reais de uso em produção. Embora seja funcional e estável, não há garantia de que ele atenderá a todos os casos de uso ou perfis de negócio.
Recomendação: avalie se a solução se encaixa no seu contexto antes de utilizá-la.
Sim. Este projeto é utilizado em produção há mais de 5 anos. A decisão de torná-lo público foi tomada para ajudar outros desenvolvedores e prestadores de serviços, especialmente quem está iniciando e precisa de uma base confiável para integrações com o Boleto Inter.
Existe a intenção de lançar uma nova versão, com melhorias arquiteturais, novas funcionalidades e compatibilidade com a última versão do Laravel, porém ainda não há uma data definida para esse lançamento.
É uma possibilidade. A ideia de incorporar recursos de IA existe, mas não há cronograma definido para o início do desenvolvimento da nova versão.
Não de forma pública. Este repositório representa uma versão estável e funcional. As evoluções futuras estão planejadas para uma nova versão do sistema, com outro ciclo de desenvolvimento e melhorias mais amplas.
Sim. É possível contratar suporte técnico pago, que pode incluir:
| Serviço | Descrição |
|---|---|
| Instalação completa | Configuração do sistema do zero |
| Configuração e validação | Ajustes e validação de funcionamento |
| Configuração de servidor | Opcional, com custo adicional |
Os valores variam conforme a complexidade do ambiente e do serviço solicitado.
Não. Atualmente, a geração de Nota Fiscal está disponível apenas para prefeituras que utilizam o sistema IPM Fiscal.
Sim. O projeto utiliza a API do Notifish. É necessário contratar o serviço em:
O envio de SMS é realizado através do serviço:
O envio de mensagens por voz utiliza o serviço:
→ kingsms.com.br – Torpedo de voz
Se este projeto te ajudou de alguma forma, considere apoiar o trabalho.
Contribuições como um café ☕, uma cerveja 🍺 ou um almoço 🍔 ajudam a manter projetos como este ativos e evoluindo.
- Clientes e serviços
- Cadastro de clientes (
Customer) - Cadastro de serviços (
Service) - Vínculo de serviços a clientes
- Tipos de nota fiscal por cliente (
CustomerNfeType)
- Cadastro de clientes (
- Boletos (Banco Inter)
- Geração de boleto automático (recorrente) e avulso
- Envio automático de boleto via e-mail
- Envio automático de boleto via WhatsApp (Notifish)
- Reenvio de boletos vencidos / lembretes
- Cancelamento de boleto direto no Inter
- Download de PDF do boleto (cacheado em
storage/app/boleto/pdf/ano/mes/) - URL assinada para download do PDF do boleto (uso pelo Notifish): rota pública
/ln/boleto/pdfcom parâmetroour_number(identificador do Inter), expira em 10 minutos; não expõe o ID interno - Atualização automática de status via webhook do Inter
- Pix
- Geração de cobranças Pix com integração Inter (
InterService::generatePaymentPix) - Geração automática de Pix (comando
ln:auto_generate_pix): mesmo critério de data de vencimento que boletos (próximo mês, último dia do mês, feriados); logs e Bugsnag em caso de falha - Página pública de pagamento (
/ln/pagamento/pix/...) com botão "Copiar código Pix" e atualização em tempo real do status (Pusher, opcional) - Geração de QRCode Pix e recibo
- Webhook Pix (Banco Inter) para atualização de pagamentos
- Geração de cobranças Pix com integração Inter (
- NF-e (Nota Fiscal de Serviço)
- Geração de XML de NF-e com base nos serviços do cliente (
NfeRepository::createNote) - Envio do XML para o webservice configurado (
NfeService) - Persistência dos dados da NF-e e link de consulta
- Envio automático da NF-e por e-mail para o cliente
- Geração automática de NF-e complementar de juros/mora quando o valor pago > valor nominal do boleto
- Geração de XML de NF-e com base nos serviços do cliente (
- WhatsApp
- Login e gestão de sessão via Notifish (instância WhatsApp)
- Envio de:
- Boleto por WhatsApp (anexo): payload Notifish com
identifier: "boleto",mediacomtype,archive(URL assinada),filename(baseado no nome fantasia do cliente, sem caracteres especiais, sempre.pdf) ecaptioncom data de vencimento (colunadue_dateda tabela boletos), ex.: "Boleto de {nome fantasia} com vencimento para dd/mm/YYYY. Após o vencimento haverá incidência de juros e multa." - Avisos de falha/sucesso de envio de boletos
- Notificações de callback do Inter (pagamentos, cancelamentos, etc.)
- Aviso interno no WhatsApp quando o cliente paga (boletos e Pix), via callbacks do Banco Inter
- Boleto por WhatsApp (anexo): payload Notifish com
- Relatórios e dashboard
- Consulta de saldo em conta (
InterService::getSaldo) - Relatório mensal de receitas/gastos (
HomeController::getMonthReport) - Cálculo de valor total de boletos pagos/em aberto no mês atual
- Extrato para contabilidade: comando que gera o extrato em PDF do mês anterior (Banco Inter), envia automaticamente ao contador por e-mail e WhatsApp, e registra cada envio no banco (
contabilidades). Se o seu contador aceita receber o extrato em PDF, basta configurar as variáveis de contabilidade no.enve ativar o comando (inclusive via agendamento).
- Consulta de saldo em conta (
- Agenda e feriados
- Cadastro de feriados (
Holiday) - Ajuste automático de vencimento, juros e mora considerando feriados (
HolidayRepository, regras emBoletoRepository)
- Cadastro de feriados (
PHP: >= 7.3 e <= 8.1 (Testado nessas versões)
- Extensões:
- BCMath
- Ctype
- Fileinfo
- JSON
- Mbstring
- OpenSSL
- PDO
- Tokenizer
- XML
- Processamento de imagem (Pix QRCode):
- O endpoint de imagem do Pix (
/ln/pagamento/pix/imagem/{uuid}) usa a bibliotecaintervention/image. - Para funcionar, o PHP precisa ter suporte a imagens via GD (mais comum) ou Imagick/ImageMagick (“imagekick”).
- O endpoint de imagem do Pix (
- Banco de dados: MySQL/MariaDB
- Cache / Sessão:
- Redis (recomendado) ou Memcached
O projeto faz uso intenso de cache (viaCache::tags) em repositórios comoBoletoRepository,NfeRepositoryetc., portanto é obrigatório ter um cache em memória configurado.
- Redis (recomendado) ou Memcached
- Framework: Laravel 8 (
laravel/framework^8.75) - Padrão de projeto:
- Controllers finos (
app/Http/Controllers) - Repositórios (
app/Repositories) implementando interfaces (app/Interfaces) - Serviços externos em
app/Services(InterService,LnService,NfeService) - Observers para eventos de modelo (
app/Observers) - Jobs/rotinas via comandos Artisan em
app/Console/Commands
- Controllers finos (
- Principais componentes:
InterService: integração com Banco Inter (boletos, Pix, saldo, extrato, webhooks, PDF)LnService: camada fina sobreHttp/cURL para requisições HTTP/RESTNfeService+NfeRepository: integração com webservice de NF-eBoletoRepository: lógica de negócio de boletos (geração, cancelamento, PDF, e-mail, webhook, NF-e de juros)PixRepository: lógica de negócio de PixNotifishRepository: comunicação com WhatsApp via NotifishHolidayRepository: feriados que impactam vencimentos- Controllers backend (prefixo
/dashboard) e frontend (prefixo/ln)
Rotas principais (resumo):
- Backend (
middleware auth, prefixo/dashboard):/– Dashboard (HomeController@index)/cliente/...– CRUD de clientes/servico/...– CRUD de serviços/fatura/boleto/...– Boletos (listar, gerar, cancelar, enviar e-mail, webhook)/fatura/pix/...– Pix (listar, gerar, webhook)/whatsapp/...– Login, status e envios WhatsApp/nota-fiscal/...– Listagem, emissão e envio de NF-e/feriado/...– CRUD de feriados
- Frontend (prefixo
/ln):/ln/pagamento/pix/{token}– Página de pagamento Pix/ln/pagamento/pix/imagem/{uuid}– Imagem QRCode Pix/ln/pagamento/pix/recibo/{uuid}– Recibo Pix/ln/boleto/pdf– Download do PDF do boleto via URL assinada (query:our_number,signature,expires); usada pelo Notifish para enviar o anexo; expira em 10 min
- Clonar o projeto
git clone https://github.com/leonardop21/boleto-inter.git
cd boleto-inter- Instalar dependências PHP
composer install- Configurar o
.env
Copie o arquivo de exemplo:
cp .env.example .envPreencha as variáveis abaixo de acordo com o seu ambiente.
APP_NAME="Gerador Boleto Inter"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=database
DB_USERNAME=user
DB_PASSWORD=pass
CACHE_DRIVER=redis
SESSION_DRIVER=redis
TIME_CACHE_IN_SECONDS=604800 # Cache em segundos (ex: 7 dias)
DARK_MODE=1 # 1 para tema escuro habilitado
PAGINATION_LIMIT=10 # Limite de paginação padrãoLOGO_SITE_EMAIL="https://exemplo.com/logo.png"
BACKGROUND_EMAIL="#090324"MAIL_MAILER=smtp
MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=
MAIL_FROM_NAME="${APP_NAME}"
EMAIL_DUVIDA= # E-mail de resposta do cliente
NOTIFY_SEND_BOLETO= # E-mail que recebe notificações de sucesso/erro de envio
NAME_SIGNATURE_MAIL= # Nome que aparecerá na assinatura
SITE_URL_REDIRECT_EMAIL= # URL exibida no corpo do e-mail# Caminhos para certificados (arquivo físico .crt e .key)
INTER_PATH_CRT=/caminho/para/arquivo.crt
INTER_PATH_KEY=/caminho/para/arquivo.key
# URL base do parceiro PJ
INTER_BASE_URL="https://cdpj.partners.bancointer.com.br/"
# Credenciais OAuth2
INTER_CLIENT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
INTER_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxx"
INTER_CLIENT_SCOPE="extrato.read boleto-cobranca.read boleto-cobranca.write"
# Webhooks
INTER_WEBHOOK_URL="https://seu-sistema.com/api/inter/webhook/boleto"
INTER_WEBHOOK_URL_PIX="https://seu-sistema.com/api/inter/webhook/pix" # se utilizadoCHAVE_PIX=seu_cnpj_ou_chave_pix
BENEFICIARIO_PIX="NOME DO BENEFICIÁRIO"
CNPJ_EMPRESA="00.000.000/0000-00"
CIDADE_EMPRESA="SUA CIDADE"
EMAIL_RECIBO="contato@empresa.com.br"# Base URL da API Notifish (v2)
NOTIFISH_BASE_URL="https://seu-subdominio.notifish.com/api/v2/"
# API Key Notifish
NOTIFISH_API_KEY="sua_api_key"
# UUID da instância (sessão WhatsApp)
NOTIFISH_UUID="uuid-da-instancia"
# Número que recebe alertas internos (DDI+DDD+Número)
NOTIFY_SEND_BOLETO_WHATSAPP="5599999999999"A página pública de pagamento Pix (/ln/pagamento/pix/...) pode exibir a confirmação de pagamento em tempo real via Pusher. Opcional.
BROADCAST_DRIVER=pusher
PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=
PUSHER_APP_CLUSTER=mt1Falhas na geração automática de boletos e Pix (e outros erros da aplicação) podem ser enviadas ao Bugsnag quando configurado.
BUGSNAG_API_KEY=NFE_BASE_URL="https://url-do-webservice-de-nfe"
AUTHORIZATION_NFE="token_ou_credencial_em_base64"
# Prestador
CNPJ_NF_PRESTADOR="00000000000000"
CIDADE_ID_NFE="0000000" # Código do município para o provedor de NF-eOpcional. Usado pelo comando ln:process-pdf-report-and-sent-email-e-whats-app, que gera o extrato em PDF do mês anterior e envia ao contador por e-mail e WhatsApp (além de salvar no banco). Se o seu contador permite receber o extrato em PDF, preencha as variáveis abaixo e agende o comando conforme necessário.
# E-mail do contador (contabilidade)
CONTABILIDADE_EMAIL=
# WhatsApp do contador (DDI+DDD+Número)
CONTABILIDADE_WHATSAPP=
# Nome da contabilidade (para registro no banco e logs)
CONTABILIDADE_NAME=- Gerar key da aplicação
php artisan key:generate- Rodar as migrations
php artisan migrate- Criar usuário
Crie seu usuário via Tinker ou usando o seeder/registro manual:
php artisan tinker
>>> \App\Models\User::factory()->create();- Acessar o sistema
- Faça login no sistema
- Cadastre um serviço
- Cadastre um cliente
- Vincule o serviço ao cliente
O projeto possui um setup de produção com:
- Nginx
- PHP-FPM (Laravel)
- MySQL
- Redis (cache e sessão)
- GD/Imagick (requisito para gerar/servir imagem do Pix QRCode)
Arquivos:
docker-compose.prod.ymldocker/php/Dockerfiledocker/nginx/default.conf
docker compose -f docker-compose.prod.yml up -d --builddocker compose -f docker-compose.prod.yml exec app php artisan migrate --forcePara o Inter funcionar, a pasta inter-certf/ deve existir no projeto e conter:
inter_api_certificado.crtinter_api_chave.key
No Docker, esses arquivos são montados em /var/www/inter-certf e as variáveis INTER_PATH_CRT e INTER_PATH_KEY apontam para esses caminhos.
O container app já vem com GD habilitado (necessário para intervention/image servir o QRCode do Pix).
Se você preferir usar Imagick/ImageMagick (“imagekick”), será necessário instalar a extensão imagick no docker/php/Dockerfile.
O sistema permite gerar boletos automaticamente para todos os clientes ativos com serviços vinculados, enviando os boletos por e-mail (e, se configurado, por WhatsApp).
php artisan ln:auto_generate_boleto- O comando:
- Localiza clientes com status ativo
- Gera boletos baseados nas configurações do cliente (valor, vencimento, juros, mora, dias após vencimento etc.)
- Data de vencimento (dia configurado no cadastro do cliente):
- Se o dia já tiver passado no mês atual (data retroativa), o vencimento é jogado para o próximo mês com o mesmo dia (respeitando o último dia do mês).
- Se o dia configurado for 31 e o mês tiver menos dias (ex.: 28 ou 30), é usado o último dia do mês.
- Se o vencimento for hoje, o boleto é gerado para hoje (não é jogado para o próximo mês).
- Ajusta datas considerando feriados (via
HolidayRepository) - Gera o boleto no Banco Inter
- Baixa/gera o PDF e o armazena em
storage/app/boleto/pdf/... - Dispara o envio por e-mail e, se habilitado, por WhatsApp
Você pode agendar esse comando no App\Console\Kernel usando o scheduler do Laravel para rodar diariamente/mensalmente, conforme sua necessidade.
- O motivo da falha (resposta da API Inter: violações,
detail, etc.) é registrado no log:storage/logs/gerar-boleto/boleto.log— mensagem no formato: "Falha ao gerar boleto para {nome}. Motivo: {detalhe}"
- A falha também é enviada ao Bugsnag (se configurado), com metadata:
customer_id,customer_name,motivo,status_code,raw_body.
O sistema permite gerar Pix automaticamente para clientes ativos com serviços vinculados, enviando o link de pagamento por e-mail e, se configurado, por WhatsApp.
php artisan ln:auto_generate_pix- O comando utiliza a mesma lógica de data de vencimento do boleto:
- Se o dia já tiver passado no mês atual, o vencimento vai para o próximo mês (mesmo dia, último dia do mês quando for 31).
- Feriados são considerados via
HolidayRepository.
- Em caso de falha, o motivo é registrado em
storage/logs/gerar-pix/pix.loge enviado ao Bugsnag (se configurado), com contexto do cliente e da resposta da API Inter. - Você pode agendar o comando no
App\Console\Kernel(scheduler) para rodar diariamente ou conforme a necessidade.
- Geração de boleto / Pix / NF-e:
storage/logs/gerar-boleto/boleto.logstorage/logs/gerar-pix/pix.logstorage/logs/gerar-nfe/nfe.log
- Callback Inter:
storage/logs/callback/callback.log
Arquivos de log adicionais podem ser gerados por comandos/integrações específicas.
Existe um comando que gera o extrato em PDF do mês anterior (Banco Inter), envia automaticamente para o contador por e-mail e WhatsApp, e salva cada envio no banco (tabela contabilidades). Se o seu contador permite receber o extrato em PDF, você pode ativar essa funcionalidade configurando no .env o e-mail e o WhatsApp da contabilidade (e o nome, para registro) e rodando o comando manualmente ou via agendamento (ex.: todo dia 1º do mês). O comando é ln:process-pdf-report-and-sent-email-e-whats-app; ele também está listado na tabela Relatório e manutenção.
Todos os comandos abaixo podem ser agendados via cron usando o Laravel Scheduler no App\Console\Kernel. Exemplo de cron para executar o scheduler a cada minuto:
* * * * * cd /caminho/do/projeto && php artisan schedule:run >> /dev/null 2>&1No método schedule() do Kernel você define, por exemplo: $schedule->command('ln:auto_generate_boleto')->monthlyOn(1, '06:00'); para gerar boletos todo dia 1 às 6h.
O sistema inclui comandos de cobrança para boletos e Pix: lembretes de vencimento (antes de vencer), lembretes de vencido (após o vencimento), e envio por e-mail, WhatsApp, SMS e voz (Voicer). Assim você pode automatizar toda a rotina de geração, envio e cobrança.
| Comando | Descrição |
|---|---|
php artisan ln:auto_generate_boleto |
Gera boletos automaticamente para clientes ativos com serviços definidos. Envia por e-mail e, se configurado, por WhatsApp. Respeita data de vencimento, feriados e último dia do mês. |
php artisan ln:auto_generate_pix |
Gera Pix e QR Code para clientes ativos com serviços definidos. Mesma lógica de vencimento do boleto. Envia link por e-mail e WhatsApp. |
php artisan ln:generate-nfe |
Gera NF-e automaticamente para todos os clientes ativos com serviços atrelados (prefeituras com IPM Fiscal). |
| Comando | Descrição |
|---|---|
php artisan ln:send-boleto {boletos_id} |
Envia o boleto por e-mail e dispara o envio pelo WhatsApp (Notifish). |
php artisan ln:send-whatsapp {boletos_id} |
Envia apenas via WhatsApp (Notifish) o boleto informado. |
php artisan ln:send_pix {pixes_id} |
Envia o Pix por e-mail e Notifish (WhatsApp). |
php artisan ln:send-nfe {nfes_id} |
Envia a NF-e por e-mail e notifica via WhatsApp. |
| Comando | Descrição |
|---|---|
php artisan ln:resend-boleto |
Lembrete de vencimento de boleto (fatura próxima do vencimento). Reenvia boletos que estão no período de lembrete. |
php artisan ln:resend-duedate-boleto |
Lembrete de boleto vencido. Reenvia boletos já vencidos para cobrança. |
php artisan ln:resend-pix |
Lembrete de vencimento de Pix (fatura próxima do vencimento). |
php artisan ln:resend-duedate-pix |
Lembrete de Pix vencido. Reenvia Pix vencidos para cobrança. |
Esses comandos podem ser agendados no cron (ex.: ln:resend-boleto todo dia às 8h; ln:resend-duedate-boleto em dias alternados após o vencimento).
Requer configuração de TOKEN_SMS no .env e uso do serviço SMS Dev.
| Comando | Descrição |
|---|---|
php artisan ln:send-boleto-sms |
Envia SMS de cobrança para boletos vencidos (lista obtida pela mesma regra do lembrete de vencido). |
php artisan ln:send-pix-sms |
Envia SMS de cobrança para Pix vencidos. |
Requer configuração de VOICER_TOKEN, VOICER_LOGIN e VOICER_AUDIO no .env e uso do serviço King SMS – Torpedo de voz.
| Comando | Descrição |
|---|---|
php artisan ln:send-boleto-voicer |
Consulta boletos vencidos e envia cobrança por voz (torpedo de voz). |
php artisan ln:send-pix-voicer |
Consulta Pix vencidos e envia cobrança por voz (torpedo de voz). |
| Comando | Descrição |
|---|---|
php artisan ln:process-pdf-report-and-sent-email-e-whats-app |
Gera o extrato em PDF do mês anterior (Banco Inter), envia ao contador por e-mail e WhatsApp e salva o registro no banco (contabilidades). Ative via .env se o contador aceita receber o extrato em PDF. |
php artisan ln:downloadBoleto {boletos_id} |
Baixa o PDF do boleto gerado no Inter (útil para conferência ou armazenamento manual). |
php artisan ln:mount_qr_code {pixes_id} |
Gera/atualiza o QR Code do Pix informado (quando o Pix já existe no Inter). |
php artisan ln:remove-old-pdf-boleto {dir?} |
Remove PDFs de boletos antigos do diretório informado (ou do diretório padrão). Útil para limpeza de disco. |
Este projeto te auxiliou de alguma forma? Então, que tal me pagar um café? ☕☕
