Avalik API v1.0 (vana)

Ettevõtte omanikud ja Ettevõtte peakasutajad Elite paketiga.

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

• Kliendid — klientide loetlemine, filtreerimine ja loomine
• Kontaktid — klientidega seotud kontaktisikute loetlemine ja loomine
• Kliendigrupid — kliendigrupi struktuuride lugemine
• Kliendi lisaväljad — klientide kohandatud väljade definitsioonidele ja väärtustele juurdepääs
• Ülesanded — ülesannete loetlemine ja filtreerimine
• Ülesande lisaväljad — ülesannete lisaväljade definitsioonidele ja väärtustele juurdepääs
• 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
• Toote lisaväljad — toodete kohandatud väljade definitsioonidele ja väärtustele juurdepääs
• Arve müüjad — arve müüja profiilide lugemine
• Teemad — ülesannete teemade loetlemine
• Veebihaagid — reaalajas sündmuste teavituste tellimine

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.

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.
2. Ava äpp ja aktiveeri see oma ettevõtte jaoks.

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. Sinu uus API võti ja API salajane võti ilmuvad tabelis. Kasuta kopeerimisnuppu iga väärtuse kopeerimiseks.

Saad luua mitu API võtmepaari eri integratsioonide jaoks. Kustuta võtmepaar, klõpsates tabelis prügikasti ikooni. See blokeerib kohe uued sisselogimised nende mandaatidega, aga ei tapa juba väljastatud tokenit: v1.0 token kontrollitakse ainult allkirja ja aegumise järgi. Vahetult enne kustutamist loodud token töötab seega kuni aegumiseni. Just selles erineb v1.0 API v3-st, kus võtme tühistamine katkestab ligipääsu kohe. Kui v1.0 salajane võti on lekkinud, kustuta paar ja loe järgmised kümme minutit endiselt avatuks.

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...

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.

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.

• 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 kompromiteeritakse, saad tühistada ainult selle võtme, 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.
• Kõik päringud nõuavad HTTPS-i. API baas-URL kasutab TLS-krüpteeringut. Ära kunagi saada mandaate ega tokeneid tavalise HTTP kaudu.
• API juurdepääs on piiratud sinu ettevõttega. Iga võtmepaar on seotud kindla ettevõttega — saad juurde pääseda ainult oma ettevõttele kuuluvatele andmetele.

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 loojaga. Kui see inimene ei ole enam ettevõtte kasutaja, annab POST /login vea ja 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.