Описание REST API

Авторизация, методы, примеры работы

Содержание

REST API в Альфа CRM


Данное описание предназначено для интеграции Альфа CRM с другими информационными сервисами. Мы дополняем этот документ описанием новых методов, моделей и параметров.

Всё взаимодействие через API должно осуществляться по протоколу REST. В качестве формата данных используется JSON. Прочие форматы и протоколы не поддерживаются.

Методы API реализуются в Контроллере (MVC) виде CRUD парадигмы вокруг каждой Модели (MVC). Модель — это отдельная сущность в CRM системе, например Ученик, или Урок, или Филиал под которую реализуется отдельный Контроллер.

Примеры запросов можно посмотреть в приложенных коллекциях Postman

Рекомендации по работе с нашим API:

  1. Создание отдельного пользователя в системе для работы именно с API (особенно актуально, если передаёте информацию с доступами сторонним разработчикам, так как такой доступ всегда можно отключить).
  2. Кеширование токена авторизации (также можно использовать обработку ошибок, чтобы, как только придет ошибка с кодом 401, снова делать запрос на получение токена).
  3. Обработка запросов последовательно:
    • сделайте запрос по API;
    • дождитесь ответа;
    • разберите полученные данные;
    • определитесь, нужно ли отправлять следующий запрос.
  4. Сохранение результатов запросов, чтобы не выгружать одни и те же данные.

По вопросам работы с нашим API можно написать на почту dev@alfacrm.pro. Ответ может занять до 3-5 рабочих дней.


Авторизация


Прежде чем обращаться к методам CRUD необходимо авторизоваться и получить временный токен. Этим токеном должен подписываться каждый CRUD запрос заголовке X-ALFACRM-TOKEN. Время жизни токена — 3600 секунд. Для получения токена нужно обратиться методом POST к URI /v2api/auth/login, а в теле запроса передать JSON объект с ключами email и api_key.

Авторизующийся пользователь должен иметь роль с предоставленным доступом к модулю v2api. Иначе запросы к CRUD будут возвращать исключение Access Denied. 

Пример из командной строки Linux (утилита curl):
$ curl -i -X 'POST' -d '{"email":"{email}","api_key":"{api_key}"}' 'https://{hostname}/v2api/auth/login'
			
//Пример кода на PHP
$ch      = curl_init();
$data    = ['email' => 'ivan@mail.ru', 'api_key' => '123456'];
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://demo.s20.online/v2api/auth/login');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
$token = $result['token'];

Варианты ответа сервера:

  • ОК, код ответа 200, в теле — JSON вида {"token":"GENERATED-TOKEN"}
  • исключение, код ответа 4XX, 5XX, в теле — JSON вида {"name":"Forbidden","message":"Not Authorized","code":0,"status":403}

Значение некоторых параметров


  • {hostname} — клиентский идентификатор, являющийся Hostname в URL для доступа в систему. Например, для https://demo.s20.online это demo.s20.online;
  • {branch} — ID филиала, в который происходит обращение;
  • {email} — e-mail пользователя для авторизации в системе;
  • {api_key} — ключ API для авторизации в системе;
  • {token} — токен, полученный при авторизации (см. блок Авторизация);

Примеры возвращаемых значений в


CRUD


  • Метод Index — возвращает JSON вида {"total":2,"count":2,"page":0,"items":[]}, где total — количество записей всего, count — количество записей в текущей коллекции items, page — текущая страница результатов выдачи. В items содержится вся коллекция записей в виде объектов различных моделей.
  • Методы Create и Update — возвращает JSON вида {"success":true,"errors":[],"model":{"id":1,...}}, где success — результат выполнения запроса (true / false), errors — коллекция ошибок если success == false, model — JSON объект Модели с публичными свойствами.
  • Метод Delete — возвращает JSON вида {"success":true,"errors":[]}, где success — результат выполнения запроса (true / false), errors — коллекция ошибок если success == false.

Branch — сущность филиала

Location — сущность локации

id
int
идентификатор
branch_id
int
филиал (Branch)
is_active bool
флаг активности
name
string(50)
наименование

Customer — центральная сущность

Group — сущность групп

Lesson — сущность урока

POST на /v2api/{branch}/lesson/create
В Body указываются поля для добавления разового урока:

Обязательные поля к заполнению: 
{
  "lesson_date" // дата урока, date (формат: "DD.MM.YYYY")
  "time_from" // время начала урока, datetime (формат: "HH:MM")
  "duration" // длительность урока в минутах, int
  "lesson_type_id" // id типа урока, int
  "subject_id" // id предмета, int
}

Необязательные поля к заполнению: 
{
  "teacher_ids" // id педагога, int array
  "is_confirmed" // подтверждение урока (по умолчанию да (1)), int
  "is_public" // возможна запись онлайн (по умолчанию нет (0)), int
  "note" // комментарий, string
  "topic" // тема, string
  "room_id" // id аудитории, int
  "group_ids" // id группы (для типов уроков с системным типом “Группа или несколько”), int array
  "customer_ids" // id клиента (для типов уроков с системным типом “Индивидуально” или “Лид, клиент или несколько”), int array
  "custom_name" // дополнительные поля, string
}
Пример из командной строки Linux (утилита curl): 
$ curl -i -X 'POST' -H 'X-ALFACRM-TOKEN: {token}' -d '' 'https://{hostname}/v2api/{branch}/lesson/create'
Пример на PHP: 
$ch     = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-ALFACRM-TOKEN: {token}', 'Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://{hostname}/v2api/{branch}/lesson/create');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, '');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
var_dump($result);

CGI — связь клиенты-группы

POST на /v2api/{branch}/cgi/update?group_id={id}&id={id} в теле {"customer_id":1,"b_date":"dd.mm.yyyy","e_date":"dd.mm.yyyy","branch_id":1}
Пример из командной строки Linux (утилита curl): 
$ curl -i -X 'POST' -H 'X-ALFACRM-TOKEN: {token}' -d '{"customer_id":1,"b_date":"dd.mm.yyyy","e_date":"dd.mm.yyyy","branch_id":1}' 'https://{hostname}/v2api/{branch}/cgi/update?id={id}'
Пример на PHP: 
$ch     = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-ALFACRM-TOKEN: {token}', 'Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://{hostname}/v2api/{branch}/cgi/update?group_id={id}&id={id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"customer_id":1,"b_date":"dd.mm.yyyy","e_date":"dd.mm.yyyy","branch_id":1}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
var_dump($result);

Subject — предметы обучения

POST на /v2api/{branch}/subject/update?id={id} в теле {"name":"New subject 2"}
Пример из командной строки Linux (утилита curl): 
$ curl -i -X 'POST' -H 'X-ALFACRM-TOKEN: {token}' -d '{"name":"New subject 2"}' 'https://{hostname}/v2api/{branch}/subject/update?id={id}'
Пример на PHP: 
$ch     = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-ALFACRM-TOKEN: {token}', 'Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://{hostname}/v2api/{branch}/subject/update?id={id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"New subject 2"}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
var_dump($result);

StudyStatus — статусы обучения

POST на /v2api/{branch}/study-status/update?id={id} в теле {"name":"New status 2"}
Пример из командной строки Linux (утилита curl): 
$ curl -i -X 'POST' -H 'X-ALFACRM-TOKEN: {token}' -d '{"name":"New status 2"}' 'https://{hostname}/v2api/{branch}/study-status/update?id={id}'
Пример на PHP: 
$ch     = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-ALFACRM-TOKEN: {token}', 'Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://{hostname}/v2api/{branch}/study-status/update?id={id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"New status 2"}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
var_dump($result);

LeadStatus — этапы воронки продаж

LeadSource — источники

Pay — платежи

POST на /v2api/{branch}/pay/index в теле {"id":1,"page":0}
page — пейджинация
В Body параметры для фильтрации: 
{
  "id"// id платежа, int
  "currency":"rub" // валюта платежа
  "location_id" // локация платежа, int
  "customer_id" // id клиента
  "employee_id"  // id педагога (тип платежа - Выдача ЗП)
  "pay_item_category_id" // id категории статей
  "pay_type_id" // тип операции, int
  "pay_item_id" // id статьи, int
  "pay_account_id" // id счета (кассы)
  "commodity_id"  // id товара (тип платежа – Продажа товара)
  "payer_name" // имя плательщика, string
  "note"  // примечание, string
  "date_from" // дата от yyyy.mm.dd
  "date_to" // дата до yyyy.mm.dd
  "sum_from" // сумма платежа от
  "sum_to" // сумма платежа до
  "bonus_from" // бонус от
  "bonus_to" // бонус до
  "is_confirmed" // подтвержден (1 - да, 0 - нет)
  "group_ids":[], // id групп
  "is_fiscal" // фискализован (1 - фискализован, 0 – нет) 
  "updated_at_from" // дата внесения последних изменений от, date (формат "DD.MM.YYYY")
  "updated_at_to" // дата внесения последних изменений до, date (формат "DD.MM.YYYY")
  "created_at_from" // дата создания от, date (формат "DD.MM.YYYY")
  "created_at_to" // дата создания до, date (формат "DD.MM.YYYY")
}
Пример из командной строки Linux (утилита curl): 
$ curl -i -X 'POST' -H 'X-ALFACRM-TOKEN: {token}' -d '{"id":1,"page":0}' 'https://{hostname}/v2api/{branch}/pay/index'
Пример на PHP: 
$ch     = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-ALFACRM-TOKEN: {token}', 'Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://{hostname}/v2api/{branch}/pay/index');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"id":1,"page":0}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
var_dump($result);

Communication — коммуникации

CustomerTariff — получение списка


абонементов клиента

POST на /v2api/{branch}/customer-tariff/index?customer_id=[id] в теле {"page":0}
customer_id — id клиента, page — пейджинация
В Body параметры для фильтрации: 
{
  "id" // id абонемента в карточке клиента, int
  "tariff_id" // id тарифа(абонемента в разделе Абонементы), int
  "is_burnable_out" //сгораемый, bool
  "balance":int|array[from,to] // баланс абонемента
  "dead": true // архивный абонемент,(false- все абонементы)
  "tariff_type" //тип абонемента(1-поурочный, 2- помесячный, 3 – недельный) int
  "is_separate_balance" // раздельный баланс, bool
}
Пример из командной строки Linux (утилита curl): 
$ curl -i -X 'POST' -H 'X-ALFACRM-TOKEN: {token}' -d '{"customer_id":1,"page":0}' 'https://{hostname}/v2api/{branch}/customer-tariff/index'
Пример на PHP: 
$ch     = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-ALFACRM-TOKEN: {token}', 'Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://{hostname}/v2api/{branch}/customer-tariff/index');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"customer_id":1,"page":0}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
var_dump($result);

Discount — сущность скидок

Log — получение списка истории


изменений

RegularLesson — сущность


регулярных уроков

Tariff — сущность абонемента

Task — сущность задач

Teacher — сущность педагога

POST на /v2api/{branch}/teacher/create в теле
Пример из командной строки Linux (утилита curl): 
$ curl -i -X 'POST' -H 'X-ALFACRM-TOKEN: {token}' -d '' 'https://{hostname}/v2api/{branch}/teacher/create'
Пример на PHP: 
$ch     = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-ALFACRM-TOKEN: {token}', 'Accept: application/json', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_URL, 'https://{hostname}/v2api/{branch}/teacher/create');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, '');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
$code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch))
    throw new \Exception('Curl error');
curl_close($ch);
if ($code !== 200)
    throw new \Exception($result['name'] . ' - ' . $result['message']);
var_dump($result);

Поделиться

Empty

По вашему запросу ничего не найдено

Перейти

Навигация

Esc

Закрыть