Merge pull request #13 from Kentico/feat/orders_updates

Feat/orders updates

README.md

@@ -1,9 +1,9 @@
 # Xperience by Kentico - KX 13 E-Commerce integration
 
 [![Kentico Labs](https://img.shields.io/badge/Kentico_Labs-grey?labelColor=orange&logo=data:image/svg+xml;base64,PHN2ZyBjbGFzcz0ic3ZnLWljb24iIHN0eWxlPSJ3aWR0aDogMWVtOyBoZWlnaHQ6IDFlbTt2ZXJ0aWNhbC1hbGlnbjogbWlkZGxlO2ZpbGw6IGN1cnJlbnRDb2xvcjtvdmVyZmxvdzogaGlkZGVuOyIgdmlld0JveD0iMCAwIDEwMjQgMTAyNCIgdmVyc2lvbj0iMS4xIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik05NTYuMjg4IDgwNC40OEw2NDAgMjc3LjQ0VjY0aDMyYzE3LjYgMCAzMi0xNC40IDMyLTMycy0xNC40LTMyLTMyLTMyaC0zMjBjLTE3LjYgMC0zMiAxNC40LTMyIDMyczE0LjQgMzIgMzIgMzJIMzg0djIxMy40NEw2Ny43MTIgODA0LjQ4Qy00LjczNiA5MjUuMTg0IDUxLjIgMTAyNCAxOTIgMTAyNGg2NDBjMTQwLjggMCAxOTYuNzM2LTk4Ljc1MiAxMjQuMjg4LTIxOS41MnpNMjQxLjAyNCA2NDBMNDQ4IDI5NS4wNFY2NGgxMjh2MjMxLjA0TDc4Mi45NzYgNjQwSDI0MS4wMjR6IiAgLz48L3N2Zz4=)](https://github.com/Kentico/.github/blob/main/SUPPORT.md#labs-limited-support)
-[![CI: Build and Test](https://github.com/Kentico/xperience-by-kentico-ecommerce/actions/workflows/ci.yml/badge.svg)](https://github.com/Kentico/xperience-by-kentico-ecommerce/actions/workflows/ci.yml)
+[![CI: Build and Test](https://github.com/Kentico/xperience-by-kentico-k13ecommerce/actions/workflows/ci.yml/badge.svg)](https://github.com/Kentico/xperience-by-kentico-k13ecommerce/actions/workflows/ci.yml)
 
-**This integration is currently a Proof of Concept (PoC).  For further details, please refer to the [Support](#support) section and the [KenticoLabs](https://github.com/Kentico/.github/blob/main/SUPPORT.md#labs-limited-support) tag associated with this feature.**
+**This integration is currently a Proof of Concept (PoC).  For further details, please refer to the [Support](#support) section and the [Kentico Labs](https://github.com/Kentico/.github/blob/main/SUPPORT.md#labs-limited-support) tag associated with this feature.**
 
 | Name | Package |
 | ------------- |:-------------:|
@@ -43,8 +43,10 @@ is located in [Dancing Goat XbyK example project](./examples/DancingGoat-K13Ecom
 The integration provides an API with services for implementing the following scenarios:
   - Listing products based on parameters, product categories, prices and inventory
   - Actions with shopping cart, changing currency and order creation
-  - Listing of orders (currently suitable for implementing listing orders in administration)
-    - **Order updates and listing for specific customers are under development**
+  - Listing of orders in administration
+  - Listing of orders for current customer
+  - Update order
+  - Listing site order statuses
   - Listing site cultures and currencies
   - Check [this part of User Guide](./docs/Usage-Guide.md#kx-13-e-commerce-integration-in-xperience-by-kentico) for more specific description 
 
@@ -137,7 +139,7 @@ dotnet add package Kentico.Xperience.StoreApi
 }
 ```
 
-2. Add [Store API services](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/examples/Kentico13_DancingGoatStore/Startup.cs#L130) to application services and configure Swagger
+2. Add [Store API services](https://github.com/Kentico/xperience-by-kentico-k13ecommerce/blob/main/examples/Kentico13_DancingGoatStore/Startup.cs#L130) to application services and configure Swagger
 ```csharp
 // Startup.cs
 
@@ -174,7 +176,7 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment environment)
   }
 }
 ```
-2. Add K13Ecommerce library to the [application services](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/examples/DancingGoat-K13Ecommerce/Program.cs#L61)
+2. Add K13Ecommerce library to the [application services](https://github.com/Kentico/xperience-by-kentico-k13ecommerce/blob/main/examples/DancingGoat-K13Ecommerce/Program.cs#L61)
 ```csharp
 // Program.cs
 

docs/Usage-Guide.md

@@ -77,6 +77,10 @@ via API.
 ### Orders
 - Endpoint `api/store/order/list` for retrieving list of orders for current customer based on request (supports paging)
 - Endpoint `api/store/order/admin/list` for retrieving list of orders (for all customers) based on request (supports paging) to display in XbyK administration (supports paging)
+- Endpoint `api/store/order/detail/{orderID}` for retrieving order detail for current customer. If the order order belongs to another customer, no order is retrieved
+- Endpoint `api/store/order/admin/detail/{orderID}` for retrieving order detail(without verifying if order belongs to current customer)
+- Endpoint `api/store/order/statuses/list` for retrieving all order statuses
+- Endpoint `api/store/order/update` for updating order(update order status, set order payment, etc.)
 
 ### Customers
 - Endpoint `api/store/customer/addresses` for retrieving current customer's addresses
@@ -218,8 +222,12 @@ and to browser cookie (uses `IShoppingCartClientStorage`)
   - Service is used e.g. in [CheckoutService in Dancing Goat example](../examples/DancingGoat-K13Ecommerce/Services/CheckoutService.cs) 
   where customer's addresses are retrieved in cart's second step.
 - `IOrderService`
-  - List of orders - currently suitable for implementing listing orders in administration
-    - **Order updates and listing for specific customers are under development** 
+  - List of orders from all customers(for implementing listing orders in administration)
+  - List of orders for current customer(based on request)
+  - Order detail for current customer(only for orders that belong to the customer)
+  - Order detail for administrator(without verifying if order belongs to current customer)
+  - List of all order statuses
+  - Update order
 - `ISiteStoreService`
   - Use for retrieving site's [list of enabled cultures](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/src/Kentico.Xperience.K13Ecommerce/SiteStore/ISiteStoreService.cs#L13), e.g. for implementation of language selector
   - Use for retrieving site's [list of enabled currencies](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/src/Kentico.Xperience.K13Ecommerce/SiteStore/ISiteStoreService.cs#L18), e.g. for implementation of currency selector
@@ -414,10 +422,11 @@ Here are links for some specific parts of shopping cart:
 - [Discount / Coupon codes](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/examples/DancingGoat-K13Ecommerce/Controllers/KStore/CheckoutController.cs#L163)
 - [Delivery details + shipping](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/examples/DancingGoat-K13Ecommerce/Controllers/KStore/CheckoutController.cs#L194)
 - [Payment](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/examples/DancingGoat-K13Ecommerce/Controllers/KStore/CheckoutController.cs#L330)
-- Payment gateway - Is not part of this PoC solution, you need to implement integration with specific payment gateway. **API for updating orders (and their statuses) is under development**.
+- Payment gateway - Is not part of this PoC solution, you need to implement integration with specific payment gateway.
 - [Order creation](https://github.com/Kentico/xperience-by-kentico-ecommerce/blob/main/examples/DancingGoat-K13Ecommerce/Controllers/KStore/CheckoutController.cs#L315)
 
 
-
-
-
+### How to handle order payments?
+1. Implement your own payment method.
+2. Retrieve all order statuses using `IOrderService` if needed.
+3. Use `UpdateOrder` method of `IOrderService` to update order status and to set `OrderIsPaid` flag according to the payment result.

examples/DancingGoat-K13Ecommerce/Controllers/TestController.cs

@@ -29,5 +29,43 @@ public async Task<IActionResult> TestSetCurrency(string currencyCode)
 
     public async Task<JsonResult> TestOrders([FromServices] IOrderService orderService)
         => Json(await orderService.GetCurrentCustomerOrderList(new OrderListRequest { Page = 1, PageSize = 10, OrderBy = "OrderID DESC" }));
+
+    public async Task<JsonResult> TestOrderStatuses([FromServices] IOrderService orderService)
+    {
+        var statuses = await orderService.GetOrderStatuses();
+        return Json(statuses);
+    }
+
+    public async Task<IActionResult> TestUpdateOrder([FromServices] IOrderService orderService)
+    {
+        var orders =
+            await orderService.GetAdminOrderList(new OrderListRequest { Page = 1, PageSize = 10, OrderBy = "OrderID DESC" });
+
+        var order = orders.Orders.First(o => o.OrderId == 25);
+
+        order.OrderGrandTotal = 999;
+        order.OrderIsPaid = true;
+        var newStatus = (await orderService.GetOrderStatuses()).First(o => o.StatusName == "Completed");
+        order.OrderStatus = newStatus;
+
+        order.OrderBillingAddress.AddressLine1 = "123 Main St";
+        order.OrderBillingAddress.AddressCity = "New York";
+
+        order.OrderShippingAddress.AddressZip = "10001";
+
+        order.OrderShippingOption = new KShippingOption { ShippingOptionId = 2 };
+        order.OrderPaymentOption = new KPaymentOption { PaymentOptionId = 1 };
+
+        order.OrderPaymentResult = new KPaymentResult
+        {
+            PaymentIsCompleted = true,
+            PaymentMethodName = "Test",
+            PaymentStatusName = "Test status"
+        };
+
+        await orderService.UpdateOrder(order);
+
+        return Ok();
+    }
 }
 #endif

src/Kentico.Xperience.K13Ecommerce/Orders/IOrderService.cs

@@ -21,4 +21,31 @@ public interface IOrderService
     /// <param name="request">Request parameters for order listing.</param>
     /// <returns>Paged list of orders.</returns>
     Task<OrderListResponse> GetAdminOrderList(OrderListRequest request);
+
+
+    /// <summary>
+    /// Get order by id for current customer.
+    /// </summary>
+    /// <param name="orderId">Order ID.</param>
+    Task<KOrder> GetCurrentCustomerOrder(int orderId);
+
+
+    /// <summary>
+    /// Get order by ID to display in XbyK administration.
+    /// </summary>
+    /// <param name="orderId">Order ID.</param>
+    Task<KOrder> GetAdminOrder(int orderId);
+
+
+    /// <summary>
+    /// Returns list of enabled order statuses.
+    /// </summary>
+    Task<ICollection<KOrderStatus>> GetOrderStatuses();
+
+
+    /// <summary>
+    /// Updates order.
+    /// </summary>
+    /// <param name="order">Order Dto, send full data for order - retrieve order data first.</param>
+    Task UpdateOrder(KOrder order);
 }

src/Kentico.Xperience.K13Ecommerce/Orders/OrderListRequest.cs

@@ -19,4 +19,9 @@ public class OrderListRequest
     /// Order by.
     /// </summary>
     public required string OrderBy { get; set; }
+
+    /// <summary>
+    /// Customer ID, leave null or zero for all customers.
+    /// </summary>
+    public int? CustomerId { get; set; }
 }

src/Kentico.Xperience.K13Ecommerce/Orders/OrderService.cs

@@ -12,4 +12,20 @@ public async Task<OrderListResponse> GetCurrentCustomerOrderList(OrderListReques
     ///<inheritdoc/>
     public async Task<OrderListResponse> GetAdminOrderList(OrderListRequest request)
         => await storeApiClient.AdminOrderListAsync(request.Page, request.PageSize, request.OrderBy);
+
+
+    /// <inheritdoc/>
+    public async Task<KOrder> GetCurrentCustomerOrder(int orderId) => await storeApiClient.OrderDetailAsync(orderId);
+
+
+    /// <inheritdoc/>
+    public async Task<KOrder> GetAdminOrder(int orderId) => await storeApiClient.AdminOrderDetailAsync(orderId);
+
+
+    /// <inheritdoc/>
+    public async Task<ICollection<KOrderStatus>> GetOrderStatuses() => await storeApiClient.OrderStatusesListAsync();
+
+
+    /// <inheritdoc/>
+    public async Task UpdateOrder(KOrder order) => await storeApiClient.UpdateOrderAsync(order);
 }