API System

From PhpCOIN Documentation

While phpCOIN can do a lot of things for you, it cannot do everything. Sometimes you need another program to accomplish a specific task.

If that program can accept instructions or data from something other than the keyboard or mouse, then phpCOIN can call it and send it data for you. Two general examples of what I am talking about are the WMM add-on, and the to-be-written QuickBooks add-on.

The WHM add-on sends data to WHM so a domain can be automatically created/changed/deleted on the server when events happen in phpCOIN. The QuickBooks add-on creates IIF import files for QuickBooks to create new clients, invoices and payments so you can have these events entered into QuickBooks simply by double-clicking an icon rather than having to re-type everything.

The file /coin_includes/api.php is loaded automatically by phpCOIN, and if specific API flags are set, phpCOIN will call selected functions within this file when events happen and will pass the function an array containing whatever data is available to phpCOIN itself at that moment in time. So, to use the API system:

1: Enable the "master api" switch:

 Admin -> Parameters -> common -> api -> API Output Master Enable

2: Enable the specific switch(es) for whatever specific function(s) you are interested in.

Product added or deleted by admin:

 Admin -> Parameters -> common -> api -> API Output Enable: Product Created
 Admin -> Parameters -> common -> api -> API Output Enable: Product Deleted

Client added or deleted by admin:

 Admin -> Parameters -> common -> api -> API Output Enable: Client Created
 Admin -> Parameters -> common -> api -> API Output Enable: Client Deleted

Domain added or deleted by admin (client must already exist):

 Admin -> Parameters -> common -> api -> API Output Enable: Domain Created
 Admin -> Parameters -> common -> api -> API Output Enable: Domain Deleted

Invoice (including copying old invoice to new) or payment added or deleted by admin (client must already exist):

 Admin -> Parameters -> common -> api -> API Output Enable: Trans Created
 Admin -> Parameters -> common -> api -> API Output Enable: Trans Deleted

Order created or deleted by admin (client must already exist):

 Admin -> Parameters -> common -> api -> API Output Enable: Order Created
 Admin -> Parameters -> common -> api -> API Output Enable: Order Deleted
 Admin -> Parameters -> common -> api -> API Output Enable: Order New Domain

Records created automatically by the ordering process before return from paylink:

 Admin -> Parameters -> common -> api -> API Output Enable: Order New Client
 Admin -> Parameters -> common -> api -> API Output Enable: Order New Domain
 Admin -> Parameters -> common -> api -> API Output Enable: Order Out Proc (for regular order only)
 Admin -> Parameters -> common -> api -> API Output Enable: Order COR Proc (for COR only)
 Admin -> Parameters -> common -> api -> API Output Enable: Trans Created (for invoice, if auto-invoice is enabled)

Records created automatically by the ordering process after return from paylink:

 Admin -> Parameters -> common -> api -> API Output Enable: Order Return Proc

3: Add your code (if small) or a link to include your source-code file (if larger) to the relevant function in /coin_includes/api.php

For example, the generic routine when an order is created is:

 function APIO_order_new ($_APIO_AData) {
   # Get security flags
     $_SEC = get_security_flags ( );
 
   # Dim some Vars
     global $_CCFG, $_TCFG, $_DBCFG, $_UVAR, $_LANG, $_SERVER, $_nl, $_sp;
 
   # Do whatever, set returns
     $_APIO_Ret['dn']	= 1;
     $_APIO_Ret['msg']	= 'none';
 
   # Return output
     return $_APIO_Ret;
 }

All you need to do is add a line to include your code, and if the results of your code need to display something to the user, set a string to be returned for phpCOIN to display:

 function APIO_order_new ($_APIO_AData) {
   # Get security flags
     $_SEC = get_security_flags ( );
 
   # Dim some Vars
     global $_CCFG, $_TCFG, $_DBCFG, $_UVAR, $_LANG, $_SERVER, $_nl, $_sp;
 
   # Do whatever, set returns
     require_once('my_custom_code.php');
     $_APIO_Ret['dn']	= 1;
     $_APIO_Ret['msg']	= 'I put a pot of coffee on for lightman';
 
   # Return output
     return $_APIO_Ret;
 }

The $_APIO_AData that is passed to the function by phpCOIN is an array containing all the information known to phpCOIN at that moment in time. So in our ordering example, we have things like:

 $_APIO_AData['ord_name_first'] -> Client first name
 $_APIO_AData['ord_company'] -> Client company
 $_APIO_AData['ord_user_name'] -> Client phpCOIN username
 $_APIO_AData['ord_user_pword'] -> Client unencrypted phpCOIN password
 $_APIO_AData['ord_domain'] -> Desired domain name

and for a payment we have thigs like:

 $_APIO_AData['it_ts'] -> Transaction date/time
 $_APIO_AData['it_invc_id'] -> Invoice record ID this transaction applies to
 $_APIO_AData['it_desc'] -> description
 $_APIO_AData['it_amount']