Шифри од УЈП

Кога документот стигнува до УЈП, одговорот на УЈП доаѓа со свои шифри. Тие никогаш не се појавуваат во нашиот каталог на грешки — тој ги носи само шифрите EARH-xxxx, кои се наши.

Обете тврдења се точни, и заедно значат дека шифра од УЈП нема каде да се прочита во каталогот. Оваа страница е тоа место.

Оваа страница ЦИТИРА, не толкува

Текстот на УЈП стои како што е даден од нив. Ние не го преведуваме, не го скратуваме и не му даваме друго значење. Ако УЈП го смени описот, тука ќе стои новиот.

Каде се појавуваат

Деталот на излезен документ носи блок ujp:

Поле	Што е	Кога е пополнето
euid	идентификаторот што УЈП ѝ го доделил на фактурата при прифаќање	веднаш штом УЈП ја прифати
qrLink	врската за QR кодот, онака како ја вратил УЈП — втисни ја таква каква што е	веднаш штом УЈП ја прифати
state	состојбата што ја пријавува УЈП, со нивниот речник	при читање на состојбата од УЈП
code	шифрата што УЈП ја враќа кога одговорот е одбивање; null кога нема таква	при одбивање, веднаш
message	текстот што УЈП го враќа, на нивниот јазик. Не е стабилен — не пишувај услов врз него	при одбивање, веднаш
checkedAt	кога последен пат сме го прочитале тој одговор	при читање на состојбата од УЈП

Блокот е null додека документот сè уште не е проследен до УЈП.

⛔ Прифатена фактура носи само euid и qrLink; останатите четири се null. УЈП при прифаќањето враќа идентификатор и врска, не состојба — state и checkedAt се пополнуваат подоцна, кога состојбата ќе се прочита. Дека фактурата е примена го кажува euid, не state.

Статусот кај нас и одговорот на УЈП се два одвоени податока

Нашиот статус кажува докаде е документот кај нас. Блокот ujp кажува што рекла УЈП. Едното не се пресметува од другото и не се прикажува наместо него.

Најлесно се мешаат кај EARH-4002: таа шифра значи дека УЈП го одбил документот — кај нас статусот тогаш е 250 Неуспешен — а вистинската причина е шифрата и описот во блокот ujp.

Мапирањето го прави eArhiva.mk

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

При праќањето не проверуваме дали ознаките внатре во документот се познати. POST outbound гледа само дали документот е структурно исправен — валиден UBL, еден документ, ЕДБ во исправен облик. Ознаките се разрешуваат подоцна, кога обработката го мапира документот кон УЈП.

⚠️ Затоа 201 не значи дека ознаките се во ред. Ако некоја од нив нема мапирање кај таа компанија, тоа се гледа подоцна — од status и failureCode на документот, не како одбивање на самото праќање.

Едно исклучение — причината за одбивање

RejectReasonCode во POST decision оди дословно: тој код нема мапирање и мора да е активен запис во шифрарникот reject-reasons. Погрешен код се одбива со EARH-2022. Тоа е единственото место каде внесуваш шифра на УЈП директно.

Пресликување UBL → полиња на УЈП

Ова е целото пресликување: секоја патека што конверторот навистина ја чита, и полето кај УЈП во кое завршува. Сè што не е во табелата не се чита — без разлика дали е исправно по UBL и дали има вредност.

UBL патека	Поле кај УЈП
cbc:ID	header.docNumber
cbc:IssueDate	header.docDate
cbc:DueDate	docPayment.docPaymentTypeDueDate
cbc:DocumentCurrencyCode	docPayment.docCurrencyCode
cbc:Note	header.docNotes
cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name	seller.sellerName
cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID	seller.sellerTin
…SupplierParty/…/cac:PostalAddress/cbc:StreetName	seller.sellerAddress.streetAddress
…SupplierParty/…/cac:PostalAddress/cbc:CityName	seller.sellerAddress.city
…SupplierParty/…/cac:PostalAddress/cbc:PostalZone	seller.sellerAddress.postalCode
…SupplierParty/…/cac:PostalAddress/cac:Country/cbc:IdentificationCode	seller.sellerCCode
cac:AccountingCustomerParty/cac:Party/cac:PartyName/cbc:Name	buyer.buyerName
cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID	buyer.buyerTin
…CustomerParty/…/cac:PostalAddress/cbc:StreetName	buyer.buyerAddress.streetAddress
…CustomerParty/…/cac:PostalAddress/cbc:CityName	buyer.buyerAddress.city
…CustomerParty/…/cac:PostalAddress/cbc:PostalZone	buyer.buyerAddress.postalCode
…CustomerParty/…/cac:PostalAddress/cac:Country/cbc:IdentificationCode	buyer.buyerCCode
cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount	docTotals.docNetAmount
cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount	docTotals.docGrossAmount
cac:LegalMonetaryTotal/cbc:PayableAmount	docTotals.docFinalAmount
cac:TaxTotal/cbc:TaxAmount	docTotals.docVatAmount
cac:InvoiceLine/cac:Item/cbc:Name	docItems[].docItemDesc
cac:InvoiceLine/cbc:InvoicedQuantity	docItems[].docItemQty
cac:InvoiceLine/cbc:InvoicedQuantity/@unitCode	docItems[].docItemMUnit
cac:InvoiceLine/cac:Price/cbc:PriceAmount	docItems[].docItemUnitPriceWoVat
cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent	docItems[].docItemVat

Уште три патеки се читаат, но не завршуваат во поле кај УЈП — влегуваат како твои ERP шифри, па оттаму минуваат низ мапирањето на организацијата кон шифрарникот на УЈП:

UBL патека	ERP шифра
cbc:InvoiceTypeCode · кај CreditNote: cbc:CreditNoteTypeCode	тип на документот
…SupplierParty/…/cac:PostalAddress/cac:Country/cbc:IdentificationCode	држава на продавачот
…CustomerParty/…/cac:PostalAddress/cac:Country/cbc:IdentificationCode	држава на купувачот

⛔ Значи 380 не е шифрата што стигнува до УЈП: 380 е шифра од UBL стандардот, 100 е шифра на УЈП („Фактура”), и патот меѓу нив минува низ мапирањето на твојата организација — местото каде за еден тип на УЈП може да има една или повеќе твои шифри. Кај двете држави мапирање по правило не е потребно: шифрарникот за држави носи ISO двобуквени шифри, па MK поминува такво какво е. Кои твои шифри се веќе мапирани кон одреден запис се гледа во erpCodes — в. подолу.

Три работи што НЕ се читаат од документот

1 · Начинот на плаќање. Не постои патека што води до него — ни cac:PaymentMeans/cbc:PaymentMeansCode, ни описот. Значи нема потреба да го праќаш, и вредност од UNCL4461 (30) или од шифрарникот payment-types (P1x) нема да пристигне ниту да помогне.

2 · Името на државата. Се чита само кодот — cac:Country/cbc:IdentificationCode (MK) — не cbc:Name.

3 · Даночната група и даночниот индикатор. Обете се изведуваат од стапката по ставка (cbc:Percent), преку шифрарниците на УЈП. Не ги праќај и не ги погодувај.

⚠️ Кога документ ќе падне, екранот за рачна корекција набројува десетина „задолжителни” полиња. Тој список е барање на тој екран — местото каде документ се довршува рачно — не барање на интеграцискиот API. Документ што поминува до УЈП не носи дел од тие полиња. Меродавно за API-то е она што е во оваа табела и во делот „Што бара УЈП” на страницата Формати.

Што од ова е задолжително го суди проверката пред поднесување; таа враќа статус 250 со EARH-4001, а поединечните причини доаѓаат во validationErrors со шифри EARH-5001…EARH-5012. Списокот што најчесто недостасува — адреса на примачот и стапка по ставка — е на страницата Формати.

Живиот извор — GET /codelists/{type}

Шифрарниците на УЈП се читаат преку интеграцискиот API, за твојата околина и твојата компанија:

Шифрарник	Што носи
document-statuses	состојбите на документот кај УЈП — тоа што стои во ujp.state
reject-reasons	причините за одбивање — оттаму е кодот што ти го праќаш во POST decision, и оттаму доаѓа причината кога документот е одбиен
void-reasons	причините за сторнирање

Тоа е меродавниот извор, не оваа страница. Списоците се менуваат кај УЈП и се читаат по околина; она што е тука е снимка со датум. Кога двете се разликуваат, точен е одговорот на GET /codelists/{type}.

Нов запис во шифрарник не е промена што го крши договорот — ниту една шифра не се брише и ниту една не го менува значењето.

Важењето се суди спрема датумот на ДОКУМЕНТОТ

Одговорот по основа ги враќа записите важечки денес. Но при поднесување важењето се суди спрема cbc:IssueDate на фактурата — значи заостаната фактура може да падне на шифра што денес е важечка.

Затоа секој запис носи и validFrom и validTo (празни кога записот нема такви датуми), а денот може да се зададе изречно:

GET /codelists/tax-indicators?asOf=2026-02-18

asOf е календарски датум, yyyy-MM-dd; изостанат значи денес. Датум што не може да се прочита се одбива со EARH-2020.

⚠️ Ова важи за сите шифрарници, не само за даночните индикатори. Најчесто се забележува кај tax-indicators и tax-groups, зашто таму стапките се менуваат со законски рокови.

erpCodes кажува што од твоето е мапирано кон тој запис

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

Тоа е начинот да провериш однапред дали твоја вредност ќе помине — особено за типот на документот, каде 380 од UBL-от е твоја шифра, а не шифра на УЈП. Ако erpCodes за записот 100 („Фактура”) не го носи 380, додај го мапирањето во веб делот, или прати ја шифрата што е веќе мапирана.

Состојби на документот кај УЈП

Снимка од шифрарникот document-statuses, 29.08.2026:

Шифра	Име	Опис на УЈП
00	Нацрт	е-Фактури што се креирани, но не се финални и не се пратени кон примачот
01	Испратена (Нова)	е-Фактура издадена од Издавачот кон Примачот, потпишана, валидирана и снимена во системот
03	Прифатена	е-Фактура издадена од Издавачот кон Примачот и Прифатена од страна на Примачот
04	Автоматски прифатена	Автоматски прифатена по истек на рок
05	Одбиена	е-Фактура издадена од Издавачот, примена од Примачот и Одбиена со соодветно образложение/причина
06	Автоматски одбиена	Автоматски се одбива ако примачот не ја прифати или одбие во законски предвидениот рок
07	Сторнирана	е-Фактура примена или одбиена од Примачот, но Сторнирана од Издавачот (со претходна потврда од Примачот)
09	Корегирана	Корегирана
10	Евидентирана	Евидентирана во систем
11	Откажана	е-Фактура издадена кон Примачот, но пред да биде Прифатена или Одбиена е Откажана од самиот Продавач

Шифрите на УЈП се ДВОЦИФРЕНИ, нашите се трицифрени

Тоа не е случајно. Нашите статуси се 1xx за влезните и 2xx за излезните токму за да не може бројка од оваа табела да се помеша со бројка од нашата: 10 тука значи Евидентирана кај УЈП, а нашиот најблизок статус е 210 Примен.

Сепак читај ја секоја вредност од своето поле: status е нашиот, ujp.state е нивниот. Нивниот е текст, не број — шифрарникот на УЈП носи водечка нула (01, 03, 09).

Причини за одбивање и сторнирање

Тука намерно нема табела. Списоците reject-reasons и void-reasons се читаат по околина и се менуваат кај УЈП; препишани тука, тие би застарувале тивко — а грешен код при одбивање се одбива со EARH-2022, што е поскапо од едно повикување.

Земи ги живо:

• GET /codelists/reject-reasons
• GET /codelists/void-reasons

Одговорот носи code и name за секој активен запис — истите вредности што ги употребуваме и ние внатрешно.