Cijene i pravo korištenja

API pristup je vezan uz pretplatničku značajku ApiAccess. Uključena je u paketu Enterprise, a na ostalim paketima dostupna je kao plaćeni dodatak. Pozivi autenticirani API ključem prema tvrtki bez značajke ApiAccess vraćaju HTTP 402 s code: "API_ACCESS_NOT_ENABLED" prije nego stignu do kontrolera.

Ova stranica je autoritativan izvor za to koji paket treba klijent vašeg partnerskog proizvoda. Marketinške stranice (locco.hr/cijene) opisuju pakete u poslovnim terminima; matrica niže je ono što runtime stvarno provjerava.

Pravilo

• ApiAccess je uključen u paketu Enterprise.
• Na ostalim paketima ApiAccess je dostupan kao plaćeni dodatak. Bez dodatka, zahtjevi se odbijaju s 402.
• Provjera se izvodi jednom po zahtjevu, nakon autentifikacije i nakon što je zaglavlje X-Company-Id razriješeno na ciljanu tvrtku. Zahtjev koji prođe provjeru troši slot u prozorima ograničenja zahtjeva; zahtjev koji ne prođe ne troši.

Provjera se temelji na ciljanoj tvrtki razriješenoj iz X-Company-Id, a ne na korisniku koji je vlasnik ključa. Korisnik koji pripada dvjema tvrtkama (jednoj sa značajkom ApiAccess, jednoj bez) imat će uspjeh prema tvrtki sa značajkom i 402 prema drugoj, istim ključem.

Matrica paketa

Za otključavanje API pristupa, korisnik može nadograditi na Enterprise (koji uključuje ApiAccess uz ostatak paketa) ili dodati ApiAccess kao dodatak na svoj trenutni paket. Oba puta dostupna su u locco web aplikaciji pod Postavke → Pretplata.

Odgovor 402

Kada ključ pogodi tvrtku koja nema ApiAccess, partner API vraća HTTP 402 s kanonskom omotnicom greške:

{
  "code": "API_ACCESS_NOT_ENABLED",
  "type": "PaymentRequired",
  "title": "<lokalizirana ljudska poruka>",
  "status": 402
}

• code: stabilno. Partneri filtriraju po ovom stringu. Konstanta je u katalogu grešaka.
• type: stara kategorija, zadržana radi kompatibilnosti sa SPA aplikacijom. Ne uvjetujte logiku po njoj.
• title: lokalizirano prema Accept-Language zaglavlju zahtjeva (zadano hr). Nikada ne parsirajte. Formulacija nije stabilna između izdanja, a stvarni tekst dolazi iz resursnih datoteka partner API-ja (SharedResource.resx / SharedResource.hr.resx).
• status: odražava HTTP status. 402 Payment Required je standardni kod za nedostatak prava korištenja. Isti status koristi se industrijski za “vjerodajnice su valjane, ali paket ne uključuje ovu površinu”.

Content-Type je application/json. Odgovor je kratak: bez errors rječnika, bez detalja po polju. Partner nema ništa za pokušati iznova s drugačijim ulazom. Jedino rješenje je da korisnik nadogradi paket.

Preporučeno postupanje partnera

402 s partnerskog API-ja je greška stanja korisnika, ne prolazna greška. Ponovljeni pokušaj istog ključa prema istoj tvrtki nastavit će vraćati 402 sve dok korisnik ne nadogradi paket.

Razumno postupanje klijenta:

1. Na 402 s code: "API_ACCESS_NOT_ENABLED", zaustavite integracijsku petlju za tu tvrtku i prikažite jasnu poruku “locco paket ovog korisnika ne uključuje API pristup” u svom sučelju ili konzoli.
2. Nemojte odgađati i ponavljati. Stanje nije prolazno.
3. Ako integracija pokriva više tvrtki, izolirajte zid na neuspješnu tvrtku. Ostale tvrtke na Enterprise paketu trebaju nastaviti raditi.

Za detaljan opis svake greške koju partner API može emitirati, pogledajte katalog grešaka.

Povezano

• Autentifikacija: bearer tokeni, zaglavlje X-Company-Id i rotacija ključeva.
• Greške: potpun katalog stabilnih strojno čitljivih kodova grešaka.
• Ograničenja zahtjeva: ograničenja po sekundi, po satu i po danu na Enterprise paketu.