Avalik API v3

API v3 on Uku praegune avalik API: see katab palju suurema osa tootest kui vana v1.0 API, kasutab lihtsamat võtmepõhist sisselogimist ilma aeguvate tokeniteta ning on versioon, mille peale peaks iga uus integratsioon ehitama.

Ettevõtte omanikud ja Ettevõtte peakasutajad Elite paketiga, kellel on Avalik API äpp aktiveeritud. Ettevõtte kasutajad ei näe ega saa luua API võtmeid.

Avalik API äpil on kolm vahekaarti: Ülevaade; (old) API, mis viib vana v1.0 API juurde; ja Avalik API — praegune v3 API, kus veedad enamiku ajast. Just sellele vahekaardile äpp avanebki.

Ukul on kaks töötavat API-t ja v3 on see, mille peale ehitada. See pole kosmeetiline versiooniuuendus — v1.0 oli lugemisele suunatud aken osale tootest, v3 aga täielik loe-kirjuta liides peaaegu kogu tootele.

• See katab kogu toote. Üle 30 ressursi v1.0 16 vastu — projektidel, eelarvetel, märgetel, lisaväljadel, manustel, tööajal ja delegeerimistel ning veel muul lihtsalt pole v1.0 endpointi.
• See kirjutab, mitte ainult ei loe. v1.0 saab luua kliente, kontakte, ülesandeid ja veebihaake ning mitte midagi muud. v3 loob, uuendab ja kustutab peaaegu kõikjal Ukus, sealhulgas arveldamises.
• Sisselogimine on kaks päist. Pole /login päringut, pole JWT-d, mis aegub iga 10 minuti järel, pole värskendusloogikat, mida valesti teha — saada lihtsalt oma ettevõtte UUID ja võti iga päringuga.
• Vead ütlevad, mis valesti läks. Iga viga kannab stabiilset koodi, mille järgi sinu integratsioon saab hargneda, mitte lauset, mida stringina võrrelda.
• Võtmeid saab kitsendada. Piira raporteerimistööriist ainult lugemisele, lukusta võti oma serverite IP-aadressile, sea aegumiskuupäev — midagi sellest v1.0 ei paku.
• Sinu arveldusandmed on kaitstud. v3 keeldub kirjutamast arvele, mis on pärast sinu integratsiooni viimast lugemist muutunud, nii et automatiseering ei saa märkamatult üle kirjutada seda, mida keegi just Ukus parandas.
• Uku võtab ise ühendust. Telli sündmusi klientide, kontaktide, ülesannete, projektide, arvete ja ajakirjete kohta — iga saatmine on allkirjastatud oma saladusega ja seda proovitakse uuesti, kui sinu endpoint ei vasta — selle asemel, et meid pidevalt pollida.
• Dokumentatsioon on elus. Proovi iga endpointi otse brauseris ja anna masinloetav spetsifikatsioon otse oma arendajale või tehisintellekti kodeerimistööriistale.

Vana API töötab endiselt ja sinu olemasolevad integratsioonid jätkavad tööd — see on külmutatud, mitte välja lülitatud. Võtmed pole aga omavahel vahetatavad: v1.0 võti ei autendi v3 vastu ja v3 võti ei tööta v1.0-l. Mõlemad võivad migreerimise ajal kõrvuti aktiivsed olla.

Iga võti kuulub sinu ettevõttele ja selle loonud isikule ning kuvatakse täies mahus vaid üks kord.

Tee: Seaded & Äpid → Avalik API → Avalik API

1. Kopeeri oma Ettevõtte UUID vahekaardi ülaosas olevast väljast — see on X-Uku-Company väärtus, mida iga päring vajab.
2. Sisesta Võtme nimi, mis ütleb, mis seda kasutab, näiteks „Power BI raportid” või „Lao sünkroniseerimine”.
3. Vali integratsiooni jaoks vajalikud Õigused:
   • Lugemine — ainult andmete lugemine.
   • Muuda — lugemine, pluss igapäevaste kirjete, näiteks klientide, kontaktide, ülesannete ja ajakirjete loomine, uuendamine ja kustutamine.
   • Kõik — kõik eelnev, pluss arveldusandmed ja API võtmete haldamine (vt allpool).
4. Soovi korral ava Lisavalikud, et määrata Aegub (valikuline) kuupäev või Lubatud IP-de loend (valikuline) (komaga eraldatud aadressid või CIDR-vahemikud, näiteks 192.168.1.1, 10.0.0.0/24), et võti töötaks ainult sinu serveritest.
5. Klõpsa Loo API võti. Täielik võti (algab uku_live_-ga) kopeeritakse sinu lõikelauale ja kuvatakse üks kord — „Kopeeri see võti kohe. Seda enam uuesti ei näidata.” Salvesta see oma paroolihaldurisse või saladuste hoidlasse ja klõpsa seejärel Valmis.

Pärast seda loetleb tabel võtme Nimi, Võtme prefiks, Õigused, Viimati kasutatud, Aegub ja Koostatud — mitte kunagi võtit ennast. Prügikasti ikoon kustutab võtme, mis tühistab selle kohe kõigi integratsioonide jaoks, mis seda veel kasutavad.

Kõik, mis raha liigutab, vajab Kõik õigust — nii lugemiseks kui kirjutamiseks. Muuda katab enamiku Ukust, kuid ei ulatu finantsandmeteni, ja päring, mis seda piiri ületab, tagastab 403 FINANCIAL_SCOPE_REQUIRED.

Lugemine. Kõik võti loeb kõike. Väiksema võtmega:

• Täielikult finantsressursid — arved, lepingud, kokkulepped, arve väljastajad, monitorid, maksud, eelarved, tööaeg ja tagasinõuded — tagastavad 403 isegi GET-päringul.
• Segaressursid — liikmed ja tooted — on siiski loetavad, kuid nende rahaväljad tulevad tühjadena: liikme krediidijäägid ning toote hinnad, maksuseaded, arveldusalus ja raamatupidamise marsruutimiskoodid.

Kirjutamine. Piir kulgeb kahtemoodi, olenevalt kirjest:

• Kõik iga kirjutamise jaoks — arved ja nende read, liikme kokkulepped, toote hinnad ning uued eelarved (eelarve summa on kohustuslik, seega uue loomine ületab alati rahapiiri). Muuda võti ei saa ühtki neist luua, muuta ega kustutada. Ka tööaja kirje loomine või kustutamine vajab Kõik õigust.
• Kõik ainult rahaväljade jaoks — lepingutel, monitoridel, toodetel, maksudel, arve väljastajatel, tööajal ja olemasolevatel eelarvetel saab Muuda võti muuta tavalisi välju, samas kui rahaväljad vajavad Kõik õigust. Rahaväljad on: lepingu arveldusperiood, arve koostamise päev ning algus- ja lõppkuupäevad; monitori lävendid; maksumäär; toote maksuseaded, arveldusalus ja raamatupidamise marsruutimiskoodid; tööaja kirje kestus ja staatus (kinnitamine või tagasilükkamine liigutab liikme krediidijääki); eelarve summa, hoiatusmäär, korduvus või staatus; ja — arve väljastajal — kõik peale staatuse ja logo, kuna selle juriidiline nimi, aadress, registrikood, KMKR number ja pangaandmed määravad, kellele makstakse. (Lepingu enda status pole enam midagi, mida sina määrad: Uku tuletab selle kuupäevadest — ootel enne perioodi, aktiivne perioodi jooksul, lõppenud pärast seda.)

Arve elutsükli toimingud Uku kasutajaliidesest on saadaval endpointidena, kumbki vajab Kõik õigust ja If-Match versioonimärgist:

• POST /invoices/{id}/send lisab arve saatmisjärjekorda (e-kiri, PDF, e-arve) ja tagastab 202 — see saadetakse taustal ning status muutub sent-iks, kui see lõpeb. Sobib, kui staatus on created, sent või paid, muidu 409 INVOICE_NOT_SENDABLE.
• POST /invoices/{id}/mark-paid salvestab makse ja viib arve staatusesse paid. Sobib ainult, kui staatus on created või sent, muidu 409 INVOICE_NOT_PAYABLE.

Tagasinõude tagasipööramiseks liigutab POST /reclaims/{id}/undo tagasinõutud aja algallikasse (õigus Kõik; 409 RECLAIM_NOT_UNDOABLE, kui see on juba tagasi pööratud, algallika ülesanne on kustutatud või perioodi arve on lukustatud).

Iga päring kannab mõlemat päist. Muud pole vaja — pole sisselogimispäringut ega tokenit, mida värskendada.

curl https://app.getuku.com/api/v3/clients \
  -H "X-Uku-Company: your-company-uuid" \
  -H "X-API-Key: uku_live_..."

Vastus mähib kirjed data massiivi koos meta plokiga lehitsemise jaoks:

{
  "data": [
    { "id": 123, "name": "Apple Ltd" }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0, "has_more": false },
  "warnings": null
}

Vead tulevad tagasi alati samas kujus, koos koodiga, mille järgi sinu integratsioon saab hargneda:

{
  "error": {
    "code": "MISSING_COMPANY",
    "message": "X-Uku-Company header is required"
  }
}

Mõned vead — näiteks tagasilükatud päringu keha — lisavad details loendi, mis nimetab vigased väljad.

Uku avaldab API v3 jaoks elava, interaktiivse sandboxi — iga endpoint koos oma päringu- ja vastuseskeemidega, ning Try it out nupp, mis teeb päris päringuid sinu enda ettevõtte vastu, kasutades sinu võtit. See on kiireim viis näha endpointi täpset kuju enne koodi kirjutamist ja see on alati ajakohane, sest see genereeritakse töötavast API-st.

• app.getuku.com/api/v3/docs — interaktiivne sandbox (Swagger UI). Kleebi oma Ettevõtte UUID ja API võti üks kord ning kutsu siis lehelt endpointe.
• app.getuku.com/api/v3/redoc — sama teatmik ainult lugemiseks mõeldud, kergemini sirvitavas vormis.
• app.getuku.com/api/v3/openapi.json — masinloetav spetsifikatsioon. Anna see oma arendajale, API kliendile nagu Postman või Insomnia, või tehisintellekti kodeerimistööriistale, et genereerida klient.
• app.getuku.com/api/v3/llms.txt — lihttekstiline kokkuvõte tehisintellekti assistentide jaoks, koos täieliku teatmikuga aadressil llms-full.txt.

Täielik ja alati ajakohane endpointide loend on ülalpool interaktiivses sandboxis.

• Kliendid ja kontaktid — kliendid, kontaktid, kliendigrupid, märked ja kliendi liikmed (iga inimese roll kliendil, sealhulgas tema portaali-kasutaja lipp).
• Töö — ülesanded, ülesannete seosed, ülesannete automatiseeringud, delegeerimised, projektid, teemad, tööplaani rollid, rollid.
• Aeg — ajakirjed, kalender (tööajad ja pühad), tööaeg.
• Arveldamine — arved ja read, lepingud ja read, tooted ja hinnad, maksud, arve väljastajad, eelarved, monitorid, tagasinõuded.
• Inimesed — liikmed ja nende kokkulepped.
• Seadistus — lisaväljad, toote väljad, tarnijad, sisumallid.
• Failid — manused ülesannetel ja märgetel (kuni 150 MB faili kohta; käivitatavad failid lükatakse tagasi).

Mõned endpointid on dokumentatsioonis märgistatud Preview ja tagastavad X-Api-Preview: true päise. Need on täielikult saadaval — märgistus tähendab, et kuju võib veel muutuda, seega fikseeri oma integratsioon selle vastu, mida testisid.

Iga API v3 loend-endpoint kasutab samu päringuparameetreid lehitsemiseks, filtreerimiseks ja sortimiseks, nii et see, mida õpid ühel ressursil, töötab kõigil.

• Lehitsemine — ?limit= (1–200, vaikimisi 50) ja ?offset= (algab 0-st). meta.has_more ütleb, millal järgmist lehte tuua. Üle 10 000 kirje puhul lehitse ?cursor= abil ja järgi meta.next_cursor.
• Filtreerimine — filtreeri välja järgi (?client_id=123), edasta mitu väärtust komaga eraldatuna, otsi teksti ?q= abil ja võrdle sufiksitega nagu ?date.gte=2026-01-01.
• Sortimine — ?sort=name kasvavalt, ?sort=-created_at kahanevalt.

Filtreeri raskeid endpointe (ülesanded, ajakirjed, arved) alati kuupäeva või emakirje järgi, mitte ei too kõike korraga.

Igal võtmel on lubatud 120 lugemispäringut ja 30 kirjutamispäringut minutis. Iga vastus ütleb, kus sa seisad:

• X-RateLimit-Limit — sinu limiit selle päringutüübi jaoks.
• X-RateLimit-Remaining — kui palju on selle minuti jooksul veel alles.
• X-RateLimit-Reset — millal loendur nullitakse.

Kui lähed üle, vastab API 429-ga koos Retry-After päisega. Oota see periood ära, selle asemel et kohe uuesti proovida. Ilma võtmeta päringud on piiratud rangemalt (60 minutis IP-aadressi kohta, kuna need saavad ainult autentimisel ebaõnnestuda), ja kõige taga on kuritarvitamise vastu 1000 päringut minutis IP kohta ülempiir — tunduvalt kõrgem kui tavaline integratsioon kunagi saadab.

Kui loomispäring aegub, ei tea sa tihti, kas see läbi läks — uuesti proovimine võib tekitada topeltarve. Ohutuks uuesti proovimiseks saada Idempotency-Key päis (mis tahes unikaalne string, mille ise genereerid) päringutele POST /invoices, /contracts, /agreements või /time-entries. Kordus sama võtmega ja identse kehaga mängib algse vastuse uuesti, selle asemel et luua teine kirje, ja vastus kannab Idempotency-Replayed: true. Võtmeid mäletatakse 24 tundi. Kaks asja tagastavad 409 selle asemel: uuesti proovimine, kui esimene päring alles töötab (IDEMPOTENCY_CONFLICT — oota ja proovi uuesti), ja võtme taaskasutamine erineva kehaga (IDEMPOTENCY_KEY_REUSED — kasuta iga erineva päringu jaoks uut võtit).

Selle asemel, et Ukut pidevalt pollida, saab Uku sind ise kutsuda: telli URL sündmusele ja iga kord, kui see sündmus juhtub, saadame kirje sinu endpointile POST-päringuna — allkirjastatult ja korduskatsetega. Sündmused hõlmavad kliente, kontakte, ülesandeid, projekte, arveid ja ajakirjeid.

Tellimused luuakse API kaudu ja vajavad Kõik õigusega võtit, kuid saad neid Ukust jälgida: Avalik API vahekaardil on Connected webhooks loend, mis näitab iga tellimuse staatust, ebaõnnestumiste arvu ja hiljutisi saatmisi, koos nuppudega välja lülitatud tellimuse uuesti sisse lülitamiseks või ebaõnnestunud saatmise uuesti saatmiseks. Täielik leping — tellimine, saatmise sisu, allkirja kontrollimine, korduskatsed ja uuesti saatmine — on artiklis Veebihaagid.

Rahaga seotud kirjed — arved, lepingud ja nende read, liikme kokkulepped, liikme krediidid ja kliendi monitorid — on kaitstud kahe süsteemi üksteise ülekirjutamise eest.

Kui loed ühte neist kirjetest, sisaldab vastus ETag päist, mis on lihtsalt tempel selle kohta, millal kirjet viimati muudeti. Kirje muutmiseks või kustutamiseks saada see tempel tagasi If-Match päisena:

• Jäta see välja ja API keeldub 428-ga — ta tahab teada, millist versiooni sa muudad.
• Saada vana tempel, kuna keegi muutis kirjet Ukus või teise integratsiooni kaudu vahepeal, ja API keeldub 412-ga. Loe kirje uuesti ja proovi värske templiga uuesti.

Arved ja kokkulepped tahavad templit iga olemasoleva kirje muudatuse juures; lepingud, liikmed ja monitorid tahavad seda, kui muudatus puudutab rahavälja. Täiesti uue kirje loomine ei vaja seda kunagi — eelmist versiooni, millega võrrelda, pole. Tavalised kirjed — ülesanded, kliendid, kontaktid, ajakirjed — ei vaja seda kunagi.

API v3 võti avab sinu ettevõtte päris andmed kõigile, kelle käes see on, seega käsitle seda sama tõsise mandaadina kui Uku enda parooli.

• Käsitle võtit nagu parooli. Ära kunagi lisa seda versioonihaldusesse, ära kunagi pane seda brauserisse ega mobiilirakendusse, kus kasutaja saaks seda lugeda.
• Üks võti integratsiooni kohta. Kui üks lekib, kustuta see ilma teisi katkestamata.
• Anna väikseim õigus, mis toimib. Raporteerimistööriist vajab Lugemine õigust, mitte Kõik.
• Lukusta võtmed oma serveritele IP lubatud loendiga ja sea Aegub kuupäev kõigele, mis on ajutine.
• Kustuta võtmed, mida enam ei kasuta. Kustutamine tühistab juurdepääsu kohe.
• Ainult HTTPS. Lihtsad HTTP päringud lükatakse tagasi.
• Võti pääseb ligi ainult sinu enda ettevõtte andmetele. Teisele ettevõttele kuuluvad kirjed tagastavad 404, mitte viga, mis paljastaks nende olemasolu.

Avalik API ja (old) API vahekaardid ilmuvad ainult Ettevõtte omanikele ja Ettevõtte peakasutajatele, ja ainult siis, kui Avalik API äpp on sinu ettevõtte jaoks Elite paketil aktiveeritud. Kui jõuad Ülevaade vahekaardile ja midagi muud pole kõrval, siis on see põhjus: aktiveeri äpp sellelt ekraanilt või palu Ettevõtte omanikul seda teha. Ettevõtte kasutajad ei näe API võtmeid üldse.

v1.0 võti ei saa v3 vastu autentida — kaks versiooni kasutavad erinevaid mandaate. Loo uus võti Avalik API vahekaardil ja lülitu kahe päise sisselogimisele (X-Uku-Company + X-API-Key); v3-s pole /login päringut ega JWT-d.

X-Uku-Company päis on päringul puudu või tühi. Kopeeri Ettevõtte UUID Avalik API vahekaardi ülaosast ja saada see koos API võtmega igas päringus. Ainult võtme saatmisest kunagi ei piisa — v3 vajab alati mõlemat päist.

Kirjutamise puhul on võtme õigus liiga kitsas: Lugemine võti ei saa midagi luua ega muuta, seega loo uus võti Muuda õigusega.

Kui veakood on täpsemalt FINANCIAL_SCOPE_REQUIRED, puudutas päring finantsandmeid — arve, lepingu, kokkuleppe, arve väljastaja, monitori, maksu, eelarve, tööaja, tagasinõude või liikme või toote rahavälja lugemist või kirjutamist. Kõik see vajab Kõik õigust, nagu on kirjeldatud jaotises Rahaandmed vajavad Kõik-õigust.

Aadressil app.getuku.com/api/v3/docs on interaktiivne sandbox, kus saad kutsuda iga endpointi brauserist — kuid see töötab sinu päris ettevõtte vastu, sest API v3 väljastab ainult päris võtmeid (uku_live_). Eraldi testettevõtet ega testvõtit pole. Arendamise ajal kirjuta väikese, selgelt nimetatud kliendi peale, kelle saad hiljem kustutada.

Saad võtme roteerida integratsiooni katkestamata, kuid ainult API kaudu — Ukus roteerimisnuppu pole. Kõik õigusega võti saab kutsuda POST /api/v3/auth/keys/{key_id}/rotate, mis väljastab asenduse ja hoiab vana võtme töökorras 24-tunnise leebe perioodi jooksul, nii et saad uue väärtuse kasutusele võtta ilma seisakuta. Võtme kustutamine kasutajaliideses, seevastu, tühistab selle kohe.