Під’єднайте vporiadku до своєї системи

Що вміє API

Кожен запит проходить через ті самі правила, що й застосунок: серії нумерації, перевірку ставок ПДВ, ліміти тарифу та журнал аудиту. API є ще одним входом до продукту, а не його другою копією.

• Рахунки та документи

  Список із фільтрами за типом, статусом, клієнтом, датами, мітками та часом зміни, деталі, PDF, ISDOC і UBL, створення, копіювання, редагування, виставлення, надсилання електронною поштою, нагадування про оплату, кредит-нота (dobropis) і сторнування.

• Платежі

  Оплати документа: список, реєстрація, оплата решти суми одним викликом і видалення. Статус документа перераховується сам.

• Клієнти

  Довідник покупців: пошук за назвою, IČO, DIČ або електронною поштою, зміни з певного моменту, деталі, створення з перевіркою на дублікати, редагування та видалення.

• Каталог

  Позиції та послуги каталогу: фільтрування, сортування, створення, редагування та видалення. Входить до тарифу Profi.

• Витрати

  Отримані документи: список із фільтрами за статусом, категорією, періодом і часом зміни, проведення, редагування та видалення. Входить до тарифу Profi.

• Отримані е-фактури

  Скринька отриманих е-фактур: список, деталі з рядками та розбивкою ПДВ і архівований оригінал UBL. Читання через API нічого не позначає як прочитане.

• Періодичні рахунки

  Розклади періодичних рахунків та їхні останні запуски (лише для читання).

• Профілі компаній

  Компанії, від імені яких робочий простір виставляє документи, з позначкою компанії за замовчуванням (лише для читання).

• Банківські рахунки

  Банківські рахунки для оплати документів, з позначкою основного (лише для читання).

• Вебхуки

  Події, які vporiadku надсилає на вашу адресу: виставлення, оплата, нова витрата, отримана е-фактура тощо. Підписані HMAC-SHA256; керувати ними можна в застосунку або через API.

• Партнерські застосунки

  OAuth 2.0 із PKCE: клієнти під’єднують ваш застосунок одним кліком, а ви отримуєте токен для кожного робочого простору саме з тими дозволами, які вони схвалили.

Швидкий старт

Базова адреса API: https://api.vporiadku.sk/api/v1. Відповіді надходять у JSON, суми передаються десятковими числами у валюті документа, дати у форматі YYYY-MM-DD.

1. Крок 1

   Увімкніть модуль Firma

   Публічний API входить до додаткового модуля Firma для тарифу Profi. Без нього API відповідає кодом 403.

2. Крок 2

   Створіть ключ

   У розділі Налаштування → API власник або адміністратор створює ключ і вибирає для нього дозволи. Повний ключ показується лише один раз.

3. Крок 3

   Надішліть перший запит

   Ping перевіряє ключ і повертає його дозволи. Зберігайте ключ у змінній середовища й ніколи не зберігайте його в коді.

4. Крок 4

   Продовжуйте в довіднику

   Кожне поле кожного запиту й відповіді описано в довіднику OpenAPI 3.1, з якого ви також можете згенерувати клієнт.

curl https://api.vporiadku.sk/api/v1/ping \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

Автентифікація ключем

Надсилайте API-ключ в одному з двох заголовків, або, якщо запит іде від партнерського застосунку, токен доступу OAuth. Ключі починаються з fak_, а токени доступу з vpa_.

Authorization: Bearer fak_…
X-API-Key: fak_…
Authorization: Bearer vpa_…

• Повний ключ показується лише під час створення; ми зберігаємо тільки його відбиток SHA-256. Втрачений ключ не відновлюється. Відкличте його та створіть новий.
• Ключ або токен доступу діє як власник свого робочого простору й ніколи не має доступу до іншого.
• API призначений для комунікації сервер-сервер. Ключу не місце в браузері чи мобільному застосунку: хто його побачить, той зможе ним скористатися.
• Ключ можна відкликати одним кліком у розділі Налаштування → API; наступний запит із ним отримає 401.
• Застосунок, який обслуговує багатьох клієнтів vporiadku, не збирає їхніх ключів: він під’єднується через OAuth 2.0 (про це в наступному розділі).

Партнерські застосунки (OAuth 2.0)

Створюєте інтеграцію для багатьох клієнтів vporiadku: платформу інтернет-магазинів, бухгалтерську програму, CRM? Зареєструйте її один раз як застосунок. Кожен клієнт під’єднає його одним кліком на екрані згоди, а ваш сервер отримає токен доступу для кожного робочого простору саме з тими дозволами, які схвалив цей клієнт. Стандартний потік із кодом авторизації (authorization code) та PKCE, ті самі дозволи, що й для API-ключів.

1. 1

   Зареєструйте застосунок

   У розділі Налаштування → API → Застосунки: назва й вебсайт, які побачать клієнти, ваші адреси перенаправлення та максимум того, що застосунок може запитувати. Ви отримаєте client_id і client_secret; секрет показується лише один раз. Робочий простір може зареєструвати до 10 застосунків, і платний тариф для цього не потрібен.

2. 2

   Перенаправте клієнта на екран згоди

   З response_type=code, вашим client_id, зареєстрованою адресою redirect_uri, потрібними дозволами (scope), параметром state і PKCE code_challenge (S256). Клієнт входить, вибирає робочий простір і схвалює доступ, або скасовує, і тоді ви отримаєте error=access_denied. Робочому простору потрібен модуль Firma, а схвалити може лише його власник або адміністратор.

3. 3

   Обміняйте код на токени

   Код повертається на вашу адресу перенаправлення разом із вашим state. Протягом 10 хвилин обміняйте його на кінцевій точці токенів, передавши секрет застосунку та code_verifier. Ви отримаєте токен доступу, токен оновлення, надані дозволи (scope) і workspace_id.

4. 4

   Викликайте API

   Надсилайте токен доступу в заголовку Authorization: Bearer у кожному запиті до /api/v1. Він дійсний 60 хвилин; ping покаже робочий простір і дозволи, які має токен.

5. 5

   Оновіть токен до завершення терміну дії

   grant_type=refresh_token повертає нову пару токенів, а старий токен оновлення стає використаним. Токен оновлення діє 365 днів від видачі; якщо використаний токен пред’явити ще раз пізніше ніж через 30 секунд, буде відкликано весь ланцюжок.

6. 6

   Від’єднання

   Відкличте токен на кінцевій точці відкликання (RFC 7009); відкликання останнього токена оновлення від’єднує застосунок від робочого простору. Клієнт теж може будь-коли від’єднати ваш застосунок. Тоді на його токени API відповідатиме 401.

Зареєструвати застосунок у розділі Налаштування → API → Застосунки →

Кінцеві точки

Екран згоди

https://vporiadku.sk/oauth/authorize

Кінцева точка токенів

https://api.vporiadku.sk/api/oauth/token

Кінцева точка відкликання

https://api.vporiadku.sk/api/oauth/revoke

• Обов’язкові PKCE з S256 і параметр redirect_uri, що точно збігається із зареєстрованою адресою: https або http лише на localhost.
• Кожен застосунок є конфіденційним клієнтом OAuth: кінцева точка токенів вимагає секрет застосунку через HTTP Basic або як client_id і client_secret у формі, але ніколи обома способами одразу. Зберігайте секрет на своєму сервері.
• Дозволи ті самі, що й для API-ключів. На запит поза межами схваленого клієнтом API відповідає 403 API_KEY_SCOPE_MISSING із заголовком WWW-Authenticate: Bearer error="insufficient_scope".
• Ліміт діє окремо для кожного застосунку в кожному робочому просторі: 120 запитів за 60 секунд на кожен робочий простір, до якого під’єднано ваш застосунок; запити з оновленими токенами теж ураховуються.
• Через /webhooks ваш застосунок може зареєструвати до 5 кінцевих точок вебхуків у кожному під’єднаному робочому просторі; вони отримують лише події, дані яких ви можете читати за своїми дозволами, і видаляються, коли клієнт від’єднує застосунок.
• Помилки кінцевої точки токенів відповідають RFC 6749: поля error та error_description; застосунок, який звертається до неї надто часто, отримує 429 temporarily_unavailable із заголовком Retry-After. На прострочений токен доступу API відповідає 401 із WWW-Authenticate: Bearer error="invalid_token". Оновіть токен і повторіть запит.

import { createHash, randomBytes } from 'node:crypto'

const codeVerifier = randomBytes(32).toString('base64url')
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url')
const state = randomBytes(16).toString('base64url')

// Keep codeVerifier and state in the user's session until the callback;
// send codeChallenge and state with the user to the consent screen.

https://vporiadku.sk/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.example%2Foauth%2Fcallback&scope=invoices%3Awrite%20clients%3Aread%20webhooks%3Awrite&state=$STATE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256

curl -X POST https://api.vporiadku.sk/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://your-app.example/oauth/callback \
  -d code_verifier="$CODE_VERIFIER"

curl -X POST https://api.vporiadku.sk/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

curl -X POST https://api.vporiadku.sk/api/v1/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.example/hooks/vporiadku", "events": ["invoice.paid", "client.created"]}'

Дозволи ключа

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

• Запис включає читання того самого ресурсу: хто створює рахунок, той отримує його назад у відповіді.
• Операція поза дозволами завершується відповіддю 403 API_KEY_SCOPE_MISSING, а в details.required указано дозвіл, якого бракує. Набір дозволів наявного ключа не змінюється: створіть новий ключ; застосунок натомість просить клієнта схвалити дозволи ще раз.
• Ключі, створені до запровадження дозволів, мають повний доступ (записаний як *), щоб наявні інтеграції працювали й далі.

Ліміти та пагінація

Кожен ключ (а також кожен партнерський застосунок у кожному робочому просторі, до якого його під’єднано) може надіслати 120 запитів за 60 секунд сукупно на всі кінцеві точки. Вікно фіксоване й після завершення повністю поновлюється.

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 60

• Кожна відповідь містить заголовки X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset (кількість секунд до поновлення вікна).
• Після вичерпання ліміту надходить відповідь 429 RATE_LIMIT_EXCEEDED із заголовком Retry-After; зачекайте вказану кількість секунд. Кожен ключ має власне вікно, як і кожен застосунок у кожному робочому просторі, до якого його під’єднано.
• Після 30 невдалих автентифікацій з однієї адреси за 60 секунд API перестає перевіряти ключі з цієї адреси, доки вікно не мине.
• Списки приймають page (від 1) і limit (за замовчуванням 20, щонайбільше 100) і повертають { data, total, page, limit }.

Idempotency-Key

Надсилайте заголовок Idempotency-Key у запитах POST і PATCH: тоді повторення запиту після обриву з’єднання не створить другого рахунку. Ключ діє протягом 24 годин і належить API-ключу (або партнерському застосунку в цьому робочому просторі), який його надіслав.

• Повтор із тим самим методом, шляхом і тілом отримує збережену відповідь із Idempotent-Replayed: true, і нічого не виконується вдруге: ні другого рахунку, ні листа, ні вебхука.
• Той самий ключ з іншим запитом завершується відповіддю 409 IDEMPOTENCY_KEY_REUSED.
• Повтор, поки перший запит ще виконується, завершується відповіддю 409 IDEMPOTENCY_KEY_IN_USE. Спробуйте за мить.
• Зберігається лише успішна відповідь: невдалий запит можна повторити з тим самим ключем.

curl -X POST https://api.vporiadku.sk/api/v1/clients \
  -H "Authorization: Bearer $VPORIADKU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4e0a-9c55-0f3e8a1b2c4d" \
  -d '{"name": "Novák s.r.o.", "ico": "12345678", "email": "faktury@novak.sk"}'

Помилки

Кожна помилка має однакову структуру. Орієнтуйтеся на error.code; повідомлення англійською і може змінюватися. Невідоме поле в тілі запиту дає помилку 400, а не мовчки ігнорується.

{
  "data": null,
  "meta": null,
  "error": {
    "code": "API_KEY_SCOPE_MISSING",
    "message": "This API key lacks the \"invoices:write\" scope",
    "details": {
      "operation": "createInvoice",
      "required": "invoices:write",
      "granted": [
        "invoices:read"
      ]
    }
  }
}

Кінцеві точки

Операцій за адресою https://api.vporiadku.sk/api/v1: 49. Таблиця генерується з того самого каталогу, за яким працює сервер.

Усі поля, параметри й відповіді описано в довіднику API →

Приклади

Приклади читають ключ зі змінної середовища VPORIADKU_API_KEY. Значення в кутових дужках замініть на ідентифікатори з попередніх відповідей.

curl "https://api.vporiadku.sk/api/v1/invoices?status=overdue&page=1&limit=50" \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

# 1. A draft; the server computes every total itself
curl -X POST https://api.vporiadku.sk/api/v1/invoices \
  -H "Authorization: Bearer $VPORIADKU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-1001" \
  -d '{"clientId": "<client id>", "issueDate": "2026-10-12", "dueDate": "2026-10-26", "items": [{"name": "Konzultácia", "quantity": 2, "unit": "hod", "unitPrice": 60, "vatRate": 23}]}'

# 2. Issue it: the number is fixed and the content locked
curl -X POST https://api.vporiadku.sk/api/v1/invoices/<invoice id>/issue \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

# 3. E-mail it to the client with the PDF attached
curl -X POST https://api.vporiadku.sk/api/v1/invoices/<invoice id>/send \
  -H "Authorization: Bearer $VPORIADKU_API_KEY"

curl -X POST https://api.vporiadku.sk/api/v1/invoices/<invoice id>/payments \
  -H "Authorization: Bearer $VPORIADKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 147.60, "paymentDate": "2026-10-20", "paymentMethod": "bank_transfer"}'

Вебхуки

Подій: 35, груп: 13. vporiadku надсилає їх методом POST на адресу, яку ви зареєструєте, і підписує секретом цієї адреси.

• Адреса отримує лише вибрані вами події; кожна адреса має власний секрет whsec_.
• Підпис міститься в заголовку x-vporiadku-signature: v1= і HMAC-SHA256 рядка «мітка часу.тіло». Перевіряйте його на необробленому тілі, порівнюйте за сталий час і відхиляйте доставки, старіші за 300 секунд.
• Відповідайте кодом 2xx протягом 10 секунд. Інші спроби ми повторюємо зі зростаючим інтервалом, загалом 8 разів; після 400, 401, 403, 404, 405, 410 і 422 уже не повторюємо.
• Та сама доставка може надійти двічі. Відкидайте дублікати за idempotencyKey з конверта.
• Кінцеві точки, вибір подій, секрети, тестова подія та журнал доставок є в розділі Налаштування → API → Вебхуки. Через /webhooks із дозволом webhooks:write кінцеві точки можна реєструвати, змінювати, тестувати й видаляти, а також замінювати їхні секрети. Партнерський застосунок бачить лише ті кінцеві точки, які зареєстрував сам, і керує тільки ними.
• Через API кінцева точка може отримувати лише події, дані яких ключ або токен може читати: події рахунків і документів потребують invoices:read, події платежів потребують payments:read, події витрат expenses:read і так далі. Події підключення до банку, звітів з ПДВ, підписки й команди можна налаштувати лише в застосунку.

Події

Рахунки

invoice.createdinvoice.updatedinvoice.sentinvoice.viewedinvoice.paidinvoice.overdueinvoice.cancelled

Інші документи

credit_note.createdquote.createdquote.acceptedquote.rejectedquote.expireddelivery_note.createdorder.created

Платежі

payment.recordedpayment.matched

Витрати

expense.createdexpense.updatedexpense.paid

Банк

bank_statement.importedbank_feed.syncedbank_feed.consent_expiring

е-Фактура

einvoice.senteinvoice.deliveredeinvoice.failedeinvoice.received

Контакти

client.createdsupplier.created

Каталог

item.created

Періодичні рахунки

recurring_invoice.generatedrecurring_invoice.failed

ПДВ

vat_report.generated

Підписка

subscription.updated

Команда

team.member_joined

Тест

ping

import { createHmac, timingSafeEqual } from 'node:crypto'

export const isGenuine = (rawBody, signature, timestamp, secret) => {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = 'v1=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(String(signature))
  return a.length === b.length && timingSafeEqual(a, b)
}

// rawBody = the request body exactly as received; signature = 'x-vporiadku-signature',
// timestamp = 'x-vporiadku-timestamp'. Answer 2xx within 10 seconds, work afterwards,
// and drop repeats by the envelope's idempotencyKey.

Конверт, заголовки та всі події описано в довіднику API →

Доступ і ціна

Публічний API та вебхуки входять до додаткового модуля Firma для тарифу Profi за 3,90 EUR на місяць без ПДВ. Модуль також додає команду з ролями, кілька компаній в одному акаунті та доступ для бухгалтера.

Поширені запитання

Скільки коштує доступ до API?

API та вебхуки входять до додаткового модуля Firma для тарифу Profi. За виклики нічого додатково платити не потрібно; діє ліміт 120 запитів на хвилину для кожного ключа.

Чи можна через API надсилати е-фактури в мережу Peppol?

Ні. Отримані е-фактури через API читати можна, а надсилання через Peppol публічний API не пропонує.

Чи є тестове середовище?

Окремої пісочниці (sandbox) немає: API завжди працює з реальними даними вашого робочого простору. Почніть із ключа лише для читання, а записи пробуйте, пам’ятаючи, що навіть чернетка отримує номер зі своєї серії нумерації.

Як змінюється API?

Версія вказана в шляху: /api/v1. Додавання поля до відповіді не є зміною, яка щось зламає, тож невідомі поля ігноруйте. Зміна, яка зламала б наявну інтеграцію, з’явилася б у новій версії.

Чи можна керувати вебхуками через API?

Так. З дозволом webhooks:write через /webhooks можна реєструвати, змінювати, тестувати й видаляти кінцеві точки, лише для подій, дані яких ключ або токен може читати. Партнерський застосунок у кожному під’єднаному робочому просторі керує лише власними кінцевими точками.

Як застосунок для багатьох клієнтів під’єднується до vporiadku?

Через OAuth 2.0: зареєструйте застосунок у розділі Налаштування → API → Застосунки, перенаправте кожного клієнта на екран згоди й зберігайте отримані токени окремо для кожного робочого простору. Клієнт вибирає робочий простір, схвалює дозволи й може будь-коли від’єднати застосунок. Кожен під’єднаний робочий простір має власний ліміт: 120 запитів на хвилину.