Business NXT API

https://docs.vismasoftware.no/businessnxtapi/
Admin
Business NXT API provides a GraphQL server-side runtime for integrators to build integrations...
Tokens:240,758
Snippets:1,162
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example URL with identity query parameters

Source: https://docs.vismasoftware.no/businessnxtapi/apps/development

Shows the query parameters Business NXT appends to your app's URL when it loads. Use these parameters to get the current context, such as companyNo, customerNo, layoutNo, elementNo, sub, user, and locale.

```text
https://your-app.example.com/?customerNo=1182082&companyNo=5051201&layoutNo=50466&elementNo=1&sub=<guid>&user=...&locale=nb-NO
```

--------------------------------

### businessnxt-list_skills

Source: https://docs.vismasoftware.no/businessnxtapi/ai/mcp

Lists available workflow skill guides (for example order management, associate management) with summaries and tags.

```APIDOC
## businessnxt-list_skills

### Description
Lists available workflow skill guides (for example _order management_ , _associate management_) with summaries and tags.

### Method
MCP Tool

### Endpoint
businessnxt-list_skills

### Response
#### Success Response
- **skills** (array) - List of skill guides with summaries and tags.

```

--------------------------------

### Scaffold a Vite project with the Business NXT SDK

Source: https://docs.vismasoftware.no/businessnxtapi/apps/sample

Commands to create a new Vite project with the vanilla-ts template, install the @business-nxt/app-messaging and @vsn-ux/gaia-styles packages, and install the basic SSL plugin as a dev dependency.

```bash
npm create vite@latest my-app -- --template vanilla-ts
cd my-app
npm install @business-nxt/app-messaging @vsn-ux/gaia-styles
npm install -D @vitejs/plugin-basic-ssl
```

--------------------------------

### SQL GROUP BY example

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/queries/grouping

Groups orders by customer and counts orders and sums their values.

```sql
SELECT CustNo, Count([OrdNo]), SUM(DNOrdSum)
FROM [Ord]
GROUP BY CustNo
```

--------------------------------

### GetCustomers GraphQL query example

Source: https://docs.vismasoftware.no/businessnxtapi/intro/exploring_api

A complete GraphQL query example named GetCustomers. It uses variables companyNo and pageSize, and includes the operationName property. The query fetches customer data using the useCompany and associate fields.

```json
{
   "query":"query GetCustomers($companyNo: Int, $pageSize: Int, $after :String)\n{\n  useCompany(no: $companyNo)\n  {\n    associate(first: $pageSize, after: $after)\n    {\n      totalCount\n      pageInfo\n      {\n        hasNextPage\n        hasPreviousPage\n        startCursor\n        endCursor\n      }\n      items\n      {\n        associateNo\n        customerNo\n        name\n      }\n    }\n  }\n}",
   "variables":{"companyNo":9112233,"pageSize":5},
   "operationName":"GetCustomers"
}
```

--------------------------------

### ExecuteGraphQL example from @business-nxt/app-messaging

Source: https://docs.vismasoftware.no/businessnxtapi/apps/development

Use the ExecuteGraphQL helper from the official SDK to run a GraphQL query. It resolves with data and rejects with GraphQLRequestError when the response carries errors. The example includes a timeout of 30000 ms.

```typescript
import { ExecuteGraphQL } from "@business-nxt/app-messaging";

const data = await ExecuteGraphQL(
  /* GraphQL */ `query GetAssociates($companyNo: Int!) { useCompany(no: $companyNo) { associate(first: 10) { items { associateNo name } } } }`,
  { companyNo: 5051201 },
  { operationName: "GetAssociates", timeout: 30000 },
);
```

--------------------------------

### Result for CONTINUE example

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/inserts

Shows the JSON response for the CONTINUE example. The first record fails due to customerNo assignment, the second succeeds despite orgUnit1 error, and the third succeeds. affectedRows is 2 and items contains null for the first record.

```json
{
  "errors": [
    {
      "message": "Error: Field value can only be allocated automatically, in accordance to choice in Company data.",
      "path": [
        "useCompany",
        "associate_create",
        "values/0",
        "customerNo"
      ],
      "extensions": {
        "data": {
          "status": 9,
          "status_name": "notLegalToEditField"
        },
        "details": "GraphQL.ExecutionError: Error: Field value can only be allocated automatically, in accordance to choice in Company data."
      }
    },
    {
      "message": "Error: Avdeling 12345678 does not exist.",
      "path": [
        "useCompany",
        "associate_create",
        "values/1",
        "orgUnit1"
      ],
      "extensions": {
        "data": {
          "status": 16,
          "status_name": "referenceNotAccepted"
        },
        "details": "GraphQL.ExecutionError: Error: Avdeling 12345678 does not exist."
      }
    }
  ],
  "data": {
    "useCompany": {
      "associate_create": {
        "affectedRows": 2,
        "items": [
          null,
          {
            "associateNo": 10001,
            "customerNo": 0,
            "name": "must fail",
            "orgUnit1": 0
          },
          {
            "associateNo": 9999,
            "customerNo": 0,
            "name": "must succeed",
            "orgUnit1": 0
          }
        ]
      }
    }
  }
}
```

--------------------------------

### associate_create with suggest argument

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/inserts

Example of creating an associate with a suggested customerNo value using the suggest argument.

```APIDOC
## Mutation associate_create (suggest argument)

### Description
Creates an associate record with a suggested value for the customerNo field. The suggest argument applies to all values in the values array.

### Method
mutation

### Endpoint
useCompany.associate_create

### Parameters
#### Request Body
- **values** (array) - Required - Array of associate objects
  - **name** (string) - Required - Name of the associate
  - **customerNo** (integer) - Required - Value to be suggested (e.g., 0)
  - **countryNo** (integer) - Optional - Country number
  - **currencyNo** (integer) - Optional - Currency number
- **suggest** (object) - Optional - Object specifying which fields to suggest
  - **customerNo** (boolean) - Required - Set to true to suggest customerNo

### Request Example
```
mutation {
  useCompany(no: $cid) {
    associate_create(
      values: [{
        name: "Test Customer",
        customerNo: 0,
        countryNo: 47,
        currencyNo: null
      }],
      suggest: {
        customerNo: true
      }
    ) {
      affectedRows
      items {
        associateNo
        customerNo
        name
      }
    }
  }
}
```

### Response
#### Success Response
- **affectedRows** (integer) - Number of affected rows
- **items** (array) - Array of created associates
  - **associateNo** (integer) - Associate number
  - **customerNo** (integer) - Suggested customer number
  - **name** (string) - Name of the associate

#### Response Example
```
{
  "data": {
    "useCompany": {
      "associate_create": {
        "affectedRows": 1,
        "items": [
          {
            "associateNo": 187,
            "customerNo": 10928,
            "name": "Test Customer"
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Create order and lines result

Source: https://docs.vismasoftware.no/businessnxtapi/examples/howto/order

Example response from the create_order mutation, showing affectedRows and the created order with its lines.

```json
{
  "data": {
    "useCompany": {
      "order_create": {
        "affectedRows": 1,
        "items": [
          {
            "orderNo": 439,
            "orderDate": 20250917
            "orderLines": {
              "items": [
                {
                  "lineNo": 1,
                  "productNo": "HW1",
                  "quantity": 1,
                  "priceInCurrency": 100
                },
                {
                  "lineNo": 2,
                  "productNo": "AGG4",
                  "quantity": 2,
                  "priceInCurrency": 75
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Run the app with npm run dev and build

Source: https://docs.vismasoftware.no/businessnxtapi/apps/sample

Commands to start the local dev server and build static files to dist/. Deploy the contents of dist/ to the HTTPS origin your app is served from.

```bash
npm run dev     # local dev server
npm run build   # outputs static files to dist/
```

--------------------------------

### businessnxt-init

Source: https://docs.vismasoftware.no/businessnxtapi/ai/mcp

Starts the session and returns the list of companies the user can access, including companyNo and tenantId for each. Call this first.

```APIDOC
## businessnxt-init

### Description
Starts the session. Returns the list of companies the user can access (with `companyNo` and `tenantId` for each). Call this first.

### Method
MCP Tool

### Endpoint
businessnxt-init

### Response
#### Success Response
- **companies** (array) - List of companies with `companyNo` and `tenantId`.

```

--------------------------------

### sortOrder without _thenBy (Error Example)

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/features/sorting

Example query showing the error when multiple fields are specified in sortOrder without using _thenBy.

```APIDOC
## GraphQL Query: postalAddress with sortOrder (Error Case)

### Description
Attempts to sort by multiple fields (postalArea and postCode) without using _thenBy, resulting in an error message and fallback sorting.

### Method
GraphQL Query

### Endpoint
Not specified (GraphQL query)

### Parameters
#### Query Variables
- **cid** (Int!) - Required - Company ID used in the useCompany field.

#### Query Arguments
- **first** (Int) - Required - Number of items to fetch (3 in example).
- **sortOrder** (Object) - Required - Sort order specification. Contains multiple fields without _thenBy.
  - **postalArea** (Enum) - Required - Sort direction (ASC or DESC) for postalArea.
  - **postCode** (Enum) - Required - Sort direction (ASC or DESC) for postCode.

### Request Example
```graphql
query read($cid: Int!)
{
  useCompany(no :$cid)
  {
    postalAddress(
      first : 3,
      sortOrder:
      {
        postalArea:ASC
        postCode:ASC
      })
    {
      totalCount
      items
      {
        postCode
        postalArea
      }
    }
  }
}
```

### Response
#### Error Response
- **errors** (Array) - List of errors.
  - **message** (String) - Error message indicating more than one field specified in one sort clause.
- **data** (Object) - Contains the result, but sorted in alphabetical order of the specified columns.
  - **useCompany** (Object) - Company context.
    - **postalAddress** (Object) - The queried postal addresses.
      - **totalCount** (Int) - Total number of matching records.
      - **items** (Array) - List of postal address objects.
        - **postCode** (String) - Postal code.
        - **postalArea** (String) - Postal area name.

#### Response Example
```json
{
  "errors": [
    {
      "message": "More than one field is specified in one sort clause (postCode,postalArea). The result may be incorrect. Use the _thenBy field to chain multiple table fields in the sort order."
    }
  ],
  "data": {
    "useCompany": {
      "postalAddress": {
        "totalCount": 5093,
        "items": [
          {
            "postCode": "0001",
            "postalArea": "OSLO"
          },
          {
            "postCode": "0010",
            "postalArea": "OSLO"
          },
          {
            "postCode": "0015",
            "postalArea": "OSLO"
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### businessnxt-init_company

Source: https://docs.vismasoftware.no/businessnxtapi/ai/mcp

Second step. Loads the tenant’s full schema and the selected company’s configuration. Required before any query, skill or mutation.

```APIDOC
## businessnxt-init_company

### Description
Second step. Loads the tenant’s full schema (core tables and data model extensions) and the selected company’s configuration — org-unit dimension labels, account-number series, voucher series, open accounting periods and behaviour switches. Required before any query, skill or mutation.

### Method
MCP Tool

### Endpoint
businessnxt-init_company

### Parameters
#### Request Body
- **companyNo** (string) - Required - The company number.
- **tenantId** (string) - Required - The tenant identifier.

### Response
#### Success Response
- **schema** (object) - The tenant’s full schema.
- **configuration** (object) - The selected company’s configuration.

```

--------------------------------

### Transform filter/value query to filters/values (example)

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/updates

Shows the same update query using the filter/value pair, which can be transformed into a filters/values query. This example is labeled 'filter & value'.

```graphql
mutation update_lang($cid : Int!)
{
  useCompany(no:$cid)
  {
    associate_update(
      filter : {associateNo : {_gt : 546}},
      value:{languageNo:44})
    {
      affectedRows
      items
      {
        associateNo
        customerNo
        name
        shortName
        languageNo
      }
    }
  }
}
```

--------------------------------

### Program.cs: Configure and run the ASP.NET Core host

Source: https://docs.vismasoftware.no/businessnxtapi/authentication/web/examples/code

The Program.cs file sets up the ASP.NET Core host builder and starts the application. It specifies the Startup class that configures services and the request pipeline.

```csharp
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

namespace MvcCode
{
   public class Program
   {
      public static void Main(string[] args)
      {
         CreateHostBuilder(args).Build().Run();
      }

      public static IHostBuilder CreateHostBuilder(string[] args) =>
          Host.CreateDefaultBuilder(args)
              .ConfigureWebHostDefaults(webBuilder =>
              {
                 webBuilder.UseStartup<Startup>();
              });
   }
}
```

--------------------------------

### JWT access token payload example

Source: https://docs.vismasoftware.no/businessnxtapi/authentication/oauth

Example payload of a JWT access token from Visma Connect, as shown on jwt.io. Contains claims like iss, aud, iat, exp, sub, and scope.

```json
{
  "nbf": 1648744531,
  "exp": 1648748131,
  "iss": "https://connect.visma.com",
  "aud": "https://business.visma.net/api/graphql",
  "client_id": "...",
  "sub": "42fd1681...",
  "auth_time": 1648744530,
  "idp": "Visma Connect",
  "llt": 1648641021,
  "acr": "3",
  "jti": "0271242A...",
  "sid": "203b1c01...",
  "iat": 1648744531,
  "scope": [
    "openid",
    "email",
    "profile",
    "business-graphql-api:access-group-based"
  ],
  "amr": [
    "pwd",
    "otp"
  ]
}
```

--------------------------------

### Startup.cs: Configure OpenID Connect and cookie authentication

Source: https://docs.vismasoftware.no/businessnxtapi/authentication/web/examples/code

Startup.cs configures OpenID Connect authentication with cookie authentication, including the OpenID Connect handler for 'oidc' scheme. Key settings: Authority, ClientId, and ClientSecret are read from application settings; response type is 'code id_token'; scopes are 'openid', 'profile', 'email', 'business-graphql-api:access-group-based', and 'offline_access' (the latter only when offline access is required). The configuration sets UsePkce, requests claims from the userinfo endpoint, and saves tokens.

```csharp
using IdentityModel;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http;
using IdentityModel.Client;
using Microsoft.IdentityModel.Logging;
using System.Threading.Tasks;
using Microsoft.Extensions.Configuration;

namespace MvcCode
{
   public class Startup
   {
      public Startup(IConfiguration configuration)
      {
         Configuration = configuration;
      }

      public IConfiguration Configuration { get; }

      public void ConfigureServices(IServiceCollection services)
      {
         JwtSecurityTokenHandler.DefaultMapInboundClaims = false;

         services.AddControllersWithViews();

         services.AddHttpClient();

         services.AddOptions();

         services.Configure<AppSettings>(Configuration);

         services.AddSingleton<IDiscoveryCache>(r =>
         {
            var factory = r.GetRequiredService<IHttpClientFactory>();
            return new DiscoveryCache(Configuration.GetValue<string>("Authority"), 
                                      () => factory.CreateClient());
         });

         services.AddAuthentication(options =>
         {
            options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = "oidc";
         })
         .AddCookie(options =>
         {
            options.Cookie.Name = "mvccode";
         })
         .AddOpenIdConnect("oidc", options =>
         {
            options.Events.OnTokenResponseReceived = (tokenResponse) =>
            {
               var accessToken = tokenResponse.TokenEndpointResponse.AccessToken;
               return Task.CompletedTask;
            };
            options.Events.OnRemoteFailure = (err) =>
            {
               return Task.CompletedTask;
            };
            options.Events.OnMessageReceived = (msg) =>
            {
               return Task.CompletedTask;
            };

            options.Authority = Configuration.GetValue<string>("Authority");
            options.RequireHttpsMetadata = false;            

            options.ClientId = Configuration.GetValue<string>("ClientId");
            options.ClientSecret = Configuration.GetValue<string>("ClientSecret");

            options.ResponseType = "code id_token";
            options.UsePkce = true;

            options.Scope.Clear();
            options.Scope.Add("openid");
            options.Scope.Add("profile");
            options.Scope.Add("email");
            options.Scope.Add("business-graphql-api:access-group-based");
            options.Scope.Add("offline_access");

            options.GetClaimsFromUserInfoEndpoint = true;
            options.SaveTokens = true;

            options.TokenValidationParameters = new TokenValidationParameters
            {
               NameClaimType = JwtClaimTypes.Name,
               RoleClaimType = JwtClaimTypes.Role,
            };
         });         
      }

      public void Configure(IApplicationBuilder app)
      {
         IdentityModelEventSource.ShowPII = true;

         app.UseDeveloperExceptionPage();
         app.UseHttpsRedirection();
         app.UseStaticFiles();

         app.UseRouting();

         app.UseAuthentication();
         app.UseAuthorization();

         app.UseEndpoints(endpoints =>
         {
            endpoints.MapDefaultControllerRoute()
                   .RequireAuthorization();
         });
      }
   }
}
```

--------------------------------

### C# Main method to execute and process GraphQL query

Source: https://docs.vismasoftware.no/businessnxtapi/intro/exploring_api/code

Shows how to create a request, execute it, and process the result. It sets the API URL, access token, company ID, and page size, then prints the account number and name for each item.

```csharp
class Program
{
   static async Task Main(string[] args)
   {
      var url = "https://business.visma.net/api/graphql";
      var accessToken = "...";
      var companyId = ...;
      var pageSize = 100;

      var request = new QueryRequest()
      {
         query =
@"query read_glas($cid : Int, $pagesize : Int){
useCompany(no: $cid) {
   generalLedgerAccount(first: $pagesize) {
         totalCount
         pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
         }
         items {
            accountNo
            name
         }
   }
}
}",
         variables = new Dictionary<string, object>
         {
            {"cid", companyId},
            {"$pagesize", pageSize}
         }
      };

      var result = await ExecuteQuery<GeneralLedgerAccountResponse>(request, url, accessToken);
      if (result?.data?.useCompany?.generalLedgerAccount?.items is object)
      {
         foreach (var gla in result.data.useCompany.generalLedgerAccount.items)
         {
            Console.WriteLine($"{gla.accountNo} - {gla.name}");
         }
      }
   }
}
```

--------------------------------

### businessnxt-get_skill

Source: https://docs.vismasoftware.no/businessnxtapi/ai/mcp

Loads a skill guide by id or search query. Optionally fetches live reference data for a given company and checks user access to required tables.

```APIDOC
## businessnxt-get_skill

### Description
Loads a skill guide by id or search query. Optionally fetches live reference data (number series, countries, …) for a given company. When called with `company_no`, also checks the user’s access to the tables the skill needs and surfaces an upfront warning if any read or write permission is missing.

### Method
MCP Tool

### Endpoint
businessnxt-get_skill

### Parameters
#### Request Body
- **id** (string) - Optional - The skill guide id.
- **query** (string) - Optional - A search query.
- **company_no** (string) - Optional - The company number for fetching live reference data and access checks.

### Response
#### Success Response
- **skill** (object) - The skill guide content.
- **referenceData** (object) - Optional live reference data.
- **accessWarnings** (array) - Optional list of missing permissions.

```

--------------------------------

### batch_create with _suggest field

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/inserts

Example of creating a batch with multiple vouchers, using the _suggest field to suggest values for batchNo, voucherNo, and voucherDate.

```APIDOC
## Mutation batch_create (_suggest field)

### Description
Creates a batch with multiple vouchers. The _suggest field allows per-record suggestion specifications, supporting composite object creation.

### Method
mutation

### Endpoint
useCompany.batch_create

### Parameters
#### Request Body
- **values** (array) - Required - Array of batch objects
  - **batchNo** (integer) - Required - Batch number (suggested)
  - **voucherSeriesNo** (integer) - Required - Voucher series number
  - **vouchers** (array) - Required - Array of voucher objects
    - **voucherNo** (integer) - Required - Voucher number (suggested)
    - **voucherDate** (integer) - Required - Voucher date (suggested)
    - **amountDomestic** (number) - Required - Amount in domestic currency
    - **creditAccountType** (integer) - Optional - Credit account type
    - **creditAccountNo** (integer) - Optional - Credit account number
    - **debitAccountType** (integer) - Optional - Debit account type
    - **debitAccountNo** (integer) - Optional - Debit account number
    - **_suggest** (object) - Optional - Suggestion specification for this voucher
      - **voucherNo** (boolean) - Required - Set to true to suggest voucherNo
      - **voucherDate** (boolean) - Required - Set to true to suggest voucherDate
  - **_suggest** (object) - Optional - Suggestion specification for the batch
    - **batchNo** (boolean) - Required - Set to true to suggest batchNo

### Request Example
```
mutation create_batch($cid : Int!, $vsn : Int!, $sno : Int!,
                      $debit1 : Int!, $debit2 : Int!)
{
   useCompany(no : $cid)
   {
      batch_create(values:[
        {
            batchNo : 0
            voucherSeriesNo : $vsn
            vouchers : [
                {
                    voucherNo: 0
                    voucherDate : 0
                    amountDomestic: 1300
                    creditAccountType: 2
                    creditAccountNo: $sno
                    _suggest : {
                        voucherNo : true
                        voucherDate : true
                    }
                },
                {
                    voucherNo: 0
                    voucherDate : 0
                    amountDomestic: 600
                    debitAccountType: 3
                    debitAccountNo: $debit1
                    _suggest : {
                        voucherNo : true
                        voucherDate : true
                    }
                },
                {
                    voucherNo: 0
                    voucherDate : 0
                    amountDomestic: 700
                    debitAccountType: 3
                    debitAccountNo: $debit2
                    _suggest : {
                        voucherNo : true
                        voucherDate : true
                    }
                }
            ]
            _suggest : {
                batchNo : true
            }
        }
        ])
        {
            affectedRows
            items 
            {
                batchNo

                joindown_Voucher_via_Batch
                {
                    items
                    {
                        batchNo
                        voucherNo
                        voucherDate
                        debitAccountNo
                        creditAccountNo
                        amountDomestic
                    }
                }
            }
        }
    }
}
```

### Response
#### Success Response
- **affectedRows** (integer) - Number of affected rows
- **items** (array) - Array of created batches
  - **batchNo** (integer) - Batch number
  - **joindown_Voucher_via_Batch** (object) - Related vouchers
    - **items** (array) - Array of vouchers
      - **batchNo** (integer) - Batch number
      - **voucherNo** (integer) - Voucher number
      - **voucherDate** (integer) - Voucher date
      - **debitAccountNo** (integer) - Debit account number
      - **creditAccountNo** (integer) - Credit account number
      - **amountDomestic** (number) - Amount in domestic currency

#### Response Example
(Not provided in source)
```

--------------------------------

### Aggregate query example

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/queries/aggregates

Example GraphQL query using aggregate functions on the order_aggregate field. Demonstrates count, sum, average, minimum, maximum, and variance. The query uses a company ID variable and filters via useCompany.

```graphql
query read($cid : Int!)
{
  useCompany(no: $cid)
  {
    order_aggregate
    {
      count
      {
        orderNo
      }

      sum
      {
        orderSumNetDomestic
        vatAmountDomestic
      }

      average
      {
        orderSumNetDomestic
        vatAmountDomestic
      }

      minimum
      {
        orderDate
        orderSumNetDomestic
        vatAmountDomestic
      }

      maximum
      {
        orderDate
        orderSumNetDomestic
        vatAmountInCurrency
      }

      variance
      {
        orderSumNetDomestic
        vatAmountDomestic
      }
    }
  }
}
```

--------------------------------

### Result of useCompany query

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/queries/query

Example JSON response for the useCompany query. Shows totalCount, pagination cursors, and a list of account items with accountNo and name.

```json
{
  "data": {
    "useCompany": {
      "generalLedgerAccount": {
        "totalCount": 340,
        "pageInfo": {
          "hasNextPage": false,
          "hasPreviousPage": false,
          "startCursor": "MA==",
          "endCursor": "MzQw"
        },
        "items": [
          {
            "accountNo": 1000,
            "name": "Forskning og utvikling"
          },
          {
            "accountNo": 1020,
            "name": "Konsesjoner"
          },
          {
            "accountNo": 1030,
            "name": "Patenter"
          },

          {
            "accountNo": 9999,
            "name": "Observasjonskonto"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Batch multiple inserts into a single request (Not recommended)

Source: https://docs.vismasoftware.no/businessnxtapi/examples/bestpractices

This example shows the inefficient approach of inserting each record in a separate mutation request. It is not recommended because it incurs performance penalties. The example includes three separate mutations, each inserting a single voucher record.

```graphql
mutation create_voucher($cid: Int, $batchId: Int!)
{
   useCompany(no: $cid)
   {
      voucher_create(values: [{
            batchNo: $batchId
            voucherNo : null
            voucherDate: null
            amountDomestic: 1300
            creditAccountType: 2
            creditAccountNo: 50000
         }])
      {
         affectedRows
         items
         {
            voucherNo
         }
      }
   }
}

mutation create_voucher($cid: Int, $batchId: Int!)
{
   useCompany(no: $cid)
   {
      voucher_create(values: [{
            batchNo: $batchId
            voucherNo : null
            voucherDate: null
            amountDomestic: 600
            debitAccountType: 3
            debitAccountNo: 4300
         }])
      {
         affectedRows
         items
         {
            voucherNo
         }
      }
   }
}

mutation create_voucher($cid: Int, $batchId: Int!)
{
   useCompany(no: $cid)
   {
      voucher_create(values: [{
            batchNo: $batchId
            voucherNo : null
            voucherDate: null
            amountDomestic: 700
            debitAccountType: 3
            debitAccountNo: 1930
         }])
      {
         affectedRows
         items
         {
            voucherNo
         }
      }
   }
}
```

--------------------------------

### Implement main.ts with GraphQL query and selection request

Source: https://docs.vismasoftware.no/businessnxtapi/apps/sample

Main application logic. It imports the Gaia styles, reads the company number from the URL, defines a GraphQL query, and on button click executes the query using ExecuteGraphQL. It also sends a selection-state-request message on startup to get the current selection. Handles GraphQLRequestError and other errors.

```typescript
import "@vsn-ux/gaia-styles/all.css";
import {
  ExecuteGraphQL,
  GraphQLRequestError,
  SendMessage,
} from "@business-nxt/app-messaging";

// Business NXT passes the current context in the iframe URL.
const companyNo = Number(new URLSearchParams(location.search).get("companyNo"));

const status = document.getElementById("status")!;
const list = document.getElementById("list")!;

const GetAssociates = /* GraphQL */ `
  query GetAssociates($companyNo: Int!, $first: Int!) {
    useCompany(no: $companyNo) {
      associate(first: $first) {
        items { associateNo name }
      }
    }
  }
`;

interface Associates {
  useCompany: { associate: { items: { associateNo: number; name: string }[] } };
}

document.getElementById("load")!.addEventListener("click", async () => {
  status.textContent = "Loading...";
  list.replaceChildren();
  try {
    const data = await ExecuteGraphQL<Associates>(
      GetAssociates,
      { companyNo, first: 10 },
      { operationName: "GetAssociates" },
    );
    const items = data.useCompany.associate.items;
    status.textContent = `${items.length} associate(s) in company ${companyNo}`;
    for (const a of items) {
      const li = document.createElement("li");
      li.textContent = `${a.associateNo} - ${a.name}`;
      list.appendChild(li);
    }
  } catch (err) {
    status.textContent =
      err instanceof GraphQLRequestError
        ? err.message
        : "The associates couldn't be loaded.";
  }
});

// Ask Business NXT for the current row selection on startup.
SendMessage({ messageType: "selection-state-request" })
  .then((selection) => console.log("Current selection:", selection))
  .catch((err) => console.warn("No selection yet:", err));
```

--------------------------------

### Start Edit Session and Create Order with Order Lines

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/editcache

This mutation starts an edit session by setting persistEditCache to true, creates an order with one order line, and then adds another order line within the same session. It returns a partialRequestId for subsequent requests.

```APIDOC
## Mutation: create_order

### Description
Starts an edit session and creates an order with order lines. The persistEditCache argument is set to true to enable the edit cache. The response includes a partialRequestId for subsequent requests.

### Method
MUTATION

### Endpoint
useCompany

### Parameters
#### Arguments (on useCompany)
- **no** (Int!) - Required - Company number.
- **persistEditCache** (Boolean) - Required - Set to true to start an edit session.

#### Variables
- **cid** (Int!) - Required - Company number.
- **cno** (Int) - Optional - Customer number.
- **pno1** (String) - Optional - Product number for first order line.
- **pno2** (String) - Optional - Product number for second order line.
- **ono** (Int) - Optional - Order number, default 0.

### Request Example
```graphql
mutation create_order($cid:Int!,
                      $cno : Int,
                      $pno1 : String,
                      $pno2 : String,
                      $ono : Int = 0)
{
  useCompany(no:$cid, persistEditCache : true)
  {
    partialRequestId
  
    order_create(values:[
      {
        customerNo : $cno
        orderLines : [
          {
            productNo : $pno1,
            quantity : 1
          }
        ]
      }
    ])
    {
      affectedRows
      items
      {
        orderNo @export(as: "ono")
        customerNo
      }
    }
  
    orderLine_create(values:[{
      orderNo : $ono,
      productNo : $pno2,
      quantity : 1
    }])
    {
      affectedRows
      items
      {
        orderNo
        lineNo
        productNo
        quantity
        priceInCurrency
      }
    }
  }
}
```

### Response
#### Success Response
- **data.useCompany.partialRequestId** (String) - Session identifier for the edit cache.
- **data.useCompany.order_create.affectedRows** (Int) - Number of affected rows.
- **data.useCompany.order_create.items** (Array) - Created order items.
- **data.useCompany.orderLine_create.affectedRows** (Int) - Number of affected rows.
- **data.useCompany.orderLine_create.items** (Array) - Created order line items.

#### Response Example
```json
{
  "data": {
    "useCompany": {
      "partialRequestId": "097ADD2B-C197-4AD3-B639-4FF5BB197325",
      "order_create": {
        "affectedRows": 1,
        "items": [
          {
            "orderNo": 3442,
            "customerNo": 10001
          }
        ]
      },
      "orderLine_create": {
        "affectedRows": 1,
        "items": [
          {
            "orderNo": 3442,
            "lineNo": 2,
            "productNo": "101",
            "quantity": 1,
            "priceInCurrency": 0
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Update order line webhook payload example

Source: https://docs.vismasoftware.no/businessnxtapi/webhooks

Example JSON payload sent by a Business NXT webhook when an order line is updated. The payload includes the table identifier, event type, primary keys, and changed columns. Some elements in changedColumns are omitted for brevity.

```json
{
    "tableIdentifier":"OrderLine",
    "tableNo":128,
    "customerNo":4801958,
    "companyNo":5199768,
    "event":"UPDATE",
    "primaryKeys": [
        {"OrderNo":3},
        {"LineNo":1}
    ],
    "timestamp":"2025-02-06T21:15:28.3971469Z",
    "changedByUser":"ola.normann",
    "changedColumns":[
        {"Description":"Hello webhook"},
        {"ChangedDate":20250206},
        {"ChangedTime":2215},
        {"ChangedByUser":"ola.normann"},
        {"ChangeTimeInMs":80128366},
        {"ChangedTimestamp":20250206211528366}
    ]
}
```

--------------------------------

### Query.useCustomer

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/queries/query

The entry point for accessing system tables. It takes a single argument, the Visma.net customer ID.

```APIDOC
## Query.useCustomer

### Description
The entry point for accessing system tables. It takes a single argument, the Visma.net customer ID.

### Field
`useCustomer`

### Arguments
- **customerId** (ID) - Required - The Visma.net customer ID.

### Returns
System table connections (Query_UseCustomer type).
```

--------------------------------

### Successful async result

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/async

Example response when the asynchronous operation has completed successfully.

```json
{
  "data": {
    "asyncResult": {
      "operationId": "caa8812d-fdb2-4546-86a9-eab30e9dde20",
      "status": "SUCCESS",
      "error": null,
      "data": "{\"data\":{\"useCompany\":{\"generalLedgerAccount\":{\"totalCount\":342,\"items\":[{\"accountNo\":1000,\"name\":\"Forskning og utvikling\"},{\"accountNo\":1020,\"name\":\"Konsesjoner\"},{\"accountNo\":1030,\"name\":\"Patenter\"},{\"accountNo\":1040,\"name\":\"Lisenser\"},{\"accountNo\":1050,\"name\":\"Varemerker\"}]}}}",
      "createdAt": "2022-09-23T12:34:07Z",
      "completedAt": "2022-09-23T12:34:11Z"
    }
  },
  "extensions": {
    "vbnxt-trace-id": "ad02666f0531856aaadfc74625dc37f1"
  }
}
```

--------------------------------

### Example create query with onError: CONTINUE

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/inserts

Shows a GraphQL mutation using associate_create with three values and onError: CONTINUE. Assumes no customer 123456 and no cost unit 12345678 exist. Demonstrates that CONTINUE reports errors but persists rows with successful assignments.

```graphql
useCompany(no : $cid)
{
  associate_create(values:[
    {
      customerNo : 123456
    },
    {
      name : "must fail"
      orgUnit1 : 12345678
    },
    {
      associateNo : 9999,
      name : "must succeed"
    }
  ],
  onError : CONTINUE)
  {
    affectedRows
    items
    {
      associateNo
      customerNo
      name
      orgUnit1
    }
  }
}
```

--------------------------------

### GraphQL Query with changedDateTimeTZ

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/datetime

Example of filtering order by changedDateTimeTZ with a timezone offset.

```APIDOC
## GraphQL Query with changedDateTimeTZ

### Description
Example of filtering order by changedDateTimeTZ with a timezone offset.

### Method
GraphQL Query

### Endpoint
Not specified

### Parameters
#### Query Variables
- **$cid** (Int!) - Required - Company ID

#### Filter Fields
- **changedDateTimeTZ** (DateTime) - Optional - Filter with _gte operator, value includes timezone offset

### Request Example
```graphql
query read($cid : Int!)
{
  useCompany(no: $cid)
  {
    order(
      filter : {
        changedDateTimeTZ : {
          _gte : "2023-05-16T09:17:28.659+02:00"}
      }
    )
    {
      totalCount
      items
      {
        orderNo
        orderDate
        changedDateTimeUtc
      }
    }
  }
}
```

### Response
#### Success Response
- **totalCount** (Int) - Total number of items
- **items** (Array) - List of items
  - **orderNo** (String) - Order number
  - **orderDate** (Date) - Order date
  - **changedDateTimeUtc** (DateTime) - Last changed timestamp in UTC

```

--------------------------------

### voucher_create with suggest argument

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/inserts

Example mutation that creates a voucher and uses the `suggest` argument to automatically fill in values for `voucherNo`, `voucherDate`, and `valueDate`.

```APIDOC
## Mutation: voucher_create

### Description
Creates a new voucher record. The `suggest` argument is used to automatically fill in values for specified numerical fields.

### Method
mutation

### Endpoint
useCompany(no: $cid) { voucher_create }

### Parameters
#### Path Parameters
- **cid** (Int!) - Required - Company ID
- **bno** (Int!) - Required - Batch number
- **cno** (Int!) - Required - Credit account number

#### Request Body
- **values** (array of objects) - Required - Array of field-value pairs for the new record. Fields must be in correct order.
- **suggest** (object) - Optional - Object specifying fields to auto-fill. Fields can be `Boolean` or `SuggestIntervalType`.

### Request Example
```graphql
mutation create_voucher($cid : Int!,
                        $bno : Int!,
                        $cno : Int!)
{
   useCompany(no : $cid)
   {
      voucher_create(
         values: [{
            batchNo : $bno
            voucherNo : 0
            voucherDate : 0
            valueDate : 0
            debitAccountNo : 1930
            creditAccountNo: $cno
            customerNo : $cno
            amountDomestic : 100
         }],
         suggest : {
          voucherNo : true,
          voucherDate : true
          valueDate : true
        }
      )
      {
         affectedRows
         items
         {
            batchNo
            voucherNo
            voucherDate
            valueDate
         }
      }
   }
}
```

### Response
#### Success Response (200)
- **affectedRows** (Int) - Number of affected rows
- **items** (array) - Array of created records with requested fields

#### Response Example
```json
{
  "data": {
    "useCompany": {
      "voucher_create": {
        "affectedRows": 1,
        "items": [
          {
            "batchNo": 2,
            "voucherNo": 60003,
            "voucherDate": 20220715,
            "valueDate": 20220715
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Queued async result

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/async

Example response when the asynchronous operation is still queued and not yet completed.

```json
{
    "data": {
        "asyncResult": {
            "operationId": "caa8812d-fdb2-4546-86a9-eab30e9dde20",
            "status": "QUEUED",
            "error": null,
            "data": "null",
            "createdAt": "2022-09-23T12:34:07Z",
            "completedAt": null
        }
    },
    "extensions": {
        "vbnxt-trace-id": "eb52491bfe7268e89d61a1121c0453af"
    }
}
```

--------------------------------

### GraphQL Query with changedDateTime filter

Source: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/datetime

Example of filtering generalLedgerAccount by changedDateTime using the _gte operator.

```APIDOC
## GraphQL Query with changedDateTime filter

### Description
Example of filtering generalLedgerAccount by changedDateTime using the _gte operator.

### Method
GraphQL Query

### Endpoint
Not specified

### Parameters
#### Query Variables
- **$cid** (Int!) - Required - Company ID

#### Filter Fields
- **changedDateTime** (DateTime) - Optional - Filter with _gte operator

### Request Example
```graphql
query read($cid : Int!)
{
  useCompany(no: $cid)
  {
    generalLedgerAccount(filter : {
      changedDateTime : {
        _gte : "2021-10-01T07:00:00"},
    })
    {
      totalCount
      items
      {
        accountNo
        name
        createdDateTime
        changedDateTime
      }
    }
  }
}
```

### Response
#### Success Response
- **totalCount** (Int) - Total number of items
- **items** (Array) - List of items
  - **accountNo** (String) - Account number
  - **name** (String) - Account name
  - **createdDateTime** (DateTime) - Creation timestamp
  - **changedDateTime** (DateTime) - Last changed timestamp

```
Tokens:
Raw