Skip to main content
Status: live (MVP). 1 MCP tool у production: tracking за TTN. Address-book (пошук міст, довідник відділень) — у roadmap (Phase 2).

​
Чому Нова Пошта

  • Структурний монополіст UA-логістики (~70% ринку посилкових перевезень). Якщо твій бізнес продає на території України — ймовірність що клієнти отримують замовлення через НП ≈ 100%.
  • Public REST API (api.novaposhta.ua/v2.0/json/), frozen since 2014 — sunset risk близький до нуля.
  • Use case clear: AI-агент відповідає на запити клієнтів про статус посилки без перемикання у НП кабінет, готує дайджест “відправлено сьогодні / прибуло / на отриманні”.

​
Підключення

  1. Отримай Nova Post API key: кабінет НП → Налаштування → Безпека → API ключі → “Створити новий ключ”. Зазвичай ~40 символів.
  2. app.brama.work → Integrations → Nova Post → встав API key.
API key зберігається envelope-encrypted (AES-256-GCM), ізольовано per-tenant. Кожен tenant бачить лише свої посилки. Brama не має спільного НП-акаунта — Bring-Your-Own.
НП API key прив’язаний до counterparty (юр. особа / ФОП у твоєму НП-кабінеті). Якщо у тебе кілька counterparty — у Brama сьогодні підключаєш лише один; Phase 2 розгляне multi-counterparty якщо буде запит.

​
MCP tools (live)

brama_novapost_track

Tracking посилок UA за TTN (express waybill number).Параметри:
  • documents (required) — масив посилок; кожен елемент:
    • document_number (required) — TTN, 14 цифр (наприклад 20450012345678)
    • phone (optional) — телефон отримувача (380660000000); якщо НП підтвердить, повертає додаткові поля
Повертає: для кожної TTN — status + status_code, status_found (boolean), city_sender / city_recipient, warehouse_sender / warehouse_recipient, date_created, scheduled_delivery_date, actual_delivery_date, document_weight, document_cost, payment_method / payment_status / amount_to_pay, afterpayment_cost, service_type, cargo_type, cargo_description, seats_amount.
Якщо TTN не знайдено — NP повертає status_code: "1" зі статусом "Номер не знайдено" і status_found: false. Це не помилка, а звичайна реакція vendor’а на невідомий номер. Не треба retry — повідом користувачу і йди далі.
Use: “де моя посилка з TTN …”, “які з 10 посилок вже прибули”, “статус оплати наложеного платежу за TTN X”.

​
Phase 2 (coming soon)

Address-book endpoints — додамо коли надійде перший запит від tenant’а:
  • brama_novapost_search_settlements — пошук міст / селищ за назвою → Ref UUID
  • brama_novapost_get_warehouses — перелік відділень / поштоматів для міста
  • brama_novapost_get_warehouse_types — типи відділень (відділення, поштомат, вантажне)
Блокер — у novapost-sdk ці endpoint’и поки що без typed-обгорток; SDK PR потрібен перед інтеграцією.

​
Створення відправлень / зміна (Phase 3)

Write-tools (create_document, update_document) потребують додаткового шару безпеки (confirmation у MCP-клієнті перед витратою грошей tenant’а на TTN, audit-log, idempotency keys). Будуть розглянуті після того, як буде стабільний read-only досвід в реальних tenant’ах.