Table of Contents

FAQ - Hosted API

Please note Reckon Accounts Hosted uses the same QBXML schema as Reckon Accounts Desktop (QBXML6.1), so please refer to the Accounts Desktop FAQ for any information regarding the QBXML schema.

Q. Are you able to provide an example of the API call required for Reckon Accounts Hosted, preferably in Curl command format?

curl -X POST 
-H “Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImlhWFVyeXpHT2ZNalBjQnN2UUpRRzR1X1J0MCIsImtpZC..._khxAHG-Gw” 
-H “Content-Type: application/x-www-form-urlencoded” 
-H “Cache-Control: no-cache” 
-H “Postman-Token: c27a0270-55fa-0485-45fa-6b96b409d9b2” 
-d ‘{"FileName":“Q:\\test.QBW”,“Operation”:“<?xml version=\”1.0\“?><?qbxml version=\”6.1\“?><QBXML>”continueOnError\“><CompanyQueryRq /></QBXMLMsgsRq></QBXML>”,
“CountryVersion”:“2019.R2.AU”,
“UserName:”Admin",
“Password”:"password"}’
“https://api.reckon.com/rah/v2/?subscription-key=<<KEY>>”


Q. When I send a call I get this message of RequestId. What does this mean, and how do I check the result of my API request?

{
     "RequestId": "9999da23-b388-43d6-9832-59bcebeedda0",
     "Data": null,
     "Success": true,
     "RetryLater": true,
     "Message": "Request has not been completed yet. Please check back in couple of minutes"
} 

This is normal behaviour with the RAH API when the request takes longer than approximately 2.5 minutes (180 seconds) to process (i.e. a  the sent request is asking for a significant amount of data or submitting a significant amount of data). The API returns a GUID of the request message as RequestId (Check back later response) due to pending request timeout. 

To get the request results, an additional request is required submitting the RequestId that was returned with the 'Check back..' response.

This secondary request is:  https://api.reckon.com/RAH/v2/{retrieveid} where 'retrieveid' is the RequestId returned in the initial response (for example: 7c566c0-8760-415b-98908-4366173c2ef1).

If the request is still not finished when a secondary request is sent, another 'Check back..' response will be received and another secondary request specifying RequestId will need to be sent. This continues until the response data for the initial request is returned. Check out the Postman collection's "Retrieve RequestId" request to find out how the payload looks like and test out your own RequestId. 


Q. I have received the following response when making an API call after a long response time.  I receive the same response when using the GUID returned in my original API call but this time it’s returned immediately.

 {
    "RequestId": "9b0940f1-90a8-49e6-8243-f6c2c2791f05",
    "Data": null,
    "Success": true,
    "RetryLater": true,
    "Message": "Request has not been completed yet. Please check back in couple of minutes"
}

Please ensure you are using the country version 2019.R2.AU or 2019.R1.NZ (see docs for correct one). 


Q. Your token endpoints require the data to be in the body. I would like to send them as query parameters as other OAuth2 implementations I have worked on accept the parameters as query parameters. Can you explain why you have taken this approach?

It is acceptable within the industry to use either approach. The Reckon API team have taken the view that it makes sense for a POST to occur within the body and not via a full URL request as the call should be hidden from the user. That is, they do not have to interact with it at all. When you utilise a refresh token that should be seamless.

A POST allows this, however, if you execute as a GET, it may be exposed to the browser in the network console and that can expose your BASE64 key. If you do it as a post it can all be handled server side. 


Q. It is taking me a long time to retrieve a list from Reckon Accounts Hosted with this call (eg for customer list). What am I doing wrong?

{
    "FileName":"Q:\\My Company File.QBW",
    "Operation":"<?xml version=\"1.0\"?><?qbxml version=\"6.1\"?><QBXML><QBXMLMsgsRq onError=\"continueOnError\">
    <CustomerQueryRq  requestID='1'>
    <OwnerID >0</OwnerID>
    </CustomerQueryRq >
    </QBXMLMsgsRq></QBXML>",
    "UserName":"myApp",
    "Password":"password",
    "CountryVersion":"2018.R2.AU"
}

This call is fine if the customer list is very small, however, Reckon Accounts Hosted can hold up to 1,000,000 records in theory, so you do not want to pull down the entire list at once. Nor should you be syncing the entire list to your application (other than the first sync / connection).

 For example, try to reduce your payload response with a filtered call: This will gather all the customers that begin with A, then change to B, C, etc

<?xml version="1.0"?><?qbxml version="6.1"?><QBXML><QBXMLMsgsRq onError="continueOnError">
 <CustomerQueryRq>
 <NameFilter><MatchCriterion>StartsWith</MatchCriterion><Name>a</Name></NameFilter>
 </CustomerQueryRq>
 </QBXMLMsgsRq></QBXML>

Once you have completed the initial sync of all customers, you can use this style of command to retrieve only those that have been modified since a specific date eg.  (which is suggested to be the last time you successfully synced).

 <?xml version="1.0"?><?qbxml version="6.1"?><QBXML><QBXMLMsgsRq onError="continueOnError">
 <CustomerQueryRq>
 <FromModifiedDate>2017-01-01</FromModifiedDate><ToModifiedDate>2017-02-20</ToModifiedDate>
 </CustomerQueryRq>
 </QBXMLMsgsRq></QBXML>


Q. I am using http://localhost as my callback URL writing a desktop connector in .NET for Reckon Accounts Hosted. After I connect my app the returning token is not displayed in the embedded web browser and I cannot see the returning URL and token code. What am I doing wrong?

Unfortunately, embedded browsers (WebBrowser contol) in Visual Studio cannot show the URL bar. However, you can get around this by creating a textbox and parsing the URL location to a string, and reading that string into the newly created textbox. This article and this article may be helpful?


Q. I am coding in C# and am getting a 401 error: Unauthorized error when requesting headers. Here is my code - any ideas? (grant type = Authorization Code)

// Request headers

client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", this.cSubKey);
client.DefaultRequestHeaders.Add("Authorization", this.cToken);

Change: client.DefaultRequestHeaders.Add(“Authorization”, this.cToken);

to this: client.DefaultRequestHeaders.Add(“Authorization”, "Bearer " + this.cToken);


Q. How do I find the correct file path of the Company (*.QBW file)?

  1. Login to Reckon Accounts Hosted application
  2. Open the company file
  3. Press Ctrl and number 1 at the same time on your keyboard and Product Information window will show up
  4. You will find the file location under File Information section. Your user should be able to copy it and then paste it in your application
    1. File is saved under Q Drive:
      "FileLocation": "Q:\{filename}"
      Example: "FileLocation": "Q:\My Company file.QBW"
    2. File is under Upload folder of Q Drive:
      "FileLocation": "Q:\Upload{filename}"
      Example: "FileLocation": "Q:\Upload\My Company file.QBW"
    3. File is under shared folder of Q Drive:
      "FileLocation": "\\{SharedFolderLocation}\{FolderName}{filename}"
      Example: "\Rah-fss-11-ap2a123-456789-MYCOMPANYFILEMy Company File.QBW" 
On 16/04/2019, we released an updated FileLocation object which can now handle full path of a shared folder, as well as the truncated FileLocation. 

Q. I’m receiving the following error trying to authorise my app through the Reckon Identity Server: "Authorization failed in Provisioning service. User NOT Authorized for file. User not found.".

When authorising an application to access Accounts Hosted you will need to login to the Reckon Identity Server with your “User ID” as opposed to your “User Name”.  Eg: User ID: 1234567-1,  not User Name: JSmith55.  


Q. I’m trying to make a refresh token request call, but it is not working.  My original token request call worked, and I’m using the refresh token I was provided in the response.

When making a refresh token request call you must include the same headers you use when making your original token request call.  The headers are as follows:

  • Content-Type = application/x-www-form-urlencoded
  • Authorization: Basic <<CLIENTID:CLIENTSECRET ENCODED IN BASE64>>

Q. I’m trying to send an invoice to Reckon Accounts with Gross Amounts by using <IsTaxIncluded>true</IsTaxIncluded>, however, the amounts are still recognised as Net amounts, so the tax is being added on top of the gross amount?

All amounts should be sent as Net amounts.  <IsTaxIncluded>true</IsTaxIncluded> will simply display the transaction in the Reckon Accounts UI as Gross, it doesn’t make the amounts you send to be Gross.   The amounts you send in your QBXML should always be entered as Net amounts. This is a limitation of the Intuit SDK.  


Q. We are getting this error connecting to a Reckon Accounts QBW file that is a shared file. Error: Please ensure the file exists and you have the correct file path set. The file path looks correct, so why are we getting this error?

Although the file path may look correct, there are often cases where the user has not shared the QBW file correctly. For example, they have 'pasted' a copy of the QBW file into the folder. This will cause the API call to fail as the API cannot find the path (even though it looks as though it exists).

As part of the troubleshooting process, the user should 're-share' their QBW file. This corrects the issue in the majority of cases.

  1. Make a 'verified' backup copy of the file (save to local PC as well for safety)
  2. Cut the file from the shared folder
  3. Paste the file in your Q drive (if you have to rename the file, do it here but not after re-sharing)
  4. Share the file again with the appropriate users
  5. Once completed, email the Reckon API Support team the UserID that you used to share it and we’ll remove the old shared folder


Q. Can you summarise the user steps for connecting an app to a Reckon Accounts Hosted file, and perhaps include the corresponding API key actions?

Only for connections prior to the June 30 2018 update to v2.2

User

API

Log in to your Accounts Hosted company (QBW file) as Admin user (single user mode).

 

Create a new user (full access rights) called API.

 

Switch to multi-user mode and log out.

 

Authorise the API in the company file (QBW file).

Include the company file Admin user name and password in the call. 

When prompted, enter your Hosted UserID and password into the Reckon Identity Server pop-up. 

You must use the user format 123456-1 ** if you can't remember this, go to your Accounts Hosted control panel web page. 

** Generally a developer will retrieve the access tokens with the above call.

Log in to the company file as Admin user, and switch to single user mode.

 

Under Edit > Preferences > Integrated Applications > Company Preferences select the ReconAccountsHostedRequestProcessor app and click Properties. Assign the user API to the processor you created earlier.

 

Switch to multi-user mode.

 

Sync your file to accept data from / send data to the integrated application.

Send all sync calls with NULL values for the company file user name and password. 

** See our authentication page for full details


Q. I have a corrupted Integrated Application in Reckon Accounts Hosted. How do I fix this?
(Only for connections prior to the June 30 2018 update to v2.2)

Open the company file as Admin (single user mode) and go to Edit > Preferences > Integrated Applications > Company Preferences and REMOVE any instances of the ReconAccountsHostedRequestProcessor.

Make a note of your EXACT file location (including folder if applicable) by going to File > Audit Company File

Close Reckon Accounts by using File > Close Company / log off

Next select the Download icon on the floating toolbar

 

Navigate to the myCompanyFile.QBW file location, and find the lgb file called myCompanyFile.lgb and delete this file. ** You must delete the same lgb file of the same name that is in the location of your company file. 

 

The Accounts Hosted environment is single-click and right-click is disengaged, therefore simply hover over the file to select it prior to clicking DELETE. If you click on the file it will download. 

Re-authorise the 3rd party app and the lgb file (and the listing under Integrated Applications) will re-create. 


Q. How does Iterator work with Reckon Accounts Hosted API?

Hosted API now supports iterators. Iterator calls need to be made within the same API Session.  So subsequent iterator calls must be made within seconds after receiving the last iterator response.  Iterators are closed and associated data lost when the API Sessions closes. The iterator attribute provided with most query types also allows you to break down query results in smaller and more manageable chunks of data. An iterator results in responses that contain only the specified number of objects.

Click here to view the supported endpoints for iterators. You can learn more about iterators from the SDK documentation (SDK-ProgrammersGuide-v13.pdf > Page 77), available from the SDK link that was provided to you when you signed up. If you cannot locate it, please let us know by emailing apisupport@reckon.com.

RAH iterators work IF the iterator ID is used whilst the connection is open (ie request received within 10 seconds of Iterator open request AND max of 10 requests in total). The RAH API db has a setting to permit a max of 10 sequential requests for an open connection before the connection is force reset which will by default stop the open iterator.

Example payload

<?xml version="1.0" ?>
 <?qbxml version="5.0" ?>
 <QBXML>
 <QBXMLMsgsRq onError="stopOnError">
 <CustomerQueryRq requestID="5001" iterator="Start">
 <MaxReturned>10</MaxReturned>
 <IncludeRetElement>ListID</IncludeRetElement>
 </CustomerQueryRq>
 </QBXMLMsgsRq>
 </QBXML>

Continuing the Iteration

To continue a particular iteration, you simply issue the same query request again, but this time with the iterator value now set to Continue, and the IteratorID field set to the IteratorID value returned from the first query iteration. Remember that the iterator DOES NOT remember all aspects of your query (just the filters!). Accordingly, if you use other fields in the query, such as IncludeRetElement, then you have to repeat those in each continuation of the iterated query.

A qbXML example is shown below:

<?xml version="1.0" ?>
<?qbxml version="5.0" ?>
<QBXML>
<QBXMLMsgsRq onError="stopOnError">
<CustomerQueryRq requestID="5001" iterator="Continue"
iteratorID="{D7355385-A17B-4f5d-B34D-F34C79C3E6FC}">
<MaxReturned>10</MaxReturned>
<IncludeRetElement>ListID</IncludeRetElement> </

CustomerQueryRq>
</QBXMLMsgsRq>

</QBXML>
Stopping the Iteration

At any point during an iteration, you can stop the iteration and destroy the iterator (freeing up memory) by issuing the query request with the iterator attribute set to “Stop” and the iteratorID set to the proper iterator ID.


Q. Why do I get the error "Error connecting to Reckon Accounts. E03: Failed to access the Reckon Accounts company file using the supplied credentials. Please verify the user exists and the username and password match those supplied."?

You will get this error for one of the below reasons:

  1. The username and password details are incorrect or
  2. The user's details provided has been deleted in the Accounts Hosted application or
  3. The username value's length is more than 21 characters. The maximum characters allowed of the username object is 21 characters. Please update the username value in the Accounts Hosted application and then update in the third-party application for successful integration.

Q. How often should Hosted API synchronisation occur?

Thousands of requests are processed by the Hosted API daily, these requests can take longer to process than more modern APIs. Due to this, while we currently don't rate limit integrations, to ensure the Hosted API platform continues to run efficiently, we recommend the following:

  • Synchronising every 30 minutes
  • Bulk synchronisation Daily

Developers who implement integrations that routinely exceed these recommendations without consultation with Reckon risk having their application API requests limited.

How did we do?

Reckon Accounts Hosted Postman Collection

Related Articles

Hosted API - 16 Apr 2019
Authentication - Hosted API
Hosted API Troubleshooting Articles
Powered by HelpDocs (opens in a new tab)

Powered by HelpDocs (opens in a new tab)