API Reference — chkuiskolopi.ge

Base URL: https://api.chkuiskolopi.ge/api/scrap/

ეს დოკუმენტი ორი ნაწილისგან შედგება:

ნაწილი I — Public API: პარტნიორი საიტებისთვის, რომლებიც ჩვენს ბოტს იყენებენ embed-ად ან პირდაპირი API call-ით.
ნაწილი II — Internal API: საკუთარი ფრონტენდის, მობილური აპლიკაციისა და გადახდის სერვისების webhook-ებისთვის.

ავტორიზაცია — მიმოხილვა

API-ში ოთხი სხვადასხვა ავტორიზაციის სქემაა გამოყენებული. ყოველი endpoint-ის ცხრილში მითითებულია, რომელი ვრცელდება მასზე.

სქემა	სად გამოიყენება	რა იცვლება
JWT	Header: `Authorization: Bearer <token>`	რეგისტრირებული მომხმარებლისთვის. ვადაგასული → `401`.
Device fingerprint	Body: `deviceInfo.device_name` + `deviceInfo.ip_address`	სტუმრებისთვის. ლიმიტი — 15 query/დღე.
partner_key	Body: `partner_key` (UUID)	მხოლოდ widget endpoint-ისთვის. პარტნიორის ბალანსიდან ჭრის.
Webhook signature	SHA1 (Flitt), verify_token (Messenger)	მხოლოდ შემომავალი webhook-ებისთვის.

„Hybrid auth" ნიშნავს, რომ endpoint ჯერ JWT-ს ეძებს header-ში; თუ არ არის, fallback-ად იყენებს device fingerprint-ს body-დან.

შეცდომების ფორმატი

ყველა შეცდომა ბრუნდება JSON-ით:

{ "error": "<message>" }

ან:

{ "message": "<message>" }

ძირითადი status code-ები: 400 (missing/invalid params), 401 (auth), 402 (balance), 404 (resource), 429 (guest limit), 500 (server).

ნაწილი I — Public API (პარტნიორი ინტეგრატორებისთვის)

პარტნიორებისთვის ხელმისაწვდომია ბოტი ორი გზით: widget-ის embed (მარტივი) ან პირდაპირი API call (მოქნილი). ორივე იყენებს partner_key-ს — UUID, რომელიც პარტნიორის ბალანსს უკავშირდება.

1.1. Widget Embed — `GET /widget.js`

ჩაშენებული ჩატის widget. ერთი <script> ტეგი საიტზე — და ხელში მარჯვენა კუთხეში ჩატის ღილაკი გამოჩნდება.

ველი	მნიშვნელობა
Method	`GET`
Auth	არ მოწმდება server-side. `partner_key` მხოლოდ კლიენტ-side გადადის.
Query	`key=<UUID>` — partner_key
Response	`200 OK`, `Content-Type: application/javascript`

გამოყენება

<script src="https://api.chkuiskolopi.ge/api/scrap/widget.js?key=YOUR_PARTNER_KEY"></script>

ეს ერთი ხაზი საკმარისია. ჩატის ღილაკი (#sa-widget-btn) ავტომატურად დაემატება გვერდს. შიგნით widget იძახებს widget/query/-ს (იხ. ქვემოთ).

1.2. Direct Query — `POST /widget/query/`

თუ პარტნიორს უნდა საკუთარი UI-ით ან server-side-ით საუბრის გამოძახება — პირდაპირ ამ endpoint-ს იძახებს.

ველი	მნიშვნელობა
Method	`POST`
Auth	`partner_key` body-ში (required). JWT საჭირო არ არის.
Content-Type	`application/json`

Request body

ველი	ტიპი	required	აღწერა
`partner_key`	string (UUID)	✓	პარტნიორის API key
`query`	string	✓	მომხმარებლის შეკითხვა
`session_id`	string	✓	სესიის ID (პარტნიორი ქმნის — მაგ. UUID per visitor)
`file_Ids`	array	—	მიბმული ფაილების ID-ები (default: `[]`)
`deviceInfo`	object	—	`{device_name, ip_address}`

Response — `200 OK`

{
  "response": "ბოტის ტექსტური პასუხი",
  "DocumentLinks": [],
  "chat_id": 12345,
  "lawyer_info": null,
  "sandbox_url": null
}

შეცდომები

Code	მიზეზი
`400`	`partner_key` მისამართის გარეშე, `query` ან `session_id` ცარიელია
`401`	invalid `partner_key`
`402`	partner balance < 5

მაგალითი

curl -X POST https://api.chkuiskolopi.ge/api/scrap/widget/query/ \
  -H "Content-Type: application/json" \
  -d '{
    "partner_key": "11111111-2222-3333-4444-555555555555",
    "query": "გამარჯობა",
    "session_id": "visitor-abc-123"
  }'

ბილინგი: ყოველი წარმატებული query-ი პარტნიორის ბალანსიდან ჭრის (არა მომხმარებლის). ბალანსის შევსება ხდება ცალკე — დაუკავშირდით ადმინისტრაციას.

ნაწილი II — Internal API (Frontend / Mobile / Webhooks)

ეს ნაწილი იყენებენ chkuiskolopi.ge-ის საკუთარი ფრონტენდი, მობილური აპლიკაცია, და გადახდის სერვისების webhook-ები. გარე ინტეგრატორებისთვის არ არის განკუთვნილი.

2.1. ჩატი და სესიები

`POST /query/` — მთავარი query endpoint

ფრონტენდიდან ბოტთან საუბრის ძირითადი endpoint.

ველი	მნიშვნელობა
Method	`POST`
Auth	Hybrid (JWT ან device fingerprint)
Content-Type	`application/json`

Request body:

ველი	ტიპი	required
`query`	string	✓
`session_id`	string	✓
`file_Ids`	array	—
`deviceInfo`	object	— (sub: `device_name`, `ip_address`)

Response 200:

{
  "response": "...",
  "DocumentLinks": [],
  "chat_id": 12345,
  "lawyer_info": null,
  "sandbox_url": null
}

Error codes: 400 (missing fields), 401 (token expired), 402 (balance < 5), 404 (user), 429 (guest daily limit hit), 500.

Side effects: იწერება ChatHistory, ბალანსი ჭრება (paid user), იძახება xAI Grok + OpenAI translate.

`GET /sessions/` — სესიების ჩამონათვალი

ველი	მნიშვნელობა
Method	`GET`
Auth	პირობითი: თუ `session_id` query param მითითებულია → public. წინააღმდეგ შემთხვევაში → JWT required.

Query params: session_id (optional)

Response 200: ChatHistorySerializer array (shared view) ან მომხმარებლის სესიების სია.

Errors: 400 (auth missing), 401, 404 (no shared chat).

`GET /chats/` — ერთი სესიის ისტორია

ველი	მნიშვნელობა
Method	`GET`
Auth	Session-based (მხოლოდ `session_id`-ით — ჩატის გასაზიარებლად)

Query params: session_id (required)

Response 200: timeline array — [{session_id, text, sender, timestamp, DocumentLinks, files, chat_id, feedback, lawyer_info}]

Errors: 400 (missing session_id), 404.

2.2. ფაილების მართვა

`POST /upload/` — ფაილების ატვირთვა

ველი	მნიშვნელობა
Method	`POST`
Auth	Hybrid
Content-Type	`multipart/form-data`

Form fields:

ველი	ტიპი	required
`files`	file[]	✓
`session_id`	string	✓
`device_name`	string	—
`ip_address`	string	—

Allowed extensions: txt, pdf, jpg, jpeg, png, gif, webp, docx, doc, xlsx, xls, csv, pptx, ppt, html, json, md, py, c, cpp, java, xml, zip, mp3, wav, m4a

Response 201: FileInfoSerializer array. Response 207: {uploaded_files, failed_uploads} — ნაწილობრივი წარმატება.

Side effects: AWS S3 upload, OpenAI Files upload. ხმოვანი ფაილებისთვის — AWS Transcribe.

`POST /list_documents/` — ფაილების სია

ველი	მნიშვნელობა
Method	`POST` (სახელის მიუხედავად)
Auth	Hybrid

Query params: page (int, default 1), page_size (int, default 10) Body: deviceInfo (object)

Response 200:

{
  "total_pages": 3,
  "current_page": 1,
  "page_size": 10,
  "total_items": 27,
  "results": [/* FileInfoSerializer + file_size + file_id */]
}

`PATCH /delete_document/` — ფაილის წაშლა (soft)

ველი	მნიშვნელობა
Method	`PATCH`
Auth	Hybrid (JWT ან device fingerprint) + ownership check

Query params: file_id (required)

Response 200: FileInfoSerializer. Errors: 400, 401, 404.

Side effects: is_deleted=True (DB-ში რჩება).

2.3. Feedback და Email

`POST /chat-history/feedback/<chat_id>/`

ველი	მნიშვნელობა
Method	`POST`
Auth	Hybrid (JWT ან device fingerprint) + ownership check

Path: chat_id (int) Body: action ("like" | "dislike")

Response: {message: "..."}

Errors: 401, 404.

`POST /chat-history/send-email/<chat_id>/`

ველი	მნიშვნელობა
Method	`POST`
Auth	JWT optional (გამოიყენება მხოლოდ user_email-ის ამოსაკითხად — სტუმარს "Guest User" გადაეცემა)

Path: chat_id Body: feedback (optional, default "None")

Response 200: {message: "Email sent successfully."} Side effects: იგზავნება email DEFAULT_FROM_EMAIL-ზე.

`POST /feedback/technical/`

ველი	მნიშვნელობა
Method	`POST`
Auth	JWT optional

Body: feedback (string, required)

Response 200: {message: "Technical feedback submitted successfully."}

2.4. სესიის მართვა

`POST /chat-session-action/`

ველი	მნიშვნელობა
Method	`POST`
Auth	Hybrid (JWT ან device fingerprint) + ownership check

Body:

ველი	ტიპი	required
`action`	`"delete"` \| `"rename"`	✓
`session_id`	string	✓
`new_name`	string	✓ (მხოლოდ rename-ისთვის)

Response: {message: "..."}

`POST /link-sessions/`

guest user-ის სესიის გადატანა რეგისტრირებულ მომხმარებელზე ლოგინის შემდეგ.

ველი	მნიშვნელობა
Method	`POST`
Auth	Hybrid (JWT უპირატესი, fallback — device_info)

Body:

ველი	ტიპი	required
`session_id`	string	✓
`new_session_id`	string	—
`device_info`	object	—

Response 200: {message, new_session_id}

2.5. ბალანსი და გადახდები

`POST /get-user-balance/`

ველი	მნიშვნელობა
Method	`POST`
Auth	JWT required

Body: არ მოიხმარება.

Response: {balance: 12.50}

`POST /recharge/smart-router/` — რეკომენდირებული შევსების endpoint

ავტომატურად ირჩევს გადახდის გზას მომხმარებლის ლოკაციით (GE → Flitt GEL, სხვა → PayPal).

ველი	მნიშვნელობა
Method	`POST`
Auth	JWT required

Body:

ველი	ტიპი	required
`amount`	float (USD)	✓ (≥ 10)
`paymentMethod`	string	— (მხოლოდ არა-GE-ისთვის)

Response 200 (GE მომხმარებელი):

{
  "status": "success",
  "gateway": "flitt_gel",
  "payment_url": "https://pay.flitt.com/...",
  "amount_gel": 27.50,
  "currency": "GEL",
  "conversion_rate": 2.75
}

არა-GE-ისთვის — გადასცემს recharge/initiate/ (PayPal) ან flitt/recharge/-ს.

`POST /recharge/initiate/` — PayPal-ის ინიცირება

ველი	მნიშვნელობა
Method	`POST`
Auth	JWT required

Body: amount (≥ 10)

Response 200: {approval_url: "https://www.paypal.com/..."}

`POST /recharge/success/` — PayPal callback-ის შემდეგ ფრონტიდან

ველი	მნიშვნელობა
Method	`POST`
Auth	არ მოწმდება (paymentId/payer_id გასაღებებად)

Body: paymentId, payer_id

Response 200: {message, new_balance}

`POST /flitt/recharge/` — Flitt-ის ინიცირება (USD direct)

ველი	მნიშვნელობა
Method	`POST`
Auth	JWT required

Body: amount (USD, ≥ 10)

Response 200:

{
  "success": true,
  "payment_id": "...",
  "order_id": "...",
  "checkout_url": "https://pay.flitt.com/...",
  "transaction_id": "..."
}

`GET/POST /flitt/return/` — Flitt-ის redirect endpoint

Flitt-ი ბრაუზერს გადამისამართებს აქ, ეს კი redirect-ით აგზავნის ფრონტენდზე.

Response: 302 → https://chkuiskolopi.ge/payment-success?<params>

შენიშვნა: ხელმისაწვდომია trailing slash-იანი (/flitt/return/) და უ-slash-ო (/flitt/return) — ერთი და იგივე handler.

2.6. შემომავალი Webhook-ები

ეს endpoint-ები გარე სერვისებიდან გამოიძახება. ფრონტენდიდან მათი გამოყენება არ არის საჭირო.

`POST /flitt/callback/` და `/flitt/callback`

Flitt-ის გადახდის შედეგების webhook.

ველი	მნიშვნელობა
Method	`POST` (CSRF exempt)
Auth	SHA1 signature (currency-specific shared secret)

Side effects: RechargeTransaction.status განახლდება, user.update_balance ეშვება.

`GET/POST /messenger/webhook/` — Facebook Messenger

ველი	მნიშვნელობა
Method	`GET` (verify) + `POST` (events)
Auth	Facebook-ის verify_token (GET) + webhook events (POST)

GET response: <challenge> plain text თუ verify_token სწორია. POST response: "EVENT_RECEIVED".

`GET /facebook/callback/` — FB OAuth callback

OAuth code-ის მისაღები endpoint.

`POST /telegram/webhook/`

ველი	მნიშვნელობა
Method	`POST`
Auth	Telegram Bot API webhook

Response: 200 "OK".

დანართი: ცნობარი

ყველა endpoint-ის სია

#	Path	Method	Auth
1	`/query/`	POST	Hybrid
2	`/sessions/`	GET	Conditional
3	`/chats/`	GET	Session-based
4	`/upload/`	POST	Hybrid
5	`/list_documents/`	POST	Hybrid
6	`/delete_document/`	PATCH	Hybrid + ownership
7	`/chat-history/feedback/<chat_id>/`	POST	Hybrid + ownership
8	`/chat-history/send-email/<chat_id>/`	POST	JWT optional
9	`/feedback/technical/`	POST	JWT optional
10	`/chat-session-action/`	POST	Hybrid + ownership
11	`/link-sessions/`	POST	Hybrid
12	`/recharge/initiate/`	POST	JWT
13	`/recharge/success/`	POST	Payment token
14	`/get-user-balance/`	POST	JWT
15	`/recharge/smart-router/`	POST	JWT
16	`/flitt/recharge/`	POST	JWT
17–18	`/flitt/callback/` & `/flitt/callback`	POST	Signature
19–20	`/flitt/return/` & `/flitt/return`	GET/POST	Payment token
21	`/widget.js`	GET	Public
22	`/widget/query/`	POST	partner_key
23	`/messenger/webhook/`	GET/POST	FB webhook
24	`/facebook/callback/`	GET	OAuth
25	`/telegram/webhook/`	POST	TG webhook

გარე სერვისები

ბექენდი ინტეგრირებულია შემდეგი მესამე-მხარის სერვისებთან: xAI Grok, OpenAI, AWS, Google Vision, PayPal, Flitt, NBG (გაცვლითი კურსი).

API Reference — chkuiskolopi.ge

ავტორიზაცია — მიმოხილვა

შეცდომების ფორმატი

ნაწილი I — Public API (პარტნიორი ინტეგრატორებისთვის)

1.1. Widget Embed — GET /widget.js

გამოყენება

1.2. Direct Query — POST /widget/query/

Request body

Response — 200 OK

შეცდომები

მაგალითი

ნაწილი II — Internal API (Frontend / Mobile / Webhooks)

2.1. ჩატი და სესიები

POST /query/ — მთავარი query endpoint

GET /sessions/ — სესიების ჩამონათვალი

GET /chats/ — ერთი სესიის ისტორია

2.2. ფაილების მართვა

POST /upload/ — ფაილების ატვირთვა

POST /list_documents/ — ფაილების სია

PATCH /delete_document/ — ფაილის წაშლა (soft)

2.3. Feedback და Email

POST /chat-history/feedback/<chat_id>/

POST /chat-history/send-email/<chat_id>/

POST /feedback/technical/

2.4. სესიის მართვა

POST /chat-session-action/

POST /link-sessions/

2.5. ბალანსი და გადახდები

POST /get-user-balance/

POST /recharge/smart-router/ — რეკომენდირებული შევსების endpoint

POST /recharge/initiate/ — PayPal-ის ინიცირება

POST /recharge/success/ — PayPal callback-ის შემდეგ ფრონტიდან

POST /flitt/recharge/ — Flitt-ის ინიცირება (USD direct)

GET/POST /flitt/return/ — Flitt-ის redirect endpoint

2.6. შემომავალი Webhook-ები

POST /flitt/callback/ და /flitt/callback

GET/POST /messenger/webhook/ — Facebook Messenger

GET /facebook/callback/ — FB OAuth callback

POST /telegram/webhook/

დანართი: ცნობარი

ყველა endpoint-ის სია

გარე სერვისები

1.1. Widget Embed — `GET /widget.js`

1.2. Direct Query — `POST /widget/query/`

Response — `200 OK`

`POST /query/` — მთავარი query endpoint

`GET /sessions/` — სესიების ჩამონათვალი

`GET /chats/` — ერთი სესიის ისტორია

`POST /upload/` — ფაილების ატვირთვა

`POST /list_documents/` — ფაილების სია

`PATCH /delete_document/` — ფაილის წაშლა (soft)

`POST /chat-history/feedback/<chat_id>/`

`POST /chat-history/send-email/<chat_id>/`

`POST /feedback/technical/`

`POST /chat-session-action/`

`POST /link-sessions/`

`POST /get-user-balance/`

`POST /recharge/smart-router/` — რეკომენდირებული შევსების endpoint

`POST /recharge/initiate/` — PayPal-ის ინიცირება

`POST /recharge/success/` — PayPal callback-ის შემდეგ ფრონტიდან

`POST /flitt/recharge/` — Flitt-ის ინიცირება (USD direct)

`GET/POST /flitt/return/` — Flitt-ის redirect endpoint

`POST /flitt/callback/` და `/flitt/callback`

`GET/POST /messenger/webhook/` — Facebook Messenger

`GET /facebook/callback/` — FB OAuth callback

`POST /telegram/webhook/`