Перейти к содержимому
Справочник API Получить API-ключи

Интеграция · Глава 8

Direct API

Отправляйте изображения со своего сервера и получайте результат проверки в том же ответе. Для бизнеса, у которого уже есть свой интерфейс съёмки и нужны только сами проверки.

5 мин чтения

Когда использовать

Большинству интеграций подходит процесс проверки: hosted-страница, kyc.js или Flutter SDK делают снимки, проводят полную проверку присутствия, сохраняют результат, отправляют вебхуки и выпускают справку. Direct API нужен, только если вы уже снимаете изображения сами и вам нужны отдельные проверки.

Процесс проверки Direct API
Кто делает снимки Страница или SDK GOXOST KYC Ваше приложение или сайт
Проверка присутствия Полная, во время шага селфи Упрощённая, по одному изображению
Заявитель, проверка, история Да Нет — ничего не создаётся
Хранение данных По вашим настройкам хранения Ничего не хранится; данные есть только в ответе
Вебхуки, очередь ручной проверки, справка Да Нет
Проверка по санкционным спискам Опция сценария Отдельный вызов: POST /aml/screen
Важно

Вызовы Direct API используют ваш секретный ключ. Делайте их только с сервера — никогда из браузера или мобильного приложения. Приложение отправляет изображения на ваш сервер, а сервер вызывает Direct API.

Базовый URL и аутентификация

Запросы Direct API идут напрямую в сервис проверок, а не в /api/v1. Его адрес берите из поля core_url в GET /usage и храните в конфигурации:

curl https://kyc.goxost.net/api/v1/usage -H "Authorization: Bearer sk_test_…"
{ "period": "2026-11", "plan": "free", "limit": 100,
  "live": { "verifications": 124, "aml_checks": 124, "direct_checks": 40 },
  "sandbox": { "verifications": 51, "aml_checks": 12, "direct_checks": 7 },
  "core_url": "https://kyc-core.9k.uz/v1" }

Аутентификация — тот же заголовок: Authorization: Bearer sk_test_… или sk_live_…. Запросы отправляются как multipart/form-data.

Эндпоинты

Эндпоинт Поля Возвращает
POST {core_url}/checks/document front (файл), back (файл, необязательно), country (ISO alpha-3, необязательно), type (id_card, passport, residence_permit, ru_internal_passport, visa; необязательно), age_only (bool, необязательно), min_age (целое, необязательно) document (type, country, data) или null, и checks
POST {core_url}/checks/face-match image_a, image_b (файлы) score, status, labels
POST {core_url}/checks/liveness image (файл) score, status, labels

Файлы: JPEG, PNG или WebP (определяется по содержимому; HEIC не принимается), до 15 МБ каждый, весь запрос — до 32 МБ.

Порядок вызовов

Типичная проверка человека с собственным интерфейсом:

  1. Приложение снимает документ (лицевую сторону, а для ID-карты и оборотную) и селфи и загружает их на ваш сервер.
  2. Сервер вызывает POST /checks/document с front и back. Прочитайте document.data (имя, номер, даты) и статусы в checks.
  3. Сервер вызывает POST /checks/face-match: фото из документа как image_a, селфи как image_b.
  4. При необходимости — POST /checks/liveness с селфи для упрощённой проверки присутствия.
  5. При необходимости проверьте имя через POST /aml/screen.
  6. Сервер сводит статусы в собственное решение и сохраняет то, что ему нужно, — GOXOST KYC ничего не хранит.
curl https://kyc-core.9k.uz/v1/checks/document \
  -H "Authorization: Bearer sk_test_…" \
  -F front=@passport.jpg \
  -F type=passport

curl https://kyc-core.9k.uz/v1/checks/face-match \
  -H "Authorization: Bearer sk_test_…" \
  -F image_a=@passport.jpg \
  -F image_b=@selfie.jpg
$coreUrl = getenv('KYC_CORE_URL'); // core_url from GET /usage
$client = new GuzzleHttp\Client();
$auth = ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')];

$document = json_decode((string) $client->post("$coreUrl/checks/document", [
    'headers' => $auth,
    'multipart' => [
        ['name' => 'front', 'contents' => fopen('passport.jpg', 'r')],
        ['name' => 'type', 'contents' => 'passport'],
    ],
])->getBody(), true);

$face = json_decode((string) $client->post("$coreUrl/checks/face-match", [
    'headers' => $auth,
    'multipart' => [
        ['name' => 'image_a', 'contents' => fopen('passport.jpg', 'r')],
        ['name' => 'image_b', 'contents' => fopen('selfie.jpg', 'r')],
    ],
])->getBody(), true);
// Node.js 20+
import { openAsBlob } from 'node:fs';

const coreUrl = process.env.KYC_CORE_URL; // core_url from GET /usage
const auth = { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` };

const docForm = new FormData();
docForm.append('front', await openAsBlob('passport.jpg'), 'passport.jpg');
docForm.append('type', 'passport');
const document = await (await fetch(`${coreUrl}/checks/document`, { method: 'POST', headers: auth, body: docForm })).json();

const faceForm = new FormData();
faceForm.append('image_a', await openAsBlob('passport.jpg'), 'passport.jpg');
faceForm.append('image_b', await openAsBlob('selfie.jpg'), 'selfie.jpg');
const face = await (await fetch(`${coreUrl}/checks/face-match`, { method: 'POST', headers: auth, body: faceForm })).json();
import os, requests

core_url = os.environ["KYC_CORE_URL"]  # core_url from GET /usage
auth = {"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"}

with open("passport.jpg", "rb") as front:
    document = requests.post(f"{core_url}/checks/document", headers=auth,
                             files={"front": front}, data={"type": "passport"}).json()

with open("passport.jpg", "rb") as a, open("selfie.jpg", "rb") as b:
    face = requests.post(f"{core_url}/checks/face-match", headers=auth,
                         files={"image_a": a, "image_b": b}).json()

Ответ /checks/document:

{
  "document": {
    "type": "passport",
    "country": "UTO",
    "data": {
      "first_name": "ANNA MARIA",
      "last_name": "ERIKSSON",
      "full_name": "ERIKSSON ANNA MARIA",
      "birth_date": "1992-08-12",
      "number": "L898902C3",
      "expiry_date": "2032-04-15",
      "age": 34,
      "is_expired": false,
      "fields": { "…": "…" },
      "mrz": { "…": "…" }
    }
  },
  "checks": [
    { "name": "document", "status": "pass", "score": 1.0, "labels": [], "ms": 410 }
  ]
}

Ответ /checks/face-match и /checks/liveness:

{ "score": 0.93, "status": "pass", "labels": [] }

У document.data та же полная схема, что и в GET /verifications/{id}. status — pass, warn или fail; labels — коды причин из главы Ошибки и коды, например FACE_MATCH_UNCERTAIN, FACE_MISMATCH, FACE_NOT_FOUND, LIVENESS_UNCERTAIN, DOC_EXPIRED.

Правила и лимиты

  • Только упрощённая проверка присутствия. Полная проверка присутствия требует шага селфи в hosted-сценарии или SDK. /checks/liveness работает по одному изображению: сомнительный результат даёт warn + LIVENESS_UNCERTAIN, но сам по себе никогда не даёт жёсткий fail. Если нужна полная проверка присутствия, используйте процесс проверки.
  • Параметры документа. С country/type принимаются только они (остальные → DOC_NOT_SUPPORTED). Для ID-карты передайте type=id_card вместе с back; если переданы обе стороны, они проверяются на согласованность (DOC_DATA_MISMATCH — данные расходятся, DOC_FACE_UNBOUND — не удаётся подтвердить, что стороны относятся к одному документу).
  • Только возраст. age_only=true возвращает document.data = null и добавляет проверку age с details.age_over. min_age по умолчанию 18, допустимо 18–30.
  • Подлинность документа. Если проверка document пройдена, изображения дополнительно проходят проверку подлинности документа. Если она вызывает сомнения, приходит warn с одним из кодов DOC_SCREEN_RECAPTURE, DOC_PRINTED_COPY, DOC_PHOTO_TAMPERED, DOC_TEMPLATE_MISMATCH.
  • Размер изображения. Изображения документа — до 52 Мп, изображение селфи для /checks/liveness — до 13 Мп, любая сторона — до 12 000 px, длинная сторона — не больше 10× короткой (422 image_too_large).
  • Ограничения частоты. 120 запросов в минуту с одного IP и 60 в минуту на окружение ключа (429 rate_limited).
  • Учёт. Каждый успешный (200) вызов считается одной единицей direct_checks, отдельно от проверок. В боевом режиме после исчерпания месячного лимита → 429 plan_limit_reached. Ошибки не учитываются.
  • Тестовый режим (sk_test_…): реальных проверок нет; каждый вызов возвращает тестовый pass (балл 0.99) и синтетический образец документа «ERIKSSON ANNA MARIA». Без ограничений, но учитывается в GET /usage.
  • Idempotency-Key не используется — у вызовов нет состояния.

Ошибки

Ошибки приходят в обёртке { "error": { "code": "…", "message": "…" } }.

HTTP code Что делать
400 validation_failed Поле отсутствует или неверно (например, min_age вне диапазона)
400 invalid_file Файл не является изображением JPEG, PNG или WebP
401 unauthenticated Ключ отсутствует или недействителен
403 forbidden Аккаунт заблокирован
413 file_too_large Запрос больше 32 МБ
422 image_too_large Разрешение или пропорции изображения превышают лимиты — уменьшите перед отправкой
429 rate_limited Слишком много запросов — снизьте частоту и повторите позже
429 plan_limit_reached Достигнут месячный лимит боевого режима
503 auth_unavailable Ключ сейчас не удаётся проверить — повторите с нарастающей паузой
503 core_unavailable Сервис проверок временно недоступен — повторите с нарастающей паузой

Отозванный ключ или заблокированный аккаунт перестаёт работать примерно в течение минуты (для боевых ключей — 10 секунд).