Ограничувања и правила

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

Правила

Правило	Вредност
граница на сообраќај	по клуч; бројката ја носи планот
големина на документ	по организација; кровот го носи планот
страничење	100 стандардно, 500 највеќе
редослед на список	најнов прв
инкрементално повлекување	by=updated + nextFrom
прозорец на идемпотентност	еден час
чекање на одговорот при праќање (Prefer: wait)	најмногу 30 секунди

Граница на сообраќај

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

• Еден клуч од повеќе сервери дели иста квота. Ако истиот клуч го употребуваат три инстанци на твојот производ, нивните барања се собираат во иста бројка. Границата не се множи со бројот на сервери.
• Повеќе клучеви зад иста излезна адреса НЕ делат квота. Ако два твои клиенти работат од иста мрежа и излегуваат преку иста адреса, секој од нив има своја бројка. Едниот не може да ја потроши квотата на другиот.

Кога границата ќе се исполни, барањето се одбива со EARH-1006 · 429 и се повторува по времето што го кажува заглавието Retry-After — не се менува ниту клучот ниту адресата.

Колку изнесува бројката

Бројката не е иста за сите. Неа ја носи планот на организацијата чиј е клучот, а сопственикот на клучот може да ја спушти уште подолу за тој конкретен клуч. Важи помалото од двете.

План	Барања во минута
Бесплатен	интеграцискиот API не е вклучен
Стартер	60
Професионален	300
Enterprise	без ограничување

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

Кога пристапот е затворен, не ограничен

Две состојби не се ограничување туку затворена врата, и обете враќаат 403 на секој повик:

Шифра	Што значи	Кај кого се решава
EARH-1010	планот на организацијата не носи интеграциски пристап	кај организацијата, преку претплатата
EARH-1011	клучот е изгаснат од сопственикот	кај сопственикот на клучот

Ниту една од двете не носи Retry-After, и тоа е намерно: чекањето не менува ништо, па повторувањето во јамка само троши. Тоа е и разликата спрема EARH-1006, каде времето е одговорот.

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

Граници по операција

Границата на сообраќај од претходниот раздел важи еднакво за секоја адреса — ниту една операција нема своја квота и ниту една не е поевтина од друга. Она што се разликува по операција е колку смее да носи едно барање:

Операција	Што е ограничено	Кога се прекршува
POST outbound	големината на документот	EARH-2012 · 413
GET outbound · GET inbound	големина на страница — 100 стандардно, 500 највеќе	EARH-3005 · 400
GET codelists/{type}	⛔ нема страничење — се враќа целата активна листа	—
сите останати	само границата на сообраќај	EARH-1006 · 429

Бројката не мора да ја знаеш однапред. И кај двете граници одговорот ја носи дозволената вредност во себе — EARH-2012 кажува колку MB се дозволени, EARH-3005 колку записи по страница. Значи еден одбиен повик е доволен за да се дознае границата; не се погодува и не се бара од нас.

Големина на документот

Се мери телото на POST outbound — самиот UBL XML. Вишокот најчесто доаѓа од вградени прилози и слики, не од самите податоци на фактурата.

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

План	Кров
Бесплатен	интеграцискиот API не е вклучен
Стартер	2 MB
Професионален	10 MB
Enterprise	50 MB

Enterprise има кров тука, а кај сообраќајот нема

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

Инкрементално повлекување — by=updated и nextFrom

Списоците имаат параметар by, кој кажува што мерат dateFrom и dateTo:

Вредност	Што мери
created — стандард	времето кога документот е создаден
updated	времето кога последно сме запишале промена кај него

Разликата е тоа што updated го решава: документ создаден минатиот месец чиј статус се сменил вчера се враќа со by=updated, а не се враќа со by=created. Со изостанат параметар однесувањето е како порано — постоечките повици не се менуваат.

Кога ќе побараш by=updated, одговорот носи и поле nextFrom: точката од која се продолжува следниот пат. Го праќаш назад како dateFrom во наредниот повик, пак со by=updated. Со by=created полето е null.

nextFrom важи САМО откако си ги повлекол СИТЕ страници

Списокот е подреден најнов прв. Ако ја земеш вредноста од nextFrom откако си ја прочитал само првата страница, следниот повик почнува од најновата промена — и сите постари промени што стоеле на страниците 2, 3, 4… се прескокнуваат засекогаш.

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

Правилото е едно: прочитај ги сите страници, па дури тогаш зачувај го nextFrom.

Преклопувањето е очекувано

Следниот повик ќе врати и дел од документите што веќе си ги видел. Тоа е договор, не дефект, и има две причини:

• долната граница dateFrom е вклучива
• nextFrom намерно е поместен малку наназад — маргина од 5 минути

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

Значи клиентот отстранува дупликати по docUid. Тоа е и сè што се бара од него.

by=updated наспрема onlyNotImported

Кај влезните документи постојат и двата, и не се заменливи:

Прашање	Параметар
„Што не сум презел уште?”	onlyNotImported=true
„Што се сменило од последното повлекување?”	by=updated

Документ што веќе си го презел и што потоа е одобрен се враќа само со by=updated — за onlyNotImported тој веќе не постои, зашто е презен.

Повторно праќање и заштита од дупликат

Секое барање што создава документ се обележува со заглавието X-Idempotency-Key. Ознаката ја избираш ти и таа е тоа што му кажува на API-то дека две барања се всушност едно исто.

Што праќаш	Што добиваш
прв пат, со нова ознака	201 — документот е создаден
повторно, иста ознака и иста содржина	200 — истиот одговор како првиот пат, без втор документ
иста ознака, поинаква содржина	EARH-2010 · 409

Разликата меѓу 201 и 200 е тоа по што се распознава дали документот е создаден сега или веќе постоел. Обата одговора носат ист документ, па повторувањето по прекината врска е безбедно.

Третиот ред е грешка, не повторување: истата ознака со поинаква содржина значи или нов документ со стара ознака, или документ изменет по првото праќање. Што точно да се направи со неа стои кај EARH-2010 во каталогот на грешки.

Прозорецот на идемпотентност трае еден час. По него истата ознака се смета за нова.

Синхроно праќање — Prefer: wait

POST outbound стандардно одговара веднаш, со статус 210: документот е примен, обработката тече во позадина. Со заглавието Prefer: wait=N одговорот чека до N секунди додека нашата обработка не стигне до исход на поднесувањето кон УЈП, па ја враќа таа состојба — заедно со ujp.euid, бројот што УЈП му го доделил на документот, и ujp.qrLink, врската за QR кодот што УЈП ја вратил.

Правило	Вредност
најдолго чекање	30 секунди — поголема вредност се сведува на 30
што се чека	само поднесувањето кон УЈП, не подоцнежните промени кај УЈП
кога рокот ќе истече	истиот 201, со статус 210 или 220 и "ujp": null — продолжи со GET outbound/{docUid}
како се знае дека е применето	заглавие Preference-Applied: wait=N во одговорот

Чекањето не менува ништо во самата обработка. Прекинато барање не ја прекинува обработката — таа продолжува, а исходот се чита со GET outbound/{docUid}. Истото заглавие важи и за повторениот повик со иста ознака за идемпотентност.

⚠️ Барањето што чека се брои во границата на сообраќај исто како секое друго — едно, без разлика колку секунди чекало.

Граница на историјата

Документи создадени пред воведувањето на идентификаторот docUid не се појавуваат преку интеграцискиот API. Тие немаат идентификатор по кој API-то може да ги адресира, па ниту еден список не ги враќа и ниту едно барање по docUid не стигнува до нив.

Тие документи не се бројат ниту во вкупниот број (totalCount) што го враќаат списоците. Значи бројката во одговорот не е вкупниот број документи на клиентот — тоа е бројот документи достапни преку интеграцискиот API. Ако твојот производ ја споредува таа бројка со она што клиентот го гледа во eArhiva, разликата е очекувана и не е грешка.

Постарите документи и понатаму се достапни преку самата апликација; она што ова го ограничува е само интеграцискиот API.