Bruke API for å hente timer fra Capitech
- oliver.bjorshol (Deactivated)
- Oliver Bjørshol
Owned by oliver.bjorshol (Deactivated)
Her finner du informasjon om hvordan API kan benyttes for å hente ut timer fra Capitech for gjenbruk i andre systemer.
I korte trekk
- Logg på kundens API portal med en gyldig bruker med tilgang til API og hent ut et accessToken
Dette gjøres via endepunkt /api/public/v1/Access/login
F.eks dinbedrift.capitech.no/API - Kjør en request mot API for timer med ønskede parameter for f. eks datointervall, klient (selskap) og evt. andre kriterier.
Dette gjøres via endepunkt api/public/v1/Time/getTimeTransactions
TimeAPI - getTimeTransactions
Beskrivelse av Request parametere
Her er en beskrivelse og forklaring av hvilke parametre en kan benytte for å hente ut timer.
En kan få mer detaljer via mouseover på hhv. request parameter og retur felter i API oversikt.
| Parameter | Påkrevd | Beskrivelse | Merknad |
|---|---|---|---|
| accessToken | Ja | Token fra Login. | Kreves for å få svar på API request |
| clientId | Ja | Klientnummer for hvilket firma en skal hente timer på | |
| fromDate | Ja | Fradato for ønsket periode i format 'yyyy-mm-dd' | Fra og med |
| toDate | Ja | Tildato for ønsket periode i format 'yyyy-mm-dd' | Til og med |
| approvedLevelFilter | Nei | Filter for å avgrense til kun godkjente timer Vanligvis benyttes nivå 1 Om flere nivå benyttes kan en spørre på f. eks nivå 2 osv.. | Om ikke angitt får en alle timer uavhengig av godkjenning. |
| employeeIdFilter | Nei | Filter for å angi evt. en eller flere ansattnr en ønsker å avgrense på. | |
| departmentIdFilter | Nei | Filter for å angi evt. en eller flere avdelingsnr en ønsker å avgrense på. | |
| taskIdFilter | Nei | Filter for å angi evt. en eller flere arbeidsoppgavenr en ønsker å avgrense på. | Bør kun benyttes sammen med avgrensning på en avdeling da arbeidsoppgavenr er en subdimensjon til avdeling. (Og samme nr på arbeidsoppgave kan i praksis være ulike oppgaver på ulike avdelinger) |
| orderIdFilter | Nei | Filter for å angi evt. en eller flere ordrenr en ønsker å avgrense på. | |
| dutyIdFilter | Nei | Filter for å angi evt. en eller flere Flow vakt id'er en ønsker å avgrense på. | NB Id på vakt er et autogenerert løpenr som ikke vises i vaktregister brukergrensesnitt. Dette filteret er kun for spesiell bruk. |
| projectIdFilter | Nei | Filter for å angi evt. en eller flere prosjektnr en ønsker å avgrense på. | |
| subProjectIdFilter | Nei | Filter for å angi evt. en eller flere underprosjektnr en ønsker å avgrense på. | Bør kun benyttes sammen med avgrensning på ett prosjekt da underprosjektnr er en subdimensjon til prosjekt. (Og samme nr på underprosjekt kan i praksis være ulike underprosjekt på ulike prosjekt) |
| projectPhaseIdFilter | Nei | Filter for å angi evt. en eller flere fasenr en ønsker å avgrense på. | Bør kun benyttes sammen med avgrensning på ett prosjekt og ett underprosjekt da fasenr er en subdimensjon til underprosjekt. (Og samme fasenr kan i praksis være ulike faser på ulike prosjekt / underprosjekt) |
| freeDimension1Filter | Nei | Filter for å angi evt. en eller flere fri dimensjon1 nr en ønsker å avgrense på. | Fri dimensjon 1 er en konfigurerbar dimensjon som kan aktiveres og gis navn iht. kundens behov. |
| freeDimension2Filter | Nei | Filter for å angi evt. en eller flere fri dimensjon2 nr en ønsker å avgrense på. | Fri dimensjon 2 er en konfigurerbar dimensjon som kan aktiveres og gis navn iht. kundens behov. |
| timeCategoryIdFilter | Nei | Filter for å angi en eller flere tidskategori nr en ønsker å avgrense på | Tidskategorier kan f. eks være Timelønn, Overtid 50%, Overtid 100%, Nattillegg osv. |
| timeCategoryTypeIdFilter | Nei | FIlter for å angi en eller flere typer timer en ønsker å avgrense på. | Typedefinisjoner er: 'O' Ordinære timer (f.eks Timelønn, Fastlønn) |
| includePayableCategory | Nei | Filter for å kunne avgrense på kun tidskategorier som er lønnet, ikke lønnet eller alle. | |
| externalStatusCodeFilter | Nei | Filter for å kunne avgrense til kun transaksjoner som har en gitt ekstern statuskode. | Benyttes f. eks for å kun hente timer som ikke er flagget med en ekstern statuskode som betyr at timene allerede er overført. Det finnes et eget API endepunkt for å sette denne statuskoden: api/public/v1/Time/setExternalStatusCode |
| includeElementsWithExternalStatusCodeNull | Nei | Filter for å kunne angi om en vil inkludere timer hvor ekstern statuskode er null eller ikke. | |
| lastUpdatedGreaterThanOrEqualToFilter | Nei | Filter for å kunne hente ut timer som er opprettet eller oppdatert på eller etter angitt dato og klokkeslett. Format: 'yyyy-mm-dd hh:mm:ss.000' | Kan benyttes for å hente kun timer som er opprettet eller endret siden angitt dato og klokkeslett. Effektiv løsnig for å hente kun differanse fra siste uthenting av data. |
| projectAlphanumericCodeFilter | Nei | Filter for å angi evt. en eller flere prosjekt alfanumerisk kode en ønsker å avgrense på. | Kan benyttes dersom det er aktivert støtte for alfanumerisk kode på prosjekter. F. eks kan prosjektnr være 10588 (løpenr) og alfanumerisk kode 'B400' |
| subProjectAlphanumericCodeFilter | Nei | Filter for å angi evt. en eller flere underprosjekt alfanumerisk kode en ønsker å avgrense på. | Bør kun benyttes sammen med avgrensning på ett prosjekt da underprosjekt alfakode er en subdimensjon til prosjekt. (Og samme kode på underprosjekt kan i praksis være ulike underprosjekt på ulike prosjekt) |
| phaseAlphanumericCodeFilter | Nei | Filter for å angi evt. en eller flere fase alfanumerisk kode en ønsker å avgrense på. | Bør kun benyttes sammen med avgrensning på ett prosjekt og ett underprosjekt da fase alfakode er en subdimensjon til underprosjekt. (Og samme fase kan i praksis være ulike faser på ulike prosjekt / underprosjekt) |
| lastApprovedOrUpdatedFilter | Nei | Filter for å kunne hente ut timer som er opprettet, oppdatert eller godkjent på eller etter angitt dato og klokkeslett. Format: 'yyyy-mm-dd hh:mm:ss.000' | Kan benyttes for å hente kun timer som er opprettet, endret eller godkjent siden angitt dato. Tar hensyn til alle nivå av godkjenning. |
| includeDeleted | Nei | Opsjon for å inkludere slettede timeregistreringer | Anbefaler å benytte timeregistreringens UID (unike id) for å evt. slette registreringen i eksternt system. |
Returdata
Her er en beskrivelse og forklaring av returdata en får fra Timer API og hva det i praksis kan benyttes til.
| Felt | Beskrivelse | Eksempel | Merknad |
|---|---|---|---|
| clientId | Klientnr | 100 | Klientnr er et unikt nr for hvert enkelt firma. For konsernkunder kjøres en request for hvert enkelt firma. |
| employeeid | Ansattnr | 155 | |
| employee | ansattnavn | Ola Danielsen | |
| datein | Dato for start | 2021-07-10 | Dato timeregistreringen startet |
| timein | start tidspunkt | 21:57:00.000 | |
| dateout | Dato for slutt | 2021-07-11 | Dato timeregistreringen sluttet |
| timeout | slutt tidspunkt | 07:01:00.000 | |
| departmentid | Avdelingsnr | 50 | |
| department | Avdelingsnavn | Logistikk | |
| taskid | Arbeidsoppgavenr | 20 | |
| task | Arbeidsoppgavenavn | Varemottak | |
| classicdutyid | Vaktid | 188 | Classic Plan vaktnr |
| classicdutycode | Vaktkode | N2 | Classic Plan vaktid |
| classicduty | Vaktbeskrivelse | Nattevakt 22 - 06 | Classic Plan vakt beskrivelse |
| orderid | Ordrenr | null | |
| order | ordrenavn | null | |
| projectid | Prosjektnr | 1001 | |
| projectAlphanumericCode | Prosjekt alfanumerisk kode | B400 | |
| project | Prosjektnavn | Bergtoppen | |
| subProjectid | Underprosjektnr | 8445 | |
| subProjectAlphanumericCode | Underprosjekt alfanumerisk kode | T8877 | |
| subProject | Undeprosjektnavn | Tilleggsbestilling øst | |
| projectPhaseid | Fasenr | null | |
| phaseAlphanumericCode | Fase alfanumersik kode | null | |
| projectPhase | Fasenavn | null | |
| shiftId | Vaktnr | 68874 | Flow Plan vaktnummer |
| shift | Vakt | N2 | Flow Plan vaktnavn |
| freeDimension1Id | Fri Dimensjon1 nr | 10 | |
| freeDimension1 | Fri dimensjon1 navn | Ordinær | |
| freeDimension2Id | Fri Dimensjon2 nr | 60 | |
| freeDimension2 | Fri dimensjon2 navn | Bas | |
| freeText | Fritekst | Overtid fordi Kjell ble forsinket | |
| approvedLevelOne | Godkjent nivå 1 | 1 | 1 = Godkjent på nivå 1 null = Ingen godkjenning |
| approvedLevelTwo | Godkjent nivå 2 | null | 1 = Godkjent på nivå 2 null = Ingen godkjenning |
| approvedLevelThree | Godkjent nivå 3 | null | 1 = Godkjent på nivå 3 null = Ingen godkjenning |
| approvedLevelFour | Godkjent nivå 4 | null | 1 = Godkjent på nivå 4 null = Ingen godkjenning |
| approvedLevelOneBy | Godkjent nivå 1 av | trineg | Bruker som har godkjent |
| approvedLevelTwoBy | Godkjent nivå 2 av | null | Bruker som har godkjent |
| approvedLevelThreeBy | Godkjent nivå 3 av | null | Bruker som har godkjent |
| approvedLevelFourBy | Godkjent nivå 4 av | null | Bruker som har godkjent |
| approvedLevelOneOn | Godkjent nivå 1 når | 2021-07-11 11:25:00 | Dato og tidspunkt for godkjenning |
| approvedLevelTwoOn | Godkjent nivå 2 når | null | Dato og tidspunkt for godkjenning |
| approvedLevelThreeOn | Godkjent nivå 3 når | null | Dato og tidspunkt for godkjenning |
| approvedLevelFourOn | Godkjent nivå 4 når | null | Dato og tidspunkt for godkjenning |
| timeCategoryId | Tidskategorinr | 10 | |
| timeCategory | Tidskategorinavn | Timelønn | |
| timeCategoryTypeId | Tidskategoritypekode | O | |
| timeCategoryType | Tidskategoritype | Ordinær | |
| timeCategoryPayable | Tidskategori lønnet | 1 | 1= Lønnet |
| qty | Antall | 7.50 | Antall timer |
| uid | Unik id | 107004 | Unik id på den aktuelle timeregistreringen. NB! En timeregistrering kan gi flere tidskategorier, dvs. samme uid på records for hhv. Timelønn og Overftid 50% |
| externalId | Ekstern id | null | Id fra ekstern system dersom det benyttes API for å registrere tid. |
| correlationId | Korrelasjonsid | null | Id som referer til siste handling som har endret transaksjonen |
| externalStatusCode | Ekstern statuskode | null | Ekstern statuskode som kan angi status i eksternt system. Benyttes f. eks for ekskludere timer som er flagget med en ekstern statuskode som betyr at timene allerede er overført. |
| lastUpdatedOn | Sist oppdatert | 2021-07-11 07:01:00 | Dato og tidspunkt for siste endring av transaksjonen. Dersom den ikke er endret er denne dato og tidspunkt for opprettelse av transaksjon |
| recordStateKey | Unik streng for sjekk av kombinasjon på uid, tidskategori og antall | 107004_10_7.50 | Denne kan benyttes for å sjekke om data i ekstern system er i samsvar med data i Capitech. Dersom en leder f. eks endrer antall timer etter at et eksternt system har hentet en transaksjon vil ikke recordstatekey lenger matche og en kan oppdatere data i eksternt system iht. dette. |
| isDeleted | Er slettet status (true / false) | false | Vises som true for slettede timeregistreringer. Disse vises kun om request parameter includeDeleted er satt til true |
Begrensninger
- Maks 31 dager periode i fra - til dato vil aksepteres
- Om returdata vil overstige 5000 records vil forespørselen avvises, avgrens med kortere datointervall eller andre filter for å redusere datamengde.
Tips
Du kan se mer detaljer om API parametere og returdata i en demoløsning her Demosalg.capitech.no/API