{"openapi":"3.1.0","info":{"title":"API de YaCRM","version":"1","description":"Lee pedidos, cotizaciones, productos, clientes, chats y mensajes, y maneja etiquetas y automatizaciones de un negocio. Autenticación: llave de conexión (Bearer yak_…) creada en Perfil → Conexión MCP / API."},"servers":[{"url":"https://yacrm.pro/api/public/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Llave de conexión. Permisos: orders:read, quotes:read, catalog:read, catalog:write, customers:read, conversations:read, labels:read, labels:write, automations:read, automations:write."}},"schemas":{"orders":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador único del pedido."},"order_number":{"type":["string","null"],"description":"Número visible del pedido en YaCRM."},"status":{"type":"string","description":"Estado general del pedido."},"payment_status":{"type":"string","description":"Estado del pago registrado por la tienda."},"fulfillment_status":{"type":"string","description":"Estado de preparación o despacho."},"currency":{"type":"string","description":"Moneda del total (por ejemplo USD)."},"total":{"type":"number","description":"Total del pedido en su moneda."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación (ISO 8601, UTC)."}}},"quotes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador único de la cotización."},"number_seq":{"type":"integer","description":"Número correlativo de la cotización."},"status":{"type":"string","description":"Estado de la cotización."},"currency":{"type":"string","description":"Moneda de la cotización."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación (ISO 8601, UTC)."}}},"products":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador único del producto."},"sku":{"type":"string","description":"Código interno (SKU) de la tienda."},"name":{"type":"string","description":"Nombre del producto."},"brand":{"type":["string","null"],"description":"Marca."},"status":{"type":"string","description":"Estado del producto en el catálogo."},"base_price":{"type":["number","null"],"description":"Precio base de catálogo."},"currency":{"type":["string","null"],"description":"Moneda del precio."},"updated_at":{"type":"string","format":"date-time","description":"Última modificación (ISO 8601, UTC)."}}},"customers":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador único del cliente."},"first_seen_at":{"type":"string","format":"date-time","description":"Primera vez que escribió al negocio."},"last_interaction_at":{"type":["string","null"],"format":"date-time","description":"Última interacción registrada."}}},"conversations":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador único del chat."},"channel":{"type":"string","description":"Canal: whatsapp, instagram, ml_question, ml_message o ml_postsale."},"channel_id":{"type":["string","null"],"format":"uuid","description":"Conexión exacta (número o cuenta) por la que llegó; null en chats antiguos que no la guardaron."},"status":{"type":"string","description":"Estado del chat: open, pending, closed o escalated."},"customer_id":{"type":["string","null"],"format":"uuid","description":"Cliente del chat (ver Clientes)."},"assigned_user_id":{"type":["string","null"],"format":"uuid","description":"Persona del equipo responsable del chat."},"unread_count":{"type":"integer","description":"Mensajes sin leer."},"last_message_at":{"type":["string","null"],"format":"date-time","description":"Último mensaje en cualquier sentido."},"last_inbound_at":{"type":["string","null"],"format":"date-time","description":"Último mensaje del cliente."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación (ISO 8601, UTC)."},"updated_at":{"type":"string","format":"date-time","description":"Última modificación (ISO 8601, UTC)."}}},"messages":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador único del mensaje."},"conversation_id":{"type":"string","format":"uuid","description":"Chat al que pertenece (ver Chats)."},"channel":{"type":"string","description":"Canal del mensaje."},"direction":{"type":"string","description":"inbound (del cliente) u outbound (de la tienda)."},"role":{"type":"string","description":"Quién lo escribió: customer, agent (equipo), ai (Sofi) o system."},"kind":{"type":"string","description":"Tipo: text, image, audio, video, document, location…"},"body":{"type":["string","null"],"description":"Texto del mensaje (los archivos no se incluyen)."},"status":{"type":"string","description":"Estado de envío: pending, sent, delivered, read o failed."},"created_at":{"type":"string","format":"date-time","description":"Fecha de registro (ISO 8601, UTC)."}}},"labels":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador único de la etiqueta."},"key":{"type":"string","description":"Clave interna estable (las predeterminadas empiezan por lead_)."},"label":{"type":"string","description":"Nombre visible."},"color_token":{"type":"string","description":"Color de la etiqueta."},"ai_mode":{"type":"string","description":"Quién la pone: manual (equipo), auto (Sofi) o rules (activadores)."},"is_active":{"type":"boolean","description":"Si está en uso."},"channels":{"type":"array","items":{"type":"string"},"description":"Canales donde se usa."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación (ISO 8601, UTC)."}}},"conversation_labels":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador de la asignación."},"conversation_id":{"type":"string","format":"uuid","description":"Chat etiquetado."},"tag_definition_id":{"type":"string","format":"uuid","description":"Etiqueta puesta (ver Etiquetas)."},"source":{"type":"string","description":"Quién la puso: human, ai o rule."},"created_at":{"type":"string","format":"date-time","description":"Cuándo se puso (ISO 8601, UTC)."}}},"automations":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador del activador."},"name":{"type":"string","description":"Nombre corto."},"trigger_kind":{"type":"string","description":"Disparador (ver Comandos → Automatizaciones)."},"idle_minutes":{"type":["integer","null"],"description":"Minutos de espera para disparadores de tiempo."},"from_label_id":{"type":["string","null"],"format":"uuid","description":"Etiqueta que debe tener el chat."},"add_label_id":{"type":["string","null"],"format":"uuid","description":"Etiqueta que pone."},"remove_from_label":{"type":"boolean","description":"Si quita la etiqueta de origen."},"override_manual":{"type":"boolean","description":"Si actúa aunque la etiqueta la haya puesto una persona."},"enabled":{"type":"boolean","description":"Si está encendido."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación (ISO 8601, UTC)."}}},"channels":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"ID de la conexión (channel_id)."},"provider":{"type":"string","description":"waha (WhatsApp), instagram o meli (Mercado Libre)."},"display_name":{"type":["string","null"],"description":"Nombre que le diste a la conexión."},"status":{"type":"string","description":"pending, connected, expired, revoked o error."},"connected_at":{"type":["string","null"],"format":"date-time","description":"Cuándo se conectó."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación (ISO 8601, UTC)."}}},"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"string","enum":["missing_or_invalid_token","api_key_revoked","api_key_expired","api_key_required","invalid_business_id","business_scope_mismatch","business_forbidden","api_actor_inactive","scope_forbidden","module_forbidden","rate_limited","invalid_query","invalid_limit","invalid_cursor","idempotency_key_required","invalid_idempotency_key","idempotency_conflict","invalid_body","command_rejected","not_found","method_not_allowed","business_scope_unavailable","permission_unavailable","resource_read_unavailable","command_unavailable","read_unavailable"]},"request_id":{"type":"string"},"detail":{"type":"string"},"reason":{"type":"string"}}}},"responses":{"Error":{"description":"Error con formato fijo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/businesses/{business_id}/orders":{"get":{"operationId":"list_orders","summary":"Pedidos","description":"Lista los pedidos del negocio, del más reciente al más antiguo.","tags":["Pedidos"],"security":[{"bearer":["orders:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/orders"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/quotes":{"get":{"operationId":"list_quotes","summary":"Cotizaciones","description":"Lista las cotizaciones del negocio, de la más reciente a la más antigua.","tags":["Cotizaciones"],"security":[{"bearer":["quotes:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/quotes"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/catalog/products":{"get":{"operationId":"list_products","summary":"Productos","description":"Lista el catálogo, empezando por los productos modificados más recientemente.","tags":["Productos"],"security":[{"bearer":["catalog:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"updated_after","in":"query","description":"Solo filas con updated_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/products"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/customers":{"get":{"operationId":"list_customers","summary":"Clientes","description":"Lista los clientes del negocio. No incluye nombres ni datos de contacto.","tags":["Clientes"],"security":[{"bearer":["customers:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/customers"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/conversations":{"get":{"operationId":"list_conversations","summary":"Chats","description":"Lista los chats de todos los canales, empezando por los que cambiaron más recientemente. No incluye nombre ni contacto.","tags":["Chats"],"security":[{"bearer":["conversations:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"updated_after","in":"query","description":"Solo filas con updated_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}},{"name":"channel","in":"query","description":"Solo chats de ese canal.","schema":{"type":"string","enum":["whatsapp","instagram","ml_question","ml_message","ml_postsale"]}},{"name":"status","in":"query","description":"Solo chats en ese estado.","schema":{"type":"string","enum":["open","pending","closed","escalated"]}},{"name":"customer_id","in":"query","description":"Solo chats de ese cliente.","schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"query","description":"Solo chats de esa conexión (ver Canales conectados).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/conversations"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/messages":{"get":{"operationId":"list_messages","summary":"Mensajes","description":"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).","tags":["Mensajes"],"security":[{"bearer":["conversations:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}},{"name":"conversation_id","in":"query","description":"Solo mensajes de ese chat.","schema":{"type":"string","format":"uuid"}},{"name":"channel","in":"query","description":"Solo mensajes de ese canal.","schema":{"type":"string","enum":["whatsapp","instagram","ml_question","ml_message","ml_postsale"]}},{"name":"direction","in":"query","description":"inbound = del cliente; outbound = de la tienda.","schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"role","in":"query","description":"Quién lo escribió.","schema":{"type":"string","enum":["customer","agent","ai","system"]}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/messages"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/labels":{"get":{"operationId":"list_labels","summary":"Etiquetas","description":"Lista las etiquetas de venta de la tienda (las del tablero), de la más nueva a la más antigua.","tags":["Etiquetas"],"security":[{"bearer":["labels:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/labels"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"label_save_post","summary":"Crear etiqueta","description":"Crea una etiqueta de venta. Si envías «activators» o «removers», la llave también necesita automations:write.","tags":["Comandos"],"security":[{"bearer":["labels:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"label":"Mayorista","color":"info","mode":"manual","instructions":"","isActive":true,"channels":["whatsapp","instagram"]}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/conversation-labels":{"get":{"operationId":"list_conversation_labels","summary":"Etiquetas puestas en chats","description":"Lista qué etiqueta tiene cada chat, de la puesta más reciente a la más antigua.","tags":["Etiquetas puestas en chats"],"security":[{"bearer":["labels:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}},{"name":"conversation_id","in":"query","description":"Solo etiquetas de ese chat.","schema":{"type":"string","format":"uuid"}},{"name":"tag_definition_id","in":"query","description":"Solo chats con esa etiqueta.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/conversation_labels"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/automations":{"get":{"operationId":"list_automations","summary":"Automatizaciones","description":"Lista los activadores que ponen o quitan etiquetas solos.","tags":["Automatizaciones"],"security":[{"bearer":["automations:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/automations"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"automation_save_post","summary":"Crear automatización","description":"Crea un activador que pone una etiqueta sola. Mismas reglas que la pantalla (máximo 20, sin círculos, nunca «Pagó»).","tags":["Comandos"],"security":[{"bearer":["automations:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/channels":{"get":{"operationId":"list_channels","summary":"Canales conectados","description":"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.","tags":["Canales conectados"],"security":[{"bearer":["conversations:read"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"next_cursor o sync_cursor de la respuesta anterior de la misma consulta.","schema":{"type":"string"}},{"name":"order","in":"query","description":"desc (por defecto) o asc. asc = sincronización sin huecos.","schema":{"type":"string","enum":["desc","asc"]}},{"name":"created_after","in":"query","description":"Solo filas con created_at posterior a esta fecha (ISO 8601 con zona).","schema":{"type":"string","format":"date-time"}},{"name":"provider","in":"query","description":"waha = WhatsApp, instagram = Instagram, meli = Mercado Libre.","schema":{"type":"string","enum":["waha","instagram","meli"]}},{"name":"status","in":"query","description":"Estado de la conexión.","schema":{"type":"string","enum":["pending","connected","expired","revoked","error"]}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","sync_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/channels"}},"next_cursor":{"type":["string","null"],"description":"Hay más páginas ahora mismo."},"sync_cursor":{"type":["string","null"],"description":"Guárdalo y envíalo como cursor en la próxima consulta."}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/labels/{label_id}":{"put":{"operationId":"label_save_put","summary":"Editar etiqueta","description":"Reemplaza nombre, color, quién la pone, instrucciones, estado y canales. Sin «activators»/«removers» no se tocan sus automatizaciones.","tags":["Comandos"],"security":[{"bearer":["labels:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"label_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"label":"Mayorista VIP","color":"info","mode":"manual","instructions":"","isActive":true,"channels":["whatsapp"]}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/conversations/{conversation_id}/labels":{"post":{"operationId":"conversation_label_set_post","summary":"Poner etiqueta en un chat","description":"Pone la etiqueta como si la pusiera el dueño de la conexión. «Pagó» no se puede poner: solo la pone un pago acreditado.","tags":["Comandos"],"security":[{"bearer":["labels:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"label_id":"3f6c1e2a-8b1d-4c5e-9a0f-1b2c3d4e5f60"}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/conversations/{conversation_id}/labels/{label_id}":{"delete":{"operationId":"conversation_label_set_delete","summary":"Quitar etiqueta de un chat","description":"Quita la etiqueta del chat. «Pagó» no se puede quitar por la API.","tags":["Comandos"],"security":[{"bearer":["labels:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"label_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/automations/{automation_id}":{"put":{"operationId":"automation_save_put","summary":"Editar automatización","description":"Reemplaza todos los campos del activador.","tags":["Comandos"],"security":[{"bearer":["automations:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"automation_delete_delete","summary":"Borrar automatización","description":"Borra el activador.","tags":["Comandos"],"security":[{"bearer":["automations:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/catalog/sources/{source_id}/products":{"post":{"operationId":"catalog_upsert_post","summary":"Enviar productos desde tu ERP","description":"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).","tags":["Comandos"],"security":[{"bearer":["catalog:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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"}]}]}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/catalog/sources/{source_id}/photo-uploads":{"post":{"operationId":"catalog_photo_upload_post","summary":"Pedir permiso para subir fotos","description":"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.","tags":["Comandos"],"security":[{"bearer":["catalog:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"files":[{"type":"jpg"},{"type":"png"}]}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/businesses/{business_id}/catalog/sources/{source_id}/stock":{"post":{"operationId":"catalog_stock_set_post","summary":"Actualizar existencia y precio desde tu ERP","description":"Liviano, hasta 50 por llamada: solo stock y price de productos ya enlazados (por external_id). Lo no enlazado vuelve como error not_linked.","tags":["Comandos"],"security":[{"bearer":["catalog:write"]}],"parameters":[{"name":"business_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación; repetirla con el mismo cuerpo devuelve la misma respuesta.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,200}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"external_id":"ERP-1001","stock":9,"price":24.9}]}}}},"responses":{"200":{"description":"Aplicado (o repetición de uno ya aplicado).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"replayed":{"type":"boolean"}}}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}}}}