Rå ↓ — Rå Markdown för AI-assistenter

Exsitec Data Link — Användning

Exsitec Data Link är en liten Windows-kompanjon som låter ett lokalt program — en Excel-arbetsbok, ett skript eller ditt eget verktyg — köra Visma Business NXT GraphQL- queries och mutations utan att själv hantera Visma-inloggning eller token. Den loggar in i Business NXT åt dig och exponerar en styrd GraphQL-gateway på din egen dator (localhost): du skickar ett GraphQL-dokument, Data Link kontrollerar dina Data Link- rättigheter för varje företag som dokumentet berör och vidarebefordrar det till Business NXT under din egen Visma-inloggning. Svaret från Business NXT returneras oförändrat.

Läser du detta med en AI-assistent? Den här sidan är den kompletta användningsreferensen. Du kan klistra in den i din assistent, eller ge den rå Markdown på /docs/usage.md?lang=sv (samma innehåll, utan formatering). Be den skriva anropen på det språk du föredrar — allt den behöver (endpoints, headers, rättighetsregler, request- och response-format samt felformat) finns nedan. För själva Business NXT-schemat (tabeller, fält, filter), peka den mot Vismas Business NXT GraphQL-dokumentation eller be den köra en introspection-query genom gatewayen.

1. Kom igång snabbt

1. Installera och logga in. Installera Data Link och högerklicka sedan på dess tray-ikon (nere till höger, nära klockan) → Logga in. Webbläsaren öppnar Visma Connect; logga in där.

2. Hitta porten och nyckeln. Läs %LOCALAPPDATA%\Exsitec\DataLink\endpoint.json — den innehåller loopback-port och en key som skapas vid varje start.

3. Säg hej. GET http://127.0.0.1:{port}/v1/status med headern X-DataLink-Key: {key}. Du får versionen och om du är inloggad.

4. Välj ett företag. GET /v1/companies listar företagen du kan komma åt, med vad din Data Link-åtkomst och dina behörigheter låter dig göra i varje företag.

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

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

   Svaret är Business NXT:s egen { "data": …, "errors": … }.

2. Så körs den

• Data Link installeras per användare och startar automatiskt när du loggar in i Windows. Den körs tyst i bakgrunden och visar en liten systemfältsikon (nere till höger i aktivitetsfältet, nära klockan).
• Högerklicka på systemfältsikonen för att:
  • se om du är Inloggad eller Utloggad,
  • Logga in / Logga ut (inloggning öppnar webbläsaren till Visma Connect),
  • Öppna loggmapp, Sök efter uppdateringar…, öppna denna användningsdokumentation och Avsluta.
• Du måste vara inloggad innan någon GraphQL-request kan lyckas. Inloggningen är interaktiv (ett webbläsarfönster); därefter förnyas sessionen automatiskt och överlever omstarter av Data Link.
• Kompanjonen har inget ”aktuellt företag”. Varje GraphQL-dokument namnger de företag det arbetar med (useCompany(no: …)), så en körande kompanjon betjänar dem alla.
• Uppdateringar: tray → Sök efter uppdateringar… laddar ned och installerar en ny version i ett steg och startar om Data Link (en notifiering bekräftar den nya versionen). En omstart ger den en ny port och nyckel — se omstartssignalen i avsnitt 3.

Var saker finns

3. Prata med det lokala API:et

Discovery — hitta porten och nyckeln

Kompanjonen väljer en ledig loopback-port vid start och skriver en liten discovery- fil så att betrodda lokala anropare kan hitta 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. API:ets bas-URL är http://127.0.0.1:{port}.
• key — den delade hemlighet som skapas vid varje start. Skicka den på varje request (se nedan). Den ändras varje gång kompanjonen startar om, så läs den på nytt — lagra den aldrig. Tolka filen med en JSON-parser: tecken som + kan skrivas som \u002B-escapes.
• instanceId — identifierar denna körning av kompanjonen (”omstartssignalen”; se nedan).

Bas-URL och versionering

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

Alla endpoints ligger under prefixet /v1 (fältet protocol i discovery- filen); GraphQL-gatewayen är /v1/nxt/graphql. Bind mot 127.0.0.1 (loopback) — kompanjonen lyssnar bara där.

Obligatoriska request-headers

Det finns ingen företagsheader: företaget anges inne i GraphQL-dokumentet.

Svarsrubriker

Omstartssignal. Om värdet i X-DataLink-Instance ändras mellan anrop har kompanjonen startat om. Läs endpoint.json på nytt — både porten och nyckeln kan ha ändrats.

Tidsgränser

• POST /v1/auth/login väntar på att du slutför webbläsarinloggningen (upp till 5 minuter).
• POST /v1/nxt/graphql tar så lång tid som Business NXT tar; stora läsningar kan ta många sekunder. Ge din HTTP-klient en generös timeout (minuter, inte sekunder).

Säkerhetsbegränsningar (varför en webbläsar-fetch avvisas)

Kompanjonen upprätthåller en trust boundary för loopback:

• Requests med en Origin-header avvisas (403) — därför kan en webbsidas fetch() inte nå den. Anropa den från en lokal process (WinHTTP, HttpClient, curl, Python, PowerShell, en VBA WinHttp.WinHttpRequest), inte från JavaScript i webbläsaren.
• Host-headern måste vara 127.0.0.1, localhost eller ::1.
• En saknad eller felaktig nyckel returnerar 401.

4. Endpoint-referens

Varje request behöver X-DataLink-Key. Response-bodys från själva Data Link är JSON med fältnamn i camelCase; POST /v1/nxt/graphql returnerar Business NXT:s body oförändrad.

GET /v1/status

Hälsa och inloggningsstatus. Den fungerar även när du är utloggad.

{
  "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

Startar den interaktiva webbläsarinloggningen och returnerar när den är klar. Ingen body. Den öppnar alltid webbläsaren, även när du redan är inloggad — kontrollera GET /v1/status först om du bara vill logga in vid behov.

{ "authenticated": true }

Om webbläsarflödet inte slutförs inom 5 minuter misslyckas anropet med 503 unavailable (retryable: true); en inloggning som Visma Connect avvisar returnerar 401 unauthorized.

POST /v1/auth/logout

Avslutar Business NXT-sessionen. Returnerar { "authenticated": false }.

GET /v1/companies

Företagen som den aktuella inloggningen kan komma åt (Business NXT:s availableCompanies), varje med sin tenant (Visma.net-kunden det tillhör) och den Data Link-åtkomst och de behörigheter som gäller där — så att du kan slå upp ett företags namn till dess nummer och se vad du får göra innan du försöker.

{
  "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 }
  ]
}

Ett företag som listas med canRead: false är ett företag som din Visma-inloggning kan se men som Data Link inte öppnar för dig (se avsnitt 5).

POST /v1/nxt/graphql — gatewayen

Kör valfri Business NXT GraphQL-query eller mutation. Bodyn är standard GraphQL-over-HTTP:

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

Vad som händer:

1. Data Link parsar dokumentet och räknar ut varje företag det läser, skriver eller tar bort i (avsnitt 6).
2. Den kontrollerar din Data Link-åtkomst och dina behörigheter för vart och ett. Om något inte är tillåtet avvisas hela dokumentet och inget når Business NXT.
3. Annars vidarebefordrar den din request-body oförändrad till Business NXT under din Visma-inloggning och returnerar Business NXT:s HTTP-status och body ordagrant — inklusive Business NXT:s egna errors och extensions (till exempel 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 förnyar din Visma-token själv och, när Business NXT svarar 429 Too Many Requests, väntar och försöker igen — båda är säkra eftersom requesten inte kördes. Den försöker aldrig igen med något annat, så en mutation kan aldrig köras två gånger; ett 5xx från Business NXT skickas tillbaka till dig som det är.

5. Data Link-åtkomst och behörigheter

Vad du får göra genom Data Link administreras av Exsitec i NxtPlatform admin. Den gamla Config API-portalen för behörighetstilldelning är borta; docs/download-värden ger inte åtkomst.

Data Link begränsar bara vad din egen Visma-användare får göra — den ger aldrig åtkomst som Visma inte skulle ge. Ett företag utanför dina availableCompanies avvisas även om du har åtkomst till dess tenant.

När du inte har Skriv-behörighet någonstans ber Data Link också Visma om en read-only-inloggning nästa gång du loggar in, så Business NXT själv avvisar mutations också.

Din åtkomst och dina behörigheter hämtas från NxtPlatform när du loggar in och uppdateras med några minuters mellanrum, och sparas bara i minnet. Om NxtPlatform inte kan nås fortsätter det senaste svaret att gälla under en kort respitperiod; efter det — eller om Data Link aldrig har nått NxtPlatform sedan den startade — avvisar gatewayen med 503 unavailable (retryable: true) i stället för att köra okontrollerat.

6. Så läser rättighetskontrollen ett dokument

Kontrollen arbetar med det parsade dokumentet, aldrig med dess text, så alias, fragments och variabler kan inte dölja något. Den är avsiktligt strikt:

Ange företaget: useCompany(no: {companyNo})

Varje företagsavgränsad läsning eller skrivning ligger under roten useCompany(no: …). no är företagsnumret från GET /v1/companies — en literal, en variabel eller ett variabel-defaultvärde:

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

(Business NXT:s organisatoriska enheter får nya etiketter per företag; i Demo - Junge Byg Aps 9999 är projekt orgUnit2.)

• Ett dokument kan namnge flera företag, normalt med alias (demo: useCompany(no: 4926238) { … } junge: useCompany(no: 6307615) { … }). Varje företag kontrolleras; ett avslag avslår hela dokumentet.
• no måste lösas till ett heltal. Ett saknat no, null, en sträng eller en odefinierad variabel avvisas med 400 invalid_request.
• Varje operation i dokumentet kontrolleras, inte bara den som operationName väljer.
• Fragments och inline fragments expanderas; @skip och @include ignoreras, så ett villkorligt urval räknas ändå.

Vad varje del av ett dokument kräver

Skriv säkert

Business NXT har inga transaktioner över flera tabeller. Två vanor gör en skrivning förutsägbar:

• Sätt onError: FAIL_TABLE på varje tabelloperation, så att en dålig rad avvisar hela tabelloperationen i stället för att skriva en del av den.
• För att få flera tabelloperationer att lyckas eller misslyckas tillsammans, använd Business NXT:s edit cache: kör dem med useCompany(no: N, persistEditCache: true, partialRequestId: "…") och avsluta med finishEditCache(action: SAVE) (eller DISCARD). Varje request rättighetskontrolleras för sig, som alla andra mutations.

7. Fel

Det finns två slags fel, och båda använder GraphQL:s felformat.

Business NXT:s egna fel — ett GraphQL-fel, ett värde som Business NXT avvisar, en rate limit — kommer tillbaka exakt som Business NXT skickade dem: dess HTTP-status och body { "data": …, "errors": [ … ] }.

Avslag från Data Link själv (requesten nådde 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/* och GET /v1/companies rapporterar sina fel i Data Links vanliga envelope i stället:

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

En okänd sökväg får en enkel 404.

8. Relation till Business NXT GraphQL API

Data Link är Business NXT:s GraphQL API, nått via din egen dator:

• Samma schema, samma dokument. Allt du kan skicka till https://business.visma.net/api/graphql skickar du till /v1/nxt/graphql, med förbehåll för rättighetskontrollen. Använd Vismas Business NXT-dokumentation, eller introspection genom gatewayen, för tabeller, fält och filter.
• Inga tokens att hantera. Data Link håller din Visma Connect-inloggning och lägger till den i varje vidarebefordrad request; ditt program ser aldrig någon token.
• Styrt. Varje dokument kontrolleras mot din Data Link-åtkomst och dina behörigheter innan det lämnar din dator, så Exsitec kan besluta per tenant vem som får läsa, skriva och radera genom Data Link.
• Inget omformas. Svaret är Business NXT:s, byte för byte.

9. Använda den från Excel

Ladda ned och importera de två VBA-modulerna nedan (Alt+F11 -> Arkiv -> Importera fil...). De är standardmoduler och använder bara late binding, så inga ändringar i Verktyg -> Referenser behövs.

Publikt VBA-API

Mönster för knappmakron

Lägg företagsspecifika inställningar och knappmakron 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

För mutations anropar du samma NxtQuery-funktion med ett mutation-dokument. SDK:t försöker aldrig köra mutations igen efter en portändring eller ett transportfel.

Auto-start och inloggning

SDK:t läser %LOCALAPPDATA%\Exsitec\DataLink\endpoint.json. Om filen saknas eller /v1/status inte svarar startar det %LOCALAPPDATA%\Exsitec.DataLink\Exsitec Data Link.exe (eller current\DesktopDataLink.Host.exe) och väntar upp till 30 sekunder.

Före varje anrop kontrollerar det /v1/status. Om du är utloggad talar Excel om att webbläsaren kommer att öppnas, anropar /v1/auth/login och kastar sedan ett fel som säger att du ska köra åtgärden igen när inloggningen är klar. Den ursprungliga GraphQL-requesten körs inte automatiskt efter inloggning.

VBA-felnummer

Meddelanden använder Data Link-trayens språkinställning (ui-settings.json) för engelska, danska, svenska och norska, med engelska som standard.

10. Exempel i andra språk

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

Endast 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. Felsökning

Fortfarande fast? Tray → Öppna loggmapp och skicka den senaste loggfilen till din Exsitec-kontakt — den innehåller inga GraphQL-dokument, belopp, nycklar eller tokens.

12. Ordlista

Det här dokumentet beskriver det lokala v1-API:et. Kompanjonen rapporterar sin körande version i GET /v1/status och i tray-menyn.