Что такое справка
Справка выпускается для каждой проверки с итоговым решением — 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 и создайте новую сессию — новая проверка получит свою справку.