Документация за разработчици

Интеграцията е разделена на две независими части: издаване на JWT в твоя backend и извикване на агента от браузъра. Секретният ключ остава само на сървъра — никога в frontend код.

OpenAPI 3.0 + SDK генерация

Машинно-четима спецификация на всички 16 операции на агента. Генерирайте client SDK за вашия език (C#, TypeScript, Java, Python, …) с openapi-generator или NSwag.

Изтегли openapi.json Изпробвай в Демо

npx @openapitools/openapi-generator-cli generate \
    -i https://napi.bg/api/v1/openapi.json \
    -g csharp \
    -o ./napi-agent-sdk

Помощни endpoint-и на агента (file / folder picker)

Браузърите по сигурност не дават absolute path през <input type="file">. Агентът предоставя два помощни POST endpoint-а, които отварят native OS диалог и връщат пълния път — удобно когато операцията очаква път до файл/папка (напр. dec1FilePath в dec1_6). Тези endpoint-и са извън typed /api/v1/operations/* повърхността и не изискват JWT.

POST `http://127.0.0.1:5123/api/pick-file`

{ "startDir": "C:/Declarations",
  "filter":   "XML файлове (*.xml);;Всички файлове (*)" }

→ 200 { "path": "C:/Declarations/dec1_2026_03.xml" }

POST `http://127.0.0.1:5123/api/pick-folder`

{ "startDir": "C:/Declarations" }

→ 200 { "path": "C:/Declarations" }

При отказан диалог се връща {"path": ""} с HTTP 200. Диалогът блокира HTTP handler-а докато потребителят затвори прозореца — заявката има timeout 600 секунди.

Live example (автоматично от openapi.json)

Избери операция от dropdown-а. Ако нищо не се зарежда: /api/v1/openapi.json трябва да е достъпен.

SERVER-SIDE — backend-ът ти издава JWT

Тези endpoint-и се викат от твоя backend (C# / Python / Node / PHP / Go). Секретният ключ napi_test_… или napi_live_… остава тук — никога не достига до браузъра.

POST /api/v1/tokens/issue

Обменете секретен ключ за кратък JWT, обвързан с конкретна операция и ЕИК. Issuer-ът проверява разрешените ЕИК-ове, минималната версия на агента и при тестов ключ слага test: true в JWT-а.

POST /api/v1/tokens/issue HTTP/1.1
Host: napi.bg
Authorization: Bearer napi_test_XXXXXXXXXXXXXXXXX
Content-Type: application/json

{
  "typeId": "vat",
  "eik":    "123456789"
}

→ 200 OK
{
  "token":      "eyJhbGciOiJSUzI1NiIs...",
  "jti":        "a3f6b9...",
  "expiresAt":  "2026-04-27T12:34:56Z",
  "issuer":     "napi.bg"
}

→ 401   невалиден / revoked / expired секретен ключ
→ 402   изчерпан лимит на ЗЛ за този ключ (по подразбиране 3 ЗЛ
        за реален ключ без подписан договор; admin override
        чрез ApplicationUser.MaxEiksOverride; неограничен след
        signed contract; тестовите ключове не са лимитирани)
→ 400   липсва eik в заявката