Интеграции с API CPA.PartnerDataImport ¶

Что такое API CPA.PartnerDataImport?¶

API CPA.PartnerDataImport – это инструмент для автоматизации обработки клиентских данных. С его помощью можно:

Экспортировать данные профилей и когорт.
Импортировать данные о клиентах, чеках, кампаниях и событиях.
Отслеживать статусы импорта или экспорта данных.

API CPA.PartnerDataImport работает исключительно с форматом JSON

Как начать?¶

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

Какие ключи нужны?¶

API-ключ (ApiKey):

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

API-ключ можно найти в разделе → Настройки клиента.

Ключ авторизации (AuthKey):

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

Ключ авторизации можно найти в разделе → Как подключить сайт.

Эти ключи передаются в каждом запросе через параметры URL или в теле запроса (для POST).

Основные функции ¶

Экспорт данных клиента ¶

Получение списка запросов профилей

Метод: GET /partner/api/ProfileDataExport/GetProfileQueryList возвращает список доступных запросов для экспорта профилей. Параметры запроса:

apiKey (обязательный): ваш API-ключ.
authKey (обязательный): ключ авторизации.

Ответ:

[
  {
    "id": 1,
    "name": "ProfileQuery1",
    "description": "Запрос 1 для профилей",
    "isActive": true
  },
  {
    "id": 2,
    "name": "ProfileQuery2",
    "description": "Запрос 2 для профилей",
    "isActive": false
  }
]

Получение профиля клиента по запросу

Метод: GET /partner/api/ProfileDataExport/GetProfileByQuery возвращает данные клиента на основе идентификатора запроса.

Параметры запроса:

QueryId (обязательный): идентификатор запроса, полученный из предыдущего метода.
IdentityType (обязательный): тип идентификатора клиента (0 – Cookie, 1 – Phone, 2 – Email, 3 – Vk).
IdentityValue (обязательный): значение идентификатора (например, номер телефона или email).
authKey и apiKey (обязательные).

Ответ (успешный):

{
  "id": 123,
  "name": "Иван Иванов",
  "email": "ivan@example.com",
  "phone": "+71234567890"
}

Импорт данных ¶

API поддерживает загрузку различных типов данных. Все запросы используют метод POST.

Импорт профилей клиентов

Метод: POST /partner/api/ProfileDataImport/ImportProfile загружает данные о клиентах.

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

{
  "authKey": "вашAuthKey",
  "actionType": 0, // Тип действия (0 - добавление, 1 - обновление)
  "dataSet": [
    {
      "identity": {
        "identityTypeCode": 1, // Например, номер телефона
        "identityValue": "+71234567890"
      },
      "profile": {
        "name": "Иван Иванов",
        "email": "ivan@example.com"
      }
    }
  ]
}

Ответ (успешный):

{
  "id": 1,
  "successfullyProcessed": 1,
  "errorProcessed": 0
}

Импорт чеков

Метод: POST /partner/api/ProfileDataImport/ImportReceiptData загружает данные о покупках пользователей.

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

{
  "authKey": "вашAuthKey",
  "actionType": 0,
  "dataSet": [
    {
      "identity": {
        "identityTypeCode": 1,
        "identityValue": "+71234567890"
      },
      "purchaseDt": "2023-01-01T12:00:00",
      "receiptNum": "123456",
      "items": [
        {
          "itemNum": 1,
          "productExternalId": "SKU123",
          "amount": 2,
          "price": 100.0,
          "discount": 10.0
        }
      ]
    }
  ]
}

Импорт маркетинговых кампаний

Метод: POST /partner/api/ProfileDataImport/ImportProfileCampaign добавляет или обновляет маркетинговые кампании.

Параметры:

{
  "authKey": "вашAuthKey",
  "actionType": 0,
  "dataSet": [
    {
      "id": "campaign123",
      "name": "Летняя распродажа",
      "startDt": "2023-06-01T00:00:00",
      "endDt": "2023-06-30T23:59:59",
      "channelType": 0, // Тип канала (0 - Email, 1 - SMS)
      "active": true
    }
  ]
}

Работа с когортами ¶

Экспорт когорт

Метод: PUT /partner/api/SegmentDataExport/ExportSegmentToExcel выгружает данные в формате Excel.

Параметры запроса:

SegmentId (обязательный): идентификатор сегмента.
IdentityType (обязательный): тип идентификатора профиля.
authKey и apiKey (обязательные).

Ответ (успешный):

{
  «id»: «task123»,
  «status»: «Created»
}

Получение статуса экспорта

Метод: GET /partner/api/SegmentDataExport/StatusForExport возвращает статус задачи экспорта.

Параметры запроса:

TaskId (обязательный): идентификатор задачи.
authKey и apiKey (обязательные).

Ответ (успешный):

{
  "status": "Completed",
  "filePath": "/exports/segment123.xlsx"
}

Проверка статуса импорта ¶

Метод: POST /partner/api/ProfileDataImport/StatusForImport проверяет статус задачи импорта данных.

Параметры запроса:

{
  "authKey": "вашAuthKey",
  "taskId": "importTask123"
}

Ответ:

{
  "status": "Completed",
  "successfullyProcessed": 100,
  "errorProcessed": 0
}

Коды ошибок (401, 400, 500)¶

401 (Unauthorized)

Возникает, если ключи авторизации (AuthKey или ApiKey) отсутствуют или указаны неверно. Необходимо проверить их правильность и актуальность.

Решение: Убедитесь, что ключи переданы в запросе и соответствуют требованиям системы.

400 (Bad Request)

Указывает на ошибку в формате запроса. Это может быть неверная структура JSON, отсутствие обязательных параметров или использование недопустимых значений.

Решение: Перепроверьте тело запроса и следуйте указанным в документации требованиям.

500 (Internal Server Error)

Это ошибка на стороне сервера, которая может быть вызвана внутренними сбоями системы.

Решение: Обратитесь в техническую поддержку с деталями запроса и времени ошибки.