Проверка личности,
понятная разработчикам.

От фотографии до результата

Интеграция состоит из трёх действий. Пользовательский camera flow, задания и переход с компьютера по QR полностью обслуживаются Sumio.

1. 1
   Создайте проверку

   Передайте эталонное фото и, при необходимости, URL webhook.

2. 2
   Сохраните и передайте ссылку

   API возвращает verification_url только при создании. Сама ссылка работает на протяжении всего camera flow до завершения или истечения срока.

3. 3
   Получите итог

   Читайте статус по UUID или обработайте HMAC-подписанное событие.

curl --fail-with-body https://api.sumio.cc/v1/verifications \
  -H "Authorization: Bearer $SUMIO_API_KEY" \
  -F "reference_image=@./person.jpg" \
  -F 'metadata={"customer_id":"customer-4821"}'

Ключ остаётся на вашем сервере

Merchant endpoints требуют API-ключ. Передавайте его как Bearer token; заголовок X-API-Key также поддерживается. Никогда не помещайте ключ в браузерный код, URL, логи или репозиторий.

Создать проверку

Фото принимается файлом через multipart или строкой Base64 через JSON. Поддерживаются JPEG, PNG и WebP; минимальный размер — 320×320 пикселей. Фактический лимит тела задаётся конфигурацией сервера.

REFERENCE_BASE64="$(base64 -w0 ./person.jpg)"

curl --fail-with-body https://api.sumio.cc/v1/verifications \
  -H "Authorization: Bearer $SUMIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg image "$REFERENCE_BASE64" \
    --arg hook "https://merchant.example/kyc/events" \
    '{
      reference_image_base64: $image,
      webhook_url: $hook,
      metadata: {customer_id: "customer-4821"}
    }')"

curl --fail-with-body https://api.sumio.cc/v1/verifications \
  -H "Authorization: Bearer $SUMIO_API_KEY" \
  -F "reference_image=@./person.jpg" \
  -F "webhook_url=https://merchant.example/kyc/events" \
  -F 'metadata={"customer_id":"customer-4821"}'

Поля запроса

Ответ 201 Created

{
  "id": "2b67f8ec-9ba7-4eef-ad17-414533b53083",
  "status": "pending",
  "verification_url": "https://id.sumio.cc/verify/REDACTED_TOKEN",
  "created_at": "2026-09-21T12:00:00Z",
  "updated_at": "2026-09-21T12:00:00Z",
  "expires_at": "2026-09-21T12:15:00Z",
  "webhook_configured": true,
  "metadata": {"customer_id": "customer-4821"},
  "result": null
}

Получить результат

Используйте UUID из ответа создания. Для обычной интеграции предпочтителен webhook, а GET — для отображения состояния и сверки.

curl --fail-with-body \
  "https://api.sumio.cc/v1/verifications/$VERIFICATION_ID" \
  -H "Authorization: Bearer $SUMIO_API_KEY"

Если polling необходим, начинайте с интервала 2 секунды и увеличьте его до 5–15 секунд. Остановитесь после terminal status или expires_at.

Отмена и безвозвратное удаление

# Отмена
curl --fail-with-body -X POST \
  "https://api.sumio.cc/v1/verifications/$VERIFICATION_ID/cancel" \
  -H "Authorization: Bearer $SUMIO_API_KEY"

# Безвозвратное удаление данных
curl --fail-with-body -X DELETE \
  "https://api.sumio.cc/v1/verifications/$VERIFICATION_ID" \
  -H "Authorization: Bearer $SUMIO_API_KEY"

Предсказуемая state machine

Подписанные события с повторной доставкой

Webhook доставляется как минимум один раз. Отвечайте любым 2xx быстро, выполняйте тяжёлую работу асинхронно и дедуплицируйте по X-Sumio-Event-Id. Redirect не выполняется.

import hashlib
import hmac
import time

def verify_sumio(raw_body: bytes, timestamp: str,
                 signature: str, secret: str) -> bool:
    try:
        sent_at = int(timestamp)
    except ValueError:
        return False

    if abs(int(time.time()) - sent_at) > 300:
        return False

    expected = "v1=" + hmac.new(
        secret.encode(),
        timestamp.encode("ascii") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Стабильный формат ошибок

{
  "detail": {
    "code": "invalid_state",
    "message": "Operation is not available while status is verified"
  }
}

Файл не содержит реальных ключей, фотографий или URL webhook. Postman environment с секретами не экспортируйте.

Операторский интерфейс

На panel.sumio.cc оператор может просматривать существующие проверки и их evidence, контролировать webhook-доставку и управлять API-ключами. Новые проверки создаются только через merchant API.

Fail-closed — часть API-контракта

Sumio не превращает один similarity score в окончательное решение. В текущем pilot автоматические подтверждение и отказ отключены: модельные итоги становятся manual_review. Автоматические решения можно включать только после калибровки FAR/FRR и APCER/BPCER на репрезентативных данных и независимого тестирования presentation attacks.

Сервис не заменяет DPIA, lawful basis, privacy notice, retention policy, manual appeal и требования вашей юрисдикции.