НАПИ Агент — интеграция за софтуерни доставчици
Документация за интеграция на НАПИ Агент във вашия продукт — счетоводен софтуер, ERP или онлайн услуга. По-долу: архитектура, примери за извикване и стъпки за достъп.
Две независими части
Интеграцията е разделена на две части: издаване на JWT във вашия backend и извикване на агента от браузъра. Секретният ключ (napi_test_… / napi_live_…) остава само на сървъра — никога във frontend код.
- OpenAPI 3.0 + SDK генерация — машинно-четима спецификация; генерирайте клиент за C#, TypeScript, Java, Python и др. с openapi-generator или NSwag.
- JWT живее 5 секунди — издавайте нов за всяка операция, не кеширайте. Краткият TTL е защитата срещу replay.
- Server-side примери — curl, Node.js, C#, Python, PHP; изложете JWT-а на frontend-а чрез вътрешен endpoint.
- Live example — интерактивен преглед на всяка операция, зареден автоматично от openapi.json, с код на JavaScript, TypeScript, curl, Python, C#, Go.
Стойностите за typeId съвпадат с операциите в openapi.json (напр. vat, dec1_6, debt_payments, taxpayers).
Защо интеграцията е сигурна
Headers, batch операции и file picker
| Header | Предназначение |
|---|---|
Authorization: Bearer <JWT> | Задължителен за операции, които изискват ЕИК. |
X-Napi-Sender-Id | Идентификатор на подател от настройките на агента. При липса и повече от един конфигуриран подател — агентът показва picker. |
X-Napi-File-Path | Абсолютен път до файл/папка за операции с локален вход (напр. dec1_6). Обикновено идва от /api/pick-file или /api/pick-folder. Алтернатива за browser-flow: _inlineFile / _inlineDir в JSON body-то. |
X-Napi-Batch-Id | Опционален GUID за multi-step бутони — диалогът за потвърждение се показва само на първата заявка; следващите със същия GUID минават мълчаливо до 10 минути. JWT-ът остава per-операция. |
POST /api/pick-file и POST /api/pick-folder — отварят native OS диалог и връщат пълния път (без JWT, timeout 600 сек).
От тестов ключ до безсрочен договор — 3 фази
Фаза 1 · Тестване и интеграция
Регистрация в napi.bg и генериране на секретен ключ от профила. Инсталирайте агента на машината на потребителя — Windows или macOS. Ключ за разработка: тестов — 90 дни; реален преди договор — 7 дни, до 3 ЕИК-а. Без лимит на брой издадени ключове; email уведомление 24 ч. преди изтичане.
Фаза 2 · Сключване на договор
Заявка за интегратор с данните на фирмата → преглед от администратор (цена за ЕИК, срок и клаузи се определят индивидуално; датата на одобрение става дата на договора) → имейл с попълнен договор → потвърждение с чекбокс „Прочел съм и съм съгласен" и сваляне на копие.
Фаза 3 · Неограничен достъп
Безсрочни ключове + месечно таксуване по условията в договора. Email уведомление 7 дни преди изтичане на договора или при прекратяване.