readme for charge module

modules/charge/README

@@ -0,0 +1,176 @@
+Charge Module
+=============
+
+The Charge module enables a few more types of billing in addition to the standard billing features offered by AgileBill, including the ability to bill for overage charges, VoIP calls, time, and any other incremental type charge.
+
+How it works
+
+The charge module will allow charges to be created that will be rolled into an invoice generated by AB at a later date, such as:
+
+* Incremental Charges
+* Overage Charges for Services (bandwidth, late fees, transaction fees, interest charges, etc)
+* Time based billing
+* EBPP
+* Insertion of CDRs for VoIP billing
+
+The charge module can be interfaced and administrated through the AB administration area, and it also offers a easy to use API for realtime integration from remote software, services, etc.
+
+There is also an import wizard in the administration area to mass import charges from any other source for the purpose of EBPP.
+
+There are serveral ways to get the incremental charge records into AB's database so an invoice can be generated. 
+One is via an Import or manual entry in AB, another is via the charge module's API, and the last is by writing directly to the AB database. 
+All three are documented below.
+
+The charge module can interface with AB's tasks that can be automatically set to run the appropriate daily, weekly, monthly, etc., functions to roll the charges into one invoice at the correct times.
+
+Adding Charges
+==============
+
+Charges can be manually added by going to Accounts > Charges > Add and entering the charge data into the form. 
+Alternatively, you can use the API documented below to automatically post your charges from another source.
+
+How to import charges from a TAB or CSV file into AB
+====================================================
+
+You can import charges to the charge module by storing the following data to a tab or comma delimited file:
+
+Field	/ Required?	/ Details
+---------------------------
+date_orig	 	Required 	 
+	Pass the current timestamp, can be generated using the php «time()" function
+status	 		Required 	 
+	0 = Not billed yet, 1 = Already billed
+account_id (or) service_id	 
+	Required 	 Either one of these parameters must be passed, but NOT both. 
+				If using the account_id parameter, the value passed must be either the unique id in the account table.
+				If using the service_id parameter, the value passed must be the unique id in the service table.
+amount	 Required 	 
+	Pass the amount per unit to be billed, accurate up to 6 decimal places.
+sweep_type	 Required 	 
+	Pass the instructions for when to sweep this charge into a new invoice, see values below:
+				0 = Daily
+				1 = Weekly
+				2 = Monthly
+				3 = Quarterly
+				4 = Semi-Annually
+				5 = Annually
+				6 = If you passed a service_id, you can use this option to sweep the charge into the invoice at the same time the associated service is billed.
+taxable	 Required 	 
+	Define whether this charge is taxable or not.
+				0 = No 
+				1 = Yes 
+quantity	 Required 	 
+	Pass the quantity of the number of units to bill at the amount (rate) passed, accurate up to 6 decimal places.
+Attributes	 Required 	 
+	Pass extra attributes name/value pairs that will viewable on the invoice with this line item, see example below:
+				attribute 1==value1
+				attribute 2==value2
+product_id	 Not Required 	 
+	Pass the unique id from the product table. Provide ONLY if the product exists in the AB database, otherwise, use the description parameter to pass a short description.
+description	 Not Required 	 
+	Pass a short description for the charge, up to 32 characters. Provide ONLY the charge is for a product not in the AB database, otherwise, use the product_id parameter.
+
+
+
+How to interface with the Charge API
+====================================
+
+The API for the Charge module in AB enables the remote insertion of incremental charges for a specified account or service.
+
+The API can be accessed via the HTTP or HTTPS (if supported by your server) protocols, by using either the POST or GET methods to pass the required parameters to the main AB index.php file that resides on your server.
+
+Parameters to Send to the API
+-----------------------------
+
+Parameter	 Required?	 Details
+------------------------------
+_do[]	 Yes 	 
+	Set to "charge:api"
+_page	 Yes 	 
+	Set to "core:blank"
+_escape	 Yes 	 
+	Set to “1”
+_login	 Yes 	 
+	Set to “1”
+_username	 Yes 	 
+	Pass a username that is authorized for the Charge API 
+_password	 Yes 	 
+	Pass the password for the username you passed
+				account_id (or) service_id	 Yes 	 Either one of these parameters must be passed, but NOT both. 
+				If using the account_id parameter, the value passed must be either the unique id or username in the account table.
+				If using the service_id parameter, the value passed must be the unique id in the service table.
+amount	 Yes 	 
+	Pass the amount per unit to be billed, accurate up to 6 decimal places.
+sweep_type	 Yes 	 
+	Pass the instructions for when to sweep this charge into a new invoice, see values below:
+				0 = Daily
+				1 = Weekly
+				2 = Monthly
+				3 = Quarterly
+				4 = Semi-Annually
+				5 = Annually
+				6 = If you passed a service_id, you can use this option to sweep the charge into the invoice at the same time the associated service is billed.
+taxable	 No 	 
+	Define whether this charge is taxable or not.
+				0 = No (default)
+				1 = Yes 
+Attributes	 No 	 
+	Pass extra attributes name/value pairs that will viewable on the invoice with this line item, see example below:
+				name--value@@name--value@@name--value
+quantity	 No 	 
+	Pass the quantity of the number of units to bill at the amount (rate) passed, accurate up to 6 decimal places. 
+				Default value = 1
+product_id	 No 	 
+	Pass the unique id from the product table. Provide ONLY if the product exists in the AB database, otherwise, use the description parameter to pass a short description.
+description	 No 	 
+	Pass a short description for the charge, up to 32 characters. Provide ONLY the charge is for a product not in the AB database, otherwise, use the product_id parameter.
+
+Example
+-------
+
+> http://localhost/agilebill/?do[]=charge:api&_page=core:blank&_escape=1&_login=1&_username=admin&_password=admin&amount=1.2345654&sweep_type=0&account_id=username&taxable=1&quantity=5&description=Testing&product_id=1&attributes=name--value@@attr--value
+
+Return Parameters
+-----------------
+
+The API will return the following parameters, in the following syntax:
+
+parameter==value++parameter==value++parameter==value
+Parameter	 Values
+status	 0 = Fail, 1 = Success
+charge_id	 If success, this will be the unique charge id created.
+error	 If fail, this will be the error message
+
+
+
+How to add charges via SQL
+==========================
+
+Charges can be added to the charge module by inserting them into the charge table in AB.
+
+Example:
+
+Charges can be added to the charge module by inserting them into the charge table in AB.
+
+> INSERT INTO charge ( ID, SITE_ID, DATE_ORIG, STATUS, SWEEP_TYPE, ACCOUNT_ID, SERVICE_ID, AMOUNT, QUANTITY, TAXABLE, ATTRIBUTES, DESCRIPTION ) VALUES ( 41, 1, 1103748923, 0, 0, 29, null, 1.2345654, 5, 1, 'name==value\r\nattr==value', 'this is the description' ); 
+
+
+How to manage the tasks that sweep the charges into an invoice
+==============================================================
+
+To setup the task to sweep the charges into invoices, you will need to create a new task in AB for each sweep type (daily, weekly, monthly, etc) that you will be creating.
+
+To add a task, go to Setup > Tasks > Add
+
+To add a task to sweep the daily charges, the following values would be entered:
+
+Name: Sweep Daily Charges
+Task Type: Internal Method
+Command: charge:sweep_daily
+Minutes: 0
+Hour: 1
+Month Day, Month, and Week Day: *
+
+
+
+