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 [email protected]"
}

Такая ошибка начнет периодически выдаваться в последние 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, кроме случаев, когда явно указано, что часовой пояс по умолчанию другой, или в передаваемой дате указывается часовой пояс (например, 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 (для списка звонков будут показаны только строки, где статус или 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 protected]",
        "Тип аккаунта": "Не указан",
        "Социальная сеть": "Нет",
        "Ответственный": "Нет",
        "Зона": "Россия и СНГ",
        "Тариф": "Тестовый",
        "Язык": "Русский",
        "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>[email protected]</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 следующих параметра:

Например (в формате 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.

Список ошибок