Загружаем 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 (если у сервера static IP) ИЛИ 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-переменных вашего сервера, посетители его не видят.
Длина 30+ символов, начинается с sk_. Никогда не должен попасть в client-side bundle или в HTML.
IP whitelist
Список IP-адресов, с которых 1ОПД принимает запросы с этим ключом.
Простой и быстрый способ защиты. Минус: при смене IP (новый VPS, миграция) нужно обновлять whitelist.
HMAC-подпись
Криптографическая подпись каждого запроса. 1ОПД проверяет: «этот payload был подписан тем, у кого секрет».
Использует HMAC-SHA256. Не зависит от IP — подходит для контейнеров, Cloud Run, AWS Lambda, k8s где IP может меняться.
API-TIMESTAMP
Unix-timestamp запроса. 1ОПД отвергает запросы старше 5 минут — защита от replay-атак.
Если у сервера часы расходятся с реальностью — будет 401. Синхронизируйте через NTP.
OPD_SECRET_B64
HMAC-секрет в base64-кодировке. Выдаётся в ЛК 1ОПД при включении HMAC-защиты на ключе.
Перед использованием декодируется обратно в bytes (base64.b64decode).
Replay-window
±300 секунд от серверного времени. Запросы вне окна отбрасываются с 401.
Выберите способ защиты — IP whitelist или HMAC
От этого зависит дальнейшая настройка.
✓ IP whitelist — проще
Подходит: bare-metal сервер, VPS со статичным IP, dedicated хостинг.
Минус: при смене сервера нужно обновлять whitelist. Не подходит для AWS Lambda / Cloud Run / kubernetes где IP'ы динамические.
HMAC — гибче
Подходит: контейнеры, serverless, кластеры, динамическая инфраструктура.
Минус: чуть больше кода (подписание каждого запроса). Зато не зависит от IP.
Подсказка
В сомнениях — выбирайте HMAC: универсальный, переживает любые миграции. Если сервер один и не двигается годами — IP whitelist работает прекрасно.
В ЛК 1ОПД выпустите sk_ ключ
С нужным типом защиты.
Зайдите в ЛК 1ОПД → «Интеграция» . Если sk_ ключа ещё нет — попросите менеджера выпустить.
1
Скопируйте sk_ ключ целиком.
2
Запишите form_id формы согласия.
3
Для IP whitelist: у sk_ ключа кнопка «IP-whitelist» → добавьте IP сервера → подтвердите паролем.
4
Для HMAC: попросите менеджера включить HMAC-защиту на ключе. Он выпустит и передаст вам
OPD_SECRET_B64 (base64 секрет, показывается один раз — храните в надёжном месте). Важно
HMAC-секрет показывается один раз в момент включения. Запишите/положите в password manager сразу. Если потеряли — менеджер выпустит новый (старые подписи перестанут работать).
Положите ключи в 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.
Важно
Никогда не коммитьте .env в git. Добавьте файл в .gitignore. Если случайно закоммитили — немедленно отзовите ключ через менеджера 1ОПД и выпустите новый.
Возьмите готовый код под ваш язык
Ниже — playground с переключателем. Выбирайте язык + опционально 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 (и OPD_SECRET_B64 если HMAC) корректно подгружены из ENV.HMAC — как считается
Знать алгоритм пригодится для debug'а и если пишете на другом языке.
Подпись считается над конкатенацией timestamp и тела запроса, разделённых переводом строки. Алгоритм — HMAC-SHA256, результат в base64. Секрет хранится в base64, перед вычислением декодируется в bytes.
API-SIGN = base64( HMAC-SHA256( ts + "\n" + body_bytes, base64_decode(secret) ) ) -
ts— unix-timestamp в секундах (строка). Например1731936000. -
body_bytes— точные байты JSON, которые вы отправляете. Сериализуйте один раз и используйте и для подписи, и для отправки. Иначе любая разница в пробелах = неправильная подпись. - 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… (если не ошибка). 3
В ЛК 1ОПД → «Согласия» → фильтр «За последний час» — должна быть запись.
✓ Готово, если
✓ Сервер вернул hash от 1ОПД (200 OK).
✓ В ЛК 1ОПД появилась запись.
✓ Если HMAC: подпись прошла валидацию (нет 401 «invalid signature»).
✓ Интеграция работает!
✓ В ЛК 1ОПД появилась запись.
✓ Если HMAC: подпись прошла валидацию (нет 401 «invalid signature»).
✓ Интеграция работает!
Если что-то не работает
Самые частые проблемы и что с ними делать. Решает 95% случаев.
HTTP 401 — «Invalid signature» ▾
Почему так
HMAC-подпись посчитана неправильно или body отличается между подписью и реальной отправкой.
Что делать
1. Сериализуйте JSON один раз: body = json.dumps(...), используйте этот string и для подписи, и для отправки.
2. В Python: data=body вместо json=.... json=... requests пересериализует и подпись поломается.
3. Разделитель между ts и body — именно \n (LF), не CRLF.
4. base64-кодирование результата HMAC, не hex.
HTTP 401 — «Timestamp out of range» ▾
Почему так
Часы сервера расходятся с реальностью больше чем на 5 минут.
Что делать
Синхронизируйте время через NTP: sudo timedatectl set-ntp true (Ubuntu/Debian).
В Docker контейнере время наследуется от хост-машины — проверьте часы хоста.
HTTP 403 — «IP not allowed» ▾
Почему так
Текущий IP сервера не в whitelist'е sk_ ключа.
Что делать
На сервере: curl ifconfig.me — узнаете текущий внешний IP. Добавьте в ЛК 1ОПД → ключ → IP-whitelist.
Если у инфраструктуры несколько исходящих IP (load balancer, NAT-пул) — добавьте все.
Альтернатива: переходите на HMAC — не зависит от IP.
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 (или async fire-and-forget), и если 1ОПД временно недоступен — продолжать обработку формы как обычно.
Альтернатива: писать в локальную очередь (Redis/SQS/RabbitMQ) и асинхронно ретраить запись в 1ОПД. Так согласие не теряется даже если оба сервера временно недоступны.
В мульти-tenant SaaS — как разделить ключи между клиентами? ▾
Почему так
Архитектурный вопрос: один ключ на всех или ключ на клиента.
Что делать
Если у каждого вашего клиента — отдельный tenant в 1ОПД (свой набор форм), то у каждого свой sk_ ключ. Храните в БД: tenant.opd_api_key, tenant.opd_hmac_secret_b64.
Если все ваши клиенты пишут в одного 1ОПД-tenant'а (вы единый оператор ПД, клиенты — конечные пользователи) — один глобальный sk_ + разные form_id через forms_scope.
Уже клиент 1ОПД
Откройте ЛК → «Интеграция»: персональные snippet'ы + готовый HTML-чекбокс с авто-ссылками на согласие и политику + кнопка «IP-whitelist» для каждого ключа.
Открыть ЛК →Ещё не клиент
Запросите тестовый доступ — выдаём ключ под ваш домен и помогаем подключиться.
Связаться →API Reference
Все endpoints, коды ошибок, форматы HMAC/Origin/IP. Таблица «какую защиту выбрать».
Открыть →