Tutorial

Integrando Notifica com Node.js: Guia Passo a Passo

Diego Santos•24 de fevereiro de 2026•7 min read

Integrando Notifica com Node.js: Do Zero à Primeira Notificação em 10 Minutos

Se você trabalha com Node.js (e quem não trabalha em 2026?), este tutorial vai te levar do npm install à primeira notificação enviada em menos de 10 minutos.

Sem enrolação. Código real, cenários reais.

Pré-requisitos

Node.js 18+ instalado
Uma conta na Notifica (crie gratuitamente)
Uma API key com escopo notifications:write (gere no Dashboard → Settings → API Keys)

Passo 1: Instalação

npm install @notifica/node

Ou se preferir yarn:

yarn add @notifica/node

Passo 2: Configuração Básica

// notifica.js
import { Notifica } from '@notifica/node';

const notifica = new Notifica({
  apiKey: process.env.NOTIFICA_API_KEY, // nunca hardcode!
  environment: 'production', // ou 'sandbox' para testes
});

export default notifica;

Dica de segurança: Use variáveis de ambiente. Nunca commite sua API key. Adicione .env ao .gitignore.

Passo 3: Enviando Seu Primeiro Email

import notifica from './notifica.js';

async function enviarEmailBoasVindas(usuario) {
  try {
    const resultado = await notifica.trigger('welcome-email', {
      to: {
        subscriberId: usuario.id,
        email: usuario.email,
        firstName: usuario.nome,
      },
      payload: {
        nome: usuario.nome,
        linkAtivacao: `https://meuapp.com.br/ativar/${usuario.token}`,
      },
    });

    console.log('✅ Email enviado:', resultado.id);
    return resultado;
  } catch (error) {
    console.error('❌ Falha no envio:', error.message);
    throw error;
  }
}

// Uso
await enviarEmailBoasVindas({
  id: 'usr_123',
  nome: 'João Silva',
  email: 'joao@empresa.com.br',
  token: 'abc123xyz',
});

O que acontece por trás:

O SDK envia o trigger para a API da Notifica
A Notifica busca o template welcome-email no seu dashboard
Injeta as variáveis (nome, linkAtivacao) no template
Envia o email via seu provedor configurado (SMTP relay ou BYOS)
Registra o envio nos logs de auditoria

Passo 4: Enviando SMS

async function enviarCodigoVerificacao(usuario, codigo) {
  const resultado = await notifica.trigger('verification-code', {
    to: {
      subscriberId: usuario.id,
      phone: usuario.telefone, // formato E.164: +5511999999999
    },
    payload: {
      codigo: codigo,
      expiracao: '10 minutos',
    },
    overrides: {
      sms: {
        // força envio via provedor específico
        providerId: 'zenvia-primary',
      },
    },
  });

  return resultado;
}

Formato do telefone: Sempre use E.164 (+5511999999999). Números sem código de país vão falhar.

Passo 5: Enviando WhatsApp

async function notificarStatusPedido(usuario, pedido) {
  const resultado = await notifica.trigger('order-status-update', {
    to: {
      subscriberId: usuario.id,
      phone: usuario.telefone,
    },
    payload: {
      numeroPedido: pedido.numero,
      status: pedido.status,
      linkRastreamento: pedido.trackingUrl,
      previsaoEntrega: pedido.previsao,
    },
  });

  return resultado;
}

// Exemplo de uso com Pix
await notificarStatusPedido(
  { id: 'usr_456', telefone: '+5511988887777' },
  {
    numero: '#12345',
    status: 'Pagamento Pix confirmado',
    trackingUrl: 'https://meuapp.com.br/rastreio/12345',
    previsao: '3 dias úteis',
  }
);

Passo 6: Notificações Multi-Canal com Fallback

Este é o poder real da Notifica — enviar para múltiplos canais com lógica de fallback:

async function alertaFraude(usuario, transacao) {
  // O workflow 'fraud-alert' está configurado no Dashboard:
  // 1. Tenta WhatsApp (prioridade alta)
  // 2. Se falhar em 30s, envia SMS
  // 3. Se ambos falharem, envia email
  // 4. Registra tudo no audit log

  const resultado = await notifica.trigger('fraud-alert', {
    to: {
      subscriberId: usuario.id,
      email: usuario.email,
      phone: usuario.telefone,
    },
    payload: {
      valor: transacao.valor,
      estabelecimento: transacao.loja,
      dataHora: new Date().toLocaleString('pt-BR'),
      linkConfirmar: `https://meuapp.com.br/confirmar/${transacao.id}`,
      linkBloquear: `https://meuapp.com.br/bloquear/${transacao.id}`,
    },
  });

  return resultado;
}

Exemplo Completo: Express.js + Notifica

Aqui está um exemplo real de API Express que integra notificações em vários fluxos:

// app.js
import express from 'express';
import notifica from './notifica.js';

const app = express();
app.use(express.json());

// Webhook de novo cadastro
app.post('/api/users', async (req, res) => {
  const { nome, email, telefone } = req.body;

  // 1. Cria usuário no banco (seu código aqui)
  const usuario = await criarUsuario({ nome, email, telefone });

  // 2. Registra como subscriber na Notifica
  await notifica.subscribers.identify(usuario.id, {
    email: usuario.email,
    phone: usuario.telefone,
    firstName: usuario.nome,
    locale: 'pt-BR',
    data: {
      plano: 'free',
      origem: req.body.utm_source || 'direct',
    },
  });

  // 3. Dispara workflow de boas-vindas
  await notifica.trigger('onboarding-flow', {
    to: { subscriberId: usuario.id },
    payload: { nome: usuario.nome },
  });

  res.status(201).json({ id: usuario.id });
});

// Webhook de Pix (recebido do Asaas)
app.post('/webhooks/asaas/pix', async (req, res) => {
  const { payment } = req.body;

  if (payment.status === 'RECEIVED') {
    await notifica.trigger('pix-confirmed', {
      to: { subscriberId: payment.customer },
      payload: {
        valor: `R$ ${payment.value.toFixed(2)}`,
        descricao: payment.description,
        transactionId: payment.transactionReceiptUrl,
      },
    });
  }

  res.sendStatus(200);
});

// Webhook de status de entrega (da transportadora)
app.post('/webhooks/shipping', async (req, res) => {
  const { orderId, status, trackingUrl } = req.body;
  const pedido = await buscarPedido(orderId);

  await notifica.trigger('shipping-update', {
    to: { subscriberId: pedido.userId },
    payload: {
      numeroPedido: orderId,
      status: traduzirStatus(status),
      linkRastreamento: trackingUrl,
    },
  });

  res.sendStatus(200);
});

app.listen(3000, () => console.log('🚀 API rodando na porta 3000'));

Gerenciando Preferências do Usuário

// Atualizar preferências de canal
await notifica.subscribers.updatePreferences('usr_123', {
  channels: {
    email: true,
    sms: true,
    whatsapp: false, // usuário não quer WhatsApp
  },
  topics: {
    marketing: false,
    transactional: true,
    security: true,
  },
});

// Consultar preferências
const prefs = await notifica.subscribers.getPreferences('usr_123');
console.log(prefs);
// { channels: { email: true, sms: true, whatsapp: false }, ... }

Recebendo Webhooks de Status

Configure um endpoint para receber status de entrega:

// Webhook da Notifica → seu app
app.post('/webhooks/notifica', async (req, res) => {
  const { type, data } = req.body;

  switch (type) {
    case 'notification.delivered':
      console.log(`✅ Entregue: ${data.notificationId} via ${data.channel}`);
      break;

    case 'notification.failed':
      console.error(`❌ Falhou: ${data.notificationId}`, data.error);
      // Lógica de retry ou alerta interno
      break;

    case 'notification.opened':
      console.log(`👁 Aberto: ${data.notificationId}`);
      // Atualizar analytics
      break;

    case 'subscriber.unsubscribed':
      console.log(`🚫 Opt-out: ${data.subscriberId} do canal ${data.channel}`);
      // Atualizar preferências no seu banco
      break;
  }

  res.sendStatus(200);
});

Tratamento de Erros

import { NotificaError, RateLimitError, ValidationError } from '@notifica/node';

try {
  await notifica.trigger('welcome-email', { /* ... */ });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Espere e tente novamente
    console.log(`Rate limited. Retry em ${error.retryAfter}ms`);
    await sleep(error.retryAfter);
    // retry...
  } else if (error instanceof ValidationError) {
    // Payload inválido — corrija antes de reenviar
    console.error('Validação falhou:', error.details);
  } else if (error instanceof NotificaError) {
    // Erro genérico da API
    console.error(`Erro ${error.statusCode}: ${error.message}`);
  } else {
    // Erro de rede ou inesperado
    throw error;
  }
}

Dicas de Performance

1. Envios em Lote (Bulk)

// Enviar para múltiplos destinatários de uma vez
const destinatarios = usuarios.map((u) => ({
  subscriberId: u.id,
  email: u.email,
  payload: { nome: u.nome, saldo: u.saldo },
}));

await notifica.trigger('monthly-statement', {
  to: destinatarios, // array de até 1000 destinatários
});

2. Fire and Forget (Assíncrono)

// Se você não precisa esperar a confirmação
notifica.trigger('analytics-event', {
  to: { subscriberId: usuario.id },
  payload: { evento: 'login' },
}).catch(console.error); // não bloqueia o fluxo

// Continua imediatamente
res.json({ status: 'ok' });

3. Circuit Breaker Pattern

import CircuitBreaker from 'opossum';

const breaker = new CircuitBreaker(
  (params) => notifica.trigger(params.template, params.data),
  {
    timeout: 5000, // 5s timeout
    errorThresholdPercentage: 50, // abre circuito com 50% de erros
    resetTimeout: 30000, // tenta novamente após 30s
  }
);

breaker.on('open', () => {
  console.warn('⚠️ Circuit breaker aberto — notificações em fallback');
  // Enfileirar para retry posterior
});

TypeScript

O SDK é totalmente tipado:

import { Notifica, TriggerPayload } from '@notifica/node';

interface WelcomePayload {
  nome: string;
  linkAtivacao: string;
}

const resultado = await notifica.trigger<WelcomePayload>('welcome-email', {
  to: { subscriberId: 'usr_123', email: 'joao@test.com' },
  payload: {
    nome: 'João',
    linkAtivacao: 'https://...',
    // campoInexistente: 'erro!' // ← TypeScript vai reclamar
  },
});

Testando com Sandbox

// Em testes, use o modo sandbox
const notifica = new Notifica({
  apiKey: process.env.NOTIFICA_API_KEY_TEST, // chave de teste
  environment: 'sandbox',
});

// Sandbox não envia notificações reais
// Mas retorna respostas realistas para testes
const resultado = await notifica.trigger('welcome-email', {
  to: { subscriberId: 'test_user', email: 'test@test.com' },
  payload: { nome: 'Teste' },
});

console.log(resultado.status); // 'sent' (simulado)

Conclusão

Em 10 minutos você:

✅ Instalou o SDK
✅ Configurou a conexão
✅ Enviou email, SMS e WhatsApp
✅ Implementou fallback multi-canal
✅ Configurou webhooks de status

O próximo passo? Explore os workflows visuais no Dashboard da Notifica — eles permitem criar lógica complexa de notificação sem escrever código adicional.

Pronto para começar? Instale o SDK (npm install @notifica/node), pegue sua API key gratuita e envie sua primeira notificação. Toda a documentação está em português.