BenthoRAG/bentho-api

Bentho API v1

完整文档：https://dev.bentho.ai · 模型文本：https://dev.bentho.ai/llms-full.txt

基础知识

• 基础URL：https://bentho.ai/api。https://bentho.org/api 仍然有效（是同一个API）：不要更改已正常运行的集成。
• 身份验证：Authorization: Bearer bth_<id>.<secret>。始终从环境变量 BENTHO_KEY 中读取它；切勿将其写入代码或显示。
• JSON格式，文档上传（multipart）和流式（SSE）除外。
• 从服务器调用：API不支持从浏览器调用（CORS）。
• 客户端超时：60秒或更长。一个问题通常需要2到20秒。

参考文献

此文件是地图。每个路由的详细信息（请求体、响应、字面错误和注释）在 references/ 中，从与 https://dev.bentho.ai 相同的源文件生成。在编写调用之前，请仅阅读您将使用的模块对应的文件：

部分	文件	内容
核心	references/nucleo.md	密钥、错误、空间、提问、文档、配置和额度：模块之外的路由。
来源	references/fuentes.md	将网页内容提取到空间文档中：每项数据都带引用和原文的卡片，以及按原样读取的页面。
转录	references/transcripcion.md	将语音备忘录和音频转换为文本。
销售代理	references/agente.md	通过聊天接待和销售：理解客户需求，使用空间目录和运费报价，并完成订单。
品牌	references/marca.md	助手个性：你的品牌身份、语气和策略。
产品	references/productos.md	空间目录：产品、价格、库存和促销。
商务	references/comercial.md	运费、附加费和优惠。
计费	references/facturacion.md	订单、应付总额和付款凭证审核。
会计	references/contabilidad.md	连接你的会计软件：对账和导出。
Kommo	references/kommo.md	与你的Kommo CRM同步潜客和对话。
落地页	references/landing.md	根据简要描述创建带表单的落地页，在交付前在浏览器中进行过测试。

使用哪个路由

任务	路由	所需权限
检查密钥：空间和权限	GET /profile（不带 /api）→ user.companies， user.permiso	任何权限
确定密钥可访问哪些空间及其模块	GET /api/companies → companies[].id， companies[].modules	任何权限
检查空间每个模块是否正常运行	GET /api/companies/{espacio}/semaforo → modulos.{id}.color 和 motivo	读取
提问	POST /api/rag/{espacio}/conversations 带上 {"question"， "session_id"}	读取
提问并实时显示文本	POST /api/rag/{espacio}/conversations/stream (SSE)	读取
列出文档	GET /api/rag/{espacio}/documents	读取
下载文档	GET /api/rag/{espacio}/documents/{archivo} (二进制)	读取
上传文档 (.pdf .docx .txt .md)	POST /api/rag/{espacio}/load_documents， multipart，字段 files 可重复	写入
检查上传是否已就绪	GET /api/rag/{espacio}/indexing_status 直到 status = done 或 error	读取
删除文档	DELETE /api/rag/{espacio}/documents/{archivo}	写入
清空响应缓存	DELETE /api/rag/{espacio}/clear_cache	写入
读取/调整响应方式	GET / PATCH /api/rag/{espacio}/config	读取 / 写入
限制、每日配额、空间IP	GET / PATCH /api/companies/{espacio}/api-config	读取 / 写入
额度	GET /api/companies/{espacio}/cuenta → cuenta.id，然后 GET /api/cuentas/{cuenta}/bolsa	读取
已结周期消费	GET /api/cuentas/{cuenta}/cierres	读取
空间模块配额	GET /api/companies/{espacio}/limite	读取
启用或禁用模块	PATCH /api/companies/{espacio}/modules 带上完整的列表 {"modules": [...]}	写入
用网页数据构建卡片	POST /api/mod/fuentes/{espacio}/fichas 带上 {"tema"， "plantilla"} → 202 带 id	写入
跟踪卡片	GET /api/mod/fuentes/{espacio}/fichas/{ficha} 直到 status = publicado 或 fallido	读取
读取构建好的卡片	GET /api/mod/fuentes/{espacio}/fichas/{ficha}/markdown	读取
根据简要描述创建落地页	POST /api/mod/landing/{espacio}/landings 带上 {"prompt"， "submitUrl"} → 202 带 id	写入
跟踪落地页	GET /api/mod/landing/{espacio}/landings/{landing} 直到 status 结束	读取
下载落地页HTML	GET /api/mod/landing/{espacio}/landings/{landing}/html	读取

正确提问

• session_id 在实际中是必需的（没有它会返回 400 "session_id es obligatorio."）。每个对话使用一个，并在后续问题中重复使用它。
• 响应：status_code "1000" = 基于文档给出了回答；"1001" = 信息不足，response 包含拒绝消息，sources 为空。不要重试 1001：结果相同。
• warning: true = 部分支持；在呈现响应时提及这一点。confidence 范围从 0 到 1。
• sources 是引用的文档；response 以页脚“参考来源：…”结束。
• 内部错误将显示为 200 状态码，带有 status_code "1001" 和文本“处理查询时发生内部错误。请重试。”：在这种情况下，您可以重试一次。

流式 (SSE)

帧格式：data: {json} 由空行分隔。忽略以 : 开头的行（每 15 秒保活一次）。事件：status， chunk（content）， handoff， done（status_code， full_response， confidence， warning， sources）和 error（content，关闭流）。根据 done 的 status_code 做出决策，而不是根据 chunk。

模块：通用规则

• 路由：https://bentho.ai/api/mod/{modulo}/{espacio}/{ruta}，使用相同的密钥。{modulo} 是ID（agente， productos， comercial， facturacion， contabilidad， kommo， marca， transcripcion， fuentes， landing），不是名称。
• 仅当ID在空间的 modules 中时才响应（GET /api/companies）；否则返回 403 此空间未启用该模块。。ID不存在或已弃用（ventas， comprension）：返回 404 未知模块。。
• GET 适用于任何密钥；POST、PUT、PATCH 和 DELETE 需要 写入 权限（403 您的账户在此空间为只读。）。例外：与销售代理对话使用 读取 权限即可。
• 仅消耗额度（402 余额不足）：销售代理 conversations…，来源（构建卡片，启动源）和落地页（创建、优化、验证、完成）。消耗量（以额度计）：GET /api/mod/{modulo}/{espacio}/consumo（销售代理和来源）。
• 502：模块不可用；重试 2-3 次，等待时间逐渐增加。
• 当路由包含尾部斜杠时请遵循（products/， conversations/， leads/…）：没有它，模块不会返回数据。
• 每个模块的指南和每个路由的参考文件：https://dev.bentho.ai/api/modulos/

销售代理（agente 模块）

• 自 2026-10-13 起取代已弃用的 ventas 和 comprension 模块：/api/mod/ventas/… 和 /api/mod/comprension/… 返回 404。与 Ventas 具有相同的契约：只需将前缀更改为 /api/mod/agente/ 即可。
• 在同一个轮次中理解每条消息的意图：没有单独的用于解释意图的路由。
• 在启用了 agente 的空间中，POST /api/rag/{espacio}/conversations（和 /stream）也会到达代理并以代理的身份响应（estado， cotizacion， handoff…）。
• 与客户对话：POST /api/mod/agente/{espacio}/conversations/ 带上 {"question"， "session_id"}（每次聊天一个 session_id；重复使用）。响应包含 response， status_code， estado， cotizacion 和 handoff（转接给人：不要忽略它）。客户端超时：90 秒。
• 重置聊天：DELETE …/sessions/{sesion}。客户图片（凭证）：POST …/conversations/evidence， multipart。
• 潜客：GET …/leads/， GET …/leads/{lead}， PATCH …/leads/{lead} 带上 {"estado"}。
• 代理配置：GET / PATCH …/leads-config。运费：POST …/pricing/tables（文件）→ 审核 → POST …/pricing/versions/{tabla}/activate；报价：POST …/pricing/quote。库存：…/inventory/…。

产品（productos 模块）

• 目录：GET / POST …/products/， GET / PATCH / DELETE …/products/{producto}；变体在 …/products/{producto}/variants 和 …/variants/{variante}；类型在 …/product-types/。
• 搜索：GET …/catalog/search。导入文件：POST …/catalog/import → 检查 GET …/catalog/imports/{importacion} → POST …/catalog/imports/{importacion}/activate（激活两次会重复产品）。
• 价格：价格表在 …/price-lists，价格在 …/prices；使用促销计算购物车价格：POST …/price-quote。促销：…/promotions。要更改价格，只需使用相同的价格表、变体、货币和 min_qty 再次设置：它会替换先前的价格（无需事先删除）。
• 库存：…/inventory/levels， …/inventory/items/{variante}；预订在 …/inventory/reservations；确认销售：POST …/inventory/sale。

商务、计费、会计和 Kommo

• 商务（comercial）：按城市划分的运费。上传 POST …/tarifas/draft（文件）→ POST …/tarifas/{carga}/activate；计算订单运费：POST …/cotizar；优惠：POST …/reglas/evaluar。
• 计费（facturacion）：POST …/orders 创建订单，包含应付总额；凭证通过 POST …/orders/{orden}/evidence（multipart）上传；在 GET …/review-queue 中审核，并通过 …/review-queue/{comprobante}/approve 或 /reject 批准或拒绝。凭证属于个人数据：不要过度存储或展示。
• 会计（contabilidad）：通过 PATCH …/config 连接软件，并通过 POST …/config/test 进行测试；将发票、支付或客户发送到队列（POST …/push/invoice， /payment， /customer）并通过 POST …/outbox/process 处理。
• Kommo（kommo）：通过 PATCH …/config（子域和长期令牌）连接，并通过 POST …/config/test 进行测试；销售管道在 GET …/pipelines；待发送项在 GET …/outbox/。

品牌和转录

• 品牌（marca）：GET / PATCH …/config（身份、风格、策略）。一个 PATCH 会替换每个部分：请发送完整的部分。
• 转录（transcripcion）：POST …/transcripciones，multipart，包含字段 archivo（最多 25 MB 和 120 秒的音频）和 idioma；返回文本。

来源（模块）

仅存在于启用了 fuentes 模块的空间中（在 GET /api/companies 中显示）；否则返回 403 此空间未启用该模块。。指南：https://dev.bentho.ai/api/fuentes/

• 模板是 markdown 格式：## 部分 和每字段一行 - 名称：要搜索的内容。没有字段的部分会导致 422。
• 构建会立即返回 202；卡片需要几分钟时间。每 10-15 秒检查一次状态。publicado 表示已构建完成；它进入空间文档（ficha-<tema>.md），当 traza.publicacion.status 为 published 时，Bentho 在响应时会使用它。如果为 fallida，系统会自动重试；如果为 rechazada，请重新构建。具有相同主题的另一张卡片将替换它。
• markdown 中的每条数据都带有 来源 和 引用；空字段会显示“在所读页面中未找到支持”。不要自行填充空字段。
• 如果填充了不到一半，traza.sugerencia 会说明：要求用户提供该案例的 2-4 个 URL，并使用 urls 重新构建。
• 当 como.cierre_externo: true 时，外部搜索会尝试最终填充空字段。未由所读页面支持的内容会标记为“通过外部搜索完成，无支持页面”：在呈现数据时提及此点。按外部费率消耗额度；仅在用户要求时使用。
• 要检查一个数据点：GET /api/mod/fuentes/{espacio}/fichas/{ficha}/pagina?url=<traza.paginas 中的 url> 会返回卡片读取的文本。
• 构建卡片和启动源会消耗额度（402 余额不足）。

落地页（模块）

仅存在于启用了 landing 模块的空间中（在 GET /api/companies 中显示）；否则返回 403 此空间未启用该模块。。指南：https://dev.bentho.ai/api/landings/

• 创建会立即返回 202；落地页需要几分钟时间。每 10-15 秒检查一次状态。不要重新…

[翻译因内容截断而完成。]