Difference between revisions of "MOR API"

From Kolmisoft Wiki
Jump to navigationJump to search
 
(258 intermediate revisions by 18 users not shown)
Line 1: Line 1:
MOR API lets other software interact to MOR without knowing internal structure of DB and other logic.
[[File:warning.png|100px|alt="warning"|link=]]<big><big><big>IMPORTANT!!! API methods described here are for newest MOR version. For previous versions please check appropriate [http://wiki.kolmisoft.com/index.php/MOR_Manual#Old_Manuals manual].</big></big></big>
[[File:api.png|right|alt="api"|link=]]
<mkmeta>Application Program Interface for MOR Class 5 Softswitch</mkmeta>


MOR accepts requests by HTML POST and returns result in XML.
<br><br>
=About=
MOR API lets other software interact with MOR without knowing the internal structure of the database (DB) and other logic.


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


<br><br>
=MOR users that are allowed to use MOR API=
* Admin
* Reseller
* Accountant - only by using Admin Hash and Secret key
* Simple User
<br><br>


=Functions=
=Functions=


==Login==
== API Related ==
* [[API Configuration]] – configuration options for API.
* [[MOR API hash construction|Hash construction]] – how to construct hash to authenticate data over API.


* [[MOR API login|login]] - Logs in user into MOR
<br>
* [[MOR API logout|logout]] - Logs out user from MOR


==Callback==
==Aggregate==
* [[MOR API aggregate get | aggregate_get]] - for getting MOR aggregate statistics.


* [[MOR API callback|callback]] - Initiates callback
<br>
* [[MOR API c2c_callback|c2c_callback]] - Initiates Click2Call specific callback


==Accounting==
==Autodialer==
* [[MOR API autodialer upload numbers | autodialer_upload_numbers]] - upload numbers from CSV file to existing Autodialer Campaign.
* [[MOR API autodialer get campaign statistics | autodialer_get_campaign_statistics]] - gets Autodialer campaign statistics for selected period.
* [[MOR API autodialer redial all failed calls | autodialer_redial_all_failed_calls]] - initiate Redial all failed calls action for specific campaign.
* [[MOR API autodialer get campaign ivr poll results | autodialer_get_campaign_ivr_poll_results]] - gets Autodialer camoaign ivr poll results.
* [[MOR API autodialer change campaign status | autodialer_change_campaign_status]] - changes Autodialer campaign status.


* [[MOR API invoices|invoices]] - Retrieves list of invoices in selected time period.
<br>


==Calls==
==Balance==
* [[MOR API user balance update | user_balance_update]] (change_user_balance) – changes User's Balance
Various methods to retrieve User balance
* [[MOR API user_balance_get|user_balance_get]] (balance) – retrieves a User Balance.
* [[Balance in phone | user_simple_balance_get]] (simple_balance) – gets User's Balance
* [[MOR API user balance get by psw | user_balance_get_by_psw]] – gets User's Balance by his owned Device's Password
* [[MOR API User Balance get by Username | user_balance_get_by_username]] – gets User's Balance by his owned Device's Username


* [[MOR API calls|calls]] - Retrieves list of calls in selected time period for some user/device
<br>


<br><br><br><br>
==Callback==
NOTE: A Callback addon is needed. Does not work on a limited version.
* [[MOR API callback init|callback_init]] (callback) – initiates callback.


=HTML POST=
<br>


All requests are in similar format:
==Calling Cards==
* [[MOR API card_by_cli_update| card_by_cli_update]] (cc_by_cli) – creates and updates calling cards, including adding and transferring funds, by being identified according the Caller_ID.
* [[MOR API card_from_group_sell| card_from_group_sell]] (buy_card_from_callingroup) – sells cards from calling card group.
* [[MOR API card_group_get| card_group_get]] (show_calling_card_group) – show calling group info.
* [[MOR API card_balance_get| card_balance_get]] (card_balance_get) – show card's balance.
* [[MOR API card_payment_add| card_payment_add]] – add payment to the calling card.
* [[MOR_API_Calling_Cards_create| calling_cards_create]] – create Calling Cards.
* [[MOR_API_Calling_Card_update| calling_card_update]] – update Calling Card.
* [[MOR_API_Calling_Cards_get| calling_cards_get]] - get Calling Cards.
* [[MOR_API_Card_Group_create| cc_group_create]] – create Card Group.
* [[MOR_API_Card_Group_update| cc_group_update]] – update Card Group.
* [[MOR API Card Groups get| cc_groups_get]] – show Calling Cards Group info.
<br>


HTML POST: http://<SERVER_IP>/mor/api/<function>?u=username&p=password
==Calls==
* [[MOR API user calls get|user_calls_get]] (user_calls) – retrieves a list of calls in a selected time period for a user/device.
* [[MOR API local calls get|local_calls_get]] - retrieves a list of local calls in a selected time period for a user.
* [[MOR_API_active_calls_get|active_calls_get]] - Retrieves list of active calls for specified User.


* username/password - of the user who is asking for the data.
<br>


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.
==Conflines==
* [[MOR API conflines update|conflines_update]] – changes settings for API, Default User or Default Device.


<br><br><hr>
<br>
<center><big><big>Following functionality WILL BE implemented IN THE FUTURE</big></big></center>
==Credit notes==
<hr><br><br>
* [[MOR API credit_notes_get| credit_notes_get]] (credit_notes) – credit notes list.
* [[MOR API credit_note_update| credit_note_update]] – credit note update.
* [[MOR API credit_notes_create| credit_note_create]] – credit note create.
* [[MOR API credit_notes_delete| credit_note_delete]] – credit note delete.


=XML API=
<br>
==Currencies==
* [[MOR_API_Exchange_rate_update|exchange_rate_update]] - Currency Exchange rate update.


API by pages
<br>
==Device==


All pages are requested by POST or GET methods.  
* [[MOR API device create| device_create]] – create device
* [[MOR_API_device_update | device_update]]  –  update device settings.
* [[MOR API device delete| device_delete]] (delete_device) – delete device
* [[MOR API devices get | devices_get]] (device_list) – users device list
* [[MOR API device details get | device_details_get]] – shows all information about specified device.
<br>
* [[MOR API device callflow get| device_callflow_get]] - returns information about specified device callflow state.
* [[MOR API device callflow update | device_callflow_update]] – updates information of specified device callflow state.
<br>
* [[MOR API CLI info get | cli_info_get]] (cli_get_info) – shows id of device where CLI belongs.
* [[MOR API CLI delete | cli_delete]] – deletes specified CLI.
* [[MOR API CLI add | cli_add]] – creates CLI and assigns it to the specified device.
* [[MOR API device clis get | device_clis_get]] – CLIs list by User and/or Device
<br>
* [[MOR API device rules get | device_rules_get]] – show Device Rules.
* [[MOR API device rule delete | device_rule_delete]] – delete Device Rule.
* [[MOR API device rule create | device_rule_create]] – create Device Rule.
<br>


== Login page ==
==DID==
a. Show Login Form <br />
Method: GET (link: /callc/login) <br />
Params: 0 <br />
Returns:
<code>
    <?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>
</code>


b. Login <br />
* [[MOR API dids get| dids_get]] – get list of particular DIDs
Method: POST (link: /api/login?u=username&p=password) <br />
* [[MOR API did_create| did_create]] – DID create
Params: 2 <br />
* [[MOR_API_did_device_assign| did_device_assign]] (did_assign_device) – Assign Device to DID
Returns: <br />
* [[MOR_API_did_trunk_device_assign| did_trunk_device_assign]] (did_trunk_device_assign) – Assign Trunk Device to DID
If already OK
* [[MOR_API_did_device_unassign| did_device_unassign]] (did_unassign_device) – Unassign Device from DID
<code>
* [[MOR_API_did_details_update| did_details_update]] (did_details_update) – Update DID details
    <?xml version="1.0" encoding="utf-8">
* [[MOR API did subscription stop|did_subscription_stop]] – STOP DID subscription
    <action>
* [[MOR API did terminate|did_terminate]] – DID terminate
      <name>login</name>
* [[MOR API did make free|did_make_free]] – DID make free
      <status>ok</status>
* [[MOR API did rates update|did_rates_update]] – Update DID rates
      <status_message>Succesfully logged in</status_message>
* [[MOR API did rates get|did_rates_get]] – Get DID rates
    </action>
* [[MOR API did close|did_close]] – close the DID
</code>
* [[MOR API did delete|did_delete]] – delete the DID
* [[MOR API did rates details get|did_rates_details_get]] – Get DID rates details
* [[MOR API did rates details update|did_rates_details_update]] – Update DID rates details


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


== Main Page ==
<br>
a. Show welcome page <br />
Method: GET (link: /callc/main) <br />
Params: 0 <br />
Returns:
<code>
  <?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>
</code>


== Details ==
==Email==
* [[MOR API email send| email_send]] (send_email) – send Email.


----
<br>
==Financial statements==
* [[MOR API financial_statements_get| financial_statements_get]] (financial_statements) – financial statements list.


* Methods: POST, GET(if allowed, not recomended)
<br>
* Params:
==Invoices==
** user_id - Users ID in MOR database. Required.
* [[MOR API invoices_get|invoices_get]] (invoices) – retrieves a list of invoices in a selected time period.
** hash - SHA1 hash constructed using user_id and API_Secret_Key (More described in Constructing hash). Required.
* [[MOR_API_invoice_update|invoice_update]] - update Invoice
* 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.


----
<br>
==IVR==
* [[MOR_API_ivr_dial_plan_update|ivr_dial_plan_update]] (invoices) – Updates IVR dial plan.
* [[MOR_API_ivr_time_period_update|ivr_time_period_update]] (invoices) – Updates IVR time period.


a. Show personal details <* pasdasbr />
<br>
Method: GET (link: /users/personal_details) <br />
==LCR==
Params: 0 <br />
* [[MOR API lcrs_get|lcrs_get]] - retrieves list of LCRs.
Returns:
* [[MOR API lcr_create|lcr_create]] - creates LCR
<code>
* [[MOR API lcr_update|lcr_update]] - updates LCR
  <?xml version="1.0" encoding="UTF-8"?>
* [[MOR API lcr_delete|lcr_delete]] - updates LCR
  <page>
* [[MOR API lcr_add_provider|lcr_add_provider]] - adds provider to LCR
    <pagename>Personal details</pagename>
* [[MOR API lcr_delete_provider|lcr_delete_provider]] - deletes provider from LCR
    <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>
</code>


b. Edit personal details
<br>
Desc: User edit personal details and push "Change" button <br />
Method: POST (link: /users/update_personal_details/%userid%) <br />
Params: 17 <br />
Params List:
[[Image:Personal details.png|600px]]<br /><br />
Returns:<br />
If already OK
<code>
    <?xml version="1.0" encoding="UTF-8"?>
    <action>
      <name>edit_personal</name>
      <status>ok</status>
      <status_message>Personal details changed</status_message>
    </action>
</code>


If something wrong
==Location Rules==
* [[MOR API location_rule_create|location_rule_create]] – creates location rule.
* [[MOR API location_rule_update|location_rule_update]] – updates location rule.
* [[MOR API location_rules_get|location_rules_get]] – retrieves location rules.
* [[MOR API location_rule_get|location_rule_get]] – retrieves location rule information.
* [[MOR API location_rule_copy|location_rule_copy]] – copies rule from one location to other one.
* [[MOR API location_rule_delete|location_rule_delete]] – delete location rule.


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


== Devices ==
==Login==
a. Show user devices<br />
* [[MOR API user_login|user_login]] (login) – logs user in to MOR.
Method: GET (link: /devices/user_devices) <br />
* [[MOR API user_logout|user_logout]] (logout) – logs user out from MOR.
Params: 0 <br />
Returns:
<code>
  <?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>
</code>


=== Call Flow ===
<br>
a. Show callflow for selected device<br />
==Monitorings==
Method: GET (link: /devices/callflow/%device_id%) <br />
* [[MOR API ma_activate_api| ma_activate]] – turn on monitorings addon
Params: 1 <br />
Returns:
<code>
    <?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>
</code>


b. Edit callflow<br />
<br>
Method: GET (link: /devices/callflow_edit/%device_id%?cft=%cf_type%) <br />
==Number Pools==
Params: 2 <br />
* [[MOR API number_pools_get| number_pools_get]] – get Number Pools list
* [[MOR API number_pool_create| number_pool_create]] – create Number Pools
* [[MOR API number pool update| number_pool_update]] – update Number Pool
* [[MOR API number pool delete| number_pool_delete]] – delete Number Pool
* [[MOR API number pool numbers create| number_pool_numbers_create]] – create numbers for Number Pool
* [[MOR API number pool numbers delete| number_pool_numbers_delete]] – delete numbers from Number Pool
<br>


CallFlow Types: <br />
==Payments==
* [[MOR API payment_create| payment_create]] (create_payment) – create payment.
* [[MOR API payments_get| payments_get]] (payments_list) – payments list.


before_call <br />
<br>
call<br />
==PBX Pool==
hangup<br />
* [[MOR API pbx_pool_create| pbx_pool_create]] – PBX Pool create.
noanswer<br />
busy<br />
failed<br />


Returns:
<br>
<code>
==Phonebooks==
    <?xml version="1.0" encoding="UTF-8"?>
* [[MOR API phonebooks_get| phonebooks_get]] (phonebooks_api ) – phonebooks list.
    <page>
* [[MOR API phonebook_edit| phonebook_edit]] (phonebook_edit_api) – edit phonebook.
      <pagename>Call State</pagename>
* [[MOR API phonebook_record_create| phonebook_record_create]] – create phonebook.
      <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>
           
++++++++++++++++++++++++++++++++++++++++++++++ <br />
+  Forward action <br />
++++++++++++++++++++++++++++++++++++++++++++++ <br />
              <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>
++++++++++++++++++++++++++++++++++++++++++++++ <br />
+  Voicemail <br />
++++++++++++++++++++++++++++++++++++++++++++++ <br />
                <action>
                  <priority>1</priority>
                  <action_id>3</action_id>
                  </action>
++++++++++++++++++++++++++++++++++++++++++++++ <br />
+  Faxdetect <br />
++++++++++++++++++++++++++++++++++++++++++++++ <br />
                <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>
++++++++++++++++++++++++++++++++++++++++++++++ <br />         
        </actions> 
      </callflow>
    </page>


</code>
<br>
==Providers==
* [[MOR API providers get| providers_get]]  – getting list of providers.
* [[MOR API provider create| provider_create]]  – create provider.
* [[MOR API provider update| provider_update]]  – update provider.
* [[MOR API provider delete| provider_delete]]  – delete provider.
<br>
=== Provider Rules===
* [[MOR_API_provider_rules_get| provider_rules_get]] - shows provider rules
* [[MOR_API_provider_rule_delete| provider_rules_delete]] - deletes provider rules
* [[MOR_API_provider_rule_create| provider_rules_create]] - creates provider rules


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


Action: forward<br />
==Queue==
Params:<br />
* [[MOR API queue log get| queue_log_get]]  – getting MOR queue log.
cf_action=forward<br />
whattodo= change_local_device<br />
deviceid=%device_id%<br />


or if forwarding to external number<br />
<br>
cf_action=forward<br />
==Quickforwards==
whattodo= change_external_device<br />
* [[MOR API Quickforwards get| quickforwards_dids_get]] (quickforwards_dids_get) – get Quickforwards.
ext_number = %ext_number% (number to forwarding)<br />
* [[MOR API Quickforwards update| quickforwards_did_update]] (quickforwards_did_update) – update Quickforwards.
* [[MOR API Quickforwards delete| quickforwards_did_delete]] (quickforwards_did_delete) – delete Quickforwards.


Action: voicemail<br />
<br>
cf_action=voicemail<br />
==Rates==
* [[MOR API rate get|rate_get]] (rate) – check user rate by prefix
* [[MOR API tariff rates get| tariff_rates_get]] (get_tariff) – get all tariff's rates
* [[MOR API tariff_retail_import | tariff_retail_import ]] (import_relail_tariff) – import xml retail tariff
* [[MOR API tariff_wholesale_update | tariff_wholesale_update ]] (wholesale_tariff) – update or create wholesale tariff
* [[MOR API tariffs_get|tariffs_get]] - retrieve list of tariffs


Action: faxdetect<br />
<br>
Params:<br />
cf_action=forward<br />
whattodo= change_fax_device<br />
deviceid=%device_id% <br />


== Rates ==
==Recordings==
a. Show all rates<br />
* [[MOR API recordings get| recordings_get]] – get MOR recordings.
Method: GET (link: /tariffs/user_rates) <br />
* [[MOR API recording update| recording_update]] - update comment for a specific recording.
Params: 0 <br />
* [[MOR API recordings delete | recordings_delete]] - delete recordings based on search parameters.
Returns:
<code>
    <?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>
</code>


b.Destinations <br />
<br>
Method: GET (link: /directions/dg_list_user_destinations/%dest_id%) <br />
== Resellers ==
Params: 1 <br />
* [[MOR API reseller group create|reseller_group_create]] - create new Reseller Group
Returns:
* [[MOR API reseller_groups_get|reseller_groups_get]] - retrieve Reseller Groups
<code>
    <?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>
</code>


=== External links ===
<br>
a. Export personal rates <br/>
==Services==
Method: GET<br/>
* [[MOR API Service create| service_create]] – create Service.
Params: 1<br/>
* [[MOR API Service delete| service_delete]] – delete Service.
Export to PDF: /tariffs/generate_personal_rates_pdf/%userid%<br/>
* [[MOR API Services get| services_get]] – get Services.
Export to CSV: /tariffs/generate_personal_rates_csv/%userid%<br/>
* [[MOR API Service update| service_update]] – update Service.


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


== Payments ==
==SMS==
a. Show Payments
NOTE: SMS addon is need to have these APIs (SMS add-on is no longer supported, new functionality will not be developed)
Method: GET (link: /payments/personal_payments) <br />
* [[MOR API sms send| sms_send]] (send_sms) – send SMS.
Params: 0 <br />
* [[MOR_API_user_sms_service_subscribe | user_sms_service_subscribe ]] – User subscription to SMS Service.
Returns:
* [[MOR_API_user_sms_get | user_sms_get ]] – Retrieves a list of SMS in a selected time period for a user/device.
<code>
    <?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>
</code>


== Invoices ==
<br>
a. Show Invoices
Method: GET (link: /accounting/user_invoices) <br />
Params: 0 <br />
Returns:
<code>
    <?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>
</code>


== Subscriptions ==  
==Spy==
a. Show Subscriptions <br/>
* [[MOR API spy_call | spy_call]] – Initiates a spy call.
Method: GET (link: /services/user_subscriptions) <br />
Params: 0 <br />
Returns:
<code>
    <?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>
</code>


== Calls ==
<br>


----
==Statistics==
* [[MOR API quickstats_get | quickstats_get]] – gets today's [[Quick Stats]] and [[Active Calls]] count


* Methods: POST, GET(if allowed, not recomended)
<br>
* Params:
** user_id - Users ID in MOR database. Required.
** period_start - Unix timestamp of calls period starting date. (Default: Today at 00:00).
** period_end - Unix timestamp of calls period end date. (Default: Today at 23:59).
** direction - Call direction. Possible values [outgoing, incoming]. (Default: outgoing)
** calltype - Call type. Possible values [all, answered, busy, no_answer, failed, missed, missed_inc, missed_inc_all, missed_not_processed_inc]. (Default: all)
** device - Device ID in MOR database. Possible values [all, numeric value of device_id]. (Default: all)
** hash - SHA1 hash constructed using params 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.


----  
<br>
==Subscriptions==
* [[MOR API subscription delete|subscription_delete]] - Subscription delete.
* [[MOR API Subscriptions get|subscriptions_get]] - Subscriptions get.
* [[MOR API subscription create|subscription_create]] - Subscription create.
* [[MOR API subscription create bulk|subscription_create_bulk]] - Bulk Subscription create.
* [[MOR API subscription update|subscription_update]] - Subscription update.
* [[MOR API Subscription Flat Rate Number Status Get| subscription_flat_rate_number_status_get]] -  check prefix covering flat-rate subscriptions
<br>


<b>need correction</b><br />
==User==
a. Show Calls <br />
Method: GET (link: /stats/call_list) <br />
Params: 0 <br />
Returns:
<code>
    <?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>
</code>


b. Change period<br />
* [[MOR API user_register| user_register]] – create new user from params.
Method: POST (link: /stats/call_list) <br />
* [[MOR API user_details_get | user_details_get]] (user_details) – gets user details.
Params: 7 <br />
* [[MOR API user_details_raw_get | user_details_raw_get]] (user_raw_details) – gets user raw details from database.
%userid% - Current UserId <br />
* [[MOR_API_user_details_update| user_details_update]] (user_update_api) – update user from params.
%search_on% (always 1?)<br />
* [[MOR API users_get| users_get]] - get user list
%period_start%<br />
* [[MOR API user_delete| user_delete]] - deletes user
%period_end%<br />
<br>
%direction%<br />
%calltype% (outgoing - incoming - all)<br />
%device% (show_device = all or device_id)<br />


Returns: See a. <br />
==Version==
* [[MOR API system version get| system_version_get]] (get_version) – get MOR version number.


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


== New calls ==
==Vouchers==
a. Show new Calls <br />
* [[MOR API voucher use| voucher_use]] – use selected voucher.
Method: GET (link: /stats/new_calls_list) <br />
Params: 0 <br />
Returns:
<code>
    <?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 ==
<br>
a. Show missed Calls <br />
= Examples =
Method: GET (link: /stats/missed_calls) <br />
* [[MOR API PHP Examples]]
Params: 0 <br />
Returns:
<code>
    <?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>
</code>


b. Change period<br />
<br><br>
Method: POST (link: /stats/missed_calls) <br />
=HTML POST=
Params: 7 <br />
All requests are in a similar format:
%userid% - Current UserId <br />
%search_on% (always 1?)<br />
%period_start%<br />
%period_end%<br />
 
Returns: See a. <br />
 
c. Process call<br />
Method: POST (link: /stats/missed_calls) <br />
Params: 1 <br />
%processed% <br />
 
Returns: See a. <br />
 
== Graphs (Detailed Statistics) ==
a. Show detailed statistics page <br />
Method: GET (link: /stats/user_stats) <br />
Params: 0 <br />
Returns:
<code>
    <?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>
</code>
 
b. Change dates <br />
Method: POST (link: /billing/stats/user_stats) <br />
Params: 2 <br />
%period_start% <br />
%period_end% <br />
 
Returns: See a.
 
== CLIs ==
a. Show all CallerIDs<br />
Method: GET (link: /devices/user_device_clis) <br />
Params: 0 <br />
Returns: 
<code>
    <?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>
</code>
 
b. Add new cli
Method: POST(link: /devices/cli_add) <br />
Params: 3 <br />
%device_id% <br />
%cli% <br />
%description% <br />
 
Returns: 
 
If already OK
 
<code>
    <?xml version="1.0" encoding="UTF-8"?>
    <action>
      <name>add_cli</name>
      <status>ok</status>
      <status_message>CLI created</status_message>
    </action>
</code>
 
If something wrong
 
<code>
    <?xml version="1.0" encoding="UTF-8"?>
    <action>
      <name>add_cli</name>
      <status>failed</status>
      <status_message>CLI not created</status_message>
    </action>
</code>
 
== Phonebook ==
a. Show phonebook<br />
Method: GET (link: /phonebooks/list/%userid%) <br />
Params: 1<br />
Returns:
<code>
<?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>
</code>
 
b. Add new entry <br />
Method: POST (/phonebooks/add_new/%userid%) <br />
Params: 3 <br />
%userid% <br />
%number% <br />
%name% <br />
 
Returns:<br />
If already OK
<code>
    <?xml version="1.0" encoding="UTF-8"?>
    <action>
      <name>add_phonebook_entry</name>
      <status>ok</status>
      <status_message>Record added</status_message>
    </action>
</code>
 
If something wrong
 
<code>
    <?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>
</code>
 
b. Delete entry <br />
Method: POST (/phonebooks/destroy/%entryid%) <br />
Params: 1 <br />
%entryid%<br />
 
Returns:<br />
If already OK
<code>
    <?xml version="1.0" encoding="UTF-8"?>
    <action>
      <name>delete_phonebook_entry</name>
      <status>ok</status>
      <status_message>Record deleted</status_message>
    </action>
</code>
 
If something wrong
 
<code>
    <?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>
</code>
 
== Faxes ==
<b>need correction</b><br />
a. Show Faxes page <br />
Method: GET (link: /stats/faxes_list/%userid%) <br />
Params: 0 <br />
Returns:
<code>
    <?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>
</code>
 
b. Change period<br />
Method: POST (link: /stats/faxes_list/%userid%) <br />
Params: 6 <br />
%userid% - Current UserId <br />
%search_on% <br />
%period_start%<br />
%period_end%<br />
%fax_status%<br />
%device_id%<br />
 
Returns: See a. <br />
 
== Callback ==
a. Execute Callback <br />
Method: POST (link: /functions/activate_callback?src=%source%&dst=%destination%&acc=%device%) <br />
Params: 3 <br />
Returns: <br />
If already OK
<code>
    <?xml version="1.0" encoding="utf-8">
    <action>
      <name>callback</name>
      <status>ok</status>
      <status_message>Callback activated</status_message>
    </action>
</code>
 
If something wrong <br />
<code>
    <?xml version="1.0" encoding="utf-8">
    <action>
      <name>callback</name>
      <status>failed</status>
      <status_message>Error description</status_message>
    </action>
</code>
 
== 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.


<code>
  HTML POST: http://<SERVER_IP>/billing/api/<function>?u=username
  >> time = "2009-09-09 00:03".to_time.to_i
=> "1252454580"
>> hash_string = "123" + time.to_s + "answered" 
=> "1231252454580answered"
</code>


* Add API_Secret_Key to the end of hash_string
* username - the user name and password of the user who is asking for the data.
<code>
>> API_Secret_Key = "Very Sercet Key"
>> hash_string += API_Secret_Key
=> "1231252454580answeredVery Sercet Key"
</code>


* Calculate SHA1 hash of hash_string
If the user has 'admin' rights, he will get more results and can perform more actions compared to a user who does not have such rights.
<br><br>
=Useful to know=


<code>
* All API methods return data straight from the database. It means that MOR GUI settings do not affect data, it will be returned as it is saved in the database. For example:
>> Digest::SHA1.hexdigest(hash_string)
** Value of money will be returned in Default System [[Currencies|Currency]].
=> "b93c35d5c6183288322122561a3da7e09abb63b7"
** Date will not be affected by [[Configuration_from_GUI#Visual| Default date format]] setting.
</code>
** Value of money will not be affected by [[Configuration_from_GUI#Visual|Number digits]] setting.


* Use this hash as a hash parameter in API calls.
<br><br>
----
=See also =
* [[API Configuration]]
* [[MOR integration]]
* [[How to block access to some API functions]]
* [[API specification to be implemented in the future]]

Latest revision as of 07:31, 22 January 2024

"warning"IMPORTANT!!! API methods described here are for newest MOR version. For previous versions please check appropriate manual.

"api"



About

MOR API lets other software interact with MOR without knowing the internal structure of the database (DB) and other logic.

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



MOR users that are allowed to use MOR API

  • Admin
  • Reseller
  • Accountant - only by using Admin Hash and Secret key
  • Simple User



Functions

API Related


Aggregate


Autodialer


Balance

Various methods to retrieve User balance


Callback

NOTE: A Callback addon is needed. Does not work on a limited version.


Calling Cards


Calls

  • user_calls_get (user_calls) – retrieves a list of calls in a selected time period for a user/device.
  • local_calls_get - retrieves a list of local calls in a selected time period for a user.
  • active_calls_get - Retrieves list of active calls for specified User.


Conflines


Credit notes


Currencies


Device





DID



Email


Financial statements


Invoices


IVR


LCR


Location Rules


Login


Monitorings


Number Pools


Payments


PBX Pool


Phonebooks


Providers


Provider Rules


Queue


Quickforwards


Rates


Recordings


Resellers


Services


SMS

NOTE: SMS addon is need to have these APIs (SMS add-on is no longer supported, new functionality will not be developed)


Spy


Statistics



Subscriptions


User


Version


Vouchers


Examples



HTML POST

All requests are in a similar format: 

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

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

Useful to know

  • All API methods return data straight from the database. It means that MOR GUI settings do not affect data, it will be returned as it is saved in the database. For example:



See also

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