Доказові звіти
Кожна завершена перевірка має доказовий звіт: документ, що фіксує вердикт, знахідки за ним із їхніми джерелами та pin, за яким його виведено. Його можна передати комплаєнс-офіцеру, аудитору чи контрагенту, і вони підтвердять його справжність без жодного облікового запису. Звіт входить у ціну перевірки й ніколи не тарифікується окремо.
Звідки береться посилання
Завершена перевірка має об'єкт report (див. Перевірки адрес):
| Поле | Опис |
|---|---|
id | Ідентифікатор звіту: r1_ і 32 символи. |
pdf_url | PDF-звіт. |
json_url | Машинозчитувальний двійник PDF. |
verification_url | Перевірка цілісності. |
report дорівнює null, поки перевірка в стані pending чи failed. Посилання постійне: воно ніколи не спливає.
Звіти відкриваються без ключа API. Єдиний захист — ідентифікатор звіту в URL, тож кожен, хто має посилання, може відкрити звіт. Ставтеся до нього як до самого звіту: не вставляйте його в публічні тікети, чати чи логи й передавайте лише тим, хто має читати звіт.
Відкрийте звіт
Усі три ендпоінти публічні й не потребують заголовка Authorization. Для них діє обмеження частоти за IP-адресою джерела; див. Обмеження частоти запитів і ліміти.
PDF
GET /v1/reports/{token}/pdf, де {token} — ідентифікатор звіту.
Коли звіт відкривають уперше в певній мові й оформленні, його формують одразу, а запит чекає на це до приблизно 20 секунд. Кожне наступне відкриття віддає збережений файл із перевіркою цілісності.
| Параметр запиту | Опис |
|---|---|
lang | Мова звіту. Англійська, якщо не вказано. Одна з en, es, pt, ru, uk, tr, vi, id, zh, ja, ko, hi, ar, fr, de. |
templateId | Оформлення за номером, від 1 до 6. |
templateCode | Оформлення за назвою. Ігнорується, якщо вказано й templateId. |
templateId | templateCode |
|---|---|
| 1 | datasheet |
| 2 | classic |
| 3 | editorial |
| 4 | signal |
| 5 | soft |
| 6 | depth |
Якщо не вказано жодного, звіт відкривається в оформленні, закріпленому за ним під час створення. Невідома мова, номер чи код, або неправильний ідентифікатор звіту повертає 400 VALIDATION_ERROR, а parameter називає проблемний параметр запиту; коди чутливі до регістру.
Якщо документ ще формується й не готовий за час очікування, запит повертає 503 REPORT_RENDERING із Retry-After: зачекайте стільки секунд і відкрийте те саме посилання знову. Якщо формування не вдалося, відповідь 503 REPORT_RENDER_FAILED; повідомлення містить короткий ідентифікатор звіту, який слід назвати підтримці, а повторне відкриття посилання після короткої паузи повторює формування.
- curl
- Node.js
- Python
curl -s -o report.pdf "https://api.leeri.ai/v1/reports/$REPORT_ID/pdf?lang=es&templateCode=classic"
import { writeFile } from 'node:fs/promises';
const url = `https://api.leeri.ai/v1/reports/${reportId}/pdf?lang=es&templateCode=classic`;
const response = await fetch(url);
if (response.status === 503) {
console.log('not ready, retry in', response.headers.get('retry-after'), 'seconds');
} else if (response.ok) {
await writeFile('report.pdf', Buffer.from(await response.arrayBuffer()));
}
import requests
response = requests.get(
f"https://api.leeri.ai/v1/reports/{report_id}/pdf",
params={"lang": "es", "templateCode": "classic"},
timeout=60,
)
if response.status_code == 503:
print("not ready, retry in", response.headers.get("Retry-After"), "seconds")
elif response.ok:
with open("report.pdf", "wb") as f:
f.write(response.content)
Кожне оформлення друкує ідентифікатор звіту й адресу сторінки верифікації. Усі оформлення, крім depth, друкують ще й хеш звіту.
JSON
GET /v1/reports/{token}/json повертає той самий звіт як дані у звичайному конверті успіху. Його відновлюють із вердикту, закріпленого під час реєстрації звіту, тож він завжди описує саме цей вердикт, що б не змінилося відтоді.
Поле в data | Опис |
|---|---|
report_id | Ідентифікатор звіту. |
schema_version | Версія корисного навантаження, з якою звіт зареєстровано. Незмінна впродовж життя звіту: старіший звіт завжди віддається у своїй версії. |
payload | Вміст звіту, що хешується: вердикт, його pin, результат, знахідки з їхніми джерелами, експозиція, шляхи й методологія. |
hash | algorithm (SHA-256), canonicalization (RFC 8785), value і covers. |
hash.value — це SHA-256 у шістнадцятковому записі від канонічної форми payload (канонізація JSON за RFC 8785). Він дорівнює хешу, зареєстрованому, коли посилання вперше було видано.
hash.covers дорівнює payload для кожного поточного звіту: ви можете обчислити хеш із отриманого payload і порівняти з hash.value. Для деяких старіших звітів це unredacted_original: хеш охоплює давнішу форму вмісту, яка не віддається, тож його не можна обчислити з відповіді, і його підтверджують через ендпоінт верифікації.
Верифікація
GET /v1/reports/{token}/verification підтверджує, що ідентифікатор звіту справжній. Він повертає:
Поле в data | Опис |
|---|---|
valid | Завжди true, коли ідентифікатор існує; невідомий ідентифікатор повертає 404. |
issued_at | Коли звіт видано. |
payload_hash | Зареєстрований SHA-256 у шістнадцятковому записі. |
hash_algorithm | SHA-256. |
Він нічого не розкриває про адресу, клієнта чи вердикт, тож його можна використати, щоб довести автентичність звіту, не розкриваючи його вміст.
- curl
- Node.js
- Python
curl -s https://api.leeri.ai/v1/reports/$REPORT_ID/verification
const response = await fetch(`https://api.leeri.ai/v1/reports/${reportId}/verification`);
const { data } = await response.json();
console.log(data.valid, data.issued_at, data.payload_hash);
import requests
response = requests.get(f"https://api.leeri.ai/v1/reports/{report_id}/verification", timeout=30)
data = response.json()["data"]
print(data["valid"], data["issued_at"], data["payload_hash"])
Перевірте звіт вручну
Будь-хто, хто має звіт, може перевірити його на https://leeri.ai/uk/verify. Вставте ідентифікатор звіту, і сторінка покаже, коли звіт видано, та зареєстрований хеш. Порівняйте цей хеш із надрукованим на звіті. Інше значення означає, що документ змінили після видачі.
Щоб перевіряти JSON автоматично, канонізуйте payload бібліотекою RFC 8785, обчисліть SHA-256 і порівняйте шістнадцятковий результат і з hash.value, і з payload_hash, який повертає ендпоінт верифікації.
Очікувані помилки
| Статус | Код | Коли |
|---|---|---|
400 | VALIDATION_ERROR | Неправильний ідентифікатор звіту або невідомий lang, templateId чи templateCode. |
404 | NOT_FOUND | Звіту з таким ідентифікатором немає. |
429 | RATE_LIMIT_EXCEEDED | Забагато запитів з цієї IP-адреси. Повторіть після Retry-After. |
503 | REPORT_RENDERING або REPORT_RENDER_FAILED | PDF ще формується, або формування не вдалося. |
Щоб відтворити вердикт, що стоїть за звітом, див. Rederive.