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

Обмінюєте client_id і client_secret на Bearer-токен на одну годину, лише сервер-до-сервер.

Обмінюєте client_id і client_secret на Bearer-токен на одну годину, лише сервер-до-сервер.

← Назад до документації API

Перший рахунок за 6 кроків

  1. Створіть облікові дані в панелі в розділі Рахунки → Налаштування → Доступ до API і одразу скопіюйте client_secret — він показується лише один раз.
  2. Надішліть POST /v1/auth/token з grant_type client_credentials, client_id і client_secret.
  3. У відповідь ви отримуєте access_token, token_type Bearer, expires_in 3600 і список наданих області.
  4. Передавайте токен у заголовку Authorization: Bearer <access_token> у кожному іншому виклику.
  5. Перевірте, що саме ви отримали, через GET /v1/me: тенант, області і поточні кошики лімітів.

Усі ендпоїнти

МетодЕндпоїнтScopeIdempotency-KeyЗапитів / хвилину
POST/auth/token
Обміняти облікові дані на токен доступу
——120
GET/me
Тенант, scope-и та поточні ліміти
invoices:read—120

Що таке API 4invoices

bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}
bash
curl -sS https://api.4invoices.net/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → тенант, надані scope-и та поточні ліміти
javascript
// Зберігайте токен у кеші; не запитуйте новий на кожен запит.
let cached = { token: "", expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt - 60_000) return cached.token;

  const res = await fetch("https://api.4invoices.net/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.FOURINVOICES_CLIENT_ID,
      client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token ${res.status}`);

  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Scope-и

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Лише сервер-до-сервер. Ніколи не викликайте API з браузерного JavaScript: client_secret потрапить до відвідувача, а CORS усе одно блокує будь-який джерело.

Помилки

СтатусТипКод
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Типові помилки

  • Токен ендпоінт має власний ліміт на IP. Один токен на процес, що оновлюється до завершення строку дії, — а не по одному на запит.
  • client_secret зберігається лише як хеш; якщо ви його втратите, створіть нові облікові дані й відкличте старі.
  • Створюйте окремі облікові дані для ERP, магазину та внутрішніх скриптів, кожні з мінімальними області. Відкликання одних не впливає на інші.
  • CORS не допускає жодного браузер origin: API за задумом працює сервер-до-сервер.

Питання та відповіді для розробників

Що станеться, якщо client_secret неправильний?

Ви отримаєте 401 з code invalid_client. Занадто короткий секрет відхиляється раніше, на етапі валідації, з 422 validation_failed і param client_secret.

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

Ні. Є один продакшн-хост. Тестуйте на проформах (document_kind проформа) і через /invoices/preview-totals, який не витрачає фіскальний номер.

Чи можна звузити області наявних облікових даних?

Так, у панелі. Уже видані токени зберігають області, з якими їх створено, до завершення строку дії — протягом однієї години.