> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hotglue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QuickBooks Web Connector

# Connector Details

| Name | Value |
| :- | :- |
| Platform | [QuickBooks Desktop](https://quickbooks.intuit.com/desktop/) |
| Auth Type | On-Premise (QuickBooks Web Connector) |
| Direction | Bidirectional |

# Overview

The [QuickBooks Web Connector (QBWC)](https://developer.intuit.com/app/developer/qbdesktop/docs/get-started/get-started-with-quickbooks-web-connector) is a Windows application from Intuit that ships with QuickBooks Desktop. It acts as a bridge between a QuickBooks company file and a web service: on a schedule you configure, QBWC contacts hotglue, picks up any pending read or write requests, runs them against the company file, and sends the results back.

Compared to the [installed QuickBooks Desktop connector](/connectors/quickbooks-desktop):

* **Nothing to install from hotglue.** Your tenant only needs a `.qwc` configuration file and a connector password. There is no `.exe` to download, run as administrator, or keep in a startup folder.
* **Works with hosted QuickBooks** (e.g. Rightworks), where the Web Connector is already installed.
* **Supports V2 flows.**
* **Tables are selected via field map**, like a normal cloud connector.

Because QBWC polls hotglue on an interval rather than holding an open connection, reads and writes are asynchronous: a job queues its requests and completes once the Web Connector's next sync processes them.

## Enable and set up your connector in hotglue

### Set up your flows

Enable the QuickBooks Web Connector in your read flow, and in your write flow if you need to write data back to QuickBooks Desktop.

The data format for both reads and writes is the same as the installed QuickBooks Desktop connector. For detailed behavior and business logic (upserts, processing order, batching, and per-record errors), see the [connector README](https://github.com/hotgluexyz/target-qbwc).

### What your tenant needs

Each tenant needs two things to connect the Web Connector:

| Item | Description |
| :- | :- |
| Connector password | A string that authenticates the Web Connector to push and pull data for the connected tenant. This is the same password used by the installed connector. |
| `.qwc` file | The configuration file that tells the Web Connector how to communicate with hotglue. It embeds the tenant ID, so each tenant needs their own. |

<Warning>The `.qwc` file and connector password must belong to the same tenant ID. A file paired with another tenant's password will not work.</Warning>

### Set up your tenant

#### Option 1: Use the widget (recommended)

The simplest way to set up a tenant is to link the QuickBooks Web Connector through the hotglue widget, either embedded in your app or opened via a magic link. Linking from the widget handles everything for you:

* Generates the tenant's connector password
* Links the tenant to your flows
* Generates the tenant's `.qwc` file

Once linked, the widget shows a download link for the `.qwc` file and a copy button for the connector password. The tenant can then follow the [end-user instructions](#end-user-instructions) below.

**White-labeling:** The `.qwc` file sets the application name your tenants see in QuickBooks and the Web Connector. To use your own branding for `.qwc` files downloaded from the widget, go to `Settings` > `Connectors` > `Quickbooks Web Connector` and change these values:

```json theme={null}
"qbwc_app_id": "hotglue-web-connector",
"qbwc_app_display_name": "Hotglue Web Connector"
```

#### Option 2: Set up the tenant via API

If you'd rather set up tenants programmatically, you can generate the password, link the tenant, and generate the `.qwc` file yourself.

<Steps>
  <Step title="Generate the connector password">
    The Web Connector accepts the same connector password as the installed connector, and uses the same endpoint to generate it:

    ```bash cURL theme={null} theme={null}
    curl 'https://api.hotglue.com/<ENVIRONMENT_ID>/<READ_FLOW_ID>/<TENANT_ID>/taps/quickbooks-desktop/token?write_flow_id=<WRITE_FLOW_ID>' \
    --header 'x-api-key: <SECRET_API_KEY>'
    ```

    <Tip>If you haven't generated a signing key before, this request will error with:
    **No signing key has been created for this environment.** To resolve, go to `Settings` > `API Keys`, and click `Generate Signing Key`.</Tip>
  </Step>

  <Step title="Link the source">
    Pass the connector password as `token` in the config of a [POST to /linkedSources](/api-reference/v1/linked-sources/link-a-source). Unlike the installed connector, you don't pass `company_file_path` or `tables`; tables are selected via field map.

    ```bash cURL theme={null} theme={null}
    curl 'https://api.hotglue.com/<ENVIRONMENT_ID>/<READ_FLOW_ID>/<TENANT_ID>/linkedSources' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <SECRET_API_KEY>' \
    --data '{
        "source": {
            "tap": "qbwc",
            "config": {
                "token": "<CONNECTOR_PASSWORD>"
            }
        }
    }'
    ```

    <ParamField body="source" type="object" required="true">
      <Expandable body="properties" defaultOpen="true">
        <ParamField body="tap" type="string" required="true">
          `qbwc`
        </ParamField>

        <ParamField body="config" type="object" required="true">
          <Expandable body="properties" defaultOpen="true">
            <ParamField body="token" type="string" required="true">
              The connector password generated in the previous step.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Step>

  <Step title="Link the target (write flows only)">
    If you're writing data to QuickBooks Desktop via a separate V1 write flow, either symlink the target config to the source config, or pass the same `token` in a POST to `/linkedTargets`:

    ```bash cURL theme={null} theme={null}
    curl 'https://api.hotglue.com/<ENVIRONMENT_ID>/<WRITE_FLOW_ID>/<TENANT_ID>/linkedTargets' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <SECRET_API_KEY>' \
    --data '{
        "target": {
            "target": "qbwc",
            "config": {
                "token": "<CONNECTOR_PASSWORD>"
            }
        }
    }'
    ```
  </Step>

  <Step title="Generate the .qwc file">
    Generate the tenant's `.qwc` file from the following public URL:

    ```
    https://qbwc.hotglue.com/qwc?tenant_id=<TENANT_ID>&app_id=hotglue-web-connector&app_display_name=Hotglue+Web+Connector
    ```

    | Parameter | Description |
    | :- | :- |
    | `tenant_id` | The tenant ID. Must match the tenant the connector password was generated for. |
    | `app_id` | Identifier for the application in the Web Connector. Replace to white-label. |
    | `app_display_name` | Name shown to the user in QuickBooks and the Web Connector (URL-encoded). Replace to white-label. |

    <Note>The `.qwc` file isn't secret on its own, since it only works alongside the matching connector password. You must still generate a separate file for each tenant, because it embeds the tenant ID.</Note>
  </Step>
</Steps>

Once you have the connector password and `.qwc` file, send both to your tenant along with the [end-user instructions](#end-user-instructions) below.

### Optional: Connect additional company files

Each QuickBooks company file is connected as its own [subtenant](/key-concepts/tenants/subtenants). For each additional company file:

1. Create a subtenant in hotglue (for example, `test-user_1`).
2. Get a connector password and `.qwc` file for the subtenant, either by linking the Web Connector in the widget for the subtenant, or by following the API steps above with the subtenant ID in place of `<TENANT_ID>`.
3. Have the user open the other company file and repeat the [end-user instructions](#end-user-instructions) with the subtenant's `.qwc` file and password.

## End-user instructions

### Requirements

**1. QuickBooks Desktop with the QuickBooks Web Connector**

Only Windows versions are supported. The Web Connector comes pre-installed with modern versions of QuickBooks Desktop, and is already installed on hosted QuickBooks environments such as Rightworks.

**2. The `.qwc` configuration file**

**3. The connector password**

### Connect the Web Connector

<Warning>If you previously used the hotglue QuickBooks Desktop Connector (`.exe`) on this machine, stop it and remove it from your startup folder before continuing.</Warning>

<Steps>
  <Step title="Open your company file">
    Open QuickBooks Desktop and log in to the company file you want to connect.
  </Step>

  <Step title="Open the Web Connector">
    Go to `File` > `App Management` > `Update Web Services`.
  </Step>

  <Step title="Add the application">
    Click `Add an Application` and select the downloaded `.qwc` file. When QuickBooks asks you to authorize the new web service, click `OK`.
  </Step>

  <Step title="Grant access">
    QuickBooks will ask what access to give the application. Select **Yes, always; allow access even if QuickBooks is not running**, and choose a QuickBooks user that won't cause access conflicts (for example, a user that isn't also logged in to the company file by someone else). Then click `Continue` and `Done`.

    <Info>If you've used the installed hotglue connector, this is the same access prompt you saw then.</Info>
  </Step>

  <Step title="Enter the password and enable syncing">
    You'll return to the Web Connector's list of applications, which now includes the hotglue application. For that application:

    1. Enter the connector password in the `Password` field (click `Yes` if asked to save it).
    2. Check `Auto-Run`, and set `Every Min` to `5`.
    3. Check the checkbox on the left of the application's row, and click `Update Selected`.
  </Step>
</Steps>

Once the update completes successfully, the Web Connector will sync with hotglue every 5 minutes and you're ready to start running jobs.

## Migrating from the installed connector

To move an existing tenant from the installed QuickBooks Desktop connector:

1. Enable the QuickBooks Web Connector in your read and write flows. Your existing export script continues to work as-is.
2. Get the tenant's connector password and `.qwc` file, either by linking the Web Connector in the widget or via the API (see [Set up your tenant](#set-up-your-tenant)).
3. Select tables via field map.
4. Have the tenant stop the installed connector, remove it from their startup folder, and follow the [end-user instructions](#end-user-instructions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.