API метод выгрузки отчета по сквозной аналитике

С помощью API-методов ниже можно выгрузить статистику по любым метрикам Calltouch, доступных в отчете: "Сквозная аналитика":

Статистику через API можно получить в любом порядке уровней вложенности:

Доступны стандартные уровни: Канал, Источник, Кампания, Объявление, Ключевое слово, Дата (Дни, Недели, Месяцы). 

Статистику по API можно отфильтровать по любым значениям канала, источника, кампании, объявления и ключевого слова. Фильтрация осуществляется по логическому условию «равно».

За один API-запрос можно сформировать статистику не более, чем за 90 дней.

Если необходимо получить статистику более, чем за 90 дней, можно последовательно отправить несколько API-запросов, разбив их на периоды.

Для скачивания описанной выше статистики по различным метрикам, необходимо последовательно выполнить 3 API-запроса:

1. Отправить запрос на формирование выгрузки, в ответ он вернет ID формирующийся выгрузки.

2. Дождаться пока выгрузка будет сформирована. Проверить ее готовность можно отдельным запросом, на входе которого указывается полученный ID формирующийся выгрузки в ответе первого запроса.

3. Как только выгрузка будет сформирована, скачать ее отдельным API-запросом.

Вся выгружаемая статистика базируется на основе отчета по Сквозной аналитике. Если вы хотите сравнить полученную статистику по API со статистикой в ЛК, используйте именно этот отчет.

Для авторизации в API используется стандартный токен и ID личного кабинета Calltouch, получить который можно в разделе:  Интеграции /  Отправка данных во внешние системы / API и Webhooks / API.

Получение по API статистики из групповых личных кабинетов недоступно. В случае такого кейса, необходимо получать статистику из отдельных личных кабинетов, входящих в групповой личный кабинет.

За каждый API-запрос списывается определенное количество API-баллов, доступных для вашей учетной записи. Количество списываемых баллов будет указана для каждого запроса далее в разделе «цена». 

Будьте внимательны при проектировании интеграции — если лимит API-баллов будет исчерпан, вы не сможете обращаться к API в течение суток. Подробнее читайте в статье: Система баллов API Calltouch.

Далее описан формат всех трех API-запросов.

API-метод формирования выгрузки статистики по различным метрикам

Цена выполнения запроса: 100 баллов

POST https://api.calltouch.ru/report-service/RestAPI/api/costs-export/create
   

Headers:

• Access-Token: API-токен Calltouch
• Site-Id: ID личного кабинета Calltouch

Формат тела запроса: JSON

Пример тела запроса:

{

    "dateFrom": "2021-04-01",
    "dateTo": "2021-04-03",
    "format": "json",

    "attribution": 0,
    "metrics": [76,77,18,112,113,111],
    "dimensions": ["medium", "source", "campaign",      "content", "term", "days"],
    "filters":     
        [
            {
                        "parameter": "source",
                        "operator": "equals",
                        "value": "yandex"
            },
            {
                        "parameter": "medium",
                        "operator": "equals",
                        "value": "cpc"
            },
            {
                        "parameter": "term",
                        "operator": "equals",
                        "value": "calltouch"
            }
       ]   
}

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

{
    "meta": [], 
    "data": { 
        "exportId": 120146 
    } 
}

Описание параметров:

ID метрик и их названий в личном кабинете Calltouch:

Как получить ID пользовательских метрик, целей и плановых метрик

В личном кабинете перейдите в меню:  Настройки /  Отчеты / Пользовательские метрики. Напротив каждой метрики указан ID.

Также вы можете скопировать список ID из кода. В браузере необходимо зайти в отчет «Сквозная аналитика», открыть инструменты разработчика, перейти на вкладку Network, отфильтровать результаты по слову settings и перезагрузить страницу. Список ID пользовательских метрик будет доступен в объекте data.metric_data.metric_types[5]:

ID целей и плановых метрик находятся там же в объектах data.metric_data.metric_types[6] и data.metric_data.metric_types[7] соответственно.

API-запрос на получение статуса формирования выгрузки

Цена выполнения запроса: 1 балл

POST https://api.calltouch.ru/report-service/RestAPI/api/costs-export/status  

Headers:

• Access-Token: API-токен Calltouch
• Site-Id: ID личного кабинета Calltouch

Формат тела запроса: JSON

Пример тела запроса:

{ 
    "exportIds": [120146,120141,120135] 
}

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

{ 
    "meta": [], 
    "data": [ 
        { 
            "exportId": 120146, 
            "status": "success", 
	    "format": "csv", 
            "parts": 1 
        }, 
        { 
            "exportId": 120135, 
            "status": "error",  
            "format": "json", 
            "parts": 0 
        }, 
        { 
            "exportId": 120141, 
            "status": "in progress",
            "format": "json", 
            "parts": 0 
        } 
    ] 
}

Описание параметров:

API-запрос скачивания сформированной выгрузки

Цена выполнения запроса: 1 балл

POST https://api.calltouch.ru/report-service/RestAPI/api/costs-export/download
   

Headers:

• Access-Token: API-токен Calltouch
• Site-Id: ID личного кабинета Calltouch

Формат тела запроса: JSON

Пример тела запроса:

{

    "exportId": 120146,
    "partNumber": 1
}   

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

{
    "meta": {
        "pagination": {
            "current_page": 1,
            "items_per_page": 3
        },
        "series": [
            [
                "(none)"
            ],
            [
                "cpc"
            ],
            [
                "organic"
            ]
        ],
        "dimensions": [
            { 
                "alias": "medium",
                "name": "Канал" 
             }
         ],
        "columns": [
            {
                "id": 76,
                "name": "Бюджет",
                "type": "currency"
            },
            {
                "id": 77,
                "name": "Клики",
                "type": "plain"
            },
            {
                "id": 18,
                "name": "Все лиды",
                "type": "plain"
            },
            {
                "id": 18,
                "name": "Все лиды %",
                "type": "percent"
            },
            {
                "id": 18,
                "name": "Все лиды цена",
                "type": "currency"
            },
            {
                "id": 112,
                "name": "Всего сделок",
                "type": "plain"
            },
            {
                "id": 113,
                "name": "Выручка",
                "type": "currency"
            },
            {
                "id": 111,
                "name": "ROI",
                "type": "percent"
            }
        ]
    },
    "data": {
        "metrics": [
            [
                0,
                8,
                1,
                0.125,
                0,
                0,
                0,
                0
            ],
            [
                0,
                0,
                3,
                0,
                0,
                0,
                0,
                0
            ],
            [
                0,
                0,
                2,
                0,
                0,
                0,
                0,
                0
            ]
        ]
    }
}

Описание параметров:

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

"12.05.2023 - 12.05.2023 Отчет по Расходам"
Канал;Источник;Бюджет;Клики;"Все лиды";"Все лиды %";"Все лиды цена"
(none);(direct);0;8;1;0.125;0
"<не заполнено>";"<не заполнено>";0;0;2;0;0
Итого;;0;8;3;0.375;0