Введение

			
 API Endpoint


        https://cloud.alfa-track.com/

                

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

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

МЕТОД GET LEADS

# Пример CURL запроса

curl -G \
'https://cloud.alfa-track.com/user/open/api/v1/leads' \
-H "Content-type: application/json" \
-H "Accept: application/json" \
-d token=lndGVJbmZGS3dffVksyDMqijqw \
-d from=2021-01-01 \
-d to=2021-01-31 \
-d attribution_model=FIRST_INTERACTION \
-d analytic_system=GOOGLE_ANALYTICS
                

Чтобы получить информацию об обращениях, необходимо сделать GET запрос на следующий url:

https://cloud.alfa-track.com/user/open/api/v1/leads

ПАРАМЕТРЫ ЗАПРОСА

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

{
   "success":true,
   "object":[
      {
         "id": 1953592530,
         "msgRealId": "<07e@nmk.com>",
         "name": "Moiseenkov, Dmitriy",
         "email": "monkov@nelmk.com",
         "firstName": "Dmitriy",
         "lastName": "Moiseenkov",
         "patronymicName": null,
         "gender": "male",
         "isCleanParsing": true,
         "gacid": "1372806527.1600149950",
         "ymcid": "1600149950687070718",
         "sendDate":1610434297000,
         "previousEmailDate":1610385456000,
         "subject": "задвижки CMO",
         "message": "Здравствуйте! Просим..",
         "attachmentsUrl": "https://files.alfa-track.com/email_attachments/491_85-2020_01_12__12_01_21-qen122%40mail.ru.zip",
         "ip": "91.229.189.248",
         "source": "yandex.ru",
         "medium": "referral",
         "campaign": "(not set)",
         "keyword": "(not set)",
         "socialNetwork": "(not set)",
         "adContent": "(not set)",
         "fullReferrer": "yandex.ru/",
         "city": "Lipetsk",
         "dateHourMinute": "202009150905",
         "sessionId": "1",
         "integrationId": null,
         "outVisitorId": "1427830.1600952",
         "outSessionId": "774153027",
         "searchPhrase":null,
         "browser": "Chrome",
         "country": "Russia",
         "deviceCategory": "desktop",
         "pagePath": "/about/",
         "analyticSystem": "GOOGLE_ANALYTICS",
         "attributionModel": "LAST_INTERACTION",
         "tags": "tag1,tag2",
         "customId": "942348510",
         "contragent": {
                "name": "ООО \"НПО Ризаур\"",
                "inn": "6234114211",
                "kpp": "621111101",
                "ogrn": "1136114002911",
                "address": "390555, Рязанская обл., Рязанский р-н, с. Добро, 1-й км., стр. 14ж, ОФИС 13",
                "representativeName": "Иванов Артем Андреевич",
                "representativePost": null,
                "fioForSignature": "Иванов А. А.",
                "revenue": 1.994191E9,
                "profit": 1.994191E9,
                "companyPriceValue": 1.773272E9,
                "active": true,
                "registrationDate": "2013-03-06",
                "liquidationDate": null,
                "reliability": "99",
                "category": "Контрольно-измерительные приборы (КИП)",
                "kved": "26.51.6",
                "website": "https://rizaur.ru",
                "domain": "rizaur.ru",
                "email": "sn@rizaur.ru",
                "phone": "+79219219219",
                "predictionData": true
            },
         "aiLeadScore": 88
      },
      {
         "id": 1196574471,
         "msgRealId": "<161.609@f40.i.mail.ru>",
         "name": "Александр Кобзин",
         "firstName": "Александр",
         "lastName": "Кобзин",
         "patronymicName": null,
         "gender": "male",
         "isCleanParsing": true,
         "gacid": "434111606.1610456462",
         "ymcid": "1610456463181945503",
         "sendDate": 1610457799000,
         "previousEmailDate": 1610456798000,
         "email": "kobzin@metserv.ru",
         "subject": "Приобретение металл..",
         "message": "Добрый день.\nПрошу..",
         "attachmentsUrl": "https://files.alfa-track.com/email_attachments/491_85-2020_01_11__12_01_21-qen122%40mail.ru.zip",
         "ip": "94.141.188.212",
         "source": "google",
         "medium": "organic",
         "campaign": "(not set)",
         "keyword": "(not provided)",
         "socialNetwork": "(not set)",
         "adContent": "(not set)",
         "fullReferrer": "google",
         "city": "Moscow",
         "dateHourMinute": "202101121602",
         "sessionId": "1",
         "integrationId": null,
         "outVisitorId": "5826817.16104526",
         "outSessionId": "885808498",
         "searchPhrase": null,
         "browser": "Chrome",
         "country": "Russia",
         "deviceCategory": "mobile",
         "pagePath": "/about/",
         "analyticSystem": "GOOGLE_ANALYTICS",
         "attributionModel": "LAST_INTERACTION",
         "tags": "tag1,tag2,tag3",
         "customId": "942348590",
         "contragent": null,
         "aiLeadScore": 88
      }
   ]
}
                

ПАРАМЕТРЫ ОТВЕТА

МЕТОД GET LEAD VISIT

# Пример CURL запроса
                
curl -G \
'https://cloud.alfa-track.com/user/open/api/v1/lead/visit' \
-H "Content-type: application/json" \
-H "Accept: application/json" \
-d token=lndGVJbmZGS3dffVksyDMqijqw \
-d email=monkov@nelmk.com \
-d attribution_date_to=2021-01-01 \
-d attribution_model=FIRST_INTERACTION \
-d analytic_system=GOOGLE_ANALYTICS
                

Чтобы получить информацию о визите, необходимо сделать GET запрос на следующий url:

https://cloud.alfa-track.com/user/open/api/v1/lead/visit

ПАРАМЕТРЫ ЗАПРОСА

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

{
   "success":true,
   "object": {
         "id":1953592530,
         "msgRealId": "<07e@nmk.com>",
         "email": "monkov@nelmk.com",
         "name": "Moiseenkov, Dmitriy",
         "firstName": "Dmitriy",
         "lastName": "Moiseenkov",
         "patronymicName": null,
         "gender": "male",
         "isCleanParsing": true,
         "gacid": "1372806527.1600149950",
         "ymcid": "1600149950687070718",
         "sendDate":1610434297000,
         "previousEmailDate":1610425586000,
         "subject": "задвижки CMO",
         "message": "Здравствуйте! Просим..",
         "attachmentsUrl": "https://files.alfa-track.com/email_attachments/491_85-2020_01_12__12_01_21-qen122%40mail.ru.zip",
         "ip": "91.229.189.248",
         "source": "yandex.ru",
         "medium": "referral",
         "campaign": "(not set)",
         "keyword": "(not set)",
         "socialNetwork": "(not set)",
         "adContent": "(not set)",
         "fullReferrer": "yandex.ru/",
         "city": "Lipetsk",
         "dateHourMinute": "202009150905",
         "sessionId": "1",
         "integrationId": null,
         "outVisitorId": "1427830.1600952",
         "outSessionId": "774153027",
         "searchPhrase":null,
         "browser": "Chrome",
         "country": "Russia",
         "deviceCategory": "desktop",
         "pagePath": "/about/",
         "analyticSystem": "GOOGLE_ANALYTICS",
         "attributionModel": "LAST_INTERACTION",
         "tags": "tag1,tag2",
         "customId": "942348510",
         "contragent": {
                "name": "ООО \"НПО Ризаур\"",
                "inn": "6234114211",
                "kpp": "621111101",
                "ogrn": "1136114002911",
                "address": "390555, Рязанская обл., Рязанский р-н, с. Добро, 1-й км., стр. 14ж, ОФИС 13",
                "representativeName": "Иванов Артем Андреевич",
                "representativePost": null,
                "fioForSignature": "Иванов А. А.",
                "revenue": 1.994191E9,
                "profit": 1.994191E9,
                "companyPriceValue": 1.773272E9,
                "active": true,
                "registrationDate": "2013-03-06",
                "liquidationDate": null,
                "reliability": "99",
                "category": "Контрольно-измерительные приборы (КИП)",
                "kved": "26.51.6",
                "website": "https://rizaur.ru",
                "domain": "rizaur.ru",
                "email": "sn@rizaur.ru",
                "phone": "+79219219219",
                "predictionData": true
            },
         "aiLeadScore": 88
      }
}
                

ПАРАМЕТРЫ ОТВЕТА

МЕТОД GET LEAD ATTACHMENTS

# Пример CURL запроса
curl -G \
'https://cloud.alfa-track.com/user/open/api/v1/lead/attachments' \
-H "Accept: application/json" \
-d token=YOUR_API_TOKEN \
-d email_id=5123456 \
-d offset=0 \
-d limit=20
                

Чтобы получить распознанный текст файлов, приложенных к письму, необходимо сделать GET запрос на следующий url:

https://cloud.alfa-track.com/user/open/api/v1/lead/attachments

Метод работает, только если в проекте включена опция «Распознавать текст вложений». Текст выдаётся только для файлов, распознанных с высокой достоверностью; остальные файлы перечисляются со статусом, но без текста.

Распознаются вложения писем, полученных начиная с 01.01.2026. Распознавание идёт в фоне, поэтому у свежего письма часть файлов может быть в статусе IN_PROGRESS — запрос можно повторить позже.

ПАРАМЕТРЫ ЗАПРОСА

Отсутствующий обязательный параметр, нечисловое значение или значение вне допустимого диапазона приводят к ошибке с кодом 40117.

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

{
  "success": true,
  "object": {
    "emailId": 5123456,
    "status": "DONE",
    "attachmentsUrl": "https://files.alfa-track.com/email_attachments/491_85-2026_09_12__10_15_00-client%40example.com.zip",
    "filesTotal": 4,
    "offset": 0,
    "limit": 20,
    "filesReturned": 4,
    "hasMore": false,
    "files": [
      {
        "id": 90211,
        "name": "Заявка.pdf",
        "path": "Заявка.pdf",
        "type": "pdf",
        "size": 184320,
        "pages": 2,
        "status": "READY",
        "text": "Заявка № 17 от 12.09.2026\nЗадвижка 30с41нж Ду100 — 4 шт.\n...",
        "headerFooterText": "ООО «Ромашка», ИНН 7700000000, тел. +7 495 000-00-00",
        "textLength": 1842,
        "headerFooterTextLength": 71,
        "textTruncated": false,
        "headerFooterTextTruncated": false
      },
      {
        "id": 90212,
        "name": "Реквизиты.docx",
        "path": "Реквизиты.docx",
        "type": "docx",
        "size": 20480,
        "pages": null,
        "status": "READY",
        "text": "Карточка предприятия\nПолное наименование: ...",
        "headerFooterText": null,
        "textLength": 913,
        "headerFooterTextLength": 0,
        "textTruncated": false,
        "headerFooterTextTruncated": false
      },
      {
        "id": 90213,
        "name": "image001.png",
        "path": "image001.png",
        "type": "png",
        "size": 5120,
        "pages": null,
        "status": "NO_TEXT",
        "text": null,
        "headerFooterText": null,
        "textLength": 0,
        "headerFooterTextLength": 0,
        "textTruncated": false,
        "headerFooterTextTruncated": false
      },
      {
        "id": 90215,
        "name": "Чертёж.dwg",
        "path": "Чертежи.zip/Чертёж.dwg",
        "type": "dwg",
        "size": 1048576,
        "pages": null,
        "status": "NOT_SUPPORTED",
        "text": null,
        "headerFooterText": null,
        "textLength": null,
        "headerFooterTextLength": null,
        "textTruncated": false,
        "headerFooterTextTruncated": false
      }
    ]
  }
}
                

ПАРАМЕТРЫ ОТВЕТА

Все поля присутствуют в ответе всегда; если значения нет, поле равно null.

Постраничная выдача. За один запрос возвращается не более 20 файлов. Чтобы получить следующую страницу, повторите запрос с offset, равным числу уже полученных файлов, пока hasMore равно true. Пока статус письма IN_PROGRESS, список файлов может меняться между запросами страниц: убирайте повторы по полю id, а если изменилось значение filesTotal — начните заново с offset=0. При статусе DONE список стабилен.

Ограничение длины текста. Каждое из полей text и headerFooterText содержит не более 200 000 символов. Полная длина текста и признак усечения возвращаются рядом — в полях textLength, headerFooterTextLength, textTruncated и headerFooterTextTruncated.

СТАТУСЫ ПИСЬМА

СТАТУСЫ ФАЙЛА

Для любого статуса, кроме READY, поля text, headerFooterText и pages равны null.

ОШИБКИ МЕТОДА

Ожидаемые ошибки метода приходят с HTTP-кодом 400; причина указана в полях httpStatus и errorCode тела ответа. Непредвиденный сбой сервера отвечает HTTP-кодом 500. Проверки выполняются в таком порядке: API ключ, опция распознавания, параметры запроса, письмо.

# Опция распознавания вложений выключена:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "errorCode": "40131",
  "errorMessage": "Feature 'ATTACHMENT_RECOGNITION' is disabled in project settings"
}

# Письмо не найдено:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "errorCode": "40000",
  "errorMessage": "Attachment email by id=5123456 doesn't exist"
}

# Неверный API ключ:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "errorCode": "40000",
  "errorMessage": "Project by API token doesn't exist"
}

# Некорректный параметр:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "errorCode": "40117",
  
"errorMessage": "There is a problem while validation: Attachment API parameter 'limit' must be between 1 and 20"
}
                

# Пример ошибки:

{
   "success":false,
   "httpStatus": "NOT_FOUND",
   "errorCode": "40000",
   
"errorMessage": "USER by token=WUxrTG9jN3Z1OWloNkpLZ3NuQmlIZz0 doesn't exist"
}
   

Ошибки

Alfa-Track API использует следующие коды ошибок:

Лимиты и ограничения

API работает в рамках одного Alfa-Track проекта.

Имеется ограничение на количество запросов в сутки, не более 1000.

Ограничено количество запросов в секунду, не более одного запроса в секунду.

Для метода GET LEAD ATTACHMENTS действует отдельный счётчик: не более 1000 запросов за окно 24 часа на клиента. Запрос каждой страницы файлов расходует один запрос.