Интеграция промо-сайта

Что подключаем

Промо-сайт остаётся вашим: платформа не заменяет форму, не хранит её и не вмешивается в вёрстку. После того как форма успешно отправлена вашим обработчиком, сайт делает ещё один запрос — к нам. Мы записываем, кто согласился, когда, по какой форме и какой текст согласия действовал в тот момент.

Отправлять согласие нужно только после успеха вашей отправки. Если форма не ушла, согласия нет: расхождение «в CRM участников больше, чем в реестре» разбирать потом нечем.

Что взять у организатора

Всё перечисленное организатор находит в кабинете 1ОПД, в карточке акции и её форм. Без этих пяти пунктов подключение не начинается.

• Адрес приёма — https://v2.1opd.ru.
• Ключ — sk_… для отправки с сервера или pk_… для отправки из браузера.
• Идентификатор формы (form_id) для каждой формы акции. Их обычно две: участие и рекламные сообщения.
• Состав полей каждой формы — точные имена, которые примет приём. Поле, которого в форме нет, будет отклонено.
• Публичные адреса документов — политика и текст согласия. На них ссылается страница акции рядом с галочкой.

curl -X POST https://v2.1opd.ru/api/v2/get-fields \
  -H 'API-KEY: sk_ключ_этой_формы' \
  -H 'Content-Type: application/json' \
  -d '{ "form_id": 12 }'

# [{"field_name":"email","field_title":"Электронная почта"},
#  {"field_name":"name","field_title":"Имя"}]

Этот запрос работает с ключом, выпущенным на одну форму. Ключ, покрывающий все формы сайта, для чтения полей не подойдёт — состав полей у форм разный, и выбрать за вас платформа не может.

Серверный ключ или браузерный

Ключи отличаются не правами, а тем, где им можно находиться.

sk_…серверный

Отправка с вашего бэкенда: PHP, Node, Python, обработчик формы CMS. Ключ секретный, в браузер не попадает. Ограничивается списком IP-адресов, с которых принимаем запрос. У хостинга исходящий адрес может отличаться от адреса сайта — сверьте его заранее.

pk_…браузерный

Отправка из JavaScript на статичном сайте, в React или Vue. Ограничивается списком доменов (Origin) — это обязательный минимум. Секретный ключ в код страницы класть нельзя: всё, что попало в браузер, считается известным всем.

forms_scopeодин ключ на сайт

Ключ может обслуживать все формы акции сразу. Тогда конкретную форму выбирает form_id в теле запроса. Отдельный ключ на каждую форму заводить не нужно.

Отправка согласия

Один эндпоинт: POST /api/v2/create-agreement. Ключ — в заголовке API-KEY, тело — JSON.

curl -X POST https://v2.1opd.ru/api/v2/create-agreement \
  -H 'API-KEY: sk_ваш_серверный_ключ' \
  -H 'Content-Type: application/json' \
  -d '{
    "form_id": 12,
    "hash_field": "participant@example.com",
    "consent_given": true,
    "fields": [
      { "field": "email", "value": "participant@example.com" },
      { "field": "name",  "value": "Иван Петров" },
      { "field": "phone", "value": "+79991234567" }
    ]
  }'

form_idобязательно для ключа на несколько форм

Какая форма акции. Если ключ выпущен на одну форму, поле можно не передавать; передадите чужой идентификатор — запрос будет отклонён, а не молча записан в другую форму.

hash_fieldобязательно

Значение, по которому мы узнаём человека, обычно электронная почта. Два согласия с одним значением станут двумя версиями одной записи, а не двумя участниками. Значение хранится зашифрованным.

fieldsобязательно

Массив { field, value }. Имена — из состава формы. Лишнее поле даёт 400: это защита от опечаток, из-за которых данные молча теряются.

consent_givenпередавайте всегда

Отметка галочки, проверенная на вашей стороне. true — отметка была, так и запишем. false — приём откажет: согласие без отметки не записывается. Не передадите — запись сохранится, но в ней останется «неизвестно», и предъявить отметку будет нечем.

form_nameпо желанию

Как форма называется в разметке страницы. По этому имени кабинет свяжет форму акции с блоком на сайте.

unmapped_fieldsпо желанию

Имена полей формы, которым не нашлось соответствия в согласии. Только имена, без значений: организатор увидит в кабинете, что форма собирает больше, чем покрывает текст согласия.

// Серверный обработчик промо-сайта: сначала своя механика,
// потом отправка согласия. Ключ живёт в переменных окружения.
const OPD_URL = "https://v2.1opd.ru/api/v2/create-agreement";

async function sendConsent({ formId, email, name, phone }) {
  const res = await fetch(OPD_URL, {
    method: "POST",
    headers: {
      "API-KEY": process.env.OPD_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      form_id: formId,
      hash_field: email,
      consent_given: true,
      fields: [
        { field: "email", value: email },
        { field: "name", value: name },
        { field: "phone", value: phone },
      ],
    }),
  });

  if (res.status === 200 || res.status === 202) return res.json();
  if (res.status === 503) throw new RetryableError(await res.text());

  // 4xx — дело в самом запросе: ключ, форма, состав полей, сроки акции.
  // Повтор того же тела не поможет, поэтому пишем в лог и разбираемся.
  throw new Error(`1ОПД ${res.status}: ${await res.text()}`);
}

Ответ и коды ошибок

HTTP/1.1 200 OK

{
  "hash": "0622845210A8C5136424513435FA90EB",
  "hash_field": "participant@example.com",
  "fields": [
    { "field": "email", "value": "participant@example.com" },
    { "field": "name",  "value": "Иван Петров" }
  ]
}

hash — идентификатор согласия, 32 шестнадцатеричных символа. Сохраните его: по нему потом читают запись и обрабатывают запрос участника.

HTTP/1.1 202 Accepted

{
  "status": "queued",
  "idempotency_key": "d4e5f6a7b8c9d0e1...",
  "check_url": "/spool/status/d4e5f6a7b8c9d0e1...",
  "original_path": "/api/v2/create-agreement"
}

Участие и реклама — две формы

Участие в акции и согласие на рекламные сообщения — разные основания и разные тексты. В платформе это две формы с разными form_id, и в реестре видно, на что именно согласился человек.

На странице это две отдельные галочки. Отмечена только первая — отправляете одно согласие по форме участия. Отмечены обе — два запроса, каждый со своим form_id и своим consent_given: true. Отправлять рекламное согласие «заодно», потому что человек участвует в акции, нельзя.

Подпись запроса

Организатор может включить обязательную подпись — тогда к каждому запросу добавляются два заголовка. Допустимое расхождение часов — 5 минут.

// Подпись включается по требованию организатора.
// Секрет выдаётся один раз в кабинете, в base64.
const ts = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify(payload); // подписываем ровно то тело, что уйдёт

const sign = crypto
  .createHmac("sha256", Buffer.from(process.env.OPD_HMAC_SECRET, "base64"))
  .update(ts + "\n" + body)
  .digest("hex");   // hex, не base64

const headers = {
  "API-KEY": process.env.OPD_API_KEY,
  "Content-Type": "application/json",
  "API-TIMESTAMP": ts,
  "API-SIGN": sign,
};

Подпись передаётся в шестнадцатеричном виде, не в base64 — в base64 приходит сам секрет. Подписывается ровно то тело, которое уходит, до любых переформатирований JSON.

Проверка до трафика

1. Отправьте один запрос из терминала, ещё не трогая сайт. Ответ 200 и hash в теле означают, что путь до платформы работает.
2. Отправьте форму на опубликованном промо-сайте — не на локальной копии и не через внутренний тестер.
3. Попросите организатора найти запись в карточке акции. Пока записи там нет, интеграция не работает, даже если сайт не показал ошибки.

Сроки акции и запросы участников

После даты окончания акции приём новых согласий закрывается: платформа отвечает 410 с признаком promo_finished и датой завершения. Ранее принятые записи остаются. Предусмотрите этот код в обработчике — иначе форма на забытой странице будет молча терять данные участников.

Если промо-сайт умеет отвечать на запросы участников, для этого есть отдельные эндпоинты: POST /api/v2/get-user отдаёт данные по hash согласия, POST /api/v2/delete-user прекращает обработку. Оба работают ключом, выпущенным на одну форму. Отдельная интеграция не обязательна: у оператора есть публичная форма обращений, её адрес выдаёт кабинет.

Что остаётся на стороне сайта

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

За сайтом остаётся и то, что участник видит: галочка не отмечена заранее, рядом с ней стоят ссылки на политику и текст согласия, отправка согласия идёт после успешной отправки формы. Запись в реестре подтверждает факт и содержание согласия — она не исправляет форму, собравшую больше данных, чем покрывает её текст.