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

Оновлення підписки

Оновити існуючу підписку

put
/tracking-push/subscribers/{id}

Цей метод оновлює дані існуючої підписки, зокрема callback URL, статус активності, типи подій тощо.

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

Метод виконує повну заміну налаштувань, а не часткове оновлення. Параметри, які ви не передасте, буде скинуто. Наприклад, якщо змінити лише url, підписка втратить фільтр eventTypes і почне отримувати webhook-сповіщення за всіма подіями. Завжди передавайте повний набір параметрів, навіть якщо змінюєте один із них.

Тип підписки змінити не можна. Якщо передати в запиті параметр type з іншим значенням, зміна не застосується. Щоб перейти на інший тип, створіть нову підписку й видаліть стару.

Зверніть увагу: події, що відбудуться за час, поки підписка вимкнена, після її повторного ввімкнення не надійдуть.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Унікальний ідентифікатор підписки, яку необхідно оновити. Це обов’язковий параметр шляху, який використовується для визначення підписки, що буде змінена.

Example: a866fe22-8134-45c7-bfe9-3cf348415e26
Body
urlstring · uriRequired

Нова URL-адреса зворотного виклику для webhook-сповіщень. Цей URL повинен бути доступним і підтримувати обробку POST-запитів.

Example: https://api.example.com/updated-webhook
isActivebooleanRequired

Визначає, чи є підписка наразі активною. Встановіть значення true, щоб активувати підписку, або false, щоб деактивувати її.

Example: false
eventTypesstring[]Optional

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

Якщо параметр не передано, фільтр буде скинуто й надходитимуть усі підтримувані події.

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

Example: null
sendWarningsbooleanOptional

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

Example: false
warningEmailstring · emailOptional

Адреса електронної пошти для надсилання попереджень. Це поле є необхідним, якщо параметр sendWarnings має значення true.

Example: admin@example.com
companyTinsstring · uuid[]Optional

Список податкових ідентифікаційних номерів компаній, що використовуються для типу підписок legal або recipientLegal.

  • Для legal підписка отримує події лише для відправлень, у яких значення поля sender.companyTin збігається з одним із значень, переданих у полі companyTins.
  • Для recipientLegal підписка отримує події лише для відправлень, у яких значення поля recipient.companyTin збігається з одним із значень, переданих у полі companyTins.
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:
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
200

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

application/json
idstringOptional

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

Example: a866fe22-8134-45c7-bfe9-3cf348415e26
typestringOptional

Тип підписки, наприклад individual, numbers або legal.

Example: individual
urlstring · uriOptional

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

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

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

Example: false
phonestringOptional

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

Example: 380001234567
cidstringOptional

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

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

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

sendWarningsbooleanOptional

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

Example: false
warningEmailstring · emailOptional

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

Example: admin@example.com
sendFullHistoryForMultiParcelbooleanOptional

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

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

Default: falseExample: false
contentTypestringOptional

Визначає Content-Type, який використовується для тіла webhook-запитів.

Значення за замовчуванням — application/json.

Example: application/json
companyTinsstring[]Optional

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

secretTokenstring · max: 600Optional

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

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

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

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

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

Example: X-Custom-TokenPattern: A-Za-z0-9
updatedAtstring · date-timeOptional

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

Example: 2025-04-14T07:53:38.970000Z
createdAtstring · date-timeOptional

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

Example: 2025-04-14T07:53:38.970000Z
put/tracking-push/subscribers/{id}
PUT /v.1.0/tracking-push/subscribers/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 307

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

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

Частина параметрів дублюється у 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

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

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

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