Gå til innhold

Handyman (FDV / service)

Handyman (fra GSGROUP) er service-/vedlikeholdssystemet (Field Service Management). ConnectMonitor synkroniserer ordrer, kunder og materiell/fakturalinjer mellom Handyman, Visma og fakturasystemet Semine. Logikken ligger i ctrlHandyman + biblioteket jhlHandymanAPI (+ SemineAPI).

flowchart LR
    HM[Handyman API<br/>hmapi.gsgroup.io] -->|ordrer InvoiceStatus=0| OS[--HandymanOrderSync]
    OS --> VO[(Visma-ordre)]
    OS -->|sett InvoiceStatus=2| HM
    HM -->|nye kunder BackOfficeId&lt;0| CS[--HandymanCustomerSync]
    CS --> VC[(Visma-kunde)]
    CS -->|skriv Visma-kundenr| HM
    SE[Semine fakturasystem] -->|fakturaer InReview| SS[--HandymanSemineSync]
    SS -->|materiell på ordre| HM
    SS -->|kommentar «overført»| SE

    classDef sys fill:#f8d7da,stroke:#b53b46
    class OS,CS,SS sys

Jobber

--HandymanOrderSync — ordrer → Visma

ctrlHandyman.HandymanSync():

  1. Hent ufakturerte ordrer (GET /weboffice/orders, InvoiceStatus=0) med detaljer, materiell (/materials) og timer (/salarycoderegistrations). Kun ordrer med ActualFinishDate satt og godkjent for faktura (kategori HsCategoryId=7 / CategoryBackOfficeId=2).
  2. Map til Visma-ordre: CustomerID fra Customer.BackOfficeId, OrderType=2, ExternalID=OrderId, referanse «HM: …». Linjer: fastpris (produkt 200105), materiell, og timer (produkt fra SalaryCodeReference.ExternalId).
  3. Validering: feiler hvis CustomerID < 0 eller pris = 0 → e-postvarsel.
  4. VBS.CreateVismaOrder → ved suksess SetOrderAsInvoiced som setter Handyman InvoiceStatus=2. Idempotens: filteret InvoiceStatus=0 hindrer at samme ordre hentes på nytt.

--HandymanCustomerSync — kunder → Visma

GET /weboffice/customers (nye = BackOfficeId < 0) → BasicData.CreateCustomer (standard PriceAgreementID=10) → skriv Visma-kundenr tilbake til Handyman (SetCustomerID, setter BackOfficeId). Kunden mappes på navn, adresse, e-post, telefon/mobil; «HMID: ‹id›» legges i internt notat.

--HandymanSemineSync — Semine-fakturaer → Handyman-materiell

Semine er et fakturamottaks-/OCR-system. Jobben:

  1. Autentiser mot Semine (OAuth2 password grant) og hent fakturaer med status InReview siste ~35 dager (Semine_DaysAgo).
  2. Match mot Handyman-ordre via 5-sifret orderReference eller capturedPurchaseOrderNumber.
  3. Legg fakturalinjene som materiell på Handyman-ordren (kundepris = kostpris × Semine_PriceFactor).
  4. Kommenter fakturaen «Faktura overført til handyman» i Semine.

Ingen duplikatsperre

HandymanSemineSync sjekker ikke om samme fakturalinjer alt er overført — kjøres den dobbelt, legges materiellet til på nytt.

API og autentisering

System Base Auth
Handyman https://hmapi.gsgroup.io:19000/api Header apikey (GUID) + handymanclientid
Semine https://api.semine.no (token: login.semine.no/connect/token) OAuth2 password grant

Handyman-endepunkter: /weboffice/orders, /orders/{id}, /orders/{id}/materials (GET+POST), /orders/{id}/salarycoderegistrations, /weboffice/customers, /customers. Semine-konfignøkler (navn): Semine_ApplicationKey, Semine_ClientId, Semine_OrganizationId, Semine_ProductCode, Semine_Username, Semine_Password, Semine_Status, Semine_PriceFactor, Semine_DaysAgo.

Teknisk gjeld

  • Handyman apikey/handymanclientid og Semine-innlogging er hardkodet i kildekoden — bør flyttes til konfig (sikkerhetsrisiko).
  • Hardkodede produktnumre (200105 fastpris/arbeid, 99999 Semine-materiell), prisfaktor og e-postmottakere.
  • HandymanSemineSync mangler duplikatsperre (se over).

Relaterte sider