Документация по формату вызова и ответа API

Ссылка на это место страницы: #1

Импорт пользователей

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

Импорт пользователя находится по адресу:
https://{account_name}.getcourse.ru/pl/api/users

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

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

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

base64_encode
    {
        "user":{
            "email":"email",
            "phone":"телефон",
            "first_name":"имя",
            "last_name":"фамилия",
            "city":"город",
            "country":"страна",
            "group_name":[ // для добавления пользователя в группы
                "Группа1", // простое добавление в групп
                ["Группа2", "2018-08-01 21:21"], // добавление в группу с указанием произвольного момента
                ["Группа4", "2018-08-02"]
            ],
            "addfields":{"Доп.поле1":"значение","Доп.поле2":"значение"} // для добавления дополнительных полей пользователя
        },
        "system":{
            "refresh_if_exists":0, // обновлять ли существующего пользователя 1/0 да/нет
            "partner_email":"email партнера (для пользователя)*"
        },
        "session":{
            "utm_source":"",
            "utm_medium":"",
            "utm_content":"",
            "utm_campaign":"",
            "utm_group":"",
            "gcpc":"",
            "gcao":"",
            "referer":""
        }
    }

Если в системе не существует пользователя с указанным email — будет создан новый пользователь.

Если пользователь существует и system.refresh_if_exists == 1 — данные пользователя будут обновлены, а список его групп дополнен группами, указанными в параметре user.group_name. Если этот флаг не установлен, то никакие данные пользователя изменены не будут.

Данные из объекта session будут зафиксированы как параметры регистрации нового пользователя. Если происходит обновление данных (только при system.refresh_if_exists == 1), то предыдущие будут заменены.

Для пользователя можно установить партнера двумя разными способами:

а) с помощью параметра system.partner_email;

б) с помощью параметра session.gcpc (имеет более высокий приоритет).

Если указанный для создаваемого/обновляемого пользователя партнер существует, то пользователь в системе будет помечен как реферал этого партнера. Если пользователь-партнер не существует — будет возвращена ошибка. Если пользователь-партнер существует, но не является партнером, то указанный пользователь автоматически получит статус партнера.

Ссылка на это место страницы: #2

Импорт заказов

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

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

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

base64_encode
    {
        "user":{
            // как в импорте пользователя
        },
        "system":{
            "refresh_if_exists":0, // обновлять ли существующего пользователя 1/0 да/нет
            "partner_email":"email партнера (для пользователя)*",
            "multiple_offers":0, // добавлять несколько предложений в заказ 1/0
            "return_payment_link":0, // возвращать ссылку на оплату 1/0
            "return_deal_number":0 // возвращать номер заказа 1/0
        },
        "session":{
            // как в импорте пользователя
        },
        "deal":{
            "deal_number":"номер заказа",
            "offer_code":"уникальный код предложения",
            "product_title":"наименование предложения",
            "product_description":"описание предложения",
            "quantity":1, // количество
            "deal_cost":"сумма заказа",
            "deal_status":"код статуса заказа",
            "deal_is_paid": "нет", // оплачен да/нет 1/0
            "manager_email":"email менеджера",
            "deal_created_at":"дата заказа",
            "deal_finished_at":"дата оплаты/завершения заказа",
            "deal_comment":"комментарий",
            "payment_type":"тип платежа из списка",
            "payment_status":"статус платежа из списка",
            "partner_email":"email партнера (для заказа)",
            "addfields":{"Доп.поле1":"значение","Доп.поле2":"значение"}, // для добавления дополнительных полей заказа
            "deal_currency":"код валюты заказа" // например, "EUR", параметр не является обязательным, если он не используется в запросе - валютой заказа будут рубли (RUB)
            "funnel_id":"ID доски продаж",
            "funnel_stage_id":"ID этапа на доске продаж"
        }
    }

Для импорта сделки обязательно должен существовать пользователь — владелец сделки.
Если переданный пользователь не существует — он создается.
Если существует пользователь с указанным email, то он используется как владелец заказа.
Если передан параметр system.refresh_if_exists == 1 И пользователь существует, то его данные будут обновлены аналогично операции импорта пользователя (за исключением объекта session — см. далее)

При импорте сделки проверяется, существует ли сделка с указанным номером.
В зависимости от этого создается новая сделка, или обновляется существующая.
Если флаг system.multiple_offers == 1 и обновляется существующий заказ, то переданные позиции в сделке добавляются к существующим, а не заменяют их.

Параметр system.refresh_if_exists никак не влияет на создание/обновление сделки (этот параметр используется только для пользователей!).

Объект session при импорте сделки содержит UTM-параметры, которые фиксируются как контекст создания заказа.
Дополнительно, если при импорте сделки происходит создание нового пользователя, то объект session используется так же и как контекст регистрации пользователя. Однако, при обновлении данных пользователя при импорте сделки объект session используется только для сделки, но не для пользователя.

Заказ может иметь указание на партнера, отличное от партнера пользователя. Партнер заказа может быть установлен двумя способами:
а) с помощью параметра deal.partner_email;
б) с помощью параметра session.gcpc (имеет более высокий приоритет).
Если указанный для сделки партнер существует, то для нее будет установлен этот партнер.
Если пользователь-партнер не существует — будет возвращена ошибка.
Если пользователь-партнер существует, но не является партнером, то указанный пользователь автоматически получит статус партнера.

Ссылка на это место страницы: #export

Ссылка на это место страницы: #users

Ссылка на это место страницы: #groups

Экспорт групп

Данные можно получить одним из способов:

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

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

Выгружаются следующие данные:

id — ID группы;
name — название группы;
last_added_at — дата и время добавления последнего пользователя в группу в формате «гггг-мм-дд чч-мм-сс». Если пользователей еще не добавляли в группу, значение будет «null».

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

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

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

Это действие запускает задачу на сбор данных и возвращает ключ экспорта в 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

Ссылка на это место страницы: #deals

Ссылка на это место страницы: #payments

Ссылка на это место страницы: #limits

Лимиты Import API

На создание новых объектов по API предусмотрены лимиты. На изменение уже созданных объектов эти лимиты не распространяются.

⚠️ Обратите внимание! Эти лимиты предназначены для создания объектов с помощью API и не влияют на экспорт данных с помощью ExportAPI или операций «вызвать URL» в процессах (вебхуков).

Тариф	Кол-во пользователей	Добавление пользователей в месяц	Добавление заказов в месяц	Добавление платежей в месяц
Старт	1 000	2 000	1 000	100
Любитель	2 000	3 000	2 000	150
Профессионал	5 000	8 000	5 000	200
Эксперт	10 000	15 000	10 000	300
Продюсер	17 000	22 000	17 000	400
Гуру	25 000	35 000	25 000	500
Полководец	50 000	60 000	50 000	750
Бизнес	100 000	100 000	100 000	1 000
VIP	200 000	200 000	200 000	1 500
Tesla	300 000	300 000	300 000	2 000
S400	400 000	400 000	400 000	2 000

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

Статистика использования API

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

Для этого:

Перейдите на страницу с адресом вида:
- http://ВАШ_АККАУНТ.getcourse.ru/saas/account/api — для системного адреса аккаунта;
- http://ВАШ_ДОМЕН/saas/account/api — для привязанного домена.
Нажмите «Статистика использования API».

Переход к статистике

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

Статистика использования API

Статья была полезной?

Заголовок

Информация не соответствует тому, что я вижу в сервисе Неясное изложение, которое трудно понять Статья полезная, но включает не всю необходимую информацию Содержание не соответствует заголовку или моим ожиданиям Проблемы с оформлением, опечатки или неработающие ссылки Статья полезная, но сам функционал неудобный или сложный Другое

(Необязательно)