Bruke API for å legge inn / oppdatere ansatte i Capitech
Her finner du informasjon om hvordan API kan benyttes for å legge inn ansatte i Capitech fra et eksternt system som kilde for ansatte.
EmployeeAPI - upsertEmployee
I dette API endepunktet kan en legge inn eller oppdatere ansatte for angitt klient (firma)
Endepunktet er api/public/v1/Employee/upsertEmployee
Upsert prinsipp
Våre Upsert API endepunkter vil automatisk håndtere at evt. eksisterende record (ansatt i dette tilfelle) oppdateres dersom den finnes fra før, hvis den ikke finnes vil den automatisk opprettes som ny record. Dette gjør det enklere og mer effektivt å realisere integrasjoner da eksternt system ikke trenger å sjekke / vite om recorden finnes fra før eller ikke.
Beskrivelse av Request parametere
Her er en beskrivelse og forklaring av hvilke parametre en kan benytte for å legge inn / oppdatere ansatte. 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 |
externalSystemId | Ja | Navn på kildesystem f. eks Navision, Agresso eller lignende | Benyttes for å finne et konfigurerbart oppsett for aktuelt system for prosessering av ansatte. Hvilke felter som skal tas med og oppdateres, utelates mv. |
clientId | Ja | Klientnummer for hvilket firma en skal legge inn ansatte på |
|
employeeId | Ja | Ansattnr |
|
fullname | Ja | Fullt navn | Iht. kundens praksis for navn. F. eks Fornavn Etternavn eller Etternavn, Fornavn |
firstname | Nei | Fornavn | Benyttes normalt ikke |
surname | Nei | Etternavn | Benyttes normalt ikke |
address1 | Nei | Adresse 1 |
|
address2 | Nei | Adresse 2 |
|
countryCode | Ja | Landkode | ISO 3166-1 alfa-2 landkode med to tegn. |
postalCode | Nei | Postnr | Må eksistere i postnr register i Capitech for aktuelt land. |
cellphoneNumber | Nei | Mobilnr | Uten mellomrom og prefiks |
phoneNumber | Nei | Telefonnr 1 |
|
phoneNumber2 | Nei | Telefonnr 2 |
|
emailAddress | Nei | Epostadresse |
|
gender | Ja | Kjønn | K for kvinne, M for mann |
socialSecurityNumber | Nei | Fødselslsdato / Personnr | Kan legge inn 6 siffer for kun fødselsdato (ddmmyy) |
employeeStartDate | Nei | Ansatt startdato | Format yyyy-mm-dd |
employeeEndDate | Nei | Ansatt sluttdato | Format yyyy-mm-dd |
employeeSeniorityDate | Nei | Ansatt ansiennitetsdato | Format yyyy-mm-dd |
authenticationId | Nei | Ekstern brukerid | For ekstern pålogging f. eks via Azure AD |
externalId | Nei | Ekstern id | Identifikator i eksternt system (kan være forskjellig fra ansattnr) |
active | Nei | Aktiv | Aktiv status i eksternt system. Benyttes ikke i Capitech da aktivering normalt av nye ansatte settes pr modul (Tid, Fravær, Plan, Fleksitid, Min Capitech mv) iht. hva den ansatte skal ha tilgang til / benytte. |
wagegroupId | Nei | Lønnsgruppenr | Nr på lønnsgruppe kan angis om ønskelig. Lønnsgruppen må finnes på den aktuelle klienten (firmaet) i Capitech. |
departmentId | Nei | Avdelingsnr | Nr på avdeling kan angis om ønskelig. Avdelingsnummeret må finnes på den aktuelle klienten (firmaet) i Capitech. |
taskId | Nei | Arbeidsoppgavenr | Nr på arbeidsoppgave på angitt avdeling kan angis om ønskelig. Arbeidsoppgavenummeret må finnes på den aktuelle klienten (firmaet) på den aktuelle avdelingen i Capitech. |
costCarrierId | Nei | Bærernr | Nr på kostnadsbærer kan angis om ønskelig. Bærernummeret må finnes på den aktuelle klienten (firmaet) i Capitech. |
statisticsGroupCode | Nei | Ansattype | A = Arbeider |
externalCorrelationId | Nei | Ekstern korrelasjonsid | Identifikator på transaksjon / melding fra eksternt system |
Returdata
Her er en beskrivelse og forklaring av returdata en får fra dette API og hva det i praksis kan benyttes til.
Felt | Beskrivelse | Eksempel | Merknad |
|---|---|---|---|
displayErrormessage | Feilmelding for visning | An error occurred | Generell feilmelding |
serverErrormessage | Server feilmelding | System.Exception: ErrorMsg: Error in sync procedure! Logg: Feil ved oppdatering i kolonne Kjonn (gyldige verdier M eller K)! | Mer detaljert feilmelding med mer presis info om hva som feiler |
Eksempel på request
Her er et eksempel på en request med et minimum av data mot api/public/v1/Employee/upsertEmployee
{
"accessToken": "gyldigaccesstokenher",
"externalSystemId": "Agresso",
"clientId": 100,
"employeeId": 100888,
"fullName": "Line Hansen",
"firstName": null,
"surname": null,
"address1": "Bergtoppen 5",
"address2": null,
"countryCode": "NO",
"postalCode": "6500",
"cellphoneNumber": null,
"phoneNumber": null,
"phoneNumber2": null,
"emailAddress": null,
"gender": "K",
"socialSecurityNumber": null,
"employeeStartDate": null,
"employeeEndDate": null,
"employeeSeniorityDate": null,
"authenticationId": null,
"externalId": null,
"active": 0,
"wageGroupId": null,
"departmentId": null,
"taskId": null,
"costCarrierId": null,
"statisticsGroupCode": "F",
"externalCorrelationId": null
}
Tips
Du kan se mer detaljer om API parametere og returdata i en demoløsning her Demosalg.capitech.no/API