е-Фактура API

Животен циклус на документ

Статус

Секоја EInvoice и InboxDocument носи стабилен јавен status, преземен од внатрешната состојба и статусниот код на УЈП:

Статус	Значење
`validating`	Во ред за чекање, сè уште не е изграден.
`invalid`	Не поминал валидација — видете `problems`.
`awaiting_signature`	Се чека вашиот агент за потпишување (Merot Bridge или SDK-агент за потпишување).
`queued`	Валидиран и потпишан, чека слот за поднесување или прекин кај УЈП да заврши.
`submitting`	Отворен е обид за поднесување.
`held`	Прекин кај УЈП — во ред за повторно поднесување во законскиот рок.
`delivered`	УЈП статус `01` — испратена, се чека одлука на купувачот.
`accepted`	УЈП статус `03` — купувачот експлицитно прифатил.
`auto_accepted`	УЈП статус `04` — молчење по рокот; УЈП тоа го смета за прифаќање.
`rejected`	УЈП статус `05`.
`cancelled_by_storno`	УЈП статус `07`.
`corrected`	УЈП статус `09`.
`registered`	УЈП статус `10`.
`draft_at_ujp`	УЈП статус `00`.
`failed`	Крајна грешка — видете `problems`.

GET /v1/einvoices/{id}/status-history ја враќа целата хронологија на статусни настани.

Крајниот рок за прифаќање/одбивање на влезна е-фактура

Влезна е-фактура мора да биде прифатена или одбиена најдоцна до 10-ти од месецот по датумот на трансакцијата. Ако не преземете ништо, УЈП молчењето го смета за прифаќање (auto_accepted). InboxDocument.decideBy е тој краен рок (вклучително), а daysLeft го брои времето до него — претплатете се на webhook-от inbox.deadline_approaching (се испраќа на 5, 2 и 1 ден пред рокот) наместо постојано да проверувате.

POST /v1/inbox/{id}/accept
POST /v1/inbox/{id}/reject   { "reasonCode": "O-3", "comment": "Стоката не е примена" }

Прифаќањето не бара причина; одбивањето бара код за причина од шифрарникот на УЈП (O-1…O-7). По истек на рокот, и двете враќаат 409 decision_deadline_passed — фактурата е веќе автоматски прифатена.

УЈП сè уште не го има потврдено ова

Дали крајниот рок до 10-ти од месецот се поместува кога паѓа во сабота, недела или празник, сè уште не е потврдено од УЈП. Имплементацијата на Merot засега не го поместува — проверувајте ги промените откако УЈП ќе појасни.

Сторно и корекција

Двете создаваат нов документ што реферира на оригиналот преку EUID — оригиналот никогаш не се менува.

Сторно (POST /v1/einvoices/{id}/storno) — целосно поништување: docStorno: 1, причина за сторно од шифрарникот на УЈП (S-x), негативни износи на ставките. Дозволено само од состојбите delivered, accepted или auto_accepted.
Корекција (POST /v1/einvoices/{id}/correction) — целосна замена: docStorno: 2, причина за корекција (C0x) и целосен заменски документ.

Двете се блокирани со 409 period_closed откако ќе биде поднесена годишната сметка на компанијата за таа година (полето annualAccountFiledFor го поставувате вие штом сметководителот ви ја поднесе — Merot нема друг начин да дознае).

Поднесување до УЈП

За разлика од Payroll API, кој генерира датотеки што самите ги качувате кај УЈП, е-Фактура API поднесува документ до УЈП вместо вас — тоа е целата негова цел. Она што никогаш не го прави е да го чува вашиот клуч за потпишување: секој документ се потпишува на вашиот уред (Merot Bridge) или на ваш сопствен сервер (SDK-агент за потпишување), пред Merot да го препрати до УЈП. Видете Потпишување: Режим А наспроти Режим Б.