Difference between revisions of "MOR API"

From Kolmisoft Wiki
Jump to navigationJump to search
Line 24: Line 24:


* [[MOR API calls|calls]] - Retrieves list of calls in selected time period for some user/device
* [[MOR API calls|calls]] - Retrieves list of calls in selected time period for some user/device
== API Related ==
* [[MOR API hash constructon|Hash construction]] - How to construct hash to authenticate data over API


<br><br><br><br>
<br><br><br><br>

Revision as of 15:35, 29 December 2008

MOR API lets other software interact to MOR without knowing internal structure of DB and other logic.

MOR accepts requests by HTML POST and returns result in XML.


Functions

Login

  • login - Logs in user into MOR
  • logout - Logs out user from MOR

Callback

Accounting

  • invoices - Retrieves list of invoices in selected time period.

Calls

  • calls - Retrieves list of calls in selected time period for some user/device

API Related





HTML POST

All requests are in similar format:

HTML POST: http://<SERVER_IP>/mor/api/<function>?u=username&p=password
  • username/password - of the user who is asking for the data.

If user has 'admin' rights - he will get more results and he can perform more actions compared to the user who does not have such rights.




Following functionality WILL BE implemented IN THE FUTURE



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


  • 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.

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>

Constructing hash


  • Concatenate all values you want to send into a single string. Notice that order should be as params are listed in descriptions.

For exmple. You want to get all answered calls of user 123 from 2009-09-09 00:03 till now. You must send user_id, period_start and calltype params.

>> time = "2009-09-09 00:03".to_time.to_i
=> "1252454580"
>> hash_string = "123" + time.to_s + "answered"  
=> "1231252454580answered"

  • Add API_Secret_Key to the end of hash_string

>> API_Secret_Key = "Very Sercet Key"
>> hash_string += API_Secret_Key
=> "1231252454580answeredVery Sercet Key"

  • Calculate SHA1 hash of hash_string

>> Digest::SHA1.hexdigest(hash_string) 
=> "b93c35d5c6183288322122561a3da7e09abb63b7"

  • Use this hash as a hash parameter in API calls.