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 から読み取ってください。コード内に記述したり、表示したりしないでください。
• ドキュメントのアップロード（multipart）とストリーム（SSE）を除き、JSONを使用します。
• サーバーから呼び出してください。APIはブラウザからの呼び出し（CORS）をサポートしていません。
• クライアントのタイムアウト: 60秒以上。質問の応答には2〜20秒かかります。

リファレンス

このファイルは概要です。各ルートの詳細（本文、レスポンス、エラーメッセージ、注意事項）は references/ にあり、https://dev.bentho.ai の情報から生成されています。API呼び出しを記述する前に、使用するモジュールのリファレンスのみを読んでください。

セクション	ファイル	内容
コア	references/nucleo.md	キー、エラー、スペース、質問、ドキュメント、設定、クレジット：モジュール以外のすべてのルート。
情報源	references/fuentes.md	Webからスペースのドキュメントにデータを取り込みます：引用付きのデータカードと、そのまま読み取られるページ。
文字起こし	references/transcripcion.md	ボイスメモや音声をテキストに変換します。
セールスエージェント	references/agente.md	チャットで対応・販売：顧客のリクエストを理解し、スペースのカタログと配送料に基づいて見積もり、注文を確定します。
ブランド	references/marca.md	アシスタントの個性：ブランドのアイデンティティ、トーン、戦術。
商品	references/productos.md	スペースのカタログ：商品、価格、在庫、プロモーション。
販売	references/comercial.md	配送料、追加料金、特典。
請求	references/facturacion.md	注文、支払総額、支払証明書の確認。
会計	references/contabilidad.md	会計ソフトとの連携： reconciliation とエクスポート。
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	読み取り / 書き込み
制限、1日あたりのクォータ、スペースの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": [...]} を使用	書き込み
Webデータからの情報カード作成	POST /api/mod/fuentes/{espacio}/fichas {"tema", "plantilla"} を使用 → 202 with 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 with 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."）。会話ごとに1つ使用し、フォローアップの質問で再利用します。
• 応答: status_code "1000" = ドキュメントに基づいて応答しました。"1001" = 十分な情報がありません。response には拒否メッセージが含まれ、sources は空になります。1001を再試行しないでください。同じ結果になります。
• warning: true = 部分的な裏付け。応答を提示する際に伝えてください。confidence は0から1の範囲です。
• sources は引用されたドキュメントです。response はフッター「Referencia: …」で終わります。
• 内部エラーは、status_code "1001" とテキスト「Ocurrió un error interno procesando la consulta. Intenta de nuevo.」を含む200として返されます。この場合のみ、1回再試行できます。

ストリーム（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）であり、名前ではありません。
• スペースの modules（GET /api/companies）にIDが含まれている場合にのみ応答します。含まれていない場合、403 módulo no habilitado para este espacio. となります。存在しないIDまたは廃止された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"} を使用（チャットごとに1つの 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（2回アクティブ化すると商品が重複します）。
• 価格: 価格表は …/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（最大25MB、120秒の音声）と idioma; テキストを返します。

情報源（モジュール）

fuentes モジュールを持つスペースのみ（GET /api/companies に表示されます）。それ以外の場合は 403 módulo no habilitado para este espacio.。ガイド: https://dev.bentho.ai/api/fuentes/

• テンプレートはマークダウンです: ## Sección と、フィールドごとに1行 - Nombre: qué buscar。セクションのないフィールド: 422。
• 作成はすぐに202を返します。情報カードの作成には数分かかります。10〜15秒ごとにステータスを確認してください。publicado は作成済みを意味します。スペースのドキュメント（ficha-<tema>.md）に追加され、traza.publicacion.status が published の場合、Bentho は応答時にそれを使用します。fallida の場合は自動的に再試行されます。rechazada の場合は、再度作成します。同じテーマの別のカードはそれを置き換えます。
• マークダウンの各データには Fuente と Cita が含まれます。空のフィールドは「sin respaldo en las páginas leídas」（読み取ったページに裏付けなし）と表示されます。空のフィールドを自分で埋めないでください。
• 半分未満しか埋まっていない場合、traza.sugerencia にその旨が表示されます。ユーザーに2〜4つの該当URLを依頼し、urls を使用して再度作成します。
• como.cierre_externo: true の場合、外部検索が最後に空のフィールドを埋めようとします。読み取ったページで裏付けられていないものには、「completado por búsqueda externa, sin página que lo respalde」（外部検索により完了、裏付けるページなし）とマークされます。データを提示する際にその旨を伝えてください。外部レートでクレジットを消費します。ユーザーが要求した場合にのみ使用してください。
• データを確認するには: GET /api/mod/fuentes/{espacio}/fichas/{ficha}/pagina?url=<url de traza.paginas> で、カードが読み取ったテキストを取得できます。
• 情報カードの作成と情報源の起動はクレジットを消費します（残高不足で402）。

ランディングページ（モジュール）

landing モジュールを持つスペースのみ（GET /api/companies に表示されます）。それ以外の場合は 403 módulo no habilitado para este espacio.。ガイド: https://dev.bentho.ai/api/landings/

• 作成はすぐに202を返します。ランディングページの作成には数分かかります。10〜15秒ごとにステータスを確認してください。再試行しないでください…

[truncated]

エラーコード

コード	HTTP	内容
1000	200	成功（応答あり）
1001	200	成功（応答なし / 拒否）
1002	200	内部エラー（1回再試行可能）
2000	400	リクエストエラー
2001	401	認証エラー
2002	403	権限エラー
2003	404	リソースが見つかりません
2004	409	競合
2005	422	バリデーションエラー
2006	429	レート制限
2007	500	内部サーバーエラー
2008	502	モジュール利用不可
2009	503	サービス利用不可

詳細については、各モジュールの完全なリファレンスを参照してください。