API de contatos

Documentação interna para desenvolvedores. Esta página aborda os endpoints da API Contacts, operações em massa, detecção de mesclagem e o modelo de dados do cliente 360. Não se destina a usuários finais.

​

Mapa de rotas

​

Padrão de autenticação

withPermissionRoute(req, {
  anyPermission: ['contacts.read'],  // for GET
  // or
  anyPermission: ['contacts.write'], // for mutations
  authMode: 'lightweight',           // for reads
}, handler)

​

Esquema de objeto de contato

interface Contact {
  id: string;
  organizationId: string;
  name: string | null;
  email: string | null;
  phone: string | null;
  whatsappPhone: string | null;
  externalId: string | null;
  avatarUrl: string | null;
  metadata: Record<string, unknown>;
  tags: string[];
  createdAt: string;
  updatedAt: string;
}

​

Listar contatos (filtros)

// GET /api/contacts
// Query params:
// - search: string (name, email, phone, externalId)
// - page, limit: pagination
// - tag: string (filter by tag)
// - channel: string (contacts with conversations in this channel)
// - dateFrom, dateTo: ISO 8601

​

Exclusão em massa

// POST /api/contacts/bulk-delete
// Body: { contactIds: string[] }
// Deletes all contacts + cascades to conversations
// Max batch: 100 IDs per request (to prevent timeout)

​

Mesclar Candidatos

// GET /api/contacts/merge-candidates?contactId=xxx
// Returns contacts that match by email, phone, or name similarity
// Uses: Prisma + application-level fuzzy matching

• O contato principal mantém seu ID
• As conversas do contato secundário são reatribuídas
• O contato secundário é excluído
• Não desfazer — avisar os usuários antes da mesclagem

​

Visão 360 do cliente

​

Índices Prisma usados

​

Problemas conhecidos/pegadinhas

• Exclusão em cascata em massa: A exclusão de contatos exclui suas conversas. Esta é uma operação destrutiva. Sempre confirme com o usuário antes de ligar.
• Normalização do telefone: Os números de telefone devem ser armazenados no formato E.164 (+5511999990000). Formatos inconsistentes fazem com que os candidatos à mesclagem percam duplicatas.
• externalId é usado para sincronização de CRM (por exemplo, HubSpot, Salesforce). Ao sincronizar de sistemas externos, sempre use upsert em organizationId + externalId.
• Mesclar candidatos usa correspondência em nível de aplicativo (não em nível de banco de dados). Para listas de contatos grandes (mais de 100 mil), isso pode ser lento. Considere adicionar um trabalho em segundo plano para organizações grandes.