API Reference — 1ОПД v2

База

• Базовый URL: https://v2.1opd.ru/api/v2
• Все запросы — POST с JSON-телом (кроме get-user, см. ниже).
• Аутентификация — заголовок API-KEY.
• Для server-side ключей — опционально API-SIGN и API-TIMESTAMP (HMAC).
• Ответ — JSON с полем ok: true/false. В случае ошибки добавляется reason (на русском).

Создать ключ для своего сайта → ваш ЛК 1ОПД.

Какую защиту выбрать

Самая частая ошибка интеграторов — выпустить ключ без защиты или выбрать защиту, неподходящую под клиента (например, IP whitelist для Tilda — у посетителей разные IP). Сверьтесь с таблицей:

Аутентификация

Все запросы должны содержать заголовок API-KEY с вашим ключом из ЛК 1ОПД.

POST /api/v2/create-agreement

Основной endpoint: создаёт запись согласия. Доступен для pk_ и sk_ (требует право create).

Body

• form_id (number) — ID формы. Опционально для single-form ключей, обязательно при forms_scope.
• hash_field (string, required) — значение поля-идентификатора (обычно email или phone).
• fields (array of {field, value}, required) — все поля формы.

POST /api/v2/create-agreement HTTP/1.1
Host: v2.1opd.ru
API-KEY: pk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "form_id": 1,
  "hash_field": "user@example.com",
  "fields": [
    { "field": "email", "value": "user@example.com" },
    { "field": "name",  "value": "Иван Иванов"    },
    { "field": "phone", "value": "+79991234567"    }
  ]
}

POST /api/v2/create-agreement HTTP/1.1
Host: v2.1opd.ru
API-KEY: pk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

# Один ключ с forms_scope=[1,2,5] обслуживает все формы сайта.
# form_id в body выбирает конкретную форму:
{
  "form_id": 2,
  "hash_field": "user@example.com",
  "fields": [
    { "field": "email", "value": "user@example.com" }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "hash": "a1b2c3d4e5f6...",
  "created_at": "2026-05-16T10:23:11Z"
}

POST /api/v2/get-fields

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

POST /api/v2/get-fields HTTP/1.1
Host: v2.1opd.ru
API-KEY: pk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "form_id": 1 }

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "form_id": 1,
  "fields": [
    { "field": "email", "required": true,  "hash": true  },
    { "field": "name",  "required": true,  "hash": false },
    { "field": "phone", "required": false, "hash": false }
  ]
}

POST /api/v2/get-user

Получить запись по hash. Требует право read. Параметры — в query-string (совместимость с v1).

POST /api/v2/get-user?API-KEY=sk_xxx&hash=a1b2c3...

# Ответ:
{
  "ok": true,
  "hash": "a1b2c3...",
  "form_id": 1,
  "fields": [
    { "field": "email", "value": "user@example.com" },
    { "field": "name",  "value": "Иван Иванов"    }
  ],
  "created_at": "2026-05-16T10:23:11Z"
}

POST /api/v2/delete-user

Удалить запись по hash. Требует право delete. Для обработки запросов субъектов ПДн на удаление (статья 21 ФЗ-152).

POST /api/v2/delete-user HTTP/1.1
Host: v2.1opd.ru
API-KEY: sk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "hash": "a1b2c3..." }

# Ответ:
{ "ok": true, "deleted": true }

HMAC-подпись

Опциональный механизм для sk_. Защищает от компрометации ключа и replay-атак.

# Псевдокод:
ts = str(int(time.time()))                       # unix timestamp, секунды
body_bytes = json.dumps(payload).encode()         # тело как байты
secret = base64.b64decode(secret_b64)             # секрет из ЛК — base64 → bytes
sign = base64.b64encode(
    hmac.new(secret, ts.encode() + b"\n" + body_bytes, "sha256").digest()
).decode()

# Заголовки:
# API-KEY:       sk_xxx
# API-SIGN:      <base64 от HMAC>
# API-TIMESTAMP: <ts>

• Алгоритм: HMAC-SHA256.
• Сообщение: ts + "\n" + body_bytes.
• Ключ HMAC: base64_decode(secret_b64) — секрет хранится в base64, в HMAC подаётся как bytes.
• Кодирование подписи: base64.
• Заголовки: API-SIGN, API-TIMESTAMP.
• Replay-window: ±300 секунд.

Origin whitelist (allowed_origins)

Для pk_. Если массив allowed_origins не пуст — проверяется заголовок Origin(или host из Referer).

• Формат: только host, без https:// и порта. Например: example.com, www.example.com.
• Wildcard на первый сегмент: *.example.com подходит для shop.example.com, но не для самого example.com.
• Запрос без Origin/Referer (curl, Postman без заголовка) отклоняется с 403.

IP whitelist

Для sk_. Список IPv4/IPv6 адресов или CIDR-сетей, с которых разрешён вызов.

• Узнать внешний IP сервера: curl ifconfig.me (исходящий, не входящий).
• Поддерживаются CIDR: 10.0.0.0/24, 2001:db8::/32.
• Если сервер за CDN/прокси — добавляйте IP исходящих запросов от вашего бэкенда (не IP CDN).
• Не подходит для серверов с динамическим IP — используйте HMAC.

forms_scope — multi-form ключи

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

// Ключ pk_abc с forms_scope: [1, 2, 5]
// Запрос с form_id=1 — OK
// Запрос с form_id=2 — OK
// Запрос с form_id=3 — 403 "Форма не разрешена ключом"

Если forms_scope пуст — ключ single-form: form_id в body не обязателен (берётся из метаданных ключа). Если задан — form_id в body обязателен.

Коды ошибок и reason-строки

В случае ошибки ответ имеет вид:

{ "ok": false, "reason": "Неверный API-ключ" }