Avalik API v1.0 (vana)

API v1.0 on enamasti lugemiseks mõeldud liides piiratud osale Ukust. See autendib kümme minutit kehtiva tokeniga. Versioon töötab edasi integratsioonide jaoks, mis ehitati enne v3 tulekut.

v1.0 API võtmepaare saavad luua ja hallata Ettevõtte omanikud ja Ettevõtte peakasutajad Elite paketiga.

API v1.0 annab juurdepääsu järgmisele:

• Kliendid — klientide loetlemine, filtreerimine ja loomine
• Kontaktid — ühe kontakti otsimine id järgi või kliendi ja e-posti aadressi järgi ning klientidega seotud kontaktisikute loomine. Kontaktide nimekirja endpointi ei ole ja kontakte ei saa lehekülgede kaupa laadida
• Kliendigrupid — kliendigrupi struktuuride lugemine
• Kliendi lisaväljad — klientidele seadistatud lisaväljade definitsioonide lugemine. Iga kliendi enda väärtused tulevad kliendi kirjega kaasa
• Ülesanded — ülesannete loetlemine, filtreerimine ja loomine
• Ülesande lisaväljad — ülesannetele seadistatud lisaväljade definitsioonide lugemine. Iga ülesande enda väärtused tulevad ülesande kirjega kaasa
• Ajakirjed — jälgitud ajaandmete päringud
• Kasutajad — tiimi kasutajate loetlemine
• Kasutajagrupid — kasutajagrupi struktuuride lugemine
• Arved — arveandmete päringud
• Lepingud — lepinguandmete päringud
• Tooted — toodete loetlemine
• Tooteväljad — arveldamise viitenimekirjade lugemine, millest tooted väärtusi võtavad, näiteks artiklid, ressursid, kulukeskused ja projektid
• Arve müüjad — arve müüja profiilide lugemine
• Teemad — ülesannete teemade loetlemine
• Veebihaagid — URL-i tellimine uue kliendi ja uue kontakti sündmustele

Vastused on JSON-vormingus. v1.0 on põhiliselt lugemiseks mõeldud API: luua saab ainult kliente, kontakte, ülesandeid ja veebihaagi tellimusi. Midagi ei saa uuendada ning kustutada saab ainult veebihaagi tellimust, et sellest loobuda. Kui pead Ukusse tagasi kirjutama, kasuta API v3.

v1.0 kaudu tellitud veebihaagid töötavad edasi. Need käivituvad ühel kitsal juhul: kui klient või kontakt luuakse Uku veebirakenduses. API kaudu, impordiga, automaatikaga või Kliendiportaalis loodud kirje v1.0 teavitust ei tekita. Versioon v3 kasutab eraldi veebihaagi mootorit, millel on oma sündmused ja andmevorming. Seega jätab v3-le üleminek sinu olemasolevad tellimused puutumata. v1.0 tellimus saadab andmeid edasi oma algses vormingus, mitte v3 vormingus.

Avalik API on äpp, mille lülitad oma ettevõttele sisse, nagu iga teise Uku integratsiooni.

Tee: Seaded & Äpid

1. Leia kaart Avalik API. Äpid on rühmitatud jaotistesse Setup, Power up ja Integrations. Avalik API on integratsioonide all ja kannab Elite märgist, sest see on Elite funktsioon.
2. Ava äpp ja aktiveeri see oma ettevõtte jaoks.

Kui lülitad Avalik API äpi välja, lakkavad kõik v1.0 võtmepaarid järgmisel päringul töötamast. Sama juhtub, kui sinu ettevõtte pakett lõpeb.

v1.0 mandaat on paar: API võti ja API salajane võti. Sul võib olla korraga mitu paari, iga integratsiooni jaoks üks.

Tee: Seaded & Äpid → Avalik API → (old) API

1. Ava Avalik API äpp ja mine vahekaardile (old) API.
2. Sisesta oma API võtmepaarile Nimi (näiteks „Raporteerimistööriist” või „Zapieri integratsioon”).
3. Klõpsa Loo uus API võti.
4. Ilmub hoiatuskast Copy this secret now — it will not be shown again. Selles on sinu uus API võti ja API salajane võti. Klõpsa Kopeeri, et salajane võti kopeerida, ja hoia see turvalises kohas.
5. Klõpsa Valmis. Kast sulgub ja salajast võtit ei saa enam uuesti vaadata.

Tabelis on seejärel iga võtmepaari nimi, API võti ja viimase muutmise kuupäev. API võtme juures on kopeerimisnupp, sest ainult võtmega sisse logida ei saa. Salajast võtit tabelis ei ole. Varem loodud võtmepaarid töötavad edasi, aga ka nende salajast võtit enam ei näidata.

Kustuta võtmepaar, klõpsates tabelis prügikasti ikooni. Ligipääs lõpeb kohe: iga seda paari kasutava integratsiooni järgmine päring lükatakse tagasi, isegi kui selle token ei ole veel aegunud. Kui v1.0 salajane võti on lekkinud, kustuta paar ja loo integratsioonile uus.

Saada POST-päring sisselogimise endpointile oma API võtme ja salajase võtmega:

POST https://app.getuku.com/api/v1.0/login
Content-Type: application/json

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret"
}

Vastus sisaldab JWT tokenit:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Lisa token kõikide järgnevate päringute autoriseerimispäisesse:

GET https://app.getuku.com/api/v1.0/clients
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT tokenid aeguvad 10 minuti pärast. Kui token aegub, autendi uuesti, et saada uus. Kujunda oma integratsioon nii, et see käsitleks uuesti autentimist automaatselt.

Interaktiivne API dokumentatsioon on saadaval aadressil app.getuku.com/docs/sandbox/. Seal saad testida endpointe, vaadata päringu- ja vastuseskeeme ning proovida päringuid otse brauserist. Pane tähele, et veebihaagi tellimuse endpointi seal ei kajastata — see on olemas, aga sandbox seda ei dokumenteeri.

v1.0 võtmepaar ulatub sinu ettevõtte päris andmeteni. Hoia seda nagu salasõna.

• Hoia oma API salajast võtit konfidentsiaalsena. Kohtle seda nagu salasõna. Ära kunagi lisa seda versioonihaldusse ega jaga lihttekstina.
• Kasuta eraldi võtmepaare eri integratsioonide jaoks. Kui üks lekib, saad kustutada ainult selle paari, ilma et see mõjutaks teisi.
• Tokenid on lühiajalised. 10-minutiline aegumisaken piirab kokkupuudet, kui token peaks pealtkuulamisel kätte langema.
• Kustuta kasutamata võtmed. Kui lõpetad integratsiooni kasutamise, eemalda selle API võtmepaar viivitamatult.
• Kasuta alati HTTPS-i. API baas-URL kasutab TLS-krüpteeringut. Ära saada võtit, salajast võtit ega tokenit kunagi tavalise HTTP kaudu.

v1.0 võti tegutseb selle loonud inimesena. Tagastatav token kannab lisaks ettevõttele ka selle inimese identiteeti ja API taga olevad teenused rakendavad tema enda ligipääsuõigusi. Kaks võtmepaari samas ettevõttes võivad seega õigustatult tagastada eri andmeid, olenevalt sellest, milliseid kliente kumbki looja näeb. Võti lakkab töötamast ka koos looja kontoga. Kui see inimene lahkub ettevõttest või tema konto deaktiveeritakse, annab järgmine päring vea ja POST /login lükatakse tagasi. Integratsioon jääb seisma, kuigi võtmepaar on tabelis alles. Kui keegi lahkub, kontrolli, millised integratsioonid tema võtmel töötasid, ja väljasta need paarid kellegi teise all uuesti.

Integratsiooni üleviimine API v3-le on peamiselt autentimise muutus. Seda saab teha ühe endpointi kaupa. Loo v3 võti samas Avalik API äpis ja jäta POST /login kutse ära. Versioonil v3 ei ole tokenivahetust, seega ei ole ka aegumist ega uuesti autentimise tsüklit. Iga päring kannab Bearer-tokeni asemel kahte päist; need on kirjas artiklis Avalik API v3.

Mõlemad võtmetüübid on korraga aktiivsed. Vii üle üks endpoint, kontrolli seda päris andmete vastu ja jäta ülejäänud integratsioon v1.0 peale, kuni oled valmis. Ressursside nimed on kahe versiooni vahel sarnased, aga mitte identsed. Kontrolli igaüht interaktiivsest dokumentatsioonist aadressil app.getuku.com/api/v3/docs, selle asemel et eeldada v1.0 tee ülekandumist.