Neste artigo, vou mostrar como funciona, na prática, um sistema real de cobrança construído em Laravel, integrando Boleto e Pix do Banco Inter, com webhooks, PDFs, crons, Docker, e-mails, WhatsApp, SMS e até ligações automáticas.

Todo o conteúdo é baseado em um projeto open source real, usado em produção, disponível no GitHub:

👉 Repositório:
https://github.com/leonardop21/boleto-inter-free

Importante: este não é um “tutorial de Hello World”. É um guia técnico completo, voltado para quem quer entender arquitetura, evitar erros comuns e colocar cobrança automática em produção com segurança.

Por que integrar diretamente com o Banco Inter?

O Banco Inter oferece uma API robusta para PJ, com suporte nativo a:

• Boletos registrados
• Pix com QR Code dinâmico
• Webhooks de status
• Consulta de cobranças
• Download de PDFs
• Extratos bancários

Ao integrar diretamente com o Inter, você elimina intermediários, reduz custos e ganha controle total sobre o fluxo financeiro.

Mas isso vem com desafios:

• Certificados mTLS
• OAuth2
• Regras rígidas de vencimento
• Webhooks que precisam ser idempotentes
• PDFs que precisam ser armazenados ou regenerados
• Conciliação automática

É exatamente isso que o projeto resolve.

Visão geral da arquitetura do sistema

Antes de entrar em código, é importante entender como o sistema foi pensado.

Componentes principais

• Laravel 8 como base
• MySQL para dados transacionais
• Redis para cache com tags
• Banco Inter API para cobranças
• Notifish para WhatsApp
• SMTP para e-mails
• SMS Dev para SMS
• King SMS (Voicer) para ligações
• Docker + Nginx + PHP-FPM em produção

Nada aqui é experimental. Tudo foi pensado para rodar 24/7, com falhas previsíveis e logs rastreáveis.

Por que Redis é obrigatório neste projeto?

Um erro comum em sistemas de cobrança é consultar a API do banco o tempo todo.

Esse projeto evita isso usando cache agressivo com tags, por exemplo:

• Cache de cobranças
• Cache de clientes
• Cache de serviços
• Cache de status de boletos e Pix

Quando um boleto muda de status (via webhook), o cache relacionado é invalidado.

👉 Sem Redis (ou Memcached), o sistema não funciona corretamente.

Instalação do projeto (ambiente local)

1. Clonando o repositório

git clone https://github.com/leonardop21/boleto-inter-free.git
cd boleto-inter-free
composer install

2. Configuração inicial

cp .env.example .env
php artisan key:generate

Configurando o banco de dados e cache

No .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=boleto_inter
DB_USERNAME=user
DB_PASSWORD=pass

CACHE_DRIVER=redis
SESSION_DRIVER=redis
TIME_CACHE_IN_SECONDS=604800

Depois:

php artisan migrate

Como funciona o modelo de cobrança

O sistema foi pensado para cobrança recorrente, mas funciona também para cobranças pontuais.

Entidades principais

• Cliente
• Serviço
• Cliente x Serviço
• Boleto
• Pix
• NF-e (opcional)

O fluxo é simples:

1. Você cadastra um cliente
2. Cadastra um serviço
3. Vincula o serviço ao cliente
4. O sistema gera boletos ou Pix automaticamente

Integração com o Banco Inter (parte crítica)

Certificados mTLS

O Inter exige:

• Um arquivo .crt
• Um arquivo .key

No .env:

INTER_PATH_CRT=/caminho/inter.crt
INTER_PATH_KEY=/caminho/inter.key

OAuth2

INTER_CLIENT_ID=seu_client_id
INTER_CLIENT_SECRET=seu_client_secret
INTER_CLIENT_SCOPE="extrato.read boleto-cobranca.read boleto-cobranca.write"
INTER_BASE_URL="https://cdpj.partners.bancointer.com.br/"

Sem isso, nenhuma requisição funciona.

Webhooks: o coração da automação

O sistema registra dois webhooks no Inter:

• Boleto
• Pix

INTER_WEBHOOK_URL=https://seusite.com/api/inter/webhook/boleto
INTER_WEBHOOK_URL_PIX=https://seusite.com/api/inter/webhook/pix

O que acontece quando um pagamento é feito?

1. O Inter chama o webhook
2. O sistema valida a assinatura
3. Atualiza o status da cobrança
4. Invalida caches relacionados
5. Registra logs
6. (Opcional) dispara notificações internas

Isso evita:

• Jobs de polling
• Consultas desnecessárias
• Status desatualizado

Geração automática de boletos

Este é um dos pontos mais sofisticados do projeto.

Comando:

php artisan ln:auto_generate_boleto

Regras implementadas

• Se o dia de vencimento já passou → gera para o mês seguinte
• Se o cliente escolheu dia 31 → ajusta para último dia do mês
• Respeita meses com 28, 29, 30 ou 31 dias
• Evita boletos duplicados
• Gera PDF automaticamente
• Salva logs detalhados

Tudo isso roda sem intervenção humana.

Geração automática de Pix

Comando:

php artisan ln:auto_generate_pix

• Gera QR Code
• Gera payload Pix
• Cria cobrança no Inter
• Registra vencimento
• Gera imagem do QR Code (GD)

Envio de cobranças por e-mail

O sistema envia:

• Boleto em PDF
• Pix com QR Code
• NF-e (se configurado)

Configuração SMTP no .env:

MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls

Além disso, o layout do e-mail é personalizável:

• Logo
• Cor de fundo
• Links de suporte

Envio por WhatsApp (Notifish)

Integração direta com a API do Notifish.

NOTIFISH_BASE_URL=https://seu.notifish.com/api/v2/
NOTIFISH_API_KEY=sua_key
NOTIFISH_UUID=sua_instancia

O sistema gera uma URL assinada temporária para o PDF do boleto, válida por poucos minutos — sem expor IDs internos.

SMS e ligações automáticas para inadimplentes

SMS

php artisan ln:send-boleto-sms
php artisan ln:send-pix-sms

Ligação (voz robótica)

php artisan ln:send-boleto-voicer
php artisan ln:send-pix-voicer

Isso é usado somente após o vencimento, como camada extra de cobrança.

Crons: como tudo roda sozinho

Você não agenda cada comando individualmente.

Apenas:

* * * * * php artisan schedule:run

O Laravel Scheduler cuida do resto.

Exemplo:

• Dia 1 → gera boletos
• Antes do vencimento → envia lembrete
• Após vencimento → cobrança progressiva

Docker em produção

O projeto já vem com:

• Dockerfile
• docker-compose.prod.yml
• Nginx configurado
• PHP-FPM otimizado
• Redis
• MySQL

Subir produção:

docker compose -f docker-compose.prod.yml up -d --build

Logs, rastreabilidade e auditoria

Cada processo tem seu próprio log:

• Boletos
• Pix
• NF-e
• Webhooks
• Erros de API

Isso é fundamental para:

• Suporte
• Auditoria
• Contabilidade
• Diagnóstico rápido

Para quem este projeto é indicado?

• Desenvolvedores PHP/Laravel
• SaaS com cobrança recorrente
• Sistemas internos de empresas
• Agências que querem padronizar cobrança
• Projetos que precisam de autonomia financeira

Conclusão

Automatizar cobranças não é só “gerar boleto”.
É lidar com:

• Datas
• Erros bancários
• Comunicação
• Inadimplência
• Escala
• Observabilidade

Este projeto resolve isso de forma pragmática, realista e testada em produção.

👉 Repositório completo:
https://github.com/leonardop21/boleto-inter-free

The post Sistema completo de cobranças via WhatsApp: boleto, Pix e NF-e na prática appeared first on Leonardo Nascimento | Engenheiro de Software.

Você quer receber um evento via API (Webhook), enviar uma mensagem no WhatsApp via Notifish e registrar o resultado (sucesso/erro) em log.

Esse fluxo é útil para:

• alertas operacionais
• notificações de deploy
• falhas de integração
• notificações de sistema para grupos

Pré-requisitos

1. n8n rodando e acessível
2. endpoint do Notifish (o seu padrão):
   POST https://meu-dominio.notifish.com/api/v2/{INSTANCE_UUID}/whatsapp/message/groups
   com header Authorization: Bearer ...
3. um lugar para log
   Vou te dar 2 opções:

• A) log em arquivo via HTTP (endpoint seu) — mais profissional
• B) log no próprio n8n (Execution data) + uma planilha/banco (se preferir)

Aqui vou usar a opção A (mais “produção”).

Parte 1 — Contrato da API (Webhook)

Você vai expor um endpoint no n8n, por exemplo:

POST https://SEU_N8N/webhook/notify

Payload recomendado (simples e suficiente):

{
  "title": "API 5xx alto",
  "message": "Erros 5xx acima do normal em /api/orders",
  "url": "https://seu-dashboard",
  "identifier": "prod:api:5xx",
  "delayMessage": 0
}

Repare que já mandamos identifier. Isso permite deduplicar e evitar spam.

Parte 2 — Dedupe (anti-spam) usando Redis (opcional, mas recomendado)

Se você tiver Redis (muito comum), dá para usar um passo “check” antes do envio.

• chave: dedupe:{identifier}
• TTL: 300s (5 minutos) por exemplo
  Se existir, você não envia.

Se você não tiver Redis, dá para deduplicar com “Data Store” do n8n ou com um endpoint seu.

Vou te passar o fluxo com Data Store do n8n (não depende de infra extra).

Parte 3 — Enviar WhatsApp via Notifish

O Notifish recebe:

{
  "message": "...",
  "identifier": "...",
  "link": true,
  "typing": "composing",
  "delayMessage": 1200
}

A gente vai montar isso no n8n.

Parte 4 — Registrar Log

Depois do envio (sucesso ou falha), registramos em um endpoint de log. Exemplo:

POST https://seu-sistema.com/api/logs/notifish

Log recomendado:

{
  "identifier": "prod:api:5xx",
  "status": "success",
  "http_status": 200,
  "provider": "notifish",
  "payload": { ... },
  "response": { ... },
  "created_at": "2026-01-22T00:00:00-03:00"
}

NODES DO WORKFLOW (passo a passo)

1) Webhook (Trigger)

• Method: POST
• Path: notify
• Response: JSON (200)

2) Function (Normalize)

Cria um formato consistente e monta a mensagem final do WhatsApp:

• título + mensagem + url
• garante identifier
• define delayMessage

3) Data Store (Get)

Busca identifier na datastore (dedupe).

4) IF (Já enviou?)

Se já existe registro recente, responde 200 “ignored” e não envia.

5) HTTP Request (Notifish)

POST no endpoint do Notifish com Bearer Token.

6) Data Store (Set)

Salva identifier com TTL (ex.: 300s) para dedupe.

7) HTTP Request (Log Success)

Envia log para seu endpoint.

8) Error Trigger / Catch (Log Error)

Se Notifish falhar, manda log com status error.

JSON do workflow para importar no n8n

Abaixo um workflow base. Você só precisa trocar:

• NOTIFISH_INSTANCE_UUID
• NOTIFISH_TOKEN
• LOG_ENDPOINT_URL

Import: n8n → Workflows → Import from file/clipboard

{
  "name": "API → Notifish WhatsApp → Log (com dedupe)",
  "nodes": [
    {
      "parameters": {
        "path": "notify",
        "httpMethod": "POST",
        "responseMode": "lastNode",
        "options": {}
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [260, 300]
    },
    {
      "parameters": {
        "functionCode": "const body = $json;\n\nconst title = body.title || 'Notificação';\nconst msg = body.message || '';\nconst url = body.url || '';\n\nconst identifier = body.identifier || `generic:${Date.now()}`;\nconst delayMessage = body.delayMessage ?? 0;\n\nconst whatsappMessage = `*${title}*\\n\\n${msg}${url ? `\\n\\n${url}` : ''}`;\n\nreturn [{\n  identifier,\n  delayMessage,\n  notifishPayload: {\n    message: whatsappMessage,\n    identifier,\n    link: true,\n    typing: 'composing',\n    delayMessage\n  },\n  original: body\n}];"
      },
      "name": "Normalize",
      "type": "n8n-nodes-base.function",
      "typeVersion": 2,
      "position": [520, 300]
    },
    {
      "parameters": {
        "operation": "get",
        "key": "={{$json.identifier}}"
      },
      "name": "Dedupe Get",
      "type": "n8n-nodes-base.dataStore",
      "typeVersion": 1,
      "position": [760, 300]
    },
    {
      "parameters": {
        "conditions": {
          "boolean": [
            {
              "value1": "={{$json.value !== undefined && $json.value !== null}}",
              "value2": true
            }
          ]
        }
      },
      "name": "Já enviou?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2,
      "position": [980, 300]
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={\"status\":\"ignored\",\"reason\":\"dedupe\",\"identifier\":\"{{$json.identifier}}\"}",
        "options": {}
      },
      "name": "Return Ignored",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [1210, 200]
    },
    {
      "parameters": {
        "url": "https://meu-dominio.notifish.com/api/v2/NOTIFISH_INSTANCE_UUID/whatsapp/message/groups",
        "method": "POST",
        "authentication": "none",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer NOTIFISH_TOKEN"
            },
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "Accept",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "jsonBody": "={{$json.notifishPayload}}",
        "options": {
          "timeout": 8000
        }
      },
      "name": "Send Notifish",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [1210, 380]
    },
    {
      "parameters": {
        "operation": "set",
        "key": "={{$json.identifier}}",
        "value": "={{JSON.stringify({sentAt: new Date().toISOString()})}}"
      },
      "name": "Dedupe Set",
      "type": "n8n-nodes-base.dataStore",
      "typeVersion": 1,
      "position": [1450, 380]
    },
    {
      "parameters": {
        "url": "LOG_ENDPOINT_URL",
        "method": "POST",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Content-Type",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "jsonBody": "={{ {\n  identifier: $json.identifier,\n  status: 'success',\n  provider: 'notifish',\n  response: $json,\n  created_at: new Date().toISOString()\n} }}"
      },
      "name": "Log Success",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [1690, 380]
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={\"status\":\"sent\",\"identifier\":\"{{$json.identifier}}\"}",
        "options": {}
      },
      "name": "Return OK",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [1910, 380]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [
        [
          {
            "node": "Normalize",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Normalize": {
      "main": [
        [
          {
            "node": "Dedupe Get",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Dedupe Get": {
      "main": [
        [
          {
            "node": "Já enviou?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Já enviou?": {
      "main": [
        [
          {
            "node": "Return Ignored",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "Send Notifish",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Send Notifish": {
      "main": [
        [
          {
            "node": "Dedupe Set",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Dedupe Set": {
      "main": [
        [
          {
            "node": "Log Success",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Log Success": {
      "main": [
        [
          {
            "node": "Return OK",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": false
}

Observações importantes (produção)

1) Dedupe com Data Store não tem TTL nativo

Ele salva “para sempre” se você não limpar. Em produção, o ideal é:

• usar Redis para TTL real, ou
• incluir timestamp e limpar por job diário

Se você quiser, eu te mando a versão com Redis (TTL real).

2) Log endpoint

Se você não tiver endpoint pronto, você pode logar em:

ou até em um arquivo via API sua

PostgreSQL/MySQL via node de banco

Google Sheets (rápido)

The post Fluxo n8n: API, WhatsApp, Log (com dedupe e tratamento de erro) appeared first on Leonardo Nascimento | Engenheiro de Software.