Една фактура со своја содржина

Кога ти треба оваа адреса

POST sandbox/inbound внесува еден влезен документ во твојата организација, со содржина што ти ја задаваш.

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

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

Оваа адреса или серијата по сценарија

Двете адреси на sandbox серверот одговараат на различни прашања. Ниту едната не ја заменува другата.

	Оваа страница `POST sandbox/inbound`	Серија по сценарија `POST sandbox/seed`
Прашањето	„еве го овој документ, стави ми го”	„дај ми ги сите состојби”
Содржината ја задава	ти, поле по поле	ние, по каталог
Колку документи создава	еден	цела серија
Состојби како истечен рок или веќе донесена одлука	⛔ не може да ги создаде	✅ ги дава готови

⛔ Документот што оваа адреса го создава е секогаш во ПОЧЕТНА состојба. Рокот за одлука е во иднина и по него нема донесена одлука — зашто тие состојби настануваат со текот на времето или со дејство што веќе се случило, не со поле во барањето.

Ако ти треба документ во некоја од нив, тоа е серијата по сценарија.

Најкраткото барање

Задолжително е само documentNumber. Сè друго има разумна стандардна вредност.

curl -X POST https://sandbox.api.earhiva.mk/api/integration/v1/sandbox/inbound \
  -H "X-Api-Key: <ВАШИОТ КЛУЧ>" \
  -H "X-Software-Id: <ИМЕ И ВЕРЗИЈА НА ВАШАТА АПЛИКАЦИЈА>" \
  -H "Content-Type: application/json" \
  -d '{ "documentNumber": "0001" }'

{
  "docUid": "eah_i_01M1BVN00S4GDT718V8SA9A7QR",  // идентификаторот кај нас
  "euid": "SBX-7F3A4B2C9D1E5A8B0C3D",            // генериран, зашто не пративме свој
  "alreadyExisted": false
}

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

⚠️ Тоа не е недовршен внес. Така изгледа документ кога кај УЈП недостасува овластување за преземање на содржината — вистинска состојба, вредна за проба.

Со твоја содржина

payload и pdfBase64 се независни едно од друго. Може да пратиш само едно, обете, или ниту едно.

curl -X POST https://sandbox.api.earhiva.mk/api/integration/v1/sandbox/inbound \
  -H "X-Api-Key: <ВАШИОТ КЛУЧ>" \
  -H "X-Software-Id: <ИМЕ И ВЕРЗИЈА НА ВАШАТА АПЛИКАЦИЈА>" \
  -H "Content-Type: application/json" \
  -d '{
        "euid": "MOJ-TEST-001",
        "documentNumber": "2026-000412",
        "docDate": "2026-09-01",
        "sellerName": "Добавувач ДООЕЛ",
        "sellerTin": "MK4030995155258",
        "docNetAmount": 10000.00,
        "docVatAmount": 1800.00,
        "docGrossAmount": 11800.00,
        "payload": "{ …UJP JSON… }",
        "pdfBase64": "JVBERi0xLjQK…"
      }'

📌 Кој облик од содржината потоа се презема со кој format, е опишано кај Влезни документи → Преземање на содржината.

Полињата на барањето

Поле	Задолжително	Што значи	Ако го изоставиш
`documentNumber`	✅ да	бројот на фактурата, онака како што издавачот ја издал	барањето се одбива
`euid`	не	идентификаторот што УЈП му го дава на документот	се генерира, со префикс `SBX-`
`docDate`	не	датум на издавање	денешниот датум
`docDeliveryDate`	не	датум на промет	истото што и `docDate`
`sellerName`	не	име на компанијата што ја издала фактурата	останува празно
`sellerTin`	не	даночен број на таа компанија	останува празно
`docNetAmount`	не	износ без ДДВ	`0`
`docVatAmount`	не	износ на ДДВ	`0`
`docGrossAmount`	не	вкупен износ	`0`
`payload`	не	машински читливата содржина, како UJP JSON	документот нема таква содржина
`pdfBase64`	не	PDF-от, запишан во base64	документот нема PDF

Како да го направиш повикот повторлив

Ако пратиш свој euid, истата вредност двапати не создава втор документ. Вториот повик го враќа постојниот:

{ "docUid": "eah_i_…", "euid": "MOJ-TEST-001", "alreadyExisted": true }

Одговорот и тогаш е 201, не 409 — разликата ја носи полето alreadyExisted, за да не мораш да гранкаш по HTTP статусот. Тоа е истиот избор како кај повторена ознака за идемпотентност при праќање документ.

Грешки што оваа адреса ги враќа

Шифра	Кога се појавува
`EARH-2030` · `400`	недостасува `documentNumber`, или `pdfBase64` не е исправен base64
`EARH-1008` · `400`	недостасува заглавието `X-Software-Id`
`EARH-1009` · `404`	адресата е повикана на сервер што не е sandbox

Што оваа адреса НЕ прави


Создава само влезни фактури	излезната насока се проба со вистински `POST outbound`
Работи само во твојата организација	ниту еден повик не гледа и не менува во туѓа
Ништо не заминува кон УЈП	ниту при создавањето, ниту кога ќе донесеш одлука
Документот е во почетна состојба	истечен рок и веќе донесена одлука не може да се зададат — за нив е серијата по сценарија
Нема чистење	документите се бришат само преку `reset` на серијата, а тој не ги допира твоите

Поврзано

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