Accounting Transaction Download
===============================

Copyright (C) 2023-2024, Haley Hashemi, Open Source Instruments Inc.


Introduction
------------

The Accounting Transaction Download (ATD) program downloads all
transactions in a specified date range from a Quickbooks Online
company account. The data file provided by ATD includes the company's
general leger for the specified date range, as well as a separate
leger for each Quickbooks class defined in the company account. Each
leger contains all transactions, including journal entries. Any
transaction that has been assigned a class will appear twice in the
data file: once in the general leger and once in a class leger. To
use ATD, we run the ATD program in a PHP server. We can set up the
PHP server on our own computer or some other computer assigned for
the purpose on our local area network. We connect to the PHP server
with a web browser, and we interact with the ATD program through its
browser interface. By means of this interface, we submit the
credentials that permit ATD to access our Quickbooks Online company
account. ATD then directs us to the Quickbooks log in, using the
credentials. We log in to Quickbooks to verify our assocation with
our Quickbooks Online company account, and we are redirected back to
the ATD interface. We can then generate and download the report.

Note:
----
This code does not use any external package managers, like
composer. If you want to use composer, change the include
('../config.php') at the top of each file to the composer autoload
function. The include('../config.php') uses the autoloader config
file that acts as an SQL database query function. This is a way of
loading Quickbooks' functions, classes, variables, etc, that are
necessary for each piece of code. 

Preliminary Steps
------------------

Prior to connecting ATD to your Quickbooks Online company account, we
must obtain our company credentials on Quickbooks and configure the
ATD code.


Registering ATD 
----------------

1) First, we create a developer account with Intuit, using our company
email address. 

2) Once we have created an Intuit Quickbooks Developer account
associated with our company, we navigate to the Dashboard.

3) From here, we "Create an App", which is more like "Registering an
App". We then navigate to the Apps' page. The "App" refers to ATD,
which is hosted on a local computer.

4) Here we are in the Development environment which contains keys and
credentials that we can use to access information about a "Sandbox
Company", which is a fake company generated by Quickbooks to test API
code on.

5) We are interested in obtaining the keys and credentials in the
Production environment, which will allow ATD to access our Quickbooks
Online company account. To do this, we must go through the app
approval process.


App Aproval Process
-------------------

1) We click "Keys and Credentials" under the Production tab. 

2) A list of to-do items will pop up. We must dulfill all of these
tasks in in order to retrieve the necessary credentials. These tasks
include verifying email address and completing our profile. The more
complicated tasks are described below.

3) Terms of service links: If we plan on publishing this app in the
quickbooks store, these URLS would contain the EULA agreement and the
Privacy Policy. If we are using this for private/personal use, we can
use a dummy URL for both. 

4) App URLs: If we plan on publishing the app, these are the URLs that
allow a user to connect or disconnect. For private/personal use, we
can use a dummy url for each. 

5) We categorize the app as "Accounting".

6) We complete the app assessment questionnaire. Note: In order to
publish ADT, adjustments and additions to the code may need to be
made. 

7) Quickbooks will either approve or reject the app. If the app is
approved, our Production company keys and credentials will be
provided.


Keys and Credentials
---------------------

Once ATD is approved, we have access to our credentials. This includes the ClientID, the Client
Secret, and the Redirect URI. The Client ID and Client Secret are
keys that identify our app and enable the app to connect to your
online company. The Client ID is the public ID of the app and the Client
Secret is a private identification string. The Redirect URI is url
that our browser is redirected to after logging in through ATD. The
redirect URI listed in the Production Settings of the App should match the redirect in the ATD code.


ATD Configuration
-----------------

1) We set the redirect URI in the atdconfig file and in our
Production keys and credentials. The redirect should be a web
address that contains code that extracts the tokens from the log-in
process, and then redirects the client to the ATD server. 
The current URI is set so that we can host the php server
locally. To use this current
URI, we navigate to the atdconfig file, and copy redirect uri
string and we paste it into the Redirect URI box in the Production Keys and
Credentials page. To create our own redirect URI website, we can
use the atd_uri files as a template. We copy paste the new redirect URI location into atdconfig and online.


2) We set the Callback URI in our redirect uri file(atd_uri).
The Callback URI redirects the client to the PHP server, and includes the callback php file in it's path. The current Callback URI is set so that we can host the ATD server
locally, and connect as a client locally. Instructions on how to
separate the client from the ATD server are at the end of this
file.

3) We set the Home URI in our redirect uri file(atd_uri). This URI should be the PHP server. The Home URI is used at the end of the callback and
report procedures to redirect the client to the home page. The
current URI is set so that we can host the ATD server locally, and
connect as a client locally. Instructions on how to separate the ATD
client from the ATD server are at the end of this file.


4) We set the baseURL in our atdconfig file, which determines the type of company the app is accessing. To
access a sandbox company, the string is "development". To access a
production company, the string is "production". 



Flow of steps for ATD connection
--------------------------------

1) Install php, version 8.3 or greater.

2) Listen on PHP Server: Open a locally hosted php server in your
terminal at the top of the ATD directory, using php -S <your ip
address OR localhost>:<port to listen on>(ex: php -S localhost:3000)

3) In your web browser, open a socket to this server by navigating to
<your ip address>:<port>

4) Submit your client ID and client Secret. You can access these in
your Development or Production settings of your app on Quickbooks.

5) Click Connect Company button, and log into your account, selecting
the company you'd like to access. Your redirect URI will bring the
web server back to the index page.

6) Fill out report settings and save them.

7) Click "Generate Report". This will take about 20 seconds.

8) Download generated reports. 

Separating client from server
-----------------------------

ATD is currently configured so that the server and client are both
local. The redirect files that are hosted on the OSI website are
atd_local and atd_186. If we want to host the PHP server on a LAN
with the IP address listed in atd_186, we change the redirect URI,
Callback URI and Home URI to reflect this address and redirect file.
If we want to host the PHP server at another IP address, we must
first identify the server's IP address. Use this IP address for the
Callback URI in your redirect file, and for the Home URI in the
callback and report files. The redirect file itself must be also be
hosted on a website, and the address of file will be our new redirect
URI.