Rå ↓ — Rå Markdown til AI-assistenter

Exsitec Data Link — Brug

Exsitec Data Link er en lille Windows-companion, der lader et lokalt program — et Excel-regneark, et script eller dit eget værktøj — køre Visma Business NXT GraphQL queries og mutations uden selv at håndtere Visma-login eller token. Den logger på Business NXT for dig og stiller en styret GraphQL-gateway på din egen maskine til rådighed (localhost): Du sender et GraphQL-dokument, Data Link kontrollerer dine Data Link-rettigheder for hver virksomhed, dokumentet berører, og videresender det til Business NXT under dit eget Visma-login. Svaret fra Business NXT kommer uændret tilbage.

Læser du dette med en AI-assistent? Denne side er den komplette brugsreference. Du kan indsætte den i din assistent eller give den den rå Markdown på /docs/usage.md?lang=da (samme indhold, uden styling). Bed den skrive forespørgslerne i det sprog, du vælger — alt, hvad den behøver (endpoints, headere, rettighedsregler, request- og response-formater samt fejlformatet), står nedenfor. Til selve Business NXT-skemaet (tabeller, felter, filtre) skal du pege den mod Vismas Business NXT GraphQL-dokumentation eller bede den køre en introspection query gennem gatewayen.

1. Kom hurtigt i gang

1. Installér og log på. Installér Data Link, højreklik derefter på dens bakkeikon (nederst til højre, ved uret) → Sign in. Din browser åbner Visma Connect; log på dér.

2. Find port og nøgle. Læs %LOCALAPPDATA%\Exsitec\DataLink\endpoint.json — den indeholder loopback-port og en key, der gælder for den aktuelle opstart.

3. Sig hej. GET http://127.0.0.1:{port}/v1/status med headeren X-DataLink-Key: {key}. Du får versionen og om du er logget på.

4. Vælg en virksomhed. GET /v1/companies viser de virksomheder, du har adgang til, samt hvad din Data Link-adgang og dine tilladelser lader dig gøre i hver af dem.

5. Kør GraphQL. POST /v1/nxt/graphql med en standard GraphQL-body:

   { "query": "{ useCompany(no: 4926238) { generalLedgerAccount(first: 5) { items { accountNo name } } } }" }
   

   Svaret er Business NXTs eget { "data": …, "errors": … }.

2. Sådan kører den

• Data Link installeres pr. bruger og starter automatisk, når du logger på Windows. Den kører stille i baggrunden og viser et lille ikon i systembakken (nederst til højre på proceslinjen, ved uret).
• Højreklik på bakkeikonet for at:
  • se om du er Signed in eller Signed out,
  • Sign in / Sign out (login åbner din browser til Visma Connect),
  • Open logs folder, Check for updates…, åbne denne brugsdokumentation og Quit.
• Du skal være logget på, før en GraphQL-request kan lykkes. Login er interaktivt (et browservindue); derefter fornyes sessionen automatisk og overlever genstart af Data Link.
• Companionen har ingen "aktuel virksomhed". Hvert GraphQL-dokument navngiver de virksomheder, det arbejder på (useCompany(no: …)), så én kørende companion betjener dem alle.
• Opdateringer: bakke → Check for updates… henter og installerer en ny version i ét trin og genstarter Data Link (en ballon bekræfter den nye version). En genstart giver ny port og nøgle — se genstartssignalet i afsnit 3.

Hvor ting ligger

3. Kommunikation med det lokale API

Discovery — find port og nøgle

Companionen vælger en ledig loopback-port ved opstart og skriver en lille discovery-fil, så betroede lokale kaldere kan finde den:

%LOCALAPPDATA%\Exsitec\DataLink\endpoint.json

{
  "port": 51234,
  "key": "b3d1…a9f0",
  "instanceId": "3f2a…",
  "processId": 18244,
  "protocol": "v1",
  "version": "2.0.0",
  "startedUtc": "2026-10-07T07:15:00.0000000+00:00"
}

• port — loopback-porten. APIets base URL er http://127.0.0.1:{port}.
• key — den delte hemmelighed for den aktuelle opstart. Send den med hver request (nedenfor). Den ændres, hver gang companionen genstarter, så læs den altid på ny — gem den aldrig. Parse filen med en JSON-parser: tegn som + kan være skrevet som \u002B escapes.
• instanceId — identificerer denne kørsel af companionen ("genstartssignalet"; se nedenfor).

Base URL og versionering

http://127.0.0.1:{port}/v1/…

Alle endpoints ligger under præfikset /v1 (protocol-feltet i discovery-filen); GraphQL-gatewayen er /v1/nxt/graphql. Bind til 127.0.0.1 (loopback) — companionen lytter kun dér.

Påkrævede request-headere

Der er ingen virksomhedsheader: Virksomheden navngives inde i GraphQL-dokumentet.

Svarheadere

Genstartssignal. Hvis værdien af X-DataLink-Instance ændres mellem kald, har companionen genstartet. Læs endpoint.json igen — både port og nøgle kan være ændret.

Timeouts

• POST /v1/auth/login venter på, at du fuldfører browserlogin (op til 5 minutter).
• POST /v1/nxt/graphql tager lige så lang tid, som Business NXT bruger; store læsninger kan tage mange sekunder. Giv din HTTP-klient en generøs timeout (minutter, ikke sekunder).

Sikkerhedsbegrænsninger (derfor afvises browser-fetch)

Companionen håndhæver en loopback-tillidsgrænse:

• Requests med en Origin-header afvises (403) — derfor kan en webside med fetch() ikke nå den. Kald den fra en lokal proces (WinHTTP, HttpClient, curl, Python, PowerShell, en VBA WinHttp.WinHttpRequest), ikke browser- JavaScript.
• Host-headeren skal være 127.0.0.1, localhost eller ::1.
• En manglende eller forkert nøgle returnerer 401.

4. Endpoint-reference

Hver request kræver X-DataLink-Key. Response-bodies fra selve Data Link er JSON med feltnavne i camelCase; POST /v1/nxt/graphql returnerer Business NXTs body uændret.

GET /v1/status

Health og loginstatus. Den virker, mens du er logget ud.

{
  "status": "ok",
  "instanceId": "3f2a…",
  "protocol": "v1",
  "version": "2.0.0",
  "provider": { "id": "business-nxt", "authenticated": true },
  "startedUtc": "2026-10-07T07:15:00+00:00"
}

POST /v1/auth/login

Starter det interaktive browserlogin og returnerer, når det er færdigt. Ingen body. Den åbner altid browseren, også når du allerede er logget på — tjek GET /v1/status først, hvis du kun vil logge på ved behov.

{ "authenticated": true }

Hvis browserforløbet ikke fuldføres inden for 5 minutter, fejler kaldet med 503 unavailable (retryable: true); et login, som Visma Connect afviser, returnerer 401 unauthorized.

POST /v1/auth/logout

Afslutter Business NXT-sessionen. Returnerer { "authenticated": false }.

GET /v1/companies

De virksomheder, det aktuelle login har adgang til (Business NXTs availableCompanies), hver med sin tenant (den Visma.net-kunde, den hører til) og den Data Link-adgang og de tilladelser, der gælder dér — så du kan slå et virksomhedsnavn op til dets nummer og se, hvad du må gøre, før du forsøger.

{
  "available": [
    { "id": "4926238", "name": "Exsitec BNXT Demo",         "tenantId": "4926230", "canRead": true, "canWrite": false, "canDelete": false },
    { "id": "6307615", "name": "Demo - Junge Byg Aps 9999", "tenantId": "2728812", "canRead": true, "canWrite": true,  "canDelete": false }
  ]
}

En virksomhed vist med canRead: false er en, dit Visma-login kan se, men som Data Link ikke åbner for dig (se afsnit 5).

POST /v1/nxt/graphql — gatewayen

Kører enhver Business NXT GraphQL-query eller mutation. Bodyen er standard GraphQL-over-HTTP:

{
  "query": "query Accounts($company: Int!) { useCompany(no: $company) { generalLedgerAccount(first: 5) { items { accountNo name } } } }",
  "variables": { "company": 4926238 },
  "operationName": "Accounts"
}

Det sker der:

1. Data Link parser dokumentet og finder ud af, hvilke virksomheder det læser, skriver eller sletter i (afsnit 6).
2. Den kontrollerer din Data Link-adgang og dine tilladelser for hver af dem. Hvis noget ikke er tilladt, afvises hele dokumentet, og intet når Business NXT.
3. Ellers videresender den din request-body uændret til Business NXT under dit Visma-login og returnerer Business NXTs HTTP-status og body ordret — inklusiv Business NXTs egne errors og extensions (for eksempel extensions.vbnxt-trace-id).

{
  "data": {
    "useCompany": {
      "generalLedgerAccount": {
        "items": [ { "accountNo": 1010, "name": "Varesalg DK" }, { "accountNo": 1020, "name": "Anden omsætning" } ]
      }
    }
  },
  "extensions": { "vbnxt-trace-id": "…" }
}

Data Link fornyer selv dit Visma-token, og når Business NXT svarer 429 Too Many Requests, venter den og prøver igen — begge dele er sikkert, fordi requesten ikke blev kørt. Den prøver aldrig andet igen, så en mutation kan aldrig køre to gange; en 5xx fra Business NXT sendes tilbage til dig, som den er.

5. Data Link-adgang og tilladelser

Hvad du må gøre gennem Data Link, administreres af Exsitec i NxtPlatform admin. Den gamle Config API-portal til tildelinger er væk; dokumentations- og downloadhosten giver ikke adgang.

Data Link begrænser kun det, din egen Visma-bruger må gøre — den giver aldrig adgang, som Visma ikke ville give. En virksomhed uden for dine availableCompanies afvises, selv hvis du har adgang til dens tenant.

Når du ikke har Write-tilladelse noget sted, beder Data Link også Visma om et skrivebeskyttet login, næste gang du logger på, så Business NXT selv også afviser mutations.

Din adgang og dine tilladelser hentes fra NxtPlatform, når du logger på, opdateres med få minutters mellemrum og holdes kun i hukommelsen. Hvis NxtPlatform ikke kan nås, gælder det seneste svar i en kort grace-periode; derefter — eller hvis Data Link aldrig har nået NxtPlatform, siden den startede — afviser gatewayen med 503 unavailable (retryable: true) i stedet for at køre uden kontrol.

6. Sådan læser rettighedskontrollen et dokument

Kontrollen arbejder på det parsede dokument, aldrig på teksten, så aliases, fragments og variables kan ikke skjule noget. Den er bevidst streng:

Navngiv virksomheden: useCompany(no: {companyNo})

Hver virksomhedsspecifik læsning eller skrivning ligger under en root useCompany(no: …). no er virksomhedsnummeret fra GET /v1/companies — en literal, en variable eller en variable-default:

query Projects($company: Int!) {
  useCompany(no: $company) {
    orgUnit2(filter: { orgUnit2No: { _eq: 2130 } }) { items { orgUnit2No name } }
  }
}

(Business NXTs organisatoriske enheder navngives pr. virksomhed; i Demo - Junge Byg Aps 9999 er projekter orgUnit2.)

• Et dokument må navngive flere virksomheder, normalt med aliases (demo: useCompany(no: 4926238) { … } junge: useCompany(no: 6307615) { … }). Hver kontrolleres; én afvisning afviser hele dokumentet.
• no skal kunne opløses til et heltal. En manglende no, en null, en streng eller en udefineret variable afvises med 400 invalid_request.
• Hver operation i dokumentet kontrolleres, ikke kun den som operationName vælger.
• Fragments og inline fragments udvides; @skip og @include ignoreres, så en betinget selection tæller stadig med.

Hvad hver del af et dokument kræver

Sikker skrivning

Business NXT har ingen transaktioner på tværs af tabeller. To vaner gør skrivning forudsigelig:

• Sæt onError: FAIL_TABLE på hver tabeloperation, så en ugyldig række afviser hele tabeloperationen i stedet for at skrive en del af den.
• For at få flere tabeloperationer til at lykkes eller fejle samlet skal du bruge Business NXTs edit cache: Kør dem med useCompany(no: N, persistEditCache: true, partialRequestId: "…") og afslut med finishEditCache(action: SAVE) (eller DISCARD). Hver request rettighedskontrolleres for sig selv, ligesom enhver anden mutation.

7. Fejl

Der er to slags fejl, og begge bruger GraphQLs error-shape.

Business NXTs egne fejl — en GraphQL-fejl, en værdi Business NXT afviser, en rate limit — kommer tilbage præcis som Business NXT sendte dem: HTTP-status og bodyen { "data": …, "errors": [ … ] }.

Afvisninger fra selve Data Link (requesten nåede aldrig Business NXT) har extensions.code:

{
  "errors": [
    {
      "message": "You have no Data Link Write permission for company 'Exsitec BNXT Demo' (4926238).",
      "extensions": { "code": "forbidden", "retryable": false, "instanceId": "3f2a…", "company": "4926238" }
    }
  ]
}

GET /v1/status, /v1/auth/* og GET /v1/companies rapporterer deres fejl i Data Links almindelige envelope i stedet:

{ "code": "unauthorized", "message": "…", "retryable": false, "instanceId": "3f2a…" }

En ukendt sti får en ren 404.

8. Forholdet til Business NXT GraphQL API

Data Link er Business NXTs GraphQL API, tilgået gennem din egen maskine:

• Samme schema, samme dokumenter. Alt, hvad du kan sende til https://business.visma.net/api/graphql, sender du til /v1/nxt/graphql, underlagt rettighedskontrollen. Brug Vismas Business NXT-dokumentation eller introspection gennem gatewayen til tabeller, felter og filtre.
• Ingen tokens at håndtere. Data Link holder dit Visma Connect-login og føjer det til hver videresendt request; dit program ser aldrig et token.
• Styret. Hvert dokument kontrolleres mod din Data Link-adgang og dine tilladelser, før det forlader din maskine, så Exsitec kan beslutte pr. tenant, hvem der må læse, skrive og slette gennem Data Link.
• Intet omformes. Svaret er Business NXTs, byte for byte.

9. Brug fra Excel

Download og importér de to VBA-moduler nedenfor (Alt+F11 -> File -> Import File...). De er standardmoduler og bruger kun late binding, så der er ikke behov for ændringer i Tools -> References.

Offentligt VBA API

Mønster for knapmakro

Læg virksomhedsspecifikke indstillinger og knapmakroer i ExsitecDataLinkCustom.bas:

Public Const COMPANY_NO As Long = 4926238

Public Sub ListAccounts()
    On Error GoTo Failed
    Dim data As Object
    Set data = NxtQuery("query Accounts($company: Int!) { useCompany(no: $company) { generalLedgerAccount(first: 20) { items { accountNo name } } } }")
    WriteRows NxtItems(data, "useCompany.generalLedgerAccount"), ActiveSheet.Range("A1"), Array("accountNo", "name")
    Exit Sub
Failed:
    ShowNxtError
End Sub

Til mutations kalder du samme NxtQuery-funktion med et mutation-dokument. SDKet prøver aldrig mutations igen efter portændring eller transportfejl.

Autostart og login

SDKet læser %LOCALAPPDATA%\Exsitec\DataLink\endpoint.json. Hvis filen mangler, eller /v1/status ikke svarer, starter det %LOCALAPPDATA%\Exsitec.DataLink\Exsitec Data Link.exe (eller current\DesktopDataLink.Host.exe) og venter op til 30 sekunder.

Før hvert kald tjekker det /v1/status. Hvis du er logget ud, fortæller Excel, at browseren åbner, kalder /v1/auth/login og rejser derefter en fejl, der beder dig køre handlingen igen, når login er fuldført. Den oprindelige GraphQL-request køres ikke automatisk efter login.

VBA-fejlnumre

Beskeder bruger Data Link-bakkens sprogindstilling (ui-settings.json) for engelsk, dansk, svensk og norsk, med engelsk som standard.

10. Eksempler i andre sprog

PowerShell

# 1. Discover the running companion.
$ep   = Get-Content "$env:LOCALAPPDATA\Exsitec\DataLink\endpoint.json" | ConvertFrom-Json
$base = "http://127.0.0.1:$($ep.port)/v1"
$hdr  = @{ "X-DataLink-Key" = $ep.key }

# 2. Check status / sign-in.
Invoke-RestMethod "$base/status" -Headers $hdr

# 3. Resolve a company name to its number, and see your rights there.
$companies = (Invoke-RestMethod "$base/companies" -Headers $hdr).available
$company   = $companies | Where-Object { $_.name -eq "Exsitec BNXT Demo" }

# 4. Run GraphQL.
$body = @{
    query     = 'query A($c: Int!) { useCompany(no: $c) { generalLedgerAccount(first: 5) { items { accountNo name } } } }'
    variables = @{ c = [int]$company.id }
} | ConvertTo-Json -Depth 5

$result = Invoke-RestMethod "$base/nxt/graphql" -Method Post -Headers $hdr `
    -ContentType "application/json" -Body $body
$result.data.useCompany.generalLedgerAccount.items

Python

Kun standardbibliotek:

import json, os, urllib.request

path = os.path.join(os.environ["LOCALAPPDATA"], "Exsitec", "DataLink", "endpoint.json")
with open(path, encoding="utf-8-sig") as f:
    ep = json.load(f)
base = f"http://127.0.0.1:{ep['port']}/v1"

def call(method, path, body=None):
    headers = {"X-DataLink-Key": ep["key"]}
    data = None
    if body is not None:
        data = json.dumps(body).encode("utf-8")
        headers["Content-Type"] = "application/json"
    request = urllib.request.Request(base + path, data=data, headers=headers, method=method)
    with urllib.request.urlopen(request, timeout=300) as response:   # HTTPError carries the GraphQL errors
        return json.load(response)

def graphql(query, **variables):
    return call("POST", "/nxt/graphql", {"query": query, "variables": variables})

companies = call("GET", "/companies")["available"]
junge = next(c for c in companies if c["name"] == "Demo - Junge Byg Aps 9999")

result = graphql(
    "query P($c: Int!, $p: Int!) { useCompany(no: $c) { orgUnit2(filter: { orgUnit2No: { _eq: $p } }) { items { orgUnit2No name } } } }",
    c=int(junge["id"]), p=2130)
print(result["data"]["useCompany"]["orgUnit2"]["items"])

11. Fejlfinding

Sidder du stadig fast? Bakke → Open logs folder og send den nyeste logfil til din Exsitec-kontakt — den indeholder ingen GraphQL-dokumenter, beløb, nøgler eller tokens.

12. Ordliste

Dette dokument beskriver det lokale v1-API. Companionen rapporterer sin kørende version i GET /v1/status og i bakkemenuen.