Справочник API

База

• Базовый адрес — https://v2.1opd.ru/api/v2. Он один для всех клиентов: к какой компании относится запрос, платформа понимает по ключу.
• Все запросы — POST с JSON-телом. Ключ — в заголовке API-KEY.
• Ответы приходят без обёрток: успех create-agreement — объект с hash, успех get-fields — сразу массив. Ошибка — объект с полем reason на русском, иногда с машинным признаком error.
• Успехом приёма согласия считаются и 200, и 202. Проверка «строго 200» отметит ошибкой согласие, которое платформа приняла и доставит.

Ключи выпускаются в кабинете: раздел «Интеграция». Там же лежит готовый код с уже подставленными ключом и идентификаторами форм.

Ключи и защита

pk_…публикуемый

Для кода, который исполняется в браузере. Виден каждому посетителю — это нормально: защита строится на списке доменов (Origin), с которых принимаются запросы. Права — приём согласий; читать и удалять записи из браузера нельзя.

sk_…секретный

Только для кода на сервере; в браузер и публичный репозиторий попадать не должен. Защита — список IP-адресов, HMAC-подпись или оба механизма сразу. Права выбираются при выпуске: приём, чтение, удаление.

Частая ошибка подключения — не тот ключ или не та защита: например, IP-список для кода в браузере, где адрес у каждого посетителя свой. Сверьтесь с таблицей.

Приём согласия

POST /api/v2/create-agreement

Главный эндпоинт: создаёт запись согласия. Работает и с pk_, и с sk_. Записывается всё, что потом понадобится для доказательства: поля, время, источник, действовавшие редакции текста согласия и политики.

POST /api/v2/create-agreement HTTP/1.1
Host: v2.1opd.ru
API-KEY: sk_ваш_ключ
Content-Type: application/json

{
  "form_id": 12,
  "hash_field": "user@example.com",
  "consent_given": true,
  "fields": [
    { "field": "email", "value": "user@example.com" },
    { "field": "first_name", "value": "Иван" },
    { "field": "phone_number", "value": "+79991234567" }
  ]
}

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

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

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

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

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

Массив { field, value }. Имена — из состава формы (см. поля субъекта и get-fields). Поле, которого в форме нет, даёт 400 Unknown field. Регистр не важен: Email и email — одно поле.

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

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

form_nameпо желанию

Имя формы в разметке страницы (например, form123456789 у Тильды). По нему кабинет предлагает привязку формы к блоку сайта.

unmapped_fieldsпо желанию

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

Что вернёт приём

HTTP/1.1 200 OK

{
  "hash": "0622845210A8C5136424513435FA90EB",
  "hash_field": "user@example.com",
  "fields": [
    { "field": "email", "value": "user@example.com" },
    { "field": "first_name", "value": "Иван" },
    { "field": "phone_number", "value": "+79991234567" }
  ]
}

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

HTTP/1.1 202 Accepted

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

Состав полей формы

POST /api/v2/get-fields

Отдаёт поля формы, к которой привязан ключ, — именно эти имена принимает fields в запросе согласия. Работает только с ключом, выпущенным на одну форму: у ключа на несколько форм составы разные, и запрос ответит 403. Тело можно отправить пустым.

POST /api/v2/get-fields HTTP/1.1
Host: v2.1opd.ru
API-KEY: sk_ключ_этой_формы
Content-Type: application/json

{}

HTTP/1.1 200 OK

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

Чтение записи

POST /api/v2/get-user

Возвращает данные субъекта по hash согласия. Нужны право «чтение» на ключе и ключ одной формы. Пригодится для ответа на запрос человека о его данных.

POST /api/v2/get-user HTTP/1.1
Host: v2.1opd.ru
API-KEY: sk_ключ_этой_формы
Content-Type: application/json

{ "hash": "0622845210A8C5136424513435FA90EB" }

[
  { "field": "email", "value": "user@example.com" },
  { "field": "first_name", "value": "Иван" }
]

# Согласие отозвано или истекло — 200 с пояснением вместо данных:
# { "status": "По данному hash был пользователь, но он был удалён. Данные недоступны." }

# hash не существует (или прошёл срок хранения) — 404:
# { "reason": "Entity not found" }

Отзыв и стирание

POST /api/v2/delete-user

Отзывает все согласия субъекта в этой форме и стирает его персональные данные; сам факт «согласие было и отозвано тогда-то» остаётся в журнале — это часть доказательства. Нужно право «удаление»; публикуемым ключом pk_ удалять нельзя.

POST /api/v2/delete-user HTTP/1.1
Host: v2.1opd.ru
API-KEY: sk_ключ_этой_формы
Content-Type: application/json

{ "hash": "0622845210A8C5136424513435FA90EB" }

# Ответ: { "status": 200 }
# Субъект уже удалён ранее — 200 с тем же пояснением, что у get-user.
# hash не существует — 404: { "reason": "Entity not found" }

HMAC-подпись

Включается на ключе по желанию (для sk_): каждый запрос подписывается секретом, и перехваченный ключ без секрета бесполезен. После включения запросы без подписи не принимаются.

import base64, hashlib, hmac, json, time

ts = str(int(time.time()))                  # unix-время, секунды
body = json.dumps(payload).encode()         # ровно те байты, что уйдут в запрос
secret = base64.b64decode(secret_b64)       # секрет из кабинета хранится в base64

sign = hmac.new(secret, ts.encode() + b"\n" + body, hashlib.sha256).hexdigest()

headers = {
    "API-KEY": "sk_...",
    "API-TIMESTAMP": ts,
    "API-SIGN": sign,   # hex, 64 символа в нижнем регистре. Не base64.
}

• Алгоритм — HMAC-SHA256. Сообщение — время + "\n" + байты тела, ровно те, что уходят в запрос, до любых переформатирований JSON.
• Секрет выдаётся в кабинете в base64 — перед подписью его декодируют в байты.
• Подпись — в шестнадцатеричном виде, 64 символа в нижнем регистре. Не base64: это самая частая причина вечного 401.
• Заголовки — API-TIMESTAMP (unix-время в секундах) и API-SIGN. Допустимое расхождение часов — 300 секунд.

Списки доменов и адресов

Originдля pk_

С каких доменов принимаются запросы; сверяется заголовок Origin или хост из Referer. Формат — только хост, без https:// и порта: example.com. Шаблон *.example.com покрывает поддомены, но не сам example.com — его вносят отдельной строкой. Запрос без Origin (curl без заголовка) отклоняется.

IPдля sk_

С каких адресов принимаются запросы; поддерживаются отдельные IPv4/IPv6 и сети CIDR (10.0.0.0/24). Вносите исходящий адрес своего сервера — у хостинга он может отличаться от адреса сайта (curl ifconfig.me с сервера покажет его). Для серверов с меняющимся адресом список не подходит — берите HMAC.

Оба списка редактируются в кабинете на карточке ключа и применяются сразу.

Один ключ на несколько форм

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

# Ключ с forms_scope: [12, 13, 21]
form_id: 12 → принято
form_id: 21 → принято
form_id: 40 → 403 «Форма не разрешена ключом»

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

Коды ошибок

Тело ошибки — { "reason": "..." }, текст на русском. В таблице — ошибки самого запроса; 202 и 503 ошибками не являются и разобраны выше.

Поля субъекта

В fields передаются любые из 28 полей ниже — имя поля указывается в field. Обязательное одно: email, он же обычно идентификатор. Пустые поля не передавайте. Все значения хранятся зашифрованными; значение — строка до 5000 символов. Какие поля включены у конкретной формы — в её карточке и в get-fields.

Проверка руками

Самый короткий способ убедиться, что ключ работает, — отправить create-agreement из терминала или Postman и найти запись в кабинете, в реестре согласий. Две оговорки:

• для pk_-ключа добавьте заголовок Origin с разрешённым доменом вручную — инструменты вне браузера сами его не ставят;
• проверка не заканчивается на ответе 200 — она заканчивается записью в реестре. Ключ мог писать в другую форму, чем вы ожидали.