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

    

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

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

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

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

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


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

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

Дополнительным уровнем безопасности является проверка ip-адресов с которых приходят запросы. Запросы с определенным ключом агента будут разрешены только для определенных статических ip-адресов. Список ip-адресов необходимо предоставить команде Call-tracking.by заблаговременно. Исключение составляют запросы на получение тестовых данных. Запросы на получение тестовых данных (демо-данные) не будут проходить проверку ip-адресов.

Агенту будет предоставлен доступ только к данным определенных пользователей. Пользователь и\или агент должен сообщить команде Call-tracking.by о своем желании передавать данные через API. После получения такого запроса будет сгенерирован уникальный UUID пользователя для использования API. UUID пользователя должен передаваться в каждом запросе в параметре user_uuid

Просмотреть возможные коды ошибок аутентификации можно в разделе "Список кодов ошибок" в конце документации.

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

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

Внимание!

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

Демо-данные

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

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

1) В качестве UUID пользователя стоит передавать 9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf

Пример:


/api/v2/stats/get_calls_per_campaign.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf&start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=854,855,856

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

3) Запрос к демо данным не будет проходить проверку на статический IP и может быть совершен с любого сервера.



Запросы к API

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

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

URL: GET /api/v2/docs/get_campaign_groups_info.json

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

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

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

/api/v2/stats/get_campaign_groups_info.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf &start_date=01-07-2015&end_date=03-07-2015
  $.get('/api/v2/stats/get_campaign_groups_info.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf&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 /api/v2/stats/get_campaigns_info.json 

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

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

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

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

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

/api/v2/stats/get_campaigns_info.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf &start_date=01-07-2015&end_date=03-07-2015&adv_group_ids=1,2,3
 var group_ids = [1,2,3];
      requestUrl = '/api/v2/stats/get_campaigns_info.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf
      &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,
        "phones": [
            "+375176111110",
            "+375176111111",
            "+375296111110",
            "+375296111111",
            "+375336111110",
            "+375336111111"
        ],
        "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 /api/v2/stats/get_calls_per_campaign.json 


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

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

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

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

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

/api/v2/stats/get_calls_per_campaign.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf &start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=854,855,856


      var campaign_ids = [854,855,856];
      requestUrl = '/api/v2/stats/get_calls_per_campaign.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf&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 /api/v2/stats/raw_calls.json 

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

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

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

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

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

/api/v2/stats/raw_calls.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf &start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=854,855,856
    var campaign_ids = [854,855,856];
      requestUrl = '/api/v2/stats/raw_calls.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf&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
    },
    {
        "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
    },
    {
        "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
    }
]


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

  • 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 - уникальный идентификатор Яндекс Метрики (доступно только при использовании динамического колл трекинга и при наличии на сайте скрипта Яндекс Метрики).

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

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


Данные о звонках совершенных с определенного номера

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

URL: GET /api/v2/stats/calls_per_caller_number.json 


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

  • agent_token - Персональный ключ агента.
  • user_uuid - Уникальный идентификатор пользователя.
  • start_date - Дата начала запрашиваемого периода. Формат день-месяц-год. Пример: '01-07-2015'.
  • end_date - Дата окончания запрашиваемого периода. Формат день-месяц-год. Пример: '31-07-2015'.
  • caller_numbers - Телефонные номера, источники звонков с которых представляют интерес. Формат - строка (телефонные номера в формате 375xxxxxxxxx через запятую).


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

/api/v2/stats/calls_per_caller_number.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf &start_date=01-07-2015&end_date=03-07-2015&adv_campaign_ids=854,855,856
     var numbers = ['+375331112211','+375295552299'];
      requestUrl = '/api/v2/stats/calls_per_caller_number.json?agent_token=IQnFQDNe6TVsWpP0hvmxpQ&user_uuid=9b2d8c12-3ce8-4291-a470-4fc0c2d2e0bf&start_date=01-07-2015&end_date=03-07-2015&caller_numbers=' + numbers.join(',');
      $.get(requestUrl, function (data) {
        $('.response-example').removeClass('loading-data');
        $('.response-example').html(JSON.stringify([data[0], data[1]], null, 4))
      })

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

[
    [
        {
            "datetime": "2015-07-01T03:05:00.000+03:00",
            "campaign_id": 856,
            "campaign_name": "SEO Yandex",
            "stat_source": "SEO Yandex",
            "duration": 42,
            "caller_number": "+375176999007",
            "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
        },
        {
            "datetime": "2015-07-02T03:05:00.000+03:00",
            "campaign_id": 858,
            "campaign_name": "Rambler.ru",
            "stat_source": "Rambler.ru",
            "duration": 56,
            "caller_number": "+375176999007",
            "caller_operator": null,
            "ads_number": "+375296111111",
            "ads_number_redirect_phones": [
                "+375447778899",
                "+375447778866",
                "+375447778844"
            ],
            "utm_keyword": null,
            "utm_campaign": null,
            "utm_source": null,
            "utm_medium": null,
            "utm_content": null
        },
        {
            "datetime": "2015-07-02T03:05:00.000+03:00",
            "campaign_id": 855,
            "campaign_name": "SEO Google (моб)",
            "stat_source": "SEO Google (моб)",
            "duration": 16,
            "caller_number": "+375256999007",
            "caller_operator": null,
            "ads_number": "+375296111111",
            "ads_number_redirect_phones": [
                "+375447778899",
                "+375447778866",
                "+375447778844"
            ],
            "utm_keyword": null,
            "utm_campaign": null,
            "utm_source": null,
            "utm_medium": null,
            "utm_content": null
        },
        {
            "datetime": "2015-07-02T03:05:00.000+03:00",
            "campaign_id": 857,
            "campaign_name": "SEO Yandex (моб)",
            "stat_source": "SEO Yandex (моб)",
            "duration": 8,
            "caller_number": "+375256999007",
            "caller_operator": null,
            "ads_number": "+375336111111",
            "ads_number_redirect_phones": [
                "+375335001122",
                "+375335001144"
            ],
            "utm_keyword": null,
            "utm_campaign": null,
            "utm_source": null,
            "utm_medium": null,
            "utm_content": null
        },
        {
            "datetime": "2015-07-01T03:05:00.000+03:00",
            "campaign_id": 858,
            "campaign_name": "Rambler.ru",
            "stat_source": "Rambler.ru",
            "duration": 51,
            "caller_number": "+375256999007",
            "caller_operator": null,
            "ads_number": "+375176111111",
            "ads_number_redirect_phones": [
                "+375172222221"
            ],
            "utm_keyword": null,
            "utm_campaign": null,
            "utm_source": null,
            "utm_medium": null,
            "utm_content": null
        }
    ]
]


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

  • datetime - время звонка, с таймзоной.
  • campaign_id - идентификатор кампании.
  • campaign_name - имя кампании.
  • duration - продолжительность звонка.
  • caller_number - номер звонившего
  • caller_operator - оператор звонившего (Внимание: вывод об операторе сделан на основании номера звонившего, а не его реального оператора)
  • ads_number - номер который показывался и\или был размещен в рекламном объявлении
  • ads_number_redirect_phones - массив номеров, на который переадресовывает номер в рекламном объявлении
  • utm_keyword - ключевое слов в случае если звонок был сделан по динамической рекламной кампании
  • utm_campaign - контекстная рекламная кампания в случае если звонок был сделан по динамической рекламной кампании

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

Данный запрос можно использовать в интеграциях с различными системами CRM.


Список кодов ошибок.

Сервер отвечает на исключительные ситуации в формате:

{ "success":false,"code": КОД ОШИБКИ, "message": СООБЩЕНИЕ ОБ ОШИБКЕ }


Возможные коды ошибок:

1. Неверный персональный ключ агента. Обратитесь за ключом. Статус ответа - 401;
2. Неверный ip-адрес. Составьте список ваших статических айпи адресов и обратитесь в службу поддержки проекта. Статус ответа - 401;
3. Неверный идентификатор клиента. Клиент с таким идентификатором не может быть найден. Статус ответа - 404;
4. Неверный формат даты начала периода, или дата отсутствует. Проверьте наличие даты и ее формат. Формат должен быть dd-mm-yyyy . Пример: 19-07-2014.'. Статус ответа - 449;
5. Неверный формат даты окончания периода, или дата отсутствует. Проверьте наличие даты и ее формат. Формат должен быть dd-mm-yyyy . Пример: 19-07-2014.'. Статус ответа - 449;
6. Превышение лимита запросов в минуту. Разрешено до 15 запросов включительно. Статус ответа - 42.