Cenník a oprávnenia

API access je podmienený funkciou predplatného ApiAccess. Je zahrnutý v pláne Enterprise a dostupný ako platený add-on na každej ďalšej úrovni. Volania overené pomocou API key voči spoločnosti bez ApiAccess vrátia HTTP 402 s code: "API_ACCESS_NOT_ENABLED" predtým, než dosiahnu controller.

Táto stránka je smerodajným zdrojom informácií o tom, aký plán potrebuje zákazník partnera. Marketingové stránky (locco.hr/cijene) popisujú úrovne ľudskou rečou; matica nižšie predstavuje to, čo vynucuje runtime.

Pravidlo

• ApiAccess je zahrnutý v pláne Enterprise.
• Na každej ďalšej úrovni je ApiAccess dostupný ako platený add-on. Bez tohto add-on sú požiadavky zamietnuté s 402.
• Kontrola prebieha raz pre každú požiadavku, po autentifikácii a po tom, čo bol header X-Company-Id preložený na cieľovú spoločnosť. Požiadavka, ktorá prejde kontrolou, spotrebuje miesto v rate-limit oknách; požiadavka, ktorá neprejde, ho nespotrebuje.

Funkcia sa viaže na cieľovú spoločnosť získanú z X-Company-Id, nie na používateľa, ktorý vlastní API key. Používateľ, ktorý patrí do dvoch spoločností (jedna s ApiAccess, druhá bez), uspeje voči oprávnenému tenantovi a dostane 402 voči druhému s rovnakým kľúčom.

Matica úrovní

Pre odomknutie API access môžu zákazníci buď prejsť na plán Enterprise (ktorý spája ApiAccess so zvyškom úrovne), alebo pridať ApiAccess add-on k svojmu aktuálnemu plánu. Obe cesty sa nachádzajú vo webovej aplikácii locco v časti Nastavenia → Predplatné.

Odpoveď 402

Keď kľúč narazí na spoločnosť, ktorej chýba ApiAccess, partnerské API vráti HTTP 402 s kánonickým chybovým envelope:

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

• code: stabilné. Partneri filtrujú podľa tohto reťazca. Konštanta sa nachádza v katalógu chýb.
• type: legacy kategória, ponechaná pre kompatibilitu so SPA. Nevetvite podľa nej.
• title: lokalizované podľa Accept-Language požiadavky (predvolené je hr). Nikdy ho neparsujte. Formulácia nie je stabilná naprieč vydaniami. Samotný text pochádza zo súborov zdrojov partnerského API (SharedResource.resx / SharedResource.hr.resx).
• status: zrkadlí stavový riadok HTTP. 402 Payment Required je štandardný kód pre chýbajúce oprávnenia. Je to rovnaký status, aký sa používa v celom odvetví pre „prihlasovacie údaje sú platné, ale plán nezahŕňa túto oblasť“.

Content-Type je application/json. Odpoveď je krátka: žiadny slovník errors, žiadne detaily pre jednotlivé polia. Neexistuje nič, čo by partner mohol skúsiť znova s inými vstupmi. Jediným riešením je, aby zákazník prešiel na vyšší plán (upgrade).

Odporúčané spracovanie pre partnerov

Odpoveď 402 z partnerského API je chyba stavu zákazníka, nie prechodná chyba. Opakované skúšanie rovnakého kľúča voči rovnakej spoločnosti bude naďalej vracať 402, kým zákazník neprejde na vyšší plán.

Rozumné spracovanie na strane klienta:

1. Pri 402 s code: "API_ACCESS_NOT_ENABLED" zastavte cyklus dopytovania (polling) integrácie pre danú spoločnosť a zobrazte jasnú správu „plán locco tohto zákazníka nezahŕňa API access“ vo vašom používateľskom rozhraní alebo prevádzkovej konzole.
2. Neaplikujte back off a neskúšajte to znova. Okno nie je prechodné.
3. Ak integrácia zahŕňa viacero spoločností, izolujte blokovanie len na zlyhávajúcu spoločnosť. Ostatné spoločnosti na pláne Enterprise by mali naďalej fungovať.

Pre podrobný prehľad každého chybového kódu, ktorý môže partnerské API vygenerovať, si pozrite katalóg chýb.

Súvisiace

• Autentifikácia: bearer tokens, header X-Company-Id a rotácia kľúčov.
• Chyby: úplný katalóg stabilných strojovo čitateľných chybových kódov.
• Rate limits: limity za sekundu, za hodinu a za deň na úrovni Enterprise.