README

Shiphero API 的简单 PHP 封装

重要提示：我目前以及之前都不曾与 Shiphero 或其任何专业合作伙伴有任何关联。此封装完全是我的个人作品，除了我自己的认可外，不包含任何其他认可。

安装

安装此包的最简单方法是使用 composer。使用以下命令安装此包：composer require mdeschermeier/shiphero

或者，可以将这些文件下载并存储在任何您认为合适的位置，只要确保 Shiphero.php 和 Shiphero_const.php 保持在同一目录中。

简介

这是一个 Shiphero REST API 的基本封装。虽然可以完全与 Shiphero 界面交互，但请注意，大多数方法都需要多维关联数组，这些数组模拟了最终传递到 cURL 的 JSON 对象的结构。

请务必查看 Shiphero 的 API 文档（http://docs.shipheropublic.apiary.io/#），以了解如何结构化您的数组以及格式化您的数据。

提供了示例，以帮助您理解此封装，但请注意，这不能替代对实际 API 文档的理解。

此封装将处理所有必要的 cURL 函数和 JSON 编码/解码。如果需要修改额外的 cURL 选项，提供了一个方法来满足此需求。此外，一旦通过 Shiphero::setKey($k) 设置了 API 密钥，则封装的各种方法中传递的数组中的 'token' => '<Your API Key>' 元素将不再需要，应从数组中省略。

目录

设置

产品

订单

供应商

履约状态

采购订单

运输

Webhook

联系

设置

Shiphero::setKey($k) - 必需

参数: $k 字符串

此方法设置存储您的 API 密钥的变量。 此方法必须在执行 API 调用之前执行！

Shiphero::setKey('<your API key>');

Shiphero::verifyPeer($b)

参数: $b 布尔值

切换 cURL 请求中的主机/对等方验证。可以根据需要切换。 默认设置为 true

Shiphero::verifyPeer(true); //Enables Host/Peer Verification

    /*==== or ====*/
    
Shiphero::verifyPeer(false); //Disables Host/Peer Verification

Shiphero::setAdditionalCurlOpt($opt, $val)

参数: $opt 常量, $val 混合

如果需要在请求中配置额外的 cURL 选项，可以通过此方法设置。 注意：CURLOPT_POST、CURLOPT_HTTPHEADER 和 CURLOPT_POSTFIELDS 被列入黑名单，将不会被修改！

Shiphero::setAdditionalCurlOpt(CURLOPT_VERBOSE, true);

Shiphero::preserveAdditionalCurlOpt($b)

参数: $b 布尔值

如果您需要 cURL 记住您并发请求的选项，此方法将允许这样做。一旦传递一个 true 值，Shiphero 类将记住您为每个请求设置的 cURL 选项设置，直到此方法传递一个 false 值。 默认设置为 false

Shiphero::setAdditionalCurlOpt(CURLOPT_VERBOSE, true); // - set a custom cURL option for next API request.

Shiphero::preserveAdditionalCurlOpt(true); // - Will remember cURL option settings until turned off

//send some requests
Shiphero::getOrderById(383484); // - cURL options remembered (CURLOPT_VERBOSE = true)
Shiphero::getProducts();        // - cURL options remembered (CURLOPT_VERBOSE = true)

Shiphero::preserveAdditionalCurlOpt(false); //Turn off cURL option rememberance and clear out stored values.

Shiphero::getVendorList(): // - Request ran with default options (CURLOPT_VERBOSE = false)

产品

Shiphero::getProduct($prod = null)

参数: $prod 数组 - 可选

查询 API 以获取产品信息。此方法可以处理单个产品（通过 sku）的检索以及使用默认设置检索 所有 项目。

$prod = array('sku' => 12345);
$response = Shiphero::getProduct($prod) // - Get one item.

$prod = array('page'=>2, 'count'=>150);
$response = Shiphero::getProduct($prod); // - Of all items, return second page, limit 150 items per page.

$response = Shiphero::getProduct(); // - Get all items, no paging (returns the first 50 products).

Shiphero::createProduct($sku, $prod, $type = 'simple')

参数: $sku 字符串, $prod 数组, $type 字符串 - 默认 "simple"

给定一个SKU和一个包含产品信息的数组，该方法将创建一个产品。产品有两种类型：简单和可配置。可配置通常用于创建具有变体的产品。该方法使用$type参数来区分这两种类型。默认为简单。

$sku = 'abc-123';
$product =  array('title'=>'Sample Item Name', 'available_inventory'=>500, 'value'=>5.00, 'price'=>5000.00,
            'images'=> array(
                   array('url' => 'http://made.up.domain.com/super_rad_product.png',
                   'position' => 1),
                   array('url' => 'http://another.made.up.domain.co.uk/more-rad-product.jpg',
                   'position' => 2)
             ));
             
Shiphero::createProduct($sku, $product); // - Create the simple product.

要创建一个可配置产品（具有变体的产品），应遵循相同的$product数组结构。请参阅API文档以获取可以设置的参数完整列表。

Shiphero::addProductToUpdateQueue($prod)

参数： $prod 数组

此方法将产品添加到产品库存更新队列。当与Shiphero::updateInventory()一起使用时，可以更新基本产品信息。请参阅API文档以获取可以设置的参数完整列表。

$product_1 = array('sku'=>'abc-123', 'quantity'=> -2, 'warehouse'=>'Secondary', 'width'=>'2.5');
Shiphero::addProductToUpdateQueue($product_1);

//Product Inventory Update Queue Contains: $product_1

$product_2 = array('sku'=>'def-456', 'new_quantity'=>200);
Shiphero::adddProductToUpdateInventoryQueue($product_2);

//Product Inventory Update Queue Now Contains: $product_1, $product_2

Shiphero::updateInventory()

参数

此方法将更新产品库存更新队列中所有产品的库存。然后，此方法将清空产品库存更新队列。

// Define Product Update Information
$product_1 = array('sku'=>'abc-123', 'quantity'=> -2, 'warehouse'=>'Secondary', 'width'=>'2.5');
$product_2 = array('sku'=>'def-456', 'new_quantity'=>200);

//Add Products to Update Queue
Shiphero::addProductToUpdateQueue($product_1);
Shiphero::addProductToUpdateQueue($product_2);

//Update Products in Queue
Shiphero::updateInventory();

Shiphero::addKitToCreationQueue($kit)

参数： $kit 数组

将套件添加到套件创建队列。与Shiphero::createKits()一起使用。

$kit = array(
            'parent_sku' => 'kit-sku-123',
            'components' => array(
	    			array(
                                 'sku'=>'product_1-sku-123',
                                 'qty'=> 3
                            	),
                            	array(
                                 'sku'=>'product_2-sku-456',
                                 'qty'=>1
                            	)
			    )
            );
     
Shiphero::addKitToCreationQueue($kit);

//Kit Creation Queue Contains: $kit (3 of 'product_1-sku-123, 1 of 'product_2-sku-456')

$another_kit = array(
            'parent_sku' => 'kit-sku-456',
            'components' => array(
	    			array(
                                 'sku'=>'product_1-sku-123',
                                 'qty'=> 10
                            	),
                            	array(
                                 'sku'=>'product_2-sku-456',
                                 'qty'=>3
                            	)
			   )
            );
     
Shiphero::addKitToCreationQueue($another_kit);

//Kit Creation Queue Contains: $kit (3 of 'product_1-sku-123, 1 of 'product_2-sku-456')
//                             $another_kit (10 of 'product_1-sku-123, 3 of 'product_2-sku-456')

Shiphero::createKits()

参数

为套件创建队列中的每个套件创建套件。完成时清空套件创建队列。以下示例从Shiphero::addKitToCreationQueue($kit) 示例继续。

//Kit Creation Queue Contains: $kit (3 of 'product_1-sku-123, 1 of 'product_2-sku-456')
//                             $another_kit (10 of 'product_1-sku-123, 3 of 'product_2-sku-456')
                               
Shiphero::createKits();  // - Kits are now created in Shiphero.

//Kit Creation Queue Contains: Nothing (empty)

Shiphero::addToRemoveKitComponentQueue($kit_sku, $component_skus)

参数： $kit_sku 字符串, $component_skus 数组

将组件或组件列表添加到要从中删除组件的套件。`$kit_sku`是要从其中删除组件的套件的SKU。`$component_skus`是组件SKU的数组。

// Kit 1 (sku 'abc-123') Components (skus): p-123, p-456, p-789
// Kit 2 (sku 'def-456') Components (skus): p-456, p-111, p-222

// - Queue Removal of Item Skus 'p-456' and 'p-789' from Kit 1
Shiphero::addToRemoveKitComponentQueue('abc-123', array('p-456', 'p-789')); 

// - Queue Removal of Item Sku 'p-111' from Kit 2
Shiphero::addToRemoveKitComponentQueue('def-456', array('p-111'));

Shiphero::removeKitComponents()

参数

从指定的套件中删除已排队的项目。完成此方法后，队列被清空。以下示例假定Shiphero::addToRemoveKitComponentQueue($kit_sku, $component_skus) 示例的延续。

// Kit 1 (sku 'abc-123') Components (skus): p-123, p-456, p-789
// Kit 2 (sku 'def-456') Components (skus): p-456, p-111, p-222

//Removal Queue:
//      Kit 1: p-456, p-789
//      Kit 2: p-111

Shiphero::removeKitComponents();

// Kit 1 (sku 'abc-123') Components (skus): p-123
// Kit 2 (sku 'def-456') Components (skus): p-456, p-222

//Removal Queue: 
//      Nothing (empty)

Shiphero::clearKit($sku)

参数： $sku 字符串

此方法根据套件的SKU删除套件中的所有组件。

// Kit 1 (sku 'abc-123') Components (skus): p-123, p-456, p-789

Shiphero::clearKit('abc-123');

// Kit 1 (sku 'abc-123') Components (skus): Nothing (empty)

订单

Shiphero::getOrders($filter, $all_stores=0)

参数： $filter 数组, $all_stores 整数

返回符合$filter数组中设置的参数的所有订单。将$all_stores设置为1将返回与当前Shiphero账户关联的所有订单。将$all_stores设置为0将仅返回与使用中的API密钥关联的商店关联的订单。默认$all_stores值为0。

请参阅Shiphero API文档以获取有关在$filter数组中设置的参数的更多信息。

$filter = array('page'=>1, 'from'=>'2016-9-1', 'to'=>'2016-9-28');

//Return all orders matching filter for current store
Shiphero::getOrders($filter)

//return all orders matching filter for ALL stores
Shiphero::getOrders($filter, 1);

Shiphero::getOrderById($id)

参数： $id 字符串

通过ID返回订单。

//Returns order with ID: 12345
Shiphero::getOrderById('12345');

Shiphero::getOrder($order_num)

参数： $order_num 字符串

通过订单号返回订单。

//Returns order number: 427895-Fri-1
Shiphero::getOrder('427895-Fri-1');

Shiphero::createOrder($order)

参数： $order 数组

此方法创建订单。由于需要传递的数组大小，请参阅Shiphero API文档以获取所有必需和可选参数的详细列表。以下示例显示了数组的结构。

注意：计划为此类添加方法以帮助构建订单，以便使此过程不那么痛苦。

// Define the order
$order = array(
    'email' => 'name@email.com,
    'line_items' => array(
        array(
            'sku' => 'abc-123',
            'name' => 'Item 1', 
            ...
        ),
        array(
            'sku' => 'def-456',
            'name' => 'Item 2',
            ...
        )
    ),
    'note_attributes' => array(
        ...
    ),
    'shipping_address' => array(
        'address1' => '123 Address Ave',
        'address2' => 'Apt 202',
        'city'     => 'Anytown',
        ...
    ),
    'order_id' => '1234567890',
    ...
);

// Create the Order
Shiphero::createOrder($order);

Shiphero::updateOrder($order)

参数： $order 数组

与 Shiphero::createOrder($order) 方法类似，此方法用于更新订单信息。与 Shiphero::createOrder($order) 方法相同，请参考Shiphero API 文档以获取参数的详细列表。

此外，唯一必需的参数是 'order_number' 和您希望更新的参数。

$order = array(
    'order_number' => '1234-123',
    ...
);

Shiphero::updateOrder($order);

Shiphero::createOrderHistory($hist)

参数： $hist 数组

此方法将订单历史添加到指定的订单。请注意，'order_id' 与 'order_number' 不同。

$hist = array(
    'order_id' => 123456,
    'username' => 'user@email.com',
    'information' => 'A note on the order history'
);

Shiphero::createOrderHistory($hist);

供应商

Shiphero::getVendorList()

参数

此方法返回完整的供应商列表。

$vendors = Shiphero::getVendorList();

Shiphero::createVendor($vendor)

参数： $vendor 数组

创建供应商。有关可以设置的完整参数列表，请参阅Shiphero API 文档。

$vendor = array('vendor_name' => 'Wyld Stallyn Guitars', // - vendor_name is the only required parameter.
                'vendor_city' => 'San Dimas',
                'vendor_state' => 'California'
          );
          
Shiphero::createVendor($vendor);

Shiphero::addProductToVendorQueue($data)

参数： $data 数组 将产品添加到供应商队列。当与 Shiphero::addProductsToVendor() 结合使用时，可以将产品添加到供应商。有关必需/可选参数的完整列表，请参阅Shiphero API 文档。

$product1 = array('sku' => 'abc-123', 'vendor_id' => '1234');
Shiphero::addProductToVendorQueue($product1);

// Products in Vendor Queue:
//          $product1:
//              sku: '1234'
//              vendor_id: '1234'
//

$product2 = array('sku' => '5678', 'vendor_id' => '9012', 'price' => 40.99, 'manufacturer_sku' => 'mSku-494');
Shiphero::addProductToVendorQueue($product2);
// Products in Vendor Queue:
//          $product1:
//              sku: '1234'
//              vendor_id: '1234'
//
//          $product2:
//              sku: '5678'
//              vendor_id: '9012'
//              price: 40.99
//              manufacturer_sku: 'msku-494'
//

Shiphero::addProductsToVendors()

参数

从供应商队列中获取产品并将它们添加到供应商。一旦此方法完成，供应商队列将被清空。下面的示例是Shiphero::addProductToVendorQueue($data)示例的延续。

// Products in Vendor Queue:
//          $product1:
//              sku: '1234'
//              vendor_id: '1234'
//
//          $product2:
//              sku: '5678'
//              vendor_id: '9012'
//              price: 40.99
//              manufacturer_sku: 'msku-494'
//

Shiphero::addProductsToVendors();

// Products in Vendor Queue:
//          Nothing (empty)
//

Shiphero::removeProductFromVendor($vendor_id, $sku)

参数： $vendor_id 整数, $sku 字符串

此方法将从供应商中移除产品。

//Vendor ID: 123456
//      contains items (skus):
//          'abc-123'
//          'def-456'
//          'ghi-789'
//

Shiphero::removeProductFromVendor(123456, 'def-456');

//Vendor ID: 123456
//      contains items (skus):
//          'abc-123'
//          'ghi-789'
//

履约状态

Shiphero::createFulfillmentStatus($status)

参数： $status 字符串

创建履约状态。

Shiphero::createFulfillmentStatus('My Custom Status');

Shiphero::deleteFulfillmentStatus($status)

参数： $status 字符串

删除履约状态。

Shiphero::deleteFulfillmentStatus('My Custom Status');

采购订单

Shiphero::addProductToPoQueue($line_item)

参数： $line_item 数组

此方法将行项目添加到采购订单行项目队列。队列（在功能上与其他所有队列类似）将存储采购订单的行项目，直到调用 Shiphero::createPO($po) 方法。

注意： 根据Shiphero API 文档（特别是以 line_items[n] 前缀的参数），必须设置 id 和 sku 参数，以及所有其他必需参数。

	$line_item1 = array('id'=>3456789012, 'sku'=>'abc-123', 'name'=>'Test1',
						'price'=>'25.00', 'quantity'=>30, 'sell_ahead'=>0);

    //PO Line Item Queue Contains: $line_item1

	$line_item2 = array('id'=>2345678901, 'sku'=>'def-456', 'name'=>'Test2',
						'price'=>'0.00', 'quantity'=>40, 'sell_ahead'=>0);
    
    //PO Line Item Queue Contains: $line_item1, $line_item2
    
    $line_item3 = array('id'=>1234567890, 'sku'=>'ghi-789', 'name'=>'Item 3',
						'price'=>'25.00', 'quantity'=>20, 'sell_ahead'=>0);
                        
    //PO Line Item Queue Contains: $line_item1, $line_item2, $line_item3
    

Shiphero::createPO($po)

参数： $po 数组

给定一个包含采购订单基本信息的数组，此方法将使用在 $po 数组和采购订单行项目队列中提供的信息（请参阅 Shiphero::addProductToPoQueue($line_item)）构建采购订单。有关必需/可选参数的完整列表，请参阅Shiphero API 文档，并请注意，其中的 line_items 参数与其完全无关。

完成此方法后，将清空采购订单行项目队列。

注意：虽然 expected_date 参数是可选的，但如果未设置，Shiphero 默认将其设置为 11/30/-0001。在 Shiphero 中，这是一个无效的日期，并且在更新采购订单时，系统将拒绝更新，直到手动更正此日期。因此，此包装器会自动将 expected_date 参数设置为当前日期，如果该参数尚未设置。

以下示例是Shiphero::addProductToPoQueue($line_item)示例的延续。

    ...
    Shiphero::addProductToPoQueue($line_item1);
	Shiphero::addProductToPoQueue($line_item2);
	Shiphero::addProductToPoQueue($line_item3);
    
    //PO Line Item Queue Contains: $line_item1, $line_item2, $line_item3
    
    $po = array('email'=>'example@email.com', 'vendor_name'=>'A. Vendor, Inc', 'created_at'=>'2016-10-03 10:42:25');
    
    Shiphero::createPO($po);
    
    //PO Line Item Queue Contains: Nothing (empty)

Shiphero::getPO($po_id)

参数： $po_id 整数

此方法检索特定采购订单的信息。

    
    $po_1 = Shiphero::getPO(1);     // - Return information from PO ID: 1
    $po_2 = Shiphero::getPO(2);     // - Return information from PO ID: 2
    $po_3 = Shiphero::getPO(456789); // - Return information from PO ID: 456789
    

货运

Shiphero::getShipments($filter)

参数： $filter 数组

此方法根据筛选条件返回一系列货运。请参阅Shiphero API 文档以获取参数的完整列表。

注意：所有返回的集合都是从 Shiphero API 作为分页响应返回的。不要忘记设置您的页面参数！

    
    //Get page 1 of all shipments from Sept. 28, 2016
    $filter = array('page'=>1, 'from'=>'2016-09-28', 'to'=>'2016-09-28');
    $collection1 = Shiphero::getShipments($filter);
    
    //Get page 6 of all shipments from Sept. 28, 2016 to Oct. 2, 2016
    $filter = array('page'=>6, 'from'=>'2016-09-28', 'to'=>'2016-10-2');
    $collection2 = Shiphero::getShipments($filter);
    

Shiphero::createShipment($shipment)

参数： $shipment 数组

此方法创建一个货运。由于输入数组很长，强烈建议查看Shiphero API 文档。

注意：未来计划包括将此过程分解成更小的部分，以便更容易管理。

    $shipment = array('warehouse'=>'Primary', 
                      'profile'=>'default',
                      'shipment'=>array(
                            'shipment_id'=>'123456',
                            'order_id'=>'78901',
                            'carrier'=>'UPS',
                            'shipping_method'=>'UPS GROUND',
                            'tracking_number'=>'abcde1234567890',
                            'cost'=>10.76,
                            'dimensions'=>array(
                                'weight'=>20,
                                'length'=>5,
                                'width'=>8,
                                'height'=>4
                            ),
                            'address'=>array(
                                'name'=>'John Doe',
                                'address1'=>'123 Anywhere St.',
                                'address2'=>'Apt 2',
                                'city'=>'Anytown',
                                'state'=>'CA',
                                'postal_code'=>'12345',
                                'country'=>'US'
                            ),
                            'label'=>array(
                                'pdf'=>'http://example.url.to/pdf/file.pdf',
                                'png'=>array(
                                    'http://example.url.to/png/page1.png',
                                    'http://example.url.to/png/page2.png'
                                )
                            ),
                            'customs_info'=>array(
                                'http://example.url.to/customs/info/page1.png',
                                'http://example.url.to/customs/info/page2.png'
                            )
                        )
                    );
                    
    Shiphero::createShipment($shipment);
    

Webhooks

Shiphero::registerWebhook($hook_info)

参数： $hook_info 数组

此方法将在 Shiphero API 中注册一个 webhook。请注意Shiphero API 文档中的参数 name 和 source，因为这些是预定义值。

注意：Shiphero 中 Capture Payment 和 Return Update 的 webhook 仍在开发中。当它们可用时，此文件将更新以反映这些更改。此外，Shiphero API 需要从创建的 webhook 中获取响应头，否则交易将不会完成！

    //register a webhook to post to URL 'http://my.owned.url.for/webhooks/' every time inventory is updated on my bigcommerce store.
    $hook_info = array('name'=>'Inventory Update', 'url'=>'http://my.owned.url.for/webhooks/', 'source'=>'bigcommerce');
    Shiphero::registerWebhook($hook_info);

Shiphero::getWebhooks()

参数

此方法返回所有当前创建的 webhook 的列表。

    
    $webhook_list = Shiphero::getWebhooks();
    

联系我

请随时通过miked.github@gmail.com与我联系，提出任何问题或关注点。请在主题行中包含“Shiphero API Wrapper”，我将尽快回复。

此外，请使用 GitHub 的问题跟踪器记录任何问题/错误。