QuickBooks Integrator 2020 .NET Edition

Questions / Feedback?

QBConnector Component

Properties   Methods   Events   Configuration Settings   Errors  

The QBCONNECTOR component is a utility that allows you to connect your QuickBooks Integrator applications to remote QuickBooks instances.




The QBConnector component is a lightweight web server which listens for HTTP requests originating from the QuickBooks Integrator components. Each request sent to the QBConnector by a QuickBooks Integrator component contains the XML data to be communicated to QuickBooks as well as configuration settings specifying how the connection is to be opened. The QBConnector then communicates with QuickBooks via COM, and returns the QuickBooks response (or an error message) in the HTTP reply.

Using the QBConnector component is easy. Simply set Listening to True, and the component will begin listening for incoming messages on the specified LocalPort. The messages will be processed by the QuickBooks application that is running on the same machine as the QBConnector, and the results will automatically be returned to the requesting client.

Basic authentication is enabled by default, meaning the connecting clients must present a user name and password in the QBConnectionString of the component they're using. The supplied user name and password are checked against the list of AuthorizedUsers. If no user in the list matches the supplied credentials, the Authorization event will fire with the Accept parameter set to false. If the user was found in the list of AuthorizedUsers then the parameter will be set to True. You may override this functionality by setting the Accept parameter inside the Authorization event manually. If no "Authorization" header supplied in the request, the Authorization event will fire with blank User and Password parameters.

Note that the QBConnectionString will be used to make the connection to QuickBooks for a user found in the AuthorizedUsers collection.

Any of the QuickBooks Integrator components can connect to the QBConnector using the QBConnectionString property of any of the components. For instance, an example using the Invoice component follows:

  Invoice.QBConnectionString = "URL='http://www.foo.com:2080'" User='Foo' Password='Bar'";

Using SSL along with a digital certificate greatly increases the security of the Remote Connector. SSL will encrypt all data transmitted across the network, ensuring that only the Connector can read incoming requests, and that only the requesting client can read the QuickBooks responses. This prevents unauthorized parties from accessing your QuickBooks data. You should use a full digital certificate on the server (Connector) side, and this will contain a public key and a private key. This version of your certificate should be kept private. You may export a version of the certificate containing the public key only, and distribute this to all clients that need to communicate with the Connector.

To use this functionality, set the SSLCert with a valid certificate and then change the SSLStartMode to sslImplicit. Now all clients must post to the QBConnector using HTTPS. eg:

  Invoice.QBConnectionString = "URL='https://www.foo.com:2080' User='Foo' Password='Bar'"; // https instead of http

The client (in these examples Invoice) has an SSLServerAuthentication event that will fire when the server presents its certificate. If the public key presented by the QBConnector is trusted by the system, the Accept parameter will be True. If it is not trusted by the system (Accept is False), you should inspect the certificate and if valid, override by setting Accept to True.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

AuthorizedUsersA list of clients allowed to connect to the server.
ConnectedToQBOpens or closes a persistent connection to QuickBooks.
EnableSSLIndicates whether server starts in SSL-mode.
ListeningIf True, the component accepts incoming connections on LocalPort.
LocalHostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPortThe TCP port in the local host where the component listens.
SSLAuthenticateClientsIf true, the server asks the client(s) for a certificate.
SSLCertThe certificate to be used during SSL negotiation.
TimeoutAn initial timeout value to be used by incoming connections.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

AddUserAdds a new user to the AuthorizedUsers collection.
ConfigSets or retrieves a configuration setting.
DoEventsProcesses events from the internal message queue.
ResetClears all properties to their default values.
ShutdownShutdown the server.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

AuthorizationFired when the client presents its credentials to the server.
ConnectedFired immediately after a connection completes (or fails).
ConnectionRequestFired when a request for connection comes from a remote host.
DisconnectedFired when a connection is closed.
ErrorInformation about errors during data delivery.
HeaderHTTP headers sent by the client.
RequestFired when a client sends a request to the component.
ResponseFired when the component sends a response to the client.
SSLClientAuthenticationFired when the client presents its credentials to the server.
SSLConnectionRequestFires when an SSL connection is requested.
SSLStatusShows the progress of the secure connection.
StatusShows the status of the server as clients connect and transactions are made.

Configuration Settings

The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.

AuthFlagsAuth Flags to use when connecting to QuickBooks.
ConnectedToQBUsed to connect or disconnect from QuickBooks.
DefaultConnectionStringDefault connection string to use for users not in the AuthorizedUsers collection.
ReadOnly[i]Whether a user is restricted to read-only access.
UseInteractiveLogonWhether interactive or network logon is used when AuthMode is set to Windows.
BuildInfoInformation about the product's build.
GUIAvailableTells the component whether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2022 4D Payments Inc. - All rights reserved.
QuickBooks Integrator 2020 .NET Edition - Version 20.0 [Build 8076]