Difference between revisions of "API specification to be implemented in the future"

From Kolmisoft Wiki
Jump to navigationJump to search
(New page: =XML API= API by pages All pages are requested by POST or GET methods. == Login page == a. Show Login Form <br /> Method: GET (link: /callc/login) <br /> Params: 0 <br /> Returns: <c...)
 
Line 1: Line 1:
=XML API=
=XML API=


Line 88: Line 87:
== Details ==
== Details ==


----
* Methods: POST, GET(if allowed, not recomended)
* Params:
** user_id - Users ID in MOR database. Required.
** hash - SHA1 hash constructed using user_id and API_Secret_Key (More described in Constructing hash). Required.
* Returns:
** Errors:
*** <error>User was not found</error> - User was not found using user_id. Use correct user_id.
*** <error>Incorrect hash</error> - Hash was not correct. Check API_Secret_Key and order or params while concatenating hash_string.


----
----

Revision as of 15:44, 29 December 2008

XML API

API by pages

All pages are requested by POST or GET methods.

Login page

a. Show Login Form
Method: GET (link: /callc/login)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Login page</pagename>
     <language>en</language>
     <error_msg></error_msg>
     <aval_languages>
       <language>en</language>
       <language>ru</language>
     </aval_languages>
   </page>

b. Login
Method: POST (link: /api/login?u=username&p=password)
Params: 2
Returns:
If already OK 

   <?xml version="1.0" encoding="utf-8">
    <action>
      <name>login</name>
      <status>ok</status>
      <status_message>Succesfully logged in</status_message> 
    </action>

If something wrong 

   <?xml version="1.0" encoding="utf-8">
    <action>
      <name>login</name>
      <status>failed</status>
      <status_message>Error description</status_message> 
    </action>

Main Page

a. Show welcome page
Method: GET (link: /callc/main)
Params: 0
Returns: 

 <?xml version="1.0" encoding="UTF-8"?>
 <page>
   <pagename>Main page</pagename>
   <username>Very Important User</username>
   <userid>1</userid>
   <language>en</language>
   <stats>
     <missed_calls>
     <missed_today>2</missed_today>
     <missed_total>8</missed_total>
     </missed_calls>
     <call_history>
       <calls>
         <call_counts>5</call_counts>
         <period>Month</period>
         <call_duration>00:20:35</call_duration>
       </calls>
       <calls>
         <call_counts>1</call_counts>
         <period>Day</period>
         <call_duration>00:01:35</call_duration>
       </calls>
     </call_history>
     <finances>
       <account>Postpaid</account>
       <balance>100 USD</balance>
       <credit>No Limit</credit>     
     </finances>    
   </stats>
  </page>

Details

a. Show personal details <* pasdasbr /> Method: GET (link: /users/personal_details)
Params: 0
Returns: 

 <?xml version="1.0" encoding="UTF-8"?>
 <page>
   <pagename>Personal details</pagename>
   <language>en</language>
   <userid>1</userid>
   <details>
     <main_details>
         <alias>101</alias>
         <account>Postpaid</account>
         <balance>100 USD</balance>
         <credit>No Limit</credit> 
     </main_details>
     <other_details>
         <username>Andrey</username>
         <surname>Mazunin</surname>
         <personalid></personalid>
         <agreement_number></agreement_number>
         <agreement_date>2008-03-11</agreement_date>
         <taxation_country>Uzbekistan</taxation_country>
         <vat_reg_number></vat_reg_number>
         <vat_percent>18.0</vat_percent>
     </other_details>
     <registration>
         <reg_address>Address</reg_address>
         <reg_postcode>700100</reg_postcode>
         <reg_city>Tashkent</reg_city>
         <reg_country>Uzbekistan</reg_country>
         <reg_state></reg_state>
         <reg_direction>Uzbekistan</reg_direction>
         <reg_phone>998975551234</reg_phone>
         <reg_mobile>998975551234</reg_mobile>
         <reg_fax>998975551234</reg_fax>
         <reg_email>admin@voip.com</reg_email>
     </registration>   
 </details>
 </page>

b. Edit personal details Desc: User edit personal details and push "Change" button
Method: POST (link: /users/update_personal_details/%userid%)
Params: 17
Params List: Personal details.png

Returns:
If already OK 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>edit_personal</name>
      <status>ok</status>
      <status_message>Personal details changed</status_message>
    </action>

If something wrong 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>edit_personal</name>
      <status>failed</status>
      <status_message>Error description</status_message>
    </action>

Devices

a. Show user devices
Method: GET (link: /devices/user_devices)
Params: 0
Returns: 

 <?xml version="1.0" encoding="UTF-8"?>
 <page>
   <pagename>Devices</pagename>
   <language>en</language>
   <userid>1</userid>
   <devices>
     <device>
         <acc>1</acc>    
         <description>Test device 1</description>
         <type>IAX2</type>
         <extension>101</extension>
         <username>101</username>
         <password>101</password>
         <cid>& quot;101& quot; & lt;101& gt; </cid>
         <last_time_registered>2007-04-06 13:51:07</last_time_registered>
     </device>
     <device>
         <acc>2</acc>    
         <description>Test FAX device</description>
         <type>FAX</type>
         <extension>102</extension>
         <username>102</username>
         <password>102</password>
         <cid>& quot;102& quot; & lt;102& gt; </cid>
         <last_time_registered>2007-04-06 13:51:07</last_time_registered>
     </device>
   </devices>
 </page>

Call Flow

a. Show callflow for selected device
Method: GET (link: /devices/callflow/%device_id%)
Params: 1
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Call Flow</pagename>
     <language>en</language>
     <userid>1</userid>
     <device>
       <device_id>1</device_id>
       <device_description>IAX2/101</device_description>
       <device_icon>phone.png</device_icon>
       <callflows>
           <callflow>
               <call_state>Before call</call_state>
               <callflow_action>-</callflow_action>
           </callflow>
           <callflow>
               <call_state>Call</call_state>
               <callflow_action>Dial(IAX2/101)</callflow_action>
           </callflow>
           <callflow>
               <call_state>Answered</call_state>
               <callflow_action>Hangup</callflow_action>
           </callflow>
           <callflow>
               <call_state>No answer</call_state>
               <callflow_action>-</callflow_action>
           </callflow>
           <callflow>
               <call_state>Busy</call_state>
               <callflow_action>Voicemail</callflow_action>
           </callflow>
           <callflow>
               <call_state>Failed</call_state>
               <callflow_action>-</callflow_action>
           </callflow>
         </callflows>
     </device> 
   </page>

b. Edit callflow
Method: GET (link: /devices/callflow_edit/%device_id%?cft=%cf_type%)
Params: 2

CallFlow Types:

before_call
call
hangup
noanswer
busy
failed

Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Call State</pagename>
     <language>en</language>
     <userid>1</userid>
     <callflow>
       <device_id>1</device_id>
       <device_description>IAX2/101</device_description>
       <device_icon>phone.png</device_icon>
       <call_state>Before call</call_state>
       <actions>

++++++++++++++++++++++++++++++++++++++++++++++
+ Forward action
++++++++++++++++++++++++++++++++++++++++++++++ 

              <action>
                <priority>1</priority>
                <action_id>2</action_id> 
                    <aval_devices>
                    <device>
                      <device_id>1</device_id>
                      <device_name>SIP/103</device_name>
                     </device>
                     .....
                    </aval_devices>  
                 </action>

++++++++++++++++++++++++++++++++++++++++++++++
+ Voicemail
++++++++++++++++++++++++++++++++++++++++++++++ 

                <action>
                  <priority>1</priority>
                  <action_id>3</action_id> 
                 </action>

++++++++++++++++++++++++++++++++++++++++++++++
+ Faxdetect
++++++++++++++++++++++++++++++++++++++++++++++ 

               <action>
                <priority>1</priority>
                <action_id>4</action_id> 
                    <aval_devices>
                    <device>
                      <device_id>1</device_id>
                      <device_name>Fax/102</device_name>
                     </device>
                     .....
                    </aval_devices>  
                 </action>

++++++++++++++++++++++++++++++++++++++++++++++ 

       </actions>   
     </callflow> 
   </page>

b. Update callflow type
Method: POST (link: /devices/callflow_edit/%device_id%?cft=%cf_type%)
Params:
whattodo = change_action (hidden) (if set empty action)

Action: forward
Params:
cf_action=forward
whattodo= change_local_device
deviceid=%device_id%

or if forwarding to external number
cf_action=forward
whattodo= change_external_device
ext_number = %ext_number% (number to forwarding)

Action: voicemail
cf_action=voicemail

Action: faxdetect
Params:
cf_action=forward
whattodo= change_fax_device
deviceid=%device_id%

Rates

a. Show all rates
Method: GET (link: /tariffs/user_rates)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Payments</pagename>
     <language>en</language>
     <userid>1</userid>
     <currency>USD</currency>
     <vat_percent>15</vat_percent>
     <aval_currencies>
       <currency>USD</currency>
       <currency>EUR</currency>
     </aval_currencies>
     <rates>
           <rate>
               <ratename>Afghanistan</ratename>
               <rateicon>afg.png</rateicon>
               <ratetype>FIX</ratetype>
               <ratecost>0.02</ratecost>
               <rate_vat_cost>0.03</rate_vat_cost>
           </rate>
           <rate>
               <ratename>Afghanistan</ratename>
               <rateicon>afg.png</rateicon>
               <ratetype>MOB</ratetype>
               <ratecost>0.04</ratecost>
               <rate_vat_cost>0.05</rate_vat_cost>
           </rate>
           .......
       </rates>
   </page>

b.Destinations
Method: GET (link: /directions/dg_list_user_destinations/%dest_id%)
Params: 1
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Destinations</pagename>
     <language>en</language>
     <groupname>Australia</groupname>
     <groupicon>aust.png</groupicon>
           <directions>
               <direction>
               <details>Australia Canberra</details>
               <prefix>61261</prefix>
               <dir_code>FIX</dir_code>
               </direction>
               <direction>
               <details>Australia Canberra</details>
               <prefix>61262</prefix>
               <dir_code>FIX</dir_code>
               </direction>
           </directions>
   </page>

External links

a. Export personal rates
Method: GET
Params: 1
Export to PDF: /tariffs/generate_personal_rates_pdf/%userid%
Export to CSV: /tariffs/generate_personal_rates_csv/%userid%

b. Change currency
Method: GET (link: /tariffs/user_rates?currency=%cur_code%)
Params: 1

Payments

a. Show Payments Method: GET (link: /payments/personal_payments)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Payments</pagename>
     <language>en</language>
     <userid>1</userid>
     <payments>
       <payment>
       <payment_date>2008-03-10 05:41:31</payment_date>
       <confirmed_date>2008-03-10 08:42:00</confirmed_date>
       <payment_type>Manual</payment_type>
       <amount>10</amount>
       <vat>15.0</vat>
       <amount_vat>11.5</amount_vat>
       <currency>USD</currency>
       <completed>Yes</completed>
       </payment>
       <payment>
       <payment_date>2008-03-10 05:41:31</payment_date>
       <confirmed_date>2008-03-10 08:42:00</confirmed_date>
       <payment_type>Manual</payment_type>
       <amount>20</amount>
       <vat>15.0</vat>
       <amount_vat>22.5</amount_vat>
       <currency>EUR</currency>
       <completed>Yes</completed>
       </payment>
     </payments>
   </page>

Invoices

a. Show Invoices Method: GET (link: /accounting/user_invoices)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Invoices</pagename>
     <language>en</language>
     <userid>1</userid>
     <invoices>
       <invoice>
           <user>user</user>
           <inv_number></inv_number>
           <period_start>2008-03-10 05:41:31</period_start>
           <period_end>2008-03-10 08:42:00</period_end>
           <issue_date>2008-03-10 08:42:00</issue_date>
           <paid></paid>
           <paid_date>2008-03-10 08:42:00</paid_date>
           <price>10</price>
           <vat>15.0</vat>
           <price_vat>11.5</price_vat>
       </invoice>
     .....
     </invoices>
   </page>

Subscriptions

a. Show Subscriptions
Method: GET (link: /services/user_subscriptions)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>User subscriptions</pagename>
     <language>en</language>
     <userid>1</userid>
     <subscriptions>
       <subscription>
       <service>Some useful service</service>
       <date_added>2008-03-10 08:42:00</date_added>
       <acivation_start>2008-03-10 08:42:00</acivation_start>
       <acivation_end>2008-03-10 08:42:00</acivation_end>
       <price>10 USD</price>
       </subscription>
       <subscription>
       <service>Some useful service</service>
       <date_added>2008-03-10 08:42:00</date_added>
       <acivation_start>2008-03-10 08:42:00</acivation_start>
       <acivation_end>2008-03-10 08:42:00</acivation_end>
       <price>10 USD</price>
       </subscription>
       ...... 
     </subscriptions>
   </page>


need correction
a. Show Calls
Method: GET (link: /stats/call_list)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Calls</pagename>
     <language>en</language>
     <error_msg></error_msg>
     <userid>1</userid>
     <show_device>all</show_device>
     <status>all</status>
     <direction>all</direction>
     <total_calls>144</total_calls>      
     <username>Very important user</username>
     <currency>USD</currency>
     <aval_languages>
       <language>en</language>
       <language>ru</language>
     </aval_languages>
     <calls_stat>
        <period>
           <period_start>2008-03-10 05:41:31</period_start>
           <period_end>2008-03-10 08:42:00</period_end>
        </period>
        <calls>
          <call>
           <date>2008-03-10 05:45:31</date>
           <called_from>12129989282</called_from>
           <called_to>12129989282</called_to>
           <destination>United States FIX USA 212 New York</destination>
           <duration>00:00:36</duration>
           <hangup_cause>Answered</hangup_cause>
           <price>0.049</price>
         </call>
        ........... 
        </calls>
      </calls_stat>
   </page>

b. Change period
Method: POST (link: /stats/call_list)
Params: 7
%userid% - Current UserId
%search_on% (always 1?)
%period_start%
%period_end%
%direction%
%calltype% (outgoing - incoming - all)
%device% (show_device = all or device_id)

Returns: See a.

External links

a. Export calls
Method: GET
Params: 4
Export to PDF: /stats/call_list_to_pdf/%userid%?call_type=%calltype%&date_from=%period_start%&date_till=%period_end%
Export to CSV: /stats/call_list_to_csv/%userid%?call_type=%calltype%&date_from=%period_start%&date_till=%period_end%

New calls

a. Show new Calls
Method: GET (link: /stats/new_calls_list)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Calls</pagename>
     <language>en</language>
     <error_msg></error_msg>
     <userid>1</userid>
     <calls_stat>
        <total_calls>2</total_calls>
        <calls>
          <call>
           <date>2008-03-10 05:45:31</date>
           <called_from>12129989282</called_from>
           <called_to>12129989282</called_to>
           <duration>00:00:36</duration>
           <hangup_cause>Answered</hangup_cause>
         </call>
        ........... 
        </calls>
      </calls_stat>
   </page>

Missed calls

a. Show missed Calls
Method: GET (link: /stats/missed_calls)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Missed calls</pagename>
     <language>en</language>
     <error_msg></error_msg>
     <userid>1</userid>
     <missed_total>9</missed_total>      
     <username>Very important user</username>
     <aval_languages>
       <language>en</language>
       <language>ru</language>
     </aval_languages>
     <calls_stat>
        <period>
           <period_start>2008-03-10 05:41:31</period_start>
           <period_end>2008-03-10 08:42:00</period_end>
        </period>
        <calls>
          <call>
           <call_id>855</call_id>
           <date>2008-03-10 05:45:31</date>
           <called_from>12129989282</called_from>
           <called_to>12129989282</called_to>
           <duration>00:00:36</duration>
           <hangup_cause>No Answer</hangup_cause>
           <<processed>0</processed>
          </call>
        ........... 
        </calls>
      </calls_stat>
   </page>

b. Change period
Method: POST (link: /stats/missed_calls)
Params: 7
%userid% - Current UserId
%search_on% (always 1?)
%period_start%
%period_end%

Returns: See a.

c. Process call
Method: POST (link: /stats/missed_calls)
Params: 1
%processed%

Returns: See a.

Graphs (Detailed Statistics)

a. Show detailed statistics page
Method: GET (link: /stats/user_stats)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Detailed statistics</pagename>
     <language>en</language>
     <userid>1</userid>
     <start_date>2008-03-10</start_date>
     <end_date>2008-03-11</end_date>
     <details>
       <main_details>
           <todays_normative>0</todays_normative>
           <months_normative>0</months_normative>
           <new_calls>0</new_calls>
       </main_details>
       <calls>
           <incoming>
               <answered>0</answered>
               <no_answer>1</no_answer>
               <busy>0</busy>
               <failed>0</failed>
           </incoming>
           <outgoing>
               <answered>0</answered>
               <no_answer>1</no_answer>
               <busy>0</busy>
               <failed>0</failed>
           </outgoing>
       </calls>
       <detailed_by_date>
           <call_by_date>
               <date>2008-03-11</date>
               <calls_count>1</calls_count>
               <duration>1.5</duration>
               <avg_time>1.5</avg_time>
               <calls_normative>100</calls_normative>
           </call_by_date>
           <call_by_date>
               <date>2008-03-10</date>
               <calls_count>1</calls_count>
               <duration>1.5</duration>
               <avg_time>1.5</avg_time>
               <calls_normative>100</calls_normative>
           </call_by_date>
        </detailed_by_date>
       </details>
   </page>

b. Change dates
Method: POST (link: /billing/stats/user_stats)
Params: 2
%period_start%
%period_end%

Returns: See a.

CLIs

a. Show all CallerIDs
Method: GET (link: /devices/user_device_clis)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>CallerIDs</pagename>
     <language>en</language>
     <userid>1</userid>
     <aval_devices>
        <device id="1">IAX2/101</device> 
        <device id="2">FAX/102</device> 
     </aval_devices>
     <clis>
       <cli>
           <cli_id>3</cli_id>
           <device>IAX2/101</device>
           <device_icon>phone.png</device_icon>
           <cli_name>5555555</cli_name>
           <cli_desc>Linus</cli_desc>
           <added_at>2007-04-06 13:51:07</added_at>
       </cli>
     ..... 
     </clis>
   </page>

b. Add new cli Method: POST(link: /devices/cli_add)
Params: 3
%device_id%
%cli%
%description%

Returns:

If already OK 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>add_cli</name>
      <status>ok</status>
      <status_message>CLI created</status_message>
    </action>

If something wrong 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>add_cli</name>
      <status>failed</status>
      <status_message>CLI not created</status_message>
    </action>

Phonebook

a. Show phonebook
Method: GET (link: /phonebooks/list/%userid%)
Params: 1
Returns: 

<?xml version="1.0" encoding="UTF-8"?>
<page>
  <pagename>Phonebook</pagename>
  <language>en</language>
  <userid>1</userid>
  <entries>
     <entry>
        <entry_number>12015551234</entry_number>
        <entry_name>ExGirlfriend</entry_name>
        <entry_added>2008-03-01 15:44:05</entry_added>
     </entry>
  ...........
  </entries>
</page>

b. Add new entry
Method: POST (/phonebooks/add_new/%userid%)
Params: 3
%userid%
%number%
%name%

Returns:
If already OK 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>add_phonebook_entry</name>
      <status>ok</status>
      <status_message>Record added</status_message>
    </action>

If something wrong 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>add_phonebook_entry</name>
      <status>failed</status>
      <status_message>Please fill all fields</status_message>
    </action>

b. Delete entry
Method: POST (/phonebooks/destroy/%entryid%)
Params: 1
%entryid%

Returns:
If already OK 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>delete_phonebook_entry</name>
      <status>ok</status>
      <status_message>Record deleted</status_message>
    </action>

If something wrong 

   <?xml version="1.0" encoding="UTF-8"?>
   <action>
      <name>delete_phonebook_entry</name>
      <status>failed</status>
      <status_message>We're sorry, but something went wrong</status_message>
    </action>

Faxes

need correction
a. Show Faxes page
Method: GET (link: /stats/faxes_list/%userid%)
Params: 0
Returns: 

   <?xml version="1.0" encoding="UTF-8"?>
   <page>
     <pagename>Faxes</pagename>
     <language>en</language>
     <error_msg></error_msg>
     <userid>1</userid>
     <show_device>all</show_device>
     <username>Very important user</username>
     <aval_languages>
       <language>en</language>
       <language>ru</language>
     </aval_languages>
     <faxes>
        <period>
           <period_start>2008-03-10 05:41:31</period_start>
           <period_end>2008-03-10 08:42:00</period_end>
        </period>
        <fax>
           <device>FAX/102</device>
           <filename></filename>
           <receive_time>2008-03-10 05:45:31</receive_time>
           <sender></sender>
           <status>Received</status>
        </fax>
        ........... 
    </faxes>
   </page>

b. Change period
Method: POST (link: /stats/faxes_list/%userid%)
Params: 6
%userid% - Current UserId
%search_on%
%period_start%
%period_end%
%fax_status%
%device_id%

Returns: See a.

Callback

a. Execute Callback
Method: POST (link: /functions/activate_callback?src=%source%&dst=%destination%&acc=%device%)
Params: 3
Returns:
If already OK 

   <?xml version="1.0" encoding="utf-8">
    <action>
      <name>callback</name>
      <status>ok</status>
      <status_message>Callback activated</status_message> 
    </action>

If something wrong 

   <?xml version="1.0" encoding="utf-8">
    <action>
      <name>callback</name>
      <status>failed</status>
      <status_message>Error description</status_message> 
    </action>

Retrieved from "https://wiki.kolmisoft.com/index.php?title=API_specification_to_be_implemented_in_the_future&oldid=2420"