Pular para o conteúdo principal

Gerenciando Assinantes (Subscribers)

👥 Público centralizado: Gerencie todos os seus usuários, preferências e consentimentos em um só lugar

Assinantes são os destinatários das suas notificações. Centralizar esses dados na Notifica permite:

  • Evitar envio para usuários que optaram por não receber
  • Segmentar públicos com metadados
  • Gerenciar preferências por canal
  • Importar em massa de CSV/JSON

O modelo de assinante​

{
  "id": "sub_abc123",
  "external_id": "user_456",           // ID do seu sistema
  "email": "[email protected]",
  "phone": "+5511987654321",
  "first_name": "Ana Paula",
  "last_name": "Silveira",
  "locale": "pt-BR",
  "timezone": "America/Sao_Paulo",
  "metadata": {
    "plano": "premium",
    "empresa": "Acme Brasil",
    "cargo": "CTO"
  },
  "channels": {
    "email": true,
    "whatsapp": true,
    "sms": false,
    "in_app": true
  },
  "created_at": "2024-01-10T10:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z"
}

Criando um assinante​

Via API​

curl -X POST https://app.usenotifica.com.br/v1/subscribers \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_789",
    "email": "[email protected]",
    "phone": "+5511998765432",
    "first_name": "Carlos",
    "last_name": "Mendes",
    "metadata": {
      "segmento": "enterprise",
      "receita_mensal": 50000
    }
  }'

Resposta:

{
  "id": "sub_xyz789",
  "external_id": "user_789",
  "email": "[email protected]",
  "phone": "+5511998765432",
  "created_at": "2024-01-15T16:30:00Z"
}

Node.js​

async function criarAssinante(dados) {
  const response = await fetch(`${BASE_URL}/subscribers`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      external_id: dados.id,
      email: dados.email,
      phone: dados.telefone,
      first_name: dados.nome,
      metadata: {
        plano: dados.plano,
        ultimo_login: new Date().toISOString()
      }
    })
  });
  
  return response.json();
}

// Uso
criarAssinante({
  id: 'user_123',
  email: '[email protected]',
  telefone: '+5511998765432',
  nome: 'Carlos',
  plano: 'pro'
});

Python​

def criar_assinante(external_id, email, telefone, nome, **metadata):
    payload = {
        'external_id': external_id,
        'email': email,
        'phone': telefone,
        'first_name': nome.split()[0],
        'last_name': ' '.join(nome.split()[1:]) if len(nome.split()) > 1 else '',
        'metadata': metadata
    }
    
    response = requests.post(
        f'{BASE_URL}/subscribers',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json=payload
    )
    response.raise_for_status()
    return response.json()

# Uso
assinante = criar_assinante(
    external_id='user_456',
    email='[email protected]',
    telefone='+5511987654321',
    nome='Maria Fernanda',
    plano='enterprise',
    cidade='São Paulo'
)

Buscando assinantes​

Listar todos (com paginação)​

curl "https://app.usenotifica.com.br/v1/subscribers?page=1&limit=50" \
  -H "Authorization: Bearer nk_live_sua_chave"

Buscar por ID​

curl https://app.usenotifica.com.br/v1/subscribers/sub_xyz789 \
  -H "Authorization: Bearer nk_live_sua_chave"

Buscar por external_id (recomendado)​

curl "https://app.usenotifica.com.br/v1/subscribers?external_id=user_789" \
  -H "Authorization: Bearer nk_live_sua_chave"

Atualizando dados​

curl -X PUT https://app.usenotifica.com.br/v1/subscribers/sub_xyz789 \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "phone": "+5511988877766",
    "metadata": {
      "plano": "enterprise_plus"
    }
  }'

⚠️ LGPD: Mantenha histórico de alterações de dados pessoais para auditoria.

Excluindo assinantes​

curl -X DELETE https://app.usenotifica.com.br/v1/subscribers/sub_xyz789 \
  -H "Authorization: Bearer nk_live_sua_chave"

✅ LGPD compliance: Exclusão remove todos os dados pessoais, mantendo apenas logs anônimos de entrega.

Gerenciando preferências​

Ver preferências de um assinante​

curl https://app.usenotifica.com.br/v1/subscribers/sub_xyz789/preferences \
  -H "Authorization: Bearer nk_live_sua_chave"

Resposta:

{
  "subscriber_id": "sub_xyz789",
  "channels": {
    "email": true,
    "whatsapp": true,
    "sms": false,
    "in_app": true
  },
  "categories": {
    "marketing": false,
    "transacional": true,
    "alertas": true
  },
  "updated_at": "2024-01-15T10:00:00Z"
}

Atualizar preferências​

curl -X PUT https://app.usenotifica.com.br/v1/subscribers/sub_xyz789/preferences \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": {
      "email": true,
      "whatsapp": false,
      "sms": false
    },
    "categories": {
      "marketing": false,
      "transacional": true
    }
  }'

Implementando página de preferências​

Crie uma página onde seus usuários controlam o que recebem:

// Frontend - React/Vue/etc
async function toggleChannel(channel, enabled) {
  await fetch(`/api/preferences/${subscriberId}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      channels: { [channel]: enabled }
    })
  });
}

// Backend - proxy para Notifica
app.put('/api/preferences/:id', async (req, res) => {
  const response = await fetch(
    `${NOTIFICA_URL}/subscribers/${req.params.id}/preferences`,
    {
      method: 'PUT',
      headers: { 
        'Authorization': `Bearer ${NOTIFICA_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(req.body)
    }
  );
  res.json(await response.json());
});

Importação em massa​

Para migrar milhares de assinantes de uma vez:

Formato CSV​

external_id,email,phone,first_name,last_name,metadata.plano
user_001,[email protected],+5511987654321,João,Silva,free
user_002,[email protected],+5511998765432,Maria,Santos,premium
user_003,[email protected],+5511976543210,Pedro,Costa,enterprise

Upload via API​

curl -X POST https://app.usenotifica.com.br/v1/subscribers/import \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -F "[email protected]" \
  -F "skip_duplicates=true" \
  -F "update_existing=true"

Resposta:

{
  "import_id": "imp_abc123",
  "status": "processing",
  "total_rows": 15000,
  "processed": 0,
  "webhook_url": "https://sua-api.com/webhooks/notifica-import"
}

Ver status da importação​

curl https://app.usenotifica.com.br/v1/subscribers/import/imp_abc123 \
  -H "Authorization: Bearer nk_live_sua_chave"

Código completo: Fluxo típico​

// signup.js - Quando usuário se cadastra no seu app

async function onUserSignup(userData) {
  try {
    // 1. Criar assinante na Notifica
    const subscriber = await criarAssinante({
      external_id: userData.id,
      email: userData.email,
      telefone: userData.phone,
      nome: userData.name,
      plano: userData.plan
    });
    
    // 2. Salvar subscriber_id no seu banco
    await db.users.update(userData.id, {
      notifica_subscriber_id: subscriber.id
    });
    
    // 3. Enviar email de boas-vindas
    await enviarNotificacao({
      subscriber_id: subscriber.id,
      template: 'welcome_email'
    });
    
    console.log('✅ Usuário integrado à Notifica');
  } catch (error) {
    console.error('❌ Erro:', error);
  }
}

LGPD: Respeitando consentimento​

Regras importantes​

  1. Consentimento explícito: Não adicione emails sem permissão
  2. Opt-out fácil: Sempre inclua link de descadastro
  3. Direito ao esquecimento: Permita exclusão completa de dados
  4. Transparência: Informe quais dados você armazena

Implementando double opt-in​

// 1. Usuário preenche formulário
// 2. Criar assinante com email=false (não ativo)
await criarAssinante({
  external_id: userId,
  email: email,
  // não ativar canais ainda
});

// 3. Enviar email de confirmação
await enviarNotificacao({
  to: { email: email },
  template: 'confirm_email',
  data: { token: confirmToken }
});

// 4. Ao confirmar, ativar canal
await fetch(`${BASE_URL}/subscribers/${subId}/preferences`, {
  method: 'PUT',
  body: JSON.stringify({ channels: { email: true } })
});

FAQ​

Q: Posso usar apenas o email do assinante, sem criar cadastro?
A: Sim! Para envios pontuais, use POST /notifications com to.email direto. Assinantes são recomendados para gestão de preferências.

Q: E se o email/telefone já existir?
A: Retorna erro 409. Use PUT /subscribers/:id para atualizar ou verifique antes com GET /subscribers?email=xxx.

Q: Quantos metadados posso adicionar?
A: Até 50 campos, máximo 10KB total.

Q: Posso segmentar por metadata?
A: Sim! Use GET /subscribers?metadata.plano=premium ou filtros avançados.

Próximo passo​

Agora que seus assinantes estão cadastrados, aprenda a enviar notificações para eles de forma eficiente.