Sisällysluettelo
- Lue tämä ensin
- Roolit ja käyttöoikeudet
- Mikä on avoin API
- Mitä tietoja on saatavilla
- Mistä löydät sen
- API-avaimen luominen
- API-avainten hallinta
- Todennus
- API-dokumentaatio
- Usein kysytyt kysymykset
📖 Lue tämä ensin
Lue API-avainten luominen ennen kuin luot API-avaimen. Siinä kerrotaan vaihe vaiheelta, miten luot avaimen ja annat sille tarvittavat käyttöoikeudet.
Roolit ja käyttöoikeudet
| Rooli | Käyttöoikeus |
|---|---|
| Ylläpitäjät, joilla on pääsy Järjestelmäasetuksiin | Voivat luoda, muokata, poistaa käytöstä ja poistaa API-avaimia |
API-avain tarvitsee rooleja, jotta järjestelmän voi yhdistää avoimeen API:in. Roolit määräävät, mitä avain voi lukea ja muuttaa Humassa. Roolien antaminen avaimelle edellyttää oman järjestelmäroolinsa.
🔗 Katso Roolit Humassa, niin tiedät, miten roolit toimivat.
Mikä on avoin API
Avoin API on Human REST API. Sen avulla voit hakea ja päivittää Human tietoja ohjelmallisesti omista järjestelmistäsi tai integraatioista.
Avoin API toimii eri tavalla kuin webhookit. Webhookien avulla Huma lähettää sinulle tiedot automaattisesti aina, kun jokin muuttuu. Avoimen API:n avulla haet tai lähetät tiedot itse, milloin haluat.
🔗 Katso Webhookit, niin tiedät, miten Human automaattiset päivitykset toimivat.
Mitä tietoja on saatavilla
Avoimen API:n kautta pääset käsiksi Human työntekijä- ja organisaatiotietoihin. Tästä osiosta näet, mitä voit hakea ja päivittää. Näin voit arvioida, kattaako avoin API tarpeesi.
💡 Integraation määrittäminen avoimen API:n avulla vaatii teknistä osaamista. Määrittäjän pitää osata lukea teknistä API-dokumentaatiota. Jos teillä ei ole tätä osaamista talon sisällä, pyydä apua IT-kumppaniltasi tai järjestelmätoimittajaltasi.
⚠️ Se, mitä API-avain näkee ja voi muuttaa, riippuu sille antamistasi rooleista. Alla lueteltu kenttä on käytettävissä vain, jos avaimella on siihen käyttöoikeus.
🔗 Lue API-avainten luominen, niin tiedät, miten annat API-avaimelle rooleja.
Työntekijät
Voit hakea, luoda ja päivittää työntekijöitä.
| Alue | Kentät |
|---|---|
| Perustiedot | Etunimi, Sukunimi, Kutsumanimi, Sähköpostiosoite, Henkilökohtainen sähköpostiosoite, Puhelinnumero |
| Henkilötiedot | Syntymäpäivä, Sukupuoli, Kansallisuus, Siviilisääty, Kotiosoite |
| Työ | Työntekijätunnus, Esihenkilö, Tiimit, Toimipisteet, Yritykset, Asiaankuuluva kokemus, Kokemusmerkintä |
| Taloustiedot | Pankkitili |
| Muut | Erityisruokavalio, Kiinnostuksenkohteet, Tietoa minusta, Älä sisällytä Raportointi-moduuliin, Sulje pois Työtyytyväisyys eNPS-kyselyistä, Yrityskohtaiset kentät |
💡 Kun luot työntekijän, voit samalla lähettää hänelle kutsun Humaan.
Tehtävät
Voit hakea, luoda, päivittää ja poistaa työntekijän tehtäviä.
| Alue | Kentät |
|---|---|
| Tehtävät | Tehtävänimike, Yksilöllinen työnkuvaus, Sopimustyyppi, Työaika prosentteina, Sopimuksen alkamispäivä, Ensimmäinen työpäivä, Koeajan päättymispäivä, Maa / Lainsäädäntö, Kommentit, Irtisanomisilmoituksen päivämäärä, Viimeinen työpäivä, Sopimuksen päättymispäivä, Päättymisen tiedot (syy ja kommentti) |
Lapset, hätäyhteyshenkilöt ja henkilötunnukset
Voit lisätä, päivittää ja poistaa näitä työntekijältä. Ne haetaan yhdessä työntekijän tietojen kanssa.
| Alue | Kentät |
|---|---|
| Lapset | Nimi, Syntymäpäivä |
| Hätäyhteyshenkilö | Nimi, Puhelinnumero, Suhde |
| Henkilötunnus | Tyyppi (kansallinen henkilötunnus tai passi), Maa, Numero |
Ryhmät ja tehtävänimikkeet
| Alue | Mitä voit tehdä | Kentät |
|---|---|---|
| Tiimit, toimipisteet ja yritykset | Hakea, luoda ja päivittää | Nimi, Kuvaus, Linkit. Toimipisteillä ja yrityksillä on myös osoite. Yrityksillä on myös Y-tunnus. |
| Tehtävänimikkeet | Hakea, luoda ja päivittää | Nimi, Kuvaus |
Vain luku
Voit hakea nämä tiedot, mutta et muuttaa niitä avoimen API:n kautta:
- Työntekijän työaika-asetus
- Merkkipäivät
- Yleiset vapaapäivät maittain
- Nykyinen palkka sellaisena kuin se näkyy työntekijän profiilissa (summa, jakso ja valuutta). Käytettävissä vain, jos organisaatiosi käyttää Palkka-moduulia ja API-avaimella on käyttöoikeus palkkatietoihin. Palkkahistoria ja palkantarkistukset eivät ole saatavilla avoimen API:n kautta.
🔗 Katso kenttien tekniset tiedot API-dokumentaatiosta.
Mistä löydät sen
Löydät avoimen API:n näin:
- Siirry kohtaan Järjestelmäasetukset.
- Valitse vasemmasta valikosta Avoin API.
⛓️💥 API-dokumentaatio: https://openapi.humahr.com/redoc/index.html
API-avaimen luominen
- Siirry kohtaan Järjestelmäasetukset ja valitse Avoin API.
- Valitse Lisää API-avain.
- Anna avaimelle nimi ja lisää halutessasi kuvaus.
- Valitse Tallenna.
- Kun avain on luotu, näet sen Client ID:n ja Client secretin.
- ⚠️ Varmista, että tallennat Client secretin turvalliseen paikkaan.
- Sulje ikkuna. Avain avautuu luettelossa, joten voit antaa sille käyttöoikeudet heti.
⚠️ Varmista, että tallennat Client secretin turvalliseen paikkaan, sillä et näe sitä enää uudelleen. Suojaa API-avaimesi, sillä kuka tahansa, jolla se on, voi lukea tai muuttaa organisaatiosi tietoja. Jos kadotat Client secretin, sinun on luotava uusi API-avain.
⚠️ Uudella API-avaimella ei ole käyttöoikeuksia. Se ei voi lukea tai muuttaa mitään ennen kuin annat sille vähintään yhden roolin.
🔗 Lue API-avainten luominen, niin tiedät, miten annat avaimelle käyttöoikeudet.
API-avainten hallinta
Sinulla voi olla useita API-avaimia samanaikaisesti. Valitse avaimen vierestä kolme pistettä, niin voit:
- Muokkaa API-avainta: muuta olemassa olevan avaimen nimeä, kuvaketta ja kuvausta.
- Poista API-avain käytöstä: avain poistetaan käytöstä heti, mutta sen roolit säilyvät. Voit ottaa sen uudelleen käyttöön samasta kohdasta valitsemalla Ota API-avain käyttöön.
- Poista: ⚠️ API-avain poistetaan välittömästi, eikä sitä voi palauttaa. Kaikki sillä tehdyt pyynnöt hylätään. Tämä voi häiritä järjestelmiä, jotka tarvitsevat pääsyn avoimeen API:in.
Todennus
OAuth2 Client Credentials: näin haet ja käytät käyttöoikeustunnusta
Tässä ohjeessa kerrotaan, miten todennat OAuth2:lla client_credentials-myöntötyypin avulla ja käytät saatua käyttöoikeustunnusta Human API:n kanssa.
🔑 Tunnuksen päätepiste: https://demo.openapi.humahr.com/auth/oauth/token
Yleiskatsaus
- Myöntötyyppi: client_credentials
- Syötteet: client_id, client_secret (Human myöntämät)
- Tulos: JSON, jossa on access_token, token_type (Bearer) ja expires_in (sekunteina)
- Käyttö: lähetä tunnus API-pyyntöjen mukana otsakkeessa Authorization: Bearer <token>
Edellytykset
Sinulla on Humalta saatu client_id ja client_secret. Säilytä nämä tunnistetiedot turvallisesti.
Ympäristömuuttujat
Voit helpottaa työtä asettamalla tunnuksen päätepisteen kerran ja käyttämällä sitä komennoissa:
export TOKEN_URL="https://demo.openapi.humahr.com/auth/oauth/token"Tunnuksen pyytäminen
curlin käyttö: application/x-www-form-urlencoded
Pyydä tunnus käyttämällä application/x-www-form-urlencoded-runkoa:
# Korvaa paikkamerkit omilla tunnistetiedoillasi CLIENT_ID="your-client-id" CLIENT_SECRET="your-client-secret" curl -sS \ -X POST "${TOKEN_URL}" \ -H "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "client_id=${CLIENT_ID}" \ --data-urlencode "client_secret=${CLIENT_SECRET}"curlin käyttö: application/json
Pyydä tunnus käyttämällä application/json-runkoa:
CLIENT_ID="your-client-id" CLIENT_SECRET="your-client-secret" curl -sS \ -X POST "${TOKEN_URL}" \ -H "Content-Type: application/json" \ -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}"💡 Huomaa: Palvelin tukee tunnuspyynnössä sekä application/x-www-form-urlencoded- että application/json-sisältötyyppiä. Valitse se, joka sopii työkaluihisi.
Onnistunut vastaus näyttää tältä:
{ "token_type": "Bearer", "access_token": "eyJhbGciOi...", "refresh_token": "def50200...", "expires_in": 3600 }Käyttöoikeustunnuksen käyttäminen
Lisää tunnus API-pyyntöjesi Authorization-otsakkeeseen:
ACCESS_TOKEN="eyJhbGciOi..." # tunnusvastauksesta curl -sS \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Accept: application/json" \ "https://demo.openapi.humahr.com/users"Lähteet
⛓️💥 OAuth 2.0 (RFC 6749), kohta 4.4: Client Credentials Grant
⛓️💥 OAuth 2.0 (RFC 6749), kohta 6: Refreshing an Access Token
API-dokumentaatioValitse Avoin API -sivulla Näytä avoimen API:n dokumentaatio, niin näet koko teknisen dokumentaation suoraan Humassa. Siinä on tiedot päätepisteistä, pyyntö- ja vastausmuodoista, tietotyypeistä ja virhekoodeista.
Voit valita kahdesta näyttömuodosta:
- Redoc: helppolukuinen yleiskatsaus kaikista päätepisteistä
- Swagger: interaktiivinen muoto, jossa voit testata pyyntöjä suoraan
💡 Voit myös valita Avaa uudessa ikkunassa tai välilehdessä, jos haluat katsoa dokumentaatiota erillisessä ikkunassa.
Dokumentaatio on jaettu resurssiryhmiin, kuten Authentication, Group, Holiday, Job Title, Position, User, User Child, User Emergency Contact ja User Identification.
⛓️💥 API-dokumentaatio: https://openapi.humahr.com/redoc/index.html
Usein kysytyt kysymykset
Miten saan pääsyn avoimeen API:in?
Siirry kohtaan Järjestelmäasetukset → Avoin API ja valitse Lisää API-avain. Tarvitset ylläpitäjän pääsyn Järjestelmäasetuksiin. Anna sen jälkeen avaimelle tarvittavat roolit. Lue ohjeet artikkelista API-avainten luominen.
Mitä tapahtuu, jos kadotan client_secretin?
Et voi hakea sitä uudelleen. Sinun on luotava uusi API-avain.
Mitä eroa on API-avaimen käytöstä poistamisella ja poistamisella?
Käytöstä poistamisen voi perua, ja voit ottaa avaimen myöhemmin uudelleen käyttöön. Poistaminen tapahtuu välittömästi ja on pysyvää. Kaikki poistetulla avaimella tehdyt pyynnöt hylätään.
Mitä eroa on avoimella API:lla ja webhookeilla?
Webhookit lähettävät sinulle tiedot automaattisesti, kun Humassa tapahtuu jotain. Avoimen API:n avulla haet tai lähetät tiedot itse, milloin haluat, tekemällä pyyntöjä API:in.
Mitä eroa dokumentaatiossa on Redocilla ja Swaggerilla?
Redoc antaa helppolukuisen yleiskatsauksen päätepisteistä. Swaggerissa voit testata pyyntöjä suoraan dokumentaationäkymässä.
Voinko nähdä luettelon kentistä lukematta teknistä dokumentaatiota?
Kyllä. Katso tämän artikkelin osio Mitä tietoja on saatavilla. Siinä on yleiskatsaus tiedoista, joita voit hakea ja päivittää.
Voinko poistaa työntekijöitä tai poistaa heitä käytöstä avoimen API:n kautta?
Et. Työntekijöiden poistaminen, käytöstä poistaminen ja uudelleen aktivointi tehdään Humassa.
Miksi API-avaimeni ei näe kaikkia kenttiä?
Avain näkee ja voi muuttaa vain tietoja, joihin sillä on käyttöoikeus roolien kautta. Tarkista avaimen roolit kohdasta Järjestelmäasetukset → Avoin API.