API


"REST API- თან ურთიერთქმედების ძირითადი პრინციპები

ინტერკასა გარე დეველოპერებს სერვერთან ურთიერთქმედების საშუალებას აძლევს.

ასეთი ურთიერთქმედების ერთ -ერთ გზას წარმოადგენს REST API.
REST API განსაზღვრავს ფუნქციების კომპლექტს, HTTP პროტოკოლის მეშვეობით ურთიერთქმედების განსახორციელებლად. აღნიშნული ფუნქციები იძლევა სისტემის სხვადასხვა რესურსთან წვდომის საშუალებას, მაგალითად ინფორმაციას ინტერკასის სისტემაში საგადახდო დავალებების მიმართულების, სავალუტო კურსების შესახებ. ასევე თანხის განაღდების მექანიზმის შექმნა. შესაბამისად, API ფუნქციები იყოფა ორად: საჯარო და კერძო (პრივატული). კერძო ფუნქციონალის შესაქმნელად სავალდებულოა ინტერკასის სისტემაში პირადი ანგარიშის შექმნა, რომელშიც მოიაზრება API-თან მუშაობა.

ურთიერთქმედება ხორციელდება GET და POST მოთხოვნების გამოყენებით UTF-8 კოდირებით URL https://api.interkassa.com/v1/[resource] . GET- ის მოთხოვნის პარამეტრების კოდი encoding- ით უნდა იყოს კოდირებული.
REST მიდგომის თანახმად მიღების (GET) თხოვნა შემდეგი URL-ის სახით https://api.interkassa.com/v1/[resource] დააბრუნებს მოთხოვნილი რესურსების სიას, ხოლო https://api.interkassa.com/v1/[resource]/[id] რესურსი მითითებული იდენტიფიკატორებით.

IR სერვერის თითოეული პასუხი აუცილებლად შეიცავს სტატუსს და კოდს, სადაც სტატუსი არის საპასუხო სტატუსი, კოდი კი - საპასუხო სტატუსის რიცხობრივი კოდი.

იმ შემთხვევაში თუ მიღებულ პასუხში მითითებულია სტატუსი = "OK" და კოდი = 0, ეს მიუთითებს იმაზე, რომ მოთხოვნა შესრულებულია წარმატებით, საპასუხო მონაცემები გადაეგზავნა მონაცემთა დარგში. პასუხში სტატუსის = "შეცდომის" მიღება მიუთითებს შეკითხვის აღსრულების შეცდომაზე, შეცდომის კოდი იგზავნება კოდის ველში და დამატებით შეტყობინებაში - სიტყვიერი აღწერის შეცდომა.

შენიშვნა: შდეგის გენერირებისას 43101 კოდი შეიძლება დაბრუნდეს, სტატუსი = "OK" დროს კი აღნიშნული კოდი მიუთითებს, რომ შდეგი გენერირებულია ინტერკსის სისტემაში, მაგრამ ჯერ კიდევ არ არის გატარებული საგადახდო სისტემაზე.


ღია რესურსები

1.ვალუტა

დანიშნულება: გაძლევთ სისტემაში გამოყენებული ვალუტებისა და განაკვეთების ჩამონათვალს

URL: URL: https://api.interkassa.com/v1/currency
მოთხოვნა: GET


2.გადახდის სისტემა-შეტანა-გადახდის საშუალება

დანიშნულება: საშუალებას გაძლევთ მიიღოთ საგადახდო დავალებების ჩამონათვალი ინტერკასის სისტემაში შესატანადი

URL: https://api.interkassa.com/v1/paysystem-input-payway

მოთხოვნა: GET


3.გადახდის სისტემა-გამოტანა-გადახდის საშუალება

დანიშნულება: საშუალებას გაძლევთ მიიღოთ ინტერკასის სისტემიდან გამოტანილი საგადახდო დავალებების ჩამონათვალი. თითოეული მიმართულებით მისი იდენტიფიკაცია ბრუნდება სისტემაში, alias- ში, ასევე PRM ელემენტში სავალდებულოდ შესავსები რეკვიზიტების-გასაღებების მოცულობით. ეს გასაღებები გამოიყენება ჩამონათვალის გამოტანის შესაქმნელად.

URL: https://api.interkassa.com/v1/paysystem-output-payway
მოთხოვნა: GET

პასუხების მაგალითები დანართში 1.


პრივატული რესურსები

API-ს პირად ფუნქციებთან წვდომისათვის საჭიროა მომხმარებლის ავტორიზაცია. ამისათვის საჭიროა ანგარიში გახსნილ იქნას ინტერკასის სისტემაში da ანგარიშის პარამეტრებში მონიშნული უნდა იყოს API ფუნქცია (სტანდარტულად ეს ოფცია გამორთულია და ირთვება სისტემაში მომხმარებლის მოთხოვნის შემდეგ).

მომხმარებლის პირადი კაბინეტის ვიზუალი ჩართული API-ით ნაჩვენებია 1 სურათზე.

სურათი 1. მომხმარებლის პირადი მონაცემები ჩართული API- ით

HTTP მოთხოვნის ავტორიზაცია ხდება შესაბამისი სტანდარტული წესების გამოყენებით: მოთხოვნის თან ერთვის HTTP დასათაურება "ავტორიზაცია".ამ პარამეტრის მნიშვნელობა შედგება სიტყვისაგან - "ძირითადი", ცარიელი ხასიათი და დაშიფრულია BASE64 წყვილით ავტორიზაცია:პაროლი, სადაც ავტორიზაცია არის მომხმარებლის ID, პაროლი კი - გასაღები (იხ. სურათი 1).

ასევე, ანგარიშის რესურსებთან მუშაობისათვის, სავალდებულოა ბიზნეს ანგარიშის იდენტიფიკატორის გადაცემა HTTP სათაურში "Ik-Api-Account-Id". აღნიშნულის სესახებ დეტალური ინფორმაცია იხილეთ ქვემოთ.


1.Account

მიზანი: გაძლევთ საშუალებას მიიღოთ მომხმარებლის ანგარიშების სია.

URL: https://api.interkassa.com/v1/account
მოთხოვნა: GET
სათაურები: ავტორიზაცია

პასუხად მოდის ანგარიშების სია , მათ შორის ბიზნეს ანგარიშებიც. ბიზნეს ანგარიშის ID ვალდებულია HTTP დასათაურების "Ik-Api-Account-Id" შესავსებად. მისი შენახვა სავალდებულოა.


2.Checkout

დანიშნულება: მომხმარებელი ღებულობს მის ანგარიშთან დაკავშირებული სალაროების ჩამონათვალს. პასუხში გადმოსცემს ინფორმაციას სალაროების მიხედვით, მათ შორის სისტემაში შესაყვან საგადახდო დავალებებს.


URL: https://api.interkassa.com/v1/checkout
მოთხოვნა: მიიღე
სათაურები: ავტორიზაცია, IK-Api- ანგარიში- Id "


3.Purse

დანიშნულება: საშუალებას მოგცემთ მიიღოთ საფულეების ჩმონათვალი, რომელიც თავისი პარამეტრებით დაკავშირებულია ანგარიშთან.

URL: https://api.interkassa.com/v1/purse
მოთხოვნა: მიიღე
სათაურები: ავტორიზაცია, IK-Api- ანგარიში- Id "


4.Co-invoice

დანიშნულება: გაძლევთ საშუალებას ატვირთოთ საგადახდო დავალებები. თითოეულ გადახდას თან ახლავს მისი ID , რითაც ირიცხება სისტემაში,ასევე შექმნის დრო და რამდენიმე სხვა რიგი პარამეტრი, მათ შორის გადახდის სტატუსი "განცხადების" ველში.

სტატუსები განმარტებულია დანართი 3-ში

URL: https://api.interkassa.com/v1/co-invoice
მოთხოვნა: მიიღე
სათაურები: ავტორიზაცია, IK-Api- ანგარიში- Id "


5.Withdraw

დანიშნულება: საშუალებას იძლევა მიიღოთ შესრულებული მიღებების ჩამონათვალი (GET), ინფორმაცია კონკრეტულ მიღებაზე (GET) და შეიქმნას ახალი მიღება სისტემაში (POST).

URL: https://api.interkassa.com/v1/withdraw
მოთხოვნა: POST
სათაურები: ავტორიზაცია, IK-Api- ანგარიში- Id "

ახალი გამოსვლის შესაქმნელად, საჭიროა POST- ის გენერირება, მოთხოვნის პარამეტრები მოცემულია ქვემოთ

amount - გადასახდელი თანხის ოდენობა. მაგალითი: 100.

paywayId - გამომავალი საგადახდო მიმართულების იდენტიფიკატორი. მაგალითი: 5203c2448f2a2d2409000005.
details[]- რეკვიზიტების წყობა, მაგალითად "ძირითადი ღირებულება". მაგალითი: დეტალები [ბარათი] = 4405882300878265.

purseId არის იდენტიფიკატორი ჩანთა, რომელიც გამოდის. მაგალითი: 108523186000.

calcKey - გადასახდელი თანხის ოდენობის გაანგარიშების ტიპი. ხელმისაწვდომი ღირებულებები: "ikPayerPrice" - ინტერკასის სიტემაში ანგარიშიდან ჩამოწრილი თანხის ოდენობით, "PSPayeeAmount" - საგადახდო სისტემის ვალუტის შესაბამისად, ბენეფიციარის ბალანსზე ჩარიცხული თანხის ოდენობით. სტანდარტულად: ikPayerPrice. მაგალითი: ikPayerPrice.

action - ქმედების ტიპი. ხელმისაწვდომი ფასეულობები: "calc" - გამოთვლა (წარმოება არ ხორციელდება ინტერკასაში), "პროცესი" - გამართვა (წარმოება). სტანდარტულად : "კალკ". მაგალითი: პროცესი.

paymentNo  - სავაჭრო სისტემის წარმოების რიცხვი, ეს ნომერი არის უნიკალური სალაროსთან მიმართებაში. პირობითი პარამეტრი. მაგალითი: 12345

თუ წარმოება წარმატებით შეიქმნა, მაშინ სისტემის პასუხში მონაცემთა ველში აღნიშნულია ინფორმაცია წარმოების შესახებ, მათ შორის სსტემაში წარმოების იდენტიფიკატორი (id) და მისი ქმედითი (state) სტატუსი. წარმოების შექმნისას მისი სტატუსი არ არის საბოლოო, ის მუშავდება საგარეო საგადახდო სისტემით.

წარმოების ნუსხის მისაღებად გამოიყენება GET თხოვნა და ამ დროს მომხმარებლის (მერჩანტის) მიერ შსრულებული წარმოების ჩამონათვალი ბრუნდება. თითოეული წარმოება გადმოსცემს სხვადასხვა ინფორმაციას, მათ შორის მისი სტატუსი,რომლის ველშიც აღნიშნულია "მდგომარეობა" (state).

სტატუსები განმარტებულია დანართში 4-ში

კერძო ფუნქციების პასუხების მაგალითები მოცემულია დანართ 2-ში.


REST API- ის გამოყენებით სავაჭრო ობიექტის გვერდზე დასკვნების განხორციელება

პარტნიორის ვებ-გვერდზე მიღებული შედეგების განსახორციელებლად აუცილებელია მთელი რიგი ქმედებების განხორციელება:

1. ანგარიშზე REST API- ის გამოყენების შესაძლებლობის გააქტიურება.

2. ანგარიშის პარამეტრებში, API სექციაში გასაღების გენერირება და IP ფილტრით პარამეტრების შევსება (იხილეთ სურათი 1). მომხმარებელთა გასაღების და Id- ს შენახვა საკუთრ სისტემაში, ისინი გამოყენებულ იქნება REST API-ის მოთხოვნების ფორმირებისას.

3. ინტერკასის ანგარიშის ბიზნეს id-ის მონაცემების მიღება, ანგარიშის რესურსზე პირადი მოთხოვნის გაგზავნით, არ უნდა დაგვავიწყდეს HTTP დასათაურება - ავტორიზაცია. სისტემაში მისი შენახვა, ის გამოყენებული იქნება შემდგომი მოთხოვნისთვის HTTP დასათაურებაში - Ik-Api-Account-Id.

4. მონაცემებთან წვდომა საფულეების მიხევით, რომლებიც მიბმულია ანგარიშზე საფულის რესურსის საშუალებით, წვდომა საფულეების ნომრებთან, ნაშთებთან HTTP დასათაურების "ავტორიზაცია" Ik-Api-ანგარიშის-Id შევსებით. გარკვეული პერიოდულობით საფულის მონაცემების მოთხოვნა და თქვენს სისტემაში მიმდინარე ბალანსის შენარჩუნება.


5. - id მიმართულება, id ელემენტი;
    - სავალდებულო რეკვიზიტების ჩამონათვალი (PRM ელემენტი), თითოეული რეკვიზიტის შენახვა სავალდებულოა;
          - ძირითადი გასაღების დასახელება დასკვნების შექმნის მოთხოვნაში დეტალების ლექსიკონში გადასაცემის მიზნით, al ელემენტი;
          - რეგულარული გამოსახვა შევსებადი რეკვიზიტების შემოწმების მიზნით, re ელემენტი;
    - მინიმალური და მაქსიმალური დაანგარიშების ჯამი, მინ და მაქს. ელემენტები.

6. დასკვნების ფორმირებისას POST მოთხოვნის გაგზავნა უკან გამოთხოვნის რესურსზე, HTTP -ს ქვესათაურის შევსება ავტორიზაცია, Ik-Api-ანგარიშის Id. მოთხოვნის შინაარსში წარუდგინოს ყველა საჭირო პარამეტრი და ასევე გაუგზავნოს გადახდის ნომრის პარამეტრი - პარტნიორის სისტემაში დაანგარიშების ნომერი.

7. იმ შემთხვევაში თუ მოთხოვნა მუშავდება შეცდომის გარეშე, დასკვნები გენერირდება ინტერკასის სისტამაში, მაშინ მოთხოვნის პასუხის მონაცემების ველი გადმოსცემს დასკვნების შესახბ ინფორმაციას, მათ შორის დასკვნების id-ს ინტერკასის სისტემაში და მის სტატუსს - მდგომარეობა (state). დასკვნების გენერირებისას მისი სტატუსი არ არის საბოლოო. ინტერკასის სისტემაში ის გაიმართება საბოლოო სტატუსამდე, პარტნიორის მონაწილეობის გარეშე.

8. თუ თქვენი პარტნიორი ინარჩუნებს თავის დასკვნებს სისტემაში და უნდა მათი სტატუსების განახლება, შესაძლებელია სტატუსის მოთხოვნა კონკრეტული დასკვნის მიხედვით, ასევე მოთხოვნის მიღება უკანგამოთხოვნის რესურსზე, ინტერკასის სისტემაში დასკვნების id მითითებით. ასე რომ მოთხოვნილი URL ჰგავს https: //api.interkassa .com / v1 / უკან გამოთხოვნა/ [id]. მკაცრად რეკომენდირებულია, რომ შეინარჩუნოთ დასკვნების შესაბამისი id სავაჭრო სისტემაში - ინტერკასის სისტემაში გამომავალი.
IR სისტემის შესაძლო პინების სტატუსი მოცემულია დანართში 4-ში.

9. იმ შემთხვევაში თუ დასკვნების მოთხოვნა წარუმატებელად გენერირდება (ქსელური შეცდომა ან IR სისტემის შეცდომა), მაშინ შეგიძლიათ მოითხოვოთ ინფორმაცია დასკვნაზე, სადაც მითითებულია გადახდის ნომერი,პარტნიორის სისტემაში დასკვნების ნომერი: https://api.interkassa.com/v1/withdraw?paymentNo=[paymentNo ]. თუ დასკვნა შესაბამისი გადახდის ნომრით არ არის ნაპოვნი, მონაცემთა ველი არ იქნება მოცემული. 


დანართი 1. ღია რესურსის გათვალისწინებული პასუხების მაგალითები


დანართი 2. კერძო რესურსით გათვალისწინებული პასუხების მაგალითები

Account

Checkout

Purse

Co-invoice

Withdraw


დანართი 3. ინტერკასის სისტემაში გადახდების სტატუსი

state აღწერა  საბოლოო
0  ახალი გადახდა არა
2 გადახდის მოლოდინი არა
3 მუშავდება საგადახდო სისტემის მიერ არა
4  საგადახდო სისტემის მიერ დაბრუნების პროცესში არა
5 ვადაგადაცილებული  დიახ
6 უკან დაბრუნებული დიახ
7 ჩარიცხულია დიახ
8 გაუქმდა  დიახ
9 გადახდა დაბრუნდა საგადახდო სისტემის მიერ  დიახ

შენიშვნა: აღუწერელი სტატუსის მიღებისას, აუცილებლად უნდა დაუკავშირდეთ IR მხარდაჭერის გუნდს.

 


დანართი 4. დასკვნების სტატუსები შიდა ბანკის სისტემაში

 

state აღწერა საბოლოო
1 მიმდინარე მოდერაციის შემოწმება არ არის არა
2 დამტკიცებულია მოდერაციის მიხედვით არა
3 გაუქმებულია  მოდერაციის მიერ დიახ
4 გაყინული  არა
5 დაცული არა
6 საგადახდო სისტემით დამუშავება არა
7 ჩარიცხვა არა
8 გატარებული დიახ
9 გაუქმებული  დიახ
11 დაბრუნებული დიახ
12 საგადახდო სისტემაში გენერირებული დასკვნა , მაგრამ ჯერ არ გაკეთებულა  არა

შენიშვნა: თუ მიიღებთ რაიმე აღუწერელ სტატუსს, უნდა დაუკავშირდეთ სისტემის მხარდაჭერის გუნდს.

გადახდების მიხედვით:

payerWriteoff - თანხის ჩამოწერა გამომგზავნთან (გამომგზავნის საფულის ვალუტაში)

payeeReceive - საგადახდო სისტემა ჩარიცხული თანხა  (საგადახდო სისტემა ინტერკასსას საფულის ვალუტაში)

ikFee - ინტერკასსას საკომისიო (საგადახდო სისტემა ინტერკასსას საფულის ვალუტაში)

ikPrice - გასაყვანი თანხა (საგადახდო სისტემა ინტერკასსას საფულის ვალუტაში)

ikPsPrice - საგადახდო სისტემაში გასაყვანი თანხა (+ საკომისიო)  (ინტერკასსას საფულის ვალუტაში)

psAmount - მიმღებისთვის გადარიცხული თანხა // payerAmount; 100 // ikPrice * ps ვალუტა

psFeeIn - payerFee; 0.8

psFeeOut - payeeFee

psCost - გაყვანის  ოპერაციის თვითღირებულება (Deprecated)

ikIncome - გაყვანის  ოპერაციის მომგებიანობა (Deprecated)

psValue - გასაგზავნი თანხა // $ psAmount + $ psFeeIn

psPrice - ანგარიშიდან ჩამოსაწერი თანხა // $ $ psValue + $ psFeeOut

psCurRate - საგადახდო სისტემის ვალუტის კოეფიციენტი

detail - რეკვიზიტები თანხის გაყვანისთვის

ტრანზაქვიის მიხედვით:

payerAmount - გასაგზავნი თანხა

payerFee - გაგზავნის საკომისიო

payerPrice - ჩამოსაწერი თანხა

payerExchFee - კონვერტაციის საკომისიო

payeeAmount - მიღებული თანხა

payeeFee -  მიღების საკომისიო

payeePrice - დარიცხული თანხის ოდენობა

exchRate - გაცვლითი კურსი, კონვერტაციის საკომისიოს გარეშე