Інтеграція з Нова Пошта

Інтеграція дає змогу створювати накладні Нової Пошти прямо з документів QUINCEFIN і відстежувати їхній статус.

Щоб почати роботу, виконайте такі кроки:

1. Створити профіль і налаштувати параметри підключення Нової Пошти
2. Створити замовлення або документ продажу
3. Створити на підставі замовлення або продажу накладну НП

Важливо: перед створенням профілю перевірте основну адресу відправлення в кабінеті Нової Пошти або створіть актуальну адресу.

Створення профілю

Для цього переходимо в налаштування системи, розділ “Інтеграції”

Обираємо “Нова пошта” - Створити

У вікні інтеграції треба заповнити всього два поля:

Вкладка “Підключення”

Назва профілю - буде відображатись у списку інтеграцій

АРІ ключ - скопіювати у вашому кабінеті Нової Пошти

Якщо ключа АРІ немає, його треба створити в кабінеті Нової Пошти:

Після заповнення ключа, треба натиснути на кнопку Перевірити ключ

Якщо ключ успішно пройшов перевірку, то автоматично у картці інтеграції заповнюється інформація з кабінету Нової Пошти:

• Контактна персона - якщо таких контактних персон декілька, то є можливість вибору контактної персони в профілі інтеграції
• Телефон
• ЄДРПОУ/ДРФО

І залишається заповнити порожні поля:

• Населений пункт - заповниться автоматично після вибору адреси нижче
• Звідки відбувається відправка - тут треба обрати актуальну адресу зі списку доступних. Вона буде підставлятись, як адреса відправки у всіх ТТН. Цей список заповнюється з відділень, поштоматів чи адрес, що додані у особистому кабінеті Нової Пошти в розділі * Налаштування/Мої адреси .

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

Для юридичних осіб адреса відправки в профілі вибирається із адрес в особистому кабінеті НП. Контактна особа підтягується із кабінета НП.

Тепер профіль можна зберегти і створювати ТТН прямо з облікової системи Quincefin.

Вкладка “За замовчуванням”

Тут можна вказати параметри, які за замовчуванням будуть підставлятись у всі нові накладні НП

• Опис відправлення - можна прописати короткий опис про товари
• Вага (кг)
• Довжина (см)
• Ширина (см)
• Висота (см)

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

Список шаблонів можна створити на сторінці інтеграції і далі обирати потрібний під час створення накладної.

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

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

Створення накладної

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

Створити накладну можна зі списку відповідних документів або з відкритого документа.

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

Натискаємо на кнопку “Створити на підставі” і обираємо Нова пошта

Документ складається з загальної інформації і вкладок з детальними даними про відправку.

Номер - унікальний порядковий номер документу у системі

Дата/Час - коли створено цей документ

Документ підстава - замовлення, рахунок або продаж, на підставі якого створено цю накладну

Номер накладної НП - заповниться автоматично після створення у кабінеті НП

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

Сценарій “Замовлення → ТТН”

1. Створіть або відкрийте замовлення покупця.
2. Перевірте партнера, телефон, контактну особу і адресу доставки в замовленні або картці партнера.
3. Натисніть Створити на підставі → Нова пошта.
4. У накладній перевірте профіль Нової Пошти, отримувача, тип доставки, відділення або адресу.
5. Заповніть вагу й габарити, перевірте оголошену вартість і параметри післяплати. Якщо замовлення отримано через API з даними Нової Пошти, адреса й післяплата можуть уже бути заповнені.
6. Створіть ЕН, щоб передати дані в кабінет Нової Пошти.

Якщо у покупця кілька контактних осіб або адрес, перевірте вкладку Адреси перед створенням ЕН. Автозаповнення допомагає перенести дані з документа-підстави, але відповідальність за коректну адресу й телефон перед відправкою лишається за користувачем.

Адреса й післяплата із замовлення сайту

Якщо сайт створює замовлення через order/add, він може передати в цьому самому замовленні блок NovaPoshta: місто, відділення або поштомат і суму післяплати. Менеджер далі створює продаж і ТТН у звичному порядку, а форма накладної використовує дані цього замовлення.

Сценарій потребує версії QUINCEFIN із підтримкою блоку NovaPoshta в API замовлень та налаштованого профілю Нової Пошти.

Для розробника інтеграції: поля, приклади та правила оновлення в API замовлень.

Що передає сайт

• CityRef — ідентифікатор міста Нової Пошти, а WarehouseRef — ідентифікатор відділення або поштомата в цьому місті. Назви можна передати додатково. Пункт отримання визначається за ідентифікаторами, а не лише за назвою.
• CODAmount — сума в гривнях, яку потрібно отримати за товар під час вручення. Сайт сам розраховує її як суму замовлення мінус передоплата; якщо замовлення повністю оплачено, передає 0.
• CODMode — MoneyTransfer для Грошового переказу або PaymentControl для Контролю оплати. Якщо режим не вказано, використовується Грошовий переказ.
• CODPayer — Recipient або Sender: хто оплачує послугу грошового переказу. За замовчуванням це отримувач. Параметр не змінює платника за доставку й застосовується тільки до Грошового переказу.

Наприклад, для замовлення на 1 500 грн із передоплатою 250 грн сайт передає післяплату 1 250 грн. QUINCEFIN підставляє саме передану суму. Це не створює документ оплати й не змінює взаєморозрахунки або оголошену вартість відправлення.

Дані зберігаються окремо для кожного замовлення. Один покупець може мати замовлення з різними відділеннями, і для цього не потрібно змінювати його картку партнера. Звичайний текст у полі DeliveryAddress не замінює блок NovaPoshta для автозаповнення форми ТТН.

Як менеджеру створити ТТН

1. Відкрийте замовлення, створене сайтом. Якщо відвантаження оформлюється через продаж, створіть Продаж на підставі цього замовлення, щоб зберегти зв’язок документів.
2. У замовленні або його продажі натисніть Створити на підставі → Нова пошта.
3. На вкладці Адреси перевірте отримувача, населений пункт і пункт отримання. Тип Відділення або Поштомат визначається автоматично за довідником Нової Пошти; адреса замовлення має пріоритет над адресою партнера.
4. Перевірте режим і суму післяплати. Для Контролю оплати потрібен профіль відправника типу Організація з відповідним договором NovaPay. Якщо профіль несумісний, форма показує попередження: виберіть потрібний профіль або вимкніть цей режим.
5. Заповніть або перевірте профіль відправника, вагу, габарити, оголошену вартість та інші обов’язкові поля. Створіть ЕН, як і для накладної, заповненої вручну.

Передавання NovaPoshta через API зберігає інструкції до замовлення. Відправлення в кабінеті Нової Пошти створюється лише після дії менеджера у формі ТТН.

Коли післяплату потрібно визначити вручну

Для ввімкненого режиму післяплати сума має бути більшою за нуль. Одночасно вмикати Грошовий переказ і Контроль оплати не можна. Розподіл суми між частинами замовлення менеджер визначає самостійно.

Перевірка враховує збережені документи на момент відкриття форми. Якщо кілька працівників одночасно відкрили незбережені ТТН для одного замовлення, узгодьте суми перед створенням ЕН: відкриті форми не резервують частину післяплати.

Що відбувається після зміни замовлення

Інтеграція може оновити дані доставки через order/update. Пропущений блок NovaPoshta залишає попередні дані, переданий об’єкт замінює блок повністю, а NovaPoshta: null очищає інструкції доставки цього замовлення. Для опублікованих замовлень діють звичайні обмеження API на редагування.

Оновлені дані використовуються під час створення наступної ТТН. Уже збережена накладна та ручні зміни в ній не перезаписуються під час повторного відкриття. Якщо блок не передавався, залишається звичайне заповнення з картки партнера або вручну.

Відображення статусів НП

Після створення та оновлення накладної система показує статус Нової Пошти не лише в самій картці накладної, а й у пов’язаних списках документів.

Для компактного відображення використовуються короткі alias статусів у вигляді кольорових тегів. Наприклад:

• Отримано - зелений тег
• В дорозі - синій тег
• На відділенні - бірюзовий тег
• У поштоматі - бірюзовий тег

Такі теги відображаються:

• у списку НП-накладних
• у картці НП-накладної
• у списках Замовлення, Рахунки та Продажі в колонці Статус НП

Короткий текст у тегу використовується для швидкого читання списку, а повна назва статусу Нової Пошти показується в tooltip при наведенні курсора.

Колонка Статус НП у списках Замовлення, Рахунки та Продажі є керованою: її можна показувати або приховувати через стандартні налаштування колонок у відповідному журналі.

Як ТТН відображається у замовленнях і продажах

ТТН НП прив’язується до документа, з якого фактично оформлено відправлення. Часто це Замовлення: товар уже передано Новій Пошті, але Продаж ще не створено, бо покупець може не забрати посилку або відмовитися від неї. Наявність ТТН не означає, що продаж уже відбувся.

У списку Замовлення відображається статус ТТН, прив’язаних безпосередньо до цього замовлення.

У списку Продажі в колонці Статус НП показуються номер ТТН і статус за такими правилами:

• якщо до продажу прив’язано власну ТТН, показується саме її номер і статус;
• якщо власної ТТН немає і продаж не створено із замовлення, інформація про ТТН не показується;
• якщо продаж створено із замовлення, сума та склад товарів із кількостями повністю збігаються, а в замовлення є одна активна ТТН, продаж показує номер і статус цієї ТТН;
• якщо продаж містить лише частину замовлення, склад товарів або кількості відрізняються, або до замовлення прив’язано кілька ТТН, у номері й статусі буде напис Кілька ТТН.

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

Детальніше: документ “Замовлення” і документ “Продаж”.

Пошук за зворотною ТТН

Після отримання зв’язку повернення від Нової пошти у версії QUINCEFIN з підтримкою зворотних ТТН можна знайти Замовлення або Продаж за номером на повернутій посилці. Відскануйте 14 цифр у поле Пошук за коментарем та номером, відкрийте потрібний продаж і створіть на його підставі повернення від покупця.

Дані надходять під час планового оновлення або після натискання Оновити статуси відправлень у списку накладних Нової пошти. Первинний номер ТТН залишається незмінним; облікове повернення ви оформлюєте самостійно.

Покроково: зворотна ТТН — пошук продажу та повернення товару.

Вкладка “Відправлення”

Тип відправлення - треба обрати зі списку:

• Посилка
• Документи
• Палети (у розробці)
• Шини-диски (у розробці)

Опис відправлення - стисла інформація про вантаж, що буде відправлено

Оголошена вартість - вартість вантажу

Габарити і вага пакунку - обов’язкові для заповнення. Для посилок, які мають неправильну геометричну форму (позначає відсутність кутів 90 градусів та плоских сторін) є можливість проставити позначку «Ручна обробка»

Якщо у відправлення декілька пакунків - то ці дані слід заповнити для кожного.

Платник за доставку - обрати зі списку:

• Отримувач - заповнюється за замовчуванням. Дані про телефон, ПІБ та тип доставки на вкладці “Адреси” заповнюються автоматично з картки партнера, якщо ці дані попередньо було заповнено.
• Відправник
• Третя особа

Форма оплати за доставку:

• Готівка
• Безготівка

Необов’язкові поля:

• Внутрішній номер відправлення
• Супроводжуючі документи
• Промокод
• Номер пакування
• Додаткова інформація про відправлення

Вкладка “Адреси”

Отримувач

• Приватна особа
• Організація
• Телефон
• Прізвище
• Ім’я
• По батькові

Тип доставки

• Відділення
• Адреса
• Поштомат
• Цифрова адреса

Адреса

Номер відділення/Поштомату

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

Підйом на поверх - ця опція стане доступною, якщо в полі тип доставки обрано адресу.

Грошовий переказ — один із режимів післяплати. Увімкніть його, якщо кошти за товар потрібно отримати грошовим переказом, і вкажіть суму та платника послуги переказу. Якщо дані надійшли через API замовлення, режим і сума можуть бути заповнені автоматично.

Пакування - включити, якщо до оплати додано пакування посилки.

Контроль оплати — режим післяплати з перерахуванням коштів на рахунок за договором NovaPay. Для нього потрібен профіль НП із типом відправника Організація та відповідний договір. Використовуйте один режим: Грошовий переказ або Контроль оплати.

Для ввімкненого режиму вкажіть Суму — скільки отримувач має сплатити за товар під час отримання. Для повністю оплаченого замовлення вимкніть обидва режими.

У режимі Грошовий переказ також виберіть платника за пересилання коштів:

• Отримувач
• Відправник

Вкладка “Додатково”

Тут можна обрати відповідального менеджера та підрозділ вашої організації для зручного фільтрування документів у журналах та звітах.

Після заповнення обов’язкових полів, можна створити ЕН.

Для цього натиснути на кнопку у верхній частині документу.

В цей момент документ не тільки проводиться у обліковій системі, але і дані потрапляють до вашого кабінету Нової пошти.

Де тепер створено і пронумеровано накладну на відправлення.

І таким чином у документі заповнюється номер накладної.

Ці дані можна перевірити в кабінеті НП у розділі Мої посилки/Чернетки

Якщо при створенні ЕН Нової Пошти виникне помилка, то на екрані з’явиться відповідне повідомлення.

Прив’язка вже існуючої ТТН Нової Пошти до документа

Окремо від стандартного створення ЕН додано сценарій для випадків, коли ТТН НП вже створена, але не пов’язана з замовленням.

У списку документів замовлення/рахунку/продажу доступна опція:

• Вибрати ТТН з документів QFin - відкрити список неприв’язаних ТТН і обрати потрібний запис.

Прив’язка через вибір з документів QFin

1. Натисніть Вибрати ТТН з документів QFin.
2. У формі пошуку відфільтруйте список за Номер, НомерНП, Партнера або Телефоном одержувача.
3. Оберіть потрібну ТТН НП і натисніть Оберіть.

Обмеження:

• у списку доступні лише неприв’язані ТТН НП;
• ТТН уже прив’язана до іншого документа не буде переназначена автоматично.

Автоматична прив’язка при імпорті замовлень

Для інтеграцій Shopify, SalesBox, Horoshop, Prom.ua, Kasta, Rozetka, KeyCRM додано автоматичну синхронізацію за номером ТТН.

Після імпорту замовлення:

• якщо вивантажений запис містить номер ТТН НП (Tracking Number / NP number), система намагається синхронізувати dlvr.NpNotes;
• якщо є неприв’язана ТТН із цим номером - вона автоматично прикріплюється до замовлення;
• якщо не знайдено, створюється мінімальний запис ТТН НП з номером, але без дублювання API-створення накладної.

Важливо: поле Номер ТТН у друкованих та транспортних документах у QUINCEFIN - це не номер накладної Нової Пошти. Номер Нової Пошти зберігається саме в полі Номер накладної НП документа НП-накладна.