API in action
Live example of the API service for buildMGR linking to Reckon Accounts Hosted. See how Accredited Partners enhance business solutions using API technologies. Reckon accredited partners enhance business solutions If you were not expecting to see this, please contact: buildMGR systems administrator: tech@buildmgr.com.au ** You will need a RAH user login/password, and a copy of the test company on your site for this test.Step 1: Authenticate against the Accounting System
(1) CLICK HERE to try a live request with the Reckon API.
This test uses the pre-allocated {clientid} for the APP: buildMGR. A request screen will be prompted by the [Reckon Identity Server] for a set of USER-ID credentials {tenantid} and {tenantidpassword} password to allow RAH access. In a live operation, these would be your own credentials for reaching an API registered [Company File] stored at the RAH data centre. The {tenantidpassword} password is never saved. The result of the above request, will have arrived back at this {Callback URL} where {authorisation:bearer TOKENS} can be observed in the header.Step 2: Observe the fetched Access_Token
(2) After step 1 is performed, the {authorisation:bearer TOKENS} will appear below{id_token}
{access_token} without variable
{token_type}
{expires_in}
{scope}
{state}
{session_state}
Step 3: Check the availability of the API server
As this is only a quick test to establish that there is a valid connection to the server, expect this reply: This XML file does not appear to have any style information associated with it. The document tree is shown below. xmlns="http://schemas.microsoft.com/2003/10/Serialization OK < / string> If your subscription key is invalid, you will end up with an error like this: StatusCode: 401 Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.Step 4: Extract Accounting Data (POST method)
NOTE: During development/testing, be sure to use the 2nd subscription key.Let's gather the BODY DATA for the POST:
Enter BODY by copying and pasting the BLUE example on the right a) select/copy the body lines, INCLUDING the curly brackets b) the tenantID and c) Subscription-Key Observe the DATA that arrives, using Firefox -- F12 -- Console -- AllThe results of the POST will be like this:
Variables defined in 'PHP snippet 2' like "snipglobal"
the date now is (UTC) : November 23rd, 2024 08:07:50 AM Snippet output follows: ..... fetching Accounts Data ....... doubleslash is: \\ .... snipbody will contain what was submitted...Values extracted from XML results using 'PHP snippet 3' like "Companyname"
Note:
If you haven't performed step 1 with a clear cache and with valid credentials, and subsequently try this step 4, you'll receive an error as follows:{ "statusCode": 404, "message": "Resource not found" }
Debugging tools
refer: Debian apache2 access.log at test site, and F12 Console debug tools of browser. Particularly consider the F12: Network and Headers interactive logging. To immediately clear cache before trying step 1, consider "CTL" + "SHIFT" + "DEL".Here is the overall NETWORK architecture involved
A combination of MS-Azure, Amazon Web Services, Digital Ocean data centres (VPS) combined with PHP5, Javascript (JS), JQuery, WordPress html5 and suiteCRM Applications.
Contact us for any technical consulting assistance
Gary Pope B.Bus(Acc)
m:0408994799 e:gaz@alchester.com.auAn Accredited Partner- Consultant (VIC. Aust)
"Working with Accountants/Bookkeepers PPs/APs, as an independent IT Professional and retired FCPA Accountant"
"Reckon Partners enhance business solutions"A technical look at how API v1 "Implicit" method integration works
A behind the scenes outline of the setup and development tools for API.
* USER access to APP: buildMGR and Vendor Product: ie: Reckon Accounts is achieved by using the user's {tenantid} username and {tenantidpassword} password to reach the respective {APP database} and {Product database}. Note: that {tenantidpassword} is never saved, but used to access the {Product database} specific to each and every unique end-user's {tenantid} username.
(1) One-time setup by API Provider.
* Vendor API Provider (ie: Reckon) initially sets up the API facility on their dedicated Vendor API Portal providing a "8-4-4-4-12" 36 character hyphenated hexadecimal {clientId} and pair of {Ocp-Apim-Subscription-Key} related 32-character hexadecimal subscriptions for primary API production or secondary development.
A secure (https) {callbackURL} redirection URL is established for the interchange of tokens for use in all subsequent API calls from the APP to the Product.
Note: Once setup, the use of {clientid} is used for all API calls to fetch tokens for a particular USER, for the APP developer's product.
* APP Developers (ie: buildMGR) enjoy API testing tools at that Portal.
As a USER of the Reckon Accounts HOSTED service, a suitably REGISTERED COMPANY FILE (xxxx.QBW) that is tagged for access by the API, is needed. For development purposes, a pre-registered company file called: "Cougar Enterprises Pty Ltd.QBW" is available for uploading into the RAH storage area in logical drive Q:. This examples throughout this explanatory page here, uses that example file.
Fetch the two example files and UPLOAD them to your RAH folder into drive Q:
Download the QBW file from here: see: http:/www.buildmgr.com.au/download/Cougar Enterprises Hosted.QBW
and the pre-registered LGB file here: http:/www.buildmgr.com.au/download/Cougar Enterprises Hosted.lgb
Under discussion: (End-Users at multiple sites)
Reckon Accounts HOSTED users all reside at a single DATA CENTRE, but separated by {tenantid} and data separation. But Integration Partners may not have that structure. For instance, buildMGR can be deployed at private cloud VPS sites, or within their own premises. This raises the question of multiple concurrent {clientid] TOKENS and related {callbackURL} relationships. Be mindful that multiple will be transacting across the API CONCURRENTLY. Whilst there is only ONE APP: buildMGR and therefore only ONE ClientID, there are MULTIPLE END-USERS dealing with their discrete instance of the buildMGR APP / API / Reckon Company File. This may need separate API setup processes to recognise each END-USER by way of a distinct {clientid}. At the time of preparing this documentation (March - May 2016), no definitive answer has been provided on this point. A case by case scenario is expected.
The API requires that the DEMO files are running on the LATEST version of RAH. This project was documented when RAH2015R2 was the version in production. Each year around June 30th, a new financial year's version is released. so be sure to UPGRADE the COUGAR file to the latest version. (IE: from June 2016, the version needed is RAH2016R2. Otherwise error 400 will occur during API processing)
(2) Login to the API Portal.
(2) Reckon API Portal (Developer testing area)
sign-in with Reckon API Portal credentials: {Portal-username} / {Portal-password}.
(3) Use Portal to retrieve TOKENS.
(From the previous step, select MENU: APIS, and then select RAH product.)
(3) Reckon RAH [token retrieval testing] via Portal at MS-Azure
GET/v2{retrieveid} [TRY IT]. Retrieval of vital {Authorization:Bearer} TOKENS with embedded {id-token} and {access-token} is achieved by use of the [Implicit] Server Identity method by submitting:
{retrieveid} using the {Portal-username} above
{Ocp-Apim-Subscription-Key} using the {Portal-password} above
Authorization:Bearer
{Identity Server} selecting the [Implicit] method
Then selecting [Implicit], an additional login window appears, where the USER's {tenantid} username {tenantidpassword} credentials are sought from an [Identity Server].
{Subscription Key} assumes the usage of the primary API production subscription that has been provided for previously.
DO NOT click on SEND.
Just select the desired {subscription key} and then go to the next step (4).
During development and testing, be sure to pick the 2nd key!
The above yields the pair of TOKENS needed.
Note: these "portal development" tokens cannot be used for APP production, they are simply examples for testing. In live production, from the APP, the combination of {clientid} and {CallbackURL} are used.
ABS reference: A test that can perform the same steps. (//absvenom/usr/local/bin/)
ie: #curl -v -X GET "https://identity.reckon.com/connect/authorize?client_id={clientid}&response_type=id_token%20token&scope=openid%20read%20write&redirect_uri={CallbackURL}&state=random_state&nonce=random_nonce"
(4) Extract DATA from the Database using TOKENS.
POST Submit request [Implicit flow method] The method described here.
Note: plans are afoot to move to v2 which is the Response Flow method
(4) Reckon RAH [APP API testing] via Portal at MS-Azure
This testing area for QBXML requests allows the submitting of a URL request combining:
{tenantid} The username to access the Vendor Product login
{Content-Type} stipulates application/json
{Ocp-Apim-Subscription-Key} assumes the primary production 32-character,
unless opting for the secondary development key
{request body} this is the APP specific logic/code being passed to the Vendor Product database of the User
ie: extract the full company profile information, using the application request like the simple: <CompanyQueryRq />
{
"FileName":"Q:\\Cougar Enterprises Hosted.QBW",
"Operation":"<?xml version=\"1.0\"?><?qbxml version=\"6.1\"?><QBXML><QBXMLMsgsRq onError=\"continueOnError\"><CompanyQueryRq /></QBXMLMsgsRq></QBXML>"
}
Authorization:Bearer
{Identity Server} stipulate [Implicit]
{Subscription key} Again, this replicates the {Ocp-Apim-Subscription-Key} above
Click SEND
Result
Content is extracted from the USER's Vendor Product database
(ie: company file information for the demo entity: Cougar Enterprises Hosted).
The APP developer then embeds their desired code to handle the processes desired with this DATA.
Some of the many API calls available:
see: http://www.buildmgr.com.au/reckon_api_scripts/
(download the Reckon Australia official SDK v6.1 qbxmlops61.xml documentation http://www.alchester.com.au/download/qbxmlops61.zip for 100's of more QBXML calls....)
By comparison, the Intuit USA version qbxmlops130.zip relates to the US version of Quickbooks, not to Reckon Accounts (Australia).
Some of the "Gotchas" along the way:
- Interest in pursuing API integration commenced in October 2015
- without prejudice, but important to allocate time for, is the whole liaison/setup process.
- early implementation delays were due to:
- the delay in processing an application for the SDK,
- the setup of the clientID,
- the lack of MS-Azure emails arriving,
- a mis-understanding of 'clientID versus subscription KEY usage (both 32 chars, but the former having 4 hyphens, making 36)
- a requirement to setup SSL certificates for the Callback URL
- a confusion on what PORTAL was being referred to
(given we also deal direct with MS-Azure for their other services, directly on 'their' portal)
- and topped off with the usual developer's curse - a couple of typos......
- Anyway, all part of a learning curve that we hope to learn from and improve.......
- More application level considerations got underway from 15/3/2016 endeavouring to be ready for RAP2016 conference (Sydney: April 2016)
- Up until 5/5/2016, the MS-Azure site was a closed shop to CORS
- Our deployment in PHP required a shift into JQuery libraries and Javascript to handle some of the website aspects
- this introduced some attention needed with the way multiple BACKSLASHES need to be deployed in Javascript versus PHP Snippets
- The Payload being passed as data in the body of a POST, gets syntax correction adding a space like "less-then, space, question-mark" where that space was not required.
ie: the need to do urlencoding within the webpage as opposed to pure PHP cade from a background APPlication.
This is due to the syntax correction protocols being adhered to, which demand that two-part punctuation characters should be prefixed by a space.
This goes back to a French versus English argument centuries prior to the advent of computer language constructs.
- Documentation and MS-Azure examples talk a lot of Ocm-Apim-Subscription-Key whereas just Subscription-Key is what's needed
- Error 500 Server Internal Errors result presently (6/5/2016) pending further interrogation of responses to local BROWSER
- Error 404 if appearing, is allegedly an error 401
- Special handling of the backslash character in programming calls for "&bsol" and not "&Backslash"
- Javascript "$.POST" cannot pass HEADERS, so use of "$.ajax" was required
- Our desire to demonstrate all this interactively within the one Callback URL here, presented the need to handle CORS for fonts
- Our local APP servers running a LAMP stack, required us to enhance the Document Root .htaccess to permit CORS handling for fonts from 'any requester'.
- With the relaxing of CORS, this demonstration code may need to be reduced in complexity, but left as is to illustrate the development revisions entailed
- The registration of an API ready COMPANY FILE is required, but this example code uses the provided Cougar Enterprises pre-registered QBW file.
- development time easily lost with mis-judging when to "GET" versus "POST" and the intervening OPTIONS responses to the APP SITE versus the Browser request
- final frontier - the POST command containing the desired {body} must have the curly brackets in the forwarded DATA and not part of the html code.
- During subsequent help to other developers, we realised that the COUGAR file needs to be continuously UPGRADED to match the latest RAH release (ie: RAH2016R2 from June 2016)
- A test login account has been added using 0038181-5 to assist other developers with online Skype/Teamviewer sessions to illustrate the whole process.
- XML parsing experience with an API developer (Sep 2016) observed that Reckon string responses to a POST, arrive with DOUBLE QUOTES in the "response" and the Parser for QBXML (or any other) takes content WITHOUT Double Quotes. (Thanks to Dharmendra Deora research)