Когда использовать
Большинству интеграций подходит процесс проверки: 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 МБ.
Порядок вызовов
Типичная проверка человека с собственным интерфейсом:
- Приложение снимает документ (лицевую сторону, а для ID-карты и оборотную) и селфи и загружает их на ваш сервер.
- Сервер вызывает
POST /checks/documentсfrontиback. Прочитайтеdocument.data(имя, номер, даты) и статусы вchecks. - Сервер вызывает
POST /checks/face-match: фото из документа какimage_a, селфи какimage_b. - При необходимости —
POST /checks/livenessс селфи для упрощённой проверки присутствия. - При необходимости проверьте имя через
POST /aml/screen. - Сервер сводит статусы в собственное решение и сохраняет то, что ему нужно, — 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 секунд).