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

Всички операции минават през POST /api/v1/operations/<typeId>. Authorization: Bearer <JWT> е задължителен за операции, които изискват ЕИК; останалите headers са опционални.

Browser-side flow-ите често нямат удобен начин да запишат файл на диска преди да го подадат — нито искат да го правят. Като алтернатива на X-Napi-File-Path агентът приема съдържанието на файла директно в JSON body-то под един от двата ключа. Базата се декодира в RAII-guard-нат temp път и се изтрива автоматично след handler-а, така че submission кодът не вижда stale файлове и disk-ът остава ограничен.

_inlineFile — единичен файл

За операции с един входен файл (HFR, Д1/Д6, ETZ 62/123, ОДИТ, Дек7.3). Записва се в %TEMP%/napi_<random>_<filename>.

{
  "eik": "131063188",
  "month": 5,
  "year": 2026,
  "fund": "0",
  "_inlineFile": {
    "filename": "dec1_6.txt",
    "contentBase64": "<base64 на TXT файла>"
  }
}

_inlineDir — множество файлове в обща папка

За VAT (изисква deklar.txt + pokypki.txt + prodajbi.txt в една папка) и други multi-file submission-и. Файловете се записват в обща %TEMP%/napi_<random>/ папка, която се подава на operation-а вместо single file path.

{
  "eik": "131063188",
  "month": 5,
  "year": 2026,
  "_inlineDir": {
    "files": [
      { "filename": "deklar.txt",   "contentBase64": "..." },
      { "filename": "pokypki.txt",  "contentBase64": "..." },
      { "filename": "prodajbi.txt", "contentBase64": "..." }
    ]
  }
}

Правила и precedence

• Когато X-Napi-File-Path header-ът присъства, той има предимство — inline ключовете се игнорират.
• В една заявка използвай или _inlineFile, или _inlineDir. Когато и двете са налични, _inlineFile се обработва пръв.
• Filename-ите се санитизират — path separator-и (/ \ : * ? " < > |) се махат за защита от path traversal.
• Temp файловете/папките се изтриват автоматично при излизане от handler-а — без cleanup отговорност за клиента.

Един user-action понякога стартира няколко операции наведнъж — напр. „покажи всички ДДС файлове за 2026 г. и свали PDF-ите" (1× vat_list + N× vat_file), или „подай Дек1/6 + свали входящ номер" (dec1_6_submit → dec1_6_receipt). По подразбиране агентът показва диалог за избор на подател на всяка такава заявка — досадно, когато всички идват от един и същи click. Batch-ът решава точно това.

Как работи

1. В момента на клика frontend-ът генерира GUID: const batchId = crypto.randomUUID();
2. Същият GUID отива в X-Napi-Batch-Id header-а на всяка заявка от поредицата.
3. На първата заявка агентът показва picker-а и запомня избора срещу този GUID за 10 минути.
4. Всички следващи заявки със същия GUID минават мълчаливо с този подател — без диалози.
5. Различен GUID или липсващ header → агентът пита наново.

Сценарии

• Справка + сваляне — списък файлове (1 заявка) + сваляне на всеки (N заявки). Едно потвърждение на подателя за целия батч.
• Подаване + квитанция — submit-операция, после извличане на входящ номер / PDF потвърждение.
• Периодичен синк — твоят backend стартира background задача, която върви през N ЕИК-а с taxpayers_list; всички споделят един batch ID така че потребителят се пита веднъж.

JS пример (browser-side)

// Един клик стартира 1 списък + N сваляния. Всички споделят
// един и същ batchId, така че агентът пита за подател само
// при първата заявка.
async function downloadAllVatFiles(year) {
  const batchId = crypto.randomUUID();   // веднъж на click

  // 1) Списък
  const list = await callAgent("vat_list",
    { typeId: "vat_list", eik: "123456789" },
    { batchId, params: { year } });

  // 2) Парче по парче — същия batchId
  for (const f of list.files) {
    const pdf = await callAgent("vat_file",
      { typeId: "vat_file", eik: "123456789" },
      { batchId, params: { fileId: f.id } });
    saveBlob(pdf);
  }
}

async function callAgent(typeId, jwtReq, { batchId, params }) {
  // "/napi/token" е ТВОЙ endpoint на твоя backend, който вътрешно
  // вика napi.bg/api/v1/tokens/issue със секретния ключ. Това НЕ е
  // endpoint на napi.bg — секретният ключ не трябва да напуска твоя
  // сървър. Виж секцията „Server-side примери" по-горе.
  const { token } = await fetch("/napi/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body:    JSON.stringify(jwtReq),
  }).then(r => r.json());

  const headers = {
    "Authorization": `Bearer ${token}`,
    "Content-Type":  "application/json",
    "X-Napi-Batch-Id": batchId,   // ← същият GUID за цялата серия
  };

  const r = await fetch(`http://127.0.0.1:5123/api/v1/operations/${typeId}`, {
    method: "POST", headers, body: JSON.stringify(params)
  });
  if (!r.ok) throw new Error(`agent ${r.status}: ${await r.text()}`);
  return r.json();
}

Браузърите по сигурност не дават 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":   "TXT файлове (*.txt);;Всички файлове (*)" }

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

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

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

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

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

Пример: избор на файл и подаване към dec1_6

Типичен сценарий — потребителят натиска бутон „Подай Дек1/6", браузърът извиква /api/pick-file за да получи пълен път, после го подава като X-Napi-File-Path header към операцията. Същият pattern важи и за /api/pick-folder при операции, които приемат директория.

async function submitDec16(jwt) {
  // 1) Отвори native OS file dialog
  const pickRes = await fetch("http://127.0.0.1:5123/api/pick-file", {
    method:  "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      startDir: "C:/Declarations",
      filter:   "Дек1/6 TXT (*.txt);;Всички файлове (*)"
    })
  });
  const { path } = await pickRes.json();
  if (!path) return;   // потребителят отказа диалога

  // 2) Извикай операцията със selected path в headera
  const opRes = await fetch("http://127.0.0.1:5123/api/v1/operations/dec1_6", {
    method:  "POST",
    headers: {
      "Authorization":    `Bearer ${jwt}`,
      "Content-Type":     "application/json",
      "X-Napi-File-Path": path,        // ← пълен път от picker-а
    },
    body: JSON.stringify({ eik: "123456789", year: 2026, month: 3 })
  });
  if (!opRes.ok) throw new Error(`agent ${opRes.status}: ${await opRes.text()}`);
  return opRes.json();   // submission result
}

Пример: избор на папка (вход за обработка)

async function pickInputFolder() {
  const r = await fetch("http://127.0.0.1:5123/api/pick-folder", {
    method:  "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ startDir: "C:/Declarations" })
  });
  const { path } = await r.json();
  return path || null;   // null когато потребителят отказа
}