README

此 API SDK 由 APIMATIC BETA v2.0 自动生成

如何配置

生成的代码可能需要使用您的 API 凭证进行配置。为此，请将凭据和配置值作为控制器构造函数的参数提供

如何构建

生成的代码使用名为 UniRest 的 PHP 库。此库的引用已作为 composer 依赖项添加到生成的 composer.json 文件中。因此，您需要互联网访问来解析此依赖项。

如何使用

要使用此 SDK，请执行以下操作

1. Open a new PHP >= 5.3 project and copy the generated PHP files in the project
   directory.
2. Use composer to install the dependencies. Usually this can be done through a 
   context menu command "Instal (dev)".
3. Import classes from your file in your code where needed for example,
       use MagicTelecomAPILib\Controllers\UsersController;
4. You can now instantiate controllers and call the respective methods.

Magic SDK 示例

1. 获取所有账户

try {
    ...

    // Create an AccountsController for account actions like:
    // create an account, a cart, cart items, checkout cart and so on
    $objController = new AccountsController();

    // Get the list of accounts
    $objResponse = $objController->getAccounts();
    $arrAccount = $objResponse->data->results;
    
    ...
    
} catch (APIException $e) {
    ...
}

您可以使用类似 page、limit 和 filters 的参数获取限制结果。查看 API 文档。以下是一个示例。

try {
    ...

    // Create an AccountsController
    $objController = new AccountsController();

    // Get a list of  accounts using pagination and filters
    // We are going to limit to first five elements with some requirements like firstname and email
    // The filters can be "number, email, contact_number, firstname, lastname"
    $objResponse = $objController->getAccounts(1, 5 "firstname::John|lastname::Doe");
    $arrAccount = $objResponse->data->results;
    
    ...
    
} catch (APIException $e) {
    …
}

2. 创建账户

try {
    ...

    // Create an AccountsController
    $objController = new AccountsController();

    // Create an account "99674698002" with roles "USER"
    $objAccount = new Account("99674698002", array("USER"), "john@example.com", "14079876543", "John", "Smith");
    $objAccountForm = new AccountForm($objAccount);
    
    $objResponse = $objController->createAccount($objAccountForm);
    $strAccount = $objResponse->number;
    
    ...
    
} catch (APIException $e) {
    ...
}

这是一个完整的响应示例。

class stdClass#13 (5) {
  public $number =>
  string(11) "99674698003"
  public $email =>
  string(19) "john@example.com"
  public $contact_number =>
  string(10) "4079876543"
  public $firstname =>
  string(4) "John"
  public $lastname =>
  string(6) "Smith"
}

3. 获取账户

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Get account "99674698003"
    $objResponse = $objController->getAccount("99674698003");
    $objAccount = $objResponse->data;
    
    ...
    
} catch (APIException $e) {
    echo "Can't accomplish this action, exception: [{$e->getMessage()}]";
}

如果账户不存在，您将收到此消息： 无法完成此操作，异常：[资源未找到]

4. 更新账户

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Create the account to update
    $objAccount = new Account("99674698004", array("USER"), "johns_new@test.com", "4079876543", "John", "New");
    $objAccountForm = new AccountForm($objAccount);
    
    // Update account "99674698002"
    $objController->updateAccount("99674698002", $objAccountForm);
    
    // Get the account with the new account value
    $objResponse = $objController->getAccount("99674698004");
    
    ...
    
} catch (APIException $e) {
    echo "Can't accomplish this action, exception: [{$e->getMessage()}]";
}

如果账户不存在，您将收到此消息： 无法完成此操作，异常：[资源未找到]

5. 删除账户

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Delete account "99674698003"
    $objController->deleteAccount("99674698003");
    
    ...
    
} catch (APIException $e) {
    ...
}

6. 获取账户访问令牌

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Get account "997766554" access tokens
    $objResponse = $objController->getAccessTokens("997766554");
    $arrToken = $objResponse->data->results;
    
    // Get the first access token
    if(isset($arrToken[0]))
    {
        $strFirstToken = $arrToken[0]->token;
    }
    
    ...
    
} catch (APIException $e) {
    ...
}

7. 创建账户访问令牌列表

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Create access token 
    $objAccessToken = new Token(true);
    $objForm = new TokenForm($objAccessToken);
    
    // Save the access token for account "997766554"
    $objResponse = $objController->createAccessTokens("997766554", $objForm);
    
    // Get access token Key
    $strKey = $objResponse->token;
    
} catch (APIException $e) {
    ...
}

8. 获取账户访问令牌

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Getting the access token "justatoken" for account "997766554"
    $objResponse = $objController->getAccessToken("997766554", "justatoken");
    $objToken = $objResponse->data;
    
    // Check if the token is active
    if($objToken->is_active) 
    {
        ...
    }
    
    ...
    
} catch (APIException $e) {
    ...
}

9. 更新账户访问令牌

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Fill a access token as not active
    $objAccessToken = new Token('false');
    $objForm = new TokenForm($objAccessToken);
    
    // Updating the access token "b3086c8ef1d4ee975d55b7fbce1e5a4eb893d6d3" for account "997766554" as not active
    $objController->updateAccessToken("997766554", 'b3086c8ef1d4ee975d55b7fbce1e5a4eb893d6d3', $objForm);
    
    ...
    
} catch (APIException $e) {
    ...
}

10. 删除账户访问令牌

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Delete access token with key "b3086c8ef1d4ee975d55b7fbce1e5a4eb893d6d3" for account "997766554"
    $objController->deleteAccessToken("997766554", 'b3086c8ef1d4ee975d55b7fbce1e5a4eb893d6d3');
    
    ...
    
} catch (APIException $e) {
    ...
}

11. 获取账户的调用位置列表

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Get the caller locations list
    $objResponse = $objController->getCallerLocations("997766554");
    $arrCallerLocation = $objResponse->data->results;
    
    // Get the amount of elements
    $intTotal = $objResponse->data->total;
    
    ...
    
} catch (APIException $e) {
    ...
}

12. 为账户创建调用位置

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Create a caller location
    // Take care unit_type must be "unit, suit or apt"
    $objCallerLocation = new CallerLocation(
                                    "John Smith",
                                    "123 Street Name",
                                    "Orlando",
                                    "FL",
                                    32819,
                                    "Suit",
                                    123,
                                    "US"
                                );
    $objForm = new CallerLocationForm($objCallerLocation);
    
    // Save the caller location
    $objResponse = $objController->createCallerLocations("997766554", $objForm);
    
    ...
    
} catch (APIException $e) {
    ...
}

13. 删除账户的调用位置

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Delete caller locations
    $objController->deleteCallerLocations("997766554");
    
    ...
    
} catch (APIException $e) {
    ...
}

14. 通过 Id 获取账户的调用位置

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Get a caller locations with id equal 7 for account "997766554"
    $objResponse = $objController->getCallerLocationById("997766554", 7);
    $objCallerLocation = $objResponse->data;
    
    ...
    
} catch (APIException $e) {
    ...
}

15. 通过 Id 更新账户的调用位置

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Create the update caller location object 
    $objCallerLocation = new CallerLocation(
                                    "John Smith",
                                    "125 Street Name",
                                    "Orlando",
                                    "FL",
                                    32819,
                                    "Apt",
                                    125,
                                    "US"
                                );
    $objForm = new CallerLocationForm($objCallerLocation);
    
    // Update the caller location with id equal 7
    $objController->updateCallerLocationById("997766554", 7, $objForm);
    
    ...
    
} catch (APIException $e) {
    ...
}

16. 通过 Id 删除账户的调用位置

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Delete a caller locations with id equal 7 for account "997766554"
    $objController->deleteCallerLocationById("997766554", 7);
    
    ...
    
} catch (APIException $e) {
    ...
}

17. 获取账户的购物车列表

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();
    
    // Get the car list for account "997766554"
    $objResponse = $objController->getCarts("997766554");
    $arrCart = $objResponse->data->results;
    
    ...
    
} catch (APIException $e) {
    ...
}

18. 为账户创建购物车

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Create Cart for account "997766554"
    $objCart = $objController->createCarts("997766554");

    // Getting cart id
    $intCartId = $objCart->cart_id;
    
    ...
    
} catch (APIException $e) {
    ...
}

19. 删除账户的所有购物车

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Delete carts for account "997766554"
    $objController->deleteCarts("997766554");

    ...
    
} catch (APIException $e) {
    ...
}

20. 通过 Id 获取账户的购物车

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Get the cart for account "997766554" with id equal 3
    $objResponse = $objController->getCart("997766554", 3);
    $objCart = $objResponse->data;

    ...
    
} catch (APIException $e) {
    ...
}

21. 通过 Id 删除账户的购物车

try {
    ...
    
    // Create an AccountsController
    $objController = new AccountsController();

    // Delete a cart for account "997766554" with id equal 6
    $objController->deleteCart("997766554", 6);
    
    ...
    
} catch (APIException $e) {
    ...
}

22. 创建购物车项目

创建干线项目

try {
    ...

    // Create routing object        
    $objRouting = new Routing("load-balanced", 
                                array(new Endpoint("108.188.149.100", "maxChannels=100")), 
                                "Sip_user_1"
                             );

    // Create Trunk Item
    $objTrunk = new TrunkItem(10, "WORLD_WIDE", "108.188.149.121", "sms,fax",  $objRouting);

    // Set the item type ("TRUNK", "LOCATION", "DID")
    $objTrunk->__set("itemType", "TRUNK");
    ...

} catch (APIException $e) {
    ...
}

创建位置项目

try {
    ...

    // Create a caller location
    $objCallerLocation = new CallerLocation(
                                    "John Smith", 
                                    "123 Street Name", 
                                    "Orlando", 
                                    "FL", 
                                    "32819", 
                                    "UNIT", 
                                    "123", 
                                    "US"
                                 );

    // Create Location Item for the trunk 23
    $objLocation = new LocationItem("ORLANDO__407___FL", 3, "sms,fax", "STANDARD", 23, objCallerLocation);

    // Setting the item type
    $objLocation->__set("itemType", "LOCATION");
    ...

} catch (APIException $e) {
    ...
}

创建 DID 项目

try {
    ...

    // Create a caller location
    $objCallerLocation = new CallerLocation(
                                    "John Smith", 
                                    "123 Street Name", 
                                    "Orlando", 
                                    "FL", 
                                    "32819", 
                                    "UNIT", 
                                    "123", 
                                    "US"
                                 );

    // Creating a Did Item for trunk 5
    $objDid = new DidItem("14701234567", 5, "STANDARD", $objCallerLocation);
    $objDid->__set("itemType", "DID");
    ...

} catch (APIException $e) {
    ...
}

创建干线通道项目

try {
    ...
    
    // Create a Trunk Channels Item with 2 additional channels for trunk 5
    $objChannelsItem = new MagicTelecomAPILib\Models\TrunkChannelsItem(2, 5);
    $objChannelsItem->__set("itemType", "TRUNK_CHANNELS");
    ...

} catch (APIException $e) {
    ...
}

23. 将项目添加到购物车

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Create a item like the examples before
    // Could be an TrunkItem, LocationItem or DidItem
    $objTrunk = ...

    //Create an form item
    $objForm = new ItemForm($objTrunk);

    // Add the item to the cart 3
    $response = $objController->createItems("997766554", 3, $objForm);

    // Get Item id from the response
    $intItemId = $response->item_id;
    ...

} catch (APIException $e) {
    ...
}

这是一个完整的响应（干线项目）示例

object(stdClass)#15 (6) {
  ["item_id"]=>
  int(4)
  ["channels"]=>
  int(10)
  ["sip_uri"]=>
  string(15) "108.188.149.125"
  ["attributes"]=>
  string(7) "sms,fax"
  ["_routing"]=>
  string(115) "{"sip_user":"sip_user_1","logic":"load-balanced",
                "endpoints":[{"uri":"108.188.149.100","attrs":"maxChannels=100"}]}"
  ["item_type"]=>
  string(5) "TRUNK"
}

24. 获取购物车项目列表

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Get the list of items from the cart 7 for account "997766554" using filter (page = 1) and (limit = 10) default values
    $objResponse = $objController->getItems("997766554", 7);
    $arrItem = $objResponse->data->results;
    
    // Get the list of items using filter (page = 2) and (limit = 5)
    $objResponse = $objController->getItems("997766554", 7, 2, 5);
    $arrItem = $objResponse->data->results;
    
    ...

} catch (APIException $e) {
    ...
}

25. 删除购物车项目列表

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Delete the list of items from the cart 7 for account "997766554"
    $objController->deleteItems("997766554", 7);
    
    ...

} catch (APIException $e) {
    ...
}

26. 获取购物车项目

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Get the items from the cart 7 for account "997766554" with id equal 9
    $objResponse = $objController->getItem("997766554", 7, 9);
    $objItem = $objResponse->data;
    
    ...

} catch (APIException $e) {
    ...
}

27. 删除购物车项目

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Get the items from the cart 7 for account "997766554" with id equal 9
    $objResponse = $objController->getItem("997766554", 7, 9);
    $objItem = $objResponse->data;
    
    // Check the item type ('TRUNK', 'DID' or 'LOCATION')
    if($objItem->item_type == 'TRUNK')
    {
        // Delete the item with id equal 9 from the cart 7 for account "997766554"
        $objController->deleteItem("997766554", 7, 9);
    }
    
    ...

} catch (APIException $e) {
    ...
}

28. 结账购物车

try {
    ...

    // Create Checkout object with using and external reference
    // "1234567899000dfhdfhdf1234"

    // External reference could be a generated string
    $objCheckout = new Checkout("1234567899000dfhdfhdf1234");

    // Create a checkout form using the checkout object
    $checkoutForm = new CartCheckoutForm($objCheckout);

    // Checkout Cart with id 3 in account "997766554"
    $response  = $objController->createCartCheckout("997766554", 3, $checkoutForm);

    // Getting Order id generated by the cart checkout
    $intOrderId = $response->order_id;
    ...

} catch (APIException $e) {
    ...
}

这是结账购物车的完整响应示例

object(stdClass)#17 (5) {
  ["external_order_reference"]=>
  string(28) "1234567899000dfhdfhdf1234eee"
  ["created"]=>
  string(24) "2016-03-11T21:16:25+0000"

["order_id"]=>
  string(1) "2"
  ["_items"]=>
  array(1) {
    [0]=>
    object(stdClass)#18 (9) {
      ["item_id"]=>
      string(1) "1"
      ["status"]=>
      string(8) "COMPLETE"
      ["item_type"]=>
      string(5) "TRUNK"
      ["channels"]=>
      int(10)
      ["sip_uri"]=>
      string(15) "108.188.149.125"
      ["attributes"]=>
      string(7) "sms,fax"
      ["_routing"]=>
      string(115) "{"sip_user":"sip_user_1","logic":"load-balanced",
                    "endpoints":[{"uri":"108.188.149.100","attrs":"maxChannels=100"}]}"
      ["trunk_handle"]=>
      string(10) "WORLD_WIDE"
      ["trunk_id"]=>
      int(7)
    }
  }
1  ["account_number"]=>
  string(9) "997766554"
}

29. 获取订单状态

try {

    $intOrderId = ...    
    $response = $objController->getOrder("997766554", $intOrderId);
    $strStatus = $response->data->status; 
    
} catch (APIException $e) {
    ...
}

30. 获取账户的 cdr 请求列表

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Get the list of cdr request for account "997766554" using filter (page = 1) and (limit = 10) default values
    $objResponse = $objController->getCdrs("997766554");
    $arrCDR = $objResponse->data->results;
    
    // Get the list of cdr request for account "997766554" using filter (page = 2) and (limit = 5)
    $objResponse = $objController->getCdrs("997766554", 2, 5);
    $arrCDR = $objResponse->data->results;
    
    // Get the list of cdr request for account "997766554" using filter (page = 1) and (limit = 2) 
    // and filter (service_type = "ORIGINATION")
    $objResponse = $objController->getCdrs("997766554", 1, 2, "service_type::ORIGINATION");
    $arrCDR = $objResponse->data->results;
    
    ...

} catch (APIException $e) {
    ...
}

31. 为账户创建 cdr

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Create a cdr for account "997766554" for a service type "TERMINATION"
    // Service type could be "ORIGINATION" or "TERMINATION"
    $objCDR = new Cdrs("TERMINATION", "2016-01-13", "2016-01-13");
    $objForm = new CdrForm($objCDR);
    
    // Save cdr object
    $objCDR = $objController->createCdrs("997766554", $objForm);
    
    ...

} catch (APIException $e) {
    ...
}

32. 删除账户的 cdr 请求列表

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Delete the cdrs list for account "997766554"
    $objController->deleteCdrs("997766554");
    
    ...

} catch (APIException $e) {
    ...
}

33. 通过 id 删除账户的 cdr

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Delete the cdrs for account "997766554" with id 2
    $objController->deleteCdrById("997766554", 2);
    
    ...

} catch (APIException $e) {
    ...
}

34. 获取账户的号码（DID）列表

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Get the Dids list for account "997766554" using filter (page = 1) and (limit = 10) default values
    $objResponse = $objController->getDids("997766554");
    $arrDid = $objResponse->data->results;
    
    // Get the Dids list for account "997766554" using filter (page = 1) and (limit = 5)
    // and filter (region_handle::FL)
    $objResponse = $objController->getDids("997766554", 1, 5, "region_handle::FL");
    $arrDid = $objResponse->data->results;
    
    ...

} catch (APIException $e) {
    ...
}

35. 删除账户的号码（DID）列表

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Delete the Dids list for account "997766554"
    $objController->deleteDids("997766554");
    
    ...

} catch (APIException $e) {
    ...
}

36. 获取账户的电话号码（DID）

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Get the Did for account "997766554" with number "13211234567"
    $objResponse = $objController->getTelephoneNumber("997766554", "13211234567");
    $objDid = $objResponse->data;
    
    ...

} catch (APIException $e) {
    ...
}

37. 更新账户的电话号码（DID）

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Create the routing to be updated
    $objRouting = new RoutingBase(
                               "load-balanced",
                               array(new Endpoint("108.188.149.101", "maxChannels=10"))
                               );
    $objTelephoneNumber = new TelephoneNumber(4, "102.225.231.41", "My new did alias", 5, $objRouting);
    $objTelephoneNumberForm = new TelephoneNumberForm($objTelephoneNumber);
    $objController->updateTelephoneNumber("997766554", "13211234567", $objTelephoneNumberForm);
    
    ...

} catch (APIException $e) {
    ...
}

38. 删除账户的电话号码（DID）

try {

    // Create an AccountsController
    $objController = new AccountsController();

    // Delete Dids for account "997766554" with number "13211234567"
    $objController->deleteTelephoneNumber("997766554", "13211234567");
    
    ...

} catch (APIException $e) {
    ...
}