Ceník a oprávnění

API access je podmíněn funkcí předplatného ApiAccess. Je součástí plánu Enterprise a je k dispozici jako placený add-on u všech ostatních úrovní. Volání ověřená pomocí API key vůči společnosti bez ApiAccess vrátí HTTP 402 s code: "API_ACCESS_NOT_ENABLED" ještě předtím, než dosáhnou controlleru.

Tato stránka je směrodatným zdrojem informací o tom, jaký plán zákazník partnera potřebuje. Marketingové stránky (locco.hr/cijene) popisují úrovně srozumitelně pro lidi; matice níže představuje to, co vynucuje runtime.

Pravidlo

• ApiAccess je součástí plánu Enterprise.
• Na všech ostatních úrovních je ApiAccess k dispozici jako placený add-on. Bez tohoto add-onu jsou požadavky zamítnuty s chybou 402.
• Kontrola probíhá jednou pro každý požadavek, po autentizaci a po přeložení hlavičky X-Company-Id na cílovou společnost. Požadavek, který projde touto bránou, spotřebuje slot v rate-limit oknech; požadavek, který neprojde, nikoliv.

Tato funkce se váže na cílovou společnost získanou z X-Company-Id, nikoliv na uživatele, který vlastní API key. Uživatel, který patří do dvou společností (jedna s ApiAccess, druhá bez), uspěje vůči oprávněnému tenantovi a obdrží chybu 402 vůči druhému se stejným klíčem.

Matice úrovní

Pro odemknutí API access mohou zákazníci buď přejít na plán Enterprise (který obsahuje ApiAccess spolu se zbytkem úrovně), nebo si přidat ApiAccess add-on ke svému stávajícímu plánu. Obě cesty najdete ve webové aplikaci locco v sekci Nastavení → Předplatné.

Odpověď 402

Když klíč narazí na společnost, které chybí ApiAccess, partnerské API vrátí HTTP 402 s kanonickou chybovou envelope:

{
  "code": "API_ACCESS_NOT_ENABLED",
  "type": "PaymentRequired",
  "title": "<localized human message>",
  "status": 402
}

• code: stabilní. Partneři filtrují podle tohoto řetězce. Konstanta se nachází v katalogu chyb.
• type: starší kategorie, zachována kvůli kompatibilitě se SPA. Nevytvářejte podle ní větvení logiky.
• title: lokalizováno podle hlavičky Accept-Language v požadavku (výchozí je hr). Nikdy tuto hodnotu neparsujte. Znění není mezi verzemi stabilní. Skutečný text pochází ze souborů prostředků partnerského API (SharedResource.resx / SharedResource.hr.resx).
• status: zrcadlí stavový řádek HTTP. 402 Payment Required je standardní kód pro chybějící oprávnění. Jde o stejný stav, který se v celém odvětví používá pro situace typu „přihlašovací údaje jsou platné, ale plán tuto oblast nezahrnuje“.

Content-Type je application/json. Odpověď je krátká: žádný slovník errors, žádné podrobnosti k jednotlivým polím. Neexistuje nic, co by partner mohl zkusit znovu s jinými vstupy. Jediným řešením je, aby zákazník upgradoval svůj plán.

Doporučené zpracování na straně partnera

Chyba 402 z partnerského API je chybou stavu zákazníka, nikoliv přechodnou chybou. Opakované zkoušení stejného klíče vůči stejné společnosti bude nadále vracet 402, dokud zákazník neprovede upgrade.

Rozumný handler na straně klienta:

1. Při chybě 402 s code: "API_ACCESS_NOT_ENABLED" zastavte polling smyčku integrace pro danou společnost a zobrazte ve svém uživatelském rozhraní nebo provozní konzoli jasnou zprávu „plán locco tohoto zákazníka nezahrnuje API access“.
2. Nepoužívejte backoff a nezkoušejte to znovu. Toto okno není přechodné.
3. Pokud integrace zahrnuje více společností, izolujte tuto bránu pouze na selhávající společnost. Ostatní společnosti na plánu Enterprise by měly nadále fungovat.

Podrobný přehled všech chybových kódů, které může partnerské API vygenerovat, najdete v katalogu chyb.

Související

• Autentizace: bearer tokens, hlavička X-Company-Id a rotace klíčů.
• Chyby: kompletní katalog stabilních strojově čitelných chybových kódů.
• Rate limits: limity za sekundu, za hodinu a za den na úrovni Enterprise.