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 와 동일한 명세서에서 생성되었습니다. 호출을 작성하기 전에 사용하려는 모듈의 파일만 읽으세요:

부분	파일	내용
핵심	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는 Referencia: … 꼬리말로 끝납니다.
• 내부 오류는 200과 status_code "1001", 텍스트 Ocurrió un error interno procesando la consulta. Intenta de nuevo.로 도착합니다: 이 경우 한 번 재시도할 수 있습니다.

스트림 (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). 이름이 아닙니다.
• 공간의 modules에 ID가 있는 경우에만 응답합니다(GET /api/companies); 그렇지 않으면 403 módulo no habilitado para este espacio.. 존재하지 않거나 제거된 ID(ventas, comprension): 404 módulo desconocido..
• GET은 모든 키로 유효합니다. POST, PUT, PATCH 및 DELETE는 escribe 권한이 필요합니다(403 Tu cuenta es de solo lectura en este espacio.). 예외: 판매 에이전트와 대화하는 것은 lee 권한으로 유효합니다.
• 크레딧만 소비합니다(잔액 부족 시 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 필드(최대 25MB 및 120초 오디오) 및 idioma 포함; 텍스트를 반환합니다.

소스 (모듈)

fuentes 모듈이 있는 공간에서만 가능합니다(GET /api/companies에 표시됨); 그렇지 않으면 403 módulo no habilitado para este espacio.. 가이드: https://dev.bentho.ai/api/fuentes/

• 템플릿은 마크다운입니다: ## Sección 및 필드당 - 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에 표시됩니다: 사용자에게 해당 사례의 URL 2-4개를 요청하고 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=<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초마다 상태를 확인하세요.