Перейти к основному содержимому

Интеграция Aplaut через Platform API

Пошаговый план интеграции без виджетов, с синхронизацией UGC-контента на бэкенде

Чек-лист перед началом интеграции​

Пожалуйста, убедитесь, что у вас:

  1. Заключен договор с Aplaut
  2. Создан аккаунт в платформе
  3. Есть выделенный специалист или команда для проведения интеграции

Интеграция. Подготовительные этапы​

  1. В разделе Команда ЛК Aplaut, созданного после заключения договора, добавьте коллег, которым необходим доступ на этапе интеграции, а также после нее.

  2. В ЛК Aplaut добавьте набор виджетовдля установки на сайт. Рекомендуем при подключении использовать название "По умолчанию", а системное название "default", как отправная точка. В дальнейшем, если у вас будет редизайн сайта или мы обновим виджеты, можно будет добавить новые наборы с другим наименованием.

  3. Если до подключения Aplaut у вас были накоплены отзывы, импортируйте их, чтобы сохранить текущую картину по рейтингам и отзывам на сайте.

    Подготовьте файл в одном из форматов: XLSX, CSV или JSONL.

    • XLSX или CSV подойдут, если у вас только отзывы, без комментариев и ответов вашей команды, и нет отзывов без текста. Эти форматы проще подготовить. Требования к файлу и порядок импорта описаны в статье «Импорт данных в кабинете».
    • JSONL нужен, если у отзывов есть комментарии и ответы либо есть отзывы без текста. Каждая строка описывает один отзыв с комментариями, файл лучше сжать gzip. Формат описан на jsonlines.org, пример файла лежит на Google Drive, полный список полей — в разделе импорта.

Интеграция. Основные этапы​

примечание

Работы по основному этапу могут выполняться параллельно с подготовительными. Это не должно тормозить интеграцию.

Синхронизация данных​

Клиент ↔ Aplaut

  1. Важный элемент в платформе Aplaut — товар. Все основные процессы и почти все дополнительные завязаны на товаре. Поэтому важно обеспечить своевременную передачу и обновление данных о товарах, для этого в платформу импортируется каталог (фид):Ознакомьтесь с требованиями к каталогу и подготовьте файл в необходимом формате;Если у вас есть товары, у которых есть варианты и на сайте такие товары объединены в мультикарточки, группируйте товары в фиде чтобы отзывы на отдельный вариант товара отображались у всех товаров;Подготовьте прямую ссылку на файл фида для его скачивания и сохраните ссылку в настройках импорта, в ЛК Aplaut (поддерживается сжатие Gzip и Basic авторизация), а также включите Автоматическое скачивания файла.

  2. Отправка новых отзывов и комментариев к ним через Submissions API (см. документацию).

    Чтобы пользователи могли оставлять отзывы без текста (только рейтинг или рейтинг с фото или видео), активируйте эту функцию через поддержку Aplaut: напишите на support@aplaut.com, в телеграм @aplaut_support_bot или в чат поддержки в личном кабинете. При передаче отзыва добавьте атрибут wordless со значением true для отзыва без текста и false для отзыва с текстом.

    Если отзыв можно оставлять только на купленные товары, проверку факта покупки реализуйте на своей стороне.

Как отправить отзыв с текстом через Submissions API:

    curl -X POST https://s-api.aplaut.io/v2/reviews \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
      --data-raw '{
        "review": {
            "rating": 5,
            "wordless": false,
            "body": "Текст отзыва",
            "pros": "Текст поля Достоинства",
            "cons": "Текст поля Недостатки,
            "recommended": true,
            "author_id": "qwerty123",
            "author_name": "Манишева Рада Якимовна",
            "author_email": "youname@yourmail.ru",
            "author_phone": "79991112233",
            "location_name": "Уфа",
            "photo_urls": ["https://yoursite.ru/picture1.png", "https://yoursite.ru/picture1.png"],
            "photo_ids": ["8787258c9549834e99febf05", "8787258c9549834e99febf06"],
            "video_ids": ["654258c9549834e99febf05c"],
            "product_id": "178963",
            "author_ip": "178.214.291.62",
            "hide_my_data": false
         }
    }'

Как отправить отзыв без текста через Submissions API:

    curl -X POST https://s-api.aplaut.io/v2/reviews \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
      --data-raw '{
        "review": {
            "rating": 5,
            "wordless": true,
            "recommended": true,
            "author_id": "qwerty123",
            "author_name": "Иван",
            "author_email": "youname@yourmail.ru",
            "author_phone": "79991112233",
            "location_name": "Уфа",
            "photo_urls": ["https://yoursite.ru/picture1.png", "https://yoursite.ru/picture1.png"],
            "photo_ids": ["8787258c9549834e99febf05", "8787258c9549834e99febf06"],
            "video_ids": ["654258c9549834e99febf05c"],
            "product_id": "178963",
            "author_ip": "178.214.291.62",
            "hide_my_data": false
         }
    }'

Как отправить комментарий к отзыву через Submissions API:

    curl  -X POST https://s-api.aplaut.io/v2/reviews/{REVIEW_ID}/comments] \
      --header 'Accept: */*' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
      --data-raw '{
      "comment": {
        "text": "Текст комментария на отзыв",
        "author_id": "qwerty123",
        "author_name": "Иван",
        "author_email": "yorname@yourmail.ru",
        "hide_my_data": true
      }
    }'

Как отправить комментарий к комментарию через Submissions API:

    curl  -X POST https://s-api.aplaut.io/v2/reviews/{REVIEW_ID}/comments] \
      --header 'Accept: */*' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer token={APLAUT_TOKEN}' \
      --data-raw '{
      "comment": {
        "text": "Текст комментария на комментарий",
        "parent_id": {REVIEW_ID},
        "external_parent_id": {REVIEW_EXTERNAL_ID}
        "author_id": "qwerty123",
        "author_name": "Иван",
        "author_email": "yorname@yourmail.ru",
        "hide_my_data": true
      }
    }'

*список других полей можно посмотреть тут*

Aplaut → Клиент​

Для синхронизации контента, а также рейтингов и кол-ва отзывов на товары используйте периодические экспорты раз в сутки.

**Экспорт дельты обновленных товаров.**Чтобы получить дельту за определенный период, нужно создать задачу на экспорт, указав в параметрах соотвествующий фильтр в параметре search_option. Например, за текущую дату:

curl  -X POST \
  'http://api.aplaut.io/v4/export_tasks' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \
  --data-raw '{
  "data": {
    "type": "export_tasks",
    "attributes": {
      "records_type": "products",
      "search_options": {
        "filter": {
            "updated_at": {
                "eq": "ГГГГ-ММ-ДД"
            }
        },
      },
      "format": "jsonl"
    }
  }
}'

В ответе будет ID задачи, статут которой нужно проверять не чаще 1 раз в 1 минуту. Пример запроса:

curl 'https://api.aplaut.io/v4/export_tasks/{TASK_ID}' \
  -H 'Authorization: Bearer token={TOKEN}'

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

 {
  "data": {
    "id": "TASK_ID",
    "type": "export_tasks",
    "attributes": {
      "records_type": "products",
      "search_options": {
        "filter": {"created_at": {"eq": "ГГГГ-ММ-ДД"}},
      },
      "state": "completed",
      "refuse_reason": null,
      "error_message": null,
      "format": "jsonl",
      "export_format": null,
      "archive_url": "{ARCHIVE_URL}",
      "archive_size": 144696,
      "archive_content_type": "application/gzip",
      "created_at": "2023-11-03T17:00:41.353+03:00",
      "updated_at": "2023-11-03T17:14:53.529+03:00",
      "started_at": "2023-11-03T17:14:47.633+03:00",
      "finished_at": "2023-11-03T17:14:53.529+03:00"
    }
  }
}

Когда state=completed, параметр archive_url будет содержать URL c архивом файла экспорта.

Экспорт дельты новых и обновленных отзывов за день.

По аналогии с товарами, чтобы получить дельту за определенный период, нужно создать задачу на экспорт, указав в параметрах соотвествующий фильтр. В отличии от товаров в records_type значение reviews:

curl  -X POST \
  'http://api.aplaut.io/v4/export_tasks' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \
  --data-raw '{
  "data": {
    "type": "export_tasks",
    "attributes": {
      "records_type": "products",
      "search_options": {
        "filter": {
            "updated_at": {
                "eq": "ГГГГ-ММ-ДД"
            }
        },
      },
      "format": "jsonl"
    }
  }
}'

Также, по аналогии с экспортом товаров, необходимо проверять статус задачи.

Ограничения экспорта:

  1. Существует квота на суммарное кол-во времени всех экспортов за день для всего аккаунта. По умолчанию 1 час в день;
  2. Если квота превышена, то задачи на экспорт отклоняются сразу после старта задачи. Бесполезно дальше создавать следующие задачи;
  3. Очень редко задача может "подвиснуть". Её статус никогда не станет completed. Если за 3 часа статус задачи не поменялся, считайте что она "подвисла". Создавайте новую;
  4. Статус всех задач можно наблюдать в ЛК тут;
  5. Такой способ синхронизации оптимизирует кол-во запросов, отправляемых в Aplaut, а также только так можно реализовать сортировку товаров и фильтрацию товаров на листинг-страницах сайта, т.к. параметры должны быть сохранены у товара в вашей БД.

Альтернативы экспортам.

В качестве альтернативы экспортам, для синхронизации контента можно использовать веб-хуки. Для настройки необходимо:

  1. Передать менеджеру Aplaut URL хоста, на который нужно отправлять вебхук.
  2. Если установлена защита по IP, добавить наши IP в белый список, предварительно уточни их у своего менеджера или в чате технической поддержки.
  3. Выбрать событие или несколько событий, на которые будет срабатывать

На какие события веб-хука можно подписаться.

Отзывы:

create_review, update_review, destroy_review, publish_review, ban_review, update_review_tags, create_comment, update_comment, destroy_comment, publish_comment, ban_comment, update_comment_tags

Вопросы и ответы:

create_question, update_question, destroy_question, create_answer, update_answer, destroy_answer

Как выглядит содержание веб-хука можно посмотреть в файле с примером.

Справочная информация​

  1. База знаний
  2. Документация Widgets API
  3. Документация Submissions API
  4. Документация Platform API