BenthoRAG/bentho-api

API v1 de Bentho

Documentación completa: https://dev.bentho.ai · Texto para modelos: https://dev.bentho.ai/llms-full.txt

Lo básico

• Base: https://bentho.ai/api. https://bentho.org/api sigue valiendo (es la misma API): no cambies integraciones que ya funcionan.
• Autenticación: Authorization: Bearer bth_<id>.<secreto>. Léela SIEMPRE de la variable de entorno BENTHO_KEY; nunca la escribas en el código ni la muestres.
• JSON salvo la subida de documentos (multipart) y el stream (SSE).
• Llama desde un servidor: la API no admite llamadas desde el navegador (CORS).
• Timeout de cliente: 60 s o más. Una pregunta tarda de 2 a 20 s.

Referencias

Este archivo es el mapa. El detalle de cada ruta (cuerpo, respuesta, errores literales y notas) está en references/, generado de las mismas fichas que https://dev.bentho.ai. Lee SOLO la del módulo que vas a usar, antes de escribir la llamada:

Parte	Archivo	Qué trae
Núcleo	references/nucleo.md	Claves, errores, espacios, preguntar, documentos, configuración y créditos: las rutas fuera de los módulos.
Fuentes	references/fuentes.md	Trae la web a los documentos del espacio: fichas con cada dato citado y páginas que se leen tal cual.
Transcripción	references/transcripcion.md	Convierte notas de voz y audios en texto.
Agente ventas	references/agente.md	Atiende y vende por chat: entiende qué pide el cliente, cotiza con el catálogo y los envíos del espacio y cierra la orden.
Marca	references/marca.md	La personalidad del asistente: identidad, tono y tácticas de tu marca.
Productos	references/productos.md	El catálogo del espacio: productos, precios, inventario y promociones.
Comercial	references/comercial.md	Tarifas de envío, recargos y beneficios.
Facturación	references/facturacion.md	Órdenes, total a pagar y revisión de los comprobantes de pago.
Contabilidad	references/contabilidad.md	Conecta tu software contable: conciliación y exportaciones.
Kommo	references/kommo.md	Sincroniza leads y conversaciones con tu CRM Kommo.
Landings	references/landing.md	Crea landings con formulario desde un brief, probadas en un navegador antes de entregarlas.

Qué ruta usar

Tarea	Ruta	Permiso
Comprobar una clave: espacios y permiso	GET /profile (sin /api) → user.companies, user.permiso	cualquiera
Saber a qué espacios llega la clave y sus módulos	GET /api/companies → companies[].id, companies[].modules	cualquiera
Saber si cada módulo del espacio funciona	GET /api/companies/{espacio}/semaforo → modulos.{id}.color y motivo	lee
Preguntar	POST /api/rag/{espacio}/conversations con {"question", "session_id"}	lee
Preguntar mostrando el texto en vivo	POST /api/rag/{espacio}/conversations/stream (SSE)	lee
Listar documentos	GET /api/rag/{espacio}/documents	lee
Descargar un documento	GET /api/rag/{espacio}/documents/{archivo} (binario)	lee
Subir documentos (.pdf .docx .txt .md)	POST /api/rag/{espacio}/load_documents, multipart, campo files repetible	escribe
Saber si lo subido ya está listo	GET /api/rag/{espacio}/indexing_status hasta status = done o error	lee
Quitar un documento	DELETE /api/rag/{espacio}/documents/{archivo}	escribe
Vaciar la caché de respuestas	DELETE /api/rag/{espacio}/clear_cache	escribe
Leer / ajustar cómo responde	GET / PATCH /api/rag/{espacio}/config	lee / escribe
Límites, cuota diaria, IPs del espacio	GET / PATCH /api/companies/{espacio}/api-config	lee / escribe
Créditos	GET /api/companies/{espacio}/cuenta → cuenta.id, luego GET /api/cuentas/{cuenta}/bolsa	lee
Gasto de los ciclos cerrados	GET /api/cuentas/{cuenta}/cierres	lee
Cupo de módulos del espacio	GET /api/companies/{espacio}/limite	lee
Activar o quitar módulos	PATCH /api/companies/{espacio}/modules con la lista COMPLETA {"modules": [...]}	escribe
Armar una ficha con datos de la web	POST /api/mod/fuentes/{espacio}/fichas con {"tema", "plantilla"} → 202 con id	escribe
Seguir una ficha	GET /api/mod/fuentes/{espacio}/fichas/{ficha} hasta status = publicado o fallido	lee
Leer la ficha armada	GET /api/mod/fuentes/{espacio}/fichas/{ficha}/markdown	lee
Crear una landing desde un brief	POST /api/mod/landing/{espacio}/landings con {"prompt", "submitUrl"} → 202 con id	escribe
Seguir una landing	GET /api/mod/landing/{espacio}/landings/{landing} hasta que status termine	lee
Bajar el HTML de una landing	GET /api/mod/landing/{espacio}/landings/{landing}/html	lee

Preguntar bien

• session_id es OBLIGATORIO en la práctica (sin él: 400 "session_id es obligatorio."). Usa uno por conversación y reúsalo en las preguntas de seguimiento.
• Respuesta: status_code "1000" = respondió con apoyo en los documentos; "1001" = no hay información suficiente, response trae el mensaje de rechazo y sources va vacío. No reintentes un 1001: dará lo mismo.
• warning: true = respaldo parcial; dilo al presentar la respuesta. confidence va de 0 a 1.
• sources son los documentos citados; response termina con el pie «Referencia: …».
• Un error interno llega como 200 con status_code "1001" y el texto «Ocurrió un error interno procesando la consulta. Intenta de nuevo.»: ahí sí puedes reintentar una vez.

Stream (SSE)

Tramas data: {json} separadas por una línea en blanco. Ignora las líneas que empiezan por : (keepalive cada 15 s). Eventos: status, chunk (content), handoff, done (status_code, full_response, confidence, warning, sources) y error (content, cierra el stream). Decide con el status_code del done, no con los chunk.

Módulos: lo común

• Ruta: https://bentho.ai/api/mod/{modulo}/{espacio}/{ruta}, con la misma clave. {modulo} es el ID (agente, productos, comercial, facturacion, contabilidad, kommo, marca, transcripcion, fuentes, landing), no el nombre.
• Solo responde si el id está en modules del espacio (GET /api/companies); si no, 403 módulo no habilitado para este espacio.. Id inexistente o retirado (ventas, comprension): 404 módulo desconocido..
• GET vale con cualquier clave; POST, PUT, PATCH y DELETE piden escribe (403 Tu cuenta es de solo lectura en este espacio.). Excepción: conversar con el Agente ventas vale con lee.
• Solo gastan créditos (402 sin saldo): Agente ventas conversations…, Fuentes (armar ficha, lanzar fuente) y Landings (crear, refinar, validar, completar). Lo gastado, en créditos: GET /api/mod/{modulo}/{espacio}/consumo (Agente ventas y Fuentes).
• 502: el módulo no está disponible; reintenta 2-3 veces con espera creciente.
• Respeta la barra final cuando la ruta la lleva (products/, conversations/, leads/…): sin ella el módulo no devuelve los datos.
• La guía de cada módulo y una ficha por ruta: https://dev.bentho.ai/api/modulos/

Agente ventas (módulo agente)

• Sustituye desde el 2026-10-13 a los módulos ventas y comprension, que se retiraron: /api/mod/ventas/… y /api/mod/comprension/… dan 404. Mismo contrato que tenía Ventas: cambia el prefijo por /api/mod/agente/ y nada más.
• Entiende qué pide cada mensaje en el mismo turno: no hay ruta aparte para interpretarlo.
• En un espacio con agente, POST /api/rag/{espacio}/conversations (y /stream) también llega al agente y responde como él (estado, cotizacion, handoff…).
• Conversar con un cliente: POST /api/mod/agente/{espacio}/conversations/ con {"question", "session_id"} (un session_id por chat; reúsalo). Responde con response, status_code, estado, cotizacion y handoff (pasar a una persona: no lo ignores). Timeout de cliente: 90 s.
• Reiniciar un chat: DELETE …/sessions/{sesion}. Imagen del cliente (comprobante): POST …/conversations/evidence, multipart.
• Leads: GET …/leads/, GET …/leads/{lead}, PATCH …/leads/{lead} con {"estado"}.
• Configuración del agente: GET / PATCH …/leads-config. Tarifas de envío: POST …/pricing/tables (archivo) → revisa → POST …/pricing/versions/{tabla}/activate; cotizar: POST …/pricing/quote. Inventario: …/inventory/….

Productos (módulo productos)

• Catálogo: GET / POST …/products/, GET / PATCH / DELETE …/products/{producto}; variantes en …/products/{producto}/variants y …/variants/{variante}; tipos en …/product-types/.
• Buscar: GET …/catalog/search. Importar un archivo: POST …/catalog/import → revisa GET …/catalog/imports/{importacion} → POST …/catalog/imports/{importacion}/activate (activarla dos veces duplica productos).
• Precios: listas en …/price-lists, precios en …/prices; cotizar un carrito con promociones: POST …/price-quote. Promociones: …/promotions. Para cambiar un precio, fíjalo otra vez con la misma lista, variante, moneda y min_qty: reemplaza al anterior (no lo borres antes).
• Stock: …/inventory/levels, …/inventory/items/{variante}; reservas en …/inventory/reservations; venta confirmada: POST …/inventory/sale.

Comercial, Facturación, Contabilidad y Kommo

• Comercial (comercial): tarifas de envío por ciudad. Subir POST …/tarifas/draft (archivo) → POST …/tarifas/{carga}/activate; cotizar un pedido: POST …/cotizar; beneficios: POST …/reglas/evaluar.
• Facturación (facturacion): POST …/orders crea la orden con el total a pagar; el comprobante se sube con POST …/orders/{orden}/evidence (multipart); se revisa en GET …/review-queue y se aprueba o rechaza en …/review-queue/{comprobante}/approve o /reject. Los comprobantes son datos personales: no los guardes ni los enseñes de más.
• Contabilidad (contabilidad): conecta el software con PATCH …/config y pruébalo con POST …/config/test; manda facturas, pagos o clientes a la cola (POST …/push/invoice, /payment, /customer) y procésala con POST …/outbox/process.
• Kommo (kommo): conecta con PATCH …/config (subdominio y token de larga duración) y prueba con POST …/config/test; embudos en GET …/pipelines; envíos en GET …/outbox/.

Marca y Transcripción

• Marca (marca): GET / PATCH …/config (identidad, estilo, tácticas). Un PATCH reemplaza cada apartado entero: manda el apartado completo.
• Transcripción (transcripcion): POST …/transcripciones, multipart con el campo archivo (un audio de hasta 25 MB y 120 s) e idioma; devuelve el texto.

Fuentes (módulo)

Solo en espacios con el módulo fuentes (sale en GET /api/companies); si no, 403 módulo no habilitado para este espacio.. Guía: https://dev.bentho.ai/api/fuentes/

• La plantilla es markdown: ## Sección y una línea - Nombre: qué buscar por campo. Sin secciones con campos: 422.
• Armar responde 202 al momento; la ficha tarda minutos. Consulta el estado cada 10-15 s. publicado quiere decir armada; entra en los documentos del espacio (ficha-<tema>.md), y Bentho la usa al responder, cuando traza.publicacion.status es published. Con fallida se reintenta sola; con rechazada, vuelve a armarla. Otra ficha con el mismo tema la reemplaza.
• Cada dato del markdown lleva Fuente y Cita; los vacíos dicen «sin respaldo en las páginas leídas». No rellenes tú los vacíos.
• Si llenó menos de la mitad, traza.sugerencia lo dice: pide a la persona 2-4 URLs del caso y vuelve a armarla con urls.
• Con como.cierre_externo: true, una búsqueda externa intenta al final llenar los campos vacíos. Lo que no respalda una página leída sale marcado «completado por búsqueda externa, sin página que lo respalde»: dilo al presentar el dato. Gasta créditos a tarifa externa; úsalo solo si la persona lo pide.
• Para comprobar un dato: GET /api/mod/fuentes/{espacio}/fichas/{ficha}/pagina?url=<url de traza.paginas> da el texto que leyó la ficha.
• Armar una ficha y lanzar una fuente gastan créditos (402 sin saldo).

Landings (módulo)

Solo en espacios con el módulo landing (sale en GET /api/companies); si no, 403 módulo no habilitado para este espacio.. Guía: https://dev.bentho.ai/api/landings/

• Crear responde 202 al momento; la landing tarda minutos. Consulta el estado cada 10-15 s. No vuelvas