WhatsApp API para contadores: boleto, prazo e declaração automáticos

Escritório de contabilidade médio no Brasil tem 150-300 clientes ativos e 2-5 contadores. A maior parte do tempo deles é gasta com tarefas repetitivas: lembrar cliente que vence DARF amanhã, pedir nota fiscal de fornecedor que atrasou, mandar guia de DAS no dia 20 do mês. Tudo manual, tudo no WhatsApp pessoal do contador, tudo correndo o risco de cair na caixa de entrada do "vou ler depois".

Pesquisa do CFC (Conselho Federal de Contabilidade) mostra que escritórios que perdem clientes citam "comunicação ruim" em 41% das saídas. Ou seja: cliente sai não porque o contador é ruim, mas porque o cliente sentiu falta de comunicação proativa. WhatsApp API resolve exatamente isso, e este artigo mostra como.

Os 4 casos de automação que mais economizam tempo

Caso 1: Alerta de vencimento de DARF/DAS

Todo escritório tem agenda de vencimentos: dia 15 GPS, dia 20 DAS-MEI, dia 25 IRRF, etc. Sistema dispara WhatsApp 3 dias antes E no dia, com link da guia em PDF anexada.

Caso 2: Solicitação automática de documentos

Dia 1 de cada mês, sistema lista clientes que precisam mandar nota fiscal de fornecedor. Dispara mensagem padrão. Cliente responde anexando PDF/foto. Sistema baixa e arquiva no DropBox/Google Drive da pasta do cliente.

Caso 3: Envio de guias prontas

Quando o software de contabilidade gera DARF/DAS/GPS, dispara automaticamente para o cliente em PDF. Cliente clica → abre PDF → paga.

Caso 4: Lembretes de IR pessoa física

Em março/abril, escritório que faz IR para pessoa física manda sequência: "(1) precisamos de seus documentos até dia X; (2) seus dados foram processados, restituição estimada de R$X; (3) declaração entregue, comprovante anexo". Cliente sente que está sendo cuidado.

Arquitetura simples

Você tem uma tabela de obrigações no banco (ou planilha exportada do software de contabilidade):

CREATE TABLE obrigacoes (
  id SERIAL PRIMARY KEY,
  cliente_id INT NOT NULL,
  cliente_telefone VARCHAR(20) NOT NULL,
  cliente_nome VARCHAR(120) NOT NULL,
  tipo VARCHAR(40) NOT NULL,        -- 'DARF', 'DAS', 'GPS', 'IRRF', 'IRPF'
  vencimento DATE NOT NULL,
  valor_centavos INT,
  guia_pdf_url TEXT,                -- link no S3/storage
  status VARCHAR(20) DEFAULT 'pending',   -- 'pending', 'notified', 'paid'
  notified_at TIMESTAMPTZ,
  paid_at TIMESTAMPTZ
);
CREATE INDEX idx_oblig_status_venc ON obrigacoes(status, vencimento);

Cron diário às 8h

// alerts-daily.ts
import axios from "axios";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const ZAP = axios.create({
  baseURL: "https://api.zap-api.tech/v1",
  headers: { Authorization: `Bearer ${process.env.ZAP_TOKEN}` },
});

async function main() {
  // Pega obrigações que vencem em 3 dias OU hoje
  const { rows } = await pool.query(`
    SELECT * FROM obrigacoes
    WHERE status = 'pending'
      AND (vencimento = CURRENT_DATE + INTERVAL '3 days' OR vencimento = CURRENT_DATE)
  `);

  for (const ob of rows) {
    const dias = Math.round((ob.vencimento - new Date()) / (1000 * 60 * 60 * 24));
    const texto = dias === 0
      ? `📌 *Vence hoje:* ${ob.tipo}\nValor: R$ ${(ob.valor_centavos / 100).toFixed(2)}\nNão deixe para a última hora.`
      : `⏰ *Lembrete ${dias} dias:* ${ob.tipo} vence em ${ob.vencimento.toLocaleDateString("pt-BR")}\nValor: R$ ${(ob.valor_centavos / 100).toFixed(2)}`;

    // Envia o texto
    await ZAP.post(`/instances/${process.env.INSTANCE_ID}/messages`, {
      to: ob.cliente_telefone,
      type: "text",
      text: texto,
    });

    // Envia a guia em PDF, se já existir
    if (ob.guia_pdf_url) {
      await ZAP.post(`/instances/${process.env.INSTANCE_ID}/messages`, {
        to: ob.cliente_telefone,
        type: "document",
        document: {
          url: ob.guia_pdf_url,
          fileName: `${ob.tipo}_${ob.vencimento.toISOString().slice(0,10)}.pdf`,
        },
      });
    }

    await pool.query(`UPDATE obrigacoes SET status='notified', notified_at=NOW() WHERE id=$1`, [ob.id]);
  }
}

main().catch(console.error);

Solicitação de documentos com keyword response

No dia 1 de cada mês, dispara para todos os clientes que precisam mandar nota:

"Bom dia, {{nome}}! 📂\n\nÉ início de mês — preciso da sua nota fiscal de fornecedor de {{mes_anterior}}. Pode me mandar agora? Pode ser foto ou PDF.\n\nResponda com a nota anexada ou digite *NAO TENHO* se não houve compras."

Webhook recebe a mensagem e cria automaticamente um arquivo na pasta do cliente:

app.post("/webhook/zap", async (req, res) => {
  res.status(200).send("ok");
  if (req.body.type !== "message.received") return;

  const { from, body, mediaUrl } = req.body.message;
  const cliente = await pool.query("SELECT * FROM clientes WHERE telefone=$1", [from]).then(r => r.rows[0]);
  if (!cliente) return;

  if (body.text === "NAO TENHO") {
    await marcarSemNota(cliente.id);
    await ZAP.post(`/instances/${process.env.INSTANCE_ID}/messages`, {
      to: from, type: "text",
      text: "Anotado! Sem notas neste mês. Bom trabalho 👍",
    });
    return;
  }

  if (mediaUrl) {
    const buffer = await axios.get(mediaUrl, { responseType: "arraybuffer" });
    await s3.upload({
      Bucket: "escritorio-docs",
      Key: `clientes/${cliente.id}/${new Date().toISOString()}.pdf`,
      Body: buffer.data,
    }).promise();
    await ZAP.post(`/instances/${process.env.INSTANCE_ID}/messages`, {
      to: from, type: "text",
      text: "Recebido! ✅ Já arquivei. Obrigado.",
    });
  }
});

Compliance: opt-out por keyword

Cliente pode pedir para parar de receber lembretes. Mensagem padrão deve sempre incluir o opt-out:

"... Para parar de receber esses lembretes, responda *SAIR*."

Webhook detecta a palavra e marca o cliente:

if (body.text?.trim().toUpperCase() === "SAIR") {
  await pool.query("UPDATE clientes SET whatsapp_opt_in=false WHERE telefone=$1", [from]);
  await ZAP.post(`/instances/${process.env.INSTANCE_ID}/messages`, {
    to: from, type: "text",
    text: "Você não vai mais receber lembretes automáticos por aqui. Continuamos disponíveis quando precisar.",
  });
}

O cron diário deve respeitar o flag: WHERE clientes.whatsapp_opt_in = true.

CFC compliance e LGPD

• Consentimento documentado: contrato com o cliente já deve mencionar uso de WhatsApp para comunicação operacional. Se não menciona, peça opt-in explícito antes do primeiro envio.
• Sigilo profissional (Resolução CFC 1.054/2005): documentos contábeis sensíveis (folha, balanço) NÃO devem ir por WhatsApp em texto puro. Mande link autenticado para o portal do cliente.
• Retenção LGPD: mensagens enviadas/recebidas devem ser retidas pelo prazo do contrato + período de obrigação fiscal (5 anos). A ZAP API oferece GET /v1/instances/:id/messages?from=&to= para exportação.
• Direito de acesso: cliente pode pedir exportação dos próprios dados — você precisa ser capaz de gerar isso em até 15 dias.

Casos práticos

Caso 1: Escritório com 180 clientes em São Paulo

Antes: 1 atendente passava 4h/dia mandando lembrete por lembrete no WhatsApp pessoal. Depois: cron automático faz tudo em 8 minutos diários. Atendente cuida de exceções (cliente que respondeu com pergunta) — ~30 min/dia. Economia: ~16h/semana, equivalente a R$3.200/mês de salário liberado para tarefas de maior valor.

Caso 2: Contabilidade nicho de médicos (45 clientes)

Cliente médico tipicamente tem 3-4 fontes de renda (CNPJ próprio, hospital, plano de saúde, autônomo) e frequentemente não envia documentos. Após implementar lembretes via WhatsApp, taxa de recebimento de documentos no prazo subiu de 62% para 91%. Inadimplência de honorários caiu 40% porque cliente percebe que o escritório está "em cima".

Caso 3: Escritório multi-sócio (320 clientes)

3 sócios, cada um com sua carteira. Cada sócio tem instância WhatsApp própria. Cron envia lembretes da carteira do sócio responsável, com a marca do sócio. Quando cliente responde, mensagem chega no WhatsApp do sócio dele, não em pool genérico — preserva relacionamento pessoal.

FAQ

É legal mandar lembrete de tributo via WhatsApp?

Sim. O lembrete é comunicação operacional do contrato de prestação de serviços contábeis, prevista no contrato assinado. Não é spam nem oferta comercial. A LGPD permite tratamento de dados quando há "execução de contrato" (Art. 7º, V).

Funciona com Domínio, Alterdata, SCI, Sage?

Sim — qualquer sistema contábil que exporta CSV ou tem API. O fluxo é: software de contabilidade → exporta tabela de obrigações em CSV → script importa para o Postgres → cron dispara mensagens. Quem usa software cloud (Conta Azul, Contábil, etc.) tipicamente tem API direto.

Cliente tem múltiplos sócios — para quem mando o lembrete?

Tabela contatos_cliente: cada cliente pode ter N contatos com diferentes papéis (financeiro, fiscal, RH). Manda lembrete fiscal só para o contato com role=fiscal, lembrete de folha só para role=rh, etc.

E se o cliente mandar dados sensíveis (folha de pagamento) por WhatsApp?

Aceite, arquive criptografado e responda orientando que o canal correto é o portal do cliente. Não recuse — cliente pode interpretar como descaso. Mas eduque progressivamente sobre o canal seguro.

Como provo que o cliente foi notificado?

O endpoint GET /v1/instances/:id/messages/:messageId retorna status (sent, delivered, read) com timestamp. Salve o messageId na tabela de obrigações como evidência. Em caso de auditoria ou disputa, você tem prova de entrega com data/hora exata.

Próximo passo

Crie sua conta e implemente os 4 casos acima em 1-2 dias. Criar conta grátis e libere horas/semana do seu time.