НАПИ Агент
Автоматизирано подаване към НАП директно от вашия софтуер
НАПИ Агент позволява на счетоводен, ERP или друг бизнес софтуер да подава данни към НАП автоматично, без потребителят да качва файлове ръчно в портала на НАП.
Как вашият софтуер извиква агента
Вашият сървър взима токен
Със секретния ключ за интегратор вашият сървър иска от napi.bg краткотраен токен за конкретна операция и ЕИК. Секретният ключ не се дава на потребителя.
Приложението вика агента
Вашето десктоп или уеб приложение изпраща JSON заявка с токена към НАПИ Агент на същия компютър.
Агентът изпълнява в НАП
Агентът проверява токена, потребителят избира подател и въвежда PIN веднъж, а отговорът от НАП се връща като JSON.
- Токенът е валиден 5 секунди и е за една операция — издавайте нов за всяка заявка. Така не може да бъде използван повторно.
- OpenAPI 3.0 — машинно-четима спецификация; генерирайте клиент за C#, TypeScript, Java, Python и др. с openapi-generator или NSwag.
- Агентът трябва да работи — вижте по-долу как вашият софтуер го стартира с
napiagent://launch. - Готов код за всяка операция на JavaScript, TypeScript, curl, Python, C# и Go в API документацията.
Стартиране на агента от вашия софтуер
При първото си стартиране НАПИ Агент регистрира в Windows и macOS адреса napiagent://. Така вашият софтуер може сам да пусне агента, когато потребителят започне работа.
Проверете дали агентът работи
GET http://127.0.0.1:5123/api/health — ако отговори, агентът е готов.
Ако не работи — отворете napiagent://launch
Системата стартира агента във фонов режим, в трея до часовника. Браузърът първо пита потребителя за разрешение. Ако агентът вече работи, нищо не се случва.
Изчакайте, докато /api/health отговори
След това изпращайте заявките към агента както обикновено.
Интерактивно демо с реален достъп до НАП
Тествайте, без да пишете нито един ред код
Демо страницата е симулация на счетоводен софтуер, който вика НАПИ Агент. От нея можете напълно безплатно, с вашите ключове, да подавате декларации и да четете данни от НАП — с тестов ключ върху примерни данни или с реален ключ върху реалните данни от НАП.
- Всички операции на агента с готови полета за попълване
- Виждате точната заявка, която изпраща софтуерът, и отговора от НАП
- API-то на агента се вика както от десктоп, така и от уеб приложения
- КЕП трябва да е поставен на компютъра — подписването се извършва от служителя, който работи на него
Отвори демото
Тестов и реален режим
Режимът зависи от два ключа: секретния ключ за интегратор от napi.bg, с който вашият софтуер вика агента, и API ключа от НАП, поставен в настройките на агента.
Тестов ключ от napi.bg
Агентът връща реалистични примерни данни за всеки ЕИК — един и същ ЕИК връща едни и същи данни всеки път. Няма обръщения към НАП, без избор на подател и без PIN. Подходящ за изграждане на интеграцията.
Подаване към тестовия сървър на НАП
С реалния ключ от napi.bg агентът работи с НАП, а тестовият API ключ от НАП ↗ насочва подаванията към тестовия сървър на НАП. Агентът разпознава сам вида на API ключа.
Реална работа с НАП
Всички операции — подаване, резултати, справки и изтегляне на файлове — се изпълняват към реалния сървър на НАП с КЕП на потребителя.
Всички операции, групирани по предназначение
Операциите с _batch подават наведнъж всички декларации в избрана папка. Пълният и винаги актуален списък с полетата е в API документацията, която се чете автоматично от openapi.json.
| Подаване на декларации | |
|---|---|
vat · vat_batch | Справка-декларация по ЗДДС и VIES декларация |
dec1_6 · dec1_6_batch | Декларации обр. 1 и 6 |
dec731 · dec736 | Справки по чл. 73, ал. 1 и ал. 6 от ЗДДФЛ |
etz62 · etz62_batch | Електронни трудови записи по чл. 62 КТ |
etz123 · etz123_batch | Електронни трудови записи по чл. 123 КТ |
high_fisc_risk | Превоз на стоки с висок фискален риск |
odit | Стандартизиран одиторски файл (Наредба № Н-18) |
| Резултати от подаването | |
|---|---|
vat_result · dec1_6_result | Резултат за ДДС и за декларации обр. 1 и 6 |
dec731_result · dec736_result | Резултат за справките по чл. 73 |
etz62_result · etz123_result | Резултат за електронните трудови записи |
high_fisc_risk_result · odit_result | Резултат за стоките с висок фискален риск и за одиторския файл |
dec92_submitted · vat_monthly_files | Подадени годишни декларации и ДДС файлове за месец |
| Справки от НАП | |
|---|---|
taxpayers | Задължени лица, до които активният КЕП има достъп |
due_amounts | Дължими суми по ЕИК и период |
debt_payments · debt_payments_types | Задължения и плащания и видовете им |
eetz_business_records | Текущи трудови договори на фирмата |
nap_catalog | Каталог с всички справки и услуги на НАП |
| Файлове и локални помощни операции | |
|---|---|
vat_portal_files · dec1_6_portal_files | Изтегляне на подадените ДДС и декларации обр. 1 и 6 от портала |
etz62_portal_files · etz123_portal_files | Изтегляне на подадените електронни трудови записи |
dec92_document · dec92_pdf | Преглед и PDF на годишната декларация по чл. 92 |
high_fisc_risk_show · save_file | Резултат за стоки с висок фискален риск и запис на файл на диска |
vat_validate · vat_files_parse | Проверка и разчитане на ДДС файловете — без обръщение към НАП |
vat_files_scan · dec1_files_scan · dec6_files_scan | Откриване на декларациите в папка — без обръщение към НАП |
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 сек).