BenthoRAG/bentho-api

Bentho API v1

Vollständige Dokumentation: https://dev.bentho.ai · Text für Modelle: https://dev.bentho.ai/llms-full.txt

Die Grundlagen

• Basis: https://bentho.ai/api. https://bentho.org/api ist weiterhin gültig (es ist dieselbe API): Ändere keine Integrationen, die bereits funktionieren.
• Authentifizierung: Authorization: Bearer bth_<id>.<secret>. Lies sie IMMER aus der Umgebungsvariablen BENTHO_KEY; schreibe sie niemals in den Code und zeige sie nicht an.
• JSON, außer beim Hochladen von Dokumenten (multipart) und beim Stream (SSE).
• Aufruf vom Server aus: Die API akzeptiert keine Aufrufe vom Browser (CORS).
• Client-Timeout: 60 s oder mehr. Eine Frage dauert 2 bis 20 s.

Referenzen

Diese Datei ist die Karte. Die Details jeder Route (Body, Response, wörtliche Fehler und Hinweise) befinden sich in references/, generiert aus denselben Datenblättern wie https://dev.bentho.ai. Lies NUR die des Moduls, das du verwenden wirst, bevor du den Aufruf schreibst:

Teil	Datei	Was sie enthält
Kern	references/nucleo.md	Schlüssel, Fehler, Räume, Fragen, Dokumente, Konfiguration und Credits: die Routen außerhalb der Module.
Quellen	references/fuentes.md	Holt das Web in die Dokumente des Raums: Datenblätter mit jedem zitierten Datum und Seiten, die so gelesen werden.
Transkription	references/transcripcion.md	Wandelt Sprachnotizen und Audios in Text um.
Sales Agent	references/agente.md	Bedient und verkauft per Chat: versteht, was der Kunde wünscht, kalkuliert mit dem Katalog und den Versandkosten des Raums und schließt die Bestellung ab.
Marke	references/marca.md	Die Persönlichkeit des Assistenten: Identität, Ton und Taktiken deiner Marke.
Produkte	references/productos.md	Der Katalog des Raums: Produkte, Preise, Inventar und Aktionen.
Handel	references/comercial.md	Versandkosten, Zuschläge und Vergünstigungen.
Abrechnung	references/facturacion.md	Bestellungen, zu zahlender Gesamtbetrag und Prüfung der Zahlungsbelege.
Buchhaltung	references/contabilidad.md	Verbindet deine Buchhaltungssoftware: Abstimmung und Exporte.
Kommo	references/kommo.md	Synchronisiert Leads und Konversationen mit deinem CRM Kommo.
Landings	references/landing.md	Erstellt Landing Pages mit Formular aus einem Briefing, getestet in einem Browser vor der Auslieferung.

Welche Route verwenden

Aufgabe	Route	Berechtigung
Einen Schlüssel prüfen: Räume und Berechtigung	GET /profile (ohne /api) → user.companies, user.permiso	beliebig
Herausfinden, zu welchen Räumen der Schlüssel Zugriff hat und deren Module	GET /api/companies → companies[].id, companies[].modules	beliebig
Prüfen, ob jedes Modul des Raums funktioniert	GET /api/companies/{raum}/semaforo → modulos.{id}.color und motivo	lesen
Fragen	POST /api/rag/{raum}/conversations mit {"question", "session_id"}	lesen
Fragen mit Live-Text-Anzeige	POST /api/rag/{raum}/conversations/stream (SSE)	lesen
Dokumente auflisten	GET /api/rag/{raum}/documents	lesen
Ein Dokument herunterladen	GET /api/rag/{raum}/documents/{datei} (binär)	lesen
Dokumente hochladen (.pdf .docx .txt .md)	POST /api/rag/{raum}/load_documents, multipart, wiederholbares Feld files	schreiben
Prüfen, ob das Hochgeladene bereit ist	GET /api/rag/{raum}/indexing_status bis status = done oder error	lesen
Ein Dokument entfernen	DELETE /api/rag/{raum}/documents/{datei}	schreiben
Den Antwort-Cache leeren	DELETE /api/rag/{raum}/clear_cache	schreiben
Lesen / Anpassen der Antwortweise	GET / PATCH /api/rag/{raum}/config	lesen / schreiben
Limits, Tageskontingent, IPs des Raums	GET / PATCH /api/companies/{raum}/api-config	lesen / schreiben
Credits	GET /api/companies/{raum}/cuenta → cuenta.id, dann GET /api/cuentas/{konto}/bolsa	lesen
Ausgaben der abgeschlossenen Zyklen	GET /api/cuentas/{konto}/cierres	lesen
Kontingent der Module des Raums	GET /api/companies/{raum}/limite	lesen
Module aktivieren oder entfernen	PATCH /api/companies/{raum}/modules mit der VOLLSTÄNDIGEN Liste {"modules": [...]}	schreiben
Ein Datenblatt mit Webdaten erstellen	POST /api/mod/fuentes/{raum}/fichas mit {"tema", "plantilla"} → 202 mit id	schreiben
Ein Datenblatt verfolgen	GET /api/mod/fuentes/{raum}/fichas/{ficha} bis status = publicado oder fallido	lesen
Das erstellte Datenblatt lesen	GET /api/mod/fuentes/{raum}/fichas/{ficha}/markdown	lesen
Eine Landing Page aus einem Briefing erstellen	POST /api/mod/landing/{raum}/landings mit {"prompt", "submitUrl"} → 202 mit id	schreiben
Eine Landing Page verfolgen	GET /api/mod/landing/{raum}/landings/{landing} bis status beendet ist	lesen
Das HTML einer Landing Page herunterladen	GET /api/mod/landing/{raum}/landings/{landing}/html	lesen

Richtig fragen

• session_id ist in der Praxis PFLICHT (ohne: 400 "session_id es obligatorio."). Verwende eine pro Konversation und verwende sie bei Folgefragen wieder.
• Antwort: status_code "1000" = antwortete mit Unterstützung aus den Dokumenten; "1001" = es gibt nicht genügend Informationen, response enthält die Ablehnungsnachricht und sources ist leer. Versuche einen 1001 nicht erneut: das Ergebnis wird dasselbe sein.
• warning: true = teilweise Absicherung; sag dies bei der Präsentation der Antwort. confidence reicht von 0 bis 1.
• sources sind die zitierten Dokumente; response endet mit dem Fuß „Referencia: …“.
• Ein interner Fehler kommt als 200 mit status_code "1001" und dem Text „Ocurrió un error interno procesando la consulta. Intenta de nuevo.“: hier kannst du es einmal erneut versuchen.

Stream (SSE)

Frames data: {json}, getrennt durch eine Leerzeile. Ignoriere Zeilen, die mit : beginnen (Keepalive alle 15 s). Ereignisse: status, chunk (content), handoff, done (status_code, full_response, confidence, warning, sources) und error (content, schließt den Stream). Entscheide anhand des status_code des done, nicht anhand der chunk.

Module: Gemeinsamkeiten

• Route: https://bentho.ai/api/mod/{modul}/{raum}/{route}, mit demselben Schlüssel. {modul} ist die ID (agente, productos, comercial, facturacion, contabilidad, kommo, marca, transcripcion, fuentes, landing), nicht der Name.
• Antwortet nur, wenn die ID in modules des Raums ist (GET /api/companies); sonst 403 módulo no habilitado para este espacio.. Nicht existierende oder entfernte ID (ventas, comprension): 404 módulo desconocido..
• GET funktioniert mit jedem Schlüssel; POST, PUT, PATCH und DELETE erfordern escribe (403 Tu cuenta es de solo lectura en este espacio.). Ausnahme: Chat mit dem Sales Agent funktioniert mit lee.
• Nur Credits verbrauchen (402 ohne Guthaben): Sales Agent conversations…, Quellen (Datenblatt erstellen, Quelle starten) und Landings (erstellen, verfeinern, validieren, abschließen). Das Verbrauchte, in Credits: GET /api/mod/{modul}/{raum}/consumo (Sales Agent und Quellen).
• 502: das Modul ist nicht verfügbar; versuche es 2-3 Mal mit zunehmender Wartezeit erneut.
• Respektiere den abschließenden Schrägstrich, wenn die Route ihn hat (products/, conversations/, leads/…): ohne ihn gibt das Modul die Daten nicht zurück.
• Der Leitfaden für jedes Modul und ein Datenblatt pro Route: https://dev.bentho.ai/api/modulos/

Sales Agent (Modul agente)

• Ersetzt ab 2026-10-13 die Module ventas und comprension, die entfernt wurden: /api/mod/ventas/… und /api/mod/comprension/… geben 404. Gleicher Vertrag wie Ventas: ersetze das Präfix durch /api/mod/agente/ und nichts weiter.
• Versteht, was jede Nachricht im selben Zug anfordert: es gibt keine separate Route zur Interpretation.
• In einem Raum mit agente erreicht POST /api/rag/{raum}/conversations (und /stream) ebenfalls den Agenten und antwortet wie er (estado, cotizacion, handoff…).
• Mit einem Kunden chatten: POST /api/mod/agente/{raum}/conversations/ mit {"question", "session_id"} (ein session_id pro Chat; wiederverwenden). Antwortet mit response, status_code, estado, cotizacion und handoff (an eine Person weiterleiten: nicht ignorieren). Client-Timeout: 90 s.
• Einen Chat zurücksetzen: DELETE …/sessions/{session}. Kundenbild (Beleg): POST …/conversations/evidence, multipart.
• Leads: GET …/leads/, GET …/leads/{lead}, PATCH …/leads/{lead} mit {"estado"}.
• Agentenkonfiguration: GET / PATCH …/leads-config. Versandkosten: POST …/pricing/tables (Datei) → prüfen → POST …/pricing/versions/{tabelle}/activate; Angebot: POST …/pricing/quote. Bestand: …/inventory/….

Produkte (Modul productos)

• Katalog: GET / POST …/products/, GET / PATCH / DELETE …/products/{produkt}; Varianten unter …/products/{produkt}/variants und …/variants/{variante}; Typen unter …/product-types/.
• Suchen: GET …/catalog/search. Eine Datei importieren: POST …/catalog/import → prüfen GET …/catalog/imports/{import} → POST …/catalog/imports/{import}/activate (zweimalige Aktivierung verdoppelt Produkte).
• Preise: Listen unter …/price-lists, Preise unter …/prices; einen Warenkorb mit Aktionen kalkulieren: POST …/price-quote. Aktionen: …/promotions. Um einen Preis zu ändern, setze ihn erneut mit derselben Liste, Variante, Währung und min_qty: ersetzt den vorherigen (lösche ihn nicht vorher).
• Bestand: …/inventory/levels, …/inventory/items/{variante}; Reservierungen unter …/inventory/reservations; bestätigter Verkauf: POST …/inventory/sale.

Handel, Abrechnung, Buchhaltung und Kommo

• Handel (comercial): Versandkosten nach Stadt. Hochladen POST …/tarifas/draft (Datei) → POST …/tarifas/{ladung}/activate; eine Bestellung kalkulieren: POST …/cotizar; Vergünstigungen: POST …/reglas/evaluar.
• Abrechnung (facturacion): POST …/orders erstellt die Bestellung mit dem zu zahlenden Gesamtbetrag; der Beleg wird mit POST …/orders/{bestellung}/evidence (multipart) hochgeladen; geprüft wird in GET …/review-queue und genehmigt oder abgelehnt in …/review-queue/{beleg}/approve oder /reject. Belege sind personenbezogene Daten: speichere oder zeige sie nicht übermäßig.
• Buchhaltung (contabilidad): Verbinde die Software mit PATCH …/config und teste mit POST …/config/test; sende Rechnungen, Zahlungen oder Kunden an die Warteschlange (POST …/push/invoice, /payment, /customer) und verarbeite sie mit POST …/outbox/process.
• Kommo (kommo): Verbinde mit PATCH …/config (Subdomain und langlebiges Token) und teste mit POST …/config/test; Trichter unter GET …/pipelines; Sendungen unter GET …/outbox/.

Marke und Transkription

• Marke (marca): GET / PATCH …/config (Identität, Stil, Taktiken). Ein PATCH ersetzt jeden Abschnitt vollständig: sende den vollständigen Abschnitt.
• Transkription (transcripcion): POST …/transcripciones, multipart mit dem Feld archivo (ein Audio von bis zu 25 MB und 120 s) und idioma; gibt den Text zurück.

Quellen (Modul)

Nur in Räumen mit dem Modul fuentes (erscheint in GET /api/companies); sonst 403 módulo no habilitado para este espacio.. Anleitung: https://dev.bentho.ai/api/fuentes/

• Die Vorlage ist Markdown: ## Abschnitt und eine Zeile - Name: wonach suchen pro Feld. Ohne Abschnitte mit Feldern: 422.
• armar antwortet sofort mit 202; das Datenblatt dauert Minuten. Frage den Status alle 10-15 s ab. publicado bedeutet fertig; es gelangt in die Dokumente des Raums (ficha-<thema>.md), und Bentho verwendet es bei der Antwort, wenn traza.publicacion.status published ist. Bei fallida wird es automatisch wiederholt; bei rechazada erstelle es erneut. Ein weiteres Datenblatt mit demselben Thema ersetzt es.
• Jedes Datum im Markdown hat Fuente und Cita; leere sagen „sin respaldo en las páginas leídas“. Fülle die Leerstellen nicht selbst aus.
• Wenn weniger als die Hälfte gefüllt ist, sagt traza.sugerencia dies: bitte die Person um 2-4 URLs des Falls und erstelle es erneut mit urls.
• Mit como.cierre_externo: true versucht eine externe Suche am Ende, die leeren Felder zu füllen. Was nicht durch eine gelesene Seite abgesichert ist, erscheint markiert als „completado por búsqueda externa, sin página que lo respalde“: sag dies bei der Präsentation des Datums. Verbraucht Credits zum externen Tarif; verwende es nur, wenn die Person es anfordert.
• Um ein Datum zu überprüfen: GET /api/mod/fuentes/{raum}/fichas/{ficha}/pagina?url=<url von traza.paginas> gibt den Text, den das Datenblatt gelesen hat.
• Das Erstellen eines Datenblatts und das Starten einer Quelle verbrauchen Credits (402 ohne Guthaben).

Landings (Modul)

Nur in Räumen mit dem Modul landing (erscheint in GET /api/companies); sonst 403 módulo no habilitado para este espacio.. Anleitung: https://dev.bentho.ai/api/landings/

• Erstellen antwortet sofort mit 202; die Landing Page dauert Minuten. Frage den Status alle 10-15 s ab. Nicht erneut