API de YaCRM

Inicio rápido

1. Entra a YaCRM → Perfil → Conexión MCP / API.
2. Copia el ID del negocio (botón del ojito) y crea una conexión con los permisos que necesitas. Copia la llave: solo se muestra una vez.
3. Reemplaza $BUSINESS_ID y $YACRM_TOKEN (la llave) en el ejemplo y ejecútalo.
4. Recibirás data (la lista) y next_cursor (la página siguiente, o null).

Paginación

Parámetros permitidos (cada uno una sola vez):

• limit: entero de 1 a 100. Por defecto 50.
• cursor: el valor next_cursor (o sync_cursor) de la respuesta anterior.
• order: desc (por defecto) o asc.
• created_after o updated_after (según el orden del recurso): fecha ISO 8601 con zona, por ejemplo 2026-11-12T00:00:00Z.
• Filtros propios de cada recurso (ver su tabla). Cualquier otro parámetro responde 422 invalid_query.

Los resultados vienen del más reciente al más antiguo. Repite con el nuevo next_cursor hasta que sea null. El cursor solo sirve para el mismo negocio, recurso, orden y filtros; no lo construyas a mano.

Sincronizar sin huecos (n8n)

Para recibir todo lo nuevo (mensajes, chats que cambiaron, etiquetas puestas) sin perder ni repetir nada:

1. Consulta con order=asc y, la primera vez, created_after con la fecha desde la que quieres empezar.
2. Cada respuesta trae sync_cursor. Guárdalo (en n8n: $getWorkflowStaticData('global')).
3. En la próxima consulta envía los mismos parámetros y cursor=<sync_cursor>. Si next_cursor no es null, pide la página siguiente enseguida.

En orden ascendente, cada fila aparece 30 segundos después de creada o cambiada. Así una escritura que aún no termina no queda saltada.

Pedidos

GET/api/public/v1/businesses/{business_id}/orders

Lista los pedidos del negocio, del más reciente al más antiguo.

Campos de cada elemento

Permiso de la llave: orders:read (módulo orders). Orden: created_at descendente.

Cotizaciones

GET/api/public/v1/businesses/{business_id}/quotes

Lista las cotizaciones del negocio, de la más reciente a la más antigua.

Campos de cada elemento

Permiso de la llave: quotes:read (módulo quotes). Orden: created_at descendente.

Productos

GET/api/public/v1/businesses/{business_id}/catalog/products

Lista el catálogo, empezando por los productos modificados más recientemente.

Campos de cada elemento

Permiso de la llave: catalog:read (módulo catalog). Orden: updated_at descendente.

Clientes

GET/api/public/v1/businesses/{business_id}/customers

Lista los clientes del negocio. No incluye nombres ni datos de contacto.

Campos de cada elemento

Permiso de la llave: customers:read (módulo customers). Orden: created_at descendente.

Chats

GET/api/public/v1/businesses/{business_id}/conversations

Lista los chats de todos los canales, empezando por los que cambiaron más recientemente. No incluye nombre ni contacto.

Campos de cada elemento

Filtros

• channel — Solo chats de ese canal. Valores: whatsapp, instagram, ml_question, ml_message, ml_postsale.
• status — Solo chats en ese estado. Valores: open, pending, closed, escalated.
• customer_id — Solo chats de ese cliente. (UUID).
• channel_id — Solo chats de esa conexión (ver Canales conectados). (UUID).

Permiso de la llave: conversations:read (módulo inbox). Orden: updated_at descendente.

Mensajes

GET/api/public/v1/businesses/{business_id}/messages

Lista los mensajes de todos los canales. Para recibir los nuevos sin perder ninguno usa order=asc y guarda el sync_cursor de cada respuesta (ver Sincronizar).

Campos de cada elemento

Filtros

• conversation_id — Solo mensajes de ese chat. (UUID).
• channel — Solo mensajes de ese canal. Valores: whatsapp, instagram, ml_question, ml_message, ml_postsale.
• direction — inbound = del cliente; outbound = de la tienda. Valores: inbound, outbound.
• role — Quién lo escribió. Valores: customer, agent, ai, system.

Permiso de la llave: conversations:read (módulo inbox). Orden: created_at descendente.

Etiquetas

GET/api/public/v1/businesses/{business_id}/labels

Lista las etiquetas de venta de la tienda (las del tablero), de la más nueva a la más antigua.

Campos de cada elemento

Permiso de la llave: labels:read (módulo inbox). Orden: created_at descendente.

Etiquetas puestas en chats

GET/api/public/v1/businesses/{business_id}/conversation-labels

Lista qué etiqueta tiene cada chat, de la puesta más reciente a la más antigua.

Campos de cada elemento

Filtros

• conversation_id — Solo etiquetas de ese chat. (UUID).
• tag_definition_id — Solo chats con esa etiqueta. (UUID).

Permiso de la llave: labels:read (módulo inbox). Orden: created_at descendente.

Automatizaciones

GET/api/public/v1/businesses/{business_id}/automations

Lista los activadores que ponen o quitan etiquetas solos.

Campos de cada elemento

Permiso de la llave: automations:read (módulo inbox). Orden: created_at descendente.

Canales conectados

GET/api/public/v1/businesses/{business_id}/channels

Cada número de WhatsApp, cuenta de Instagram o cuenta de Mercado Libre conectada, con su ID fijo. Ese ID es el channel_id de chats y avisos. Sin llaves ni tokens.

Campos de cada elemento

Filtros

• provider — waha = WhatsApp, instagram = Instagram, meli = Mercado Libre. Valores: waha, instagram, meli.
• status — Estado de la conexión. Valores: pending, connected, expired, revoked, error.

Permiso de la llave: conversations:read (módulo inbox). Orden: created_at descendente.

Comandos

Los comandos exigen una llave de conexión con el permiso indicado y el encabezado Idempotency-Key: una clave única por operación (8 a 200 caracteres: letras, números, . _ : -).

• Si se corta la red, reintenta con la misma clave y el mismo cuerpo: no se repite el cambio y recibes la misma respuesta con "replayed": true.
• La misma clave con otro cuerpo responde 409 idempotency_conflict. Un comando rechazado no guarda la clave: corrige y reintenta.
• Respuesta correcta: 200 con { data, replayed }. Una regla de la tienda rechaza con 422 command_rejected y el motivo en reason.
• «Pagó» nunca se pone ni se quita por la API: solo la pone un pago acreditado.

{
  "label": "Mayorista",
  "color": "info",
  "mode": "manual",
  "instructions": "",
  "isActive": true,
  "channels": [
    "whatsapp",
    "instagram"
  ]
}

{
  "label": "Mayorista VIP",
  "color": "info",
  "mode": "manual",
  "instructions": "",
  "isActive": true,
  "channels": [
    "whatsapp"
  ]
}

{
  "label_id": "3f6c1e2a-8b1d-4c5e-9a0f-1b2c3d4e5f60"
}

{
  "name": "Sin respuesta 1 día",
  "trigger": "customer_idle",
  "idleMinutes": 1440,
  "fromLabelId": "8a2d4c6e-1f3b-4d5a-9c7e-2b4d6f8a0c1e",
  "addLabelId": "3f6c1e2a-8b1d-4c5e-9a0f-1b2c3d4e5f60",
  "removeFromLabel": true,
  "overrideManual": false,
  "enabled": true
}

{
  "name": "Sin respuesta 2 días",
  "trigger": "customer_idle",
  "idleMinutes": 2880,
  "fromLabelId": "8a2d4c6e-1f3b-4d5a-9c7e-2b4d6f8a0c1e",
  "addLabelId": "3f6c1e2a-8b1d-4c5e-9a0f-1b2c3d4e5f60",
  "removeFromLabel": true,
  "overrideManual": false,
  "enabled": true
}

{
  "items": [
    {
      "external_id": "ERP-1001",
      "sku": "PF-COR-0812",
      "name": "Pastilla de freno delantera Corolla 2008-2013",
      "description": "Juego de 4",
      "brand": "Bosch",
      "price": 25.5,
      "currency": "USD",
      "stock": 12,
      "status": "active",
      "photos": [
        {
          "path": "5d2e8a1c-3b4f-4a6d-8e9f-0a1b2c3d4e5f/7c9e1a3b-5d6f-4b8a-9c0d-1e2f3a4b5c6d/0b6f3c1e-2a4d-4e8f-9b1c-3d5e7f9a1b2c.jpg"
        }
      ]
    }
  ]
}

{
  "files": [
    {
      "type": "jpg"
    },
    {
      "type": "png"
    }
  ]
}

{
  "items": [
    {
      "external_id": "ERP-1001",
      "stock": 9,
      "price": 24.9
    }
  ]
}

Colores: info, warning, success, danger, muted, new, followup. Quién pone la etiqueta (mode): manual, auto (Sofi, con instrucciones de al menos una frase) o rules (activadores). Disparadores: first_inbound, inbound_unlabeled, customer_idle, customer_replied, order_created, order_paid, quote_created, quote_accepted, ml_purchase, case_opened, assigned, ai_paused, label_age.

Avisos al instante (webhooks)

En vez de preguntar cada pocos minutos, YaCRM llama a tu n8n en cuanto pasa algo. Lo creas en Perfil → Avisos al instante o pidiéndoselo al asistente por MCP.

• Eventos: message.received, message.sent, conversation_label.added, conversation_label.removed, order.created, order.updated (cambió estado, pago o despacho; trae changes con antes y después) y customer.created. El filtro por canal y conexión aplica a mensajes y etiquetas; pedidos y clientes llegan de todos los canales. Pedidos y clientes traen los mismos datos que la API, sin nombre ni contacto del comprador.
• «Mensaje enviado» significa registrado en YaCRM; el estado (pendiente, enviado, entregado) viaja en data.status.
• Encabezados: webhook-id (único: úsalo para no procesar dos veces), webhook-timestamp y webhook-signature (HMAC-SHA256, formato Standard Webhooks).
• Responde 2xx en menos de 10 s. Si falla se reintenta con espera creciente. Con 5 fallos seguidos se frena unos minutos; si además lleva 24 horas sin una entrega buena, se pausa solo hasta que lo reactives.
• Prueba en 60 segundos: crea un nodo Webhook (POST) en n8n, pega su URL de producción en el aviso y pulsa Probar.

// n8n · nodo Webhook con la opción «Raw Body» activada (la firma se calcula sobre el texto exacto)
// n8n · nodo Code siguiente:
const crypto = require('crypto');
const secret = 'whsec_…'; // la firma que te mostró YaCRM (guárdala como credencial)
const id = $json.headers['webhook-id'];
const ts = $json.headers['webhook-timestamp'];
const body = Buffer.from($binary.data.data, 'base64').toString('utf8');
const key = Buffer.from(secret.slice(6), 'base64');
const expected = 'v1,' + crypto.createHmac('sha256', key).update(`${id}.${ts}.${body}`).digest('base64');
const ok = $json.headers['webhook-signature'].split(' ').includes(expected);
if (!ok) throw new Error('Firma inválida');
return [{ json: JSON.parse(body) }];

Productos desde tu ERP

Tu ERP sigue siendo el dueño del catálogo; n8n traduce sus campos y YaCRM los recibe como una fuente con nombre propio, igual que llegan los de Mercado Libre.

1. Crea la fuente en Perfil → Fuentes de catálogo (ERP) y copia su ID.
2. Crea una conexión API con el permiso catalog:write.
3. En n8n, lee tu ERP, arma lotes de hasta 50 y envíalos a los comandos de abajo con un Idempotency-Key distinto por lote.

• Enviar productos desde tu ERP (catalog.upsert): Hasta 50 por llamada. Crea o actualiza por external_id (el ID del producto en tu ERP) y solo escribe lo que cambió. Si el SKU ya existe en otra ficha no crea nada: queda en «Posibles duplicados» hasta que la tienda decida. Responde fila por fila: created, updated, unchanged, pending_merge o error. Rechaza todo si Mercado Libre está conectado (una sola fuente manda la existencia).
• Pedir permiso para subir fotos (catalog.photo_upload): Hasta 10 por llamada (jpg, png o webp). Devuelve por foto un «path» y un «upload_url» de un solo uso (vence en 2 horas): sube los bytes con PUT a upload_url (Content-Type de la imagen, máx. 5 MB) y luego envía el path en «photos» de catalog.upsert. Las fotos no pasan por YaCRM. En catalog.upsert, «photos» reemplaza solo las fotos que puso tu ERP (la lista vacía las quita); las que subió la tienda no se tocan. En productos publicados en Mercado Libre se ignoran.
• Actualizar existencia y precio desde tu ERP (catalog.stock_set): Liviano, hasta 50 por llamada: solo stock y price de productos ya enlazados (por external_id). Lo no enlazado vuelve como error not_linked.
• Fotos: pide permiso con catalog.photo_upload, sube cada foto con PUT a su upload_url (jpg, png o webp, hasta 5 MB) y envía los path en photos de catalog.upsert. Las fotos van directo de n8n al almacén de YaCRM; YaCRM nunca descarga enlaces de terceros.
• Si un SKU ya existe en tu catálogo, no se crea ni se pisa: queda en Inventario → Posibles duplicados para que elijas «Unirlos» o «Son distintos».
• Con Mercado Libre conectado, el ERP escribe solo si cada cuenta de Mercado Libre tiene encendido «Descontar stock local en Mercado Libre» en Canales; si no, responde catalog_source_conflict_meli.
• En un producto publicado en Mercado Libre el ERP manda solo la existencia: título, precio y estado siguen siendo los de Mercado Libre, y YaCRM sube la existencia nueva a Mercado Libre. Productos con varias variaciones en Mercado Libre se rechazan (erp_ml_variations_unsupported).
• Las ventas de Mercado Libre no se restan solas en tu ERP: escucha el aviso order.created en n8n, descuenta en el ERP y vuelve a mandar la existencia con catalog.stock_set.