BenthoRAG/bentho-api

API v1 do Bentho

Documentação completa: https://dev.bentho.ai · Texto para modelos: https://dev.bentho.ai/llms-full.txt

O básico

• Base: https://bentho.ai/api. https://bentho.org/api ainda funciona (é a mesma API): não altere integrações que já estão funcionando.
• Autenticação: Authorization: Bearer bth_<id>.<secreto>. Leia SEMPRE da variável de ambiente BENTHO_KEY; nunca a escreva no código nem a exiba.
• JSON exceto para upload de documentos (multipart) e stream (SSE).
• Chame a partir de um servidor: a API não aceita chamadas do navegador (CORS).
• Timeout do cliente: 60 s ou mais. Uma consulta leva de 2 a 20 s.

Referências

Este arquivo é o mapa. O detalhe de cada rota (corpo, resposta, erros literais e notas) está em references/, gerado a partir das mesmas fichas de https://dev.bentho.ai. Leia APENAS a do módulo que você vai usar, antes de escrever a chamada:

Parte	Arquivo	O que contém
Núcleo	references/nucleo.md	Chaves, erros, espaços, perguntar, documentos, configuração e créditos: as rotas fora dos módulos.
Fontes	references/fuentes.md	Traz a web para os documentos do espaço: fichas com cada dado citado e páginas que são lidas tal qual.
Transcrição	references/transcripcion.md	Converte notas de voz e áudios em texto.
Agente de Vendas	references/agente.md	Atende e vende por chat: entende o que o cliente pede, cotiza com o catálogo e os envios do espaço e fecha o pedido.
Marca	references/marca.md	A personalidade do assistente: identidade, tom e táticas da sua marca.
Produtos	references/productos.md	O catálogo do espaço: produtos, preços, inventário e promoções.
Comercial	references/comercial.md	Tarifas de envio, sobretaxas e benefícios.
Faturamento	references/facturacion.md	Pedidos, total a pagar e revisão dos comprovantes de pagamento.
Contabilidade	references/contabilidad.md	Conecta seu software contábil: conciliação e exportações.
Kommo	references/kommo.md	Sincroniza leads e conversas com seu CRM Kommo.
Landings	references/landing.md	Cria landings com formulário a partir de um brief, testadas em um navegador antes de entregá-las.

Qual rota usar

Tarefa	Rota	Permissão
Verificar uma chave: espaços e permissão	GET /profile (sem /api) → user.companies, user.permiso	qualquer
Saber a quais espaços a chave tem acesso e seus módulos	GET /api/companies → companies[].id, companies[].modules	qualquer
Saber se cada módulo do espaço funciona	GET /api/companies/{espaco}/semaforo → modulos.{id}.color e motivo	leitura
Perguntar	POST /api/rag/{espaco}/conversations com {"question", "session_id"}	leitura
Perguntar mostrando o texto ao vivo	POST /api/rag/{espaco}/conversations/stream (SSE)	leitura
Listar documentos	GET /api/rag/{espaco}/documents	leitura
Baixar um documento	GET /api/rag/{espaco}/documents/{arquivo} (binário)	leitura
Enviar documentos (.pdf .docx .txt .md)	POST /api/rag/{espaco}/load_documents, multipart, campo files repetível	escrita
Saber se o que foi enviado já está pronto	GET /api/rag/{espaco}/indexing_status até status = done ou error	leitura
Remover um documento	DELETE /api/rag/{espaco}/documents/{arquivo}	escrita
Limpar o cache de respostas	DELETE /api/rag/{espaco}/clear_cache	escrita
Ler / ajustar como responde	GET / PATCH /api/rag/{espaco}/config	leitura / escrita
Limites, cota diária, IPs do espaço	GET / PATCH /api/companies/{espaco}/api-config	leitura / escrita
Créditos	GET /api/companies/{espaco}/cuenta → cuenta.id, depois GET /api/cuentas/{conta}/bolsa	leitura
Gasto dos ciclos fechados	GET /api/cuentas/{conta}/cierres	leitura
Cota de módulos do espaço	GET /api/companies/{espaco}/limite	leitura
Ativar ou remover módulos	PATCH /api/companies/{espaco}/modules com a lista COMPLETA {"modules": [...]}	escrita
Montar uma ficha com dados da web	POST /api/mod/fontes/{espaco}/fichas com {"tema", "plantilla"} → 202 com id	escrita
Acompanhar uma ficha	GET /api/mod/fontes/{espaco}/fichas/{ficha} até status = publicado ou fallido	leitura
Ler a ficha montada	GET /api/mod/fontes/{espaco}/fichas/{ficha}/markdown	leitura
Criar uma landing a partir de um brief	POST /api/mod/landing/{espaco}/landings com {"prompt", "submitUrl"} → 202 com id	escrita
Acompanhar uma landing	GET /api/mod/landing/{espaco}/landings/{landing} até que status termine	leitura
Baixar o HTML de uma landing	GET /api/mod/landing/{espaco}/landings/{landing}/html	leitura

Como perguntar bem

• session_id é OBRIGATÓRIO na prática (sem ele: 400 "session_id é obrigatório."). Use um por conversa e reutilize-o nas perguntas de acompanhamento.
• Resposta: status_code "1000" = respondeu com base nos documentos; "1001" = não há informação suficiente, response traz a mensagem de rejeição e sources vai vazio. Não tente novamente um 1001: dará o mesmo.
• warning: true = respaldo parcial; diga isso ao apresentar a resposta. confidence vai de 0 a 1.
• sources são os documentos citados; response termina com o rodapé «Referência: …».
• Um erro interno chega como 200 com status_code "1001" e o texto «Ocorreu um erro interno processando a consulta. Tente novamente.»: nesse caso você pode tentar novamente uma vez.

Stream (SSE)

Quadros data: {json} separados por uma linha em branco. Ignore as linhas que começam com : (keepalive a cada 15 s). Eventos: status, chunk (content), handoff, done (status_code, full_response, confidence, warning, sources) e error (content, fecha o stream). Decida com base no status_code do done, não nos chunk.

Módulos: o comum

• Rota: https://bentho.ai/api/mod/{modulo}/{espaco}/{rota}, com a mesma chave. {modulo} é o ID (agente, productos, comercial, facturacion, contabilidad, kommo, marca, transcripcion, fuentes, landing), não o nome.
• Só responde se o id estiver em modules do espaço (GET /api/companies); se não, 403 módulo não habilitado para este espaço.. Id inexistente ou removido (ventas, comprension): 404 módulo desconhecido..
• GET vale com qualquer chave; POST, PUT, PATCH e DELETE exigem escrever (403 Sua conta é somente leitura neste espaço.). Exceção: conversar com o Agente de Vendas vale com leitura.
• Só gastam créditos (402 sem saldo): Agente de Vendas conversations…, Fontes (montar ficha, lançar fonte) e Landings (criar, refinar, validar, completar). O gasto, em créditos: GET /api/mod/{modulo}/{espaco}/consumo (Agente de Vendas e Fontes).
• 502: o módulo não está disponível; tente novamente 2-3 vezes com espera crescente.
• Respeite a barra final quando a rota a tiver (products/, conversations/, leads/…): sem ela o módulo não retorna os dados.
• O guia de cada módulo e uma ficha por rota: https://dev.bentho.ai/api/modulos/

Agente de Vendas (módulo agente)

• Substitui a partir de 2026-10-13 os módulos ventas e comprension, que foram removidos: /api/mod/ventas/… e /api/mod/comprension/… dão 404. Mesmo contrato que o Ventas tinha: mude o prefixo para /api/mod/agente/ e nada mais.
• Entende o que cada mensagem pede no mesmo turno: não há rota separada para interpretá-la.
• Em um espaço com agente, POST /api/rag/{espaco}/conversations (e /stream) também chega ao agente e responde como ele (estado, cotizacion, handoff…).
• Conversar com um cliente: POST /api/mod/agente/{espaco}/conversations/ com {"question", "session_id"} (um session_id por chat; reutilize-o). Responde com response, status_code, estado, cotizacion e handoff (passar para uma pessoa: não o ignore). Timeout do cliente: 90 s.
• Reiniciar um chat: DELETE …/sessions/{sessao}. Imagem do cliente (comprovante): POST …/conversations/evidence, multipart.
• Leads: GET …/leads/, GET …/leads/{lead}, PATCH …/leads/{lead} com {"estado"}.
• Configuração do agente: GET / PATCH …/leads-config. Tarifas de envio: POST …/pricing/tables (arquivo) → revisa → POST …/pricing/versions/{tabela}/activate; cotizar: POST …/pricing/quote. Inventário: …/inventory/….

Produtos (módulo productos)

• Catálogo: GET / POST …/products/, GET / PATCH / DELETE …/products/{produto}; variantes em …/products/{produto}/variants e …/variants/{variante}; tipos em …/product-types/.
• Buscar: GET …/catalog/search. Importar um arquivo: POST …/catalog/import → revisa GET …/catalog/imports/{importacao} → POST …/catalog/imports/{importacao}/activate (ativá-la duas vezes duplica produtos).
• Preços: listas em …/price-lists, preços em …/prices; cotizar um carrinho com promoções: POST …/price-quote. Promoções: …/promotions. Para alterar um preço, defina-o novamente com a mesma lista, variante, moeda e min_qty: substitui o anterior (não o apague antes).
• Estoque: …/inventory/levels, …/inventory/items/{variante}; reservas em …/inventory/reservations; venda confirmada: POST …/inventory/sale.

Comercial, Faturamento, Contabilidade e Kommo

• Comercial (comercial): tarifas de envio por cidade. Enviar POST …/tarifas/draft (arquivo) → POST …/tarifas/{carga}/activate; cotizar um pedido: POST …/cotizar; benefícios: POST …/regras/evaluar.
• Faturamento (facturacion): POST …/orders cria o pedido com o total a pagar; o comprovante é enviado com POST …/orders/{pedido}/evidence (multipart); é revisado em GET …/review-queue e aprovado ou rejeitado em …/review-queue/{comprovante}/approve ou /reject. Os comprovantes são dados pessoais: não os guarde nem os exiba em excesso.
• Contabilidade (contabilidad): conecta o software com PATCH …/config e teste com POST …/config/test; envia faturas, pagamentos ou clientes para a fila (POST …/push/invoice, /payment, /customer) e processe-a com POST …/outbox/process.
• Kommo (kommo): conecta com PATCH …/config (subdomínio e token de longa duração) e teste com POST …/config/test; funis em GET …/pipelines; envios em GET …/outbox/.

Marca e Transcrição

• Marca (marca): GET / PATCH …/config (identidade, estilo, táticas). Um PATCH substitui cada seção inteira: envie a seção completa.
• Transcrição (transcripcion): POST …/transcripciones, multipart com o campo archivo (um áudio de até 25 MB e 120 s) e idioma; retorna o texto.

Fontes (módulo)

Apenas em espaços com o módulo fuentes (aparece em GET /api/companies); se não, 403 módulo não habilitado para este espaço.. Guia: https://dev.bentho.ai/api/fuentes/

• O modelo é markdown: ## Seção e uma linha - Nome: o que buscar por campo. Sem seções com campos: 422.
• Montar responde 202 no momento; a ficha leva minutos. Consulte o status a cada 10-15 s. publicado significa montada; entra nos documentos do espaço (ficha-<tema>.md), e o Bentho a usa ao responder, quando traza.publicacion.status é published. Com fallida tenta novamente sozinha; com rechazada, monte-a novamente. Outra ficha com o mesmo tema a substitui.
• Cada dado do markdown traz Fonte e Citação; os vazios dizem «sem respaldo nas páginas lidas». Não preencha você os vazios.
• Se preencheu menos da metade, traza.sugerencia o diz: peça à pessoa 2-4 URLs do caso e monte-a novamente com urls.
• Com como.cierre_externo: true, uma busca externa tenta no final preencher os campos vazios. O que não é respaldado por uma página lida sai marcado «completado por busca externa, sem página que o respalde»: diga isso ao apresentar o dado. Gasta créditos a tarifa externa; use-o apenas se a pessoa o pedir.
• Para verificar um dado: GET /api/mod/fontes/{espaco}/fichas/{ficha}/pagina?url=<url de traza.paginas> retorna o texto que a ficha leu.
• Montar uma ficha e lançar uma fonte gastam créditos (402 sem saldo).

Landings (módulo)

Apenas em espaços com o módulo landing (aparece em GET /api/companies); se não, 403 módulo não habilitado para este espaço.. Guia: https://dev.bentho.ai/api/landings/

• Criar responde 202 no momento; a landing leva minutos. Consulte o status a cada 10-15 s. Não repita a chamada de criação até que o status anterior tenha terminado.
• O status ativa significa que está no ar. Se por algum motivo a landing estiver com status erro ou cancelada, você pode tentar recriá-la com um novo prompt.
• Para baixar o HTML: GET /api/mod/landing/{espaco}/landings/{landing}/html retorna o HTML completo.
• Créditos: criar, refinar e publicar uma landing gastam créditos (402 sem saldo).