Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Нова підписка

Створити нову підписку

post
/tracking-push/subscribers

Цей метод використовується для створення нової підписки для отримання сповіщень про відстеження через webhook. Підписка може бути різних типів, наприклад для окремого номера або для компанії, і є необхідною для клієнтів, які хочуть отримувати оновлення статусів відправлень у реальному часі.

Authorizations
AuthorizationstringRequired

Авторизаційний JWT-токен із терміном дії 1 година в заголовку

Body
typestring · enumRequired

Тип підписки, яку необхідно створити. Це обов’язкове поле, яке може приймати такі значення:

  • individual — для особистих облікових записів;
  • numbers — для відстеження конкретних номерів відправлень;
  • legal — для бізнес-облікових записів, що потребують додаткових даних про компанію;
  • recipientLegal — для відстеження всіх відправлень, що прямують до юридичного клієнта-одержувача;
  • creator — для відстеження всіх відправлень, створених клієнтом, незалежно від того, чи вказаний він як відправник.

Див. розділ Типи підписок.

🔹Номери відправлень під час створення підписки не передаються. Для підписки типу numbers спочатку створіть підписку, а потім додайте номери окремим запитом — див. метод Додати номери до існуючої підписки.

Possible values:
urlstring · uri · min: 3Required

URL зворотного виклику, на який надсилатимуться webhook-сповіщення. Має підтримувати отримання POST-запитів із JSON-навантаженням.

isActivebooleanRequired

Визначає, чи повинна підписка бути активною одразу після створення. Якщо false, підписку буде створено, але webhook-сповіщення не надсилатимуться.

phonestringOptional

Номер телефону, пов’язаний із підпискою. Номер телефону повинен бути в міжнародному форматі.

🔸Обов’язкове, якщо type має значення individual.

eventTypesstring[]Optional

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

Якщо значення не передано, підписка за замовчуванням буде створена для всіх типів подій.

Допустимі значення — див. розділ Типи подій для параметра eventTypes.

sendWarningsbooleanOptional

Визначає, чи потрібно надсилати попередження електронною поштою у разі виникнення проблем із зазначеним webhook URL. Якщо параметр увімкнено, система надсилатиме сповіщення про проблеми доставки або інші помилки.

Default: false
warningEmailstring · emailOptional

Адреса електронної пошти, на яку надсилатимуться попередження щодо проблем із методом. Адреса електронної пошти повинна бути коректною та активною для забезпечення доставки попереджень.

🔸Обов’язкове, якщо sendWarnings має значення true.

sendFullHistoryForMultiParcelbooleanOptional

Визначає спосіб надсилання webhook-сповіщень для багатомісцевих відправлень.

🔹Якщо true, webhook-сповіщення надсилається окремо по кожному місцю відправлення. Структура тіла запиту при цьому не змінюється.

Default: falseExample: false
contentTypestring · enumOptional

Content-Type, з яким надсилатимуться webhook-запити. Підтримувані значення:

  • application/json — рекомендоване значення для нових інтеграцій.
  • text/plain — застаріле значення, підтримку якого буде припинено.

Вибране значення впливає лише на значення заголовка Content-Type. Структура тіла запиту однакова для обох значень.

🔹Якщо contentType не передано, за замовчуванням використовується application/json.

🔸text/plain — застаріле значення, підтримку якого буде припинено. Для нових інтеграцій використовуйте application/json. Якщо ваша підписка наразі використовує text/plain, рекомендуємо перейти на application/json завчасно: тіло запиту при цьому не зміниться, зміниться лише значення заголовка Content-Type.

Default: application/jsonExample: application/jsonPossible values:
companyTinsstring · uuid[]Optional

Список податкових ідентифікаційних номерів компаній, що використовуються для типу підписок legal або recipientLegal. Цей параметр є обов’язковим для юридичних підписок і необхідний для підтвердження особи компанії. Кожен TIN повинен бути коректним UUID.

  • Для legal підписка отримує події лише для відправлень, у яких значення поля sender.companyTin збігається з одним із значень, переданих у полі companyTins.
  • Для recipientLegal підписка отримує події лише для відправлень, у яких значення поля recipient.companyTin збігається з одним із значень, переданих у полі companyTins.

🔸Обов’язкове, якщо type має значення legal або recipientLegal.

secretTokenstring · max: 600Optional

Токен авторизації webhook, який використовується для перевірки вхідних webhook-запитів.

🔸Токен є необов’язковим і, якщо його надано, повинен містити лише латинські літери та цифри, до 600 символів.

Example: k4MzM1NywiZXhwIjoxNzM3Pattern: ^[A-Za-z0-9]+$
secretTokenHeaderNamestring · nullableOptional

Назва заголовка, що використовується для передачі secretToken у webhook-запитах.

Якщо secretTokenHeaderName передано та його значення не є null, його значення використовується як назва заголовка для передачі secretToken.
Якщо secretTokenHeaderName не передано або встановлено значення null, використовується назва заголовка за замовчуванням X-NP-Key.

Вимоги до валідації:

  • Дозволені лише латинські літери, цифри та дефіси.
  • Не повинен починатися або закінчуватися дефісом.
  • Не повинен містити пробіли або будь-які інші спеціальні символи.

🔸Це поле є необов’язковим.

Example: X-Custom-TokenPattern: ^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$
Responses
201

Підписку успішно створено.

application/json
idstringOptional

Унікальний ідентифікатор створеної підписки.

🔸Збережіть значення id — воно необхідне для всіх подальших операцій із цією підпискою.

Example: f5300824-58a9-496b-ac3b-bee156844fdf
typestringOptional

Тип створеної підписки.

Example: numbers
secretTokenstring · max: 600Optional

Токен авторизації webhook, який використовується для перевірки вхідних webhook-запитів.

🔸Токен є необов’язковим і, якщо його надано, повинен містити лише літерно-цифрові символи.

Example: k4MzM1NywiZXhwIjoxNzM3Pattern: ^[A-Za-z0-9]+$
secretTokenHeaderNamestringOptional

Визначає назву HTTP-заголовка, який використовується для передачі secretToken у webhook-запитах.

🔸Якщо поле вказано, назва заголовка повинна складатися лише з латинських літер, цифр і дефісів, не повинна починатися або закінчуватися дефісом, а також не повинна містити пробіли чи інші спеціальні символи.

🔸Це поле є необов’язковим.

Example: X-Custom-TokenPattern: A-Za-z0-9
urlstring · uriOptional

URL зворотного виклику для підписки.

Example: https://api.example.com/webhook
isActivebooleanOptional

Визначає, чи є підписка наразі активною.

Example: true
phonestringOptional

Номер телефону, пов’язаний із підпискою.

Example: 380630000001
cidstringOptional

Унікальний ідентифікатор користувача.

Example: 11a111a1-a1a1-11aa-a111-111111aa1111
eventTypesstring[]Optional

Список типів подій, які буде відстежувати підписка:

  • ReadyToShip: Відправлення створено та готове до відправки.
  • Deleted: Відправлення видалено.
  • ParcelPlaceRemoved: Місце відправлення було видалено з відправлення.
  • Received: Відправлення отримано одержувачем.
  • MoneyTransfer: Створено грошовий переказ, пов’язаний із відправленням.
  • MoneyTransferReceived: Грошовий переказ, пов’язаний із відправленням, виплачено одержувачу.
  • Returned: Відправлення повертається або вже повернуто відправнику.
  • Refused: Одержувач відмовився прийняти відправлення.
  • Redirecting: Відправлення перенаправляється на іншу адресу або у відділення.
  • Utilization: Відправлення утилізовано.
  • Redelivery: Заплановано повторну спробу доставки відправлення.
  • UndeliveryReason: Зафіксовано причину недоставки.
  • ChangeTime: Дату або час доставки було змінено.
  • ArrivalSC: Відправлення прибуло до сортувального центру.
  • TransferToPartner: Відправлення передано партнеру для подальшої доставки.
  • LoadingCourier: Відправлення завантажено до транспортного засобу кур’єра.
  • ArrivalSenderWarehouse: Відправлення прибуло на склад відправника.
  • DepartureSenderWarehouse: Відправлення вибуло зі складу відправника.
  • InCityRecipient: Відправлення прибуло до міста одержувача.
  • AwaitingOnDivision: Відправлення очікує у відділенні або пункті видачі.

🔸Це поле приймає лише типи подій, наведені вище.
Будь-які значення поза цим списком не підтримуються та не повинні передаватися.

Example: ["ReadyToShip"]
sendWarningsbooleanOptional

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

Example: true
warningEmailstring · emailOptional

Адреса електронної пошти, яка використовується для надсилання попереджень.

Example: admin@example.com
sendFullHistoryForMultiParcelbooleanOptional

Визначає спосіб надсилання webhook-сповіщень для багатомісцевих відправлень.

🔹Якщо true, webhook-сповіщення надсилається окремо по кожному місцю відправлення. Структура тіла запиту при цьому не змінюється.

Default: falseExample: false
contentTypestringOptional

Визначає Content-Type, який використовується для тіла webhook-запитів. Значення за замовчуванням — application/json.

Example: application/json
companyTinsstring[]Optional

Список податкових ідентифікаційних номерів юридичної особи, пов’язаної з підпискою.

updatedAtstring · date-timeOptional

Дата та час останнього оновлення підписки.

Example: 2024-02-26T20:08:26.217000Z
createdAtstring · date-timeOptional

Дата та час створення підписки.

Example: 2024-02-26T20:08:26.217000Z
post/tracking-push/subscribers
POST /v.1.0/tracking-push/subscribers HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 372

{
  "type": "numbers",
  "url": "https://api.webhook.test/test_endpoint",
  "isActive": true,
  "phone": "",
  "eventTypes": [
    "ReadyToShip",
    "Received",
    "Returned"
  ],
  "sendWarnings": true,
  "warningEmail": "example@novadigital.com",
  "sendFullHistoryForMultiParcel": false,
  "contentType": "application/json",
  "companyTins": [],
  "secretToken": "k4MzM1NywiZXhwIjoxNzM3",
  "secretTokenHeaderName": "X-Custom-Token"
}
{
  "id": "a866fe22-8134-45c7-bfe9-3cf348415e26",
  "type": "numbers",
  "url": "https://api.somehost.link/endpoint",
  "isActive": true,
  "phone": "",
  "cid": "11a111a1-a1a1-11aa-a111-111111aa1111",
  "eventTypes": [
    "ReadyToShip"
  ],
  "sendWarnings": true,
  "sendFullHistoryForMultiParcel": false,
  "contentType": "application/json",
  "companyTins": [],
  "secretToken": "k4MzM1NywiZXhwIjoxNzM3",
  "secretTokenHeaderName": "X-Custom-Token",
  "warningEmail": "someuser@novadigital.com",
  "updatedAt": "2025-04-14T07:26:20.994000Z",
  "createdAt": "2025-04-14T07:26:20.994000Z"
}

Застарілі параметри

Частина параметрів дублюється у snake_case-написанні. Ці параметри збережено виключно для забезпечення зворотної сумісності — для нових інтеграцій використовуйте варіанти в camelCase.

Застарілий параметр
Використовуйте замість нього

is_active

isActive

event_types

eventTypes

send_warnings

sendWarnings

warning_email

warningEmail

company_tins

companyTins

secret_token

secretToken

secret_token_header_name

secretTokenHeaderName

created_at

createdAt

updated_at

updatedAt

Ці ж застарілі параметри присутні у відповідях на створення та оновлення підписки. Далі в статті вони не повторюються.

ПопередняСписок підписок
НаступнаОновлення підписки

Останнє оновлення