Avtentikacija

Vsak zahtevek proti /api/v1/* mora vsebovati glavo Authorization: Bearer <api-key>. Ključe izdajajo administratorji podjetja prek locco spletne aplikacije.

Bearer token model

locco uporablja neprozorne (opaque) bearer žetone. Strežnik shrani ključ v hashirani obliki, zato je njegova vrednost v plaintextu klicatelju vidna le enkrat (v trenutku izdaje). Izgubljenega ključa ni mogoče obnoviti. Namesto tega ga rotirajte.

Izdajte ključ pod Nastavitve → Integracije → API ključi v locco spletni aplikaciji. Gumb “API dokumentacija” na tej strani vodi sem.

Format ključa

Ključi so nizi v obliki:

locco_live_<naključni-niz>

Predpona locco_live_ je stabilna. Ključ obravnavajte kot skrivnost: shranite ga v svoj secret manager, nikoli ga ne commitajte v različico kode in nikoli ga ne logirajte. Ključ omogoča dostop do vsakega endpointa, do katerega ima dovoljenje uporabnik, ki je izdal ključ, znotraj ciljnega podjetja.

Glava X-Company-Id

Vsak zahtevek z API ključem MORA vsebovati Guid ciljnega podjetja v glavi X-Company-Id:

X-Company-Id: 00000000-0000-0000-0000-000000000000

Manjkanje te glave vrne HTTP 400 s code: "VALIDATION_FAILED". Glava je obvezna pri vsakem zahtevku, tudi kadar lastnik ključa pripada le enemu podjetju. locco nikoli ne sklepa ciljnega najemnika samo iz ključa.

Guid podjetja najdete v URL-ju locco spletne aplikacije, ko ste v ciljnem podjetju, ali ga zahtevajte od lastnika računa.

Primer zahtevka

bash
curl https://api.locco.hr/api/v1/travel-entries \
  -H "Authorization: Bearer locco_live_..." \
  -H "X-Company-Id: 00000000-0000-0000-0000-000000000000"

Uspešni odgovori vsebujejo glave z omejitvami zahtevkov (glej Omejitve zahtevkov) in standardno JSON telo. Odgovori z napako vsebujejo stabilen strojno berljiv code (glej Napake).

Rotacija ključa

Za rotacijo ključa brez prekinitve delovanja:

  1. Generirajte nov ključ na strani z nastavitvami. Plaintext vrednost takoj kopirajte v svoj secret manager.
  2. Nastavite svoje odjemalce z novim ključem vzporedno s starim.
  3. Ko se promet preusmeri, prekličite stari ključ. Preklicani ključi vrnejo HTTP 401.

Ne obstaja operacija “ponovno generiraj”, ki bi ohranila staro vrednost ključa. Vedno izdajte nov ključ, migrirajte, nato prekličite starega.

Pravica do uporabe

Ciljno podjetje mora imeti naročniško funkcijo ApiAccess, ki je na voljo s paketoma Enterprise in Custom. Zahtevki proti podjetju brez te funkcije vrnejo HTTP 402 s code: "API_ACCESS_NOT_ENABLED". Glejte Cene in pravica do uporabe za popolno matrico po paketih in obliko odgovora.

Glejte katalog napak za popoln seznam strojno berljivih kod napak in ustrezni partnerski odziv za vsako od njih.