Avalik API v3

Selle artikli lõpuks oled loonud API v3 võtme, teinud autenditud päringu ja tead, kuidas Uku finantsandmeid piirab, rahakirjeid versioonib ja päringute arvu piirab.

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

Avalik API äpp avaneb kolme vahekaardiga: Ülevaade, (old) API vana v1.0 API jaoks ning Avalik API — praegune v3 API, kus sa oma aja veedad. Äpp avaneb sellel vahekaardil.

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

• See ulatub kogu tooteni. Projektidel, eelarvetel, märkmetel, manustel, tööajal ja delegeerimistel lihtsalt ei ole v1.0 lõpp-punkti.
• Vead ütlevad, mis valesti läks. Iga viga kannab püsivat koodi, mille järgi sinu integratsioon saab hargneda, mitte lauset, mida stringina otsida.
• Võtmeid saab kitsendada. Anna raportitööriistale ainult lugemisõigus, seo võti IP-aadressi järgi oma serveritega, määra aegumiskuupäev — midagi sellest v1.0 ei paku.

Vana API töötab edasi ja sinu olemasolevad integratsioonid töötavad edasi — see on külmutatud, mitte välja lülitatud. Võtmed ei ole omavahel vahetatavad: v1.0 võti v3-s ei autendi ja v3 võti v1.0-s ei tööta. Mõlemad võivad üleminekul kõrvuti aktiivsed olla.

API v3 võtme lood Uku Avalik API äpist. Iga võti kuulub sinu ettevõttele ja selle loonud inimesele 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. Täida nime väli, mis ütleb, mis seda kasutab, näiteks „Power BI raportid” või „Lao sünkroniseerimine”. Välja vihje on ingliskeelne: Võtme nimi — nt Power BI aruandlus.
3. Vali integratsiooni jaoks vajalikud Õigused:
   • Lugemine — ainult andmete lugemine.
   • Muuda — lugemine, pluss igapäevaste kirjete loomine, uuendamine ja kustutamine. Näiteks kliendid, kontaktid, ülesanded ja ajakirjed.
   • Kõik — kõik eelnev, pluss API võtmete haldamine.
4. Otsusta Kaasa finantsandmed (arved, tulu, hinnad, eelarved) üle. See on eraldi märkeruut, mitte neljas õigus — vaata allpool Rahaandmed on eraldi õigus. Kõik valimine märgib selle sinu eest ära ja lukustab peale.
5. Soovi korral ava Lisavalikud. Seal saad määrata Aegub (valikuline) kuupäeva või Lubatud IP-aadressid (valikuline) loendi, et võti töötaks ainult sinu serveritest. Loend võtab komaga eraldatud aadresse või CIDR-vahemikke, näiteks 192.168.1.1, 10.0.0.0/24.
6. Klõpsa Loo API võti. Täielik võti (algab uku_live_-ga) kopeeritakse lõikelauale ja kuvatakse üks kord — „Copy this key now — it will not be shown again.” Salvesta see salasõnahaldurisse või saladuste hoidlasse. Klõpsa seejärel Valmis.

Pärast seda loetleb tabel võtme Nimi, Võtme eesliide, Õigused, Lisas, Viimati kasutatud, Aegub ja Koostatud — mitte kunagi võtit ennast. Õigused veerg ühendab mõlemad valikud üheks sildiks: näed Lugemine, Lugemine + finantsandmed, Muuda, Muutmine + finantsandmed või Kõik. Prügikasti ikoon kustutab võtme, mis tühistab selle kohe kõigi integratsioonide jaoks, mis seda veel kasutavad.

Iga eespool kirjeldatud võti on integratsioonivõti. See kuulub ettevõttele, kannab valitud õigusi ja käitub ühtemoodi, kes päringu ka ei käivitaks.

API oskab luua ka isikliku võtme, mis tegutseb ühe nimelise kasutajana. Iga selle päring on piiratud sellega, mida see inimene Ukusse sisse logides näeb ja muuta saab. Kui ta klienti avada ei saa, ei saa ka võti. Loo selline võti, saates kind: 'personal' ja kasutaja id aadressile POST /api/v3/auth/keys võtmega, millel on Kõik õigus.

Vali isiklik võti siis, kui kutsuja peaks olema päris inimene. Näiteks assistent, kes vastab küsimusele „mis on mu selle nädala ülesanded?”. Vali integratsioonivõti siis, kui kutsuja on süsteem, näiteks öine sünkroniseerimine.

POST /auth/keys kaudu loodud isiklik võti on meelega kitsas ja seda laiendada ei saa:

• Selle õigused on fikseeritud lugemisele ja kirjutamisele. Kõik küsida ei saa ja scopes väärtuse saatmine tagastab 400.
• Finantsligipääsu nii kunagi ei anta, olgu inimese õigused Ukus millised tahes. Raharessursid vastavad 403 FINANCIAL_SCOPE_REQUIRED. Ainus erand on allpool kirjeldatud brauseris sisselogimine.
• Võtmete haldamisest keeldutakse, ka võtme enda puhul. Iga /auth/keys päring tagastab 403 PERSONAL_KEY_CANNOT_MANAGE_KEYS.

„Ettevõtteülene” kirjeldab andmeid, mida integratsioonivõti näeb, mitte identiteedi puudumist. Iga võti jätab meelde, kes selle lõi. Mõni õiguste kontroll käib selle inimese järgi, olgu võti mis liiki tahes: kliendi kustutamine, kasutajate haldamine ja dokumenditüüpi märkmete kirjutamine.

Kõik, mis raha liigutab, vajab Kaasa finantsandmed märkeruutu — nii lugemiseks kui kirjutamiseks. Ilma selleta tagastab päring, mis finantspinda puudutab, 403 FINANCIAL_SCOPE_REQUIRED, olgu võtme õigus milline tahes.

Märkeruut asub kolme õiguse kõrval, mitte nende sees, ja see ongi kasulik osa: finantsligipääs ja kirjutusõigus on teineteisest sõltumatud valikud. Lugemine + finantsandmed võti saab tõmmata arvete summasid raportitöölauale, suutmata samal ajal ühtki kirjet muuta. Analüütika jaoks on see õige kuju.

Piiraval väraval on kaks kuju ja sama jaotus kehtib nii lugemisel kui kirjutamisel.

Terve kirje. Arved ja nende read, lepingud ja nende read, kasutajate kokkulepped, toodete hinnad, arve väljastajad, monitorid, maksud, eelarved ja tööaeg on piiratud tervikuna. Ilma märkeruuduta tagastavad need 403 isegi GET-päringul, sealhulgas GET /products/{id}/prices. Nii kukub hinnakirja sünkroniseerimine Lugemine võtmega läbi juba esimese päringu peal. Iga kirjutamine on keelatud, ükskõik millist välja sa muutsid. Lepingu ümbernimetamine vajab märkeruutu sama palju kui selle arveldusperioodi muutmine: kui Muuda võti saaks muuta „ainult nime”, saaks ta lugeda kirjet, mida tal näha ei tohi.

Ainult rahaväljad. Tooted ja kasutajad jäävad ilma märkeruuduta loetavaks ja muudetavaks, aga nende rahaväljad mitte. Toode tuleb tagasi tühjade hindade, maksuseadete, arveldusaluse ja raamatupidamise koodidega, kasutaja tühjade saldodega. Nende muutmine vajab märkeruutu ja lisaks If-Match versioonitemplit.

Raha kirjutamine vajab alati mõlemat poolt: märkeruutu ja õigust, mis lubab kirjutada.

Lepingu status ei ole midagi, mida sa ise määrad: Uku tuletab selle kuupäevadest — enne perioodi ootel, perioodi sees aktiivne, pärast lõppenud. Sellest sõltub ka see, kas saad lepingu kustutada. Aktiivsest või lõppenud lepingust keeldutakse veaga 409 CONTRACT_LOCKED. Nihuta kogu kuupäevavahemik tulevikku, nii et tuletatud staatus muutub ootel olevaks, ja kustuta siis.

API v3 avab arve elutsükli tegevused — saatmise ja makstuks märkimise — lõpp-punktidena. Kõik vajavad finantsligipääsu ja If-Match versioonitemplit:

• POST /invoices/{id}/send paneb arve saatmise järjekorda (e-kiri, PDF, e-arve) ja tagastab 202. Arve läheb välja taustal ja status muutub sent-iks, kui see on lõpetatud. Sobib olekus created, sent või paid, muidu 409 INVOICE_NOT_SENDABLE.
• POST /invoices/{id}/mark-paid märgib makse ja viib arve olekusse paid. Sobib ainult olekus created või sent, muidu 409 INVOICE_NOT_PAYABLE.

Sinu esimene API v3 päring on tavaline HTTPS-päring kahe päisega. Sisselogimise päringut ega uuendatavat tokenit ei ole.

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

Õnnestunud loendipäringud mähivad kirjed data sisse ja lisavad lehitsemiseks meta ploki. Iga lõpp-punkti täpne kuju on interaktiivses liivakastis.

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

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

Mõni viga — näiteks tagasi lükatud päringukeha — lisab details loendi, mis nimetab vigased väljad.

Uku avaldab API v3 jaoks elava interaktiivse liivakasti. Seal on iga lõpp-punkt koos päringu ja vastuse skeemidega ning Try it out nupp, mis teeb sinu võtmega päris päringuid sinu ettevõtte vastu. See on kiireim viis näha lõpp-punkti täpset kuju enne koodi kirjutamist. Liivakast on alati ajakohane, sest see genereeritakse töötavast API-st.

• app.getuku.com/api/v3/docs — interaktiivne liivakast (Swagger UI). Kleebi oma Ettevõtte UUID ja API võti üks kord sisse ning kutsu lõpp-punkte otse lehelt.
• app.getuku.com/api/v3/redoc — sama teatmik ainult lugemiseks, hõlpsamini sirvitavas kujunduses.
• app.getuku.com/api/v3/openapi.json — masinloetav spetsifikatsioon. Anna see oma arendajale, API-kliendile nagu Postman või Insomnia või AI-kooditööriistale, mis genereerib kliendi.
• app.getuku.com/api/v3/llms.txt — tekstiline kokkuvõte AI-assistentidele, täielik teatmik aadressil llms-full.txt.
• app.getuku.com/api/v3/capabilities — masinloetav loend sellest, mida API praegu oskab, genereeritud töötavast koodist. Võtit ei ole vaja. Kontrolli enne mandaatide olemasolu, kas Uku midagi toetab, ja lase oma integratsioonil see käivitumisel lugeda, selle asemel et vananevaid eeldusi koodi kirjutada. Selle not_available loend vastab küsimusele „miks selle jaoks lõpp-punkti ei ole?”. Loend nimetab, mida Uku meelega välja jätab ja mida selle asemel kasutada. Kasutaja aktiveerimine on üks neist: see jääb backoffice’i tegevuseks. Anda API võtmele õigus kellelegi büroo andmetele ligipääs anda ei ole vahetus, mida Uku teeb.
• app.getuku.com/api/v3/changelog — API enda ülevaade sellest, mis ja millal muutus. Loe seda enne, kui eeldad, et kuude eest testitud käitumine kehtib endiselt.

API v3 ulatub peaaegu kogu Ukuni. Need on ressursiperekonnad, mida see avab. Alati ajakohane lõpp-punktide loend on interaktiivses liivakastis.

• Kliendid ja kontaktid — kliendid, kontaktid, kliendigrupid, märkmed ja kliendi kasutajad (iga inimese roll kliendil, sealhulgas kliendiportaali märge).
• Töö — ülesanded, ülesannete seosed, ülesannete automaatika, delegeerimised, projektid, teemad, tööplaani rollid ja rollid. Ülesannetel on ka oma lõpp-punktid lõpetamiseks ja uuesti avamiseks, kontroll-loendid, kommentaarid ja paljude ülesannete korraga muutmine.
• Tööplaanid — kliendi tööplaani mallid ja nende ülesanded. Rakenda mall paljudele klientidele korraga või lükka malli muudatused juba seda kasutavatele klientidele. Projekti tööplaanidel on oma komplekt.
• Aeg — ajakirjed, kalender (puhkuse, vaba aja ja tööaja kirjed ning riiklikud pühad), tööaeg ja tööaja saldod.
• Arveldamine — arved ja read, lepingud ja read, tooted ja hinnad, maksud, arve väljastajad, eelarved, monitorid ning ettevõtte arveldamise vaikeseaded. Samuti kliendi arvete genereerimine ja nende eelvaade. Arved kannavad ka välju process_status ja process_error. Need ütlevad, et arveldusmootor ei suutnud arvet hinnastada, mis muidu näeb välja nagu tavaline Töös arve. Filtreeri neid päringuga ?has_process_error=true.

• Inimesed — kasutajad ja nende kokkulepped, tiimid ning kasutajate muutmine paljudel klientidel korraga.
• Raportid — ajakokkuvõtted, ettevõtteülene KPI hetkeseis ja BI-numbrid analüütika töölaudade taga. Rahanumbrid ilmuvad ainult finantsligipääsuga võtmele.
• Otsing ja tegevused — üks otsing arvete, kontaktide, tarnijate, lepingute, ülesannete ja märkmete ülemuselt, pluss tegevuste jälg väljade tasemel enne- ja pärast-väärtustega. Kliendid ei ole otsingukategooria. Kliendi nime järgi leidmiseks kasuta kliendiloendil ?q= või GET /resolve, mis muudab nime otse id-ks.
• Sinu enda mandaat — GET /auth/me vastab, mida sinu käes olev võti teha tohib. See annab ettevõtte, inimese, kellena võti tegutseb, õigused ja päringupiirangu tasemed.
• Dokumendid ja kaustad — kliendi kaustapuu, kaustamallid ja dokumendid ise ühendatud Google Drive’is, Dropboxis või SharePointis.
• Digiteerimine — saada kliendi dokumendid digiteerimisele ja vaata, mis tagasi tuli.
• Sinu raamatupidamistarkvara — loe seal olevaid arveid, kanna Uku arve sinna üle ja küsi, kas arve on makstud. Sünkroniseerida saab ka maksu- ja tootekoode.
• Seadistus — kohandatud väljad, tooteväljad, tarnijad, sisumallid ja ettevõtte äpid. GET /company/apps ütleb, millised on aktiivsed, ja POST /company/apps/{id}/activate lülitab ühe sisse. Nii saab aktiveerida ainult Arveldamise, E-posti, Ärianalüütika ja Tööjõuhalduse. Mõni neist lülitab sisse ka teisi ja lugemispäring ütleb enne kirjutamist, millised. Väljalülitamise lõpp-punkti meelega ei ole.
• Failid — manused ülesannetel ja märkmetel (kuni 150 MB faili kohta; käivitatavad failid lükatakse tagasi).

Mõnele päringule ei saa kohe vastata. Tööplaani malli rakendamine või lükkamine paljudele klientidele ja kasutajate muutmine paljudel klientidel vastavad selle asemel töö tunnusega. Edenemist küsi päringuga GET /jobs/{id}.

Uku märgib osa lõpp-punkte dokumentatsioonis sildiga Preview ja need tagastavad päise X-Api-Preview: true. Need on täiesti kasutatavad — silt tähendab, et kuju võib veel muutuda, seega seo oma integratsioon sellega, mida testisid.

API v3 loendilõpp-punktid jagavad samu päringuparameetreid lehitsemiseks, filtreerimiseks ja sortimiseks. Nii kandub see, mida ühel ressursil õpid, enamasti üle teistele. Mõni ressurss toetab vähem kui täiskomplekti — interaktiivne liivakast näitab täpselt, mida igaüks vastu võtab.

• Lehitsemine — ?limit= ja ?offset= (algab nullist). Enamik loendeid võtab 1–200 ja vaikimisi 50, aga mõni vaikimisi 100 ja tegevuste jälg peatub sajal. Loe lõpp-punkti enda vahemikku liivakastist, ära eelda. meta.has_more ütleb, millal järgmist lehte tõmmata. Üle 10 000 kirje lehitse ?cursor= abil seal, kus ressurss seda pakub, ja järgi meta.next_cursor.
• Filtreerimine — kasuta operaatori järelliidet: ?client_id.eq=123, ?date.gte=2026-01-01, ?status.in=created,sent, ?topic_id.neq=4. Vabateksti ?q= on paljudel ressurssidel, aga mitte kõigil. Kohandatud väljad filtreeruvad kujul ?custom_fields.<nimi>=väärtus. Nimeta väli nii, nagu inimene seda nimetaks: töötab nii pealkiri SECRET kui ka salvestatud nimi, suurtähtedest sõltumata. Kahest sama pealkirjaga eri väljast keeldutakse, selle asemel et nende vahel arvata.
• Sortimine — ?sort=name kasvavalt, ?sort=-created_at kahanevalt. Väli, mille järgi ressurss ei sordi, jäetakse vahele, mitte ei lükata tagasi. Saad 200 vaikimisi järjekorras ja miski ei ütle, et sortimist ei arvestatud. Kontrolli esimest lehte, ära eelda.

Filtreeri raskeid lõpp-punkte (ülesanded, ajakirjed, arved) alati kuupäeva või ülemkirje järgi, selle asemel et kõike tõmmata.

Et avastada, mille järgi ressurss filtreerida oskab, saada ?zzz.eq=1 ja loe loendit, millega sind tagasi lükatakse.

Kui sinu integratsioon kontrollib Ukut ajakava järgi, vähendavad kaks võimalust iga kontrolli hinda.

Küsi ainult muutunut. GET /tasks/{id}, GET /clients/{id} ja GET /invoices/{id} tagastavad ETag-i. Saada see järgmisel sama kirje lugemisel tagasi päisena If-None-Match. Kui midagi ei muutunud, vastab Uku 304 Not Modified tühja kehaga ja jätab kirje uuesti kokku panemata.

Küsi ainult neid välju, mida kasutad. GET /tasks, GET /clients ja GET /invoices võtavad vastu ?fields=, komaga eraldatud loendi võtmetest, mida soovid. id tuleb alati kaasa, nii et tulemused jäävad ühendatavaks. Parameetri ära jätmine ei muuda midagi.

Osa väljajätmisi säästab päris tööd, mitte ainult baite. assignees ja comments ära jätmine ülesannete loendist või rows arvetelt jätab nende taga olevad lisapäringud tegemata. Arve võib kanda kuni 200 rida. Väljanimest, mida Uku ei tunne, keeldutakse veaga 400 VALIDATION_ERROR, mis loetleb kehtivad nimed, nii et sinu integratsioon saab end parandada.

API v3 piirab iga võtme lugemisi ja kirjutamisi eraldi: 120 lugemispäringut ja 30 kirjutamispäringut minutis. Kui päring läheb sinu võtme eelarve arvele, kannab vastus nelja päist:

• X-RateLimit-Limit — sinu lubatud arv seda tüüpi päringute jaoks.
• X-RateLimit-Remaining — kui palju sel minutil alles on.
• X-RateLimit-Reset — millal loendur nullitakse.
• X-RateLimit-Tier — kumma eelarve arvele läks, read või write.

Neid ei ole igal vastusel, seega ära nõua neid. Ilma nendeta tulevad tagasi võtmeta läbi läinud päringud, dokumentatsiooni lõpp-punktid ja iga hetk, mil Uku piirangute hoidla on lühiajaliselt kättesaamatu. Viimasel juhul ei jõustata piirangut üldse.

Kui ületad võtme eelarve, vastab API 429 RATE_LIMIT_EXCEEDED koos päisega Retry-After. Oota see aeg ära, selle asemel et kohe uuesti proovida.

Teine piirang loeb iga päringut sinu IP-aadressilt, olgu võti milline tahes, ja seda kontrollitakse enne võtme eelarvet. See on meelega helde — 1000 päringut minutis — sest jagatud aadress, näiteks Zapieri või Make’i väljumissõlm, kannab korraga paljude büroode liiklust. Päringuid, mis saabuvad ilma võtmeta, hoitakse samalt aadressilt palju rangema 60 minutis piiri sees.

Mõlemad vastavad samas kujus nagu iga teine keeldumine: 429 RATE_LIMIT_EXCEEDED JSON-kehas koos Retry-After ja X-RateLimit-* päistega. Nii saad ka siin error.code järgi hargneda täpselt nagu mujal.

Idempotentsuse võti laseb sul API v3-s loomispäringut korrata ilma topeltkirje riskita. Kui loomine aegub, ei tea sa sageli, kas see läbi läks. Saada siis algses päringus päis Idempotency-Key (mis tahes unikaalne string, mille ise genereerid). Kordus sama võtmega ja baidihaaval identse kehaga mängib algse vastuse uuesti, selle asemel et teine kirje luua, ja vastus kannab Idempotency-Replayed: true. Uku mäletab iga võtit 24 tundi.

Baidihaaval identne on sõna-sõnalt: Uku võtab toorbaitidest sõrmejälje ega korrasta JSON-i enne. Nii loeb kordus, mis kirjutab keha võtmed teises järjekorras, teiseks päringuks ja saab 409. Hoia esimese katse keha alles ja saada täpselt needsamad baidid.

Peaaegu iga loomislõpp-punkt võtab päise vastu. Samuti paljud tegevused, mis kirje olekut muudavad: arve saatmine, makstuks märkimine, ülesande lõpetamine, tööplaani malli rakendamine.

Siin olev loend vananeks, seega loe praegust API-st endast. app.getuku.com/api/v3/capabilities tagastab selle data.idempotency all ja nimetab välja jäänud lõpp-punktid koos põhjusega. Võtit ei ole vaja.

Kaks asja tagastavad selle asemel 409. Kordamine ajal, mil esimene päring alles käib, annab IDEMPOTENCY_CONFLICT — oota ja proovi uuesti. Võtme taaskasutamine teistsuguse kehaga annab IDEMPOTENCY_KEY_REUSED — kasuta iga eri päringu jaoks uut võtit.

Veebihaagid lasevad Ukul sinu lõpp-punkti kutsuda, kui midagi muutub, selle asemel et sinu integratsioon Ukut pidevalt küsiks. Telli URL sündmusele ja iga kord, kui see sündmus juhtub, saadame kirje sinu lõpp-punkti, allkirjastatult ja korduskatsetega. Sündmused katavad kliendid, kontaktid, ülesanded, projektid, arved ja ajakirjed.

v3 tellimusi jälgid ja haldad Ukus endas. Avalik API vahekaardil on Ühendatud webhookid loend. See näitab iga tellimuse staatust, ebaõnnestumiste arvu ja hiljutisi saatmisi. Nupud lubavad tellimuse peatada või taaskäivitada, kustutada ja ebaõnnestunud saatmist korrata. Tellimused luuakse API kaudu, mitte siin. Mõlema mootori täielik kirjeldus — tellimine, saadetise sisu, allkirja kontroll, korduskatsed ja kordussaatmine — on artiklis Veebihaagid.

Rahaga seotud kirjeid kaitseb versioonitempel selle eest, et kaks süsteemi teineteist üle ei kirjutaks. Reegel on: raha kandev kirje tahab templit iga olemasoleva kirje muudatuse juures, ükskõik millist välja sa puudutad, tavalised kirjed — ülesanded, kliendid, kontaktid, ajakirjed — aga mitte kunagi. Tooted ja kasutajad on vahepealne juht: nende tavaliste väljade muutmine templit ei vaja, rahaväljade muutmine vajab.

Milliste kirjutamiste juures templit vaja on, hoitakse ühe loendina API enda teatmikus. Nii see vananeda ei saa. Vaata täielikku teatmikku või ava lõpp-punkt interaktiivses liivakastis. Liivakast näitab If-Match päist iga kirjutamise juures, mis seda võtab.

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

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

API v3 võti avab sinu ettevõtte elavad andmed sellele, kes seda hoiab. Kohtle seda sama kaalu mandaadina nagu Uku enda salasõna.

• Anna väikseim õigus, mis töötab. Raportitööriist, mis loeb raha, vajab Lugemine + finantsandmed, mitte Kõik — just selleks eraldi märkeruut ongi. See, mis raha ei loe, vajab ainult Lugemine.
• Seo võtmed oma serveritega IP-loendi abil ja määra ajutistele Expires at kuupäev.
• Võtme kustutamine tühistab selle kohe kõigi integratsioonide jaoks, mis seda veel kasutavad. See on lekke lahendus, aga see katkestab kõik, mis seda võtit veel hoiab.
• Kutsu alati üle HTTPS-i. Päring aadressile http:// lükatakse tagasi veaga 403 HTTPS_REQUIRED, aga see lükatakse tagasi pärast saabumist, nii et võti on juba krüpteerimata üle võrgu liikunud. Kohtle iga võtit, mille oled kunagi üle tavalise HTTP saatnud, lekkinuna: kustuta see ja loo uus.
• Võti ulatub alati ainult sinu enda ettevõtte andmeteni. Teisele ettevõttele kuuluvad kirjed tagastavad 404, mitte vea, mis nende olemasolu paljastaks.

Avalik API ja (old) API vahekaardid ilmuvad ainult Ettevõtte omanikele ja peakasutajatele ning alles siis, kui Avalik API äpp on sinu ettevõtte jaoks Elite paketis aktiveeritud. Kui satud Ülevaate peale ja kõrval ei ole midagi, siis on põhjus see: aktiveeri äpp sellelt ekraanilt või palu Ettevõtte omanikul seda teha. Ettevõtte kasutajad ei näe API võtmeid üldse.

Avalikku API v2 ei ole kunagi olnud. Uku läks v1.0 pealt otse v3 peale, seega ei ole v2, mille kaudu üle minna, ei ole v2 võtmeid ega /api/v2/ lõpp-punkte. Kui kolid v1.0 pealt ära, on v3 järgmine ja ainus samm. Numbrihüpe peegeldab muutuse suurust, mitte versiooni, millest ilma jäid.

v1.0 võti ei saa v3-s autentida — kaks versiooni kasutavad eraldi mandaate. Loo Avalik API vahekaardil uus võti ja mine üle kahe päisega sisselogimisele (X-Uku-Company + X-API-Key). v3-s ei ole /login päringut ega JWT-d.

X-Uku-Company päis puudub päringul või on tühi. Kopeeri Ettevõtte UUID Avalik API vahekaardi ülaosast ja saada see iga päringuga koos API võtmega. Kui autendid X-API-Key abil, on mõlemad päised kohustuslikud — võtmest üksi ei piisa.

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

Kui veakood on täpsemalt FINANCIAL_SCOPE_REQUIRED, puudutas päring finantsandmeid. Finantspind katab arved, lepingud, kokkulepped, arve väljastajad, monitorid, maksud, eelarved, tööaja ja toodete hinnad, samuti kasutaja või toote rahavälja. See vajab Kaasa finantsandmed märkeruutu, nagu on kirjeldatud jaotises Rahaandmed on eraldi õigus. Võtmeid pärast loomist muuta ei saa, seega loo asendus märgitud ruuduga ja kustuta vana.

Väljanimi ei ole see, mille järgi see lõpp-punkt filtreerib. Loe veakehast details.allowed — see loetleb iga nime, mida sa kasutada oleksid saanud — ja paranda kirjaviis või vali õige väli. Vaata Lehitsemine, filtreerimine ja sortimine.

Keeldumine on API viis öelda sulle varakult, selle asemel et valesid andmeid tagasi anda. Filtri nimest, mida Uku ei tunne, keeldutakse, seda ei jäeta vahele. Nii tähendab 200, et sinu filtrist saadi aru.

Kontrolli kõigepealt ?sort=: sortimisvälja, mida ressurss ei tunne, jäetakse vaikselt vahele ja see on ainus päringuparameeter, mis endiselt niimoodi käitub. Kui filter tuli tagasi koodiga 200 ja kõigega, on väli päris ja selle väärtus sobis iga kirjega. Kontrolli väärtust, mille saatsid, mitte nime.

.neq on otsene „ei võrdu” võrdlus, seega jätab see välja iga kirje, mille väli on tühi.

Võta ?topic_id.neq=4. See tagastab teise teemaga ülesanded, aga mitte ülesandeid, millel teemat üldse ei ole. Loendist, mida loed kui „kõik peale teema 4”, on puudu nii palju kirjeid, kui paljul teemat määratud ei ole.

Miski sind ei hoiata: vastus on tavaline 200 usutava välimusega loendiga. Kui vajad ka tühjasid, tõmba need eraldi ja ühenda kaks loendit ise.

See, kuidas vale filtriväärtus ebaõnnestub, sõltub välja tüübist. Numbreid, kuupäevi ja tõene-väär välju kontrollitakse, seega väärtus, mida selliseks lugeda ei saa, tagastab 422 INVALID_FILTER_VALUE koos oodatud tüübiga details all. Tekstivälju ei kontrollita, seega vale väärtus seal lihtsalt ei sobi millegagi ja tagastab 200 tühja data massiiviga — eristamatu õigest filtrist, millel vasteid ei ole.

Ülesande status on koht, kus see kõige sagedamini hammustab. Väärtus, mida Ukus näed, ei ole alati see, mida API salvestab. Sisemine komplekt on new, in_progress, finished, inactive ja archived. .eq kasutades pead saatma täpselt ühe neist. Tavaline ?status= kuju on andestavam ja võtab vastu levinud sünonüüme.

Aadressil app.getuku.com/api/v3/docs on interaktiivne liivakast, kus saad iga lõpp-punkti brauserist kutsuda. See töötab aga sinu päris ettevõtte vastu, sest API v3 väljastab ainult elavaid võtmeid (uku_live_). Eraldi testettevõtet ega testvõtit ei ole. Ehitamise ajal kirjuta väikese selgelt nimetatud kliendi peale, mille saad pärast kustutada.

Võtit saab vahetada ilma integratsiooni katkestamata, aga ainult API kaudu — Ukus rotatsiooninuppu ei ole. Kõik õigusega võti saab kutsuda POST /api/v3/auth/keys/{key_id}/rotate, mis väljastab asenduse ja hoiab vana võtme 24 tundi töös. Nii saad uue väärtuse kasutusele võtta ilma seisakuta. Võtme kustutamine liideses tühistab selle seevastu kohe.