BenthoRAG/bentho-api

API Bentho v1

Documentation complète : https://dev.bentho.ai · Texte pour modèles : https://dev.bentho.ai/llms-full.txt

Les bases

• Base : https://bentho.ai/api. https://bentho.org/api est toujours valable (c'est la même API) : ne modifiez pas les intégrations qui fonctionnent déjà.
• Authentification : Authorization: Bearer bth_<id>.<secret>. Lisez-la TOUJOURS depuis la variable d'environnement BENTHO_KEY ; ne l'écrivez jamais dans le code ni ne l'affichez.
• JSON sauf pour le téléchargement de documents (multipart) et le stream (SSE).
• Appelez depuis un serveur : l'API n'accepte pas les appels depuis le navigateur (CORS).
• Timeout client : 60 s ou plus. Une question prend de 2 à 20 s.

Références

Ce fichier est la carte. Le détail de chaque route (corps, réponse, erreurs littérales et notes) se trouve dans references/, généré à partir des mêmes fiches que https://dev.bentho.ai. Lisez UNIQUEMENT celui du module que vous allez utiliser, avant d'écrire l'appel :

Partie	Fichier	Ce qu'il contient
Noyau	references/nucleo.md	Clés, erreurs, espaces, interroger, documents, configuration et crédits : les routes en dehors des modules.
Sources	references/fuentes.md	Amène le web aux documents de l'espace : fiches avec chaque donnée citée et pages lues telles quelles.
Transcription	references/transcripcion.md	Convertit les notes vocales et les audios en texte.
Agent commercial	references/agente.md	Répond et vend par chat : comprend ce que le client demande, établit un devis avec le catalogue et les expéditions de l'espace et finalise la commande.
Marque	references/marca.md	La personnalité de l'assistant : identité, ton et tactiques de votre marque.
Produits	references/productos.md	Le catalogue de l'espace : produits, prix, inventaire et promotions.
Commercial	references/comercial.md	Tarifs d'expédition, surcoûts et avantages.
Facturation	references/facturacion.md	Commandes, total à payer et vérification des reçus de paiement.
Comptabilité	references/contabilidad.md	Connecte votre logiciel comptable : rapprochement et exportations.
Kommo	references/kommo.md	Synchronise les leads et les conversations avec votre CRM Kommo.
Landings	references/landing.md	Crée des landing pages avec formulaire à partir d'un brief, testées dans un navigateur avant d'être livrées.

Quelle route utiliser

Tâche	Route	Permission
Vérifier une clé : espaces et permission	GET /profile (sans /api) → user.companies, user.permiso	n'importe laquelle
Savoir à quels espaces la clé a accès et ses modules	GET /api/companies → companies[].id, companies[].modules	n'importe laquelle
Savoir si chaque module de l'espace fonctionne	GET /api/companies/{espace}/semaforo → modulos.{id}.color et motivo	lecture
Interroger	POST /api/rag/{espace}/conversations avec {"question", "session_id"}	lecture
Interroger en affichant le texte en direct	POST /api/rag/{espace}/conversations/stream (SSE)	lecture
Lister les documents	GET /api/rag/{espace}/documents	lecture
Télécharger un document	GET /api/rag/{espace}/documents/{fichier} (binaire)	lecture
Télécharger des documents (.pdf .docx .txt .md)	POST /api/rag/{espace}/load_documents, multipart, champ files répétable	écriture
Savoir si ce qui a été téléchargé est prêt	GET /api/rag/{espace}/indexing_status jusqu'à status = done ou error	lecture
Supprimer un document	DELETE /api/rag/{espace}/documents/{fichier}	écriture
Vider le cache des réponses	DELETE /api/rag/{espace}/clear_cache	écriture
Lire / ajuster la réponse	GET / PATCH /api/rag/{espace}/config	lecture / écriture
Limites, quota journalier, IP de l'espace	GET / PATCH /api/companies/{espace}/api-config	lecture / écriture
Crédits	GET /api/companies/{espace}/cuenta → cuenta.id, puis GET /api/cuentas/{cuenta}/bolsa	lecture
Dépense des cycles fermés	GET /api/cuentas/{cuenta}/cierres	lecture
Limite des modules de l'espace	GET /api/companies/{espace}/limite	lecture
Activer ou supprimer des modules	PATCH /api/companies/{espace}/modules avec la liste COMPLÈTE {"modules": [...]}	écriture
Créer une fiche avec des données du web	POST /api/mod/fuentes/{espace}/fichas avec {"tema", "plantilla"} → 202 avec id	écriture
Suivre une fiche	GET /api/mod/fuentes/{espace}/fichas/{ficha} jusqu'à status = publicado ou fallido	lecture
Lire la fiche créée	GET /api/mod/fuentes/{espace}/fichas/{ficha}/markdown	lecture
Créer une landing page à partir d'un brief	POST /api/mod/landing/{espace}/landings avec {"prompt", "submitUrl"} → 202 avec id	écriture
Suivre une landing page	GET /api/mod/landing/{espace}/landings/{landing} jusqu'à ce que status se termine	lecture
Télécharger le HTML d'une landing page	GET /api/mod/landing/{espace}/landings/{landing}/html	lecture

Bien interroger

• session_id est OBLIGATOIRE en pratique (sans lui : 400 "session_id es obligatorio."). Utilisez-en un par conversation et réutilisez-le dans les questions de suivi.
• Réponse : status_code "1000" = a répondu en s'appuyant sur les documents ; "1001" = pas assez d'informations, response apporte le message de rejet et sources est vide. Ne réessayez pas un 1001 : cela donnera le même résultat.
• warning: true = appui partiel ; dites-le en présentant la réponse. confidence va de 0 à 1.
• sources sont les documents cités ; response se termine par le pied de page « Référence : … ».
• Une erreur interne arrive en 200 avec status_code "1001" et le texte « Ocurrió un error interno procesando la consulta. Intenta de nuevo. » : dans ce cas, vous pouvez réessayer une fois.

Stream (SSE)

Trames data: {json} séparées par une ligne vide. Ignorez les lignes qui commencent par : (keepalive toutes les 15 s). Événements : status, chunk (content), handoff, done (status_code, full_response, confidence, warning, sources) et error (content, ferme le stream). Décidez avec le status_code du done, pas avec les chunk.

Modules : le commun

• Route : https://bentho.ai/api/mod/{module}/{espace}/{route}, avec la même clé. {module} est l'ID (agente, productos, comercial, facturacion, contabilidad, kommo, marca, transcripcion, fuentes, landing), pas le nom.
• Ne répond que si l'id est dans modules de l'espace (GET /api/companies) ; sinon, 403 módulo no habilitado para este espacio.. Id inexistant ou retiré (ventas, comprension) : 404 módulo desconocido..
• GET fonctionne avec n'importe quelle clé ; POST, PUT, PATCH et DELETE nécessitent écriture (403 Tu cuenta es de solo lectura en este espacio.). Exception : converser avec l'Agent commercial fonctionne avec lecture.
• Seuls consomment des crédits (402 sans solde) : Agent commercial conversations…, Sources (créer une fiche, lancer une source) et Landings (créer, raffiner, valider, compléter). Ce qui est dépensé, en crédits : GET /api/mod/{module}/{espace}/consumo (Agent commercial et Sources).
• 502 : le module n'est pas disponible ; réessayez 2-3 fois avec une attente croissante.
• Respectez la barre oblique finale quand la route en a une (products/, conversations/, leads/…) : sans elle, le module ne renvoie pas les données.
• Le guide de chaque module et une fiche par route : https://dev.bentho.ai/api/modulos/

Agent commercial (module agente)

• Remplace depuis le 2026-10-13 les modules ventas et comprension, qui ont été retirés : /api/mod/ventas/… et /api/mod/comprension/… donnent 404. Même contrat que celui de Ventas : changez le préfixe par /api/mod/agente/ et rien de plus.
• Comprend ce que chaque message demande dans le même tour : il n'y a pas de route séparée pour l'interpréter.
• Dans un espace avec agente, POST /api/rag/{espace}/conversations (et /stream) arrive également à l'agent et répond comme lui (estado, cotizacion, handoff…).
• Converser avec un client : POST /api/mod/agente/{espace}/conversations/ avec {"question", "session_id"} (un session_id par chat ; réutilisez-le). Répond avec response, status_code, estado, cotizacion et handoff (passer à une personne : ne l'ignorez pas). Timeout client : 90 s.
• Redémarrer un chat : DELETE …/sessions/{session}. Image du client (reçu) : POST …/conversations/evidence, multipart.
• Leads : GET …/leads/, GET …/leads/{lead}, PATCH …/leads/{lead} avec {"estado"}.
• Configuration de l'agent : GET / PATCH …/leads-config. Tarifs d'expédition : POST …/pricing/tables (fichier) → vérifier → POST …/pricing/versions/{table}/activate ; faire un devis : POST …/pricing/quote. Inventaire : …/inventory/….

Produits (module productos)

• Catalogue : GET / POST …/products/, GET / PATCH / DELETE …/products/{produit} ; variantes dans …/products/{produit}/variants et …/variants/{variante} ; types dans …/product-types/.
• Rechercher : GET …/catalog/search. Importer un fichier : POST …/catalog/import → vérifier GET …/catalog/imports/{import} → POST …/catalog/imports/{import}/activate (l'activer deux fois duplique les produits).
• Prix : listes dans …/price-lists, prix dans …/prices ; faire un devis pour un panier avec promotions : POST …/price-quote. Promotions : …/promotions. Pour changer un prix, fixez-le à nouveau avec la même liste, variante, devise et min_qty : il remplace le précédent (ne le supprimez pas avant).
• Stock : …/inventory/levels, …/inventory/items/{variante} ; réservations dans …/inventory/reservations ; vente confirmée : POST …/inventory/sale.

Commercial, Facturation, Comptabilité et Kommo

• Commercial (comercial) : tarifs d'expédition par ville. Télécharger POST …/tarifas/draft (fichier) → POST …/tarifas/{chargement}/activate ; faire un devis pour une commande : POST …/cotizar ; avantages : POST …/reglas/evaluar.
• Facturation (facturacion) : POST …/orders crée la commande avec le total à payer ; le reçu est téléchargé avec POST …/orders/{commande}/evidence (multipart) ; il est vérifié dans GET …/review-queue et approuvé ou rejeté dans …/review-queue/{reçu}/approve ou /reject. Les reçus sont des données personnelles : ne les stockez pas et ne les montrez pas excessivement.
• Comptabilité (contabilidad) : connectez le logiciel avec PATCH …/config et testez-le avec POST …/config/test ; envoyez des factures, paiements ou clients dans la file d'attente (POST …/push/invoice, /payment, /customer) et traitez-la avec POST …/outbox/process.
• Kommo (kommo) : connectez avec PATCH …/config (sous-domaine et token de longue durée) et testez avec POST …/config/test ; entonnoirs dans GET …/pipelines ; envois dans GET …/outbox/.

Marque et Transcription

• Marque (marca) : GET / PATCH …/config (identité, style, tactiques). Un PATCH remplace chaque section entière : envoyez la section complète.
• Transcription (transcripcion) : POST …/transcripciones, multipart avec le champ archivo (un audio jusqu'à 25 Mo et 120 s) et idioma ; renvoie le texte.

Sources (module)

Uniquement dans les espaces avec le module fuentes (apparaît dans GET /api/companies) ; sinon, 403 módulo no habilitado para este espacio.. Guide : https://dev.bentho.ai/api/fuentes/

• Le modèle est en markdown : ## Section et une ligne - Nom : quoi chercher par champ. Sans sections avec champs : 422.
• Créer répond 202 immédiatement ; la fiche prend des minutes. Consultez l'état toutes les 10-15 s. publicado signifie créée ; elle entre dans les documents de l'espace (ficha-<thema>.md), et Bentho l'utilise en répondant, quand traza.publicacion.status est published. Avec fallida, elle se réessaie automatiquement ; avec rechazada, recréez-la. Une autre fiche avec le même thème la remplace.
• Chaque donnée du markdown porte Fuente et Cita ; les vides disent « sin respaldo en las páginas leídas ». Ne remplissez pas vous-même les vides.
• Si elle a rempli moins de la moitié, traza.sugerencia le dit : demandez à la personne 2-4 URLs du cas et recréez-la avec urls.
• Avec como.cierre_externo: true, une recherche externe tente à la fin de remplir les champs vides. Ce qui n'est pas appuyé par une page lue sort marqué « completado por búsqueda externa, sin página que lo respalde » : dites-le en présentant la donnée. Consomme des crédits au tarif externe ; utilisez-le uniquement si la personne le demande.
• Pour vérifier une donnée : GET /api/mod/fuentes/{espace}/fichas/{ficha}/pagina?url=<url de traza.paginas> donne le texte qu'a lu la fiche.
• Créer une fiche et lancer une source consomment des crédits (402 sans solde).

Landings (module)

Uniquement dans les espaces avec le module landing (apparaît dans GET /api/companies) ; sinon, 403 módulo no habilitado para este espacio.. Guide : https://dev.bentho.ai/api/landings/

• Créer répond 202 immédiatement ; la landing page prend des minutes. Consultez l'état toutes les 10-15 s. Ne revenez pas