Skip to content

Управление промокодами

API позволяет получить список промокодов, создать новый, изменить условия действия и удалить промокод. Все запросы используют HTTP Basic авторизацию и поля application/x-www-form-urlencoded.

Общие правила

  • uid - владелец промокода в CRM. Отрицательный UID допустим.
  • uid=0 - общий промокод без владельца. Его может применить любой покупатель.
  • all_products=1 - промокод действует на все товары в стандартном оформлении заказа WinWinLand. В базе это product_id=1.
  • Для отдельных товаров передавайте один или несколько параметров product_ids[].
  • product_ids[]=1 также означает все товары. Его нельзя передавать вместе с другими ID товаров.
  • Укажите ровно один вид выгоды: discount или price. Значение discount от 1 до 99 задает скидку в процентах, от 100 - скидку в рублях. price задает итоговую цену.

Создание, изменение и удаление выполняются последовательно для одного аккаунта. Если другой запрос уже меняет промокоды, API вернет 503. После сохранения в CRM API по умолчанию запускает синхронизацию со всеми настроенными внешними магазинами и возвращает ее результат отдельно. Ошибка синхронизации не отменяет сохраненный промокод. При создании или изменении передайте sync_external=0, чтобы сохранить изменения только в CRM, без синхронизации с внешними магазинами. Значение 1 включает синхронизацию; другие значения дают ошибку 400.

Получить список промокодов

Endpoint: GET /promocodes/

Необязательные параметры:
uid - UID владельца. Для общих промокодов укажите 0.
promocode - код промокода.
limit - число записей от 1 до 200, по умолчанию 100.
offset - смещение, по умолчанию 0.

curl -sS -G "$BASE_URL/promocodes/" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "uid=0" \
  --data-urlencode "promocode=PUBLIC10"

Создать промокод

Endpoint: POST /promocodes/

Обязательные параметры:
promocode - код до 50 символов.
uid - UID владельца или 0 для общего промокода.
tm1 - время начала действия, Unix timestamp.
tm2 - время окончания действия, Unix timestamp.
discount или price - один вид выгоды.
product_ids[] или all_products=1 - область действия.

Необязательные параметры:
fee_1, fee_2 - партнерское вознаграждение.
cnt - лимит применений. -1 означает без ограничения.
hold - срок удержания начисления.
keep - 0 или 1.
sync_external - 1 по умолчанию; 0 отключает синхронизацию со всеми внешними магазинами для этого запроса.

Пример общего промокода на 10% для всех товаров:

curl -sS -X POST "$BASE_URL/promocodes/" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "promocode=PUBLIC10" \
  -d "uid=0" \
  -d "tm1=1793203200" \
  -d "tm2=1795795200" \
  -d "discount=10" \
  -d "all_products=1"

Пример промокода для товаров с ID 12 и 19:

curl -sS -X POST "$BASE_URL/promocodes/" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "promocode=WELCOME10" \
  -d "uid=-12345" \
  -d "tm1=1793203200" \
  -d "tm2=1795795200" \
  -d "discount=10" \
  -d "product_ids[]=12" \
  -d "product_ids[]=19"

Для создания без синхронизации добавьте к этому запросу -d "sync_external=0".

Изменить промокод

Endpoint: POST /promocodes/update/

Передайте promocode и uid существующего промокода, затем полный новый набор настроек:
tm1, tm2, discount или price, product_ids[] или all_products=1.

Дополнительно: fee_1, fee_2, cnt, hold, keep, sync_external (1 по умолчанию, 0 отключает синхронизацию).

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

Удалить промокод

Endpoint: POST /promocodes/delete/

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

Необязательные параметры:
product_ids[] - удалить привязки только к указанным товарам.
all_products=1 - удалить привязку ко всем товарам.

Если не передавать ни product_ids[], ни all_products, API удалит все привязки указанного промокода. Удаление действует в CRM. Удаление купона во внешнем магазине не поддерживается текущими интеграциями.

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

{
  "ok": true,
  "local_saved": true,
  "promocode": "PUBLIC10",
  "uid": 0,
  "all_products": true,
  "bindings": [{"id": 123, "product_id": 1}],
  "sync_enabled": true,
  "sync": [{
    "id": 123,
    "providers": {
      "insales": "success",
      "yandex_kit": "skipped",
      "nethouse": "skipped"
    }
  }]
}

Поле local_saved=true подтверждает сохранение в CRM. Если передано sync_external=0, ответ содержит sync_enabled=false и пустой массив sync=[]. Возможные статусы внешней синхронизации: success, failed, skipped и unknown. Значение unknown означает, что интеграция не смогла подтвердить результат, например при уже существующем коде в InSales.

Ошибки

  • 400 - неверные параметры, даты, товары или область действия.
  • 404 - владелец, товар или изменяемый промокод не найден.
  • 409 - код уже принадлежит другому владельцу или для товара уже есть другой промокод владельца.
  • 503 - промокоды этого аккаунта сейчас изменяются другим запросом. Повторите запрос позднее.