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

    

Документация описывает интеграцию с системой Call-tracking.by, которая позволит использовать данные, полученные сервисом, в других системах отчетности (в том числе CRM системах). 

Внимание!
Для всех методов API установлен лимит в 15 запросов в минуту.

Дата составления данной документации - 22 октября 2015 г.
Дата последнего изменения данной документации - 15 января 2025 г.

При возникновении любых вопросов по функционалу API свяжитесь, пожалуйста, с вашим персональным менеджером, и вам обязательно помогут.

Надеемся на плодотворное сотрудничество!
Ваша команда сервиса Call-tracking.by.


Аутентификация и безопасность

Аутентификация происходит с использованием специально сгенерированного секретного ключа (токена). Данный ключ выдаётся клиенту персональным менеджером по запросу. Ключ необходимо будет пересылать в каждом запросе. Имя параметра: user_token. 

Клиент несет полную ответственность за передачу своего персонального ключа третьим лицам. По запросу клиента ключ может быть заменен, также можно полностью отключить интеграцию.

Клиенту будет предоставлен доступ только к собственным данным.

Внимание!

    API нельзя использовать для попыток узнать конфиденциальную информацию пользователей, не являющихся клиентами агента, который запрашивает данные. Команда Call-tracking.by оставляет за собой право блокировки любых запросов клиента, если им была совершена попытка запроса данных о пользователях, не являющихся его клиентами. Команда Call-tracking.by может отключать возможность получения данных для всех агентов, в случае возникновения угрозы безопасности данных.

Демо-данные

Для облегчения интеграции с Call-tracking.by система предоставляет возможность работы API в демо-режиме.

Работа в демо-режиме полностью соответствует работе в нормальном режиме за исключением:

1) В качестве UUID пользователя необходимо передавать TsMbF1mGyiEWejBJ2eOh_w

Пример:
app.call-tracking.by/crm_api/v1/stats/get_calls_per_campaign.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=854,855,856

2) У демо-пользователя имеются данные лишь за период с 01-07-2015 по 31-07-2015


Запросы к API

Запрос на получение групп кампании

Кампании в системе Call-tracking.by могут быть объединены в группы. Например, если клиенту необходимо отслеживать несколько сайтов, несколько дилеров и т.д. Получить список групп пользователя можно с помощью следующего запроса:

URL: GET app.call-tracking.by/crm_api/v1/docs/get_campaign_groups_info.json

Обязательные параметры:

  • user_token - Секретный ключ пользователя.
  • start_date - Дата начала запрашиваемого периода. Формат: день-месяц-год. Пример: 01-07-2015.
  • end_date - Дата окончания запрашиваемого периода. Формат: день-месяц-год. Пример: 31-07-2015.

Примеры запросов:

app.call-tracking.by/crm_api/v1/stats/get_campaign_groups_info.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015
  $.get('/crm_api/v1/stats/get_campaign_groups_info.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015', function (data) {    $('.response-example').removeClass('loading-data');    $('.response-example').html(JSON.stringify(data))  })
Пример ответа:
[{"id"=>1, "name"=>"group_campaign_opt"}, {"id"=>2, "name"=>"group_campaign_roznica"}]

Параметры ответа:

  • id - идентификатор группы.
  • name - имя группы.

Возможное практическое применение:

Такой запрос можно использовать для создания формы в личном кабинете агента. Например, следующего вида:


Запрос на получение информации об активных кампаниях пользователя

Кампании в системе Call-tracking.by имеют различные настройки: отслеживаемые сайты, активные номера, подмена номера только для мобильных, и т.д. Получить информацию об активных кампаниях пользователя можно с помощью такого запроса: 

URL: GET app.call-tracking.by/crm_api/v1/stats/get_campaigns_info.json

Обязательные параметры:

  • user_token - Секретный ключ пользователя.
  • start_date - Дата начала запрашиваемого периода. Формат: день-месяц-год. Пример: 01-07-2015.
  • end_date - Дата окончания запрашиваемого периода. Формат: день-месяц-год.  Пример: 31-07-2015.

Необязательные параметры:

  • adv_group_ids - Если указан, то будет предоставлена только информация о кампаниях указанных групп. Формат: строка (идентификаторы групп через запятую).
  • adv_campaign_ids - Если указан, то будет предоставлена только информация о кампаниях указанных идентификаторов. Формат: строка  (идентификаторы кампании через запятую).

Примеры запросов:

app.call-tracking.by/crm_api/v1/stats/get_campaigns_info.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015&adv_group_ids=1,2,3
    var group_ids = [1,2,3];
      requestUrl = '/crm_api/v1/stats/get_campaigns_info.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015&adv_group_ids=' + group_ids.join(',')
      $.get(requestUrl, function (data) {
        $('.response-example').removeClass('loading-data');
        $('.response-example').html(JSON.stringify(data, null, 4))
      })


Пример ответа:

[
    {
        "id": 854,
        "name": "SEO Google",
        "site_urls": "demo-call-tracking.by",
        "page_regexp": "",
        "adv_campaign_group_id": null,
        "dynamic": false,
        "online": true,
        "mobile": false,
        "status": "confirmed",
        "phones": [
            "+375176111110",
            "+375176111111",
            "+375296111110",
            "+375296111111",
            "+375336111110",
            "+375336111111"
        ],
        "ad_sources": [
            "CallTraсkingБеларусь"
        ],
        "start_date": "2015-07-01",
        "end_date": "2015-08-01"
    }
]

  

Параметры ответа:

  • id - идентификатор кампании.
  • name - имя кампании.
  • start_date - дата начала кампании.
  • end_date - дата окончания кампании.
  • site_urls - сайты, на которые распространяется действия кампании (например, у клиента 2 сайта и на каждом из них настроена кампания Яндекс, но отслеживание должно вестись раздельно).
  • page_regexp - страницы сайта, на которые настроена кампания.
  • adv_campaign_group_id - идентификатор группы, к которой принадлежит кампания.
  • dynamic - настроена ли кампания динамической (обратитесь к менеджеру за разъяснением).
  • online - настроена ли кампания онлайн (обратитесь к менеджеру за разъяснением).
  • mobile - настроена ли кампания только для мобильных устройств (обратитесь к менеджеру за разъяснением).
  • phones - телефонные номера, которые используются в кампании.
  • status - текущий статус кампании (может быть подтвержденным и неподтвержденным).

Возможное практическое применение:

Можно использовать для создания информационной страницы с настройками кампании. Например, следующего вида:


Запрос на получение информации о звонках по кампаниям пользователя

Получить информацию о звонках по кампаниям пользователя можно с помощью данного запроса:

URL: GET app.call-tracking.by/crm_api/v1/stats/get_calls_per_campaign.json


Обязательные параметры:

  • user_token - Секретный ключ пользователя.
  • start_date - Дата начала запрашиваемого периода. Формат: день-месяц-год.  Пример: 01-07-2015.
  • end_date - Дата окончания запрашиваемого периода. Формат: день-месяц-год.  Пример: 01-07-2015.

Необязательные параметры:

  • adv_group_ids - Если указан, то будет предоставлена только информация о кампаниях указанных групп. Формат: строка  (идентификаторы групп через запятую).
  • adv_campaign_ids - Если указан, то будет предоставлена только информация о кампаниях указанных идентификаторов. Формат: строка  (идентификаторы кампании через запятую).

Примеры запросов:

app.call-tracking.by/crm_api/v1/stats/get_calls_per_campaign.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=854,855,856
      var campaign_ids = [854,855,856];
      requestUrl = '/crm_api/v1/stats/get_calls_per_campaign.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=' + [campaign_ids[0], campaign_ids[1]].join(',');
      $.get(requestUrl, function (data) {
        $('.response-example').removeClass('loading-data');
        $('.response-example').html(JSON.stringify([data[0], data[1]], null, 4))
      })

Пример ответа:

[
    {
        "id": 854,
        "name": "SEO Google",
        "calls_count": 15,
        "uniq_calls_count": 0,
        "show_count": 118
    },
    {
        "id": 855,
        "name": "SEO Google (моб)",
        "calls_count": 19,
        "uniq_calls_count": 4,
        "show_count": 151
    }
]


Параметры ответа:

  • id - идентификатор кампании.
  • name - имя кампании.
  • calls_count - количество звонков за выбранный интервал.
  • uniq_calls_count - количество уникальных звонков за выбранный интервал.
  • show_count - количество уникальных показов телефонов за выбранный интервал.

Возможное практическое применение:

Можно использовать для создания страниц с отчетами в виде таблиц или графиков. Например, следующего вида:



Данные о всех звонках пользователя

Метод позволяет получить информацию о всех звонках по всем кампаниям пользователя. Данные о звонках передаются от соответствующих операторов. 

Внимание!
Метод возвращает максимум по 500 записей на страницу.

URL: GET app.call-tracking.by/crm_api/v1/stats/raw_calls.json

Обязательные параметры:

  • user_token - Секретный ключ пользователя.
  • start_date - Дата начала запрашиваемого периода. Формат: день-месяц-год. Пример: 01-07-2015.
  • end_date - Дата окончания запрашиваемого периода. Формат: день-месяц-год. Пример: 01-07-2015.
  • page - Страница выборки. Необходимо для получения более 500 записей. Нумерация начинается с единицы. По умолчанию 1.

Необязательные параметры:

  • adv_group_ids - Если указан, то будет предоставлена только информация о кампаниях указанных групп. Формат: строка (идентификаторы групп через запятую).
  • adv_campaign_ids - Если указан, то будет предоставлена только информация о кампаниях указанных идентификаторов. Формат: строка (идентификаторы кампании через запятую).

Примеры запросов:

app.call-tracking.by/crm_api/v1/stats/raw_calls.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015&page=1&adv_campaign_ids=854,855,856
      var campaign_ids = [854,855,856];
      requestUrl = '/crm_api/v1/stats/raw_calls.json?user_token=TsMbF1mGyiEWejBJ2eOh_w&start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=' + campaign_ids.join(',');
      $.get(requestUrl, function (data) {
        $('.response-example').removeClass('loading-data');
        $('.response-example').html(JSON.stringify([data[0], data[1]], null, 4))
      })

Пример ответа:


[
    {
        "datetime": "2015-07-02T00:10:00.000+03:00",
        "campaign_id": 854,
        "campaign_name": "SEO Google",
        "stat_source": "SEO Google",
        "duration": 40,
        "caller_number": "+375176999000",
        "caller_operator": null,
        "ads_number": "+375336111110",
        "ads_number_redirect_phones": [
            "+375335001122",
            "+375335001144"
        ],
        "utm_keyword": null,
        "utm_campaign": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_content": null,
        "roistat_id": null,
        "google_analytics_id": null,
        "yandex_metrica_id": null,
        "facebook_pixel_id": null,
        "answered": true,
        "answered_number": "+375335001122",
        "voice_record_link": ""
    },
    {
        "datetime": "2015-07-02T00:35:00.000+03:00",
        "campaign_id": 854,
        "campaign_name": "SEO Google",
        "stat_source": "SEO Google",
        "duration": 62,
        "caller_number": "+375176999001",
        "caller_operator": null,
        "ads_number": "+375336111110",
        "ads_number_redirect_phones": [
            "+375335001122",
            "+375335001144"
        ],
        "utm_keyword": null,
        "utm_campaign": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_content": null,
        "roistat_id": null,
        "google_analytics_id": null,
        "yandex_metrica_id": null,
        "facebook_pixel_id": null,
        "answered": true,
        "answered_number": "+375335001122",
        "voice_record_link": ""
    },
    {
        "datetime": "2015-07-02T01:00:00.000+03:00",
        "campaign_id": 854,
        "campaign_name": "SEO Google",
        "stat_source": "SEO Google",
        "duration": 7,
        "caller_number": "+375176999002",
        "caller_operator": null,
        "ads_number": "+375336111110",
        "ads_number_redirect_phones": [
            "+375335001122",
            "+375335001144"
        ],
        "utm_keyword": null,
        "utm_campaign": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_content": null,
        "roistat_id": null,
        "google_analytics_id": null,
        "yandex_metrica_id": null,
        "facebook_pixel_id": null,
        "answered": true,
        "answered_number": "+375335001122",
        "voice_record_link": ""
    }
]


Параметры ответа:

  • datetime - время звонка, с тайм зоной.
  • campaign_id - идентификатор кампании.
  • campaign_name - имя кампании.
  • stat_source - нормализованный источник звонка. Сформирован на основании utm-меток, реферала и названия отслеживаемого источника.
  • duration - продолжительность звонка.
  • caller_number - номер звонившего.
  • caller_operator - оператор звонившего (Внимание! вывод об операторе сделан на основании номера звонившего, а не его реального оператора).
  • ads_number - номер кампании, который был показан клиенту и/или был размещен в рекламном объявлении.
  • ads_number_redirect_phones - массив номеров, на который переадресовывает номер кампании.
  • answered - статус звонка (отвечен/не отвечен).
  • answered_number - номер, который ответил на звонок.
  • voice_record_link - ссылка на файл записи, присутствует, если запись включена. Запись по ссылке доступна, пока запись хранится в личном кабинете (исходя из настроек хранения записей в личном кабинете клиента).
  • utm_keyword - ключевое слово (в случае, если звонок поступил по динамической кампании).
  • utm_source - источник трафика (в случае, если звонок поступил по динамической кампании).
  • utm_campaign - рекламная кампания (в случае, если звонок поступил по динамической кампании).
  • utm_medium - тип трафика (в случае, если звонок поступил по динамической кампании).
  • utm_content - содержание рекламной кампании (в случае, если звонок поступил по динамической кампании).
  • roistat_id - уникальный идентификатор Roistat (доступно только при использовании динамического колл трекинга и при наличии на сайте скрипта Roistat).
  • google_analytics_id - уникальный идентификатор Google Analytics (доступно только при использовании динамического колл трекинга и при наличии на сайте скрипта Google Analytics).
  • yandex_metrica_id - уникальный идентификатор Яндекс Метрики (доступно только при использовании динамического колл трекинга и при наличии на сайте скрипта Яндекс Метрики).

Возможное практическое применение:

Можно использовать для создания страниц с данными о всех звонках с фильтрацией. Например, следующего вида: