Огляд API

API Foppy доступне за базовим шляхом /api/v1. Усі запити та відповіді — у форматі JSON. Автентифікація — через JWT у заголовку Authorization: Bearer <token>.

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

Метод	Шлях	Опис
POST	/api/v1/auth/register	Реєстрація (акаунт очікує підтвердження email)
POST	/api/v1/auth/verify-email	Підтвердження email за токеном, повертає JWT
POST	/api/v1/auth/resend-verification	Повторно надіслати лист підтвердження
POST	/api/v1/auth/login	Вхід, повертає JWT (потрібен підтверджений email)
POST	/api/v1/auth/forgot-password	Надіслати лист для відновлення пароля
POST	/api/v1/auth/reset-password	Встановити новий пароль за токеном

Telegram

Метод	Шлях	Опис
GET	/api/v1/telegram/status	Чи прив’язаний Telegram до акаунта
POST	/api/v1/telegram/link	Видати посилання для прив’язки (/start <token>)

Профіль і рахунки

Метод	Шлях	Опис
GET	/api/v1/kveds	Повний класифікатор КВЕД (ДК 009:2010)
POST	/api/v1/profile	Створити / оновити реквізити ФОП
POST	/api/v1/invoices	Створити швидкий рахунок
GET	/api/v1/invoices	Список рахунків (пагінація, пошук, фільтр за статусом)
GET	/api/v1/public/invoices/{token}	Публічна сторінка рахунку (без авторизації)

Приклади запитів

Базова адреса продакшн-API — https://core.foppy.co. У прикладах нижче замініть <jwt> на токен, отриманий після входу, а <token> — на публічний токен рахунку.

Реєстрація

curl -X POST https://core.foppy.co/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"S3cret-pass"}'

{ "pending": true, "email": "[email protected]" }

Вхід

curl -X POST https://core.foppy.co/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"S3cret-pass"}'

{ "token": "<jwt>", "user_id": "a1b2c3d4-0000-0000-0000-000000000000" }

Публічна сторінка рахунку (без авторизації)

curl https://core.foppy.co/api/v1/public/invoices/<token>

{
  "number": "INV-000123",
  "status": "issued",
  "amount": "5000.00",
  "currency": "UAH",
  "beneficiary_name": "ФОП Петренко Іван Іванович",
  "iban": "UA903052992990004149123456789",
  "purpose": "Оплата за консультаційні послуги згідно з рахунком INV-000123",
  "qr_payload": "BCD\n001\n1\nUCT\n...",
  "qr_svg": "<svg ...>…</svg>",
  "footer_text": "Сформовано у Foppy",
  "footer_url": "https://foppy.co"
}

Помилки

Усі помилки повертаються у форматі JSON зі статусом HTTP та полем error:

{ "error": "not found" }

Спробуйте запити в інтерактивній пісочниці.