დეველოპერები

ყველაფერი, რაც ინჟინერს - ან AI აგენტს - სჭირდება waybill.ge-თან ინტეგრაციისთვის. პროდუქტის მთავარი პროგრამული ინტერფეისი არის ჰოსტინგური MCP (Model Context Protocol) სერვერი; მის გვერდით არის მცირე საჯარო REST API და მანქანურად წაკითხვადი აღმოჩენის ფაილები.

სწრაფი ცნობარი

რესურსი URL
MCP მისამართი /mcp (streamable HTTP)
აგენტების ინდექსი (llms.txt) /llms.txt
OpenAPI სპეციფიკაცია /openapi.json
API ცნობარი (Swagger UI) /docs
საჯარო REST API /api/v1/
OAuth აღმოჩენა /.well-known/oauth-protected-resource/mcp/
საიტის რუკა /sitemap.xml

Markdown- პირველ რიგში: ამ საიტის ყველა საჯარო გვერდი ხელმისაწვდომია text/markdown ფორმატშიც - გამოგზავნეთ Accept: text/markdown ჰედერი ან დაამატეთ გზას .md (მაგალითად /developers.md).

ავტორიზაცია და უფლებები (scopes)

ორი ტიპის კრედენციალი, ორივე იგზავნება Bearer ტოკენად /mcp-ზე:

  1. OAuth 2.1 (რეკომენდებულია აგენტების პლატფორმებისთვის: claude.ai, Claude Code, ChatGPT). Grok Bot იმავე ანგარიშს იყენებს. Authorization-code ნაკადი PKCE-ით; მხარდაჭერილია დინამიური კლიენტის რეგისტრაცია (RFC 7591). Scope მოდელი:
    • mcp - წვდომა მომხმარებლის RS.GE ზედნადებების ინსტრუმენტებზე და Balance.ge-ის მხოლოდ წაკითხვად ბუღალტრულ ინსტრუმენტებზე, ერთი და იგივე დადასტურებით. საცდელი პერიოდი მოიცავს სრულ წვდომას ყველა ფუნქციაზე. თვიური მოქმედებების ლიმიტი მაინც მოქმედებს. Balance-ის ინსტრუმენტები დავთარში არ აგზავნიან და არ წერენ. აღმოჩენა იწყება /.well-known/oauth-protected-resource/mcp/-დან.
  2. API გასაღებები (rsk_live_...) იქმნება პანელში, API keys განყოფილებაში. გასაღები ერთი კომპანიის ანგარიშზეა (tenant) მიბმული, ნებისმიერ დროს გაუქმებადია, ჩანს მხოლოდ ერთხელ შექმნისას და სერვერზე ინახება Argon2 ჰეშად. გასაღებები იმავე ანგარიშს და იმავე თვიურ ლიმიტს იყენებენ, რასაც OAuth ტოკენები.

არასდროს ჩააშენოთ კლიენტში RS.GE სერვის-პაროლი ან Balance.ge-ის API პაროლი; თითოეული ერთხელ შეგყავთ პანელში და ინახება დაშიფრული.

MCP ინსტრუმენტები

სერვერი გთავაზობთ ტიპიზებულ ინსტრუმენტებს RS.GE ზედნადების სრული ციკლისთვის: save_waybill_draft, activate_waybill, close_waybill, cancel_waybill, confirm_waybill, reject_waybill, save_invoice_from_waybill, ასევე წაკითხვის ინსტრუმენტები (get_waybill, list_seller_waybills, list_buyer_waybills, lookup_name_by_tin, lookup_taxpayer_info, list_units, list_waybill_types, list_transport_types) და სისტემური ინსტრუმენტები (check_credentials, get_quota_status, get_egress_ip, whoami).

იმავე სერვერზე არის Balance.ge-ის მხოლოდ წაკითხვადი ინსტრუმენტები დაკავშირებული cloud.balance.ge კომპანიებისთვის: balance_list_companies, balance_check_credentials, balance_list_clients, balance_list_vendors, balance_list_items, balance_list_employees, balance_list_warehouses, balance_list_branches, balance_list_price_types, balance_get_stocks, balance_get_prices, balance_client_balances, balance_vendor_balances, balance_fetch_general_ledger, balance_cash_flow, balance_open_financials, balance_open_operations. ეს ინსტრუმენტები კითხვებზე პასუხობენ. დავთარში არ აგზავნიან და არ წერენ.

ყველა ინსტრუმენტი აბრუნებს სტრუქტურირებულ JSON პასუხს {ok, data | code+message} ფორმით.

საჯარო REST API

მინიმალური, ავტორიზაციის გარეშე ხელმისაწვდომი ინტერფეისი:

  • GET /api/v1/plans - მიმდინარე გეგმების კატალოგი (სახელები, ფასები ლარში, კვოტები) ტიპიზებულ JSON-ად
  • GET /health - სერვისის მდგომარეობა

ორივე აღწერილია ტიპიზებული სქემებით /openapi.json-ში.

ვერსიები და მოძველების პოლიტიკა

  • REST ინტერფეისი ვერსიონირებულია URL-ის გზაში (/api/v1/). შემლახავი ცვლილებები გამოდის ახალი ვერსიის გზაზე; v1-ის პასუხების ფორმა ვერსიის აწევის გარეშე არ შეიცვლება.
  • MCP ინსტრუმენტების სქემები იცვლება მხოლოდ დამატებით: ველები ემატება და არა იშლება.
  • როცა რომელიმე ინტერფეისი მოხსნას ელოდება, ამას ვაცხადებთ მინიმუმ 6 თვით ადრე: შესაბამის პასუხებს ემატება Deprecation და Sunset ჰედერები (RFC 8594) და ცვლილება ქვეყნდება ამ გვერდზე.

ლიმიტები და კვოტები

  • საჯარო REST API იზღუდება კლიენტის IP-ის მიხედვით. პასუხებს ახლავს სტანდარტული rate-limit ჰედერები (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); ლიმიტის გადაჭარბება აბრუნებს 429-ს Retry-After ჰედერით.
  • MCP ინსტრუმენტების გამოძახებები ხარჯავს გეგმის კვოტას. დარჩენილი კვოტა შეამოწმეთ get_quota_status ინსტრუმენტით; გადაჭარბება აბრუნებს სტრუქტურირებულ QUOTA_EXCEEDED შეცდომას.

დაწყება

  1. დარეგისტრირდით (14-დღიანი საცდელი პერიოდი, ბარათი არ არის საჭირო)
  2. დააკავშირეთ სისტემა პანელში. RS.GE: ინსტრუქცია. Balance (მხოლოდ წაკითხვა): /dashboard/connect-balance. დასაწყებად ერთი საკმარისია.
  3. დაამატეთ MCP სერვერი თქვენს ასისტენტს. Cursor-ის მომხმარებლები: იხილეთ Cursor-თან დაკავშირების სექცია. Connector გვერდზე მზა ინსტრუქციებია claude.ai-სთვის, Claude Cowork-ისთვის, Claude Desktop-ისთვის, Claude Code-ისა და Codex-ისთვის. ChatGPT და Grok Bot იმავე ანგარიშს იყენებენ. ან შექმენით API გასაღები სხვა კლიენტებისთვის.

ინტეგრაციის კითხვები: hello@waybill.ge.

Cursor-თან დაკავშირება

ეს არ არის Cursor Marketplace-ის ჩამონათვალი. ეს არის პირდაპირი კონექტორი ჰოსტინგური MCP სერვერისკენ.

გახსნა Cursor-ში

თუ Cursor არ გაიხსნა, გამოიყენეთ ვებ ინსტალერი.

ან ჩასვით Cursor-ის MCP პარამეტრებში

{ "mcpServers": { "waybill": { "url": "https://waybill.ge/mcp/" } } }

ინსტალაციის შემდეგ გაიარეთ ავტორიზაცია waybill.ge-ზე. ანგარიში და მინიმუმ ერთი დაკავშირებული სისტემა (RS.GE ან Balance) მაინც გჭირდებათ.