gowechat/docs/doc.adoc

= GoWechat使用文档
:toc: left
:icons: font

[[install,安装]]
== 安装
  go get github.com/yaotian/gowechat

[[use,使用]]
== 配置

==== 参数
```go
var config = wxcontext.Config{
  //微信公众平台，商户平台，需要填写的信息
	AppID:          "your app id",
	AppSecret:      "your app secret",
	Token:          "your token",
	EncodingAESKey: "your encoding aes key", 

	//以下是 mch商户平台需要的变量
	SslCertFilePath string //证书公钥文件的路径
	SslKeyFilePath  string //证书私钥文件的路径
	SslCertContent  string //公钥证书的内容
	SslKeyContent   string //私钥证书的内容
	MchID           string //商户ID
	MchAPIKey       string //商户平台设置的api key
}

```

=== 微信平台的操作接口

==== 微信公众平台

```go
wc := gowechat.NewWechat(config)
//微信公众平台
mp, err := wc.MpMgr()
if err != nil {
  return
}
```

==== 微信商户平台

```go
wc := gowechat.NewWechat(config)
//微信商户平台
mch , err := wc.MchMgr()
if err != nil {
  return
}

```

== 在框架中使用

=== beego中使用的例子
  ./examples/beego 

=== gin中使用的例子
  ./examples/gin

=== net/http中使用的例子 
  ./examples/http

[[mp,mp]]
== 微信公众平台

=== 1.接口参数
[source,go]
----
var config = wxcontext.Config{
  //微信公众平台，商户平台，需要填写的信息
	AppID:          "your app id",
	AppSecret:      "your app secret",
	Token:          "your token",
	EncodingAESKey: "your encoding aes key", 
}
----

=== 2.接口参数创建接口
[source,go]
----
wc := gowechat.NewWechat(config)
//微信公众平台
mp, err := wc.MpMgr()
if err != nil {
  return
}
----


=== 3.开发消息服务器
将开发的消息服务器（http://your_domain/wx_server）接入到微信公众平台，有几个步骤

1. 接入你的消息服务器时，微信公众号后台，会发信息给你的服务器，来进行验证。所以你的服务器需要知道如何处理验证消息。    
2. 微信公众平台与你的消息服务器之间通过消息通信来进行同步合作。所以你的消息服务器需要知道如何处理消息与如何发送消息。

本接口将复杂的过程（加密，打包，验证等等）封装了，让你只需要关心业务环节。

将以下的代码，加入到你的controller中，接口自动完成上面所说的两个功能，

[IMPORTANT]
你的controller需要能接收GET与POST两种消息

[source,go]
----
wc := gowechat.NewWechat(config)
//微信公众平台
mp, err := wc.MpMgr()
if err != nil {
  return
}

// 传入request和responseWriter
msgHandler := mp.GetMsgHandler(c.Ctx.Request, c.Ctx.ResponseWriter)

//设置接收消息的处理方法
msgHandler.SetHandleMessageFunc(func(msg message.MixMessage) *message.Reply {
  switch msg.Event {
  case message.EventSubscribe:
    return c.handleSubscribe(&msg)
  case message.EventScan:
    return c.handleScan(&msg)
  case message.EventUnsubscribe:
    return c.handleUnsubscribe(&msg)
  case message.EventClick:
    return c.handleClick(&msg)
  case message.EventLocation:
    return c.handleLocation(&msg)
  }

  switch msg.MsgType {
  case message.MsgTypeText:
    //回复消息：演示回复用户发送的消息
    text := message.NewText(msg.Content)
    return &message.Reply{message.MsgTypeText, text}
  case message.MsgTypeImage:
    return c.handleImage(&msg)
  }

	//处理消息接收以及回复
	err = msgHandler.Handle()
	if err != nil {
		beego.Error(err)
	}

})

----

=== 4.消息类型
消息分为以下几种：文本、图片、视频、声音、链接、坐标、图文、文章。

===== 文本消息
[source,go]
----
//回复消息：演示回复用户发送的消息
text := message.NewText("your message want to be sent")
return &message.Reply{message.MsgTypeText, text}
----

===== 图片消息
[source,go]
----
pic := message.NewImage("your_pic_mediaID")
return &message.Reply{message.MsgTypeImage, pic}
----

===== 视频消息
[source,go]
----
video := message.NewVideo("your_mediaID", "your_title", "your_description")
return &message.Reply{message.MsgTypeVideo, video}
----

===== 声音消息
[source,go]
----
voice := message.NewVoice("your_mediaID")
return &message.Reply{message.MsgTypeVoice, voice}
----

===== 链接消息
NOTE: 微信目前不支持回复链接消息

===== 坐标消息
NOTE: 微信目前不支持坐标消息

===== 图文消息
[source,go]
----
news := message.NewNews([]*Article{message.NewArticle("your_title", "your_description", "your_picURL", "your_url")})
return &message.Reply{message.MsgTypeNews, news}
----



=== 模板消息

=== 用户

=== 网页授权

=== JSSDK

=== 二维码

=== 菜单

[[mch,mch]]
== 微信支付(商户平台)

=== 1.接口参数

[source,go]
----
var config = wxcontext.Config{
  //微信公众平台，商户平台，需要填写的信息
	AppID:          "your app id",
	AppSecret:      "your app secret",
	Token:          "your token",
	EncodingAESKey: "your encoding aes key", 

  //------以下是 mch商户平台需要的变量
  //
  //证书公钥，路径，内容要保证只要有一项设置
	SslCertFilePath string //证书公钥文件的路径
	SslCertContent  string //公钥证书的内容

  //私钥，路径，内容要保证只要有一项设置
	SslKeyFilePath  string //证书私钥文件的路径
	SslKeyContent   string //私钥证书的内容

	MchID           string //商户ID
	MchAPIKey       string //商户平台设置的api key
  //------ End 商户平台设置
}
----

=== 2.接口参数创建接口

[source,golang]
----
wc := gowechat.NewWechat(config)
//微信商户平台
mch , err := wc.MchMgr()
if err != nil {
  return
}
----

=== 3.订单参数
[source,golang]
----
type OrderInput struct {
	OpenID      string //trade_type=JSAPI时（即公众号支付），此参数必传，此参数为微信用户在商户对应appid下的唯一标识
	Body        string //String(128)
	OutTradeNum string //String(32) 20150806125346 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|*@ ，且在同一个商户号下唯一。
	TotalFee    int    //分为单位
	IP          string
	NotifyURL   string //异步接收微信支付结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数
	ProductID   string //trade_type=NATIVE时（即扫码支付），此参数必传

	tradeType   string //JSAPI，NATIVE，APP
}
----

=== 4.订单参数创建支付数据

[source,go]
----

//接口参数
wc := gowechat.NewWechat(config)

//商户平台接口
mch , err := wc.MchMgr()
if err != nil {
  return
}

//订单参数
var order pay.OrderInput
order.OpenID = your_openID
order.Body = "购物支付"
order.OutTradeNum = your_trade_num
order.TotalFee = your_fee
order.IP = your_ip
order.NotifyURL = your_notify_URL
----

公众号支付 H5中调用jssdk支付：
[source,go]
----
//公众号支付（jssdk支付数据）
cfg, err := mch.GetPay().GetJsAPIConfig(order)
----

扫码支付：
[source,go]
----
qrcodeImageURL, err := mch.GetPay().GetNativePayQrcodePicURL(order)
----

=== 5.生成支付JS配置

==== 1.WeixinJSBridge:
支付数据，json格式，这些数据可以传递到前端模板中使用
[source,go]
----
//公众号支付（jssdk支付数据）
cfg, err := mch.GetPay().GetJsAPIConfig(order)
json := cfg.ToJSON()
----

前端的JS代码例子
[source,javascript]
----
...
WeixinJSBridge.invoke(
       'getBrandWCPayRequest', {{$json}},
       function(res){
           if(res.err_msg == "get_brand_wcpay_request:ok" ) {
                // 使用以上方式判断前端返回,微信团队郑重提示：
                // res.err_msg将在用户支付成功后返回
                // ok，但并不保证它绝对可靠。
           }
       }
   );
...
----

==== 2.JSSDK:
支付数据，map格式，这些数据可以传递到前端模板中使用
[source,go]
----
//公众号支付（jssdk支付数据）
cfg, err := mch.GetPay().GetJsAPIConfig(order)
mapData := cfg.ToMap()
----

前端的JS代码例子
[source,javascript]
----
wx.chooseWXPay({
    timestamp: {{$timestamp}},
    nonceStr: {{$nonceStr}},
    package: {{$package}},
    signType: {{$signType}},
    paySign: {{$paySign}}, // 支付签名
    success: function (res) {
        // 支付成功后的回调函数
    }
});
----

=== 6.支付通知
微信支付后，微信服务器会将支付结果回调到你的服务器，服务器地址是在订单参数中设置的NotifyURL,为了安全，过来的数据需要检验正确。
[source,go]
----
wc := gowechat.NewWechat(config)
//微信商户平台
mch , err := wc.MchMgr()
if err != nil {
  return
}

//回调的数据检查，例子
req := c.Ctx.Request
data, err := ioutil.ReadAll(req.Body)
if err != nil {
	return
}
isSuccess, err := mch.GetPay().CheckPayNotifyData(data)
if err != nil {
	return
}
//成功后，你自己的处理

----



=== 订单

==== 统一下单

==== 查询订单

该接口提供所有微信支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。

需要调用查询接口的情况：

* 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；
* 调用支付接口后，返回系统错误或未知交易状态情况；
* 调用被扫支付API，返回USERPAYING的状态；
* 调用关单或撤销接口API之前，需确认支付状态；

==== 关闭订单

=== 退款

=== 账单


[[open,open]]
== 开放平台

[[corp,corp]]
== 企业微信

[[mini,mini]]
== 小程序

[[code,code]]
== 贡献代码