Bruke API for å legge inn ansatte i Capitech
Navigasjon: Simployer Tid og Bemanning - Brukerveiledninger / Capitech API for integrasjoner
Tips
Du kan se mer detaljer om API parametere og returdata i en demoløsning her Demosalg.capitech.no/API
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. NB! Oppsett for aktuelt system må være opprettet for at forespørsler mot dette API skal behandles |
| 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. F.eks NO for Norge, SE for Sverige. |
| postalCode | Nei | Postnr | Må eksistere i postnr register i Capitech for aktuelt land. F. eks 6517 i Norge. |
| cellphoneNumber | Nei | Mobilnr | Uten mellomrom og prefiks F. eks 90012345 |
| 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) eller 11 siffer for fullt personnr |
| 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 Eksempel trine.hansen@bedriften.no |
| 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 F = Funksjonær Null = ikke definert |
| 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
}