Difference between revisions of "MOR API user calls get"

From Kolmisoft Wiki
Jump to navigationJump to search
 
(33 intermediate revisions by 9 users not shown)
Line 1: Line 1:
=[[MOR API]]=
<!---This functionality is available from MOR 8--->
''This functionality is available from [[MOR 8 documentation | MOR 8]]''
=Description=
Retrieves list of calls in selected time period for specified User/Device.<br><br>


Retrieves list of calls in selected time period for some user/device
'''Admin''' - can get any user calls


'''Reseller''' - can get his and his users calls.
'''User''' - can get his own calls.
<br>
=Usage=
* From '''MOR X4''' call: '''/api/user_calls_get'''
* For Backwards-compatibility old name 'user_calls' is also usable. Call: '''/api/user_calls'''
* Methods: POST, GET(if allowed, not recomended)
<br><br>
<br><br>
'''Admin''' - can get every user calls
===Parameters=== 


'''Reseller''' - can get his and his users calls
Parameters which are '''included''' into hash:


'''User''' - can get his own calls
* period_start - Unix timestamp of calls period starting date. (Default: Today at 00:00). <!---Nuo MOR 8--->
* period_end - Unix timestamp of calls period end date. (Default: Today at 23:59). <!---Nuo MOR 8--->
* s_user - User's ID in MOR database. '''Required, if s_reseller is not used'''. <!---Nuo MOR 8. Nuo mor 9 iš user_id tapo s_user--->
* s_call_type - Call type. Possible values [all, answered, no answer, failed, busy]. (Default: all) <!---Nuo MOR 8. Nuo mor 9 s_call_type--->
* s_device - Device ID in MOR database. Possible values [all, numeric value of device_id]. (Default: all). <!---Nuo MOR 8. Nuo mor 9 s_device--->
* s_provider - Provider ID in MOR database. Possible values [all, numeric value of provider_id]. (Default: all).Only for Admin and Reseller PRO.  <!---Nuo MOR 9. From mor 10 works with reseller if has own_providers--->
* s_hgc - Hangup cause code ID in MOR database. Possible values [all, numeric value of hangup_cause_code_id]. (Default: all). Only for Admin and Reseller if Show HGC for Resellers is ON.  <!---Nuo MOR 9--->
* s_did - show calls made through specific DID. Possible values [all, calls.did_id]. (Default: all). Only for Admin.  <!---Nuo MOR 9--->
* s_destination - prefix.  <!---Nuo MOR 9--->
* order_by - Possible values [time, src, dst, prefix, nice_billsec, hgc, server, p_name, p_rate, p_price, reseller, r_rate, r_price, user, u_rate, u_price, number, d_provider, d_inc, d_owner]. (Default: time).  <!---Nuo MOR 9--->
* order_desc - Possible values [0,1]. (Default: 0).  <!---Nuo MOR 9--->
* only_did - show calls that only went through did. Possible values [0,1]. (Default: 0).  <!---Nuo MOR 11--->
* s_uniqueid - returns specific Call by uniqueid. Date parameters are ignored in this case.
* s_callback_uniqueid - returns Call(s) by callback uniqueid. Date parameters are ignored in this case. Only works when '''use_callback_uniqueid''' setting is enabled in [[Mor.conf|mor.conf]].
* originator_codec_name - originator codec.
* terminator_codec_name - terminator codec.


'''Note that parameters are shown in the same order as they have to be when generating the hash. Last parameter in a row is API_Secret_Key'''
<br><br>
Parameters which are '''not included''' into hash:


==[[MOR 8 documentation | MOR 8]]==
* [[MOR API hash construction | hash]] - SHA1 hash constructed using parameters above and API_Secret_Key ([[MOR API hash construction | More described in Constructing hash]]). '''Required''' (if setting '''Disable hash checking''' is not checked).
* u - username  for authentication. '''Required'''. <!---NUO x4 password nereikalaujamas--->
* <!---Nuo MOR X6---> s_reseller - Reseller type User ID in MOR database.  (Default: all).
<br><br><!---Nuo MOR 8 buvo, o nuo MOR 9 nebėra direction---> <!---Iki nuo 11 buvo s_did_pattern, s_reseller_did, vėliau nebeliko--->
 
===Request===
 
If you want find s_call_type=all calls for s_user = 5, through s_device=7 in period from 2011-11-01 23:59:59 till 2011-11-30 23:59:59, and your API Secret Key = 456789
 
You send:
 
HTML POST: http://<SERVER_IP>/billing/api/user_calls_get?u=username&s_user=5&period_start=1320191999&period_end=1322697599&s_device=7&s_call_type=all&hash=df2983700ffecb52e6649f0cb3981b66537083a4
 
'''* Note that username is not included in hash'''
<br><br>
<br><br>
===Returns===
'''Success:''' Everything is ok. You get the list of calls if there is any:
<?xml version="1.0" encoding="UTF-8"?>
<page>
  <pagename>Calls</pagename>
  <language>en</language>
  <error_msg></error_msg>
  <userid>0</userid>
  <username>admin</username>
  <total_calls>1</total_calls>
  <currency>USD</currency>
  <calls_stat>
    <period>
      <period_start>2008-03-07 11:48:18</period_start>
      <period_end>2012-03-07 11:46:01</period_end>
    </period>
    <show_user>all</show_user>
    <show_device>all</show_device>
    <show_status>all</show_status>
    <show_provider>4</show_provider>
    <show_hgc>all</show_hgc>
    <show_did>1</show_did>
    <calls>
      <call>
        <calldate2>2009-01-02 00:00:01</calldate2>
<!---This functionality is available from MOR x3--->        <timezone>GMT+02:00</timezone>
        <clid>37046246362</clid>
        <destination>Lithuania MOB Lithuania mobile</destination>
        <did>37063042438</did>
        <did_inc_price>1.0</did_inc_price>
        <did_price>1.0</did_price>
        <did_prov_price>1.0</did_prov_price>
        <dispod>ANSWERED(16)</dispod>
        <dst>37063042438</dst>
        <nice_billsec>20.0</nice_billsec>
        <nice_reseller> </nice_reseller>
        <prefix>3706</prefix>
        <profit>4</profit>
        <provider_name>Test Provider</provider_name>
        <provider_price>1.0</provider_price>
        <provider_rate>0.0</provider_rate>
        <reseller_price>0.0</reseller_price>
        <reseller_rate>0.0</reseller_rate>
        <server_id>1</server_id>
        <src>37046246362</src>
        <user>test_user</user>
<!---This functionality is available from MOR X11--->        <user_currency>EUR</user_currency>
<!---This functionality is available from MOR X11--->        <user_exchange_rate>0.744100000000000</user_exchange_rate>
        <user_id>5</user_id>
        <user_price>2.0</user_price>
        <user_rate>0.0</user_rate>
        <dst_user_id>7</dst_user_id>
<!---This functionality is available from MOR x4--->        <uniqueid>1232113379.3</uniqueid>
      </call>
    </calls>
  </calls_stat>
</page>
'''NOTE''' that calldate is in system(server) Time Zone.
'''Errors:'''
* <error>API Requests are disabled</error> – '''Allow API globally''' setting is unchecked.
* <error>Access Denied</error> – Such username does not exist in the database or it was not specified.
* <error>Incorrect hash</error> – Hash was not correct. Check API_Secret_Key and order or params while concatenating hash_string.
* <error>User was not found</error> – User was not found using user_id. Use correct user_id.


* Call: /api/user_calls
Example:
* Methods: POST, GET(if allowed, not recomended)
* 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)
** [[MOR API hash construction | hash]] - SHA1 hash constructed using params and API_Secret_Key ([[MOR API hash construction | More described in Constructing hash]]). '''Required'''.
** u - Users username. '''Required'''.
** p - Users password. '''Required'''.
* Returns:
** Errors:
*** <error>User was not found</error> - User was not found using user_id. Use correct user_id. Make sure that username (u) and password (p) are specified.
*** <error>Incorrect hash</error> - Hash was not correct. Check API_Secret_Key and order or params while concatenating hash_string.


== from[[MOR 9 documentation | MOR 9]]==
  <status>
    <error>API Requests are disabled</error>
  </status>
<br><br>
<br><br>


* Call: /api/user_calls
=See also=
* Methods: POST, GET(if allowed, not recomended)
 
* Params:
* [[MOR API]]
** s_user - Users ID in MOR database.
** 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).
** s_call_type - Call type. Possible values [all,answered,no answer,failed,busy]. (Default: all)
** s_device - Device ID in MOR database. Possible values [all, numeric value of device_id]. (Default: all)
** s_provider - Provider ID in MOR database. Possible values [all, numeric value of provider_id]. (Default: all).Only for Admin.
** s_hgc - Hangup cause code ID in MOR database. Possible values [all, numeric value of hangup_cause_code_id]. (Default: all). Only for Admin or Reseller if Show HGC for Resellers is ON
** s_did - Did ID in MOR database. Possible values [all, numeric value of did_id]. (Default: all).Only for Admin.
** s_destination - prefix.
** order_by - Possible values [time,src,dst,prefix,nice_billsec,hgc,server,p_name,p_rate,p_price, reseller, r_rate,r_price,user,u_rate,u_price,number, d_provider, d_inc, d_oener]. (Default: time)
** order_desc - Possible values [0,1]. (Default: 0)
** [[MOR API hash construction | hash]] - SHA1 hash constructed using params and API_Secret_Key ([[MOR API hash construction | More described in Constructing hash]]). '''Required'''.
** u - Users username. '''Required'''.
** p - Users password. '''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>
== from [[MOR 10 documentation | MOR 10]] ==
<br>
add new params
* Params:
** s_provider - for reseller if allow own_providers.
<br>
== from [[MOR 11 | MOR 11]] ==
<br>
add new params
* Params:
** only_did - get only calls made via DIDs. Possible values [0,1]. (Default: 0)

Latest revision as of 13:28, 20 January 2023

Description

Retrieves list of calls in selected time period for specified User/Device.

Admin - can get any user calls

Reseller - can get his and his users calls.

User - can get his own calls.

Usage

  • From MOR X4 call: /api/user_calls_get
  • For Backwards-compatibility old name 'user_calls' is also usable. Call: /api/user_calls
  • Methods: POST, GET(if allowed, not recomended)



Parameters

Parameters which are included into hash:

  • 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).
  • s_user - User's ID in MOR database. Required, if s_reseller is not used.
  • s_call_type - Call type. Possible values [all, answered, no answer, failed, busy]. (Default: all)
  • s_device - Device ID in MOR database. Possible values [all, numeric value of device_id]. (Default: all).
  • s_provider - Provider ID in MOR database. Possible values [all, numeric value of provider_id]. (Default: all).Only for Admin and Reseller PRO.
  • s_hgc - Hangup cause code ID in MOR database. Possible values [all, numeric value of hangup_cause_code_id]. (Default: all). Only for Admin and Reseller if Show HGC for Resellers is ON.
  • s_did - show calls made through specific DID. Possible values [all, calls.did_id]. (Default: all). Only for Admin.
  • s_destination - prefix.
  • order_by - Possible values [time, src, dst, prefix, nice_billsec, hgc, server, p_name, p_rate, p_price, reseller, r_rate, r_price, user, u_rate, u_price, number, d_provider, d_inc, d_owner]. (Default: time).
  • order_desc - Possible values [0,1]. (Default: 0).
  • only_did - show calls that only went through did. Possible values [0,1]. (Default: 0).
  • s_uniqueid - returns specific Call by uniqueid. Date parameters are ignored in this case.
  • s_callback_uniqueid - returns Call(s) by callback uniqueid. Date parameters are ignored in this case. Only works when use_callback_uniqueid setting is enabled in mor.conf.
  • originator_codec_name - originator codec.
  • terminator_codec_name - terminator codec.

Note that parameters are shown in the same order as they have to be when generating the hash. Last parameter in a row is API_Secret_Key

Parameters which are not included into hash:

  • hash - SHA1 hash constructed using parameters above and API_Secret_Key ( More described in Constructing hash). Required (if setting Disable hash checking is not checked).
  • u - username for authentication. Required.
  • s_reseller - Reseller type User ID in MOR database. (Default: all).



Request

If you want find s_call_type=all calls for s_user = 5, through s_device=7 in period from 2011-11-01 23:59:59 till 2011-11-30 23:59:59, and your API Secret Key = 456789

You send:

HTML POST: http://<SERVER_IP>/billing/api/user_calls_get?u=username&s_user=5&period_start=1320191999&period_end=1322697599&s_device=7&s_call_type=all&hash=df2983700ffecb52e6649f0cb3981b66537083a4 

* Note that username is not included in hash

Returns

Success: Everything is ok. You get the list of calls if there is any:

<?xml version="1.0" encoding="UTF-8"?>
<page>
 <pagename>Calls</pagename>
 <language>en</language>
 <error_msg></error_msg>
 <userid>0</userid>
 <username>admin</username>
 <total_calls>1</total_calls>
 <currency>USD</currency>
 <calls_stat>
   <period>
     <period_start>2008-03-07 11:48:18</period_start>
     <period_end>2012-03-07 11:46:01</period_end>
   </period>
   <show_user>all</show_user>
   <show_device>all</show_device>
   <show_status>all</show_status>
   <show_provider>4</show_provider>
   <show_hgc>all</show_hgc>
   <show_did>1</show_did>
   <calls>
     <call>
       <calldate2>2009-01-02 00:00:01</calldate2>
       <timezone>GMT+02:00</timezone>
       <clid>37046246362</clid>
       <destination>Lithuania MOB Lithuania mobile</destination>
       <did>37063042438</did>
       <did_inc_price>1.0</did_inc_price>
       <did_price>1.0</did_price>
       <did_prov_price>1.0</did_prov_price>
       <dispod>ANSWERED(16)</dispod>
       <dst>37063042438</dst>
       <nice_billsec>20.0</nice_billsec>
       <nice_reseller> </nice_reseller>
       <prefix>3706</prefix>
       <profit>4</profit>
       <provider_name>Test Provider</provider_name>
       <provider_price>1.0</provider_price>
       <provider_rate>0.0</provider_rate>
       <reseller_price>0.0</reseller_price>
       <reseller_rate>0.0</reseller_rate>
       <server_id>1</server_id>
       <src>37046246362</src>
       <user>test_user</user>
       <user_currency>EUR</user_currency>
       <user_exchange_rate>0.744100000000000</user_exchange_rate>
       <user_id>5</user_id>
       <user_price>2.0</user_price>
       <user_rate>0.0</user_rate>
       <dst_user_id>7</dst_user_id>
       <uniqueid>1232113379.3</uniqueid>
     </call>
   </calls>
 </calls_stat>
</page>

NOTE that calldate is in system(server) Time Zone.

Errors:

  • <error>API Requests are disabled</error> – Allow API globally setting is unchecked.
  • <error>Access Denied</error> – Such username does not exist in the database or it was not specified.
  • <error>Incorrect hash</error> – Hash was not correct. Check API_Secret_Key and order or params while concatenating hash_string.
  • <error>User was not found</error> – User was not found using user_id. Use correct user_id.

Example:

 <status>
   <error>API Requests are disabled</error>
 </status>



See also