Серија по сценарија

Зошто оваа страница постои

Влезните документи — фактурите што некој друг ги испраќа кон тебе — во вистинска работа ги доставува Управата за јавни приходи. На sandbox серверот ние никогаш не зборуваме со УЈП: тоа е сервер за проба, и ништо од него не заминува кон вистинска институција.

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

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

Каталог на сценарија

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

Три што сам не можеш да ги создадеш

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

Име на сценариото	Во каква состојба е документот	Што прави твојот софтвер кога ќе прати одлука
`deadlinePassed`	рокот за одлука поминал, па УЈП веќе го прифатил документот сам	добива `409` со шифра `EARH-3006`
`alreadyAccepted`	одлуката е веќе донесена и потврдена — документот е прифатен	добива `409` со истата шифра
`alreadyRejected`	истото, но документот е одбиен	добива `409` со истата шифра

⛔ Овие три состојби не настануваат со барање, туку со ТЕКОТ НА ВРЕМЕТО или со дејство што веќе се случило. Затоа не можеш да ги произведеш ниту преку внесување на еден документ, кое секогаш создава документ во почетна состојба.

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

Со каква содржина пристигнува документот

Име на сценариото	Што носи документот
`full`	и машински читлива содржина (UJP JSON) и PDF
`payloadOnly`	само машински читлива содржина, без PDF
`pdfOnly`	само PDF
`noContent`	⛔ ниту едно од двете

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

📌 Кој формат враќа содржина, а кој враќа грешка, е опишано кај Влезни документи → Преземање на содржината. Тоа важи за секој влезен документ, не само за засеаните.

Останати состојби на документот

Име на сценариото	Во каква состојба е документот
`acknowledged`	приемот е веќе потврден, па документот не се враќа кога бараш само непреземени; носи време на потврда
`deadlineToday`	рокот за одлука истекува денес — граничен случај, одлуката сè уште поминува

Износи

Име на сценариото	Каков износ носи
`zeroVat`	ДДВ е нула
`creditNote`	сите износи се негативни
`largeAmount`	износ близу горната граница на форматот

За филтрите при преземање список

Име на сценариото	Што овозможува да пробаш
`secondSender`	филтрирање по даночен број на испраќачот — овој документ носи различен од сите останати
`olderThanWeek`	филтрирање по датум на пристигање, со `by=created`
`updatedRecently`	преземање само на она што се сменило, со `by=updated`

Првото барање

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

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

{
  "seed": 1,           // бројот на серијата што е употребен
  "created": 15,       // колку документи се создадени
  "deleted": 0,        // колку постари засеани документи се избришани; 0 без чистење
  "documents": [
    { "scenario": "full",           "docUid": "eah_i_…", "euid": "SEED-1-full",
      "expect": "format=original и format=pdf враќаат 200; format=ubl враќа 404" },
    { "scenario": "deadlinePassed", "docUid": "eah_i_…", "euid": "SEED-1-deadlinePassed",
      "expect": "POST decision враќа 409 EARH-3006 — рокот поминал" }
    // …и по еден запис за секое останато сценарио
  ]
}

docUid е идентификаторот на документот кај нас. Со него потоа повикуваш GET inbound/{docUid}, GET inbound/{docUid}/file и POST inbound/{docUid}/decision.

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

Телото на барањето има три полиња и ниту едно не е задолжително.

Поле	Тип	Што прави ако го изоставиш
`seed`	цел број	се употребува 1 — не случаен број
`reset`	точно/неточно	ништо не се брише
`scenarios`	список имиња	се создаваат сите сценарија од каталогот

`seed` — бројот на серијата

Ист број дава иста серија. Исти износи, исти датуми, исти испраќачи, исти рокови, во ист редослед.

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

Што праќаш	Што добиваш
`"seed": 1`	серијата број 1
`"seed": 1` повторно	истата серија број 1
`"seed": 2`	друга серија — ако ти треба втора, напоредна
полето изостанато	серијата број 1

`reset` — чистење пред полнењето

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

Со reset: true се бришат фактурите што оваа иста адреса ги создала претходно — и ништо друго.

⛔ Документ што дошол по друг пат остава недопрен. Тоа важи и за фактура што си ја внел преку внесување на еден документ со своја содржина: таа носи твоја содржина и можеби си ја составувал долго.

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

`scenarios` — само дел од каталогот

Кога пробуваш еден случај, не ти треба целата серија:

curl -X POST https://sandbox.api.earhiva.mk/api/integration/v1/sandbox/seed \
  -H "X-Api-Key: <ВАШИОТ КЛУЧ>" \
  -H "X-Software-Id: <ИМЕ И ВЕРЗИЈА НА ВАШАТА АПЛИКАЦИЈА>" \
  -H "Content-Type: application/json" \
  -d '{ "seed": 1, "reset": true, "scenarios": ["deadlinePassed", "alreadyAccepted"] }'

Ако полето го изоставиш, се создаваат сите сценарија.

⛔ Име што не е од каталогот се одбива, и тогаш ништо не се создава. Одговорот е 400 со шифра EARH-2030 и во него стојат дозволените имиња. Печатна грешка нема да создаде половина серија — тоа е состојба што не би ја очекувал и не би ја забележал.

Употреба во автоматски тест

Образецот што го препорачуваме за еден циклус:

1. POST sandbox/seed   { "seed": 1, "reset": true }
     → зачувај го одговорот; тој е очекуваниот резултат за чекорот 3

2. GET  inbound        повлечи ги сите
     → тврди дека бројот на вратени документи се совпаѓа со полето `created`

3. За секој документ од одговорот на чекорот 1:
     GET  inbound/{docUid}
     GET  inbound/{docUid}/file?format=original   → 200 или 404, според сценариото
     POST inbound/{docUid}/decision               → 200 или 409, според сценариото

4. Тврди дека ниту еден одговор не е 500

Чекорот 1 враќа сè што му треба на чекорот 3.

💡 Не го впишувај списокот сценарија во тестот како постојана вредност — прочитај го од одговорот. Тогаш твојот тест останува точен и кога ние ќе додадеме ново сценарио, а тоа додавање не е промена на договорот.

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

Шифра	Кога се појавува
`EARH-2030` · `400`	име во `scenarios` што не е од каталогот. Ништо не се создава; одговорот ги набројува дозволените
`EARH-1008` · `400`	недостасува заглавието `X-Software-Id`
`EARH-1009` · `404`	адресата е повикана на сервер што не е sandbox

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


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

Поврзано

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