Протокол

Функции АПИ доступны только по HTTPS-протоколу (SSL)

PHP SDK

Вы можете воспользоваться нашим SDK

Авторизация

Отдельной авторизации не требуется.

Для авторизации необходимо при каждом запросе передать секретный ключ как параметр key POST-запроса. Подробнее о том, как сгенерировать секретный ключ API, читайте в отдельной статье.

Действие

Действие передается как параметр action POST-запроса

Параметры действия

Параметры для действия передаются в формате JSON, закодированного в base64 в параметре params POST-запроса

Примечание
Импорт или экспорт данных по API доступны только на платных тарифах GetCourse. На ознакомительном тарифе этот функционал закрыт.

Формат ответа

Ответ возвращается в формате JSON:

{
        "success":"true/false", // результат вызова
        "action":"вызванное действие",
        "result":{
            "deal_id":"уникальный id заказа",
            "deal_number":"номер заказа",
            "success":"true/false", // результат действия
            "user_id":"id пользователя",
            "user_status":"статус пользователя",
            "payment_link":"ссылка на страницу оплаты",
            "error_message":"сообщение об ошибке",
            "error":"true/false", // наличие ошибок
        }
    }
            

Управление группами пользователя

Метод предназначен для импорта данных, а не для оперативного управления объектами!

Импорт информации о группах пользователя находится по адресу:

https://{account_name}.getcourse.ru/pl/api/users

Для обновления информации о группах пользователя необходимо передать действие update, секретный ключ и параметры пользователя:

Параметры пользователя:

base64_encode
    {
    "user":{
        "id":"id пользователя",
        "group_name": ["Группа 1", "Группа 2"] // список групп
    }
} 

В результате выполнения запроса пользователь будет состоять во всех группах, указанных в списке group_name. Если ранее пользователь состоял в каких-либо группах, не указанных в group_name — он будет удален из этих групп.

Метод предназначен для импорта данных, а не для оперативного управления объектами!

Импорт сделки находится по адресу:

https://{account_name}.getcourse.ru/pl/api/deals

Для добавления сделки необходимо передать действие add, секретный ключ, параметры сделки, параметры пользователя, для которого создается сделка:

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}&params={params}"

Обратите внимание: 

1. Минимально необходимыми параметрами для создания нового заказа являются:

• уникальный код предложения* (либо наименование предложения) + сумма заказа + email пользователя

ИЛИ

• ID предложения + email пользователя.

2. Для редактирования существующего заказа — те же параметры, но также:

• номер заказа

• Если в запросе передан параметр deal_cost, то именно он будет указан в качестве цены для позиции в заказе. При отсутствии параметра deal_cost для позиции в заказе устанавливается цена из предложения.

• Если по offer_id предложение в аккаунте не найдено, то вернется ошибка и заказ не создастся.

Изменение статуса заказа (сделки)

Статус заказа можно изменить по адресу:

https://{account_name}.getcourse.ru/pl/api/deals

Для изменения статуса сделки необходимо передать действие add, секретный ключ, и следующий набор параметров сделки и пользователя:

base64_encode
    {
    "user":{
        "email":"email@yopmail.com"
    },
    "deal":{
        "deal_number":"13667463",
        "deal_status":"new"
    }
}
            

Коды статусов заказа (deal_status)

• new — Новый
• payed — Завершен
• cancelled — Отменен
• false — Ложный
• in_work — В работе
• payment_waiting — Ожидаем оплаты
• part_payed — Частично оплачен
• waiting_for_return — Ожидаем возврата
• not_confirmed — Не подтвержден
• pending — Отложен

Коды статусов платежей (payment_status)

• expected — Ожидается
• accepted — Получен
• returned — Возвращен
• tobalance — Пополнение баланса
• frombalance — Списание с баланса
• returned_to_balance — Начисление на депозит

Коды методов оплаты (payment_type)

• 2CO — 2Checkout
• ALFA — Альфа-банк
• bepaid — bePaid
• BILL — Безналичный расчёт
• CARD — Банковской картой
• CARD_TERMINAL — Банковская карта через терминал
• CASH — Наличные
• cloud_payments — CloudPayments
• cloud_payments_kz — CloudPaymentsKz
• fondy — Fondy
• hutki_grosh — Хуткi Грош
• interkassa — Интеркасса
• INTERNAL — Внутренний баланс
• justclick — Justclick
• kvit — Квитанция в банк
• mandarinpay — MandarinPay
• OTHER — Другое
• payanyway — PayAnyWay
• PAYPAL — PayPal
• perfect_money — Perfect Money
• PERFECTMONEY — Perfect Money
• platim — Platim.ru
• QIWI — Qiwi (устаревшее)
• qiwi_kassa — QIWI Касса
• QUICKTRANSFER — Системы быстрых переводов
• RBK — РБК Деньги
• rbkmoney — РБК Деньги (устаревшее)
• rbkmoney_new — РБК Деньги (2018 г)
• ROBOKASSA — Робокасса
• SBER — Sberbank
• sberbank — Сбербанк эквайринг
• stripe — Stripe
• tinkoff — Тинькофф Банк
• tinkoffcredit — Тинькофф Кредит
• VIRTUAL — Бонусный счет
• walletone — Единая касса
• wayforpay — WayForPay
• WEBMONEY — Webmoney
• yandex_kassa — Яндекс.Касса
• YANDEXMONEY — Яндекс.Деньги
• zpayment — Z-payment
• ebanx — EBANX
• swedbank — Swedbank

Коды валют

• 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

Обратите внимание: Если заказ имеет статус «Завершён» и вы меняете статус при помощи API на любой другой, то активные покупки, связанные с заказом, не будут отменены. То есть без изменения статуса покупки у пользователя сохранится доступ, выданный этой покупкой.

При изменении статуса заказа с помощью API на "Завершен" (payed) в заказе будет создан платеж, так же как при передаче параметра deal_is_paid.

Чтобы забирать доступ по покупке, рекомендуем использовать другой способ:

1. Создайте или используйте существующее дополнительное поле заказа.

2. Затем передайте по API желаемый статус заказа в это дополнительное поле.

3. После этого при помощи настроенного процесса автоматически измените статус заказа в соответствии со значением дополнительно поля.

В результате связанные с заказом покупки будут отменены и пользователь потеряет доступ.

Пример добавления пользователя (PHP)

<?php
$accountName = 'XXXXXX';
$secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
 
$user = [];
$user['user']['email'] = 'xxxxx@xxxxx.xxx';
$user['user']['phone'] = '+74951234567';
$user['user']['first_name'] = 'Василий';
$user['user']['last_name'] = 'Пупкин';
$user['user']['city'] = 'Москва';
$user['user']['country'] = 'Россия';
$user['user']['group_name'] = ['Группа1', 'Группа2'];
$user['system']['refresh_if_exists'] = 1;
 
$json = json_encode($user);
$base64 = base64_encode($json);
 
if( $curl = curl_init() ) {
	curl_setopt($curl, CURLOPT_URL, 'https://' . $accountName . '.getcourse.ru/pl/api/users');
	curl_setopt($curl, CURLOPT_RETURNTRANSFER,true);
	curl_setopt($curl, CURLOPT_POST, true);
	curl_setopt($curl, CURLOPT_POSTFIELDS, 'action=add&key=' . $secretKey . '&params=' . $base64);
	$out = curl_exec($curl);
	echo $out;
	curl_close($curl);
} else {
	echo 'Failed initialization';
}
?>

Export API предназначен для периодической выгрузки данных из Геткурса для анализа. Геткурс только предоставляет данные и не влияет на возможности обработки этих данных во внешних системах.

Важно! Еxport API не предназначен для постоянной выгрузки данных по новым объектам, т. к. в аккаунте действуют ограничения на количество запросов, — 100 запросов за 2 часа к ExportAPI (учитываются все запросы, в т. ч. проверка статуса готовности экспорта). Если необходимо оперативно передавать данные по новым объектам, используйте процессы с операцией «Вызвать URL». Подробнее в статье → «Как настроить callback-вызов из GetCourse».

Export API находится по адресу:

https://{account_name}.getcourse.ru/pl/api/account

Какие данные можно выгружать через API:

1. Пользователи

2. Группы

3. Заказы

4. Платежи

Структура данных для каждого объекта соответствует тому, что выгружается в CSV с помощью интерфейса экспорта в соответствующих разделах

Для получения данных нужно:

1. Отправить действие users, секретный ключ и хотя бы один фильтр объектов для экспорта:

«https://{account_name}.getcourse.ru/pl/api/account/users?key={secret_key}&....»

Вместо «....» добавляются необходимые параметры фильтра.

Если в запрос нужно добавить несколько фильтров, отделите их знаком амперсанд &. Подобная запись аналогична использованию логического оператора «И». В результате будут отобраны объекты, которые удовлетворяют всем условиям фильтра.

«https://{account_name}.getcourse.ru/pl/api/account/users?key={secret_key}&param1=value1&param2=value2...»

Это действие запускает задачу на сбор данных и возвращает ключ экспорта в JSON-строке, который понадобится для проверки статуса готовности и для получения данных.

2. Отправить действие exports, ключ экспорта и секретный ключ:

«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»

Это действие проверяет статус готовности и возвращает поток данных в JSON-строке.

Параметры фильтров:

• Дата создания пользователей
  • created_at[from]=YYYY-MM-DD
  • created_at[to]=YYYY-MM-DD

• Статус пользователя
  • status=active/in_base

• Эл.почта пользователя (несколько почт можно указать через запятую)
  • email=электронная_почта_пользователя

Дополнительные параметры (не являются фильтрами, поэтому для корректного запуска необходимо указать хотя бы один фильтр, как было показано в пункте 1):

ID групп пользователя:

• idgrouplist=id (через запятую будут выгружены все ID групп, в которых состоит пользователь);
• idgrouplist=id_date (через запятую будут выгружены все ID групп, в которых состоит пользователь и даты его добавления в эти группы в формате «ID группы: ГГГГ-ММ-ДД».).

Ознакомиться со списком экспортируемых полей можно в отдельной статье

→ «Экспорт пользователей из системы».

1.2 Для экспорта данных пользователей по группе используйте ID группы при отправке запроса в формате:

«https://{account_name}.getcourse.ru/pl/api/account/groups/{ID}/users?key={secret_key}&....»

Параметр {ID} замените на ID группы. Вместо «....» добавьте хотя бы один из параметров фильтра.

Если в запрос нужно добавить несколько фильтров, отделите их знаком амперсанд &. Подобная запись аналогична использованию логического оператора «И». В результате будут отобраны объекты, которые удовлетворяют всем условиям фильтра.

«https://{account_name}.getcourse.ru/pl/api/account/groups/{ID}/users?key={secret_key}&param1=value1&param2=value2...»

Это действие запускает задачу на сбор данных и возвращает ключ экспорта в JSON-строке, который понадобится для проверки статуса готовности и для получения данных.

Список экспортируемых полей находится в отдельной статье. Дополнительно к ним выгружаются следующие поля:

• ID группы;
• Добавлен в группу — в формате «гггг-мм-дд чч-мм-сс».

2. Далее отправьте действие exports, ключ экспорта и секретный ключ:

«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»

Это действие проверяет статус готовности и возвращает поток данных в JSON-строке.

Параметры фильтров:

• Дата создания пользователей
  • created_at[from]=YYYY-MM-DD
  • created_at[to]=YYYY-MM-DD

• Статус пользователя
  • status=active/in_base

• Дата добавления в группу (дополнение к фильтру group_id)
  • added_at[from]=YYYY-MM-DD
  • added_at[to]=YYYY-MM-DD

2. Отправить действие exports, ключ экспорта и секретный ключ:

«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»

Это действие проверяет статус готовности и возвращает поток данных в JSON-строке.

Параметры фильтров:

• Дата создания заказов
  • created_at[from]=YYYY-MM-DD
  • created_at[to]=YYYY-MM-DD

• Статус заказа
  • status=deal_status
• Дата оплаты заказа

  • payed_at[from]=YYYY-MM-DD

  • payed_at[to]=YYYY-MM-DD

• Дата завершения заказа
  • finished_at[from]=YYYY-MM-DD
  • finished_at[to]=YYYY-MM-DD

• Дата изменения статуса заказа
  • status_changed_at[from]=YYYY-MM-DD
  • status_changed_at[to]=YYYY-MM-DD
• Заказы пользователей определенной группы
  • user_in_group=ID группы
• Заказы пользователя (можно указать несколько ID через запятую)
  • user_id=ID пользователя

Список возможных статусов заказа:

• new
• payed
• cancelled
• in_work
• payment_waiting
• part_payed
• waiting_for_return
• not_confirmed
• pending

2. Отправить действие exports, ключ экспорта и секретный ключ:

«https://{account_name}.getcourse.ru/pl/api/account/exports/{export_id}?key={secret_key}»

Это действие проверяет статус готовности и возвращает поток данных в JSON-строке.

Параметры фильтров:

• Дата создания платежей
  • created_at[from]=YYYY-MM-DD
  • created_at[to]=YYYY-MM-DD

• Статус платежа
  • status=deal_status
• Дата изменения статуса платежа

  
  

  • status_changed_at[from]=YYYY-MM-DD

  • status_changed_at[to]=YYYY-MM-DD

Список возможных статусов платежа:

• expected
• accepted
• returned
• tobalance
• frombalance
• returned_to_balance

Получение справочников дополнительных полей пользователя и дополнительных полей заказа

Находится по адресу:

https://{account_name}.getcourse/pl/api/account/fields

Для получения списка полей необходимо передать действие key (секретный ключ API аккаунта) и action (должен быть указан «Get»):

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}»

На платформе есть возможность индивидуального согласования лимитов. Для уточнения информации обратитесь в поддержку по ссылке.

Чтобы учесть лимиты при загрузке новых данных, отслеживайте статистику использования API.

Для этого:

1. Перейдите в раздел «Профиль» — «Настройки аккаунта» — «АПИ».
2. Нажмите на ссылку «Статистика использования API».

В статистике отображается ежемесячная информация о создании объектов с помощью API.

Причина: превышен лимит в месяц для тарифа аккаунта на создание объектов по API.

Рекомендации:

• скорректировать количество запросов в месяц, чтобы не превышать лимит для текущего тарифа;
• перейти на тариф, который позволяет создавать больше объектов через API.

Причина: попытка создать заказ с несколькими предложениями в рамках одного запроса. Данная возможность на платформе не предусмотрена.

Рекомендации: добавлять каждое предложение при помощи отдельного запроса.

Для этого:

1. Отправьте запрос для создания заказа с одним предложением.
2. Измените уникальный код предложения и добавьте к запросу параметр multiple_offers=1. Номер заказа изменять не нужно.

При выполнении второго запроса в созданный заказ будет добавлено необходимое предложение.

Причина: достигнут лимит количества запросов export api, который составляет 100 запросов за 2 часа.

Рекомендации:

• дождаться обнуления лимита;
• не отправлять одновременно большое количество запросов, так как выполняются они последовательно, и следующий запрос не будет исполнен до завершения предыдущего.

Причина: в запросе на экспорт используются фильтры, под который не попадает ни один объект.

Рекомендации:

• проверить наличие объектов при помощи выборки в аккаунте;
• изменить фильтры в запросе.

Причина: запрос не содержит минимального набора данных.

Рекомендации:

• проверить наличие в запросе минимального набора параметров.

Минимальный набор параметров описан выше [перейти ↑].

Возможные причины: 

1. Данные полей передаются не в теле запроса (body).
2. Выбран неверный тип контента (content-type) для тела запроса (body).
3. Все поля и их значения кодируются в base64.
4. Используется GET-запрос.

Рекомендации:

1. Передавать поля со значениями в теле запроса (body).
2. Для тела запроса выбрать тип контента form-data.
3. Кодировать только значение поля params.
4. Использовать POST-запрос.

Причина: некорректно указано имя аккаунта или ключ API.

Рекомендации: проверить правильность указанного в запросе ключа и имени аккаунта.

Причина: в запросе на изменение данных используется ключ, который дает право только на чтение.

Рекомендации: создать новый ключ, который дает право на запись и чтение.

Возможные причины:

• ошибка в переменной params или её отсутствие;
• значение переменной params не закодировано в base64.

Рекомендации: 

• проверить синтаксические ошибки в значении переменной params  (фигурные скобки, запятые, кавычки и т.д.);
• кодировать значение переменной params в Base64.

Возможные причины:

• ошибка в переменной params или её отсутствие;
• отсутствие в переменной params обязательных данных пользователя.

Рекомендации:

• проверить синтаксические ошибки в значении переменной params (фигурные скобки, запятые, кавычки и т.д.);
• проверить наличие в запросе почты или телефона пользователя.

Если вы столкнулись с иными ошибками или у вас есть дополнительные вопросы о работе API GetCourse, вы можете обратиться в нашу поддержку по ссылке → https://getcourse.ru/contacts.