1. Получение доступа к API
Для получения доступа зайдите в Талланто раздел Администрирование – Включить доступ к API – установите Включить API = Да.
Далее в поле скопируйте значение из поля Токен – это токен доступа, который ваша программа будет использовать для аутентификации в Талланто.
Нажмите «Save token and download Postman collection» - для загрузки файла с коллекцией всех методов API. Этот файл можно использовать при тестировании.
2. Тестирование с помощью Postman
Установите последнюю версию Postman по ссылке. При необходимости создайте новое рабочее пространство (Workspace). Далее импортируйте файл коллекции методов, полученной на прошлом этапе. С помощью Postman – вы сможете формировать запросы к базе данных вашей CRM и проверить с вашими данными все методы API.
3. Описание методов
| Название | Get possible methods (without token) |
| Описание | Список методов API |
| Параметры | |
| Возвращаемые значения | Список методов API |
| Название | List possible modules |
| Описание | Список модулей системы, по которым можно сделать запрос |
| Параметры | method = list_possible_modules |
| Возвращаемые значения | Список модулей и для каждого модуля наименования таблиц базы данных, связанных с модулем |
| Название | List possible module fields |
| Описание | Список полей для указанного модуля |
| Параметры | method = list_possible_fields
module = название модуля (ученик, занятие и т.п.)
|
| Возвращаемые значения | Список полей модуля, для каждого поля указано Имя(name), Лейбла в СРМ (label), Тип в БД(dbType), Обязательность (required) и другие параметры |
| Название | HTML documentation about fields for module |
| Описание | Формирует документацию в формате html для описания модуля |
| Параметры | method = list_possible_fields_doc
module = название модуля (ученик, занятие и т.п.)
|
| Возвращаемые значения | Страница документации |
| Название | List of possible enum values for fields with options |
| Описание | Формирует списки значений, такие как список типов ученика, список статусов записи на занятии, список филиалов и прочее |
| Параметры | method = list_enum_values
options[] = название списка, может быть несколько параметров options
|
| Возвращаемые значения | Списки значений в формате название списка, список системных значений плюс список отображаемых названий |
| Название | Get single entry by id |
| Описание | Запись с выбранным идентификатором для указанного модуля |
| Параметры | method = get_entry_by_id
module = название модуля (ученик, занятие и т.п.)
id = идентификатор
|
| Возвращаемые значения | Данные соответствующие записи с указанным идентификатором, если нет такой записи возвращает ошибку |
| Название | Get single entry by values |
| Описание | Возвращает одну запись со значениями полей для указанного модуля |
| Параметры | method = entry_by_fields
module = название модуля (ученик, занятие и т.п.)
fields_values[навание поля] = значение в поле, fields_values может быть несколько
|
| Возвращаемые значения | Одна запись для модуля, данные которой совпадают с указанными значениями полей. Если совпадений найдено несколько, то возвращается одно из них. |
| Название | Get entry list (all records or by query) |
| Описание | Все записи для модуля либо все подходящие по указанным параметрам |
| Параметры | method = get_entry_list
module = название модуля (ученик, занятие и т.п.)
query = sql запрос для уточнения поиска
order_by = sql команда сортировки записей
fields_values[навание поля] = значение в поле, fields_values может быть несколько, если указаны fields_values, то значения query не учитываются
offset = запрос возвращает по 50 записей, смещение для получения следующих записей
|
| Возвращаемые значения | result_count - количество сформированных записей в списке результата, максимум 50
total_count - общее количество записей для запроса
next_offset - смещение
entry_list - список результирующих записей (ученики, занятия и т.п.)
|
| Название | Create entry |
| Описание | Создает запись с указанными параметрами |
| Параметры | method = set_entry
module = название модуля (ученик, занятие и т.п.)
fields_values[навание поля] = значение в поле, fields_values может быть несколько
|
| Возвращаемые значения | Созданная запись, в случае если запись не была создана, возвращает ошибку
|
| Название | Update entry |
| Описание | Обновляет запись с указанными параметрами |
| Параметры | method = set_entry
module = название модуля (ученик, занятие и т.п.)
id = идентификатор записи
fields_values[навание поля] = значение в поле, fields_values может быть несколько
|
| Возвращаемые значения | Обновленная запись со всеми полями или ошибка, если запись не существует
|
| Название | Delete enty by id |
| Описание | Удаляет запись с указанным идентификатором |
| Параметры | method = set_entry
module = название модуля (ученик, занятие и т.п.)
id = идентификатор записи
|
| Возвращаемые значения | Возвращает true если удаление было успешным, false – если удаление не произошло.
|
4. Коды ответов
| Коды ответов |
| Заголовок | Описание |
| 200 | Запрос прошел успешно |
| 401 | Ошибка авторизации. Не включено API или указан неправильный токен |
| 400 | Ошибка, переданы некорректные данные. Подробности в теле ответа: number - Код ошибки, description - описание ошибки.
|
| Коды ошибок |
| Номер | Описание |
| 1501 | Обязательное поле отсутсвует в запросе |
| 1502 | Запись не существует |
| 1503 | Ошибка SQL, проверьте ваш запрос |
| 1504 | Не корректный емайл адрес |
| 1505 | У вас нет доступа к этому модулю |
| 1506 | В случае если для ClassContactsRelationship или CoursesContactsRelationship не было найдено занятие/группа/или ученик по переданному id |
| 1507 | Занятие уже закрыто: если записываем ученика на закрытое занятие или меняем статус на закрытом занятии или удаляем ученика с закрытого занятия |
| 999 | Ошибка |
5. Особенности использования поля Дата
Данные с типом Дата и Время возвращаются в часовом поясе системы пользователя.
А при запросах Get entry list или Get single entry by values и использование поиска по датам, время нужно задавать в UTC, так как в базе данных время хранится без привязки к часовому поясу.
