Flutter插件enzona的介绍与使用

描述

该库是一个SDK（仍在开发中），旨在简化对ENZONA API的使用。通过使用此SDK，开发者可以专注于其项目的核心业务逻辑。

可用API

以下是当前可用的API列表：

入门指南

在开始使用此SDK之前，建议先查看ENZONA官方文档，了解测试环境（如bulevar/api sandbox）并熟悉API的工作流和功能。

推荐资源：

1. 简单的教程
2. 官方文档和示例

如何添加此SDK到项目中

首先，在项目中添加enzona作为依赖项，具体步骤如下：

对于纯Dart项目：

dart pub add enzona

对于Flutter项目：

flutter pub add enzona

最后执行以下命令以下载依赖项到您的pub-cache：

dart pub get 或 flutter pub get

如何使用此SDK

使用SDK非常简单，只需创建一个实例并初始化即可。

创建SDK实例：

final enzona = Enzona(  
  apiUrl: apiUrl, // ENZONA API的基本URL (https://api.enzona.net 或 https://apisandbox.enzona.net)
  accessTokenUrl: accessTokenUrl, // 可选，OAuth2认证端点URL (https://api.enzona.net/token 或 https://apisandbox.enzona.net/token)，若未指定，默认为 `$apiUrl/token`
  consumerKey: consumerKey, // 商户的Consumer Key
  consumerSecret: consumerSecret, // 商户的Consumer Secret
  scopes: scopes, // 认证Token的范围
  timeout: Duration(seconds: 30), // 可选，设置请求超时时间
  httpClient: HttpClient(), // 可选，用于自定义HTTP客户端配置
);

初始化SDK：

await enzona.init();

此时，您已成功获取访问ENZONA API的权限！

身份验证机制

ENZONA的API使用OAuth2变体进行身份验证（无Token自动刷新）。此SDK实现了OAuth2，并且会自动处理Token的刷新，无需手动干预。

手动刷新Token：

if(enzona.credentials.isExpired) {  
  final credentials = await enzona.refreshCredentials();  
  print(credentials.accessToken);
}

注意事项

为避免属性名、过滤器和值错误，请注意以下类的使用：

• Params：定义所有属性名和过滤器。
• StatusCode：定义交易状态码。
• Order：定义排序类型。

示例代码：

final filters = <String, dynamic> {  
  Params.pageIndex: 0,  
  Params.pageSize: 5,  
  Params.order: Order.desc,  
};  

final response = await enzona.paymentAPI.getPayments(filters: filters);  

if(response.isSuccessful && (response.body?.isNotEmpty ?? false)) {  
  final payment = response.body![0];  
  if(payment.statusCode == StatusCode.confirmada) {  
    print(payment.amount?.total);  
  }  
}

使用PaymentAPI

通过SDK实例，您可以访问各种API，包括支付API。请注意，认证的scope决定了可访问的API范围。

PaymentAPI支持的功能：

示例：列出/筛选支付记录

final response = await enzona.paymentAPI.getPayments(
  pageIndex: 0,
  pageSize: 5,
  merchantUUID: 'test',
  merchantOp: 'test',
  enzonaOp: 'test',
  status: StatusCode.confirmada,
  startDate: DateTime.now().subtract(Duration(days: 7)),
  endDate: DateTime.now(),
  order: Order.desc,
);  

if(response.isSuccessful && (response.body?.isNotEmpty ?? false)) {  
  print('totalCount: ${response.headers[Pagination.totalCountHeader]}');  
  for(var payment in response.body!) {  
    print('id: ${payment.transactionUUID}, statusCode: ${payment.statusCode}');  
  }  
}

示例：获取单个支付详情

final response = await enzona.paymentAPI.getPayment(transactionUUID: '支付ID');  
if(response.isSuccessful) {  
  final payment = response.body;  
  print('id: ${payment?.transactionUUID}, statusCode: ${payment?.statusCode}');  
}  

示例：创建支付

final payment = PaymentRequest(  
  returnUrl: "http://url.to.return.after.payment.confirmation",  
  cancelUrl: "http://url.to.return.after.payment.cancellation",  
  merchantOpId: PaymentRequest.generateRandomMerchantOpId(),  
  currency: "CUP",  
  amount: PaymentAmount(  
    total: 33,  
    details: PaymentAmountDetails(  
      shipping: 1,  
      tax: 0,  
      discount: 2,  
      tip: 4,  
    ),  
  ),  
  items: [  
    PaymentItem(  
      name: "Payment Item 1",  
      description: "Some item description",  
      quantity: 2,  
      price: 15,  
      tax: 0,  
    )  
  ],  
  description: "This is an example payment description",  
);

final response = await enzona.paymentAPI.createPayment(data: payment);  
if(response.isSuccessful) {  
  final createdPayment = response.body;  
  print('id: ${createdPayment?.transactionUUID}, statusCode: ${createdPayment?.statusCode}');  
}  

示例：完成支付

final response = await enzona.paymentAPI.completePayment(transactionUUID: '支付ID');  

if(response.isSuccessful) {  
  final completedPayment = response.body;  
  print('id: ${completedPayment?.transactionUUID}, statusCode: ${completedPayment?.statusCode}');  
} else if(response.error is ErrorResponse &&  
    (response.error as ErrorResponse).code == StatusCode.transaccionNoConfirmada) {  
  final errorResponse = response.error as ErrorResponse;  
  print('错误信息: ${errorResponse.message}. 支付必须先确认才能完成');  
}  

示例：取消支付

final response = await enzona.paymentAPI.cancelPayment(transactionUUID: '支付ID');  

if(response.isSuccessful) {  
  final cancelledPayment = response.body;  
  print('id: ${cancelledPayment?.transactionUUID}, statusCode: ${cancelledPayment?.statusCode}');  
} else {  
  print('发生错误，无法取消支付');  
}  

示例：获取退款列表

final response = await enzona.paymentAPI.getRefunds(
  pageIndex: 0,
  pageSize: 5,
  merchantUUID: 'test',
  transactionUUID: '支付ID',
  status: StatusCode.aceptada,
  startDate: DateTime.now().subtract(Duration(days: 7)),
  endDate: DateTime.now(),
  order: Order.desc,
);  

if(response.isSuccessful && (response.body?.isNotEmpty ?? false)) {  
  print('totalCount: ${response.headers[Pagination.totalCountHeader]}');  
  for(var refund in response.body!) {  
    print('id: ${refund.transactionUUID}, statusCode: ${refund.statusCode}');  
  }  
}

示例：完全退款

final response = await enzona.paymentAPI.refundPayment(transactionUUID: '支付ID');  
if(response.isSuccessful) {  
  final refund = response.body;  
  print('id: ${refund?.transactionUUID}, statusCode: ${refund?.statusCode}');  
}  

示例：部分退款

final refund = Refund(  
  amount: PaymentAmount(  
    total: 5,  
  ),  
  description: 'This is a partial refund'  
);  

final response = await enzona.paymentAPI.refundPayment(transactionUUID: '支付ID', data: refund);

if(response.isSuccessful) {  
  final refund = response.body;  
  print('id: ${refund?.transactionUUID}, statusCode: ${refund?.statusCode}');  
}