Формати

Внимание

Сите примери на оваа страница важат само за demo околината sandbox.earhiva.mk.

Документот се праќа како 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

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

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

Што приемот НЕ го проверува

Постоењето на примачот не се проверува при прием. ЕДБ во исправен облик што не води до познат примач е примен документ; ако примачот не може да се разреши подоцна, тоа се гледа како статус 50 со EARH-4005, не како одбиено барање.

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

2. Шема

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

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

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

Шемата е опис на профилот, не портата на приемот

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

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

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

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

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

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

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

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

ЕДБ-то на примачот во примерот (4030000000000) е измислена вредност во исправен облик и поминува на demo околината без да води до вистински примач. Ако сакаш да пратиш кон одреден примач, замени го — обликот останува ист.

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