Загружаем 1ОПД
Подготавливаем страницу…
Server-side API: PHP, Node.js, Python
Самый надёжный способ интеграции: ключ sk_ остаётся на сервере, защита идёт через IP whitelist или HMAC. Подходит любому языку и любой инфраструктуре.
⏱ Время
~20-30 минут
Зависит от языка и фреймворка. Простой случай (PHP и cURL) занимает 15 минут.
Что нужно знать
Базовый разработчик
Один из языков (PHP, Node, Python) и работа с ENV-переменными.
Доступы
Сервер · 1ОПД
SSH или деплой к серверу, плюс ЛК 1ОПД для выпуска ключа.
Какой ключ и какая защита
- Тип ключа:
sk_(secret, только server-side) - Защита: IP whitelist для сервера со статическим адресом либо HMAC-подпись для контейнеров, serverless и k8s. При повышенных требованиях ставят обе.
- Multi-form: 1 ключ на сайт с
forms_scope=[id1, id2, …], и в каждом запросе передаётеform_idв body. - Bare-metal и VPS со статикой → IP whitelist. Docker, k8s, Lambda, Cloud Run → HMAC. Прод и stage на разных адресах → проще HMAC.
Ключ создаёт менеджер 1ОПД и передаёт вам один раз. Все endpoints → API Reference
Что значат эти слова
Прочитайте один раз: дальше в инструкции эти слова уже не будут пугать.
Ключ sk_ (secret)
Серверный ключ. Живёт в ENV-переменных сервера, посетителям сайта не виден.
Состоит из префикса sk_ и 64 hex-символов. В client-side bundle и в HTML попадать не должен.
IP whitelist
Список IP-адресов, с которых 1ОПД принимает запросы с этим ключом.
Простой и быстрый способ защиты. Ограничение: при смене адреса (новый VPS, миграция) список надо обновлять.
HMAC-подпись
Криптографическая подпись каждого запроса: 1ОПД проверяет, что тело подписал владелец секрета.
Алгоритм HMAC-SHA256, подпись в hex. От IP не зависит, поэтому подходит контейнерам, Cloud Run, AWS Lambda и k8s.
API-TIMESTAMP
Unix-timestamp запроса. Запросы за пределами окна ±300 секунд 1ОПД отвергает: это защита от replay-атак.
Часы сервера с расхождением дают 401. Синхронизируйте время через NTP.
OPD_SECRET_B64
HMAC-секрет в кодировке base64. Менеджер 1ОПД выдаёт его при включении HMAC-защиты на ключе один раз.
Перед вычислением подписи декодируйте секрет обратно в байты (base64.b64decode). Сама подпись при этом остаётся в hex.
Replay-window
±300 секунд от серверного времени. Запрос вне окна получает 401.
Выберите способ защиты: IP whitelist или HMAC
От этого зависит дальнейшая настройка.
✓ IP whitelist: проще
Подходит: bare-metal сервер, VPS со статичным адресом, выделенный хостинг.
Ограничение: при смене сервера список надо обновлять. Для AWS Lambda, Cloud Run и kubernetes с динамическими адресами способ не подходит.
HMAC: гибче
Подходит: контейнеры, serverless, кластеры, динамическая инфраструктура.
Ограничение: кода немного больше, каждый запрос нужно подписывать. Зато адрес отправителя роли не играет.
Подсказка
В сомнениях берите HMAC: он универсален и переживает любые миграции. Для единственного сервера, который не меняется годами, достаточно IP whitelist.
В ЛК 1ОПД выпустите ключ sk_
С выбранным типом защиты.
Зайдите в ЛК 1ОПД → «Интеграция» . Если ключа sk_ ещё нет, попросите менеджера его выпустить.
1
Скопируйте ключ sk_ целиком.
2
Запишите form_id формы согласия.
3
Для IP whitelist: у ключа sk_ нажмите «IP-whitelist», добавьте адрес сервера и подтвердите паролем.
4
Для HMAC: попросите менеджера включить HMAC-защиту на ключе. Он передаст
OPD_SECRET_B64, секрет в кодировке base64, показанный один раз. Важно
HMAC-секрет виден один раз, в момент включения. Положите его в менеджер паролей сразу. При утрате менеджер выпустит новый, и прежние подписи перестанут проходить.
Положите ключи в ENV сервера
Не в код и не в git, только через ENV.
Никогда не записывайте sk_ и OPD_SECRET_B64 прямо в коде, держите их в ENV-переменных:
# В .env / /etc/environment / systemd Unit / docker-compose.yml
OPD_KEY=sk_abc12345678901234567890
# Для HMAC дополнительно:
OPD_SECRET_B64=base64encodedsecretXYZ== - VPS и bare-metal: /etc/environment, ~/.bashrc или systemd Environment= в Unit-файле сервиса.
- Docker: docker-compose.yml → environment либо --env-file при docker run.
- Kubernetes: Secret + envFrom в Deployment.
- AWS Lambda и Cloud Run: переменные окружения функции через консоль провайдера.
- PHP-FPM: php-fpm.conf
env[OPD_KEY]=либо getenv() из системного окружения.
Важно
Никогда не коммитьте .env в git, добавьте файл в .gitignore. Если ключ уже попал в коммит, немедленно отзовите его через менеджера 1ОПД и выпустите новый.
Возьмите готовый код под свой язык
Ниже переключатель языка и опция HMAC.
Выберите язык (PHP, Node.js, Python) и отметьте «Подписывать HMAC», если работаете с этим типом защиты.
PHP · cURL
<?php
$body = json_encode([
"form_id" => 1, // ← form_id из ЛК 1ОПД
"hash_field" => $_POST["email"],
"fields" => [
["field" => "email", "value" => $_POST["email"]],
["field" => "name", "value" => $_POST["name"]],
["field" => "phone", "value" => $_POST["phone"]],
],
]);
$ch = curl_init("https://app.1opd.ru/api/v2/create-agreement");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
// sk_ + IP whitelist в ЛК ИЛИ sk_ + HMAC (переключите вкладку)
"API-KEY: sk_xxxxxxxxxxxxxxxxxxxx", // ← ваш sk_ ключ
"Content-Type: application/json",
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
error_log("1ОПД hash: " . ($data["hash"] ?? "(error)")); 1
Замените
form_id: 1 на свой номер формы из ЛК. 2
Приведите список
fields к полям своей формы. 3
Проверьте, что
OPD_KEY и, при HMAC, OPD_SECRET_B64 корректно читаются из ENV.HMAC: как считается подпись
Алгоритм нужен для отладки и для реализации на другом языке.
Подпись считают от конкатенации timestamp и тела запроса, разделённых переводом строки. Алгоритм HMAC-SHA256, результат в hex. Сам секрет лежит в base64: перед вычислением декодируйте его в байты.
API-SIGN = hex( HMAC-SHA256( ts + "\n" + body_bytes, base64_decode(secret) ) ) -
ts: unix-timestamp в секундах, строкой. Например1731936000. -
body_bytes: точные байты отправляемого JSON. Сериализуйте его один раз и используйте и для подписи, и для отправки: любая разница в пробелах даёт неверную подпись. - Регистр hex значения не имеет, сравнение идёт в нижнем регистре. Base64-подпись бэкенд не принимает.
- Replay-window: ±300 секунд от серверного времени. Синхронизируйте часы через NTP.
- Заголовки в запросе:
API-KEY+API-SIGN+API-TIMESTAMP.
Важно
В Python берите
data=body, а не json=...: requests пересериализует JSON, и подпись не совпадёт. Сериализуйте через json.dumps(..., separators=(",", ":")), без лишних пробелов.Проверьте интеграцию
Логи сервера и раздел «Согласия» в ЛК 1ОПД.
1
Вызовите свой серверный endpoint с обращением в 1ОПД, например через curl или Postman.
2
В логах сервера появится
1ОПД hash: ABC123…. При ответе 202 hash не приходит: согласие принято в очередь, и его идентификатор отдаст GET /spool/status/<idempotency_key>. 3
В ЛК 1ОПД → «Согласия» → фильтр «За последний час» появится запись.
✓ Готово, если
✓ Сервер получил от 1ОПД код 200 с hash либо 202 с idempotency_key.
✓ В ЛК 1ОПД появилась запись.
✓ При HMAC подпись прошла проверку: 401 «invalid signature» нет.
✓ Интеграция работает.
✓ В ЛК 1ОПД появилась запись.
✓ При HMAC подпись прошла проверку: 401 «invalid signature» нет.
✓ Интеграция работает.
Если что-то не работает
Самые частые проблемы и что с ними делать. Решает 95% случаев.
HTTP 401 «Invalid signature» ▾
Почему так
Подпись посчитана неверно либо тело запроса при подписании и при отправке не совпало.
Что делать
1. Сериализуйте JSON один раз: body = json.dumps(...), и используйте эту строку и для подписи, и для отправки.
2. В Python берите data=body, а не json=...: с json=... requests пересериализует тело, и подпись сломается.
3. Разделителем между ts и body служит именно \n (LF), а не CRLF.
4. Результат HMAC кодируйте в hex, а не в base64. В base64 приходит только сам секрет.
HTTP 401 «Timestamp out of range» ▾
Почему так
Часы сервера расходятся с реальным временем больше чем на 5 минут.
Что делать
Синхронизируйте время через NTP: sudo timedatectl set-ntp true (Ubuntu, Debian).
Контейнер Docker наследует время хост-машины, поэтому проверяйте часы хоста.
HTTP 403 «IP not allowed» ▾
Почему так
Текущий адрес сервера отсутствует в whitelist ключа sk_.
Что делать
Выполните на сервере curl ifconfig.me, узнайте текущий внешний адрес и добавьте его в ЛК 1ОПД → ключ → IP-whitelist.
Если у инфраструктуры несколько исходящих адресов (балансир, NAT-пул), внесите все.
Второй путь: перейти на HMAC, он от адреса не зависит.
OPD_KEY undefined или null ▾
Почему так
Сервис не подхватил ENV-переменные.
Что делать
1. Перезапустите сервис после изменения .env.
2. Для systemd добавьте в Unit-файл EnvironmentFile=/path/to/.env либо Environment="OPD_KEY=sk_...", затем systemctl daemon-reload и restart.
3. Для Docker проверьте, что переменная передана через docker-compose environment или --env-file.
4. На PaaS (Vercel, Railway, Render) внесите её в UI Environment Variables.
Connection timeout или refused ▾
Почему так
Хостинг блокирует исходящие HTTPS-соединения.
Что делать
Выполните на сервере curl https://app.1opd.ru/healthz: ответом должен прийти JSON.
При timeout обратитесь к провайдеру и попросите открыть исходящий 443 для app.1opd.ru.
Чаще всего это встречается на дешёвых shared-хостингах.
Увидит ли пользователь ошибку, если 1ОПД ответит 500 или 503? ▾
Почему так
Зависит от того, как написана интеграция.
Что делать
Рекомендация: не блокируйте основную бизнес-логику. Оберните вызов 1ОПД в try/catch либо отправляйте его fire-and-forget, чтобы обработка формы шла как обычно.
Учтите и то, что 503 приходит редко: при недоступном бэкенде спул-шлюз отвечает 202 и доставляет согласие сам. 503 означает отказ и бэкенда, и очереди.
Для критичных потоков заводите локальную очередь (Redis, SQS, RabbitMQ) и повторяйте запись асинхронно: тогда согласие не потеряется и при одновременной недоступности обеих сторон.
Мульти-tenant SaaS: как разделить ключи между клиентами? ▾
Почему так
Архитектурный вопрос: один общий ключ или ключ на клиента.
Что делать
Когда у каждого клиента отдельный тенант в 1ОПД со своим набором форм, у каждого свой ключ sk_. Храните в БД поля tenant.opd_api_key и tenant.opd_hmac_secret_b64.
Когда все клиенты пишут в один тенант 1ОПД (оператором персональных данных выступаете вы, а клиенты выступают субъектами), достаточно одного ключа sk_ и разных form_id через forms_scope.
Уже клиент 1ОПД
Откройте ЛК → «Интеграция»: персональные snippet'ы + готовый HTML-чекбокс с авто-ссылками на согласие и политику + кнопка «IP-whitelist» для каждого ключа.
Открыть ЛК →Ещё не клиент
Запросите тестовый доступ: выдаём ключ под ваш домен и помогаем подключиться.
Связаться →API Reference
Все endpoints, коды ошибок, форматы HMAC/Origin/IP. Таблица «какую защиту выбрать».
Открыть →Что вернёт API при отправке согласия
Успехом считаются и 200, и 202. Проверка «строго 200» отметит ошибкой согласие, которое 1ОПД принял и доставит.
- 200
- Согласие записаноВ ответе приходит hash согласия: 32 hex-символа. По нему читают запись и отзывают её.
- 202
- Принято в очередь, это тоже успехТакой ответ приходит, когда бэкенд 1ОПД временно недоступен: согласие принято, и 1ОПД запишет его, как только бэкенд ответит. Hash в теле 202 не приходит: пока запись не дошла до базы, брать его неоткуда. Повторы доставки идут ступенями от 10 минут до 48 часов, тело запроса хранится 72 часа.
- hash
- Посчитать на стороне отправителя нельзяhash идентифицирует согласие, а не субъекта: MD5("<form_id> <MD5(hash_field)> <версия согласия>"). Версия считает, сколько раз этот субъект уже давал согласие в этой форме, то есть состояние на стороне 1ОПД. Если после 202 hash всё-таки нужен, запросите его по идентификатору из ответа: GET /spool/status/<idempotency_key>, после доставки там появится delivered_hash.
- ⛔
- Не переотправляйте запрос, чтобы «получить 200»Повтор с тем же телом в пределах 5 минут 1ОПД подавляет и возвращает hash оригинала. За этим окном повтор помечает прежнюю запись неактуальной и заводит новую версию, а оригинал всё равно доедет из очереди: в журнале окажутся две версии одного согласия. Отдельно про обрыв связи: если ответа не было вовсе, дошёл ли запрос, неизвестно, и повтор может дать вторую версию, зато потери не будет. Ради одного лишь hash повторять не нужно: после доставки его отдаёт GET /spool/status/<idempotency_key>.
- 503
- Повторите отправкуЕдинственный случай, когда ретрай нужен: недоступны и бэкенд, и очередь, доставку 1ОПД не гарантирует. Тело: {"status": "unavailable"}. Не путайте с 202: там доставка гарантирована, здесь нет.
- 4xx
- Ошибка в самом запросе401: ключ или подпись. 403: Origin, IP или форма вне разрешённых. 400: не хватает обязательного поля. 429: превышен лимит частоты. Повтор с тем же телом не поможет, нужно чинить запрос. Полный разбор кодов приведён в справочнике API.
Поля субъекта персональных данных
В массиве fields передавайте любые из 28 полей ниже, имя поля стоит в столбце field. Обязательное одно: email, он же идентификатор субъекта (hash_field). Остальные 27 опциональны, незаполненное поле не передавайте. Все значения 1ОПД шифрует на своей стороне (AES-256-GCM). Актуальный список полей конкретной формы отдаёт POST /api/v2/get-fields.
| field | Название | Примечание |
|---|---|---|
email | Электронная почта | обязательное · идентификатор (hash_field) |
first_name | Имя | опциональное |
last_name | Фамилия | опциональное |
sur_name | Отчество | опциональное |
birth_date | Дата рождения | опциональное |
phone_number | Номер телефона | опциональное |
birth_place | Место рождения | опциональное |
registration_address | Адрес регистрации | опциональное |
delivery_address | Адрес доставки | опциональное |
passport_details | Паспортные данные | опциональное |
inn | ИНН | опциональное |
snils | СНИЛС | опциональное |
bank_details | Банковские реквизиты | опциональное |
account_vk | Аккаунт VK | опциональное |
account_telegram | Аккаунт Telegram | опциональное |
account_instagram | Аккаунт Instagram | опциональное |
account_facebook | Аккаунт Facebook | опциональное |
account_viber | Аккаунт Viber | опциональное |
account_ok | Аккаунт OK | опциональное |
account_whatsapp | Аккаунт WhatsApp | опциональное |
job_title | Должность | опциональное |
organization_name | Название организации | опциональное |
field_of_activity | Сфера деятельности | опциональное |
city | Город | опциональное |
mattermost_account | Аккаунт Mattermost | опциональное |
slack_account | Аккаунт Slack | опциональное |
ms_teams_account | Аккаунт MS Teams | опциональное |
sex | Пол | значения male / female · в карточках: «мужчина» / «женщина» |
Набор одинаков для всех способов интеграции (Tilda, WordPress, Bitrix, браузерный JS, server-side API). Каждое значение приходит строкой длиной до 5000 символов.