WooCommerce APP Helper - Documention - 1

WooCommerce App Helper 是一个WooCommerce 服务端,作用是为基于WooCommerce 的电子商务APP提供一套使用JSON进行交互的接口,本文为部分开发记录以及说明文档。

获取优惠券的端口getcouponbycode

参数数据:

  1. {
  2.     "code""优惠券代码"
  3. }

或者:

  1. {
  2.     "v""优惠券代码"
  3. }

如果优惠券存在,则返回:

  1. {
  2.     "coupon": {
  3.         "id": 18,
  4.         "code""off-12",
  5.         "type""percent_product",
  6.         "created_at""2015-04-23T15:43:31Z",
  7.         "updated_at""2015-07-01T11:02:24Z",
  8.         "amount""12.00",
  9.         "individual_use": false,
  10.         "product_ids": [],
  11.         "exclude_product_ids": [],
  12.         "usage_limit": null,
  13.         "usage_limit_per_user": null,
  14.         "limit_usage_to_x_items": 0,
  15.         "usage_count": 1,
  16.         "expiry_date""2016-09-30T00:00:00Z",
  17.         "enable_free_shipping": true,
  18.         "product_category_ids": [],
  19.         "exclude_product_category_ids": [],
  20.         "exclude_sale_items": false,
  21.         "minimum_amount""0.00",
  22.         "maximum_amount""0.00",
  23.         "customer_emails": [],
  24.         "description"""
  25.     }
  26. }

 

 

 创建订单端口create_order

  1. Array
  2. (
  3.     [order] => Array
  4.         (
  5.             [payment_details] => Array
  6.                 (
  7.                     [method_id] => weixinpay
  8.                     [method_title] => 微信支付
  9.                     [paid] =>
  10.                 )
  11.             [billing_address] => Array
  12.                 (
  13.                     [first_name] => 李
  14.                     [last_name] => 发财
  15.                     [address_1] => 我的地址栏1
  16.                     [address_2] =>
  17.                     [city] => 郑州
  18.                     [state] => CN17
  19.                     [postcode] => 450001
  20.                     [country] => CN
  21.                     [email] => a@example.com
  22.                     [phone] => 5555555
  23.                 )
  24.             [shipping_address] => Array
  25.                 (
  26.                     [first_name] => 李
  27.                     [last_name] => 发财
  28.                     [address_1] => 我的地址栏1
  29.                     [address_2] =>
  30.                     [city] => 郑州
  31.                     [state] => CN17
  32.                     [postcode] => 450001
  33.                     [country] => CN
  34.                 )
  35.             [customer_id] => 1
  36.             [line_items] => Array
  37.                 (
  38.                     [0] => Array
  39.                         (
  40.                             [product_id] => 10
  41.                             [quantity] => 2
  42.                         )
  43.                     [1] => Array
  44.                         (
  45.                             [product_id] => 22
  46.                             [quantity] => 1
  47.                         )
  48.                 )
  49.             [shipping_lines] => Array
  50.                 (
  51.                     [0] => Array
  52.                         (
  53.                             [method_id] => flat_rate
  54.                             [method_title] => Flat Rate
  55.                             [total] => 32
  56.                         )
  57.                 )
  58.         )
  59. )

测试用例1:

商品数据:

  1. $line_items = array(
  2.     array(
  3.         "product_id" => 53,
  4.         "quantity" => 1
  5.     ),
  6.     array(
  7.         "product_id" => 43,
  8.         "quantity" => 1
  9.     ),
  10. );

完整的参数数据(不管是用哪种语言,请确保最终上传的是与此结果格式相同的JSON数据):

  1. $args = array('order'=>array(
  2.                 'payment_details'=>array(
  3.                     'method_id'=>'weixinpay',
  4.                     'method_title'=>'微信支付',
  5.                     'paid'=>false,
  6.                 ),
  7.                 'billing_address'=>array(
  8.                   "first_name" => '当前用户的姓氏',
  9.                   "last_name" => '当前用户的名字',
  10.                   "address_1" => '当前用户的地址',
  11.                   "address_2" => "",
  12.                   "country" => 'CN',
  13.                   "state" => 'CN17',
  14.                   "city" => '郑州',
  15.                   "postcode" => '100010',
  16.                   "email" => 'suifengtec@qq.com',
  17.                   "phone" => '13800138000'
  18.                 ),
  19.                 'shipping_address'=>array(
  20.                   "first_name" => '当前用户的姓氏',
  21.                   "last_name" => '当前用户的名字',
  22.                   "address_1" => '当前用户的地址',
  23.                   "address_2" => "",
  24.                   "country" => 'CN',
  25.                   "state" => 'CN17',
  26.                   "city" => '郑州',
  27.                   "postcode" => '100010',
  28.                   "email" => 'suifengtec@qq.com',
  29.                   "phone" => '13800138000'
  30.                 ),
  31.                 'customer_id'=>'1',
  32.                 'line_items'=>$line_items,
  33.                 'shipping_lines'=>array(array(
  34.                       "method_id" => "free_shipping",
  35.                       "method_title"=> "免费送货",
  36.                       "total" => 0
  37.                 ))
  38.     ));
  39. $args = json_encode($args);

测试用例2:

  1. {
  2.   "order": {
  3.     "payment_details": {
  4.       "method_id""weixinpay",
  5.       "method_title""微信支付",
  6.       "paid"false
  7.     },
  8.     "billing_address": {
  9.       "first_name""李",
  10.       "last_name""发财",
  11.       "address_1""我的地址栏1",
  12.       "address_2""",
  13.       "city""郑州",
  14.       "state""CN17",
  15.       "postcode""450001",
  16.       "country""CN",
  17.       "email""a@example.com",
  18.       "phone""5555555"
  19.     },
  20.     "shipping_address": {
  21.       "first_name""李",
  22.       "last_name""发财",
  23.       "address_1""我的地址栏1",
  24.       "address_2""",
  25.       "city""郑州",
  26.       "state""CN17",
  27.       "postcode""450001",
  28.       "country""CN"
  29.     },
  30.     "customer_id"1,
  31.     "line_items": [
  32.       {
  33.         "product_id"10,
  34.         "quantity"2
  35.       },
  36.       {
  37.         "product_id"22,
  38.         "quantity"1
  39.       }
  40.     ],
  41.     "shipping_lines": [
  42.       {
  43.         "method_id""flat_rate",
  44.         "method_title""Flat Rate",
  45.         "total"32
  46.       }
  47.     ]
  48.   }
  49. }

 

返回的JSON数据解码后为:

  1. {
  2.   order: {
  3.     id: 164
  4.     order_number: 164
  5.     created_at: "2015-07-01T10:06:45Z"
  6.     updated_at: "2015-07-01T10:06:45Z"
  7.     completed_at: "2015-07-01T10:06:45Z"
  8.     status: "pending"
  9.     currency: "CNY"
  10.     total: "122.02"
  11.     subtotal: "90.02"
  12.     total_line_items_quantity: 3
  13.     total_tax: "0.00"
  14.     total_shipping: "32.00"
  15.     cart_tax: "0.00"
  16.     shipping_tax: "0.00"
  17.     total_discount: "0.00"
  18.     shipping_methods: "Flat Rate"
  19.     payment_details: {
  20.         method_id: "weixinpay"
  21.         method_title: "微信支付"
  22.         paid: false
  23.     }
  24.     billing_address: {
  25.       first_name: "李"
  26.       last_name: "发财"
  27.       company: ""
  28.       address_1: "我的地址栏1"
  29.       address_2: ""
  30.       city: "郑州"
  31.       state: "CN17"
  32.       postcode: "450001"
  33.       country: "CN"
  34.       email: "a@example.com"
  35.       phone: "5555555"
  36.     }
  37.     shipping_address: {
  38.       first_name: "John"
  39.       last_name: "Doe"
  40.       company: ""
  41.       address_1: "我的地址栏1"
  42.       address_2: ""
  43.       city: "郑州"
  44.       state: "CN17"
  45.       postcode: "450001"
  46.       country: "CN"
  47.     }
  48.     note: ""
  49.     customer_ip: "115.*.*.*"
  50.     customer_user_agent: ""
  51.     customer_id: 1
  52.     view_order_url: "https://域名/my-account/view-order/164"
  53.     line_items: [2]
  54.     0:  {
  55.       id: 189
  56.       subtotal: "0.02"
  57.       subtotal_tax: "0.00"
  58.       total: "0.02"
  59.       total_tax: "0.00"
  60.       price: "0.01"
  61.       quantity: 2
  62.       tax_class: null
  63.       name: "测试商品1"
  64.       product_id: 10
  65.       sku: "tpp1"
  66.       meta: [0]
  67.     }
  68.     1:  {
  69.       id: 190
  70.       subtotal: "90.00"
  71.       subtotal_tax: "0.00"
  72.       total: "90.00"
  73.       total_tax: "0.00"
  74.       price: "90.00"
  75.       quantity: 1
  76.       tax_class: null
  77.       name: "测试商品0"
  78.       product_id: 22
  79.       sku: ""
  80.       meta: [0]
  81.     }
  82.     shipping_lines: [1]
  83.     0:  {
  84.     id: 191
  85.     method_id: "flat_rate"
  86.     method_title: "Flat Rate"
  87.     total: "32.00"
  88.     }
  89.     tax_lines: [0]
  90.     fee_lines: [0]
  91.     coupon_lines: [0]
  92.     customer: {
  93.       id: 1
  94.       created_at: "2015-04-23T14:28:34Z"
  95.       email: "suifengtec@qq.com"
  96.       first_name: "李"
  97.       last_name: "发财"
  98.       username: "admin01@cwporg"
  99.       role: "administrator"
  100.       last_order_id: "164"
  101.       last_order_date: "2015-07-01T10:06:45Z"
  102.       orders_count: 13
  103.       total_spent: "540.00"
  104.       avatar_url: "#"
  105.       billing_address: {
  106.         first_name: "李"
  107.         last_name: "发财"
  108.         company: "某某公司"
  109.         address_1: "我的地址栏1"
  110.         address_2: ""
  111.         city: "郑州"
  112.         state: "CN17"
  113.         postcode: "450001"
  114.         country: "CN"
  115.         email: "a@example.com"
  116.         phone: "5555555"
  117.       }
  118.       shipping_address: {
  119.         first_name: "李"
  120.         last_name: "发财"
  121.         company: "某某公司"
  122.         address_1: "我的地址栏1"
  123.         address_2: ""
  124.         city: "郑州"
  125.         state: "CN17"
  126.         postcode: "450001"
  127.         country: "CN"
  128.       }
  129.       gender: "male"
  130.     }
  131.   }
  132. }

 

如果想创建包含优惠券的订单,可包含参数:

  1. "coupon_lines"=>
  2. array(array(
  3.     'code'=>'off-12'
  4.     )
  5. )

上述参数与shipping_lines和line_items等平级,示例参数数据:

  1. {
  2.     "order": {
  3.         "payment_details": {
  4.             "method_id""weixinpay",
  5.             "method_title""微信支付",
  6.             "paid"false
  7.         },
  8.         "billing_address": {
  9.             "first_name""当前用户的姓氏",
  10.             "last_name""当前用户的名字",
  11.             "address_1""当前用户的地址",
  12.             "address_2""",
  13.             "country""CN",
  14.             "state""CN17",
  15.             "city""郑州",
  16.             "postcode""100010",
  17.             "email""suifengtec@qq.com",
  18.             "phone""13800138000"
  19.         },
  20.         "shipping_address": {
  21.             "first_name""当前用户的姓氏",
  22.             "last_name""当前用户的名字",
  23.             "address_1""当前用户的地址",
  24.             "address_2""",
  25.             "country""CN",
  26.             "state""CN17",
  27.             "city""郑州",
  28.             "postcode""100010",
  29.             "email""suifengtec@qq.com",
  30.             "phone""13800138000"
  31.         },
  32.         "customer_id""1",
  33.         "line_items": [
  34.             {
  35.                 "product_id"53,
  36.                 "quantity"1
  37.             },
  38.             {
  39.                 "product_id"43,
  40.                 "quantity"1
  41.             }
  42.         ],
  43.         "shipping_lines": [
  44.             {
  45.                 "method_id""free_shipping",
  46.                 "method_title""免费送货",
  47.                 "total"0
  48.             }
  49.         ],
  50.         "coupon_lines": [
  51.             {
  52.                 "code""off-12"
  53.             }
  54.         ]
  55.     }
  56. }

 

更新订单端口 update_order

注意:端点链接中必需加上订单的id,示例: cwp_endpoint=update_order&id=订单ID

参数数据格式:

  1. Array
  2. (
  3.     [order] => Array
  4.         (
  5.             [status] => completed
  6.         )
  7. )

返回数据与新建订单端口一致。

可用的状态:见端口get_order_status的说明

当订单状态被首次修改为下面中的一种时,该订单将被认为已支付:

  1. 'processing','preparing' ,'prepareing','wating','completed'

返回参数中的paid将为true:

  1. 'payment_details'=>array(
  2.     'method_id'=>'支付方式ID',
  3.     'method_title'=>'支付方式名称',
  4.     'paid'=>true,
  5. )

获取某用户订单信息的端点 getcustomerorders / get_customer_order

参数数据:

  1. {"id":"用户ID"}

返回数据为JSON化的该顾客的各个订单的数据。

获取订单状态的端点 get_order_status

参数数据:

  1. {"id":"订单ID"}

返回数据(如果订单存在的话):

  1. {"order":{"id":订单ID,"status":"waiting"}}

其中,订单状态可能的值以及说明如下:

    1. pending : 待付款;
    1. cancelled : 已取消;
    1. refunded : 已退款;
    1. processing : 已支付,待备货;
    1. preparing : 已备货,待发货;
    1. waiting : 已发货,待收货;
  1. completed : 已收货,订单完成;

上面的 preparing、waiting为自定义的订单状态,其它几种为用得上的 WooCommerce 内置的订单状态。

获取运费的端点 getshipping

应ZYC需求定制。

参数数据(可选):

  1. {"id":"位置代码"}

位置代码应与WooCommerce 后台配送类型的SLUG一致,并且这个配送类型应该在/wp-admin/admin.php?page=wc-settings&tab=shipping&section=wc_shipping_flat_rate 已设置运费。

如果没有参数数据( 上传参数数据中的位置代码不是任何一个WooCommerce配置类型的slug,或者没有设置其标准运费),将会默认返回:

  1. {"flat_rate":{"id":"flat_rate","cost":"30","fee":"0"},"custom":{"01001":{"cost":"30","fee":"2"},"01002":{"cost":"35","fee":"3"}}}

如果传递的有参数数据,将按照参数返回,示例如下:

  1. {"01001":{"cost":"30","fee":"2"}}

返回数据中的cost为运费,fee为手工费,在WooCommerce中设置,此外需要注意:app中的配送类型的slug需要与WooCommerce一致。

返回微信access_token的端点getwechataccesstoken

备注:由LY定制。

无需上传参数数据,

返回:

  1. {"wx_access_token": {"access_token": "正确的返回值"}}

参数缺失则返回:

  1. {"errors":[{"code":"601","message":"Please check the Wechat APP ID and the APP key !"}]}

 

说明:

支持 WeixinPay for WooCommerce 插件,如果想从其它插件获取微信access_token,请使用下面这个hook,其中传递的参数$access_token为尝试从服务器存储中找到的微信的access_token:

  1. $access_token = apply_filters('wc_app_helper_get_wechat_access_token',$access_token);

 

返回关于我们页面的端点 about /get_about_page

应ZYC需求定制。

该页面可以在后台设置,设置之后,会在about端点上返回,无需参数,返回数据为标准的WordPress post数据,返回格式为json,详见在线测试的实例。

WooCommerce APP Helper
返回数据的格式示例(中文已转换为可见):

  1. {
  2.     "about": {
  3.         "title""示例页面",
  4.         "content""这是示范页面。页面和博客文章不同,它的位置是固定的,通常会在站点导航栏显示。很多用户都创建一个“关于”页面,向访客介绍自己。例如,个人博客通常有类似这样的介绍:\n\n<blockquote>欢迎!我白天是个邮递员,晚上就是个有抱负的演员。这是我的博客。我住在天朝的帝都,有条叫做杰克的狗。</blockquote>\n\n……公司博客可以这样写:\n\n<blockquote>XYZ Doohickey公司成立于1971年,自从建立以来,我们一直向社会贡献着优秀doohicky。我们的公司总部位于天朝魔都,有着超过两千名员工,对魔都政府税收有着巨大贡献。</blockquote>\n\n您可以访问<a href=\"https://coolwp.org/wp-admin/\">仪表盘</a>,删除本页面,然后添加您自己的内容。祝您使用愉快!",
  5.         "img"false
  6.     }
  7. }

 

返回APP 首页上方幻灯项目组的端点 homesliders / get_home_sliders

应ZYC需求定制。

无需参数,按照设定的幻灯返回,返回格式示例(以转换为可视化的JSON):

  1. {
  2. sliders: [3]
  3.     0:  {
  4.         media: "https://在线测试的域名/wp-content/uploads/2015/04/122.jpg"
  5.         txt: "幻灯文本1"
  6.         url: "https://www.coolwp.com"
  7.     }
  8.     1:  {
  9.         media: "https://在线测试的域名/wp-content/uploads/2015/04/122.jpg"
  10.         txt: "幻灯文本2"
  11.         url: "https://suoling.net"
  12.     }
  13.     2:  {
  14.         media: "https://在线测试的域名/wp-content/uploads/2015/04/23.jpg"
  15.         txt: "幻灯文本3"
  16.         url: "https://www.coolwp.com"
  17.     }
  18. }

 

获取特定产品分类的端点 category / get_category

参数数据

  1. {"id":"产品分类的ID"}

如果上传的参数数据中不含分类ID,就尝试看看链接中是否设置了id,如果有,尝试返回ID为该id的分类的情况。

返回示例:

  1. {
  2. product_category: {
  3.     id: 9
  4.     name: "蒙古国海军特产"
  5.     slug: "mg"
  6.     parent: 0
  7.     description: ""
  8.     count: 2
  9.     img: "https://在线测试的域名/wp-content/uploads/2015/04/7.jpg"
  10.     pid: [2]
  11.         0:  "22"
  12.         1:  "43"
  13.     childids: [2]
  14.         0:  11
  15.         1:  12
  16.     }
  17. }

上述返回中的pid标示该产品分类下的产品ID的数组,数组长度为该分类下产品的数量,childids表示该分类的子分类的ID。

 

申请发送重置用户密码短信的端点 resetpwd / reset_password

应ZYC需求定制。

参数数据

  1. {"to": "手机号","msg": "阿拉伯数字"}

其中,msg为可选参数,如果没有,将有服务器生成6位随机的阿拉伯数字,test表示是否为测试模式,如果为真,就不实际通过移动通信网关发布,直接返回短信发送成功的结果。

短信发送成功后返回的结果:

  1. {"ok":[{"id":用户的ID,"to":手机号码,"message":验证码内容,"timestamp":时间戳}]}

短信发送成功后,用户的密码即为用户的新密码。

动作成功后返回示例:

WooCommerce APP Helper 重置密码成功的返回示例

收到的短信:

WooCommerce APP Helper 重置密码的短信

返回中时间戳1436068835 对应于北京时间 12:00:35,看起来有两分钟的延迟,其实,动作后,就马上收到短信的,延迟不超过1分钟。

短信发送成功的前提是:

1). 这个手机已经与网站用户/顾客相关联;

2). 发送手机短信的网关畅通,发送短信的网关与移动运营商之间的网关畅通,移动运营商并未将发送短信的号码列为垃圾号码,你的手机上的安全程序并未将发送短信的号码列为垃圾号码,所以,请选定一家靠谱的运营商,经过实际测试,Twilio并不理想(最大延迟可达半个小时左右),Clickatell并不理想(最大延时可达半个小时,并且与中国国内的移动运营商之间的关系似乎并不好,先是使用106开头的号码发送,后来发现使用133开头的手机号发送,并且还有漏发现象,漏发依然扣钱)。

短信发送失败则返回:

  1. {"errors":[{"code":"600","message":"Sending failure!"}]}

 

更新用户资料的端点 updateuser / update_user

参数数据分两类:
1).更新用户的

  1. pwd(密码)
  2. nickname(昵称)
  3. email(电邮)
  4. phone(手机号)
  5. gender(性别)

请使用:

  1. {"id": "用户ID","type": "类型","value": "值"}

2). 更新用户的其它资料,请使用(应ZYC于2015.07.01提出的需求增加):

  1. {
  2.     "id"1,
  3.     "type""others",
  4.     "value": {
  5.         "billing_first_name": {
  6.             "v""王狗蛋2"
  7.         },
  8.         "billing_state": {
  9.             "v""CN2"
  10.         },
  11.         "billing_city": {
  12.             "v""朝阳"
  13.         },
  14.         "billing_address_1": {
  15.             "v""郑州市某地址1"
  16.         },
  17.         "billing_phone": {
  18.             "v""13800138001"
  19.         },
  20.         "nickname": {
  21.             "v""昵称1"
  22.         }
  23.     }
  24. }

成功后返回:

  1. {
  2.     "done": [
  3.         {
  4.             "done"true,
  5.             "type""others",
  6.             "value": [
  7.                 "{\"billing_first_name\":{\"v\":\"\\u738b\\u72d7\\u86cb2\"},\"billing_state\":{\"v\":\"CN2\"},\"billing_city\":{\"v\":\"\\u671d\\u9633\"},\"billing_address_1\":{\"v\":\"\\u90d1\\u5dde\\u5e02\\u67d0\\u5730\\u57401\"},\"billing_phone\":{\"v\":\"13800138001\"},\"nickname\":{\"v\":\"\\u6635\\u79f01\"}}"
  8.             ]
  9.         }
  10.     ]
  11. }

用户不存在则返回:

  1. {"errors":[{"code":"600","message":"Account Not Exist!!!"}]}

缺失必要参数则返回:

  1. {"errors":[{"code":"602","message":"Something is wrong !"}]}

或者

  1. {"errors":[{"code":"601","message":"Nothing to do !"}]}

 

发送手机短信的端口 msg

由LY定制,项目开始时采用Twilio,发现Twilio不理想,与LY商议后,按LY指示又用Clickatell,发现还是不理想,最终,与LY商议,决定用国内的“容联-云通讯”。

参数数据:

  1. {"to":"手机号码","msg":"五位阿拉伯数字"}

发送成功返回:

  1. {"ok":[{"phone":"手机号码","message":"五位阿拉伯数字","timestamp":"UNIX时间戳"}]}

返回示例:

WooCommerce APP helper 短信发送返回示例

手机收到短信:

WooCommerce APP Helper 手机短信截图

短信发送端口的时间戳 1436067870对应的是北京时间 11:44:30,两分钟左右,收到短信,由于采用的是免费的测试账户,效果看起来还不错。

发送失败返回:

  1. {"errors":[{"code":"600","message":"Sending failure!"}]}

获取指定slug的分类下的产品 getcatproducts / get_products_by_cat_slug

参数数据

    1. {
    1.     "type""slug",
    1.     "v""分类的slug"
  1. }

如果该分类存在,并且分类下有商品,将会返回该分类下的商品。

获取全部商品的端点 get_products

无需参数,返回全部商品。

无需参数,返回全部推荐商品,如果没有设置推荐商品。

获取特定ID的产品的详情的端点 get_product

参数数据:

    1. {
    1.     "id""产品ID"
  1. }

如果指定ID的产品存在,就返回该产品的详情。

更多端点文档,请戳这里:  https://www.coolwp.com/woocommerce-app-helper-2.html
还有这里: WooCommerce APP Helper V1- Maintenance


error: 错误信息!