Veliki obim i špicevi: ograničenja API-ja, red čekanja i Black Friday

Tezga API podrazumevano prima 120 zahteva u minuti za izdavanje i refundaciju i 240 za čitanje, po firmi. Granica je podešavanje naloga, a ne kod: podiže se na zahtev do 10.000 zahteva u minuti, pre najavljene akcije. Broj računa mesečno nije ograničen. Tvoj deo posla je da klijent poštuje Retry-After, da ispred poziva ima red čekanja i da svaki zahtev nosi externalId.

Koliko zahteva u minuti ti zaista treba?

Granica se računa u prozoru od jedne minute, po firmi, zajedno za sve ključeve. Svi pozivi koji nešto upisuju (račun, refundacija, avans, kopija, kalkulacija, nivelacija, artikli i kupci) dele jedan brojač pisanja. Ako imaš tri sistema sa tri ključa, oni dele isti brojač. Računica je jednostavna: jedna porudžbina je jedan poziv /order, pa ti treba broj porudžbina u najjačem minutu, uvećan za refundacije i rezervu. Za rezervu je dobar početak 50 odsto.

Najjači sat	Porudžbina u minuti	Sa rezervom 50%	Da li staje u podrazumevanih 120?
3.000 porudžbina	50	75	Da
6.000 porudžbina	100	150	Ne, podigni na 200
12.000 porudžbina	200	300	Ne, podigni na 300 ili više
60.000 porudžbina	1.000	1.500	Ne, podigni na 1.500 ili više

Brojke u tabeli su računica, a ne merenje: tačan broj zavisi od toga da li porudžbina ide kao jedan poziv ili je podeljena na više, i koliko se refundacija očekuje. Najpoštenije je da pre akcije proveriš svoj najjači minut iz prošle godine.

Vrh prodaje ne udara direktno u API: red čekanja ga razvlači, a radnici ne prelaze ugovoreni broj poziva u minuti.

Šta tačno klijent treba da radi?

• Red čekanja ispred poziva. Porudžbina koja je plaćena upisuje se u red, a ne zove API u istom zahtevu kupca. Time kupac ne čeka fiskalizaciju, a vrh se razvlači.
• Radnici ograničeni brojem poziva. Veličinu skupa radnika vezuješ za X-RateLimit-Limit, ne za pogađanje.
• 429 znači čekaj. Zaglavlje Retry-After kaže posle koliko sekundi; ne ponavljaj odmah i ne koristi novi externalId.
• 202 nije greška. Poreska uprava ne odgovara, a Tezga sama ponavlja fiskalizaciju; opisano u tekstu kad Poreska uprava ne radi.
• Isti externalId uvek. Ponovljen zahtev vraća postojeći dokument, i kad dva zahteva stignu istovremeno.

// Node.js: jedan radnik, poštuje Retry-After, isti externalId pri ponavljanju
async function izdaj(porudzbina, kljuc, pokusaj = 0) {
  const r = await fetch("https://pos.narbiz.com/api/integrations/order?provider=custom", {
    method: "POST",
    headers: { "X-Tezga-Api-Key": kljuc, "Content-Type": "application/json" },
    body: JSON.stringify({ externalId: porudzbina.broj, tok: "fiskalni", ...porudzbina.telo }),
  });
  if (r.status === 429 && pokusaj < 5) {
    const cekaj = Number(r.headers.get("Retry-After") ?? "5") * 1000;
    await new Promise((res) => setTimeout(res, cekaj));
    return izdaj(porudzbina, kljuc, pokusaj + 1);
  }
  if (r.status === 200 || r.status === 202) return r.json();
  throw new Error(`Tezga ${r.status}`);
}

Kako se upisuju artikli i kupci u velikom obimu?

Pozivi /products i /customers primaju od 1 do 500 stavki, a telo može biti do 512 KB. Jedna loša stavka ne ruši ostale: odgovor nosi ishod po stavci. Ponovljen isti zahtev je bezbedan i vraća status bez_izmene. Katalog od 50.000 artikala je zato 100 poziva, što staje u jedan minut pri podrazumevanom limitu pisanja. Pošto isti brojač koristi i izdavanje računa, sinhronizaciju kataloga stavi van vrha prodaje.

Stanje zaliha se preko ovog poziva ne upisuje, da knjiga promena ostane tačna. Prijem robe ide kroz /kalkulacija, a promena cene kroz /nivelacija; više u tekstu o ERP-u i fiskalizaciji.

Kako se limit podiže i koliko košta obim?

Limit se podiže na zahtev: javi očekivani broj računa u minuti pre početka prodaje. Najniža vrednost koju nalog može da ima je 10, a najviša 10.000 zahteva u minuti. Broj računa mesečno nije ograničen: u pretplati je uključeno 3.000, a preko toga 2 dinara po računu. Na Enterprise nivou postoje dva modela, 2 RSD po računu ili 800 € mesečno po sajtu bez obzira na broj računa; uz kurs od oko 117 dinara za evro fiksni model postaje povoljniji od oko 46.800 računa mesečno po sajtu. Uslovi su na strani Enterprise.

Ograničenje je vezano za nalog, a ne za kod: isti kod radi i u testu i u vrhu, bez izmena, a granicu klijent čita iz zaglavlja, ne iz konstante.

Izvori: OpenAPI opis Tezga eKase, verzija 1.6.0 (pos.narbiz.com/api/openapi.json), ИБ 1597; uputstvo za integratore (pos.narbiz.com/api-dokumentacija.pdf); strana Enterprise, uslovi verzija 1.0 (tezgafiskal.com/enterprise). Brojke u tabeli su računica, ne merenje.