Visma Business NXT — oppsett av ISV / servicebruker

Veiledning for å opprette og godkjenne ISV-appen (Client ID / Client Secret) og tilhørende servicebruker som XENDO bruker mot Visma Business NXT.

Hva er hva?

XENDO lagrer Client ID og Client Secret (kryptert) per selskap, henter tilgjengelige firmaer via availableCustomers / availableCompanies, og synker mot ett valgt vismaNetCompanyId.

Forutsetninger

Token-endepunkt: https://connect.visma.com/connect/token
GraphQL: https://business.visma.net/api/graphql-service

Del 1 — Registrer ISV-app (Developer Portal)

Gjøres én gang per integrasjonsklient (f.eks. isv_…). Samme app kan brukes mot flere kunder når de har godkjent den.

1. Gå til Visma Developer Portal / Visma Connect for app-registrering.
2. Opprett en ny app som Service-integrasjon (client credentials).
3. Noter:
   • Client ID (vises ofte som isv_…) — dette er «ISV-bruker» i XENDO.
   • Client Secret — genereres én gang; lagre sikkert. Rotasjon krever oppdatering i XENDO.
4. Under APIs / scopes, sørg for at Business NXT GraphQL er tilgjengelig. Typiske scopes:
   • business-graphql-service-api:access-group-based-readonly — anbefalt til lesing / synk
   • business-graphql-service-api:access-group-based — full tilgang (inkl. skriving)
5. Under Customers (eller tilsvarende): legg til / inviter kunden som skal bruke appen, og få godkjenning.

Les vs. skriv

• XENDO trenger i praksis lesetilgang for faktura- og økonomisynk.
• Bruk readonly-scope der det er mulig.
• Fullt scope uten -readonly gir skrivetilgang via samme klient — unngås i produksjon med mindre det er bevisst (f.eks. midlertidig test). Egne klienter for revisjon/export anbefales.

XENDO sender ikke scope eller tenant_id i token-kallet. Hvilke rettigheter tokenet får, styres av det som er registrert og godkjent på appen i Visma.

Del 2 — Servicebruker i Visma Business NXT (hos kunden)

1. Logg inn i Visma Business NXT som administrator.
2. Opprett eller finn en servicebruker / integrasjonsbruker.
3. Navnet på servicebrukeren må være det samme som ISV-appens navn i Developer Portal (krav fra Visma for service-integrasjoner).
4. Gi servicebrukeren tilgang til de firmaene (selskaper) som skal synkes til XENDO.
5. Gå til Innstillinger → Integrasjoner → Apper.
6. Finn appen (f.eks. XENDO eller navnet på ISV-appen) og aktiver den for aktuelt firma / kunde.

Uten aktivering og servicebruker-tilgang feiler token eller GraphQL med «access denied» / tom availableCustomers.

Del 3 — Legg inn i XENDO

1. Innstillinger → Integrasjoner → Visma Business NXT.
2. Oppgi ISV-bruker / Client ID og Client Secret.
3. Klikk Hent selskaper og velg ett selskap.
4. Velg prosjekt- og produksjonskodefelt (OrgUnit).
5. Lagre og Test tilkobling.

Detaljer: visma-business-nxt.md.

Sjekkliste

• [ ] ISV-app opprettet som Service-integrasjon
• [ ] Client ID og Client Secret notert (secret lagret sikkert)
• [ ] Korrekt GraphQL-scope (helst readonly)
• [ ] Kunden godkjent under Developer Portal → Customers
• [ ] Servicebruker i NXT med samme navn som appen
• [ ] Servicebruker har tilgang til ønskede firmaer
• [ ] App aktivert under NXT → Integrasjoner → Apper
• [ ] availableCompanies returnerer forventede selskaper
• [ ] Credentials og valgt selskap lagret i XENDO; test tilkobling OK

Feilsøking

Sikkerhet

• Behandle Client Secret som passord. Del kun via sikker kanal.
• Secret vises ikke igjen i XENDO etter lagring (kryptert at rest).
• Unngå å gjenbruke en klient med skrivetilgang til formål som kun trenger lesing (f.eks. revisjonspakker) — bruk egen readonly-klient.
• Kundedata i XENDO ligger i kundens tenant-database.

Relatert

• Visma Developer Portal: https://oauth.developers.visma.com