Влезни документи

Влезниот документ — оној што некој друг го испратил кон тебе — има свој животен циклус и свој статусен речник. Тој не е продолжение на речникот на излезните документи: двата се одделни, и ниту една шифра не постои во обата.

Првата цифра е насоката, последните две се чекорот

Влезните документи носат 1xx, излезните 2xx. Последните две цифри се истиот чекор во животниот циклус кај обете:

Чекор	Влезни	Излезни
Примен кај нас	110	210
Во обработка	120	220
Испратен кон другата страна	—	230
Прифатен / Испорачан	140	240
Одбиен / Неуспешен	150	250
Сторниран	—	260
Архивиран	170	270
Примен конечен документ од УЈП	180	—

Цртичката е податок, не празнина. Влезен документ ти не го праќаш и не го сторнираш — тоа го прави издавачот, и кај тебе се гледа како состојба на УЈП.

Опсезите се разделени за да не може една иста бројка да значи две работи, ниту меѓу двете листи, ниту спрема шифрите на УЈП — тие се двоцифрени, нашите се трицифрени.

Значи: не пишувај едно пресликување за обете листи. Која листа ја читаш го знаеш од адресата на која си — inbound или outbound.

Статуси на влезниот документ

Колоната Последен статус? кажува дали документот застанува таму засекогаш. „Да" значи дека од тој статус нема каде понатаму — документот повеќе не се менува и нема што да се чека. „Не" значи дека документот сè уште може да се помести, сам или по твое дејство, дури и кога стои во него со денови.

Шифра	Име	Што значи	Последен статус?
110	Примен	Документот пристигна кај нас и е заведен. Тука стои додека некој кај примачот не почне да работи со него — и тука се наоѓа секој документ што сè уште не си го презел.	не
120	Во обработка	Документот е во обработка кај примачот: се чита, се проверува и се подготвува за одлука. Одлуката сè уште не е донесена, па рокот во decisionDeadline и понатаму тече.	не
140	Одобрен	Документот е одобрен. Одлуката е запишана кај нас и се пријавува кон УЈП — запишано не значи потврдено, па статусот не е последен: по потврдата пристигнува конечниот документ од УЈП.	не
150	Одбиен	Документот е одбиен. Одговорот тогаш носи и причина за одбивањето во текст, за да не треба да се бара поддршка за да се дознае што се случило.	не
170	Архивиран резервирана — сè уште не се враќа	РЕЗЕРВИРАНА — бројот е зафатен, состојбата сè уште не постои. Чекорот „архивиран" е ист кај двете насоки (кај излезните е 270); кај влезните доаѓа заедно со конечниот документ од УЈП. Објавена е за да се види дека 140 Одобрен НЕ е последен статус: клиент што го чита како последен престанува да прашува за документ чиј животен циклус сè уште тече.	не
180	Примен конечен документ од УЈП резервирана — сè уште не се враќа	РЕЗЕРВИРАНА — бројот е зафатен, состојбата сè уште не постои. API-то нема да ја врати додека преземањето на конечниот потпишан документ од УЈП не биде испорачано. Тоа е последниот чекор во животниот циклус на влезниот документ.	да

Премини

Зошто 140 Одобрен не е последен статус

Одлуката не е крајот на животниот циклус. По неа документот се архивира кај нас, а УЈП враќа конечен потпишан документ. Затоа во табелата стојат и шифрите 170 и 180, означени како резервирани.

Што значи резервирана	бројот е зафатен, состојбата сè уште не постои
Што прави API-то денес	не ги враќа — ниту еден одговор не носи 170 ниту 180
Зошто се сепак објавени	без нив 140 изгледа како последен статус, па клиент што го прочитал така престанува да прашува за документ чиј животен циклус сè уште тече

Кога состојбата ќе почне да се враќа, тоа ќе биде најавено преку Changelog — како и секое друго проширување.

Одбиен документ носи причина

Кога документот е во 150 Одбиен, одговорот носи и причина за одбивањето во текст. Не треба да се бара поддршка за да се дознае што се случило.

Причината се избира од шифрарникот reject-reasons, кој се чита од GET /codelists/reject-reasons. Истиот шифрарник е тој од кој се зема кодот кога ти одбиваш документ преку POST /inbound/{docUid}/decision.

Рок за одлука — decisionDeadline

Секој влезен документ носи поле decisionDeadline: календарскиот ден до кој документот треба да се одобри или одбие. Кога документот нема поставен рок, полето е null — не измислен ден.

Полето стои и во списокот и во деталот, за да можат документите што сè уште чекаат одлука да се подредат по тоа колку време им останало, без секој да се повлекува во целост.

Рокот е ДАТУМ, не миг и не бројач

decisionDeadline е датум: 2026-09-15. Нема време, нема временска зона, и затоа не зависи од часовникот на оној што го чита.

Одговорот намерно нема поле со преостанати денови. Таква бројка старее внатре во телото: повикувач што го кеширал одговорот преку полноќ би читал број што веќе не важи, без ништо да го пријави. Пресметката е твоја, со твојот часовник — а датумот што ја носи не се менува.

Штом рокот помине, УЈП го прифаќа документот сам. Значи оној што сè уште одлучува мора да го прочита ова поле за да знае колку време му останало. Рокот преживува по одлуката: одлучен документ го задржува својот decisionDeadline — тоа е разликата наспрема причината за одбивање, што излегува само кога документот е одбиен.

Што сум презел и што се сменило

Две работи што личат, а прашуваат различно:

Прашање	Како се бара
„Што не сум презел уште?”	onlyNotImported=true
„Што се сменило од последното повлекување?”	by=updated со dateFrom

Документ што веќе си го презел и што потоа е одобрен се враќа само со by=updated. Тие два не се заменливи; подробно за инкременталното повлекување — Ограничувања и правила.

Преземање на содржината

GET inbound/{docUid}/file ја враќа содржината на документот. Тој бара параметар format, и тој параметар прима точно три вредности:

format	Што враќа	Кога е достапен
original	фајлот онака како што пристигнал, каков и да е неговиот вид	секогаш, ако документот воопшто носи содржина
ubl	содржината како UBL, значи како XML	само ако документот пристигнал во XML
pdf	придружниот PDF	само ако PDF пристигнал со документот

⛔ Ниту еден облик не се создава на барање. Ако документот не пристигнал како XML, ubl враќа 404 — ние нема да го претвориме за да го исполниме барањето. Тоа важи и за pdf.

ubl враќа 404 кај документ што пристигнал како UJP JSON

Голем дел од влезните фактури пристигнуваат како машински читлив UJP JSON, не како XML. За нив format=ubl враќа 404 — и тоа е однесување, не пропуст. Содржината ја земаш со format=original.

Трите исходи и како се разликуваат

Одговор	Шифра	Што значи
200	—	содржината се враќа
404	EARH-3001	нема таков документ, или документот не е твој
404	EARH-3002	документот постои, но не пристигнал во бараниот облик
409	EARH-9003	обликот постоел, а содржината е загубена кај нас

⚠️ EARH-3002 и EARH-9003 личат, а значат спротивни работи. Првата е уредна состојба што твојот софтвер едноставно ја прескокнува: тој облик никогаш не постоел. Втората значи дека постоел и ние сме го загубиле — таму нема што да поправаш во повикот, и вреди да ни се јавиш.

📌 И во двата случаја сè останато за документот се чита нормално: статусот, износите, историјата.

---

Како да добиеш влезни документи за проба

На sandbox серверот твојата организација нема ниту еден влезен документ: тие ги доставува УЈП, а таму кон УЈП не се оди. Затоа постојат две адреси што ја полнат, и тие одговараат на различни прашања:

Кога ти треба	Земи
Сите состојби опишани на оваа страница — вклучувајќи ги оние што сам не можеш да ги создадеш, како истечен рок и веќе донесена одлука	Серија по сценарија
Еден конкретен документ со твоја содржина — на пример фајл од вистински клиент што ти го руши читањето	Една фактура со своја содржина

⛔ Обете постојат само на sandbox серверот.