Última actualización: 13 de septiembre de 2026
Un negocio que usa Lokonvio puede conectar su propio sistema —su ERP, su web, o un asistente de IA— para consultar su embudo de WhatsApp: conversaciones, pedidos y estado del bot. La llave se genera desde el panel, en Acceso por API, y cada llave solo ve los datos de su empresa.
Base: https://lokonvio.com/api/v1. Se autentica con un header, en cualquiera de las dos formas:
X-API-Key: lk_live_xxxxxxxxxxxx Authorization: Bearer lk_live_xxxxxxxxxxxx
Cada llave nace con un alcance, que se escoge al generarla y no se puede ampliar después — si hace falta más, se genera otra y la anterior deja de servir:
403.Límite: 120 peticiones por minuto por empresa. Al pasarse responde 429 con la cabecera Retry-After.
La llave se guarda cifrada y se muestra una sola vez, al generarla. Si se pierde, se genera otra: no hay forma de recuperarla, ni siquiera para nosotros.
Todas las fechas van en ISO 8601 con zona (UTC), y cada respuesta lo repite en el campo timezone — quien lee un informe no abre la documentación.
since / until — cualquier fecha ISO. Filtran por fecha de creación.limit — máximo 200, por defecto 50.cursor — el next_cursor de la página anterior.La paginación va por cursor y no por offset. No es un detalle de gusto: con offset, una conversación nueva mientras se recorre el listado corre todas las páginas y hace que una fila se repita o se pierda. En un informe de campaña eso es un lead fantasma o un lead que nunca se contó.
Cuando next_cursor viene en null, no hay más páginas.
GET https://lokonvio.com/api/v1/conversations?source=meta_ads&limit=20
GET https://lokonvio.com/api/v1/conversations/{id}?messages=30Filtros propios: source y status. Cada conversación trae:
phone — el número del cliente.source — meta_ads, organic u other.ad — cuando vino de un anuncio: ad_id, ctwa_clid, headline y clicked_at. El ctwa_clid es lo que permite cruzar estas conversaciones contra el reporte de Meta Ads.status — new, in_progress, closed_won o closed_lost.assigned_to — bot o human.orders_count — cuántos pedidos salieron de esa conversación.El detalle (/conversations/{id}) agrega los últimos mensajes, y cada uno dice quién habló: customer, bot o agent —una persona del equipo, ya sea desde el panel o desde el celular del dueño—.
Esto se dice aquí y no en una nota al pie porque quien no lo sabe los trata como hechos y saca conclusiones que no respaldamos:
status se deriva. No hay nadie marcando conversaciones. Es closed_won si tiene un pedido pagado —el único estado que es un hecho—; closed_lost si nunca hubo pedido y lleva más de 7 días sin actividad; new si el cliente escribió y nadie contestó todavía; y in_progress el resto. Una venta cerrada hace un mes sigue siendo closed_won aunque la conversación lleve un mes quieta.source es lo que Meta nos dijo, no lo que comprobamos. Vale meta_ads cuando Meta mandó el referral del anuncio en el primer mensaje. Lo demás sale como organic: no porque se haya verificado que llegó solo, sino porque nadie nos señaló un anuncio. Alguien que vio la pauta y tecleó el número a mano aparece como organic.La atribución que se devuelve hoy es de primer toque: el anuncio que trajo al cliente, que no se pisa si vuelve por otro. Los informes de Meta usan último clic por defecto, así que los dos números pueden no coincidir y eso no es un error de ninguno de los dos: están respondiendo preguntas distintas.
GET https://lokonvio.com/api/v1/orders?payment_status=paid&since=2026-09-01
total / currency — el valor, siempre en COP.payment_status — pending, paid o failed.payment_link — el enlace de pago, si el pedido tiene uno.shipping_guide — la guía, con shipping_carrier, shipping_status y tracking_url.cash_on_delivery — si se paga al recibir: amount que cobra la transportadora y su status. En null si no aplica.items[] — sku, name, size, qty, price y subtotal.conversation_id — con qué conversación enlazarlo.subtotal / discount / coupon / delivery_fee — cómo se compone el total. Sin esto, un pedido con un 15% aplicado se lee como una venta más pequeña y no se sabe si fue la promoción.size sale de las opciones del producto. Si el negocio no guarda la talla como una opción, ese campo viene en null: preferimos decir "no lo sé" a adivinarlo.
Lo que el negocio vende. Sirve a los dos verticales con la misma forma, porque en la base son lo mismo: lo que en una tienda es un producto con tallas, en un restaurante es un plato con sus opciones.
GET https://lokonvio.com/api/v1/catalog → cuántas categorías, productos y unidades
GET https://lokonvio.com/api/v1/catalog/categories → las categorías / secciones de la carta
GET https://lokonvio.com/api/v1/catalog/products?limit=50 → los productos con sus variantes
GET https://lokonvio.com/api/v1/catalog/products/{id} → el detalle, con fotos y opciones
GET https://lokonvio.com/api/v1/catalog/coupons → los cupones que se pueden ofrecer HOYFiltros de /products:
category_id — solo los de una categoría.search — busca en el nombre y en el SKU.available — true deja solo lo que se puede vender ahora mismo.Variantes y opciones no son lo mismo, y confundirlas lleva a vender una talla que no existe:
sku, su price y su stock. La combination dice cuál es: {"Talla":"06M","Color":"Rojo"}.price_delta. No tiene stock.El stock vive en la variante. Un body talla 06M puede estar agotado mientras el 12M sobra, así que el stock del producto es la suma de las suyas. Un producto sin variantes lo devuelve en null y no en cero: cero significaría "agotado", que es otra cosa que "aquí no se lleva inventario".
available junta las tres cosas que apagan una venta: que el producto esté desactivado, marcado como no disponible, o agotado hasta una hora — el "se acabó por hoy" del restaurante, que se levanta solo y viene en out_of_stock_until.
El costo del producto no sale nunca. Es el margen del negocio, y no hace falta para nada de lo que esta API sirve. La llave la puede tener una agencia o el proveedor de un ERP.
Los cupones son los que se pueden ofrecer hoy: ya descartados los vencidos y los que no aplican este día de la semana. Es exactamente la misma lista que ve el asistente, así que sirve para comprobar si está anunciando las promociones vigentes. Traen code, type (percent o amount), value y min_purchase.
GET https://lokonvio.com/api/v1/bot/health GET https://lokonvio.com/api/v1/summary?since=2026-09-01&until=2026-09-30
/bot/health devuelve ok, degraded o down — y cuando está caído, el motivo. El más silencioso es quedarse sin saldo: los mensajes siguen saliendo y el asistente deja de responder, así que desde fuera todo parece normal mientras cada lead se pierde. Por eso el motivo va en la respuesta y no en un log.
/summary es el informe de un periodo en una sola llamada. Sin fechas, las últimas 24 horas:
{
"conversations_started": 42,
"conversations_from_ads": 31,
"orders_created": 9,
"orders_paid": 7,
"revenue_paid": 640000,
"conversion_rate": 0.1667,
"avg_first_response_seconds": 38,
"platform_cost_cop": 12400,
"timezone": "UTC (ISO 8601)"
}platform_cost_cop es lo que costó atender esas conversaciones — mensajes, asistente y transcripción de voz—. No lo da ninguna herramienta de anuncios, y es lo que completa el costo real por venta.
Si quien va a consultar es un asistente, no hace falta escribir un cliente: hay un servidor MCP con las mismas consultas, la misma llave y el mismo aislamiento.
POST https://lokonvio.com/api/v1/mcp (Streamable HTTP · JSON-RPC 2.0) X-API-Key: lk_live_xxxxxxxxxxxx Métodos: initialize · tools/list · tools/call
Herramientas de consulta:
list_conversations — los leads, con su origen y estado.get_conversation — el detalle con sus mensajes.list_orders — los pedidos con ítems y envío.get_bot_health — si el asistente está respondiendo.get_summary — el resumen del periodo.get_catalog_summary — el tamaño del catálogo y el stock total.list_categories — las categorías o secciones de la carta.list_products — los productos o platos, con variantes y stock.list_coupons — los cupones que se pueden ofrecer hoy.get_product — el detalle con fotos y opciones.Y dos que escriben, solo si la llave tiene permiso de escritura: add_note —una nota interna que ve el equipo y el cliente no— y tag_conversation. Con una llave de solo consultar, esas dos no aparecen siquiera en tools/list.
No hay ninguna herramienta que envíe mensajes, cambie un pedido, mueva un precio o borre algo. Es deliberado: quien consume un MCP es un modelo, y lo que lee son mensajes escritos por desconocidos. Una nota mal puesta se borra; un mensaje enviado a doscientos clientes, no.
Requiere una llave con permiso de escritura. Si el chat no existe, se crea.
GET https://lokonvio.com/api/v1/templates
POST https://lokonvio.com/api/v1/messages/template
{"to":"+573001112233","templateSid":"HXxxxx","variables":{"1":"Juan"}}El número puede ir con o sin whatsapp:. Las variables que envíes sobrescriben las automáticas de la plantilla.
401 — falta la llave o no es válida.403 — la llave es de solo consultar y se intentó escribir.404 — no existe, o no es de tu empresa. Las dos dan lo mismo a propósito: decir "existe pero no es tuyo" ya es contar algo de otro.429 — pasaste el límite. Espera lo que diga Retry-After.La especificación completa, siempre al día porque la genera el mismo servidor que responde:
GET https://lokonvio.com/api/v1/openapi.json
¿Dudas o algo que falta? Escríbenos a info@arawanahomestudio.com.