API для фінансових документів

Додавайте банківські виписки, рахунки й чеки зі своєї програми. Отримуйте розпізнані дані, перевіряйте сумнівні поля та завантажуйте CSV, Excel або JSON.

Схема OpenAPI Завантажити приклад

Схема OpenAPI містить поля запитів, відповіді й потрібні дозволи. Приклад бере ключ зі змінної середовища та завантажує лише вибраний вами файл.

Підключіть робочий простір

У робочому просторі відкрийте Налаштування → API-ключі. Створіть ключ лише з потрібними дозволами. Ідентифікатор простору розташований після /app/ у його адресі. Передавайте ключ у заголовку Authorization: Bearer до https://rahunko.com/api/v1/workspaces/{workspaceId}.

Відкрити Rahunko

Зберігайте ключ на сервері

Повний ключ показується лише під час створення. Зберігайте його в сховищі секретів, а не в коді браузера, адресах, скриншотах чи журналах. Кожен ключ належить одному простору. Для заміни створіть новий ключ, а потім відкличте старий у налаштуваннях.

Завантажити приклад

Запустіть завантажений приклад через Bun. Задайте RAHUNKO_API_KEY і RAHUNKO_WORKSPACE_ID у змінних середовища. Ключ потребує documents:write і jobs:read. Для експорту також потрібен exports:read. Приклад не підтверджує перевірку документа за вас.

bun upload-document.ts ./statement.pdf

Завантажте файл

Створіть завантаження, передавши розмір файлу, SHA-256 і batchId. Розділіть файл за отриманим partSize та надішліть частини до partsUrl/{partNumber}. Для кожної частини передайте її хеш і Idempotency-Key. Коли всі частини надіслані, викличте completeUrl.

Запустіть обробку

Після завершення завантаження викличте uploadUrl/finalize. За отриманим ідентифікатором завдання перевіряйте його стан. Обробка й перевірка мають окремі стани. Навіть після успішної обробки деякі поля можуть потребувати перевірки.

Перевірте й експортуйте

Отримайте результат завдання або документ. Перевірте чи виправте значення через ендпоінти review, потім експортуйте поточну revision. Якщо версія змінилася, спершу отримайте свіжі дані. Не позначайте документ перевіреним автоматично лише заради експорту.

Ліміти й повторні запити

Розмір файлу до 50 MiB. Завантаження діє одну годину. Використовуйте отримані розмір частини й адреси. Також діють квоти обробки робочого простору. Повторюйте Idempotency-Key лише для того самого запиту чи частини. Після 429 врахуйте Retry-After, якщо він є, та збільшуйте паузу між спробами.

До 300 запитів на ключ і 600 на IP-адресу за 60 секунд. Діють обидва ліміти. Перевищення будь-якого повертає 429 із Retry-After.

Обробляйте помилки явно

400 або 422 означає, що дані треба виправити. 401 чи 403 означає відмову в доступі. 404 означає, що ресурс недоступний у цьому просторі. 409 означає конфлікт стану, версії або ключа повторного запиту. Не повторюйте ці запити без змін. Помилка 5xx може бути тимчасовою. Повторюйте лише безпечні для повторення операції.

Виняток: відповідь результату завдання з HTTP 409 і status=waiting означає, що обробка триває. Продовжуйте перевіряти стан із паузою між запитами.

Вебхуки

Адресу для сповіщень наразі має налаштувати оператор Rahunko. API реєструє її endpointId, а не довільний URL. Перевіряйте підпис точних байтів тіла й часової мітки, відхиляйте застарілі запити та не обробляйте повторно той самий eventId. Поки адресу не налаштовано, перевіряйте стан завдання запитами.

Заголовок x-rahunko-signature містить sha256= і Base64 від HMAC-SHA256 рядка timestamp.eventId.rawBody з налаштованим секретом. Ідентифікатор береться з x-rahunko-event-id, Unix-час у секундах із x-rahunko-timestamp. Перед обробкою тіла порівняйте підписи за сталий час.

Ендпоінти

Список генерується з версійованого контракту API. Кожен запит потребує API-ключа робочого простору. Шляхи, поля й назви дозволів однакові для всіх мов.

Список документівGET /api/v1/workspaces/{workspaceId}/documents: Потрібний дозвіл: documents:read
Отримати документGET /api/v1/workspaces/{workspaceId}/documents/{documentId}: Потрібний дозвіл: documents:read
Видалити документDELETE /api/v1/workspaces/{workspaceId}/documents/{documentId}: Потрібний дозвіл: documents:write
Скасувати обробкуPOST /api/v1/workspaces/{workspaceId}/documents/{documentId}/cancel: Потрібний дозвіл: documents:write
Отримати дані оригіналуGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence: Потрібний дозвіл: documents:read
Отримати сторінку оригіналуGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence/pages/{pageNumber}: Потрібний дозвіл: documents:read
Експортувати версіюGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/export: Потрібний дозвіл: exports:read
Отримати поля для перевіркиGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/review: Потрібний дозвіл: documents:read
Виправити поляPATCH /api/v1/workspaces/{workspaceId}/documents/{documentId}/review: Потрібний дозвіл: documents:write
Підтвердити виконану перевіркуPOST /api/v1/workspaces/{workspaceId}/documents/{documentId}/review/complete: Потрібний дозвіл: documents:write
Отримати стан обробкиGET /api/v1/workspaces/{workspaceId}/jobs/{jobId}: Потрібний дозвіл: jobs:read
Отримати результат і посилання на експортGET /api/v1/workspaces/{workspaceId}/jobs/{jobId}/result: Потрібний дозвіл: jobs:read
Перевірити квоту обробкиGET /api/v1/workspaces/{workspaceId}/quota: Потрібний дозвіл: documents:read
Створити завантаженняPOST /api/v1/workspaces/{workspaceId}/uploads: Потрібний дозвіл: documents:write
Отримати стан завантаженняGET /api/v1/workspaces/{workspaceId}/uploads/{uploadId}: Потрібний дозвіл: documents:write
Скасувати завантаженняPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/abort: Потрібний дозвіл: documents:write
Завершити завантаження частинPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/complete: Потрібний дозвіл: documents:write
Передати файл на обробкуPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/finalize: Потрібний дозвіл: documents:write
Завантажити частинуPUT /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/parts/{partNumber}: Потрібний дозвіл: documents:write
Список зареєстрованих вебхуківGET /api/v1/workspaces/{workspaceId}/webhooks: Потрібний дозвіл: webhooks:read
Зареєструвати налаштований вебхукPOST /api/v1/workspaces/{workspaceId}/webhooks: Потрібний дозвіл: webhooks:write
Вимкнути вебхукDELETE /api/v1/workspaces/{workspaceId}/webhooks/{endpointId}: Потрібний дозвіл: webhooks:write