Conectar SMOC con la REST API

Guía sencilla que muestra cómo conectarse a la REST API de SMOC desde tu propio código, trabajos de sincronización o flujos de CRM. Las claves de cliente están asociadas a la empresa y son de solo lectura por defecto. Las claves con permisos de escritura pueden realizar escrituras limitadas, incluyendo el envío desde la bandeja de entrada; no pueden editar gráficos de flujos, publicar flujos ni iniciar campañas de prospección en LinkedIn. Las claves de superusuario pueden guardar borradores de flujos y temas en las mismas llamadas POST /api/v2/{toolName}; la publicación sigue requiriendo intervención humana en Studio o Console. Las herramientas de dominio están en REST v2 como POST /api/v2/{toolName} (los mismos controladores que MCP). Lista completa de llamadas: Referencia de la API REST v2. GET /api/company/mongocontact es para Zapier.

Consigue tu clave API

1. Ve a Ajustes → Integraciones → API en SMOC Console.
2. Opcionalmente, ponle un nombre a la clave y una caducidad (7, 30 o 90 días). Deja la caducidad en Sin caducidad si no quieres que expire.
3. Genera la clave y cópiala inmediatamente — solo se muestra una vez, así que guárdala en un lugar seguro.

Tu clave está vinculada a tu empresa. Cada solicitud realizada con ella está automáticamente restringida a tus datos. Generar una nueva clave no revoca las claves existentes. Las claves emitidas se muestran en la misma página — revoca las que no uses allí. La página de MCP usa los mismos controles — consulta la captura de pantalla en la guía de MCP.

URL base

URL base: https://api.smoc.ai

Endpoint completo de contactos:

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

Autenticación

Contactos heredados: envía la clave en una cabecera HTTP personalizada llamada token. REST v2 acepta Authorization: Bearer o token.

GET /api/company/mongocontact HTTP/1.1
Host: api.smoc.ai
token: YOUR_SMOC_API_KEY

No uses claves secretas de Clerk (sk_…) ni claves publicables (pk_…).

Qué funciones existen

REST v2 — POST /api/v2/{toolName}

Refleja las herramientas de dominio de MCP (contacts_search, cpcs_overview, inbox_threads_list y el resto). OpenAPI: GET /api/v2 o GET /api/v2/openapi.json. Consulta la referencia REST v2.

Listar contactos de la empresa — GET /api/company/mongocontact (Zapier / compatible)

Devuelve una página de contactos de la empresa asociada a la clave, además de recuentos agregados.

Qué devuelve

• Registros de contacto: nombre, correo electrónico, teléfono, estado, dirección, fecha de la última conversación, historial de visitas/UTM, respuestas a encuestas, campos de texto personalizados, datos de referidos y promociones cuando se recopilan. Los leads inteligentes positivos de flujo de mensajes son leads estándar (status: "1") y también incluyen leadSentiment, leadCapturedAt y tags cuando están presentes.
• leadsCount — contactos con estado lead (incluido sin establecer)
• customerCount — contactos con estado cliente

Los recuentos cubren todos los contactos de la empresa, no solo la página actual.

Parámetros de consulta

Parámetro	Predeterminado	Descripción
limit	100	Máximo de contactos a devolver (1–500)
sortByField	(ninguno)	Orden descendente por createdAt, updatedAt, lastConversationDate o leadCapturedAt
status	(ninguno)	Filtrar por estado de contacto. status=1 es la encuesta estándar de leads e incluye leads inteligentes positivos de flujo de mensajes

Valores de estado de contacto: "1" lead, "2" cliente, "3" perdido, "4" convertido.

Las claves de cliente no pueden crear, actualizar ni eliminar contactos. No hay paginación por cursor en mongocontact — usa limit y lleva el seguimiento de los IDs vistos en el cliente, o usa el sondeo de Zapier. La búsqueda avanzada es POST /api/v2/contacts_search.

Las estructuras de respuesta a nivel de campo están en la Referencia pública de la API de contactos.

Ejemplo de solicitud

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

Qué no está en la API de cliente

Las claves con permisos de escritura aún no pueden publicar un flujo, activar/desactivar en vivo (flowcharts_set_active), eliminar registros ni iniciar una campaña de prospección en LinkedIn. El envío desde la bandeja de entrada (send) es opcional en una clave con permisos de escritura (inbox_threads_send, solo texto, requiere idempotencyKey). Usa SMOC MCP desde Claude, Cursor o VS Code para las mismas herramientas sobre MCP.

Notas de seguridad

• La clave se muestra una sola vez al crearla — guárdala en un gestor de contraseñas o variable de entorno.
• Nunca subas la clave a un repositorio Git.
• Las claves de cliente están restringidas a los datos de tu empresa. Las claves por defecto son de solo lectura; las escrituras, incluido el envío desde la bandeja de entrada, son opcionales.
• Revoca las claves no utilizadas desde la lista de claves emitidas en Ajustes → Integraciones → API.

Resolución de problemas

• 401 Falta la cabecera del token: envía token: <key>, no Authorization: Bearer.
• 401 Token inválido o revocado: confirma que la clave es correcta y no ha sido revocada.
• 422 el límite no debe superar 500: reduce el parámetro de consulta limit.
• 422 Valor de estado inválido: usa 1, 2, 3 o 4.

Ver también

• Referencia de la API REST v2 — todas las llamadas POST /api/v2/{toolName}
• Conectar SMOC con la REST API
• API pública de contactos
• MCP para Claude, Cursor y VS Code