API Reference — 1ОПД v2

 POST /api/v2/create-agreement HTTP/1.1
Host: app.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: app.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

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

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

# Если бэкенд временно недоступен, ответ будет 202 Accepted —
# согласие принято в очередь и запишется автоматически при восстановлении:
# HTTP/1.1 202 Accepted
# {
#  "status": "queued",
#  "idempotency_key": "d4e5f6a7b8c9d0e1...",
#  "message": "Accepted for processing. Will be delivered when backend recovers.",
#  "check_url": "/spool/status/d4e5f6a7b8c9d0e1...",
#  "original_path": "/api/v2/create-agreement"
# }
#
# Это НЕ ошибка — считайте 202 успехом и не ретрайте: повтор с тем же телом
# дедуплицируется по idempotency_key, дубля согласия не будет.
#
# ⚠ В ответе 202 НЕТ поля hash — и посчитать его у себя нельзя.
# hash — это идентификатор СОГЛАСИЯ, а не субъекта:
#   hash = MD5("<form_id> <MD5(hash_field)> <версия согласия>")
# Версия — сколько раз этот субъект уже соглашался в этой форме, то есть
# состояние на нашей стороне. Поэтому дождаться его придётся от нас.
#
# Как получить hash после 202: по идентификатору из ответа
#   GET /spool/status/<idempotency_key>
# После доставки там появится поле delivered_hash.
#
# ⛔ НЕ отправляйте тот же запрос повторно, чтобы «получить hash в 200».
# Повтор не идемпотентен на уровне согласия: он пометит прежнюю запись
# неактуальной и создаст НОВУЮ версию согласия, а оригинал всё равно доедет
# из очереди. Получите две версии одного согласия вместо одной.
#
# Сколько мы держим очередь: повторы идут ступенями от момента приёма —
# 10 мин, 30 мин, 1 ч, 3 ч, 6 ч, 12 ч, сутки, 36 ч, 48 ч. Плюс запись
# разбирается сразу, как только бэкенд снова отвечает, не дожидаясь ступени.
# Само тело хранится 72 часа. Если за это время доставить не удалось —
# мы это видим по своим счётчикам, но вам уведомление не приходит.
#
# check_url — если захотите убедиться, что отложенное согласие дошло:
# GET https://app.1opd.ru/spool/status/<idempotency_key>
# Опрашивать не обязательно — доставка на нас; это на случай разбирательства.
#
# Возможные status:
#   waiting_retry      — ждёт следующей попытки, время в next_attempt_at
#   replaying          — отправляется прямо сейчас
#   delivered          — записано, время в delivered_at
#   failed_permanent   — бэкенд ответил 4xx: дело в самом запросе (ключ, форма,
#                        обязательное поле). Причина — в last_error, повтор
#                        того же тела не поможет
#   failed_max_attempts — девять попыток за 48 часов не прошли
#
# 404 — записи нет: либо ключа не существовало, либо прошло больше 72 часов
# и она вышла из хранения. Тело и заголовки запроса эндпоинт не отдаёт. 

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

{ "form_id": 1 } 

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

# Ответ — массив полей, объявленных у этой формы (без обёртки):
[
 { "field_name": "email", "field_title": "Электронная почта" },
 { "field_name": "first_name", "field_title": "Имя" },
 { "field_name": "phone_number", "field_title": "Номер телефона" }
]

# field_name — то, что вы передаёте в fields[].field при create-agreement.
# Полный перечень возможных полей — в таблице ниже на этой странице. 

 POST /api/v2/get-user HTTP/1.1
Host: app.1opd.ru
API-KEY: sk_xxxxxxxxxxxxxxxxxxxx
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 HTTP/1.1
Host: app.1opd.ru
API-KEY: sk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "hash": "0622845210A8C5136424513435FA90EB" }

# Ответ:
{ "status": 200 }

# Если субъект уже был удалён ранее — 200 с пояснением:
# { "status": "По данному hash был пользователь, но он был удалён. Данные недоступны." }
# Если hash не найден — 404: { "reason": "Entity not found" } 

 # Псевдокод (Python):
ts = str(int(time.time())) # unix timestamp, секунды
body_bytes = json.dumps(payload).encode() # тело как байты — ровно то, что отправляете
secret = base64.b64decode(secret_b64) # секрет из ЛК — base64 → bytes

# Подпись — HEX (не base64!):
sign = hmac.new(
 secret, ts.encode() + b"\n" + body_bytes, hashlib.sha256
).hexdigest()

# Заголовки:
# API-KEY: sk_xxx
# API-SIGN: <hex-строка, 64 символа>
# API-TIMESTAMP: <ts> 

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

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