Формати

Документот се праќа како UBL 2.1 XML во телото на POST /api/integration/v1/outbound. Оваа страница кажува кој профил се очекува, кои полиња се задолжителни за документот воопшто да биде примен, и каде се шемата и работниот пример.

1. Профил

UBL 2.1 е широк стандард и дозволува многу повеќе отколку што која било околина навистина чита. Профил е стеснувањето што важи кај нас: кој корен се прифаќа, во кои простори на имиња, и кои полиња мора да ги има документот за воопшто да биде примен. Сè што стандардот го дозволува а профилот не го бара, смее да го има — но не се проверува и не се бара.

Се прима UBL 2.1, во оригиналните простори на имиња на OASIS, со корен Invoice или CreditNote:

Вид	Корен	Простор на имиња
Фактура	`Invoice`	`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2`
Одобрение	`CreditNote`	`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2`

Двата придружни простора се стандардните:

cbc  urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2
cac  urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2

Едно барање носи точно еден документ. Обвивка со повеќе Invoice елементи се одбива со EARH-2011.

Задолжителни полиња

Ова се сите проверки што приемот ги прави. Секоја од нив има своја шифра, и таа шифра се враќа во истиот повик — не подоцна.

Што се бара	Патека во документот	Шифра кога недостасува
ЕДБ на примачот	`cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID`	`EARH-2003`
тоа ЕДБ во исправен облик	истата патека	`EARH-2004`
тип на документот	`cbc:InvoiceTypeCode` · кај `CreditNote`: `cbc:CreditNoteTypeCode`	`EARH-2005`
износ за плаќање	`cac:LegalMonetaryTotal/cbc:PayableAmount`	`EARH-2006`

Издавачот не е задолжителен за приемот — испраќачот се разрешува од клучот, па cac:AccountingSupplierParty смее да носи само име, како во примерокот подолу. ⛔ Но ако впишеш ЕДБ таму, тоа мора да е ЕДБ-то на организацијата на која припаѓа клучот; туѓо ЕДБ се одбива со EARH-2007 во истиот повик.

⚠️ Тоа важи низ целата обработка, не само при приемот. Што документот не го носи за издавачот — ЕДБ, ДДВ број, адреса — се пополнува од твојата организација пред фактурата да замине кон УЈП. Значи блок со само име е доволен.

📌 Матичните податоци на издавачот ги одредува регистарот на УЈП: и кога документот ги носи, името и адресата се усогласуваат со регистрираните пред поднесувањето. Тоа спречува фактура со податоци што не се совпаѓаат со регистарот.

Што се суди	Патека во документот	Шифра кога не се согласува
ЕДБ на издавачот, кога е впишано	`cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID`	`EARH-2007`

Пред нив се проверува и обликот на самото тело — EARH-2001 кога XML-от не е добро обликуван, и EARH-2002 кога коренот не е ниту Invoice ниту CreditNote во горните простори.

Обликот на ЕДБ-то е тринаесет цифри, со или без двобуквен земјин префикс — 4030000000000 и MK4030000000000 се обете исправни, а примач од друга земја со свој префикс исто така поминува.

Постоењето на примачот не се проверува при прием, и не мора да постои однапред: примач што не е заведен партнер се заведува од самиот документ — од името, ЕДБ-то и адресата што ги носи — па обработката продолжува. EARH-4005 останува само за случај кога и тоа не е можно (пр. ЕДБ во неисправен облик што приемот го пропуштил), и се гледа како статус 250, не како одбиено барање.

Даночната исправност исто така не се проверува кај нас — тоа е работа на УЈП, и нејзиниот одговор доаѓа подоцна, како статус на документот. Значи 201 значи „документот е заведен”, не „документот е исправен за УЈП”. Патеката натаму е на страницата Статуси.

Што бара УЈП, а приемот не го проверува

Пред праќањето кон УЈП, фактурата се проверува против полињата што УЈП ги бара. Документ без некое од нив е примен (201), но застанува пред УЈП со статус 250 и EARH-4001, а причината е во validationErrors.

Што се бара	Патека во документот
адреса на примачот — улица, град, поштенски број	`cac:AccountingCustomerParty/cac:Party/cac:PostalAddress` — `cbc:StreetName`, `cbc:CityName`, `cbc:PostalZone`
стапка на ДДВ на секоја ставка, во проценти	`cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent`

Даночната група и индикаторот за УЈП се изведуваат од стапката. Збирот на ДДВ по ставки мора да одговара на cac:TaxTotal/cbc:TaxAmount.

2. Шема

Шемата го опишува профилот опишан погоре — коренот, задолжителните патеки и обликот на износите.

Фајл	Што е
`ubl21-earhiva.xsd`	главната шема — коренот `Invoice`
`ubl21-earhiva-cbc.xsd`	Common Basic Components
`ubl21-earhiva-cac.xsd`	Common Aggregate Components

Главната шема ги увезува другите две по релативна патека, па сите три се преземаат во иста папка. Инаку валидацијата паѓа со неразрешен увоз, а не со наод во документот.

Приемот не врти XSD валидација. Тој ги прави точно шестте проверки од табелата погоре, и ниту една повеќе. Затоа документ што паѓа на шемата — на пример со елемент што профилот не го именува — сепак може да биде примен.

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

⛔ Но шемата не е порта пред УЈП. Тие се две различни мерки: шемата суди облик, УЈП суди содржина. Документ што ја задоволува шемата и понатаму може да застане на 250 со EARH-4001 — на пример без адреса на примачот или без стапка по ставка, зашто во шемата обете се незадолжителни. Списокот што УЈП го бара е во делот погоре.

3. Работни примери

invoice-ubl21.xml е фактура што се прима таква каква е на sandbox серверот — 201 со docUid. Тоа е истиот фајл што го бара чекорот 3 од Quick Start — сними го како invoice.xml во папката од која ја извршуваш командата.

Тој оди и до УЈП, каде застанува со EARH-4002 — примачот во него е измислен. Единственото што ја отвора патеката до крај е подолу.

Содржината на документот е на македонски. Ако компанијата во која тестираш има друг стандарден јазик, земи го invoice-ubl21-en.xml — иста структура, содржина на англиски.

Замени го ова со своето:

Што	Каде
податоците за испраќачот — компанијата од чие име праќаш	`cac:AccountingSupplierParty`
бројот на документот	`cbc:ID`
датумите	`cbc:IssueDate` (задолжителен) и `cbc:DueDate` (незадолжителен — примерокот го носи, смееш и да го тргнеш)
износите и ставката	`cac:TaxTotal`, `cac:LegalMonetaryTotal`, `cac:InvoiceLine`

Не менувај го ова:

трите xmlns декларации на коренот, и самиот корен Invoice
имињата и редоследот на елементите
cbc:InvoiceTypeCode — 380 е фактура
патеката до ЕДБ-то на примачот, и cbc:PayableAmount со неговиот currencyID

Примачот мора да постои кај УЈП. ЕДБ-то во примерот (4030000000000) е измислена вредност во исправен облик. Кај нас тоа не е пречка — примач што не е заведен партнер се заведува од самиот документ — но УЈП го одбива со E1000 „Company NOT Found!: buyer”, што се гледа како 250 со EARH-4002. Замени го со ЕДБ на вистинска компанија.

⛔ За испраќачот не пополнуваш ништо. ЕДБ-то, ДДВ бројот и адресата на издавачот доаѓаат од твојата организација. Ако впишеш ЕДБ на издавач, тоа мора да е ЕДБ-то на организацијата на која припаѓа клучот — туѓо се одбива со EARH-2007 во истиот повик.

⚠️ Ако праќаш за повеќе сопствени фирми, секоја бара своја организација и свој клуч.

Прилог во PDF не е задолжителен. Кога го има, оди како base64 во cac:AdditionalDocumentReference/cac:Attachment/cbc:EmbeddedDocumentBinaryObject со mimeCode="application/pdf"; прилог со друг тип се прескокнува без грешка.