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

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

Справки

По каждой завершённой проверке выпускается справка с электронной подписью. В ней указано, кто запросил проверку, зачем и какое было решение, — а подлинность справки любой может подтвердить на https://kyc.goxost.net/verify.

4 мин чтения

Что такое справка

Справка выпускается для каждой проверки с итоговым решением — GREEN или RED. Кейс ON_HOLD получает справку после решения вашего проверяющего. Справка готова примерно через 5 минут после решения, об этом сообщает вебхук certificate.issued.

Справка содержит:

Раздел Что указано
Заказчик Ваша компания (юридическое название из профиля бизнеса), проект, сайт
Цель Зачем проводилась проверка: purpose сессии, иначе заявителя, иначе цель по умолчанию из профиля бизнеса
Лицо ФИО, дата рождения, тип, страна и номер документа
Решение Одобрено, отклонено или отменено (истёк срок проверки), дата решения, проверяющий — если решение принято вручную
Выполненные проверки Какие проверки проводились (документ, сверка селфи с документом, проверка присутствия, санкции, …) простыми словами
Срок действия Для GREEN — действует до (2 года с даты решения); у RED срока нет
Согласие Когда человек дал согласие, версия текста согласия, устройство и IP-адрес
Договор Номер вашего договора и его SHA-256, если вы передали contract при создании сессии
Изображения Отпечатки SHA-256 сохранённых изображений, использованных в проверке

В PDF есть номер справки (crt_…) и QR-код, который открывает страницу его проверки. Баллы, машинные коды причин и внутренний метод принятия решения не печатаются.

Примечание

Справка никогда не меняется. Если после повторной проверки решение изменилось, выпускается новая версия, а старая помечается как заменённая. При удалении заявителя сохранённый текст справки стирается, а страница проверки показывает справку как отозванную.

Справки, созданные в тестовом окружении, помечены «Тестовый режим — справка не имеет юридической силы».

Справка подтверждает, что проверка состоялась и что она показала на эту дату. Это не документ, удостоверяющий личность, и не подтверждение вашего договора с клиентом.

Скачивание через API

GET /verifications/{id}/certificate возвращает справку по завершённой проверке.

Параметр Значения По умолчанию
format pdf — PDF для печати (скачивается как crt_….pdf); json — машиночитаемое содержимое json
lang Язык PDF: uz, ru, en uz
curl "https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate?format=pdf&lang=en" \
  -H "Authorization: Bearer sk_live_…" \
  -o certificate.pdf
$client = new GuzzleHttp\Client(['base_uri' => 'https://kyc.goxost.net/api/v1/']);
$client->get('verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
    'query' => ['format' => 'pdf', 'lang' => 'en'],
    'sink' => __DIR__ . '/certificate.pdf',
]);
import { writeFile } from 'node:fs/promises';

const res = await fetch(
  'https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate?format=pdf&lang=en',
  { headers: { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await writeFile('certificate.pdf', Buffer.from(await res.arrayBuffer()));
import os, requests

res = requests.get(
    "https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf/certificate",
    headers={"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"},
    params={"format": "pdf", "lang": "en"},
)
res.raise_for_status()
open("certificate.pdf", "wb").write(res.content)

Формат JSON содержит то же, что и PDF, в структурированном виде (certificate.requester, certificate.purpose, certificate.subject, certificate.verification, certificate.valid_until, certificate.verify_url, …), а также электронную подпись и блок meta со status и superseded_by. Если справка понадобится позже, храните PDF или JSON вместе со своими записями. Чтобы доказать подлинность, используйте страницу проверки или GET /certificates/{id} — подпись проверяет только GOXOST KYC.

Повторные запросы возвращают точно такой же документ. Каждое скачивание записывается в ваш журнал аудита.

Ошибка Когда
409 conflict Проверка в статусе ON_HOLD (итогового решения ещё нет)
404 not_found Проверка не найдена или заявитель удалён
400 validation_failed Неподдерживаемый format или lang
503 certificate_unavailable Справки временно недоступны — повторите позже

В панели на странице заявителя есть кнопка Скачать справку о проверке для тех же файлов.

Как любой может проверить справку

Передайте справку тому, кому нужно подтверждение, — банку, партнёру или самому человеку. Аккаунт для проверки не нужен. Страница https://kyc.goxost.net/verify предлагает три способа.

1. По номеру или QR-коду

Отсканируйте QR-код в PDF, откройте ссылку https://kyc.goxost.net/verify/crt_… или введите номер справки (или вставьте ссылку) в поиск на https://kyc.goxost.net/verify. Страница показывает:

  • подлинная ли справка, недействительна, заменена более новой версией или отозвана;
  • заказчика и цель;
  • дату выпуска, решение и срок действия;
  • тип документа и маскированный номер (первые 2 и последние 4 символа, например L8•••02C3);
  • когда человек дал согласие.

Имя, дата рождения и другие персональные данные здесь не показываются.

2. Загрузите PDF

На той же странице загрузите PDF-файл (до 4 МБ). Он побайтно сравнивается с PDF, выпущенным GOXOST KYC, — любое изменение, даже в один символ, не пройдёт проверку. Файл не сохраняется.

3. Введите номер документа с копии

Если вам показывают распечатку или скан, введите полный номер документа, напечатанный на ней. Если номер совпадает со справкой, страница покажет ФИО и номер документа для сравнения с копией. Несовпадение означает, что копию изменили или подделали. Так можно проверить одну справку до 20 раз в сутки.

Совет

Везде, где вы передаёте справку, указывайте рядом ссылку на проверку — получатель подтвердит её в один клик.

Статус справки

Чтобы проверить свою справку из кода, вызовите GET /certificates/{certificate_id} с API-ключом того же окружения. Персональных данных в ответе нет.

curl https://kyc.goxost.net/api/v1/certificates/crt_01m6yyj5eaqdmyg2ty0mheaj3h \
  -H "Authorization: Bearer sk_live_…"
{
  "certificate_id": "crt_01m6yyj5eaqdmyg2ty0mheaj3h",
  "version": 1,
  "status": "current",
  "signature_valid": true,
  "valid": true,
  "decision": "GREEN",
  "outcome": "approved",
  "issued_at": "2026-11-09T10:09:30Z",
  "valid_until": "2028-11-09T10:04:12Z",
  "expired": false,
  "superseded_by": null,
  "verify_url": "https://kyc.goxost.net/verify/crt_01m6yyj5eaqdmyg2ty0mheaj3h"
}
status Значение
current Актуальная версия справки
superseded Повторная проверка выпустила новую версию — см. superseded_by
revoked Заявитель удалён, справка отозвана
invalid_signature Сохранённый текст не соответствует подписи — не доверяйте ему

valid — единый ответ на вопрос «проверен ли человек сейчас»: он равен true, только если status — current, решение — GREEN и valid_until ещё не наступил.

Срок действия и повторная проверка

Результат GREEN действует 2 года с даты решения (valid_until в проверке, заявителе и справке). За 30 дней до окончания и в момент окончания приходит applicant.reverification_due. Чтобы проверить человека снова, вызовите POST /applicants/{id}/reset и создайте новую сессию — новая проверка получит свою справку.