Gå til innhold

Connect API: Arkitektur

Teknisk referanse for API-et (knapphus-connect-api, ASP.NET Web API på .NET Framework 4.8). Målet er at en ny utvikler kan spore et kall hele veien app → API → Visma.

Løsningens prosjekter

Prosjekt Innhold
knapphus-connect-api Selve API-et: kontrollere, filtre, modeller, repositorier
eportal.core ePortal-funksjonalitet: timeregistrering, perioder, lønnsarter, modultilgang
forms.core Eldre skjemasystem (FormResponses)
Knapphus.Landax.Client Landax-klientbibliotek (OAuth2-token-cache, Incident-/Survey-/Document-tjenester)
nortrace.api Soolo/NorTrace-klient (tanktelemetri)
dottieApi Dottie-klient (ansatte/feed, 1 times cache)
*-tests Enhetstester

Avhengighet: jhlVismaAPI (JHL_VismaBusinessInterface) — eget repo, DLL i dependencies/. Kilde: d:\VSTS\Knapphus\Knapphus Connect\jhlVismaAPI\jhlVismaAPI_Business.

Kontrollerinventar

Kontroller Rute Ansvar
UserController /api/User/* «Alt»-kontrolleren: login, ordrer, beholdning, tanker, kunder, leads, avvik, kjøretøy, vær, statistikk (40+ endepunkter)
AuthController /api/auth/* Refresh-token (/refresh) og utlogging/revokering (/logout)
CompanyController /api/Company/* Selskapslisten til login-skjermen (anonym)
ReceiptController /api/receipts/* Leveringskvitteringer (PDF)
SMSController (webhook) Innkommende målerstand-SMS (GasNet)
Customers/OrderController, TransactionController /api/... Kundeinnsyn: ordrer og korttransaksjoner
Forms/FormController /api/forms/* Eldre skjemasystem
Eportal/TimeRegistrationController (+Setting) /api/timeRegistration* Timeliste: lønnsarter, helligdager, perioder, oppsett
Landax/LandaxController /api/landax/* Avvik-proxy mot Landax
Landax/SurveyController /api/landax/surveys/* Sjekkliste-proxy
Landax/SurveyKioskController /api/landax/surveys/kiosk/* Anonyme kiosk-endepunkter (token-validert)
Landax/KioskTokenController /api/landax/kiosk-tokens/* Kiosk-token-administrasjon

Autentiseringsløpet (per kall)

  1. Klienten sender Authorization: Bearer ‹JWT›.
  2. Filteret JwtAuthenticationAttribute validerer tokenet (JwtManager.GetPrincipal, HS256, ingen issuer/audience-validering) og leser claims: brukernavn (uname), kryptert passord (p), selskaps-ID (cID), brukernivå (userLevel).
  3. Filteret oppretter new jhlVismaAPI.Business(companyID) og setter den på BaseAPIController.ERPAPI, og verifiserer brukeren mot Visma (ERPAPI.User.VerifyUser). Brukernavn ≥ 5 tegn behandles som leverandør.
  4. Kontrolleren bruker ERPAPI.Order/Inventory/BasicData/Metering/... — flertenant via selskaps-ID-en i tokenet.

Token-par: tilgangstoken 4 t (JWT) + refresh-token 3 dager (tilfeldig streng i tabellen RefreshTokens per selskapsdatabase, med kryptert passord for regenerering). POST /api/auth/refresh validerer og utsteder nytt tilgangstoken; 401-interceptoren i appen kaller den automatisk.

sequenceDiagram
    participant App
    participant F as JwtAuthenticationAttribute
    participant B as jhlVismaAPI.Business
    participant V as Visma
    App->>F: Bearer-token
    F->>F: Valider JWT, les claims
    F->>B: new Business(companyID)
    B->>V: VerifyUser(brukernavn, passord)
    V-->>B: OK + brukerdata
    F-->>App: (controller kjører med ERPAPI satt)

Konfigurasjonsreferanse (Web.config appSettings)

Nøkkelnavn og betydning — verdier/hemmeligheter står kun i konfigfilene:

Nøkkel(gruppe) Styrer
JwtTokenValidHours, JwtSecretKey (Delvis historiske — selve signeringen bruker konstanten i JwtManager)
Landax_ApiUrl/AuthUrl/ClientId/ClientSecret/Username/Password Landax-proxyen
SMS_* (Username, Password, PlatformPartnerId, PlatformId, GateId, Source) SMS-gateway (LinkMobility)
NorTraceBearer Fast token mot Soolo-portalen
Dottie* Dottie-fallback-nøkler (kan overstyres per selskap)
ABAX* (ClientId, ClientSecret, IdentityProviderUri, ApiUri) ABAX OAuth2
VBS_Endpoint/CertDNS/User/Password Visma Business Services
VBS_Order_ColTruck=9614 / ColStatus=6072 / ColDepot=9616 / ColType=6071 / ColConfirmedDate=4516 VBS-kolonnenumre for ordrefelter
Visma* (stor familie) Felt-mapping mot Visma — se Visma-feltreferansen
VismaSQL_OrdWhere Grunnfilteret for ordrelister (trtp=1, ikke fakturert, ordtp in (1,2), gr11 in (2))
OrderStatusWhenCompleted=2, OrderStatusWhenCompletedNeedApproval=3 Statusverdier ved ferdigmelding
DeviationLimit Maks beholdningsavvik ved nullstilling
DataHost_API/User/Pwd + {id}_DataHost_ID CO DataHost (−1 = av)
{id}_InternalEmail Intern varslingsmottaker per selskap
{id}_FactNo Fakturaserie per selskap
{id}_Vol2StdOff Standardliter av/på per selskap
WorkOrderFilePath, DeviationFiles, UNCPath Filstier for vedlegg/PDF
URL_Drivingdirections Kart-URL for veibeskrivelse
StdPaymentTerms, StdPaymentMethod, DefaultCustomerPriceGroup Standarder ved kundeopprettelse

companiesSection (selskapsoppsett)

Attributt Type Styrer
clientID int Visma-selskapsnummer (nøkkel overalt)
clientName string Visningsnavn i appen
validateTruckStock bool Beholdningskontroll ved levering
logo string Logofil (vises bl.a. i kiosk)
nortraceDepartment string Soolo-tag-filter, f.eks. Avdeling:Vats,Avdeling:Sør
UsePlanner "0"/"1" Planlegger-modulen
DisableBREG 0/1 Skrur av Brønnøysund-oppslag
PayrollPeriodCutoffDay int Lønnsperiodens brytningsdag (31 = kalendermåned)
CustomerClient int Kundeinnsynsvariant
DisableUserFilter 0/1 Skrur av brukerfiltrering av ordrer
DottieClientId/DottieApiKey string Dottie per selskap (fallback: felles nøkler, da vises kun «Alle Selskap»-oppslag)
WageTypes (nested) liste Lønnsarter (tittel + kode) for timelisten

jhlVismaAPI-kontrollerne (Business-fasaden)

new Business(clientNo) gir:

Egenskap Ansvar
User Verifisering, brukerdata, gjeldende bil/henger, modultilgang
Order Ordre-CRUD, tildeling, ferdigmelding, godkjenningskø
Inventory FreeInf2-transaksjoner, bil-/tankbeholdning
BasicData Biler, hengere, tanker, depoter, produkter, Vol2Std-faktorer
Activity Lønnsarter/aktiviteter
Metering Gassmålere (GasNet): målerstander, DLR, kundedata
Forms Eldre sjekklister
Voucher / Invoice / EG Bilag, faktura, EG-regnskap (brukes mest av ConnectMonitor)

Enum-avvik app ↔ backend

Backend-enumene avviker fra appens på to punkter: UserType er 1/2/3 (Employee/Customer/Supplier) i jhlVismaAPI men 0/1/2 i appen, og Userlevel har Planner = 3, User = 9 i backend mot User = 3 i appen. Verdiene oversettes i login-svaret — vær obs ved feilsøking på tvers.

(Verifisert i JwtAuthenticationAttribute.cs, BaseAPIController.cs, JwtManager.cs, Web.config, CompaniesSection.cs, jhlVismaAPI VBS.cs og Enums.cs.)

Relaterte sider