SMOC Public Contacts API — Guía de integración

Guía de la API Pública de Contactos de SMOC: un endpoint REST de solo lectura para listar contactos y obtener recuentos agregados de tu empresa. Úsalo desde integraciones personalizadas, trabajos de sincronización o junto con la aplicación de Zapier.

Descripción general

La API Pública de SMOC permite que sistemas de terceros lean contactos de una sola empresa. Está alojada en Cloudflare Workers y se delimita automáticamente a la empresa asociada a tu clave API.

Lo que hace actualmente:

• Lista los contactos de tu empresa (hasta 500 por solicitud)
• Devuelve recuentos agregados de leads y clientes
• Delimita los datos automáticamente a la empresa asociada a tu clave API

Lo que no hace:

• Crear, actualizar o eliminar contactos
• Paginación con cursores o desplazamientos (solo un límite limit)
• Consultar varias empresas con una sola clave

Este contrato compatible con Zapier se mantiene. El único endpoint de contactos para ese contrato es:

GET /api/company/mongocontact

La búsqueda avanzada de contactos es adicional: POST /api/v2/contacts_search. No migres Zapier fuera de mongocontact.

Para la configuración en Console, autenticación y una visión general de las funciones, comienza con la guía de conexión a la API REST.

Obtén tu clave API

Todas las integraciones de datos de SMOC utilizan el mismo patrón de token de Console que Zapier y MCP:

1. Inicia sesión en SMOC Console.
2. Ve a Ajustes → Integraciones → API (usa Integraciones → Zapier para la configuración específica de Zapier).
3. Opcionalmente nombra la clave y establece una caducidad, luego haz clic en Generar nueva clave API.
4. Copia la clave inmediatamente: solo se muestra una vez y no se puede recuperar más tarde.

Generar una nueva clave no revoca las claves existentes. Las claves emitidas se muestran en la misma página: revoca las claves no utilizadas allí cuando necesites rotar credenciales.

Cada clave está vinculada a una empresa. La clave lleva una declaración operatorId igual al ID de esa empresa. La API utiliza esto para delimitar todos los datos de contacto: no puedes pasar un ID de empresa diferente en la solicitud.

URLs base

Entorno	URL base
Producción	https://api.smoc.ai

Ejemplo de endpoint completo:

GET https://api.smoc.ai/api/company/mongocontact

Autenticación

Envía tu clave API en una cabecera HTTP personalizada llamada token:

GET /api/company/mongocontact HTTP/1.1
Host: api.smoc.ai
token: <your-api-key>
Content-Type: application/json

La API verifica la clave y lee la declaración operatorId para determinar de qué empresa devolver los contactos. No envías un ID de empresa en la URL ni en la cadena de consulta.

No uses:

• Authorization: Bearer … — esta cabecera no es aceptada por este endpoint (aunque la página "API Access" de Console pueda mostrarlo actualmente). Usa la cabecera token en integraciones hasta que se añada soporte de producto para Bearer.
• Claves secretas de Clerk (sk_…) o claves publicables (pk_…): se rechazan con 401 Invalid token type.

Solicitud

Método: solo GET. Otros métodos (por ejemplo, POST) devuelven 404 Not Found.

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
limit	entero	No	100	Máximo de contactos a devolver. Debe estar entre 1–500.
sortByField	cadena	No	(ninguno)	Ordena los contactos descendente por este campo.
status	cadena	No	(ninguno)	Filtra por estado del contacto. status=1 es el sondeo estándar de leads, incluyendo smart leads positivos de flujo de mensajes.

Valores permitidos para sortByField:

Valor	Ordena por
createdAt	Fecha de creación del contacto. Cuando se solicita este orden (y status se omite o es 1), los smart leads recientes de los últimos 14 días se integran y la página se reordena por max(createdAt, leadCapturedAt) para que aparezcan sin desplazar los contactos web más recientes.
updatedAt	Fecha de última actualización
lastConversationDate	Fecha de última conversación
leadCapturedAt	Cuando el contacto se convirtió en smart lead (usa updatedAt para filas históricas)
companyUsers.lastConversationDate	Alias heredado de lastConversationDate (compatibilidad con Zapier)

El orden es siempre descendente (más reciente/mayor primero). Si se omite, se usa el orden natural de MongoDB.

Respuesta

Éxito (200 OK)

{
  "data": [ /* array of contact objects */ ],
  "leadsCount": 42,
  "customerCount": 18
}

Campo	Tipo	Descripción
data	array	Registros de contactos de tu empresa
leadsCount	número	Contactos con estado "1" o null
customerCount	número	Contactos con estado "2"

leadsCount y customerCount reflejan todos los contactos de la empresa, no solo la página actual.

Campos del objeto contacto

Cada elemento en data incluye solo los campos siguientes (se excluyen campos sensibles/internos):

Campo	Descripción
id	Identidad de sondeo de Zapier. Normalmente el _id de Mongo. Los smart leads de conversión tardía (leadCapturedAt al menos 1 hora después de createdAt, y a partir del 11-09-2026) usan {mongoId}__sl para que New Contact pueda activarse. Usa contactId para el id estable de Mongo.
contactId	_id estable de Mongo. No cambia cuando id se reescribe para un smart lead tardío.
linkedinUrl	URL de perfil de LinkedIn cuando está presente (linkedinUrl de nivel superior o el primer linkedinProfiles[].url).
userId	Identificador de usuario
email	Dirección de correo electrónico
firstName	Nombre
lastName	Apellidos
msisdn	Número de teléfono
company	Nombre de la empresa (empleador del contacto, si se captura)
city, state, street, zip	Campos de dirección
status	Estado del ciclo de vida del contacto (ver abajo). Los smart leads positivos de flujo de mensajes usan "1" como los leads de formulario web.
leadSentiment	"positive" o "negative" cuando se clasificó una respuesta de flujo de mensajes; se omite en caso contrario
leadCapturedAt	Hora ISO-8601 en que el contacto se convirtió en smart lead positivo (usa updatedAt si falta)
tags	Etiquetas de contacto resueltas { id, name, systemKind? }[] (incluye Auto: Positive Lead / Auto: Negative Lead)
brandId	Identificador de marca
operatorId	Identificador de empresa/operador
createdAt	Marca de tiempo de creación ISO-8601
updatedAt	Marca de tiempo de última actualización ISO-8601
lastConversationDate	Fecha ISO-8601 de la última conversación
acceptedCommunication	Si el contacto aceptó comunicaciones
acceptedPrivacy	Si el contacto aceptó los términos de privacidad
inviterUser	Quién refirió a este contacto (objeto)
rewardFlows	Flujos donde se ganaron recompensas
promosPresented	Promociones mostradas al contacto
promosRedeemed	Promociones canjeadas
answeredSurveyQuestions	Respuestas a encuestas
usersReferred	Usuarios referidos por este contacto
referralLinks	Detalles del enlace de referido
visitList	Historial de visitas/sesiones (dispositivo, UTM, geo, etc.)
textFields	Campos de texto personalizados capturados en flujos

Los campos pueden ser null o estar ausentes si no se recopilaron para ese contacto.

Valores de estado del contacto

Estado	Significado
"1"	Lead (incluye smart leads positivos de flujo de mensajes)
"2"	Cliente
"3"	Perdido
"4"	Convertido
null	Se trata como Lead en los recuentos

Formatos de objetos anidados

inviterUser

{
  "id": 123,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]"
}

rewardFlows / promos

{ "id": "...", "title": "Summer promo" }

referralLinks

{
  "key": "...",
  "campaignId": 1,
  "campaignName": "...",
  "flowVariantId": 1,
  "url": "https://...",
  "share": true
}

visitList — incluye browser, os, deviceType, country, region, city, campos UTM (utmSource, utmMedium, utmCampaign, etc.), referrer, landingPage, userAgent, ip.

answeredSurveyQuestions — incluye texto de pregunta/respuesta, traducciones, información de recompensa y marcas de tiempo.

textFields — campos personalizados de flujo: flowId, flowName, variantId, variantName, key, value.

Respuestas de error

Todos los errores devuelven JSON con un campo error. Algunos incluyen un hint.

Estado HTTP	Condición	Ejemplo de cuerpo
401	Falta la cabecera token	{ "error": "Missing token header" }
401	Clave inválida/revocada, o clave sk_/pk_ usada	{ "error": "Invalid or revoked token", "hint": "You can create a valid token from the Integration Dashboard." }
403	Clave válida pero sin declaración operatorId	{ "error": "Unauthorized" }
422	limit > 500	{ "error": "limit must not exceed 500" }
422	sortByField inválido	{ "error": "Invalid sortByField value" }
422	status inválido	{ "error": "Invalid status value" }
404	Ruta o método incorrecto	Not Found (texto plano)

Ejemplos de solicitudes

Básico — obtener hasta 100 contactos:

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact"

Obtener 25 contactos, ordenados por última conversación:

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact?limit=25&sortByField=lastConversationDate"

Obtener leads estándar (leads de formulario web y smart leads positivos de flujo de mensajes):

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact?status=1&sortByField=leadCapturedAt"

Ejemplo de respuesta truncada:

{
  "data": [
    {
      "id": "665a1b2c3d4e5f6789012345",
      "email": "[email protected]",
      "firstName": "Alex",
      "lastName": "Smith",
      "msisdn": "+4712345678",
      "status": "2",
      "operatorId": "10",
      "createdAt": "2025-03-15T10:22:00.000Z",
      "lastConversationDate": "2025-06-01T14:30:00.000Z",
      "visitList": [
        {
          "deviceType": "mobile",
          "browser": "Chrome",
          "country": "NO",
          "utmSource": "google"
        }
      ]
    }
  ],
  "leadsCount": 120,
  "customerCount": 45
}

Integración con Zapier

SMOC ofrece una aplicación de Zapier que utiliza este mismo endpoint. Flujo típico:

1. Obtén acceso mediante el enlace de invitación de Zapier (enlazado desde Console → Ajustes → Integraciones → Zapier).
2. Genera una clave API en Console.
3. En Zapier: Mis aplicaciones → Integraciones personalizadas → Añadir conexión y pega la clave cuando se solicite un token.
4. Crea un Zap con el disparador SMOC → Nuevo contacto.

El disparador de Zapier consulta este endpoint y trata los contactos devueltos como nuevos cuando aparecen. Nuevo contacto se basa en id. Los smart leads de conversión tardía (prospectos importados que luego obtienen leadCapturedAt) ahora reciben un id {contactId}__sl estable para que el Zap existente de Nuevo contacto pueda activarse una vez. contactId sigue siendo el id de Mongo para el mapeo CRM. Esto se aplica a cada empresa; solo las capturas a partir del 11-09-2026 se reescriben (temporal hasta que exista un disparador dedicado de Nuevo smart lead). Es preferible usar HubSpot Crear o actualizar contacto por correo electrónico para evitar duplicados si el prospecto ya fue sincronizado. Consulta la guía de Zapier para la configuración paso a paso.

Limitaciones y notas de diseño

• Las claves de cliente son solo lectura — mongocontact no escribe. Las herramientas de mutación REST v2 son solo para superadministradores.
• Sin paginación por offset/cursores — usa limit (máx. 500). Para sincronizar todos los contactos, ordena de forma consistente y rastrea los IDs vistos en el cliente, o usa el modelo de sondeo de Zapier.
• Delimitación automática — la clave API determina la empresa; no hay parámetro de sobrescritura multiempresa.
• Campos limitados por proyección — solo se devuelven los campos listados arriba; los campos internos de la base de datos se eliminan.
• Compatibilidad heredada — la ruta del endpoint y el alias de orden companyUsers.lastConversationDate existen para mantener la compatibilidad con la API original y la app de Zapier.

Relacionado: MCP (clientes de IA)

El mismo worker de API también expone MCP en https://api.smoc.ai/mcp y REST v2 en POST /api/v2/{toolName} con herramientas de contacto más avanzadas (contacts_search, contacts_get, contacts_get_stats, etc.). Consulta la guía de MCP y la referencia de REST v2.

Para una visión general de producto de todas las rutas de integración, consulta smoc.ai/integraciones.

Referencia rápida

Elemento	Valor
Endpoint	GET /api/company/mongocontact
Cabecera de autenticación	token: <api-key>
Tipo de contenido	application/json
Tamaño máximo de página	500
Tamaño de página predeterminado	100
Delimitación de empresa	Por clave API (declaración operatorId)
Creación de clave	Console → Ajustes → Integraciones → API

Ver también

• Referencia de la API REST v2 — cada llamada POST /api/v2/{toolName}
• Conectar SMOC con la API REST
• API Pública de Contactos
• MCP para Claude, Cursor y VS Code