Документація API

Початок роботи

Створіть обліковий запис і пройдіть онбординг на app.pmnt.app — додайте свій бізнес-субʼєкт та його банківський рахунок IBAN.
Згенеруйте API-ключ у розділі Налаштування → API-ключі. Повний ключ показується лише один раз, одразу після створення — збережіть його в надійному місці.

Зробіть свій перший запит:

curl https://app.pmnt.app/api/me \
  -H "Authorization: Bearer apa_YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json"

Автентифікація

Кожен запит до захищеного ендпоїнта передає ваш API-ключ у заголовку Authorization. Ключі — це непрозорі рядки з префіксом apa_, а не JWT.

Authorization: Bearer apa_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ключ привʼязаний до вашого облікового запису й має всі його права — окремих обмежень (scopes) для ключів поки немає.
Зберігається лише хеш ключа. Якщо ви втратили ключ, створіть новий і відкличте старий — відкликання діє миттєво.
Запити без дійсного ключа отримують 403 Forbidden на захищених ендпоїнтах.

Типи доступу до API

Усі ендпоїнти типово потребують API-ключ — передавайте його в кожному запиті як Authorization: Bearer apa_…. Лише кілька публічних ендпоїнтів доступні без ключа:

GET /invoice/{short_code} — публічний пошук рахунку; сам короткий код виконує роль токена доступу.
POST /delivery-info — дані доставки, які надсилає сторінка платника.
GET /delivery-providers, GET /delivery-providers/{id} — довідник служб доставки.
GET /categories, GET /categories/{id}, GET /purposes, GET /purposes/{id} — довідники платежів.

Конвенції JSON:API

API відповідає специфікації JSON:API 1.0. Надсилайте та очікуйте тип вмісту application/vnd.api+json. Ендпоїнти списків підтримують стандартні параметри запиту:

Параметр	Опис	Приклад
`filter[attr]`	Фільтрувати список за значенням атрибута.	`?filter[state]=paid`
`sort`	Поля сортування через кому; префікс `-` означає спадний порядок.	`?sort=-qr_generated_at`
`page[limit]`	Keyset-пагінація: розмір сторінки та курсори `page[after]` / `page[before]` з попередньої відповіді.	`?page[limit]=25`
`page[count]`	Додати загальну кількість записів до обʼєкта meta.	`?page[count]=true`
`include`	Довантажити повʼязані ресурси в тій самій відповіді.	`?include=business_entity,bank_account`
`fields[type]`	Часткові набори полів: повернути лише перелічені атрибути.	`?fields[invoice]=short_code,state`

Помилки

Помилки повертаються в конверті помилок JSON:API з HTTP-статусом, що відповідає зовнішній помилці:

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "forbidden"
    }
  ]
}

Ендпоїнти

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

Базова URL-адреса: https://app.pmnt.app/api · Інтерактивний Swagger UI · Специфікація OpenAPI (JSON)

Профіль

Визначення облікового запису за API-ключем.

GET /me: Профіль користувача, якому належить наданий API-ключ.

Рахунки

Виставляйте платіжні рахунки й керуйте ними. Кожен рахунок отримує публічну сторінку платника та платіжний QR-код НБУ.

GET /invoices: Список ваших рахунків (з фільтрами та пагінацією).
POST /invoices: Створити рахунок. Генерація QR-коду ставиться в чергу автоматично.
GET /invoices/{id}: Отримати окремий рахунок.
PATCH /invoices/{id}: Оновити примітку покупця або позначку «обране».
DELETE /invoices/{id}: Видалити рахунок.
POST /invoices/{id}/disable: Деактивувати активний рахунок.
POST /invoices/{id}/enable: Повторно увімкнути вимкнений рахунок.
POST /invoices/{id}/confirm-payment: Позначити рахунок як оплачений.
GET /invoice/{short_code}: Публічний пошук рахунку за коротким кодом. Сам короткий код є токеном доступу; поля лише для власника залишаються прихованими.

Наприклад, створіть рахунок і отримайте його сторінку платника та QR-код:

curl -X POST https://app.pmnt.app/api/invoices \
  -H "Authorization: Bearer apa_YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invoice",
      "attributes": {
        "business_entity_id": "YOUR_BUSINESS_ENTITY_ID",
        "bank_account_id": "YOUR_BANK_ACCOUNT_ID",
        "purpose": "Оплата за послуги",
        "amount": 1980
      }
    }
  }'

Відповідь надходить зі станом created; qr_url заповнюється асинхронно за мить. Сторінка платника доступна за адресою https://app.pmnt.app/pay/{short_code}.

{
  "data": {
    "type": "invoice",
    "id": "6b9f2c1e-4a5d-4e8f-9c3b-2d7a8e1f0b4c",
    "attributes": {
      "short_code": "…",
      "state": "created",
      "qr_url": null
    }
  }
}

Бізнес-субʼєкти

Компанії, ФОП та фізичні особи, від імені яких ви виставляєте рахунки. Податкові номери (ЄДРПОУ/РНОКПП) перевіряються автоматично.

GET /business-entities: Список ваших бізнес-субʼєктів.
POST /business-entities: Створити бізнес-субʼєкт (назва, податковий номер, тип).
GET /business-entities/{id}: Отримати окремий бізнес-субʼєкт.
PATCH /business-entities/{id}: Оновити назву або тип.
DELETE /business-entities/{id}: Видалити субʼєкт, який не має рахунків.
POST /business-entities/{id}/set-default: Зробити цей субʼєкт за замовчанням.

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

IBAN-рахунки, привʼязані до ваших бізнес-субʼєктів. Реквізити банку визначаються з IBAN автоматично.

GET /bank-accounts: Список ваших банківських рахунків.
POST /bank-accounts: Додати IBAN до бізнес-субʼєкта.
GET /bank-accounts/{id}: Отримати окремий банківський рахунок.
PATCH /bank-accounts/{id}: Оновити позначку основного рахунку.
DELETE /bank-accounts/{id}: Видалити банківський рахунок.
POST /bank-accounts/{id}/set-primary: Зробити цей рахунок основним.

Доставка

Необовʼязковий збір даних доставки для рахунків, що потребують відправлення.

POST /delivery-info: Надіслати дані доставки для рахунку (використовується сторінкою платника).
GET /delivery-providers: Список підтримуваних служб доставки.
GET /delivery-providers/{id}: Отримати службу доставки.

Довідники

Довідкові дані для категоризації рахунків: категорії та призначення платежів НБУ.

GET /categories: Список категорій платежів.
GET /categories/{id}: Отримати категорію платежу.
GET /purposes: Список призначень платежів.
GET /purposes/{id}: Отримати призначення платежу.

Аналітика

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

GET /invoices/{id}/visits: Список відвідувань сторінки рахунку (до 100 за запит).
GET /invoices/{id}/visits/stats: Агрегована статистика відвідувань з необовʼязковим діапазоном from/to.

Життєвий цикл рахунку

Рахунок проходить через такі стани; переходи відбуваються через сторінку платника та наведені вище ендпоїнти:

stateDiagram-v2
    direction LR
    [*] --> created: POST /invoices
    created --> pending_delivery: потрібна доставка
    created --> awaiting_payment: платник відкриває сторінку
    pending_delivery --> awaiting_payment: дані доставки надіслано
    created --> paid: підтвердження оплати
    awaiting_payment --> paid: підтвердження оплати
    created --> expired: минув термін valid_until
    pending_delivery --> expired
    awaiting_payment --> expired
    created --> disabled: деактивація
    pending_delivery --> disabled
    awaiting_payment --> disabled
    disabled --> created: повторне увімкнення

created — Рахунок виставлено, але сторінку платника ще ніхто не відкривав.
pending_delivery — Платник відкрив рахунок, що потребує доставки, але ще не надіслав дані доставки.
awaiting_payment — Платник відкрив сторінку оплати.
paid — Власник підтвердив оплату через confirm-payment.
expired — Термін valid_until минув; прострочення застосовується автоматично щохвилини.
disabled — Вимкнений вручну через disable; enable повертає його в created.

Повні схеми атрибутів і решта перелічень (field_lock_preset, transfer_type, …) містяться у специфікації OpenAPI.

Підтримка

Маєте запитання щодо API? Напишіть на admin@pmnt.app або перегляньте Довідковий центр.