Перейти к содержанию

REST API Roistat

Общие сведения

Что такое 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

Адрес API 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, кроме случаев, когда явно указано, что часовой пояс по умолчанию другой, или в передаваемой дате указывается часовой пояс (например, 2016-12-12 11:30:10+0300).

Пример:

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, если вы хотите получить информацию и о визитах заказов:

{
    "extend": ["visit"]
}

Сочетание нескольких параметров

Можно использовать несколько разных параметров для управление данными. Все они перечисляются через запятую в одном 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 секунду
  • 100 запросов в 1 минуту
  • 5000 запросов в 1 час

Кроме указанных выше правил, других общих ограничений нет. Однако у некоторых методов могут быть дополнительные ограничения. Список этих ограничений (при их наличии) можно найти в описании метода.

Ответ

Спецификация формата JSON

В API используется стандартный формат JSON. Подробнее про спецификацию можно прочитать по ссылке: http://www.json.org/.

Спецификация формата XML

Все запросы и ответы в формате XML используют единую спецификацию.

  • Корневой элемент всегда <data></data>.

  • Для описания свойства с именем 'name' и значением 'value' вам нужно обернуть 'value' в тег 'name'. Пример:

    <!--?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.