API Нової Пошти, monobank і Checkbox: інтеграція

Інтеграція з Новою Поштою, monobank, Checkbox і платіжними шлюзами прибирає ручне перенесення даних між сайтом, CRM, обліком і сервісами, якими бізнес користується щодня. Накладні створюються з замовлення, статус посилки приходить покупцю сам, виписка банку розноситься в облік, а чеки кас звіряються з виручкою.

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

Нова Пошта

API Нової Пошти працює через одну адресу, на яку надсилається запит з API-ключем, назвою моделі і методу. Ключ відправник отримує в особистому кабінеті.

Типові сценарії:

• Пошук міста і відділення у формі оформлення. Метод пошуку населених пунктів і метод списку відділень з фільтром за номером або вулицею. Покупець обирає зі списку, і адреса завжди коректна.
• Створення експрес-накладної з замовлення в CRM або обліку.
• Відстеження. Статус за номером накладної, місто і відділення отримувача, планова і фактична дата доставки.
• Сповіщення покупцю про відправлення і прибуття.
• Накладений платіж: звірка отриманих сум з замовленнями.

У нашій платформі агентів конектор до Нової Пошти вміє відстежувати посилку, шукати населений пункт і отримувати відділення міста. Агент підтримки відповідає на «де моя посилка» за номером накладної без участі менеджера.

Пастки:

• Довідники міст і відділень великі і змінюються. Кешуйте їх і оновлюйте за розкладом.
• Розширений статус посилки потребує телефону відправника або отримувача.
• Помилки API приходять у тілі відповіді з ознакою неуспіху, а код HTTP при цьому може бути успішним. Перевіряйте ознаку в тілі.

monobank

Персональний API дає власнику рахунку, зокрема ФОП, доступ до рахунків, балансів і виписки за токеном з особистого кабінету API.

• Виписка запитується за період до 31 доби.
• Для частини методів діє жорсткий ліміт частоти: один запит на хвилину. Тому інформацію про клієнта і виписку забирайте за розкладом, зберігайте у себе і не звертайтесь до API на кожен показ сторінки.
• Для отримання нових операцій одразу можна зареєструвати вебхук.

Еквайринг monobank для бізнесу дає створення рахунку на оплату, статуси і повідомлення про оплату на ваш сервер з підписом, який перевіряється ключем банку.

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

Checkbox

Checkbox це програмний РРО. Його API дає доступ до кас, змін, чеків і звітів.

• Для роботи потрібні ключ ліцензії каси і вхід касира, після якого сервер отримує токен доступу. Токен варто кешувати на час його дії і входити заново лише після того, як він сплив.
• Можна перевірити, чи відкрита зміна, отримати чеки і Z-звіти.

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

Друга деталь: дата чека і дата зарахування еквайрингу на рахунок різні. Дохід точки ми рахуємо за датою фіскального чека, а гроші між терміналом і рахунком показуємо окремим станом «еквайринг у дорозі». Так виручка дня сходиться з касою, а гроші сходяться з банком.

Платіжні шлюзи

Для онлайн-оплати на сайті чи в боті використовуються WayForPay, LiqPay, еквайринг monobank та інші. Логіка схожа:

1. Сервер створює платіж з сумою і номером замовлення.
2. Покупець платить на сторінці шлюзу.
3. Шлюз надсилає повідомлення на ваш сервер з підписом.
4. Сервер перевіряє підпис і змінює статус замовлення.

Уроки з платформи турнірів. На платформі серії падел-турнірів гравці оплачують участь через WayForPay, а адміністратор сам робить повернення і заміну пар.

• Код «повернення в обробці» означає прийняте повернення. Одного разу шлюз узяв повернення в роботу і відповів кодом 1138, а наш код порахував це відмовою. Друга спроба отримала «Invalid Amount», бо повернення вже йшло. Тепер такий код записується як повернення зі станом «шлюз обробляє», кожна невдала спроба лишає слід у журналі, а окрема кнопка звіряє стан зі шлюзом.
• Повернення в обробці ще не гроші на картці. Шлюз повертає кошти з балансу мерчанта, і поки суми там немає, повернення висить. Система перевіряє такі повернення за розкладом.
• Оплата в Mini App. Усередині Telegram форму оплати ми не відкриваємо. Сервер видає одноразове посилання на оплату, дійсне 20 хвилин, і Telegram відкриває його в зовнішньому браузері.

Тестові середовища

Частина сервісів дає тестовий режим або тестові ключі, частина працює лише з бойовими даними. План перевірки залежить від цього.

• Платіжні шлюзи зазвичай мають тестові картки або тестовий мерчант. Проганяйте на них оплату, відмову, повернення і повторне повідомлення.
• Служби доставки дозволяють створювати накладні, які можна видалити до передачі посилки. Тестові накладні видаляйте одразу після перевірки.
• Банківські API для виписок працюють з реальним рахунком. Для перевірки використовуйте рахунок з невеликою кількістю операцій і режим лише читання.
• Каси перевіряються на тестовій касі або касі в тестовому режимі, щоб не створювати фіскальних чеків.

Спільні правила для всіх інтеграцій

• Ключі лише на сервері і в сховищі секретів, ніколи в коді сторінки чи репозиторії.
• Ідемпотентність. Повторне повідомлення про ту саму оплату або повторний імпорт того самого чека має давати той самий результат.
• Журнал кожного запиту і відповіді з часом і причиною помилки.
• Повтори з паузами при збоях мережі.
• Ліміти частоти кожного API враховані в розкладі.
• Сповіщення адміністратору, коли обмін зупинився.

Покроковий план

1. Перелічіть сценарії: що звідки і куди має йти.
2. Отримайте ключі і тестові доступи, де вони є.
3. Визначте, де зберігаються дані і як часто оновлюються.
4. Зробіть обмін з журналом і повторами.
5. Прогоніть реальні випадки: повернення, часткова оплата, скасування, повторне повідомлення.
6. Запустіть і перевірте звірку за перший тиждень.

Чек-лист

• Помилки API перевіряються і за кодом, і за тілом відповіді.
• Повторне повідомлення не створює другу оплату.
• Z-звіт замінює підсумок чеків зміни.
• Ліміти частоти враховані.
• Ключі відсутні в коді сторінки.
• Збій обміну видно в журналі і в сповіщенні.

Що замовити

Інтеграції з сервісами доставки, банками і касами ми робимо в напрямі автоматизація бізнес-процесів, а якщо дані мають іти в облікову систему, в напрямі інтеграція з BAS і 1С. Опишіть у формі заявки, які сервіси і системи треба звʼязати, і після брифу ми повернемось з планом і оцінкою за робочий день.