。 现在我将根据文档生成完整的 Go SDK 代码工程。 ## 分析 **认证机制**：客户应用使用 `HmacSHA256` 算法，密钥为 `client-secret`，签名数据为 `timestamp + nonce`，结果 Base64 编码。需要生成 timestamp 和 nonce。 **接口列表**： 1. 订单开票（POST） 2. 开票状态查询（POST） 3. 创建付款单据（POST） 4. 支付完成通知（回调，客户提供接口） 5. 支付状态查询（POST） **通知机制**：客户提供接口，平台调用，响应直接返回字符串 `SUCCESS` 或 `FAILED`。 现在开始生成所有文件： --- // File: intelligence_finance_v1/go.mod ```go module intelligence_finance_v1 go 1.21 ``` --- // File: intelligence_finance_v1/errors.go ```go package intelligence_finance_v1 import "fmt" // Error 表示 SDK 返回的错误类型。 type Error struct { // Code 错误码 Code int // Msg 错误信息 Msg string // Err 底层错误 Err error } // Error 实现 error 接口。 func (e *Error) Error() string { if e.Err != nil { return fmt.Sprintf("code=%d, msg=%s, err=%v", e.Code, e.Msg, e.Err) } return fmt.Sprintf("code=%d, msg=%s", e.Code, e.Msg) } // Unwrap 返回底层错误，支持 errors.Is/As。 func (e *Error) Unwrap() error { return e.Err } // NewError 创建一个新的 Error。 func NewError(code int, msg string) *Error { return &Error{Code: code, Msg: msg} } // WrapError 包装底层错误。 func WrapError(code int, msg string, err error) *Error { return &Error{Code: code, Msg: msg, Err: err} } // 预定义错误 var ( // ErrInvalidConfig 配置无效 ErrInvalidConfig = NewError(1001, "invalid config") // ErrNetwork 网络请求失败 ErrNetwork = NewError(1002, "network error") // ErrSignature 签名失败 ErrSignature = NewError(1003, "signature error") // ErrResponse 响应解析失败 ErrResponse = NewError(1004, "response error") // ErrBusiness 业务错误（code != 0） ErrBusiness = NewError(1005, "business error") ) ``` --- // File: intelligence_finance_v1/crypto.go ```go package intelligence_finance_v1 import ( "crypto/hmac" "crypto/rand" "crypto/sha256" "encoding/base64" "fmt" "math/big" "time" ) // GenerateTimestamp 生成秒级时间戳字符串。 func GenerateTimestamp() string { return fmt.Sprintf("%d", time.Now().Unix()) } // GenerateTimestampMillis 生成毫秒级时间戳字符串。 func GenerateTimestampMillis() string { return fmt.Sprintf("%d", time.Now().UnixMilli()) } // GenerateNonce 生成指定长度的加密安全随机字符串。 func GenerateNonce(length int) (string, error) { const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" b := make([]byte, length) for i := range b { num, err := rand.Int(rand.Reader, big.NewInt(int64(len(charset)))) if err != nil { return "", err } b[i] = charset[num.Int64()] } return string(b), nil } // HmacSHA256Base64 使用 HmacSHA256 算法对 data 进行签名，密钥为 secret，结果以 Base64 编码返回。 // // 对应文档认证机制：客户应用使用 client-secret 对 (timestamp + nonce) 进行签名。 func HmacSHA256Base64(secret, data string) string { mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(data)) return base64.StdEncoding.EncodeToString(mac.Sum(nil)) } // BuildSignature 根据文档认证机制生成签名。 // // 签名算法：HmacSHA256 // 密钥：client-secret // 签名数据：x-bfl-signature-timestamp + x-bfl-signature-nonce // 结果编码：Base64 func BuildSignature(clientSecret, timestamp, nonce string) string { return HmacSHA256Base64(clientSecret, timestamp+nonce) } ``` --- // File: intelligence_finance_v1/types.go ```go package intelligence_finance_v1 // 发票类型枚举 const ( InvoiceTypeSpecial = 1 // 专用发票 InvoiceTypeNormal = 2 // 普通发票 InvoiceTypeNormalElectronic = 3 // 普通发票(电子) InvoiceTypeSpecialElec = 4 // 专用发票(电子) InvoiceTypeDigitalSpecial = 8 // 数电专票 InvoiceTypeDigitalNormal = 9 // 数电普票 ) // 开票状态枚举 const ( InvoiceStatusNotInvoiced = 0 // 未开票 InvoiceStatusInvoicing = 1 // 开票中 InvoiceStatusPartialFailed = 2 // 部分失败 InvoiceStatusSuccess = 3 // 开票成功 InvoiceStatusFailed = 4 // 开票失败 InvoiceStatusPartialNotDone = 5 // 部分未开 InvoiceStatusNoDigitalAccount = 6 // 未配置数电账号 InvoiceStatusNoAutoConfig = 7 // 未配置自动开票配置 ) // 支付状态枚举 const ( PaymentStatusSuccess = "SUCCESS" // 支付成功 PaymentStatusFail = "FAIL" // 支付失败 PaymentStatusTerminate = "TERMINATE" // 支付取消 PaymentStatusWaitPay = "WAIT_PAY" // 待支付 PaymentStatusPaying = "PAYING" // 支付中 PaymentStatusPartSuccess = "PART_SUCCESS" // 部分支付成功 PaymentStatusRefund = "REFUND" // 退款 ) // 来源枚举 const ( SourceApproval = "approval" // 审批单 SourceOpenAPI = "openapi" // 开发接口 ) // 账户类型枚举 const ( AccountTypeAlipay = "ALIPAY" // 支付宝 AccountTypeBankCard = "BANKCARD" // 银行卡 AccountTypeCorpBankCard = "CORP_BANK_CARD" // 对公银行卡 AccountTypePersonalBankCard = "PERSONAL_BANK_CARD" // 对私银行卡 ) // CommonResponse 通用响应结构。 type CommonResponse struct { Code int `json:"code"` // 响应码 Msg string `json:"msg"` // 响应信息 Data any `json:"data"` // 响应数据 } // InvoiceRequest 订单开票请求参数。 type InvoiceRequest struct { CompanyCode string `json:"companyCode"` // 开票的企业主体编码 OrderID string `json:"orderId"` // 订单唯一标识 InvoiceType int `json:"invoiceType"` // 发票类型枚举 Products []InvoiceProduct `json:"products"` // 货物/服务明细列表 Remark string `json:"remark,omitempty"` // 订单备注 Purchaser string `json:"purchaser"` // 购方企业名称 TaxNum string `json:"taxnum,omitempty"` // 购方纳税人识别号 PurchaserAddr string `json:"purchaserAddress,omitempty"` // 购方地址 PurchaserTel string `json:"purchaserTel,omitempty"` // 购方电话 BankName string `json:"bankName,omitempty"` // 购方开户行名称 BankAccount string `json:"bankAccount,omitempty"` // 购方银行账号 Phone string `json:"phone,omitempty"` // 收票人手机号 Email string `json:"email,omitempty"` // 收票人邮箱 ApplyPerson string `json:"applyPerson,omitempty"` // 开票申请人名称 Payee string `json:"payee,omitempty"` // 收款人 Reviewer string `json:"reviewer,omitempty"` // 复核人 InvoiceRemark string `json:"invoiceRemark,omitempty"` // 发票备注栏内容 NaturalPerson string `json:"naturalPerson,omitempty"` // 购买方自然人标识 AdditionInfo string `json:"additionInfo,omitempty"` // 附加信息（JSON数组字符串） } // InvoiceProduct 订单开票货物/服务明细项。 type InvoiceProduct struct { ProductName string `json:"productName"` // 货物或服务名称 RevenueCode string `json:"revenueCode"` // 19位税收分类编码 AmountIncludeTax float64 `json:"amountIncludeTax"` // 单条明细含税总金额（元） Specs string `json:"specs,omitempty"` // 规格型号 Unit string `json:"unit,omitempty"` // 计量单位 Quantity float64 `json:"quantity"` // 数量 Discount float64 `json:"discount,omitempty"` // 折扣金额 TaxSign int `json:"taxSign,omitempty"` // 是否含税：0-不含税；1-含税 TaxRate float64 `json:"taxRate,omitempty"` // 税率（小数形式） } // InvoiceResponse 订单开票响应参数。 type InvoiceResponse struct { Status int `json:"status"` // 开票状态 ErrorMsg string `json:"errorMsg"` // 错误信息 DataList []InvoiceData `json:"dataList"` // 发票数据列表 } // InvoiceData 发票数据。 type InvoiceData struct { DeviceCode string `json:"deviceCode"` // 税控设备号 Drawer string `json:"drawer"` // 开票人 Email string `json:"email"` // 邮箱 InvoiceType string `json:"invoiceType"` // 发票类型 IssueType string `json:"issueType"` // 开票类型 ListFlag string `json:"listFlag"` // 清单标识 Mobile string `json:"mobile"` // 手机号 OriginalInvCode string `json:"originalInvCode,omitempty"` // 原蓝票代码 OriginalInvNo string `json:"originalInvNo,omitempty"` // 原蓝票号码 AdditionInfo string `json:"additionInfo,omitempty"` // 附加信息 Payee string `json:"payee"` // 收款人 PurchaserAddress string `json:"purchaserAddress"` // 购方地址 PurchaserBankAccount string `json:"purchaserBankAccount"` // 购方银行账号 PurchaserBankName string `json:"purchaserBankName"` // 购方开户行 PurchaserName string `json:"purchaserName"` // 购方名称 PurchaserTaxNo string `json:"purchaserTaxNo"` // 购方税号 PurchaserTel string `json:"purchaserTel"` // 购方电话 NaturalPerson string `json:"naturalPerson,omitempty"` // 自然人标识 Remark string `json:"remark"` // 备注 Reviewer string `json:"reviewer"` // 复核人 SellerAddress string `json:"sellerAddress,omitempty"` // 销方地址 SellerBankAccount string `json:"sellerBankAccount"` // 销方开户账号 SellerBankName string `json:"sellerBankName"` // 销方开户行 SellerName string `json:"sellerName"` // 销方名称 CheckCode string `json:"checkCode"` // 校验码 CipherText string `json:"cipherText"` // 密码区 DrewDate string `json:"drewDate,omitempty"` // 开票日期 InvoiceCode string `json:"invoiceCode"` // 发票代码 InvoiceNo string `json:"invoiceNo"` // 发票号码 InvoiceStatus string `json:"invoiceStatus"` // 发票状态 LayoutFileURL string `json:"layoutFileUrl,omitempty"` // 电子发票地址 PdfURL string `json:"pdfUrl,omitempty"` // 电子发票PDF地址 OfdURL string `json:"ofdUrl,omitempty"` // 电子发票OFD地址 XmlURL string `json:"xmlUrl,omitempty"` // 电子发票XML地址 TotalExcludeTax string `json:"totalExcludeTax"` // 合计金额（不含税） TotalIncludeTax string `json:"totalIncludeTax"` // 合计金额（含税） TotalTaxAmount string `json:"totalTaxAmount"` // 合计税额 LevyingType string `json:"levyingType"` // 征税方式 Details []InvoiceDetail `json:"details"` // 商品明细列表 } // InvoiceDetail 发票商品明细。 type InvoiceDetail struct { Amount string `json:"amount,omitempty"` // 金额 Quantity string `json:"quantity,omitempty"` // 数量 DeductionAmount string `json:"deductionAmount,omitempty"` // 扣除金额 TaxAmount string `json:"taxAmount,omitempty"` // 税额 ItemTitle string `json:"itemTitle"` // 商品合并显示名称 TaxCode string `json:"taxCode"` // 税收分类编码 ItemType string `json:"itemType"` // 商品行性质 ItemName string `json:"itemName"` // 商品简称 Specs string `json:"specs,omitempty"` // 商品规格型号 TaxFreePolicy string `json:"taxFreePolicy"` // 免税政策 PreferentialPolicy string `json:"preferentialPolicy"` // 优惠政策类型 TaxRate string `json:"taxRate"` // 税率 TaxSign string `json:"taxSign"` // 是否含税 Unit string `json:"unit,omitempty"` // 计量单位 UnitPrice string `json:"unitPrice,omitempty"` // 单价 } // InvoiceStatusQueryRequest 开票状态查询请求参数。 type InvoiceStatusQueryRequest struct { OrderID string `json:"orderId"` // 订单唯一标识 } // InvoiceStatusQueryResponse 开票状态查询响应参数。 type InvoiceStatusQueryResponse struct { Status int `json:"status"` // 开票状态 Message string `json:"message"` // 状态描述 Data []InvoiceData `json:"data"` // 发票详细列表 } // PaymentOrderRequest 创建付款单据请求参数。 type PaymentOrderRequest struct { Code string `json:"code"` // 单据编码 YidaAppType string `json:"yidaAppType,omitempty"` // 宜搭应用类型 EmpAccountUserID string `json:"empAccountUserId,omitempty"` // 员工账户用户ID Department *Department `json:"department,omitempty"` // 部门信息 Usage string `json:"usage,omitempty"` // 用途 PaymentUserID string `json:"paymentUserId,omitempty"` // 付款用户ID Customer *Customer `json:"customer,omitempty"` // 客户信息 PrincipalID string `json:"principalId,omitempty"` // 负责人ID Remark string `json:"remark,omitempty"` // 备注 Supplier *Supplier `json:"supplier,omitempty"` // 供应商信息 Title string `json:"title,omitempty"` // 标题 Project *Project `json:"project,omitempty"` // 项目信息 PaymentUserIDListStr string `json:"paymentUserIdListStr,omitempty"` // 付款用户ID列表字符串 NeedPayment bool `json:"needPayment,omitempty"` // 是否需要付款 PaymentDetailListJSONStr string `json:"paymentDetailListJsonStr,omitempty"` // 付款明细JSON字符串 PaymentDetailList []PaymentDetail `json:"paymentDetailList,omitempty"` // 付款明细列表 Company *Company `json:"company,omitempty"` // 企业主体信息 Amount string `json:"amount,omitempty"` // 金额 RecipientAccountInfo *RecipientAccount `json:"recipientAccountInfo,omitempty"` // 收款账户信息 EnterpriseAccount *EnterpriseAccount `json:"enterpriseAccount,omitempty"` // 企业账号信息 Category []Category `json:"category,omitempty"` // 收支类别信息 UserID string `json:"userId"` // 用户ID OccurDate int64 `json:"occurDate,omitempty"` // 发生日期（时间戳） Product *Product `json:"product,omitempty"` // 商品信息 YidaFormUUID string `json:"yidaFormUuid,omitempty"` // 宜搭表单UUID CanEditPaymentInfo bool `json:"canEditPaymentInfo,omitempty"` // 是否可编辑付款信息 PaymentUserIDList []string `json:"paymentUserIdList,omitempty"` // 付款用户ID列表 YidaProcInsID string `json:"yidaProcInsId,omitempty"` // 宜搭流程实例ID SyncPaymentOrder bool `json:"syncPaymentOrder,omitempty"` // 是否同步付款单据 } // Department 部门信息。 type Department struct { Code string `json:"code,omitempty"` // 部门编码 Name string `json:"name"` // 部门名称 } // Customer 客户信息。 type Customer struct { Code string `json:"code,omitempty"` // 客户编码 Name string `json:"name"` // 客户名称 } // Supplier 供应商信息。 type Supplier struct { Code string `json:"code,omitempty"` // 供应商编码 Name string `json:"name"` // 供应商名称 } // Project 项目信息。 type Project struct { Code string `json:"code,omitempty"` // 项目编码 Name string `json:"name"` // 项目名称 } // Category 收支类别信息。 type Category struct { Code string `json:"code,omitempty"` // 类别编码 Name string `json:"name"` // 类别名称 } // Product 商品信息。 type Product struct { Code string `json:"code,omitempty"` // 商品编码 Name string `json:"name"` // 商品名称 } // Company 企业主体信息。 type Company struct { Code string `json:"code,omitempty"` // 企业编码 Name string `json:"name"` // 企业名称 } // EnterpriseAccount 企业账号信息。 type EnterpriseAccount struct { EnterpriseAccountCode string `json:"enterpriseAccountCode,omitempty"` // 企业账号编码 AccountCategory string `json:"accountCategory"` // 账户类别 AccountType string `json:"accountType,omitempty"` // 账户类型 CardNo string `json:"cardNo,omitempty"` // 卡号 AccountName string `json:"accountName,omitempty"` // 账户名称 OfficialNumber string `json:"officialNumber,omitempty"` // 对公账号 OfficialName string `json:"officialName,omitempty"` // 对公账户名称 Name string `json:"name,omitempty"` // 名称 Code string `json:"code,omitempty"` // 编码 City string `json:"city,omitempty"` // 城市 Province string `json:"province,omitempty"` // 省份 } // RecipientAccount 收款账户信息。 type RecipientAccount struct { AccountCategory string `json:"accountCategory"` // 账户类别 AccountType string `json:"accountType,omitempty"` // 账户类型 CardNo string `json:"cardNo,omitempty"` // 卡号 AccountName string `json:"accountName,omitempty"` // 账户名称 } // PaymentDetail 付款明细。 type PaymentDetail struct { Amount string `json:"amount,omitempty"` // 金额 InvoiceInfo *InvoiceInfo `json:"invoiceInfo,omitempty"` // 发票信息 ProductCode string `json:"productCode,omitempty"` // 商品编码 ProjectCode string `json:"projectCode,omitempty"` // 项目编码 Remark string `json:"remark,omitempty"` // 备注 PrincipalID string `json:"principalId,omitempty"` // 负责人ID Tax string `json:"tax,omitempty"` // 税额 } // InvoiceInfo 付款明细发票信息。 type InvoiceInfo struct { InvoiceNo string `json:"invoiceNo,omitempty"` // 发票号码 InvoiceCode string `json:"invoiceCode,omitempty"` // 发票代码 } // PaymentOrderResponse 创建付款单据响应参数。 type PaymentOrderResponse struct { Code string `json:"code"` // 单据唯一编码 } // PaymentNotifyRequest 支付完成通知数据（接口4）。 type PaymentNotifyRequest struct { Code string `json:"code"` // 单据编码 InstanceID string `json:"instanceId"` // 实例ID CorpID string `json:"corpId"` // 企业ID PaymentStatus string `json:"paymentStatus"` // 支付状态 PaymentTime string `json:"paymentTime"` // 支付时间 UserID string `json:"userId"` // 用户ID FailReason string `json:"failReason,omitempty"` // 失败原因 PayerAccountInfo *PayerAccountInfo `json:"payerAccountInfo,omitempty"` // 付款账户信息 PayeeAccountInfo *PayeeAccountInfo `json:"payeeAccountInfo,omitempty"` // 收款账户信息 RelatedRowNumberList []string `json:"relatedRowNumberList,omitempty"` // 关联行号列表 Source string `json:"source,omitempty"` // 来源 Template string `json:"template,omitempty"` // 模板 Amount string `json:"amount,omitempty"` // 金额 } // PayerAccountInfo 付款账户信息。 type PayerAccountInfo struct { BankOpenDTO *BankOpenDTO `json:"bankOpenDTO,omitempty"` // 银行信息 EnterpriseAccountCode string `json:"enterpriseAccountCode,omitempty"` // 企业账号编码 AccountType string `json:"accountType,omitempty"` // 账户类型 } // PayeeAccountInfo 收款账户信息。 type PayeeAccountInfo struct { BankOpenDTO *BankOpenDTO `json:"bankOpenDTO,omitempty"` // 银行信息 } // BankOpenDTO 银行信息。 type BankOpenDTO struct { BankCode string `json:"bankCode,omitempty"` // 银行编码 BankName string `json:"bankName,omitempty"` // 银行名称 BankBranchCode string `json:"bankBranchCode,omitempty"` // 银行支行编码 BankBranchName string `json:"bankBranchName,omitempty"` // 银行支行名称 AccountName string `json:"accountName,omitempty"` // 账户名称 BankCardNo string `json:"bankCardNo,omitempty"` // 银行卡号 Type string `json:"type,omitempty"` // 账户类型 } // PaymentStatusQueryRequest 支付状态查询请求参数。 type PaymentStatusQueryRequest struct { Code string `json:"code"` // 单据编码 UserID string `json:"userId"` // 用户ID } // PaymentStatusQueryResponse 支付状态查询响应参数（与支付通知数据结构一致）。 type PaymentStatusQueryResponse struct { Code string `json:"code"` // 单据编码 InstanceID string `json:"instanceId"` // 实例ID CorpID string `json:"corpId"` // 企业ID PaymentStatus string `json:"paymentStatus"` // 支付状态 PaymentTime string `json:"paymentTime"` // 支付时间 UserID string `json:"userId"` // 用户ID FailReason string `json:"failReason,omitempty"` // 失败原因 PayerAccountInfo *PayerAccountInfo `json:"payerAccountInfo,omitempty"` // 付款账户信息 PayeeAccountInfo *PayeeAccountInfo `json:"payeeAccountInfo,omitempty"` // 收款账户信息 RelatedRowNumberList []string `json:"relatedRowNumberList,omitempty"` // 关联行号列表 Source string `json:"source,omitempty"` // 来源 Template string `json:"template,omitempty"` // 模板 Amount string `json:"amount,omitempty"` // 金额 } // Notification 通用通知数据（bizType/bizId/data）。 type Notification struct { BizType string `json:"bizType"` // 业务类型 BizID string `json:"bizId"` // 业务ID Data string `json:"data"` // 业务数据 } ``` --- // File: intelligence_finance_v1/client.go ```go package intelligence_finance_v1 import ( "bytes" "context" "encoding/json" "fmt" "io" "net/http" "time" ) // Client 是智能财务业财连接 SDK 的客户端。 type Client struct { // baseURL 平台接口基础地址 baseURL string // tenantID 平台分配的租户唯一标识 tenantID string // clientID 平台分配的应用标识 clientID string // clientSecret 平台分配的密钥 clientSecret string // httpClient HTTP 客户端 httpClient *http.Client // signEnabled 是否启用签名（钉钉AI表格无需配置签名，可关闭） signEnabled bool } // ClientOption 客户端配置选项。 type ClientOption func(*Client) // WithHTTPClient 自定义 HTTP 客户端。 func WithHTTPClient(hc *http.Client) ClientOption { return func(c *Client) { c.httpClient = hc } } // WithSignEnabled 设置是否启用签名（默认启用）。 func WithSignEnabled(enabled bool) ClientOption { return func(c *Client) { c.signEnabled = enabled } } // NewClient 创建一个新的智能财务业财连接客户端。 // // 参数： // - baseURL：平台接口基础地址 // - tenantID：平台分配的租户唯一标识 // - clientID：平台分配的应用标识（钉钉AI表格固定为 dd-ai-table） // - clientSecret：平台分配的密钥 func NewClient(baseURL, tenantID, clientID, clientSecret string, opts ...ClientOption) *Client { c := &Client{ baseURL: baseURL, tenantID: tenantID, clientID: clientID, clientSecret: clientSecret, httpClient: &http.Client{Timeout: 30 * time.Second}, signEnabled: true, } for _, opt := range opts { opt(c) } return c } // doRequest 发送 HTTP 请求并解析响应。 func (c *Client) doRequest(ctx context.Context, path string, reqBody any, respBody any) error { bodyBytes, err := json.Marshal(reqBody) if err != nil { return WrapError(ErrSignature.Code, "marshal request body failed", err) } req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, bytes.NewReader(bodyBytes)) if err != nil { return WrapError(ErrNetwork.Code, "create request failed", err) } // 设置公共请求头 req.Header.Set("Content-Type", "application/json") req.Header.Set("tenant-id", c.tenantID) req.Header.Set("client-id", c.clientID) // 签名（钉钉AI表格无需配置，可通过 WithSignEnabled(false) 关闭） if c.signEnabled { timestamp := GenerateTimestamp() nonce, err := GenerateNonce(16) if err != nil { return WrapError(ErrSignature.Code, "generate nonce failed", err) } req.Header.Set("x-bfl-signature-timestamp", timestamp) req.Header.Set("x-bfl-signature-nonce", nonce) req.Header.Set("x-bfl-signature", BuildSignature(c.clientSecret, timestamp, nonce)) } resp, err := c.httpClient.Do(req) if err != nil { return WrapError(ErrNetwork.Code, "do request failed", err) } defer resp.Body.Close() respBytes, err := io.ReadAll(resp.Body) if err != nil { return WrapError(ErrResponse.Code, "read response body failed", err) } if resp.StatusCode != http.StatusOK { return WrapError(ErrResponse.Code, fmt.Sprintf("unexpected http status: %d", resp.StatusCode), nil) } if err := json.Unmarshal(respBytes, respBody); err != nil { return WrapError(ErrResponse.Code, "unmarshal response body failed", err) } return nil } // doRequestCommon 发送请求并解析通用响应结构（code/msg/data）。 func (c *Client) doRequestCommon(ctx context.Context, path string, reqBody any, data any) error { var common CommonResponse if err := c.doRequest(ctx, path, reqBody, &common); err != nil { return err } if common.Code != 0 { return WrapError(common.Code, common.Msg, nil) } if data != nil && common.Data != nil { // 将 data 重新序列化后反序列化到目标结构 dataBytes, err := json.Marshal(common.Data) if err != nil { return WrapError(ErrResponse.Code, "marshal data failed", err) } if err := json.Unmarshal(dataBytes, data); err != nil { return WrapError(ErrResponse.Code, "unmarshal data failed", err) } } return nil } // CreateInvoice 提交订单开票请求（接口1）。 // // 请求方法：POST // 描述：提交订单开票请求。 func (c *Client) CreateInvoice(ctx context.Context, req *InvoiceRequest) (*InvoiceResponse, error) { var resp InvoiceResponse if err := c.doRequestCommon(ctx, "/invoice/create", req, &resp); err != nil { return nil, err } return &resp, nil } // QueryInvoiceStatus 查询订单开票状态（接口2）。 // // 请求方法：POST // 描述：查询订单开票状态。 func (c *Client) QueryInvoiceStatus(ctx context.Context, req *InvoiceStatusQueryRequest) (*InvoiceStatusQueryResponse, error) { var resp InvoiceStatusQueryResponse if err := c.doRequestCommon(ctx, "/invoice/status", req, &resp); err != nil { return nil, err } return &resp, nil } // CreatePaymentOrder 创建付款单据（接口3）。 // // 请求方法：POST // 描述：创建付款单据。 func (c *Client) CreatePaymentOrder(ctx context.Context, req *PaymentOrderRequest) (*PaymentOrderResponse, error) { var resp PaymentOrderResponse if err := c.doRequestCommon(ctx, "/payment/order/create", req, &resp); err != nil { return nil, err } return &resp, nil } // QueryPaymentStatus 查询支付状态（接口5）。 // // 请求方法：POST // 描述：查询支付状态，响应数据与支付通知一致。 func (c *Client) QueryPaymentStatus(ctx context.Context, req *PaymentStatusQueryRequest) (*PaymentStatusQueryResponse, error) { var resp PaymentStatusQueryResponse if err := c.doRequestCommon(ctx, "/payment/status", req, &resp); err != nil { return nil, err } return &resp, nil } // HandlePaymentNotify 处理支付完成通知（接口4，平台回调客户接口）。 // // 该方法用于客户服务端接收平台回调，解析通知数据并返回响应字符串。 // 响应 BODY 直接返回字符串：SUCCESS 表示成功，FAILED 表示失败。 func HandlePaymentNotify(body []byte) (*PaymentNotifyRequest, error) { var req PaymentNotifyRequest if err := json.Unmarshal(body, &req); err != nil { return nil, WrapError(ErrResponse.Code, "unmarshal payment notify failed", err) } return &req, nil } // HandleNotification 处理通用通知（bizType/bizId/data）。 // // 该方法用于客户服务端接收平台通用通知，解析通知数据。 func HandleNotification(body []byte) (*Notification, error) { var n Notification if err := json.Unmarshal(body, &n); err != nil { return nil, WrapError(ErrResponse.Code, "unmarshal notification failed", err) } return &n, nil } ``` --- // File: intelligence_finance_v1/example_test.go ```go package intelligence_finance_v1 import ( "context" "encoding/json" "fmt" "net/http" "testing" ) // ExampleNewClient 展示如何创建客户端并提交订单开票请求。 func ExampleNewClient() { // 创建客户端 client := NewClient( "https://api.example.com", "your-tenant-id", "dd-ai-table", "your-client-secret", ) // 构建订单开票请求 req := &InvoiceRequest{ OrderID: "ORDER20240101001", InvoiceType: InvoiceTypeDigitalSpecial, // 数电专票 Purchaser: "示例科技有限公司", TaxNum: "91110000XXXXXXXXXX", Email: "finance@example.com", Phone: "13800000000", Products: []InvoiceProduct{ { ProductName: "软件开发服务", RevenueCode: "1090101000000000000", AmountIncludeTax: 11300, Quantity: 1, TaxSign: 1, TaxRate: 0.13, }, }, } resp, err := client.CreateInvoice(context.Background(), req) if err != nil { fmt.Printf("create invoice failed: %v\n", err) return } fmt.Printf("invoice status: %d\n", resp.Status) } // ExampleClient_QueryInvoiceStatus 展示如何查询开票状态。 func ExampleClient_QueryInvoiceStatus() { client := NewClient( "https://api.example.com", "your-tenant-id", "dd-ai-table", "your-client-secret", ) resp, err := client.QueryInvoiceStatus(context.Background(), &InvoiceStatusQueryRequest{ OrderID: "ORDER20240101001", }) if err != nil { fmt.Printf("query invoice status failed: %v\n", err) return } fmt.Printf("status: %d, message: %s\n", resp.Status, resp.Message) } // ExampleClient_CreatePaymentOrder 展示如何创建付款单据。 func ExampleClient_CreatePaymentOrder() { client := NewClient( "https://api.example.com", "your-tenant-id", "dd-ai-table", "your-client-secret", ) req := &PaymentOrderRequest{ Code: "PAY20240101001", UserID: "user-001", Title: "供应商货款", Amount: "11300.00", Supplier: &Supplier{ Name: "示例供应商有限公司", }, Company: &Company{ Name: "示例科技有限公司", }, PaymentDetailList: []PaymentDetail{ { Amount: "11300.00", InvoiceInfo: &InvoiceInfo{ InvoiceNo: "12345678", InvoiceCode: "011002000111", }, }, }, } resp, err := client.CreatePaymentOrder(context.Background(), req) if err != nil { fmt.Printf("create payment order failed: %v\n", err) return } fmt.Printf("payment order code: %s\n", resp.Code) } // ExampleClient_QueryPaymentStatus 展示如何查询支付状态。 func ExampleClient_QueryPaymentStatus() { client := NewClient( "https://api.example.com", "your-tenant-id", "dd-ai-table", "your-client-secret", ) resp, err := client.QueryPaymentStatus(context.Background(), &PaymentStatusQueryRequest{ Code: "PAY20240101001", UserID: "user-001", }) if err != nil { fmt.Printf("query payment status failed: %v\n", err) return } fmt.Printf("payment status: %s\n", resp.PaymentStatus) } // ExampleHandlePaymentNotify 展示如何在客户服务端处理支付完成通知。 func ExampleHandlePaymentNotify() { // 模拟平台回调的请求体 body := []byte(`{ "code": "PAY20240101001", "instanceId": "inst-001", "corpId": "corp-001", "paymentStatus": "SUCCESS", "paymentTime": "2024-01-01 12:00:00", "userId": "user-001", "amount": "11300.00", "source": "openapi" }`) notify, err := HandlePaymentNotify(body) if err != nil { fmt.Printf("handle payment notify failed: %v\n", err) return } // 处理业务逻辑... // 返回响应字符串 if notify.PaymentStatus == PaymentStatusSuccess { fmt.Println("SUCCESS") } else { fmt.Println("FAILED") } } // TestSignature 验证签名算法。 func TestSignature(t *testing.T) { secret := "test-secret" timestamp := "1700000000" nonce := "abc123" sig := BuildSignature(secret, timestamp, nonce) if sig == "" { t.Fatal("signature should not be empty") } t.Logf("signature: %s", sig) } // TestHandlePaymentNotify 测试支付通知解析。 func TestHandlePaymentNotify(t *testing.T) { body := []byte(`{"code":"PAY001","instanceId":"i1","corpId":"c1","paymentStatus":"SUCCESS","paymentTime":"2024-01-01 12:00:00","userId":"u1"}`) n, err := HandlePaymentNotify(body) if err != nil { t.Fatalf("handle payment notify failed: %v", err) } if n.Code != "PAY001" { t.Fatalf("unexpected code: %s", n.Code) } } // TestHandleNotification 测试通用通知解析。 func TestHandleNotification(t *testing.T) { body := []byte(`{"bizType":"invoice","bizId":"ORDER001","data":"{\"status\":3}"}`) n, err := HandleNotification(body) if err != nil { t.Fatalf("handle notification failed: %v", err) } if n.BizType != "invoice" { t.Fatalf("unexpected bizType: %s", n.BizType) } } // TestJSONMarshal 测试请求体 JSON 序列化。 func TestJSONMarshal(t *testing.T) { req := &InvoiceRequest{ OrderID: "ORDER001", InvoiceType: 9, Purchaser: "测试公司", Products: []InvoiceProduct{ {ProductName: "服务", RevenueCode: "1090101000000000000", AmountIncludeTax: 100, Quantity: 1}, }, } b, err := json.Marshal(req) if err != nil { t.Fatalf("marshal failed: %v", err) } t.Logf("request json: %s", string(b)) } // TestHTTPHandler 展示如何将通知处理接入 HTTP 服务。 func TestHTTPHandler(t *testing.T) { handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { var body []byte _, _ = r.Body.Read(body) notify, err := HandlePaymentNotify(body) if err != nil { w.Write([]byte("FAILED")) return } _ = notify w.Write([]byte("SUCCESS")) }) _ = handler } ``` --- === SDK 生成完成 === ## 加密实现 以下是从加密工具获取的完整实现： ### 加密实现 1 { "success": true, "data": "\n### 参数拼接规范\n\n**常见拼接方式**：\n\n1. **字典序排序**：按key字典序排序后拼接 `key=value\u0026key2=value2`\n2. **固定顺序**：按文档指定顺序拼接\n3. **JSON字符串**：整个请求体作为签名串\n\n**代码模板**：\n\n```go\npackage crypto\n\nimport (\n \"fmt\"\n \"sort\"\n \"strings\"\n)\n\n// BuildSignString 方式1：字典序排序拼接\nfunc BuildSignString(params map[string]string) string {\n keys := make([]string, 0, len(params))\n for k, v := range params {\n if v != \"\" \u0026\u0026 k != \"sign\" \u0026\u0026 k != \"signature\" {\n keys = append(keys, k)\n }\n }\n sort.Strings(keys)\n \n var parts []string\n for _, k := range keys {\n parts = append(parts, fmt.Sprintf(\"%s=%s\", k, params[k]))\n }\n return strings.Join(parts, \"\u0026\")\n}\n\n// BuildSignStringOrdered 方式2：固定顺序拼接\nfunc BuildSignStringOrdered(params map[string]string, orderedKeys []string) string {\n var parts []string\n for _, k := range orderedKeys {\n if v, ok := params[k]; ok \u0026\u0026 v != \"\" {\n parts = append(parts, fmt.Sprintf(\"%s=%s\", k, v))\n }\n }\n return strings.Join(parts, \"\u0026\")\n}\n```\n\n**注意事项**：\n- 确认文档指定的排序规则（字典序/固定顺序）\n- 确认空值是否要包含（通常排除空值）\n- 确认是否需要URL编码\n- 注意排除签名字段本身\n", "tool": "param_concat" } ### 加密实现 2 { "success": true, "data": "\n### 时间戳和随机数生成规范\n\n**代码模板**：\n\n```go\npackage crypto\n\nimport (\n \"crypto/rand\"\n \"fmt\"\n \"math/big\"\n \"time\"\n)\n\n// GenerateTimestamp 生成秒级时间戳\nfunc GenerateTimestamp() string {\n return fmt.Sprintf(\"%d\", time.Now().Unix())\n}\n\n// GenerateTimestampMillis 生成毫秒级时间戳\nfunc GenerateTimestampMillis() string {\n return fmt.Sprintf(\"%d\", time.Now().UnixMilli())\n}\n\n// GenerateNonce 生成指定长度的随机字符串（加密安全）\nfunc GenerateNonce(length int) (string, error) {\n const charset = \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789\"\n b := make([]byte, length)\n for i := range b {\n num, err := rand.Int(rand.Reader, big.NewInt(int64(len(charset))))\n if err != nil {\n return \"\", err\n }\n b[i] = charset[num.Int64()]\n }\n return string(b), nil\n}\n```\n\n**注意事项**：\n- 确认文档要求的是秒级还是毫秒级时间戳\n- 确认nonce的长度要求（通常16-32位）\n- 生产环境建议使用加密安全的随机数生成器\n", "tool": "nonce_timestamp" }