Introduction
The 4D Payments QuickBooks Connector for QuickBooks is a simple application that facilitates connections to company files from your application. The 4D Payments QuickBooks Connector accepts connections via a lightweight embedded Web server that runs on the machine where QuickBooks is installed. The server supports SSL/TLS, enabling users to connect securely from remote machines.
The first time you connect to QuickBooks, you must authorize your application. Complementing the per-application authentication of QuickBooks, the 4D Payments QuickBooks Connector has per-user authentication. Before connecting to QuickBooks for the first time, configure at least one 4D Payments QuickBooks Connector user.
You can configure users through the UI on the Users tab. You can then follow the procedure in "Getting Started" to connect an application to QuickBooks. After connecting, you can monitor QuickBooks connections on the Users tab.
It is recommended to configure the 4D Payments QuickBooks Connector in the UI, but you can also run the 4D Payments QuickBooks Connector from the command line. This can simplify deploying the 4D Payments QuickBooks Connector in scenarios where normally there is not a user logged in, such as running a Web server. See the Advanced page to configure the 4D Payments QuickBooks Connector when you are not using the UI.
The 4D Payments QuickBooks Connector automatically manages the connection to QuickBooks, but you can configure almost every aspect of how users connect to QuickBooks through the 4D Payments QuickBooks Connector. The following pages outline the capabilities of the 4D Payments QuickBooks Connector and how to get started.
Getting Started
The 4D Payments QuickBooks Connector can be used to read and write to QuickBooks in situations where direct COM access to QuickBooks is not available (e.g., ASP.NET, Java, or QuickBooks on a remote machine). Follow the procedure below to connect to QuickBooks for the first time through the 4D Payments QuickBooks Connector:
- Open the company file you want to connect to in QuickBooks using an administrator account in single-user mode.
-
Open the 4D Payments QuickBooks Connector from the system tray and add a user on the Users tab. Enter a User and Password and select the level of access in the Data Access menu.
Note: The 4D Payments QuickBooks Connector does not use the User and Password properties to access QuickBooks; the User and Password properties authenticate the user to the 4D Payments QuickBooks Connector. Authentication to QuickBooks is handled based on the Application Name property.
- When you first connect, a dialog will appear in QuickBooks prompting you to authorize the application. After authorizing the application, you can then execute commands to QuickBooks. By default, the 4D Payments QuickBooks Connector connects to the currently open company file.
- If you want to access QuickBooks when QuickBooks is not running, save the company file information for the user. The 4D Payments QuickBooks Connector will then automatically open QuickBooks in the background with the company file for that user.
Note that if the QuickBooks UI is open, you can only connect to that company file. Additionally, note that the user permissions you run the 4D Payments QuickBooks Connector under must match the user permissions you run QuickBooks under. The 4D Payments QuickBooks Connector installation process installs the 4D Payments QuickBooks Connector as a service under the current user account.
How do I Connect to QuickBooks over SSL/TLS?
You can enable SSL/TLS on the Advanced tab.
Users
The Users tab provides an interface to add, edit, and delete users. At least one user must be added before communicating with QuickBooks.
This tab displays a list of existing users along with information about the user's configuration.
When adding or editing a user, the following options are available:
- User: Sets the username. This is required.
- Password: Sets the password for the user. This is required when using Basic authentication (default).
- Company File: Specifies the company file with which the application will communicate. By default this is the company file that is currently open in QuickBooks. A company file must be specified in order to access the company file when QuickBooks is closed.
- Authentication: Specifies the type of authentication to perform when the user connects. The 4D Payments QuickBooks Connector supports the following authentication methods:
Basic Authentication (default): Authenticates the user with a username and password. Windows Authentication: Authenticates the user as a Windows user. In this case the Password field is not applicable. When the 4D Payments QuickBooks Connector receives a connection request, it will authenticate the user to Windows using the credentials supplied in the request. - Application Name: Optionally sets the name of the application as seen by QuickBooks. Authentication to QuickBooks is handled based on the provided application name.
- Data Access: Specifies the allowed access for the user.
Full: Allows read and write access for the user. Read-only: Restricts the user to read-only operations. QuickBooks data cannot be modified.
The Test Connection button provides a quick way to verify the application can connect with QuickBooks.
When a user is added the 4D Payments QuickBooks Connector will prompt you to authorize the application with QuickBooks if necessary.
Status
The Status tab provides a log of the activity happening with the 4D Payments QuickBooks Connector. Logs can be cleared or copied by right-clicking in the Recent Activity window.
You can adjust the detail of the logs to include information useful when troubleshooting: Select the granularity in the Log Mode menu on the Advanced tab. On the Advanced tab, you can also configure the 4D Payments QuickBooks Connector to write logs to a file and select the log rotation interval.
Advanced
The Advanced tab allows granular control over the Remote Connector's server. The 4D Payments QuickBooks Connector contains an embedded Web server that runs as a Windows service and listens for HTTP requests. Each request contains the XML data to be communicated to QuickBooks as well as configuration settings specifying how the connection is to be opened. The 4D Payments QuickBooks Connector then communicates with QuickBooks via COM and returns the QuickBooks response (or an error message) in the HTTP reply.
This chapter details how to control each of these aspects of connecting to QuickBooks through the UI, command-line interface, and the registry. The following sections detail the options available on the Advanced tab.
Logging Options
- Write Logs to a Folder: Enables or disables writing log files to the specified folder in addition to writing logs to the Status tab.
- Folder: Specifies the folder where log files are written.
- Log Rotation: Determines how logs are organized on disk.
Creates one file for each day, week, or month, depending on the
following values:
Daily (default): Uses a new log file every day. Files are written with the format "yyyy_MM_dd.txt". For example, "2013_09_23.txt". Weekly: Uses a new log file every week. Files are written with the format "yyyy_ww.txt". For example, "2013_34.txt", where 34 means this is the 34th week of 2013. Monthly: Uses a new log file every month. Files are written with the format "yyyy_mm.txt". For example, "2013_09.txt". - Log Level: Sets the verbosity of the log output. In most situations, Info (the default) is sufficient. The Verbose option is helpful for debugging purposes.
- Max Log Size: Specifies the maximum size of the log file. When the maximum is reached logging automatically rolls over to a new file.
IP Options
- Port: The port on which the server listens.
- Allowed Clients: A comma-separated list of host names or IP addresses that can access the server. The wildcard character '*' is supported. If unspecified (default) any client can connect.
Enabling Persistent Connections
All communications to QuickBooks company files must first go through QuickBooks. If QuickBooks is closed, this means that for each attempt to connect to the company file, QuickBooks needs to be launched and then closed again. By default the 4D Payments QuickBooks Connector queues requests for data and performs the necessary authentication for each request. The following options can be used to override this behavior and keep the connection to the company file alive after the query finishes executing, so further requests will respond more quickly.
Warning: If a user attempts to manually open QuickBooks while a persistent connection is opened, QuickBooks will throw an error stating that the company file is already in use.
- Enable Persistent Connection: This is disabled by default: Normally your code controls when the connection to QuickBooks is opened and closed by calling the Open and Close methods; however, when this setting is enabled, the Remote Connector establishes a persistent connection to QuickBooks even when Open and Close are not used. This allows multiple applications to share the connection and simultaneously access the 4D Payments QuickBooks Connector.
- Idle Timeout: Sets the idle timeout for the persistent connection in seconds. This is only applicable to the persistent connection. If there is no activity within this time window the 4D Payments QuickBooks Connector closes the connection.
Testing the Connection
In addition to testing the connection on a per-user basis from the Users tab the "Test Connection" button on the Advanced tab provides a simple way to verify the application can communicate with QuickBooks. To use this functionality QuickBooks must be open.
Enabling TLS/SSL
Enable TLS (1.x) to encrypt communication between your application and the 4D Payments QuickBooks Connector. TLS/SSL uses digital certificates to protect the confidentiality, integrity, and authenticity of your data: You can generate these certificates on the Advanced tab. Once you have enabled TLS, you will need to send your public key certificate to any connecting applications.The following options are used to configure TLS/SSL:
- Enable TLS: Enables or disables TLS (1.x) communication.
- Select Certificate: Loads an existing certificate.
- Generate Certificate: Creates a new certificate.
Command-Line Interface
In addition to the UI, the 4D Payments QuickBooks Connector has a command-line interface that makes it easy to deploy on machines where a user is not always logged in, for example, a Web server. To facilitate deployment to these environments, the 4D Payments QuickBooks Connector contains two executables:
| 4DPaymentsQBConnector.exe | Provides the user interface and allows configuration of the application. |
| 4DPaymentsQBConnectorService.exe | Processes requests and performs all interaction with QuickBooks. |
The syntax for managing the 4D Payments QuickBooks Connector Windows service from the command line is as follows:
RemoteConnectorService.exe /Service <Command>
The following commands are available:
| Install | Installs the Windows service. |
| Delete | Deletes the Windows service. |
| Start | Starts the Windows service. |
| Stop | Stops the Windows service. |
| State | Reports the current state of the Windows service (started or stopped). |
| Auto | Changes the Windows service startup type to Automatic. |
| Manual | Changes the Windows service startup type to Manual. |
| Disabled | Changes the Windows service startup type to Disabled. |
Registry Keys
Configuration options for 4D Payments QuickBooks Connector are stored in the Windows registry in HKEY_LOCAL_MACHINE\SOFTWARE\DPayments\4D Payments Quickbooks Connector. This registry location holds setting that are available for 4D Payments QuickBooks Connector globally. Additional registry keys are available for settings related directly to specific Users.
The tree structure of these registry keys is described below:
- HKEY_LOCAL_MACHINE\SOFTWARE\DPayments\4D Payments Quickbooks Connector
| Name | Type | Description |
| LocalAuth | String | A randomly generated administrator password that is used for authorization between the user interface and the Windows service. This is only used when authorizing a user configured for Windows authentication to QuickBooks from the user interface. This may be removed or changed if desired. |
| AllowedClients | String | A comma-separated list of host names or IP addresses that can access the server. The wildcard character '*' is supported (default). If unspecified any client can connect. |
| AuthFlags | DWORD | Specifies the versions of QuickBooks to which the application can connect. The value is a binary OR of the values below, represented in hex. The default value is "0xF" (all editions are supported).
|
| CloseAndRetryConnect | DWORD | Specifies whether connection retry logic is enabled. When set to 1 (True), if an error is encountered while opening a connection to QuickBooks the application will attempt to stop the QuickBooks process and reconnect. The CloseAndRetryTimeout, CloseAndRetryCount, and CloseAndRetryErrorList settings are applicable when this setting is 1 (True). |
| CloseAndRetryTimeout | DWORD | Sets the time in seconds that the application will wait for the connection to QuickBooks to be established. The default value is 30 (seconds). If the timeout is reached, the QuickBooks process will be closed and the connection will be retried. Note that this setting should be adjusted with caution. If the timeout is set too low the QuickBooks process may not have time to open normally before reaching the timeout. This setting is only applicable when CloseAndRetryConnect is True. |
| CloseAndRetryCount | DWORD | Sets the number of times to retry the connection. If an error is encountered while opening a connection to QuickBooks, the application will stop the QuickBooks process and retry until this limit is reached. The default value is 3. This setting is only applicable when CloseAndRetryConnect is True. |
| CloseAndRetryErrorList | String | Specifies a comma-separated list of QuickBooks error codes on which to retry a connection. If QuickBooks returns an error code listed in this property, the QuickBooks process will be stopped and the connection will be retried. If the error is not in this list the application will return the error as normal. The default value is "0x80040402,0x80040408". Specify the value "*" to indicate all errors. This setting is only applicable when CloseAndRetryConnect is True. |
| QBInstanceFile | String |
Specifies the full path to the QBINSTANCEFINDER file in the QuickBooks installation. For instance: "C:\ProgramData\Intuit\QuickBooks\QBINSTANCEFINDER17.INI". This setting is only applicable when CloseAndRetryConnect is set to True. If the connection retry logic stops the QuickBooks process the specified QBINSTANCEFINDER file will be cleared of any previous entries. QuickBooks uses the QBINSTANCEFINDER file to keep track of open instances, however, in some situations it may not be properly reset after stopping the process. When specified this setting allows the application to properly reset the file after stopping the process. |
| LocalHost | String | Sets the host name or user-assigned IP interface through which connections are initiated or accepted. In most cases this does not need to be set, as the application will use the default interface on the machine. If you have multiple interfaces, you can specify the interface to use here. For instance, "192.168.1.102". |
| LogEnabled | DWORD | Enables or disables logging to a file. Logs are always written to the console. The default is 0 (False). |
| LogDir | String | Sets the path to a folder on disk where log files will be written. This is only applicable if LogEnabled is set to True. |
| LogFormat | DWORD | Sets how often new log files are created. Possible values are the following:
|
| LogLevel | DWORD | Sets the logging level. Possible values are the following:
|
| LogPort | DWORD | Sets a separate port for logging. Log messages are sent over UDP from 4DPaymentsQBConnectorService.exe to the UI. By default this is the same value as the port defined in the Port option. Set this option to avoid using the same port as another UDP service running on the same machine. |
| MaxLogSize | DWORD | Specifies the maximum size of the log file. When the maximum is reached logging automatically rolls over to a new file. |
| Port | DWORD | Sets the port where the server listens for incoming connections. The default value is 8167. |
| PersistentEnabled | DWORD | Enables or disables persistent connections to QuickBooks. The default is 0 (False), meaning that your code controls when the connection to QuickBooks is opened and closed by calling the Open and Close methods. However, when this setting is enabled, a persistent connection to QuickBooks is established by the 4D Payments QuickBooks Connector even when Open and Close are not used. This is helpful in situations when multiple applications may be simultaneously accessing the 4D Payments QuickBooks Connector, because it allows them to share the connection. |
| PersistentIdleTimeout | DWORD | Sets the idle timeout for the persistent connection in seconds. If there is no activity within this time window, the connection to QuickBooks will be closed. This is only applicable when PersistentEnabled is True. |
| PromptForRegPermissions | DWORD | Specifies whether to prompt to modify registry permissions when access is not allowed. This is only applicable when saving settings from the UI. |
| RunAsService | DWORD | Run the application as a service or with the standard run-time permissions. The default value is 1 (True). |
| SSLCertPassword | String | Sets the password of the SSL certificate. |
| SSLCertStore | String | Sets the location of the SSL certificate. This may be a path to a file or the name of a Windows certificate store: "MY", "ROOT", "CA", or "SPC". |
| SSLCertSubject | String | Sets the subject of the SSL certificate. |
| SSLCertType | String | Sets the type of SSL certificate to use. A certificate must be specified when SSL is enabled. The PFX option signifies a .pfx file on disk. The User option signifies the user's Windows certificate store. The Machine option signifies the Windows certificate store of the machine. |
| SSLEnabled | DWORD | Sets whether TLS/SSL connections are allowed. The default value is 0 (False). Enabling TLS/SSL disables plaintext connections. |
| Timeout | DWORD | Sets the operational timeout for connected clients. The default value is 60. |
| UseInteractiveLogon | DWORD | Sets whether interactive or network logon will authorize users when AuthMode is set to 1 (Windows). In most cases this does not need to be set. This should be set to 1 (True) if your domain controller is Samba. The default value is 0 (False). |
User Registry Keys
Each user will have a separate subkey with user-specific settings. For example: HKEY_LOCAL_MACHINE\SOFTWARE\DPayments\4D Payments Quickbooks Connector\Users\User1.
| Name | Type | Description | ||||||
| AppName | String | Sets the name of the application that will be used to provide authentication to QuickBooks when a connection is made. If this value is not set, the 4D Payments QuickBooks Connector uses the value provided by the client. | ||||||
| AuthMode | DWORD | Sets the type of authentication to perform when the user connects. From the client side the process of connecting is exactly the same no matter which option you choose. Possible values are the following:
| ||||||
| Authorized | DWORD | Specifies whether the AppName has been authorized for the CompanyFile. If 1 (True) the AppName has been authorized with the CompanyFile. This is an indicator used by the application when changing settings in the UI. | ||||||
| CompanyFile | String | Sets the path to a QuickBooks company file (.qbw). If this is not set, the currently open company file is used. When QuickBooks is not running, this option must be set. | ||||||
| ConnectionMode | String | Sets the connection mode for the user. The default is DontCare. In most cases you do not need to set this value. If this is not set, the application will connect in whatever mode QuickBooks is already open in. Possible values are the following:
| ||||||
| Password | String | Sets the password of the user. This is required when AuthMode is set to 0 (Basic Authentication). The 4D Payments QuickBooks Connector application will always store the SHA-256 hash of the password for security. However, this may also be manually set to a plaintext password to allow backward compatibility. | ||||||
| ReadOnly | DWORD | Specifies whether the user has read-only (1) or full access (0). |
Wire Protocol
This section will provide you with an understanding of how to communicate with the 4D Payments QuickBooks Connector over HTTP, including which headers are required and what their functions are, how to format the query body, and what to expect in response.
HTTP Methods
All communication with the 4D Payments QuickBooks Connector should take place by issuing a POST request to the path /.
HTTP Errors
The 4D Payments QuickBooks Connector can respond with several possible HTTP error codes, depending upon the nature of the error. These are the most common, although others can occasionally occur.
| 404: Not Found | The request is using an incorrect path. All requests must be targeted at the server root. |
| 401: Authorization Required | The request is attempting to communicate with the 4D Payments QuickBooks Connector without providing an Authorization header, or with an Authorization header that does not match any user in the Users tab. |
| 405: Method Not Allowed | The request is using an incorrect method. All requests must be made using the POST method. |
| 411: Length Required | The request did not provide a Content-Length header. All requests must provide a Content-Length header, even if it is 0. |
| 517: Server Error | The 4D Payments QuickBooks Connector understands the request, but QuickBooks failed to process it. One common cause is that the QBXML sent to 4D Payments QuickBooks Connector is malformed, but there are several other possibilities. The response body contains a more detailed description of the error that the Remote Server collected from QuickBooks. |
Mandatory Request Headers
The following headers are required when connecting to the 4D Payments QuickBooks Connector - not providing these will cause the Remote Connector to reject your request.
Content-Length
The Content-Length must be the length of the request body in bytes. It must always be present, even if the request body is empty.
Authorization
You will have to provide credentials as HTTP Basic authentication tokens when communicating with the 4D Payments QuickBooks Connector. When authenticating using AuthMode 0 (Basic Authentication), this header should contain the username and password of a user configured in the Users tab. When authenticating using AuthMode 1 (Windows Authentication), this header should contain the username and password of a Windows user registered in the Users tab.
X-AcctSyncInteractionType
The X-AcccSyncInteractionType header indicates what kind of processing the 4D Payments QuickBooks Connector will do on the data it receives. There are several different values this header can take on, and each value will instruct the 4D Payments QuickBooks Connector to perform different operations.
| X-AcctSyncInteractionType: 0 |
Setting the interaction type to 0 directs the 4D Payments QuickBooks Connector to connect to QuickBooks and execute the QBXML query given in the request body. Afterword, the QBXML response will be provided by the 4D Payments QuickBooks Connector in the response body. There are several different kinds of QBXML queries that the 4D Payments QuickBooks Connector will accept when in this interaction type. Please refer to the QuickBooks SDK documentation for details and examples. |
| X-AcctSyncInteractionType: 1 |
Setting the interaction type to 1 will cause the 4D Payments QuickBooks Connector to respond with the path to the company file that is currently open in QuickBooks. For example, this kind of request might cause the Remote Connector to return an HTTP 200 with a body containing C:\Users\Public\Documents\company.qbw followed by a CRLF newline. |
| X-AcctSyncInteractionType: 101 |
Setting the interaction type to 101 will cause the 4D Payments QuickBooks Connector to open up a persistent connection to the QuickBooks company file. This should make repeated queries against the same company file faster because QuickBooks will not need to open the company file for each request. However, persistent connections are not required, and you can execute QBXML requests against the 4D Payments QuickBooks Connector without opening a persistent connection. There is no content in the response of this query; if this request succeeds, the 4D Payments QuickBooks Connector will return an HTTP 200 with a body containing a single CRLF newline. Note that this request will succeed, but have no effect, if the "Enable Persistent Connections" option is enabled in the Advanced tab. When that option is enabled, all requests will occur over a persistent connection, even if one is not explicitly requested via this header. Finally, the persistent connection opened by this request will eventually time out if no activity occurs on it. The length of this timeout is defined by the "Idle Timeout" option under the Advanced tab. |
| X-AcctSyncInteractionType: 102 |
Setting the interaction type to 102 will cause the 4D Payments QuickBooks Connector to close a persistent connection to the QuickBooks company file. This should be done after you are finished executing queries over a persistent connection opened by a previous 101 request. There is no content in the response of this query; the 4D Payments QuickBooks Connector will send an HTTP 200 response with a body containing single CRLF newline if this request succeeds. Note that this request will succeed, but the persistent connection will remain open, if the "Enable Persistent Connections" option is enabled in the Advanced tab. In addition, this request will succeed, but have no effect, if no persistent connection is currently open (either because one was never opened, or because one that used to be open timed out). |
| X-AcctSyncInteractionType: 103 |
Setting the interaction type to 103 will cause the 4D Payments QuickBooks Connector to query QuickBooks find out the most recent version of QBXML that it supports, and then respond with that version number. For example, on a recent version of QuickBooks, this request might return an HTTP 200 with a body containing the value 13.0 followed by a CRLF newline. |
| X-AcctSyncInteractionType: 104 |
Setting the interaction type to 104 will cause the 4D Payments QuickBooks Connector to query QuickBooks and find out all of the version of QBXML that it supports, and then return them, one per line. For example, on a recent version of QuickBooks , this request might return an HTTP 200 with a body containing the values below followed by a CRLF newline: 1.0 1.1 2.0 2.1 3.0 4.0 4.1 5.0 6.0 7.0 8.0 9.0 10.0 11.0 12.0 13.0
|
| X-AcctSyncInteractionType: 105 |
Setting the interaction type to 105 will cause the 4D Payments QuickBooks Connector to connect to QuickBooks and check that the user is authorized to access the company file. On a success, this will return an HTTP 200 containing the text 0 followed by a CRLF newline. On a failure, this will return an HTTP 200 containing the text 1 followed by a CRLF newline. |
| X-AcctSyncInteractionType: 106 |
Setting the interaction type to 106 will cause the 4D Payments QuickBooks Connector to connect to QuickBooks and check that the company file is accessible. On a success, this will return an HTTP 200 containing the text 0 followed by a CRLF newline. On a failure, this will return an HTTP 200 containing the text 1 followed by a CRLF newline. |
Optional Request Headers
X-QBPOS
This header can take on the values True or False, and defaults to False. When connecting to a 4D Payments QuickBooks Connector that is connected to the point-of-sale edition of QuickBooks, this header must be set to True. When connecting to a 4D Payments QuickBooks Connector that is connected to the desktop edition of QuickBooks, this header must be set to False, or omitted.
X-AcctQBPOSPractice
This header can take on the values True or False. When X-QBPOS is True, this will direct QuickBooks to enter practice mode, which allows your application to make changes that will not be stored permanently. See the QuickBooks point-of-sale documentation for more details on practice mode.
When X-QBPOS is False, the 4D Payments QuickBooks Connector will ignore this header, and it can be omitted.
X-QBPOSVersion
When X-QBPOS is True, this header should be set to the version number of point-of-sale edition of QuickBooks that you are connecting to.
When X-QBPOS is False, the 4D Payments QuickBooks Connector will ignore this header, and it can be omitted.
X-DelayAfterOpen
This header takes a positive integer representing milliseconds and pauses the request after opening the connection to QuickBooks for that period of time. This header is normally not required, but it can help if QuickBooks is processing requests slowly and causing the 4D Payments QuickBooks Connector to respond with errors.