Общие сведения¶
Что такое API?¶
API (от англ. application programming interface – интерфейс программирования приложений) – это интерфейс, который дает возможность с помощью специальных команд управлять каким-либо программным обеспечением (приложением, сервисом, программой и т.п.).
Для чего используют API Roistat?¶
API в Roistat используется для достижения различных бизнес-целей. В данной документации мы предлагаем вам описание тех методов API, которыми вы сами сможете оперировать для выполнения своих бизнес-задач. Например, можно обновлять информацию о лидах или выгружать списки звонков из Коллтрекинга, а затем использовать их в своих целях. Обычно наши клиенты используют API для более гибкой настройки интеграции Roistat со своими системами.
Особенности API Roistat¶
Протокол передачи данных¶
API поддерживает как HTTP-, так и HTTPS-протоколы.
Формат запросов¶
API поддерживает CORS – кросс-доменные запросы.
В API Roistat используются POST- и GET-запросы. Тип запроса указан отдельно для каждого метода.
Авторизация¶
Все запросы требуют API-ключ и номер проекта для авторизации.
Номер проекта можно передавать в URL запроса, например: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?project=12345
API-ключ можно передавать двумя способами:
-
Устанавливая HTTP-заголовок
Api-key
(рекомендуемый способ):Api-key: 1234567890qwerty
-
Добавляя параметр
key
в URL запроса (небезопасный способ):https://cloud.roistat.com/api/v1/project/calltracking/phone/list?key=1234567890qwerty&project=12345
Где найти API-ключ?¶
Уникальный API-ключ формируется для каждого пользователя в отдельности и относится ко всем проектам в одном профиле.
API-ключ можно посмотреть в настройках профиля.
Структура запроса¶
Вы можете использовать как JSON-, так и XML-формат для отправляемых данных.
Подробнее читайте в пункте Запрос.
Формат ответа¶
Форматом ответа по умолчанию является JSON. Если передавать данные в формате XML, ответ будет представлен в виде XML.
Вы можете принудительно выставить формат, используя HTTP-заголовок Accept
с одним из значений: application/json
или application/xml
.
Подробнее читайте в пункте Ответ.
Внесение изменений в форматы ответов¶
Мы периодически обновляем форматы ответов по методам API Roistat (в основном, с целью оптимизации работы). В таких случаях мы обязательно уведомляем наших пользователей. В описании метода мы указываем срок поддержки старого формата, чтобы все пользователи метода API успели внести необходимые изменения в своих системах, и способы работы с новым форматом в переходный период.
Для поддержки двух форматов используется флаг is_new
. Чтобы получать данные в новом формате, необходимо в запросе передавать переменную is_new=1
. Без этого параметра метод будет возвращать данные в старом формате.
Обратите внимание, что если при запросе данных вы получаете ошибку, приведенную ниже, то переходный период подходит к концу, и старый формат ответа скоро перестанет поддерживаться:
{
"status": "error",
"error": "The data requested in the old format. Soon the method will be fully transferred to the new data format. Please, contact support@roistat.com"
}
Такая ошибка начнет периодически выдаваться в последние 2 месяца переходного периода.
Запрос¶
Формат запросов¶
API поддерживает CORS – кросс-доменные запросы.
В API Roistat используются POST- и GET-запросы. Тип запроса указан отдельно для каждого метода.
Структура имени URL-запросов¶
Каждый URL начинается с адреса API (https://cloud.roistat.com/api/v1/), за ним следует название ресурса или действия, название метода и номер проекта. Также в URL можно передавать API-ключ, но мы рекомендуем передавать его в HTTP-заголовке.
Например, рассмотрим URL для получения списка телефонных номеров в Коллтрекинге: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?project=12345
Если нужно передать в URL API-ключ, ссылка будет выглядеть следующим образом: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?key=1234567890qwerty&project=12345
Авторизация¶
Все запросы требуют API-ключ и номер проекта для авторизации. Исключение – методы /user/projects и /account/project/create, где требуется только API-ключ.
Номер проекта можно передавать в URL запроса, например: https://cloud.roistat.com/api/v1/project/calltracking/phone/list?project=12345
API-ключ можно передавать двумя способами:
-
Устанавливая HTTP-заголовок
Api-key
(рекомендуемый способ):Api-key: 1234567890qwerty
-
Добавляя параметр
key
в URL запроса (небезопасный способ):https://cloud.roistat.com/api/v1/project/calltracking/phone/list?key=1234567890qwerty&project=12345
Где найти API-ключ?¶
Уникальный API-ключ формируется для каждого пользователя в отдельности и относится ко всем проектам в одном профиле. API-ключ можно посмотреть в настройках профиля.
Структура запроса¶
Вы можете использовать как JSON-, так и XML-формат для отправляемых данных.
Часовой пояс (timezone)
Во всех API-методах по умолчанию используется часовой пояс UTC+0, если явно не указан другой.
Пример:
2017-01-01 12:00:00 будет интерпретировано в 2017-01-01 12:00:00+00:00
2017-01-01 12:00:00+0300 будет интерпретировано в 2017-01-01 09:00:00+00:00
То есть если вы передаете данные в московском времени, то необходимо указать часовой пояс.
Фильтрация данных (filters)
Чтобы отфильтровать получаемые данные, необходимо в теле запроса передать параметр filters
.
Если необходимо отфильтровать по одному полю:
{
"filters": [
["id", ">=", "15774"]
]
}
- 1-ый элемент массива – поле объекта, по которому происходит фильтрация;
- 2-ой элемент – оператор;
- 3-ий элемент – значение поля.
Второй элемент (оператор) может принимать следующие варианты:
Оператор | Описание |
---|---|
<, <=, =, !=, >, >= | Операторы сравнения |
in | Проверка вхождения значения параметра в предполагаемый массив из параметров |
null | Если указать значение 0 , то идет проверка на IS NOT NULL . Если 1 , то IS NULL . |
like | Проверка совпадения. Аналог %LIKE% |
Пример использования оператора in
(для списка звонков будут показаны только строки, где статус или ANSWER
, или CANCELLED
):
{
"filters": [
["status", "in", ["ANSWER", "CANCELLED"]]
]
}
Можно применять несколько фильтров. В этом случае используется оператор and
(логическое И) или or
(логическое ИЛИ). Пример фильтра, который отбирает данные по дате между 22 и 23 мая (время в UTC0):
{
"filters": {
"and": [
["date", ">", "2016-05-21T21:00:00+0000"],
["date", "<", "2016-05-22T21:00:00+0000"]
]
}
}
Пример фильтра, который покажет данные с датой между 22 и 23 мая или позже 31 мая:
{
"filters": {
"or": [{
"and": [
["date", ">", "2016-05-21T21:00:00+0000"],
["date", "<", "2016-05-22T21:00:00+0000"]
]
},
["date", ">", "2016-05-30T21:00:00+0000"]
]
}
}
Сортировка (sort)
Сортировка работает по полям ресурса, который запрашивается в методе.
Например, есть ресурс заказа:
{
"id": "12345",
"url": "https://site.com/crm/account.php?account_id=12345",
"source_type": "standard",
"creation_date": "2016-06-19T07:33:46+0000",
"update_date": "2016-06-19T09:00:27+0000",
"revenue": 0,
"cost": 0,
"client_id": "12345",
"visit_id": "67890",
"custom_fields": {
"имя": "Валера",
"email": "email@mail.ru",
"Тип аккаунта": "Не указан",
"Социальная сеть": "Нет",
"Ответственный": "Нет",
"Зона": "Россия и СНГ",
"Тариф": "Тестовый",
"Язык": "Русский",
"roistat": 67890,
"status_name": "Зарегистрированный"
},
"status": {
"id": "0",
"type": "progress",
"name": "Зарегистрированный"
}
}
Чтобы отсортировать заказы по дате обновления, начиная с недавно обновленных, нужно передать в теле запроса массив sort
, где:
- 1-ый ключ – поле для сортировки;
- 2-ой ключ – способ сортировки:
asc
– по возрастанию (1-ый элемент – самый маленький; если со временем, то самый ранний);desc
– по убыванию (1-ый элемент – самый большой; если со временем, то самый поздний).
{
"sort": ["creation_date","desc"]
}
Ограничение объема данных (limit и offset)
Если требуется ограничить размер данных, получаемых в ответе, то используются стандартные параметры limit
и offset
.
Пример, когда нужно получить первые 100 строк:
{
"limit": 100,
"offset": 0
}
Для получения следующих 100 строк тело запроса должно быть таким:
{
"limit": 100,
"offset": 100
}
Запрос дополнительных данных (extend)
Каждый объект может иметь связь с другим объектом. Например, у объекта order
может быть зависимый объект visit
, т.е. при запросе данных о заказе вы можете запросить также и данные о визите.
Чтобы не отправлять 2 отдельных запроса на получение таких связанных объектов, можно использовать параметр extend
и в массиве указать список зависимых объектов, которые вы хотите получить.
Пример использования параметра extend
в методе /integration/order/list, если вы хотите получить информацию и о визитах заказов:
Сочетание нескольких параметров
Можно использовать несколько разных параметров для управление данными. Все они перечисляются через запятую в одном JSON-объекте. Например:
{
"extend": ["visit"],
"sort": ["creation_date","desc"],
"limit": 100,
"offset": 0,
"filters": {
"and": [
["date", ">", "2016-05-21T21:00:00+0000"],
["date", "<", "2016-05-22T21:00:00+0000"]
]
}
}
Ограничения по количеству запросов¶
Ограничения применяются ко всем методам API и действуют для каждого проекта в отдельности.
На данный момент действуют следующие ограничения:
- 10 запросов в 1 секунду;
- 5000 запросов в 1 час.
Кроме указанных выше правил, других общих ограничений нет. Однако у некоторых методов могут быть дополнительные ограничения. Список этих ограничений (при их наличии) можно найти в описании метода.
Ответ¶
Спецификация формата JSON¶
В API используется стандартный формат JSON. Подробнее про спецификацию можно прочитать по ссылке: http://www.json.org/.
Спецификация формата XML¶
Все запросы и ответы в формате XML используют единую спецификацию.
-
Корневой элемент всегда
<data></data>
. -
Для описания свойства с именем
'propertyName'
и значением'propertyValue'
вам нужно обернуть'propertyValue'
в тег'propertyName'
. Пример:<!--?xml version='1.0' encoding='UTF-8'?--> <data> <id>123</id> <name>Ivan</name> <email>ivan@gmail.com</email> </data>
-
Для представления списков (массивов без текстовых ключей, например:
[3, 7, 4]
) необходимо оборачивать каждое значение в тег<item></item>
.Чтобы отправить несколько групп свойств (например, для создания или изменения нескольких объектов одним запросом), необходимо обернуть каждую группу в тег
<item></item>
.В примере ниже тег
<item></item>
используется для отправки информации о двух разных людях в одном запросе. Каждый человек имеет свой список телефонных номеров.<!--?xml version='1.0' encoding='UTF-8'?--> <data> <item> <name>Ivan</name> <phones> <item>8-999-123-45-67</item> <item>8-999-987-65-43</item> </phones> </item> <item> <name>Fedor</name> <phones> <item>8-999-999-99-99</item> </phones> </item> </data>
Структура ответа¶
Ответ содержит 3 следующих параметра:
Название параметра | Значение |
---|---|
data | данные, которые вы запрашивали (подробнее читайте в описании к каждому методу в отдельности) |
total | итоговое количество строк (total используется в тех случаях, когда data – это массив с данными) |
status | статус запроса |
Например (в формате JSON):
{
"data": [{
"id": "12345",
"name": "Валера",
"static_source": {
"system_name": "yamarket6",
"display_name": "yamarket",
"icon_url": "https://favicon.yandex.net/favicon/market.yandex.ru",
"utm_source": null,
"utm_medium": null,
"utm_campaign": null,
"utm_term": null,
"utm_content": null,
"openstat": null
},
"visit": null,
"order": null
}, {
"id": "67890",
"name": "Василий",
"static_source": null
}],
"total": 2,
"status": "success"
}
Ошибки¶
Все ошибки представляются в виде человеко- и машиночитаемого статуса. По умолчанию все методы возвращают HTTP-статус 200 OK
, в том числе, и в случае ошибки.
Чтобы при ошибке возвращались соответствующие HTTP-коды, необходимо включить Use-Http-Code
в заголовок запроса и выставить значение 1
.
Список ошибок
Код ошибки | Дополнительный HTTP-код | Описание ошибки |
---|---|---|
incorrect_request | 400 | Ошибка в теле запроса (Request Body). |
unknown_error | 400 | Ошибка при обработке запроса на стороне Roistat. Повторите запрос. Если ошибка повторится, обратитесь в поддержку Roistat. |
authentication_failed | 401 | В запросе указан неверный API-ключ и/или номер проекта. |
authorization_failed | 401 | Нет доступа к сторонним сервисам с данными (например, CRM). |
insufficient_funds | 402 | Недостаточно средств на балансе проекта. |
option_not_available | 402 | Запрашиваемая опция недоступна (не включена в проекте либо не поддерживается для текущего тарифа или языковой зоны). |
option_not_paid | 402 | Запрашиваемая опция не оплачена. |
project_frozen | 402 | Проект заморожен. |
access_denied | 403 | Нет доступа к данным в проекте Roistat. Проверьте настройки в разделе «Права доступа». |
resource_not_found | 404 | Ошибка в URL запроса. |
resource_already_exists | 409 | Попытка создать сущность, которая уже существует. Например, при работе с Коллтрекингом в Request Body указан номер телефона, который уже есть в проекте. |
request_data_validation_error | 422 | В запросе передается неверный тип данных. Убедитесь, что тип данных (string, integer и т.п.) соответствует требованиям метода. |
request_limit_error | 429 | Превышен лимит запросов. См. раздел «Ограничения по количеству запросов». |
internal_error | 500 | Ошибка при обработке запроса на стороне Roistat. Повторите запрос. Если ошибка повторится, обратитесь в поддержку Roistat. |