е-Фактура API

Потпишување: Режим А наспроти Режим Б

Квалификуваниот електронски потпис мора да се создаде на уредот на самиот сопственик на сертификатот — клуч чуван на серверот е најмногу напреден потпис, никогаш квалификуван. Затоа овој API нема режим „испратете ни го вашиот сертификат”. Наместо тоа, секој документ кон УЈП го потпишува агент за потпишување што вие го хостирате, а кој одржува излезна конекција кон Merot и потпишува краткотрајни барања за потпишување.

Режим А — Merot Bridge (стандардно)

Merot Bridge е десктоп апликација за Windows, macOS и Linux. Комуницира со вашиот токен или паметна картичка преку PKCS#11 (со резервна опција CNG за Windows), ви покажува што точно се потпишува, и потпишува локално — вашиот приватен клуч никогаш не го напушта уредот. Ова е вистинскиот избор за бизниси и сметководствени бироа што имаат некој на работно место да потврди потпис, и е усогласено од првиот ден на сите три оперативни системи.

Режим Б — SDK-агент за потпишување

Ако имате сопствен сервер (типично за софтверски куќи), SigningWorker од TypeScript или C# SDK-то се поврзува како агент на истиот начин како Bridge, користејќи PKCS#11 токен/HSM или PFX сертификат на тој сервер. Не е потребна десктоп апликација. Ова го задржува сертификатот на инфраструктура што ја контролирате вие, но имајте предвид: PFX датотека е напреден потпис освен ако самиот уред што го чува е сертифициран QSCD (на пр. HSM) — прашајте го вашиот издавач на сертификати што бара вашиот сертификат.

Забелешка

Нема Режим В. Хостиран сертификат — Merot да го чува вашиот клуч за потпишување — не се нуди, и нема да се нуди освен ако УЈП не потврди дека е-печат на правно лице или далечинско квалификувано потпишување е прифатливо за JWS потписи на е-Фактура.

Како функционира барањето за потпис

Merot го гради документот, ја пресметува точната содржина за потпишување JWS (заглавие + содржина), и — ако регистрираниот потписник е со чувар (custody) bridge или sdk — создава барање за потпишување наместо самиот да го потпише. Е-фактурата останува во awaiting_signature.
Вашиот агент го прима барањето преку отворената конекција (wss://, со long-poll резервна опција), сам ја парсира содржината (никогаш не верува само на резимето на Merot), и — за пишување (испраќање, сторно, корекција, прифаќање/одбивање) — бара од вас потврда, освен ако не сте се пријавиле за неприсутно потпишување за таа инсталација. Читањата (проверка на статус, листа, PDF, …) се потпишуваат автоматски штом агентот е отклучен.
Агентот го враќа потписот назад (POST /v1/signing-requests/{id}/signature). Merot го проверува спрема вашиот регистриран сертификат пред нешто да се испрати до УЈП.
Барањата за потпис истекуваат по 240 секунди (во рамки на 300-те секунди прозорец на самиот УЈП); истечено барање тивко се заменува со ново, без да се смета за неуспешен обид.

Спарување (pairing)

Во конзолата, генерирајте 8-карактерен код за спарување (важи 10 минути, еднократна употреба) и внесете го во Merot Bridge или проследете го до SigningWorker. Агентот добива сопствен Ed25519 клуч на уредот, чуван во вашиот системски трезор (DPAPI/Keychain/libsecret) — откриен тајн клуч на агентот сам по себе е бескорисен без него.

Неприсутно потпишување

Стандардно, секое пишување бара човек да потврди на Bridge. Сопственик на сметка може да ја пријави инсталацијата за неприсутно потпишување (сервер-режим) за целосно автоматизирани текови на работа — ова се ревидира, а агентот сепак одбива сè што излегува надвор од очекуваната содржина за наведената намена.