Add API endpoint for customer returns

api/app/controllers/spree/api/customer_returns_controller.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    class CustomerReturnsController < Spree::Api::BaseController
+      before_action :load_order
+      around_action :lock_order, only: [:create, :update, :destroy, :cancel]
+
+      rescue_from Spree::Order::InsufficientStock, with: :insufficient_stock_error
+
+      def create
+        authorize! :create, CustomerReturn
+        @customer_return = CustomerReturn.create(customer_return_params)
+        if @customer_return.save
+          respond_with(@customer_return, status: 201, default_template: :show)
+        else
+          invalid_resource!(@customer_return)
+        end
+      end
+
+      def index
+        authorize! :index, CustomerReturn
+
+        @customer_returns = @order.
+          customer_returns.
+          accessible_by(current_ability, :read).
+          ransack(params[:q]).
+          result
+
+        @customer_returns = paginate(@customer_returns)
+
+        respond_with(@customer_returns)
+      end
+
+      def new
+        authorize! :new, CustomerReturn
+      end
+
+      def show
+        authorize! :show, CustomerReturn
+        @customer_return = @order.customer_returns.accessible_by(current_ability, :read).find(params[:id])
+        respond_with(@customer_return)
+      end
+
+      def update
+        authorize! :update, CustomerReturn
+        @customer_return = @order.customer_returns.accessible_by(current_ability, :update).find(params[:id])
+        if @customer_return.update(customer_return_params)
+          respond_with(@customer_return.reload, default_template: :show)
+        else
+          invalid_resource!(@customer_return)
+        end
+      end
+
+      private
+
+      def load_order
+        @order ||= Spree::Order.find_by!(number: order_id)
+        authorize! :read, @order
+      end
+
+      def customer_return_params
+        params.require(:customer_return).permit(permitted_customer_return_attributes)
+      end
+    end
+  end
+end

api/app/helpers/spree/api/api_helpers.rb

@@ -22,6 +22,7 @@ module ApiHelpers
         :state_attributes,
         :adjustment_attributes,
         :inventory_unit_attributes,
+        :customer_return_attributes,
         :return_authorization_attributes,
         :creditcard_attributes,
         :payment_source_attributes,
@@ -117,6 +118,10 @@ def required_fields_for(model)
         :id, :state, :variant_id, :shipment_id
       ]
 
+      @@customer_return_attributes = [
+        :id, :number, :stock_location_id, :created_at, :updated_at
+      ]
+
       @@return_authorization_attributes = [
         :id, :number, :state, :order_id, :memo, :created_at, :updated_at
       ]

api/app/views/spree/api/customer_returns/index.json.jbuilder

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+json.customer_returns(@customer_returns) do |customer_return|
+  json.(customer_return, *customer_return_attributes)
+end
+json.partial! 'spree/api/shared/pagination', pagination: @customer_returns

api/app/views/spree/api/customer_returns/new.json.jbuilder

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+json.attributes([*customer_return_attributes])
+json.required_attributes(required_fields_for(Spree::CustomerReturn))

api/app/views/spree/api/customer_returns/show.json.jbuilder

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+json.(@customer_return, *customer_return_attributes)

api/config/routes.rb

@@ -40,6 +40,8 @@
           put :cancel
         end
       end
+
+      resources :customer_returns, except: :destroy
     end
 
     resources :checkouts, only: [:update], concerns: :order_routes do

api/openapi/solidus-api.oas.yml

@@ -1475,6 +1475,60 @@ paths:
         - api-key: []
       requestBody:
         $ref: '#/components/requestBodies/return-authorization-input'
+  '/orders/{order_id}/customer_returns/{id}':
+    get:
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema: {}
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '404':
+          $ref: '#/components/responses/not-found'
+      summary: Get order customer return
+      description: Gets an orders customer return.
+      operationId: get-order-customer-return
+      tags:
+        - Customer returns
+      security:
+        - api-key: []
+    parameters:
+      - name: order_id
+        in: path
+        required: true
+        description: The order number
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    put:
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/customer-return'
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '404':
+          $ref: '#/components/responses/not-found'
+        '422':
+          $ref: '#/components/responses/unprocessable-entity'
+      summary: Update order customer return
+      description: "Updates an orders customer return."
+      operationId: update-order-customer-return
+      tags:
+        - Customer returns
+      requestBody:
+        $ref: '#/components/requestBodies/customer-return-input'
+      security:
+        - api-key: []
   /orders:
     get:
       responses:
@@ -4908,6 +4962,65 @@ paths:
             type: boolean
       security:
         - api-key: []
+  '/orders/{order_number}/customer_returns':
+    get:
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/pagination-data'
+                  - type: object
+                    properties:
+                      customer_returns:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/customer-return'
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '404':
+          $ref: '#/components/responses/not-found'
+      summary: List order customer returns
+      description: "Lists an order's customer returns."
+      operationId: list-order-customer-returns
+      tags:
+        - Customer returns
+      parameters:
+        - $ref: '#/components/parameters/page'
+        - $ref: '#/components/parameters/per_page'
+      security:
+        - api-key: []
+    parameters:
+      - name: order_number
+        in: path
+        schema:
+          type: string
+        required: true
+    post:
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/customer-return'
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '404':
+          $ref: '#/components/responses/not-found'
+        '422':
+          $ref: '#/components/responses/unprocessable-entity'
+      summary: Create order customer return
+      description: Creates a customer return for an order.
+      operationId: create-order-customer-return
+      tags:
+        - Customer returns
+      requestBody:
+        $ref: '#/components/requestBodies/customer-return-input'
+      security:
+        - api-key: []
 tags:
   - name: Address books
   - name: Addresses
@@ -4929,6 +5042,7 @@ tags:
   - name: Promotions
   - name: Properties
   - name: Return authorizations
+  - name: Customer returns
   - name: Shipments
   - name: States
   - name: Stock items
@@ -5068,6 +5182,11 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/return-authorization-input'
+    customer-return-input:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/customer-return-input'
     option-value-input:
       content:
         application/json:
@@ -6584,3 +6703,47 @@ components:
           type: integer
         stock_item_id:
           type: integer
+    customer-return-input:
+      type: object
+      title: Customer return
+      properties:
+        number:
+          type: string
+        stock_location_id:
+          type: integer
+        return_items_attributes:
+          type: array
+          items:
+            type: object
+            properties:
+              inventory_unit_id:
+                type: integer
+              reception_status_event:
+                type: string
+              return_authorization_id:
+                type: integer
+              exchange_variant_id:
+                type: integer
+              preferred_reimbursement_type_id:
+                type: integer
+              resellable:
+                type: boolean
+            required:
+              - inventory_unit_id
+      required:
+        - stock_location_id
+        - return_items_attributes
+      x-examples:
+        Create New Customer Return:
+          stock_location_id: 1
+          return_items_attributes:
+            - inventory_unit_id: 198
+              reception_status_event: receive
+    customer-return:
+      type: object
+      title: Customer return
+      properties:
+        number:
+          type: string
+        stock_location_id:
+          type: integer