> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brama.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Nova Post

> Tracking посилок Нової Пошти UA – read-only MVP.

<Note>
  **Status: live (MVP).** 1 MCP tool у production: tracking за TTN. Address-book (пошук міст, довідник відділень) – у roadmap (Phase 2).
</Note>

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

* Структурний монополіст 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.

<Tip>
  НП API key прив'язаний до **counterparty** (юр. особа / ФОП у твоєму НП-кабінеті). Якщо у тебе кілька counterparty – у Brama сьогодні підключаєш лише один; Phase 2 розгляне multi-counterparty якщо буде запит.
</Tip>

## MCP tools (live)

<Card title="brama_novapost_track" icon="package">
  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`.

  <Warning>
    Якщо TTN не знайдено – NP повертає `status_code: "1"` зі статусом `"Номер не знайдено"` і `status_found: false`. Це **не помилка**, а звичайна реакція vendor'а на невідомий номер. Не треба retry – повідом користувачу і йди далі.
  </Warning>

  Use: "де моя посилка з TTN ...", "які з 10 посилок вже прибули", "статус оплати наложеного платежу за TTN X".
</Card>

## 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'ах.