API de contactos

Documentación interna para desarrolladores. Esta página cubre los puntos finales de la API de contactos, las operaciones masivas, la detección de fusiones y el modelo de datos de cliente 360. No está destinado a usuarios finales.

​

Mapa de ruta

​

Patrón de autenticación

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

​

Esquema de objeto de contacto

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 contactos (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

​

Eliminación masiva

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

​

Fusionar candidatos

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

• El contacto principal mantiene su identificación.
• Se reatribuyen las conversaciones del contacto secundario.
• Se elimina el contacto secundario.
• No deshacer: advierte a los usuarios antes de fusionar

​

Cliente-Vista 360

​

Índices Prisma utilizados

​

Problemas conocidos / Problemas

• Cascada de eliminación masiva: Al eliminar contactos, se eliminan sus conversaciones. Esta es una operación destructiva. Confirme siempre con el usuario antes de llamar.
• Normalización de teléfonos: Los números de teléfono deben almacenarse en formato E.164 (+5511999990000). Los formatos inconsistentes hacen que los candidatos a fusión omitan duplicados.
• externalId se usa para la sincronización de CRM (por ejemplo, HubSpot, Salesforce). Al sincronizar desde sistemas externos, utilice siempre upsert en organizationId + externalId.
• Fusionar candidatos utiliza coincidencias a nivel de aplicación (no a nivel de base de datos). Para listas de contactos grandes (más de 100.000), esto puede resultar lento. Considere agregar un trabajo en segundo plano para organizaciones grandes.