BenthoRAG/bentho-api

Bentho API v1

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

基礎知識

• 基礎網址：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 秒一次 keepalive）。事件：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 módulo no habilitado para este espacio.。不存在或已移除的 ID（ventas、comprension）：404 módulo desconocido.。
• GET 可以使用任何密鑰；POST、PUT、PATCH 和 DELETE 需要 寫入 權限（403 Tu cuenta es de solo lectura en este espacio.）。例外：與銷售代理對話只需 讀取 權限。
• 僅消耗點數（餘額不足時返回 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 módulo no habilitado para este espacio.。指南：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 módulo no habilitado para este espacio.。指南：https://dev.bentho.ai/api/landings/

• 創建立即回應 202；登陸頁面需要幾分鐘完成。每 10-15 秒檢查一次狀態。