Створення API - ключа

API - ключі видаються виключно фізичним особам. Щоб використовувати API для бізнес - потреб, необхідно призначити довірену особу - представника компанії та отримати API - ключі на її ім'я або призначити довіреною особою того, у кого вже є ключ.

Дані довіреної особи представника вказуються в договорі з Nova Post.

Як створити ключ клієнту з Європи

1. Створіть обліковий запис в кабінеті My Nova Post

Зареєструйтесь на my.novapost.com. Покрокова інструкція з реєстрації

2. Створіть API-ключ у кабінеті My Nova Post

Перейдіть у розділ «Інтеграції → API-ключі» my.novapost.com та створіть ключ для продакшн-середовища.

Під час створення ключа система автоматично відобразить усі організації, закріплені за вашим акаунтом. Ви можете:

• обрати одну або кілька організацій, до яких надається доступ через цей ключ;

• або створити окремі ключі для кожної організації, якщо потрібно розділити доступи між командами чи проєктами.

Ключ одразу з’явиться у списку з інформацією про:

• дату створення

• назву

• статус (активний/деактивований)

• організацію

• термін дії

Створення тестового API-ключа — спосіб 1

На сторінці генерації тестових ключів на порталі Nova Post:

• Укажіть номер телефону, який зареєстрований у вашому особистому кабінеті my.novapost.com та виконайте запит на створення ключа.

• Після успішного запиту буде згенеровано тестовий API-ключ для пісочниці (Stage environment), прив’язаний до фізичної особи без зв’язку з організаціями.

Спосіб 2

Create or renew a test API key (Sandbox only)

post

https://api-stage.novapost.pl/v.1.0https://api.novapost.com/v.1.0

/test-api-keys

Public endpoint available only in non-production environments (Sandbox) to create or renew a test API key for a client identified by phone.

Requirements:

• The phone number must be registered in the Client Portal (EBC): https://my.novapost.com/

• UA key generation is currently not supported

Behavior:

• If a key already exists and is Active, a repeated call within the same day will return the same key

• If expired, the key will be reactivated with a new expiration date

• If deleted by cleanup, a new key will be created

• Only one active key is allowed per phone, limited to one request per day

Next step: After receiving the apiKey, you must generate a temporary JWT by calling GET /clients/authorization. The JWT is required for all authorized requests. Paste the jwt into the Authorize dialog under the JWT scheme in this documentation to enable Try-it-out.

🔹Description of control elements:

SCHEMA Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.

• Single line description A description that fits into a single line; any text that does not fit remains hidden.

• Multiline description An expanded description that displays more than one line of text.

EXAMPLE Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

Body

application/json

phonestringRequired

Phone number registered in EBC. Format like 49XXXXXXXXX (no '+'). UA keys generation is currently not supported.

Example: 498213437654

Responses

200

Test API key created or returned

application/json

apiKeystringRequired

Test API key for Stage usage only.

Example: 99dde7bdce11414efc2f1c10ddbfd42da8ce4bf2

createdAtstring · date-timeRequiredExample: 2025-08-27T08:03:02.000000Z

expDatestring · date-timeRequiredExample: 2026-08-29T23:59:59.000Z

statusstring · enumRequiredExample: ActivePossible values:

400

Validation error

application/json

404

Client not found in EBC

application/json

409

Multiple matching clients found in EBC

application/json

429

Daily limit exceeded for this user (one request per day)

application/json

503

Connection time-out

application/json

post

/test-api-keys

HTTPcURLJavaScriptPython

POST /v.1.0/test-api-keys HTTP/1.1
Host: api-stage.novapost.pl/
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "phone": "498213437654"
}

{
  "value": {
    "apiKey": "78b97003b587d7758bede604fd185e3e",
    "createdAt": "2025-07-24T09:00:00Z",
    "expDate": "2026-07-24T23:59:59Z",
    "status": "Active"
  }
}

Як створити ключ клієнту з України

Генерація ключів в Бізнес - кабінеті України у вкладці «Налаштування - Безпека».

1

Авторизуйтесь в бізнес - кабінеті як юридична особа

2

Перейдіть в розділ "Налаштування"

3

Виберіть розділ "Безпека"

4

Натисніть "Створити ключ"

5

Ключ створено. Скопіюйте код для використання API Nova Post.

Додаткові рекомендації

• Безпека: Зберігайте ваші API ключі в надійному місці та не розголошуйте їх третім особам.

• Тестування: Використовуйте тестове середовище для перевірки інтеграції, перш ніж переходити до продакшн - середовища.

• Контроль доступу: Регулярно перевіряйте список користувачів, які мають доступ до вашого облікового запису та API ключів.