API Call and Response Format Documentation
Please note: The information in the article does not replace the basic knowledge needed to use the API functionality. The article is intended for experienced users.
Protocol
API functions are available only via HTTPS protocol (SSL)
PHP SDK
You can use our SDK
Authorization
No separate authorization is required.
For authorization, it is necessary to pass the secret key as the key parameter of the POST request at each request
Action
The action is passed as an action parameter of the POST request
Action Parameters
The parameters for the action are transmitted in base64-encoded JSON format in the params parameter of the POST request
Note
Data import or export via API is only available on GetCourse paid tariffs. This functionality is closed on the trial tariff.
Response format
The response is returned in JSON format:
{ "success":"true/false", // the result of the call "action":"triggered action", "result":{ "deal_id":"unique order id", "deal_number":"order number", "success":"true/false", // the result of the action "user_id":"user id", "user_status":"user status", "payment_link":"link to the payment page", "error_message":"error message", "error":"true/false", // presence of errors } }
Importing users
The method is intended for data import, not for quick object management!
The user's import is located at:
"https://{account_name}.getcourse.io/pl/api/users"
To add a user, you need to send an action add, the secret key and the parameters of the user being added:
curl -i -H "Accept: application/json; q=1.0, */*; q=0.1" "https://{account_name}.getcourse.ru/pl/api/users" -d "action=add&key={secret_key}¶ms={params}"
User Parameters:
base64_encode { "user":{ "email":"email", "phone":"phone", "first_name":"name", "last_name":"surname", "city":"city", "country":"country", "group_name":[ // to add a user to groups "Group1", // easy addition to a group ["Group2", "2023-05-01 21:21"], // adding to a group with an indication of an arbitrary moment ["Group4", "2023-05-02"] ], "addfields":{"Additional.field1":"value","Additional.field12":"value"} // to add additional user fields }, "system":{ "refresh_if_exists":0, // whether to update an existing user 1/0 yes/no "partner_email":"email of the partner (for the user)*" }, "session":{ "utm_source":"", "utm_medium":"", "utm_content":"", "utm_campaign":"", "utm_group":"", "gcpc":"", "gcao":"", "referer":"" } }
If there is no user with the specified email in the system, a new user will be created.
If the user exists and system.refresh_if_exists == 1 the user's data will be updated, and the list of his groups will be supplemented with the groups specified in the user.group_name parameter. If this flag is not set, then no user data will be changed.
Data from the object session will be recorded as the parameters of registration of a new user. If data is being updated (only when system.refresh_if_exists == 1), then the previous ones will be replaced.
There are two different ways to set up a partner for a user:
а) using the parameter system.partner_email;
б) using the parameter session.gcpc (has a higher priority).
If the partner specified for the user being created/updated is If there is, then the user in the system will be marked as a referral of this partner. If the partner user does not exist, an error will be returned. If a partner user exists but is not a partner, then the specified user will automatically receive the partner status.
Managing user groups
The method is intended for importing data, and not for quick object management!
Import information about user groups is located at:
"https://{account_name}.getcourse.ru/pl/api/users"
To update information about user groups, you need to send an action update, secret key and user parameters:
User parameters:
base64_encode { "user":{ "id":"user ID", "group_name": ["Group 1", "Group 2"] // list of groups } }
As a result of executing the request, the user will be a member of all the groups specified in the list group_name. ЕIf the user previously belonged to any groups not specified in the group_name — he will be removed from these groups.
Import orders
The method is intended for data import, not for quick object management!
The import of the transaction is located at:
"https://{account_name}.getcourse.io/pl/api/deals"
To add a transaction, you need to send an action add, secret key, transaction parameters, parameters of the user for whom the transaction is being created:
curl -i -H "Accept: application/json; q=1.0, */*; q=0.1" "https://{account_name}.getcourse.ru/pl/api/deals" --data "action=add&key={secret_key}¶ms={params}"
base64_encode { "user":{ // similar to importing a user }, "system":{ "refresh_if_exists":0, // whether to update an existing user 1/0 yes/no "partner_email":"email of the partner (for the user)*", "multiple_offers":0, // add multiple offers to order 1/0 "return_payment_link":0, // return the payment link 1/0 "return_deal_number":0 // return order number 1/0 }, "session":{ // similar to importing a user }, "deal":{ "deal_number":"order number", "offer_code":"unique offer code", "product_title":"name of the offer", "product_description":"description of the offer", "quantity":1, // quantity "deal_cost":"order amount", "deal_status":"order status code", "deal_is_paid": "no", // paid yes/no 1/0 "manager_email":"manager's email", "deal_created_at":"order date", "deal_finished_at":"date of payment/order completion", "deal_comment":"comment", "payment_type":"payment type from the list", "payment_status":"payment status from the list", "partner_email":"email of the partner (for the order)", "addfields":{"Additional.field 1":"value","Additional.field 2":"value"}, // to add additional order fields "deal_currency":"order currency code" // for example, "EUR", the parameter is optional if it is not used in the request - the order currency will be your base currency } }
To import a transaction, there must be a user - the owner of the transaction.
If the transferred user does not exist, it is created.
If there is a user with the specified email, then he is used as the owner of the order.
If the paramert system.refresh_if_exists == 1 If the user exists, then his data will be updated similarly to the user import operation (with the exception of the session object, see below)
When importing a transaction, it is checked whether there is a transaction with the specified number.
Depending on this, a new deal is created, or an existing one is updated.
If the flag system.multiple_offers == 1 and the existing order is updated, then the transferred positions in the transaction добавляются to the existing ones, and do not replace them.
Parameter system.refresh_if_exists it does not affect the creation/updating of the transaction in any way (this parameter is used only for users!).
Object session when importing a transaction, it contains UTM parameters that are fixed as the context for creating an order.
Additionally, if a new user is created when importing a transaction, the session object is used in the same way as the user registration context. However, when updating user data when importing a transaction, the session object is used only for the transaction, but not for the user.
The order may have an indication of a partner other than the user's partner. The order partner can be set in two ways:
а) using the parameterdeal.partner_email;
б) using the parameter session.gcpc (has a higher priority).
If the partner specified for the transaction exists, then this partner will be installed for it.
If the partner user does not exist, an error will be returned.
If a partner user exists but is not a partner, then the specified user will automatically receive the partner status.
Pay attention:
1. The minimum necessary parameters for creating a new order are:
- unique offer code* or the name of the offer
- order amount
- user's email
To edit an existing order — those same parameters, but also:
- order number
- parameter refresh_if_exists = 1
* - located in the settings of the required offer:
Changing the status of an order (transaction)
The order status can be changed at:
https://{account_name}.getcourse.ru/pl/api/deals
To change the status of a transaction, you must pass an action add, the secret key, and the following set of transaction and user parameters:
base64_encode { "user":{ "email":"email@yopmail.com" }, "deal":{ "deal_number":"13667463", "deal_status":"new" } }
Order status codes (deal_status)
- new
- payed
- cancelled
- false
- in_work
- payment_waiting
- part_payed
- waiting_for_return
- not_confirmed
- pending
Payment status codes (payment_status)
- expected
- accepted
- returned
- tobalance
- frombalance
- returned_to_balance
Codes of payment methods (payment_type)
- 2CO
- ALFA
- BILL
- CARD
- CARD_TERMINAL
- CASH
- cloud_payments
- cloud_payments_kz
- fondy
- hutki_grosh
- interkassa
- INTERNAL
- justclick
- kvit
- OTHER
- payanyway
- PAYPAL
- perfect_money
- PERFECTMONEY
- QIWI
- qiwi_kassa
- QUICKTRANSFER
- RBK
- rbkmoney
- rbkmoney_new
- ROBOKASSA
- SBER
- sberbank
- tinkoff
- tinkoffcredit
- VIRTUAL
- walletone
- wayforpay
- WEBMONEY
- yandex_kassa
- YANDEXMONEY
- ZPAYMENT
- prodamus
- ebanx
- swedbank
Currency codes
- RUB
- USD
- EUR
- GBP
- BYR
- BYN
- KZT
- UAH
- AUD
- DKK
- CHF
- SEK
- ZAR
- AMD
- RON
- BRL
- ILS
- MYR
- SGD
- KGS
- CAD
- MXN
- JPY
- UZS
- PLN
- AZN
- AED
- TRY
- INR
- RSD
- CZK
- MNT
- NZD
Please note: If the order has the status «Completed» and you change the status using the API to any other, then active purchases related to the order will not be canceled. That is, without changing the purchase status, the user will retain the access granted by this purchase.
To get access to the purchase, we recommend using another method:
1. Create or use an existing additional order field.
2. Then send the desired order status via the API to this additional field.
3. After that, using the configured process, automatically change the order status according to the value of the additional field.
As a result, the purchases associated with the order will be canceled and the user will lose access.
Example of adding a user (PHP)
<span style="color: #000000; font-weight: bold;"><?php</span> <span style="color: #000088;">$accountName</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'XXXXXX'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$secretKey</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span> <span style="color: #339933;">=</span> <span style="color: #009900;">[</span><span style="color: #009900;">]</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'user'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'email'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'xxxxx@xxxxx.xxx'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'user'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'phone'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'+74951234567'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'user'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'first_name'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'Василий'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'user'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'last_name'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'Пупкин'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'user'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'city'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'Москва'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'user'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'country'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #0000ff;">'Россия'</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'user'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'group_name'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #009900;">[</span><span style="color: #0000ff;">'Группа1'</span><span style="color: #339933;">,</span> <span style="color: #0000ff;">'Группа2'</span><span style="color: #009900;">]</span><span style="color: #339933;">;</span> <span style="color: #000088;">$user</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'system'</span><span style="color: #009900;">]</span><span style="color: #009900;">[</span><span style="color: #0000ff;">'refresh_if_exists'</span><span style="color: #009900;">]</span> <span style="color: #339933;">=</span> <span style="color: #cc66cc;">1</span><span style="color: #339933;">;</span> <span style="color: #000088;">$json</span> <span style="color: #339933;">=</span> <span style="color: #990000;">json_encode</span><span style="color: #009900;">(</span><span style="color: #000088;">$user</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #000088;">$base64</span> <span style="color: #339933;">=</span> <span style="color: #990000;">base64_encode</span><span style="color: #009900;">(</span><span style="color: #000088;">$json</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #b1b100;">if</span><span style="color: #009900;">(</span> <span style="color: #000088;">$curl</span> <span style="color: #339933;">=</span> <span style="color: #990000;">curl_init</span><span style="color: #009900;">(</span><span style="color: #009900;">)</span> <span style="color: #009900;">)</span> <span style="color: #009900;">{</span> <span style="color: #990000;">curl_setopt</span><span style="color: #009900;">(</span><span style="color: #000088;">$curl</span><span style="color: #339933;">,</span> CURLOPT_URL<span style="color: #339933;">,</span> <span style="color: #0000ff;">'https://'</span> <span style="color: #339933;">.</span> <span style="color: #000088;">$accountName</span> <span style="color: #339933;">.</span> <span style="color: #0000ff;">'.getcourse.ru/pl/api/users'</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #990000;">curl_setopt</span><span style="color: #009900;">(</span><span style="color: #000088;">$curl</span><span style="color: #339933;">,</span> CURLOPT_RETURNTRANSFER<span style="color: #339933;">,</span><span style="color: #009900; font-weight: bold;">true</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #990000;">curl_setopt</span><span style="color: #009900;">(</span><span style="color: #000088;">$curl</span><span style="color: #339933;">,</span> CURLOPT_POST<span style="color: #339933;">,</span> <span style="color: #009900; font-weight: bold;">true</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #990000;">curl_setopt</span><span style="color: #009900;">(</span><span style="color: #000088;">$curl</span><span style="color: #339933;">,</span> CURLOPT_POSTFIELDS<span style="color: #339933;">,</span> <span style="color: #0000ff;">'action=add&key='</span> <span style="color: #339933;">.</span> <span style="color: #000088;">$secretKey</span> <span style="color: #339933;">.</span> <span style="color: #0000ff;">'¶ms='</span> <span style="color: #339933;">.</span> <span style="color: #000088;">$base64</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #000088;">$out</span> <span style="color: #339933;">=</span> <span style="color: #990000;">curl_exec</span><span style="color: #009900;">(</span><span style="color: #000088;">$curl</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #b1b100;">echo</span> <span style="color: #000088;">$out</span><span style="color: #339933;">;</span> <span style="color: #990000;">curl_close</span><span style="color: #009900;">(</span><span style="color: #000088;">$curl</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #009900;">}</span> <span style="color: #b1b100;">else</span> <span style="color: #009900;">{</span> <span style="color: #b1b100;">echo</span> <span style="color: #0000ff;">'Failed initialization'</span><span style="color: #339933;">;</span> <span style="color: #009900;">}</span> <span style="color: #000000; font-weight: bold;">?></span>
Export API
The Export API is designed to periodically upload data from the Getcourse for analysis.
The getcourse only provides data and does not affect the processing capabilities of this data in external systems.
The Export API is not designed for fast data transfer separately for each object.
Located at address:
https://{account_name}.getcour...
What data can be uploaded via the API:
The data structure for each object corresponds to what is uploaded to CSV using the interface export in the relevant sections
Pay attention:
— API exports are performed in a single stream, i.e. it is not possible to process a request for the formation of a new export file until the formation of the export file for the previous request is completed;
No more than 100 requests related to the export API methods can be processed within the framework of one account in 2 hours.
Export Users
To get the data, you need:
1. Send Action users, the secret key and although there would be one object filter to export:
«https://{account_name}.getcourse.ru/pl/api/account/users?key={secret_key}&....»
The necessary filter parameters are added instead of "...." (see below).
This action starts a task to collect data and returns the export key in the JSON string, which will be needed to check the readiness status and to receive data.
2. Send Action exports, export key and secret key:
«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»
This action checks the ready status and returns a data stream in a JSON string.
Filter Parameters:
- User creation date
- created_at[from]=YYYY-MM-DD
- created_at[to]=YYYY-MM-DD
- User status
- status=active/in_base
You can get acquainted with the list of exported fields in a separate article.
Export Groups
The data can be obtained in one of the following ways:
1.1 To get list of all groups users need to submit an action groups and the secret key:
«https://{account_name}.getcourse.ru/pl/api/account/groups?key={secret_key}»
The following data is uploaded:
- id — ID groups;
- name — group name;
- last_added_at — date and time when the last user was added to the group in the format "yyyy-mm-dd hh-mm-ss". If users have not been added to the group yet, the value will be "null".
1.2 To export data users by group use the group ID when sending a request in the format:
«https://{account_name}.getcourse.ru/pl/api/account/groups/{ID}/users?key={secret_key}&....»
Replace the {ID} parameter with the group ID. Instead of "...." add at least one of the filter parameters (see below).
This action starts a task to collect data and returnsthe export key in the JSON string, which will be needed to check the readiness status and to receive data.
The list of exported fields is in a separate article. In addition to them, the following fields are unloaded:
- Group ID;
- Added to the group -in the format "yyyy-mm-dd hh-mm-ss".
2. Next, send the action exports, export key and secret key:
«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»
This action checks the ready status and returns a data stream in a JSON string.
Filter Parameters:
- User creation date
- created_at[from]=YYYY-MM-DD
- created_at[to]=YYYY-MM-DD
- User status
- status=active/in_base
- Date added to the group (addition to the group_id filter)
- added_at[from]=YYYY-MM-DD
- added_at[to]=YYYY-MM-DD
Export Orders
To get the data, you need:
1. Send Action deals, the secret key and although there would be one object filter to export
«https://{account_name}.getcourse.ru/pl/api/account/deals?key={secret_key}&....»
The necessary filter parameters are added instead of "...." (see below).
This action starts a task to collect data and returns export key in a JSON string, кwhich will be needed to check the readiness status and to receive data.
2. Send Action exports, export key and secret key:
«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»
This action checks the ready status and returns a data stream in a JSON string.
Filter Parameters:
- Date of creation of orders
- created_at[from]=YYYY-MM-DD
- created_at[to]=YYYY-MM-DD
- Order status
- status=deal_status
- Order payment date
payed_at[from]=YYYY-MM-DD
payed_at[to]=YYYY-MM-DD
- Order completion date
- finished_at[from]=YYYY-MM-DD
- finished_at[to]=YYYY-MM-DD
- Date of order status change
- status_changed_at[from]=YYYY-MM-DD
- status_changed_at[to]=YYYY-MM-DD
List of possible order statuses:
- new
- payed
- cancelled
- in_work
- payment_waiting
- part_payed
- waiting_for_return
- not_confirmed
- pending
Exporting payments
To get the data, you need:
1. Send Action payments, the secret key and although there would be one object filter to export
«https://{account_name}.getcourse.ru/pl/api/account/payments?key={secret_key}&....»
The necessary filter parameters are added instead of "...." (see below).
This action starts a task to collect data and returns the export key in the JSON string, which will be needed to check the readiness status and to receive data.
2. Send Action exports, export key and secret key:
«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»
This action checks the ready status and returns a data stream in a JSON string.
Filter Parameters:
- Payment creation date
- created_at[from]=YYYY-MM-DD
- created_at[to]=YYYY-MM-DD
- Payment status
- status=deal_status
- Date of payment status change
status_changed_at[from]=YYYY-MM-DD
status_changed_at[to]=YYYY-MM-DD
List of possible payment statuses:
- expected
- accepted
- returned
- tobalance
- frombalance
- returned_to_balance
You can see the list of exported fields in;article.
Getting directories of additional user fields and additional order fields
Located at address
"https://{account_name}.getcourse.io/pl/api/fields"
To get a list of fields, you need to send an action key (account API secret key) and action ("Get" must be specified):
curl -i -H «Accept: application/json; q=1.0, */*; q=0.1» «https://{account_name}.getcourse.ru/pl/api/account/fields» -d «action=get&key={secret_key}»