Difference between revisions of "MOR API device update"

From Kolmisoft Wiki
Jump to navigationJump to search
 
(48 intermediate revisions by 10 users not shown)
Line 14: Line 14:


* '''device''' - device_id. '''Required'''.
* '''device''' - device_id. '''Required'''.
* '''authentication''' - 0 stands for "Dynamic (Username/Password)" Device Authentication, 1 stands for "IP Authentication:"
* '''username''' - sets value for Username if device Authentication value is Dynamic. <!--su #12727 ticketu apdaryta kad sitas apram veiktu ir su username ir su device_name parametrais--->
* '''host''' - sets value for IP Address if device Authentication value is IP Authentication
* '''port''' - sets value for Port if device Authentication value is IP Authentication


'''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'''
'''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'''
Line 21: Line 26:
* '''u''' - username for authentication. '''Required'''.
* '''u''' - username for authentication. '''Required'''.
* '''new_location_id''' - location_id.
* '''new_location_id''' - location_id.
<br>
<!--FROM MOR X5--->
'''Additional feature''' <br>If API setting '''Allow Resellers to use Admin Localization Rules''' is enabled:<br>Reseller is able to set location inherited from Admin. '''new_location_id''' should be used as a parameter for location.
* '''callerid_number''' - number.
* '''callerid_name''' - name.
<!--FROM MOR X6--->
* '''trunk''' - 0 stand for "No", 1 stand for "Yes", 2 stands for "Yes with ANI".
* '''fax_email_add''' - email address to add.
* '''fax_email_delete''' - email address to delete.
* '''call_limit''' - call limit. Set 0 if you want unlimited sim. calls.
* '''inbound_call_limit''' - call limit. Set 0 if you want unlimited inbound calls.
* '''fromuser''' - sets value for Fromuser.
* '''password''' - sets value for Password if device Authentication value is Dynamic.
* '''call_timeout''' - max call duration (in seconds).
* '''extension''' - device extension. Allowed symbols: a-z0-9#*.
* '''pin''' - device PIN. Allowed symbols: 0-9 or empty parameter.
* '''hidden''' - for hiding and unhiding Devices. Allowed values: 0 - unhide, 1 - hide.
* '''language''' - sets value for language.
<!--FROM MOR X12--->
* '''allow_empty_callerid''' - if set to 1, allows to set empty callerid_number and/or callerid_name.
* '''comment''' - device comment to add or update.
<!--FROM MOR X13--->
* '''encryption''' - enable or disable encryption. Allowed values: 1 - yes, 0 - no.
* '''transport''' - allowed values: "'''udp'''", "'''tcp'''", "'''udp,tcp'''", "'''tcp,udp'''", "'''tls'''".
<!--FROM MOR X14-->
* '''hostname''' - set device hostname, will take effect only if authentication = 1 (IP authenticated device).
* '''device_balance_enabled''' - enable or disable device balance. Allowed values: 1 - enable, 0 - disable.
* '''balance''' - set device balance. Only numeric values.
<!--FROM MOR X16-->
* '''ringing_timeout''' - max ringing duration in seconds (minimum value is 10).
* '''callerid_control_by_dids''' - 1 - enable, 0 - disable. Only available when the device has DIDs and the CallerID Number field is empty.
* '''voicemail_email''' - device VoiceMail email.
* '''description''' - updates device description field.
* '''progressinband''' - allowed values: "'''No'''", "'''Yes'''", "'''Never'''".
<!--FROM MOR X17 -->
* '''emergency_callerid''' - number for Emergency callerID.
* '''emergency_callerid_pool_id''' - Id of Emergency CallerID Number Pool
* '''sendrpid''' - yes, no (SIP)
* '''t38_support''' - no, yes, fec, redundancy and none (SIP and FAX, same as GUI)
* '''сopy_legA_name_to_LegB_number''' - 0,1 (SIP)
<!--FROM MOR X18 -->
* '''total_call_limit''' - one concurrent Call Limit (Outbound + Inbound). If the request uses call_limit and inbound_call_limit together with total_call_limit, then total_call_limit will be used.
* '''valid_cid_number_pool_id''' - Number Pool with valid CallerIDs.
* '''fake_number_pool_id''' - Random Number from Number Pool.
'''Note''': It should be taken into account that '''Use random Number when CallerID is invalid''' is not stored in the database. The option is '''on''' when both '''number_pools''' ('''valid_cid_number_pool_id''' and '''fake_number_pool_id''') are set. If they are not set, both '''number_pool''' parameters must be specified the first time to save the values. Other times, the parameters can be specified separately.
To disable the option '''Use random Number when CallerID is invalid''' it is required to send '''-1''' with parameters '''valid_cid_number_pool_id''' or '''fake_number_pool_id'''.<br>
Example: '''valid_cid_number_pool_id=-1'''.
* '''trunk_3cx''' - Enable 3CX option. This setting is meaningful only if the '''trunk''' parameter is set to 1 or 2.
<br><br>
'''Additional feature'''  
<br><br>
If API setting '''Allow Resellers to use Admin Localization Rules''' is enabled:<br>Reseller is able to set location inherited from Admin. '''new_location_id''' should be used as a parameter for location.
<br><br>
<br><br>


===Request===
===Request===


  HTML POST: http://<SERVER_IP>/billing/api/device_update?u=admin&device=2&location_id=7&hash=297dab8c386794b2e947d52affb8f576c643569e
  HTML POST: http://<SERVER_IP>/billing/api/device_update?u=admin&device=2&new_location_id=7&hash=297dab8c386794b2e947d52affb8f576c643569e
<br><br>
<br><br>


Line 47: Line 100:
* <error>Device was not found</error> - Device id incorrect or does not exist
* <error>Device was not found</error> - Device id incorrect or does not exist
* <error>Location was not found</error> - Location id incorrect or does not exist
* <error>Location was not found</error> - Location id incorrect or does not exist
* <error>Password is too short</error> - Password of device is too short
* <error>CallerID Control By DIDs was not updated because the device has callerID number</error>
* <error>CallerID Control By DIDs was not updated because the device is not assigned to any DID</error>
* <error>Wrong format of VoiceMail Email address</error>
* <error>Emergency CallerID was not updated. Number Pool was not found</error>
* <error>Emergency CallerID Number Pool was not updated. Emergency CallerID must be present</error>
* <error>Emergency CallerID Number Pool was not updated. Number Pool was not found</error>
<br><br>
<br><br>
==Examples==
Change Username/Password authenticated Device to IP authenticated Device:
http://<SERVER_IP>/billing/api/device_update?u=admin&device=51&authentication=1&host=192.168.5.20&port=5060&hash=XXXX
Set empty CallerID:
http://<SERVER_IP>/billing/api/device_update?u=admin&device=2&allow_empty_callerid=1&callerid_number=&hash=XXXX
=See also=
=See also=


* [[MOR API]]
* [[MOR API]]

Latest revision as of 12:23, 11 July 2024

Description

MOR API update existing Device from params.

Usage

  • Call: /api/device_update
  • Methods: POST, GET(if allowed, not recomended)



Parameters

Parameters which are included into hash:

  • device - device_id. Required.
  • authentication - 0 stands for "Dynamic (Username/Password)" Device Authentication, 1 stands for "IP Authentication:"
  • username - sets value for Username if device Authentication value is Dynamic.
  • host - sets value for IP Address if device Authentication value is IP Authentication
  • port - sets value for Port if device Authentication value is IP Authentication


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 which are listed above. 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 ( More described in Constructing hash). Required.
  • u - username for authentication. Required.
  • new_location_id - location_id.
  • callerid_number - number.
  • callerid_name - name.
  • trunk - 0 stand for "No", 1 stand for "Yes", 2 stands for "Yes with ANI".
  • fax_email_add - email address to add.
  • fax_email_delete - email address to delete.
  • call_limit - call limit. Set 0 if you want unlimited sim. calls.
  • inbound_call_limit - call limit. Set 0 if you want unlimited inbound calls.
  • fromuser - sets value for Fromuser.
  • password - sets value for Password if device Authentication value is Dynamic.
  • call_timeout - max call duration (in seconds).
  • extension - device extension. Allowed symbols: a-z0-9#*.
  • pin - device PIN. Allowed symbols: 0-9 or empty parameter.
  • hidden - for hiding and unhiding Devices. Allowed values: 0 - unhide, 1 - hide.
  • language - sets value for language.
  • allow_empty_callerid - if set to 1, allows to set empty callerid_number and/or callerid_name.
  • comment - device comment to add or update.
  • encryption - enable or disable encryption. Allowed values: 1 - yes, 0 - no.
  • transport - allowed values: "udp", "tcp", "udp,tcp", "tcp,udp", "tls".
  • hostname - set device hostname, will take effect only if authentication = 1 (IP authenticated device).
  • device_balance_enabled - enable or disable device balance. Allowed values: 1 - enable, 0 - disable.
  • balance - set device balance. Only numeric values.
  • ringing_timeout - max ringing duration in seconds (minimum value is 10).
  • callerid_control_by_dids - 1 - enable, 0 - disable. Only available when the device has DIDs and the CallerID Number field is empty.
  • voicemail_email - device VoiceMail email.
  • description - updates device description field.
  • progressinband - allowed values: "No", "Yes", "Never".
  • emergency_callerid - number for Emergency callerID.
  • emergency_callerid_pool_id - Id of Emergency CallerID Number Pool
  • sendrpid - yes, no (SIP)
  • t38_support - no, yes, fec, redundancy and none (SIP and FAX, same as GUI)
  • сopy_legA_name_to_LegB_number - 0,1 (SIP)
  • total_call_limit - one concurrent Call Limit (Outbound + Inbound). If the request uses call_limit and inbound_call_limit together with total_call_limit, then total_call_limit will be used.
  • valid_cid_number_pool_id - Number Pool with valid CallerIDs.
  • fake_number_pool_id - Random Number from Number Pool.

Note: It should be taken into account that Use random Number when CallerID is invalid is not stored in the database. The option is on when both number_pools (valid_cid_number_pool_id and fake_number_pool_id) are set. If they are not set, both number_pool parameters must be specified the first time to save the values. Other times, the parameters can be specified separately. To disable the option Use random Number when CallerID is invalid it is required to send -1 with parameters valid_cid_number_pool_id or fake_number_pool_id.
Example: valid_cid_number_pool_id=-1.

  • trunk_3cx - Enable 3CX option. This setting is meaningful only if the trunk parameter is set to 1 or 2.



Additional feature

If API setting Allow Resellers to use Admin Localization Rules is enabled:
Reseller is able to set location inherited from Admin. new_location_id should be used as a parameter for location.

Request

HTML POST: http://<SERVER_IP>/billing/api/device_update?u=admin&device=2&new_location_id=7&hash=297dab8c386794b2e947d52affb8f576c643569e



Returns

Success

<page>
  <status>
    <success>Device successfully updated</success>
  </status>
</page>




Errors

  • <error>Incorrect hash</error> - Hash was not correct. Check API_Secret_Key and order or params while concatenating hash_string.
  • <error>Access Denied</error> - access not allowed
  • <error>Device was not found</error> - Device id incorrect or does not exist
  • <error>Location was not found</error> - Location id incorrect or does not exist
  • <error>Password is too short</error> - Password of device is too short
  • <error>CallerID Control By DIDs was not updated because the device has callerID number</error>
  • <error>CallerID Control By DIDs was not updated because the device is not assigned to any DID</error>
  • <error>Wrong format of VoiceMail Email address</error>
  • <error>Emergency CallerID was not updated. Number Pool was not found</error>
  • <error>Emergency CallerID Number Pool was not updated. Emergency CallerID must be present</error>
  • <error>Emergency CallerID Number Pool was not updated. Number Pool was not found</error>



Examples

Change Username/Password authenticated Device to IP authenticated Device:

http://<SERVER_IP>/billing/api/device_update?u=admin&device=51&authentication=1&host=192.168.5.20&port=5060&hash=XXXX

Set empty CallerID:

http://<SERVER_IP>/billing/api/device_update?u=admin&device=2&allow_empty_callerid=1&callerid_number=&hash=XXXX

See also