Nxus.Qbd 0.8.1

Nxus.Qbd

Official .NET SDK for the Nxus QuickBooks Desktop API.

Installation

dotnet add package Nxus.Qbd

Quick Start

using Nxus.Qbd;

using var client = new NxusClient(new NxusClientOptions {
    ApiKey = "sk_live_...",
    ConnectionId = "your-connection-id",
});

// List vendors
var page = await client.Vendors.ListAsync(limit: 50);
foreach (var vendor in page.Data) {
    Console.WriteLine(vendor.GetProperty("name").GetString());
}

// Retrieve a single customer
var customer = await client.Customers.RetrieveAsync("80000001-1234567890");

// Create an invoice
var invoice = await client.Invoices.CreateAsync(new {
    customerRefListId = "80000001-1234567890",
});

Sync And Async APIs

The SDK supports both sync and async usage:

// Sync
var vendors = client.Vendors.List(limit: 10);
foreach (var vendor in vendors.Data) {
    Console.WriteLine(vendor.GetProperty("name").GetString());
}

// Async
var asyncPage = await client.Vendors.ListAsync(limit: 10);
await foreach (var vendor in asyncPage) {
    Console.WriteLine(vendor.GetProperty("name").GetString());
}

Environments

The SDK defaults to https://api.nx-us.net/.

For local development, use Environment = NxusEnvironment.Development. An explicit BaseUrl override still wins when you need a custom endpoint:

using var client = new NxusClient(new NxusClientOptions {
    ApiKey = "sk_test_...",
    Environment = NxusEnvironment.Development,
    ConnectionId = "your-connection-id",
});

Timeouts

The SDK defaults to a 30s client timeout. You can override this globally or per request:

using var client = new NxusClient(new NxusClientOptions {
    ApiKey = "sk_live_...",
    ConnectionId = "your-connection-id",
    Timeout = TimeSpan.FromSeconds(60),
});

var page = await client.Transactions.ListAsync(
    limit: 100,
    options: new RequestOptions {
        Timeout = TimeSpan.FromSeconds(45),
    });

List and report calls can also send a backend timeout hint without changing the local HTTP timeout:

var page = await client.Customers.ListAsync(
    limit: 100,
    options: new RequestOptions {
        ServerTimeoutSeconds = 45,
    });

When ServerTimeoutSeconds is provided, the SDK sends it as the X-Nxus-Timeout-Seconds request header and preserves it across pagination calls.

Connection Scoping

Every request requires a QuickBooks Desktop connection context. The easiest path is to set it once on the client:

using var client = new NxusClient(new NxusClientOptions {
    ApiKey = "sk_live_...",
    ConnectionId = "your-connection-id",
});

You can also set it per request:

var vendor = await client.Vendors.RetrieveAsync(
    "80000001-1234567890",
    new RequestOptions {
        ConnectionId = "your-connection-id",
    });

Pagination

All list methods return a CursorPage<T> that supports both manual navigation and auto-pagination:

// Auto-paginate through all records
var firstPage = await client.Customers.ListAsync(limit: 100);
await foreach (var customer in firstPage) {
    Console.WriteLine(customer.GetProperty("name").GetString());
}

// Manual page-by-page navigation
var page = await client.Customers.ListAsync(limit: 50);
while (page.HasNextPage()) {
    page = await page.GetNextPageAsync();
}

If you stop early with break, the SDK best-effort closes the backend cursor automatically so the QuickBooks Desktop lane is released quickly:

var page = await client.Customers.ListAsync(limit: 100);
await foreach (var customer in page) {
    if (customer.GetProperty("name").GetString() == "Acme") {
        break;
    }
}

Examples

Runnable examples live in examples/Nxus.Qbd.Examples/:

The example runner auto-loads a .env file from the repo root. Copy .env.example to .env and fill in your values:

copy .env.example .env

NXUS_API_KEY=sk_test_your_key_here
NXUS_CONNECTION_ID=your_connection_id_here
NXUS_ENVIRONMENT=development

Run an example:

dotnet run --project examples/Nxus.Qbd.Examples -- crud
dotnet run --project examples/Nxus.Qbd.Examples -- pagination

Error Handling

Non-success responses throw NxusApiException:

using Nxus.Qbd.Errors;

try {
    await client.Vendors.RetrieveAsync("non-existent-id");
} catch (NxusApiException ex) {
    Console.WriteLine(ex.Status);
    Console.WriteLine(ex.UserMessage);
    Console.WriteLine(ex.Code);
    Console.WriteLine(ex.RequestId);
}

Resources

All QuickBooks Desktop resources are available as namespaced properties on NxusClient:

Custom fields and data extensions

QuickBooks Desktop uses the same underlying mechanism for both UI-visible custom fields and application-only integration data:

A definition must exist before a value can be written. Definitions are identified by ownerId + name; values add the specific QuickBooks target to that composite identity. QuickBooks may omit DataExtID for private definitions, so SDK consumers must allow DataExtDef.id to be null.

The ownerId determines how a definition is used:

• Public custom field: use "0". The field is visible in the QuickBooks UI, its type must be STR255TYPE, and assignToObjects must contain at least one of Customer, Employee, Item, or Vendor. Public definitions cannot be deleted through the SDK.
• Private data extension: use an application-owned GUID such as "{C3AA84E0-D242-47AB-A12B-3EDA3A2590A2}". The field is available only to applications that know that GUID. assignToObjects is optional; when supplied, it may contain any object type supported by QuickBooks for DataExtDefAdd. The GUID does not require separate registration with QuickBooks.

The assignToObjects property is therefore optional in the SDK request type, but conditionally required by QuickBooks for public definitions. QuickBooks accepts a private definition with the property omitted and returns that definition with an empty assignToObjects list. Supply the intended object assignments before relying on DataExt value writes for those object types.

The normal workflow is:

1. Create the DataExtDef.
2. Create a DataExt value using the same ownerId and field name, plus a target such as a Customer ListID, an Invoice TxnID, or a transaction-line TxnLineID.
3. Update or delete the value using that same composite identity.
4. Delete a private definition only after its values are no longer needed. Public definitions must be managed in the QuickBooks UI because QuickBooks does not support deleting them through DataExtDefDel.

Public fields are typically used for information users should see or edit in QuickBooks. Private extensions are commonly used for external-system identifiers, synchronization or verification markers, workflow state, migration metadata, and other integration data that should not appear in the QuickBooks UI.

License

MIT