Технички водич за интеграција со системот е-Фактура

Овој водич е наменет за:

• програмери,
• ИТ-менаџери,
• ERP компании,
• и тимови што развиваат сметководствен софтвер.

Во продолжение ќе ги разгледаме:

• архитектурата на системот е-Фактура,
• UBL XML форматот,
• API комуникацијата,
• дигиталниот потпис,
• и преминот од тест во продукциска околина.

Сите примери се поедноставени за полесна читливост.

Како функционира системот

Системот на УЈП функционира како централен hub за размена на електронски фактури.

Издавачот испраќа фактура преку API, УЈП ја валидира и потпишува со временски печат, а потоа документот станува достапен за примателот.

Процесот:

1. Издавачот креира UBL XML во својот софтвер
2. Документот се потпишува со дигитален сертификат на издавачот
3. Се испраќа преку HTTPS POST до API endpoint на УЈП
4. УЈП валидира формат, ДДВ броеви и потписи
5. Се враќа уникатен идентификатор (EUID) и QR код
6. Примателот добива нотификација и пристап до документот

Секоја размена е логирана и нема можност за повлекување. Сторно фактури се правен документ со посебен код.

UBL 2.1 формат на документ

Документот следи UBL 2.1 стандард, усогласен со европската норма EN 16931. Тоа значи дека истиот формат се користи и во Италија, Германија и други земји во ЕУ.

Минимални обврзни полиња:

• cbc:ID: број на фактура
• cbc:IssueDate: датум на издавање
• cbc:DocumentCurrencyCode: валута (MKD, EUR, USD)
• cac:AccountingSupplierParty: податоци за издавачот
• cac:AccountingCustomerParty: податоци за примателот
• cac:InvoiceLine: ставки со количина, цена, ДДВ
• cac:TaxTotal: вкупен ДДВ по стапки
• cac:LegalMonetaryTotal: вкупни износи

Скратен пример:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>ФАК-2026-000001</cbc:ID>
  <cbc:IssueDate>2026-10-01</cbc:IssueDate>
  <cbc:DocumentCurrencyCode>MKD</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>...</cac:AccountingSupplierParty>
  <cac:InvoiceLine>...</cac:InvoiceLine>
</Invoice>

API повици и автентикација

Главни endpoints:

Endpoint	Метод	Опис
/invoices/submit	POST	Праќа потпишана фактура
/invoices/{euid}	GET	Презема статус и податоци
/invoices/incoming	GET	Листа на влезни фактури
/invoices/{euid}/accept	POST	Прифаќа влезна фактура
/invoices/{euid}/reject	POST	Одбива влезна фактура

Автентикацијата е во два слоја:

1. OAuth 2.0 токен добиен преку дигитален сертификат
2. XML потпис на самиот документ со XAdES стандард

Токенот трае 24 часа. Препорачано е кеширање и автоматско обновување. Секој повик мора да биде преку HTTPS со TLS 1.2 или повисок.

Дигитален потпис на документот

Потписот се прави според XAdES-BES профил, на самиот UBL документ пред испраќање. Без валиден потпис, УЈП ќе го одбие повикот со грешка 401.

Чекори за потпишување:

1. Канонизација на XML преку C14N
2. Пресметка на SHA-256 hash
3. Шифрирање со приватниот клуч од сертификатот
4. Вградување на <ds:Signature> блок во документот

Често користени библиотеки:

• PHP: robrichards/xmlseclibs
• .NET: вградени класи System.Security.Cryptography.Xml
• Java: Apache Santuario
• Python: signxml

Тестирајте го потписот преку UJP валидаторот пред да испратите вистинска фактура. Грешен потпис е најчестата причина за одбиени документи.

Од тест до продукција

Преминувањето во продукција не е автоматско. Бара завршување на формална регистрација и преглед од страна на УЈП.

Контролна листа пред продукција:

• Успешно поминати минимум 50 тест фактури различни типови
• Имплементиран retry механизам за привремени грешки
• Логирање на сите HTTP повици со timestamp и EUID
• Backup стратегија за непотпишани документи во чек
• Тестиран сторно процес и кредитни белешки
• Време на одговор под 5 секунди по фактура

Препораки за продукциско работење:

• Идемпотентни повици со уникатен request_id header
• Rate limiting од страна на клиентот, максимум 60 повици во минута
• Алертинг за HTTP 5xx грешки и неуспешни потписи
• Архивирање на испратените XML документи 10 години локално

Продукциската регистрација опфаќа потпишување договор со УЈП, доделување продукциски токени и финален преглед на интеграцијата. Планирајте најмалку 4 недели за оваа фаза.