spree_api 6.0.0.rc1 → 6.0.0.rc3

data/app/controllers/spree/api/v3/admin/delivery_methods_controller.rb

@@ -5,6 +5,88 @@ module Spree
         class DeliveryMethodsController < ResourceController
           scoped_resource :delivery_methods
 
+          # A single POST/PATCH can ship eligibility rules and carrier service
+          # rows alongside the basics; `DeliveryMethod#rules=` / `#services=`
+          # reconcile to the desired set, so the dashboard saves the whole
+          # sheet in one round-trip.
+          request_params :delivery_method do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Express'
+            body.attribute :admin_name, :string, nullable: true
+            body.attribute :code, :string, nullable: true
+            body.attribute :fulfillment_provider, :string,
+              example: 'manual',
+              description: 'Fulfillment provider shorthand (see the fulfillment providers endpoint), e.g. `manual`.'
+            body.attribute :pickup_point_provider, :string, nullable: true
+            body.attribute :rate_provider, :string,
+              nullable: true,
+              description: 'Rate provider shorthand (see the rate providers endpoint), e.g. `easy_post`. Omit or send null for the built-in provider, which prices through the method\'s calculator.'
+            body.attribute :storefront_visible, :boolean
+            body.attribute :available_to_sellers, :boolean,
+              description: "Marketplace only: whether a seller's packages may be quoted by this method. Off by default, and refused on a method that belongs to a seller."
+            body.attribute :tracking_url, :string, nullable: true
+            body.attribute :estimated_transit_business_days_min, :integer, nullable: true
+            body.attribute :estimated_transit_business_days_max, :integer, nullable: true
+            body.attribute :tax_category_id, :id,
+              nullable: true,
+              description: 'Prefixed tax category ID (`taxcat_...`), or null to clear.'
+            body.attribute :markup_flat, :decimal,
+              nullable: true,
+              description: 'Method-level flat handling fee added on top of provider-quoted rates.'
+            body.attribute :markup_percent, :decimal,
+              nullable: true,
+              description: 'Method-level percentage handling fee added on top of provider-quoted rates. Ignored for calculator-priced methods.'
+            body.attribute :delivery_profile_id, :id,
+              example: 'fp_86Rf07xd4z',
+              description: 'Delivery profile this method belongs to (`fp_...`); defaults to the store default profile.'
+            body.attribute :delivery_origin_group_id, :id,
+              description: "Origin group offering this method (`og_...`); defaults to the zone's group, else the profile's default group."
+            body.attribute :delivery_zone_id, :id,
+              nullable: true,
+              description: "Delivery zone narrowing destinations (`dz_...`), or null for no restriction. Must belong to the method's profile."
+            body.attribute :stock_location_ids, :array, of: :id,
+              description: 'Pickup locations (`sloc_...`); replaces the full set.'
+            body.attribute :calculator, :object,
+              description: "How the method prices a shipment: a type from the calculators endpoint and its preferences, matching that type's `schema`." do |calculator|
+              calculator.attribute :type, :string, example: 'flat_rate'
+              calculator.attribute :preferences, :hash, example: { amount: '12.5' }
+            end
+            # Permitted by `rule_attributes`, which adds the association-backed
+            # config each registered rule kind declares.
+            body.attribute :rules, :array,
+              permit: false,
+              description: 'Eligibility rules. Replaces the full set: omitted rules are removed.' do |rule|
+              rule.attribute :id, :id
+              rule.attribute :type, :string, description: 'A rule kind from the delivery method rule types endpoint.'
+              rule.attribute :active, :boolean
+              rule.attribute :preferences, :hash
+              rule.attribute :product_ids, :array, of: :id,
+                description: 'Products an association-backed rule (`excluded_products_rule`) applies to.'
+            end
+            body.attribute :services, :array,
+              as: 'DeliveryMethodServiceParams',
+              description: 'Carrier service rows: which provider services this method offers. Replaces the full set: omitted rows are removed; no rows means every service the provider returns is offered.' do |service|
+              service.attribute :id, :id, description: 'Prefixed row ID (`dms_...`) when updating an existing row.'
+              service.attribute :carrier, :string,
+                required: true,
+                example: 'UPS',
+                description: "Carrier identifier as the provider's API knows it."
+              service.attribute :service, :string,
+                required: true,
+                example: 'Ground',
+                description: "Service identifier as the provider's API knows it."
+              service.attribute :label, :string,
+                nullable: true,
+                description: 'Display label shown to customers instead of the carrier-derived name.'
+              service.attribute :markup_flat, :decimal,
+                nullable: true,
+                description: 'Overrides the method-level flat markup for this service.'
+              service.attribute :markup_percent, :decimal,
+                nullable: true,
+                description: 'Overrides the method-level percentage markup for this service.'
+              service.attribute :position, :integer
+            end
+          end
+
           # GET /api/v3/admin/delivery_methods/calculators
           # Registered delivery calculator classes with their preference
           # schemas, so admin UIs can render configuration forms.
@@ -15,7 +97,7 @@ module Spree
               {
                 type: calculator_class.api_type,
                 name: calculator_class.description,
-                preference_schema: calculator_class.respond_to?(:serialized_preference_schema) ? calculator_class.serialized_preference_schema : []
+                schema: calculator_class.preference_json_schema
               }
             end
 
@@ -80,9 +162,9 @@ module Spree
           def create
             @resource = model_class.new(assignable_params)
             authorize_resource!(@resource, :create)
-            assign_calculator(@resource)
+            @resource.assign_calculator_attributes(permitted_params[:calculator])
 
-            if @resource.errors.empty? && @resource.save
+            if @resource.save
               render json: serialize_resource(@resource), status: :created
             else
               render_validation_error(@resource.errors)
@@ -90,10 +172,12 @@ module Spree
           end
 
           def update
-            @resource.assign_attributes(assignable_params)
-            assign_calculator(@resource)
+            saved = save_atomically do
+              @resource.assign_attributes(assignable_params)
+              @resource.assign_calculator_attributes(permitted_params[:calculator])
+            end
 
-            if @resource.errors.empty? && @resource.save
+            if saved
               render json: serialize_resource(@resource)
             else
               render_validation_error(@resource.errors)
@@ -118,23 +202,8 @@ module Spree
             Spree.api.admin_delivery_method_serializer
           end
 
-          # A single POST/PATCH can ship eligibility rules and carrier service
-          # rows alongside the basics; `DeliveryMethod#rules=` / `#services=`
-          # reconcile to the desired set, so the dashboard saves the whole
-          # sheet in one round-trip.
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :admin_name, :code, :fulfillment_provider,
-              :pickup_point_provider, :rate_provider, :storefront_visible, :tracking_url,
-              :available_to_sellers,
-              :estimated_transit_business_days_min, :estimated_transit_business_days_max,
-              :tax_category_id, :calculator_type, :markup_flat, :markup_percent,
-              :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id,
-              stock_location_ids: [], calculator_preferences: {},
-              rules: rule_attributes,
-              services: [:id, :carrier, :service, :label, :markup_flat, :markup_percent, :position]
-            )
+            params.permit(*permitted_attributes, rules: rule_attributes)
           end
 
           def rule_attributes
@@ -158,7 +227,7 @@ module Spree
 
           # Resolves prefixed-ID params to records; calculator handled separately.
           def assignable_params
-            attributes = permitted_params.except(:tax_category_id, :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id, :stock_location_ids, :calculator_type, :calculator_preferences)
+            attributes = permitted_params.except(:tax_category_id, :delivery_profile_id, :delivery_origin_group_id, :delivery_zone_id, :stock_location_ids, :calculator)
             if params.key?(:tax_category_id)
               attributes[:tax_category] = params[:tax_category_id].present? ? Spree::TaxCategory.accessible_by(current_ability, :show).find_by_prefix_id!(params[:tax_category_id]) : nil
             end
@@ -200,40 +269,6 @@ module Spree
               where(id: decode_prefixed_ids(ids)).
               pluck(:id)
           end
-
-          def assign_calculator(delivery_method)
-            calculator_type = permitted_params[:calculator_type]
-            preferences = permitted_params[:calculator_preferences]
-
-            if calculator_type.present? && delivery_method.calculator&.class&.api_type != calculator_type
-              selected_calculator_class = Spree::DeliveryMethod.calculators.find do |klass|
-                klass.api_type == calculator_type
-              end
-              unless selected_calculator_class
-                delivery_method.errors.add(:calculator_type, :invalid)
-                return
-              end
-
-              delivery_method.calculator = selected_calculator_class.new
-            end
-
-            return if preferences.blank?
-
-            # A payload may carry preferences without naming a calculator —
-            # editing the amount on a method that already has one, or creating
-            # with the default. The model only builds the default calculator
-            # at validation, so without this the preferences land on nothing
-            # and the amount the merchant typed is silently replaced by a free
-            # rate.
-            delivery_method.ensure_calculator
-            return if delivery_method.calculator.nil?
-
-            preferences.each do |key, value|
-              next unless delivery_method.calculator.has_preference?(key)
-
-              delivery_method.calculator.set_preference(key, value)
-            end
-          end
         end
       end
     end

data/app/controllers/spree/api/v3/admin/delivery_profiles/origin_groups_controller.rb

@@ -10,6 +10,13 @@ module Spree
           class OriginGroupsController < ResourceController
             scoped_resource :settings
 
+            request_params 'DeliveryOriginGroupParams' do |body|
+              body.attribute :name, :string, nullable: true, example: 'EU warehouse'
+              body.attribute :position, :integer
+              body.attribute :stock_location_ids, :array, of: :id,
+                description: 'Prefixed stock location IDs (`sloc_...`); replaces the full set. Empty means every store location.'
+            end
+
             def create
               @resource = scope.new(assignable_params)
               authorize_resource!(@resource, :create)
@@ -46,7 +53,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(*model_additional_permitted_attributes, :name, :position, stock_location_ids: [])
+              params.permit(*permitted_attributes)
             end
 
             def collection_includes

data/app/controllers/spree/api/v3/admin/delivery_profiles_controller.rb

@@ -9,6 +9,18 @@ module Spree
         class DeliveryProfilesController < ResourceController
           scoped_resource :settings
 
+          request_params :delivery_profile do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Oversized'
+            body.attribute :kind, :string,
+              example: 'shipping',
+              description: 'Registered profile kind (`shipping`, `digital`, extension kinds) from the kinds endpoint. Read on create only; defaults to shipping.'
+            body.attribute :default, :boolean,
+              description: 'Promotes this profile to the store default; the previous default is demoted.'
+            body.attribute :position, :integer
+            body.attribute :stock_location_ids, :array, of: :id,
+              description: 'Prefixed stock location IDs (`sloc_...`); replaces the full set. Empty means every store location.'
+          end
+
           # GET /api/v3/admin/delivery_profiles/kinds
           # Registered profile kinds, so admin UIs offer extension-added
           # kinds without hardcoding the built-ins.
@@ -58,7 +70,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :default, :position, :kind, stock_location_ids: [])
+            params.permit(*permitted_attributes)
           end
 
           def collection_includes

data/app/controllers/spree/api/v3/admin/delivery_zones_controller.rb

@@ -8,6 +8,26 @@ module Spree
         class DeliveryZonesController < ResourceController
           scoped_resource :settings
 
+          request_params :delivery_zone do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'US North-East'
+            body.attribute :description, :string, nullable: true
+            body.attribute :delivery_profile_id, :id,
+              description: 'Delivery profile this zone belongs to (`fp_...`); defaults to the store default profile.'
+            body.attribute :delivery_origin_group_id, :id,
+              description: 'Origin group this zone belongs to (`og_...`).'
+            body.attribute :members, :array,
+              as: 'DeliveryZoneMemberParams',
+              description: "Replaces the zone's full member set atomically." do |member|
+              member.attribute :member_type, :string, required: true, choices: Spree::DeliveryZoneMember::MEMBER_TYPES
+              member.attribute :country_code, :country, example: 'US'
+              member.attribute :state_code, :string,
+                description: 'A subdivision code or name. Without `country_code` the country is inferred when only one country matches.'
+              member.attribute :postal_code_prefix, :string
+              member.attribute :postal_code_from, :string
+              member.attribute :postal_code_to, :string
+            end
+          end
+
           def create
             @resource = model_class.new(zone_params)
             authorize_resource!(@resource, :create)
@@ -50,11 +70,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :name, :description, :delivery_profile_id, :delivery_origin_group_id,
-              members: [:member_type, :country_code, :state_code, :postal_code_prefix, :postal_code_from, :postal_code_to]
-            )
+            params.permit(*permitted_attributes)
           end
 
           def collection_includes

data/app/controllers/spree/api/v3/admin/email_templates/drafts_controller.rb

@@ -8,6 +8,19 @@ module Spree
           class DraftsController < Admin::BaseController
             include Spree::Api::V3::Admin::EmailTemplateLookup
 
+            request_params 'EmailTemplateDraftParams' do |body|
+              body.include_attributes Spree::Api::V3::Admin::EmailTemplateLanguageRequestSchema
+              body.attribute :subject, :string, nullable: true, example: 'Your order {{ order.number }} is confirmed'
+              body.attribute :body, :string,
+                example: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>'
+              body.attribute :lock_version, :integer,
+                nullable: true,
+                example: 0,
+                description: 'The `lock_version` the draft was loaded with, or null when there was no draft; a save from an older copy is refused with 409. Omit it to save without checking.'
+              body.attribute :rebase, :boolean,
+                description: "Marks the draft as based on Spree's current default, after reviewing what changed in it."
+            end
+
             # PUT /api/v3/admin/email_templates/:email_template_id/draft
             #
             # Send the `lock_version` the draft was loaded with: a save made from
@@ -18,7 +31,7 @@ module Spree
 
               result = Spree.email_template_save_draft_workflow.call(
                 store: current_store, key: email_template.key, locale: language, actor: current_actor,
-                attributes: params.permit(:subject, :body, :lock_version, :rebase).to_h.symbolize_keys
+                attributes: params.permit(*declared_permitted_attributes).to_h.symbolize_keys
               )
               render_email_template_result(result)
             end

data/app/controllers/spree/api/v3/admin/email_templates/previews_controller.rb

@@ -6,6 +6,10 @@ module Spree
           class PreviewsController < Admin::BaseController
             include Spree::Api::V3::Admin::EmailTemplateLookup
 
+            request_params 'EmailTemplatePreviewParams' do |body|
+              body.include_attributes Spree::Api::V3::Admin::EmailTemplatePreviewRequestSchema
+            end
+
             before_action :authorize_sample_data!
 
             # POST /api/v3/admin/email_templates/:email_template_id/preview

data/app/controllers/spree/api/v3/admin/email_templates/publications_controller.rb

@@ -6,6 +6,13 @@ module Spree
           class PublicationsController < Admin::BaseController
             include Spree::Api::V3::Admin::EmailTemplateLookup
 
+            request_params 'EmailTemplateVersionParams' do |body|
+              body.include_attributes Spree::Api::V3::Admin::EmailTemplateLanguageRequestSchema
+              body.attribute :lock_version, :integer,
+                permit: false,
+                description: "The draft's `lock_version` as reviewed. A draft saved since is refused with 409."
+            end
+
             before_action :authorize_sample_data!
 
             # POST /api/v3/admin/email_templates/:email_template_id/publication

data/app/controllers/spree/api/v3/admin/email_templates/restorations_controller.rb

@@ -6,6 +6,14 @@ module Spree
           class RestorationsController < Admin::BaseController
             include Spree::Api::V3::Admin::EmailTemplateLookup
 
+            request_params 'EmailTemplateRestoreParams' do |body|
+              body.include_attributes Spree::Api::V3::Admin::EmailTemplateLanguageRequestSchema
+              body.attribute :lock_version, :integer,
+                nullable: true,
+                permit: false,
+                description: "The open draft's `lock_version`, or null when there is none; checked as when saving."
+            end
+
             # POST /api/v3/admin/email_templates/:email_template_id/revisions/:revision_id/restoration
             #
             # Copies the revision into the language's draft, to be published

data/app/controllers/spree/api/v3/admin/email_templates/test_emails_controller.rb

@@ -6,6 +6,10 @@ module Spree
           class TestEmailsController < Admin::BaseController
             include Spree::Api::V3::Admin::EmailTemplateLookup
 
+            request_params 'EmailTemplatePreviewParams' do |body|
+              body.include_attributes Spree::Api::V3::Admin::EmailTemplatePreviewRequestSchema
+            end
+
             before_action :authorize_sample_data!
 
             # POST /api/v3/admin/email_templates/:email_template_id/test_email

data/app/controllers/spree/api/v3/admin/exports_controller.rb

@@ -16,6 +16,26 @@ module Spree
           # readable ones instead of gating on a single scope.
           skip_scope_check! only: :index
 
+          request_params :export do |body|
+            body.attribute :type, :string,
+              required: true, on: :create,
+              example: 'products',
+              description: 'Which dataset to export, as its shorthand: `products`, `orders`, `customers`, `product_translations`, `gift_cards`, `coupon_codes`, `newsletter_subscribers`, `price_list_prices`, `purchase_orders`, or a type an extension registers.'
+            body.attribute :record_selection, :string,
+              choices: %w[filtered all],
+              example: 'filtered',
+              description: '`filtered` (the default) keeps `search_params`; `all` ignores them and exports every record in scope.'
+            body.attribute :results_url, :string,
+              example: 'https://admin.example.com/store_abc/exports',
+              description: "Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's allowed origins."
+            # Read from the raw params: a Ransack hash nests groupings, which
+            # `permit(search_params: {})` rejects.
+            body.attribute :search_params, :hash,
+              permit: false,
+              example: { name_cont: 'shirt' },
+              description: 'A Ransack query, with the predicates the list endpoint accepts. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: "all"`.'
+          end
+
           # We stream the CSV inline rather than redirecting to ActiveStorage's
           # signed-URL endpoint because the SPA's Vite proxy only forwards
           # `/api/*`. A cross-origin redirect to `/rails/active_storage/...`
@@ -92,13 +112,10 @@ module Spree
             klass.new(attrs)
           end
 
-          # `search_params` carries an arbitrary Ransack hash with nested
-          # groupings (`{ g: [{ name_cont: 'foo' }] }`). Rails' `permit(k: {})`
-          # rejects nested hashes, so we extract via `to_unsafe_h`. `:format`
-          # is intentionally dropped — only CSV is supported and Rails' request
-          # format would otherwise overwrite the model's enum.
+          # `:format` is intentionally dropped — only CSV is supported and Rails'
+          # request format would otherwise overwrite the model's enum.
           def permitted_params
-            attrs = params.permit(*model_additional_permitted_attributes, :type, :record_selection, :results_url)
+            attrs = params.permit(*permitted_attributes)
             raw = params[:search_params]
             attrs[:search_params] = raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw if raw.present?
             attrs

data/app/controllers/spree/api/v3/admin/files_controller.rb

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class FilesController < Admin::BaseController
+          include Spree::Api::V3::FileUploads
+
+          # The endpoint that uses a file checks its own scope (`write_customers`
+          # for an avatar, and so on), so this gate is the floor, not the only
+          # check. `write_products` covers the dominant flow, product media.
+          scoped_resource :products
+
+          skip_before_action :authenticate_user
+
+          # Permitted by Spree::Api::V3::FileUploads, shared with the seller branch.
+          request_params 'FileUploadCreateParams', action: :create do |body|
+            body.include_attributes Spree::Api::V3::FileUploadRequestSchema
+          end
+
+          private
+
+          def file_upload_serializer
+            Spree.api.admin_file_upload_serializer
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/gift_card_batches_controller.rb

@@ -11,6 +11,25 @@ module Spree
         class GiftCardBatchesController < ResourceController
           scoped_resource :gift_cards
 
+          request_params :gift_card_batch do |body|
+            body.attribute :prefix, :string,
+              required: true, on: :create,
+              example: 'WELCOME',
+              description: 'Lowercased and prepended to every generated code.'
+            body.attribute :amount, :decimal,
+              required: true, on: :create,
+              example: '25.00',
+              description: 'The amount of each card, greater than zero.'
+            body.attribute :codes_count, :integer,
+              required: true, on: :create,
+              example: 100,
+              description: 'How many cards to generate. Capped at `gift_card_batch_limit`; batches over `gift_card_batch_web_limit` generate in the background.'
+            body.attribute :currency, :currency,
+              example: 'USD',
+              description: 'ISO 4217 currency code. Defaults to the store currency.'
+            body.attribute :expires_at, :date, nullable: true, example: '2030-12-31'
+          end
+
           protected
 
           def model_class
@@ -22,7 +41,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :prefix, :codes_count, :amount, :expires_at, :currency)
+            params.permit(*permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/admin/gift_cards_controller.rb

@@ -13,6 +13,24 @@ module Spree
         class GiftCardsController < ResourceController
           scoped_resource :gift_cards
 
+          request_params :gift_card do |body|
+            body.attribute :amount, :decimal,
+              required: true, on: :create,
+              example: '25.00',
+              description: 'Greater than zero.'
+            body.attribute :currency, :currency,
+              example: 'USD',
+              description: 'ISO 4217 currency code. Defaults to the store currency.'
+            body.attribute :code, :string, example: 'WELCOME50', description: 'Generated when omitted.'
+            body.attribute :expires_at, :date, nullable: true, example: '2030-12-31'
+            # Resolved through the caller's ability by `resolve_customer`.
+            body.attribute :customer_id, :id,
+              nullable: true,
+              permit: false,
+              example: 'cus_UkLWZg9DAJ',
+              description: 'The customer the card belongs to. Needs the `read_customers` permission; null detaches it.'
+          end
+
           before_action :resolve_customer, only: [:create, :update]
 
           protected
@@ -26,7 +44,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :code, :amount, :expires_at, :currency).tap do |attributes|
+            params.permit(*permitted_attributes).tap do |attributes|
               attributes[:customer] = @customer if params.key?(:customer_id)
             end
           end

data/app/controllers/spree/api/v3/admin/imports_controller.rb

@@ -17,10 +17,43 @@ module Spree
           # writable ones instead of gating on a single scope.
           skip_scope_check! only: :index
 
+          request_params :import do |body|
+            body.attribute :type, :string,
+              required: true, on: :create,
+              example: 'products',
+              description: 'Which dataset to import, as its shorthand: `products`, `customers`, `product_translations`, `price_list_prices`, `purchase_orders`, or a type an extension registers.'
+            body.attribute :attachment_signed_id, :string,
+              required: true, on: :create,
+              description: 'The `signed_id` of the uploaded CSV, from `files.upload()` with `visibility: "private"`.'
+            body.attribute :delimiter, :string,
+              choices: [',', ';', '|', "\t"],
+              example: ',',
+              description: 'CSV column separator. Defaults to a comma.'
+            body.attribute :results_url, :string,
+              example: 'https://admin.example.com/store_abc/settings/imports',
+              description: "Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's allowed origins."
+            body.attribute :price_list_id, :id,
+              description: 'For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store; other types ignore it.'
+          end
+
+          request_params 'ImportCompleteMappingParams', action: :complete_mapping do |body|
+            body.attribute :mappings, :array,
+              description: 'Column assignments to apply before processing starts. Omit to accept the ones assigned on create.' do |mapping|
+              mapping.attribute :schema_field, :string,
+                required: true,
+                example: 'slug',
+                description: "A schema field name from the import's `schema_fields`."
+              mapping.attribute :file_column, :string,
+                nullable: true,
+                example: 'Product Handle',
+                description: 'The CSV header to read the field from; null unmaps the field.'
+            end
+          end
+
           # POST /api/v3/admin/imports
           #
-          # `attachment` is an ActiveStorage signed blob id obtained from
-          # POST /api/v3/admin/direct_uploads. On success the import advances
+          # `attachment_signed_id` is a signed id obtained from
+          # POST /api/v3/admin/files. On success the import advances
           # straight into `mapping` (auto-assigning file columns from the CSV
           # headers), so the response already carries the mapping payload.
           def create
@@ -48,12 +81,6 @@ module Spree
             else
               render_errors(@resource.errors)
             end
-          rescue ActiveSupport::MessageVerifier::InvalidSignature
-            render_error(
-              code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],
-              message: 'Invalid attachment signed id',
-              status: :unprocessable_content
-            )
           end
 
           # PATCH /api/v3/admin/imports/:id/complete_mapping
@@ -259,7 +286,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :type, :attachment, :preferred_delimiter, :results_url, :price_list_id)
+            params.permit(*permitted_attributes)
           end
 
           # A price-list import writes into one list, named by its prefixed id.

data/app/controllers/spree/api/v3/admin/integrations_controller.rb

@@ -15,6 +15,18 @@ module Spree
           subclassed_via -> { Spree::Integration.registered_classes },
                          unknown_type_error: 'unknown_integration_type'
 
+          request_params :integration do |body|
+            body.attribute :type, :string,
+              required: true,
+              only: :create,
+              example: 'carrier',
+              description: 'Wire shorthand from the integration types endpoint.'
+            body.attribute :active, :boolean,
+              description: 'Activating runs the connection check, and a failed check is a 422.'
+            body.attribute :preferences, :hash,
+              description: 'Credential values. Secret preferences come back masked, and sending a masked value back keeps the stored secret.'
+          end
+
           # GET /api/v3/admin/integrations/types
           # Pure registry discovery — which integrations are installed and how
           # they're configured. Deliberately carries no per-store connected
@@ -47,7 +59,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :type, :active, preferences: {})
+            params.permit(*permitted_attributes)
           end
 
           # `types` is read-only discovery — maps to the read scope.

data/app/controllers/spree/api/v3/admin/invitation_acceptances_controller.rb

@@ -10,6 +10,14 @@ module Spree
           skip_scope_check!
           skip_before_action :authenticate_admin!, only: [:lookup, :accept]
 
+          request_params 'InvitationAcceptParams', action: :accept do |body|
+            body.attribute :password, :string,
+              description: 'Required when the invitee has no account yet: it creates one. An existing account signs in without it.'
+            body.attribute :password_confirmation, :string
+            body.attribute :first_name, :string
+            body.attribute :last_name, :string
+          end
+
           rate_limit to: Spree::Api::Config[:rate_limit_login],
                      within: Spree::Api::Config[:rate_limit_window].seconds,
                      store: Rails.cache,
@@ -24,7 +32,6 @@ module Spree
           end
 
           # POST /api/v3/admin/auth/invitations/:id/accept?token=:token
-          # Body: { password?, password_confirmation?, first_name?, last_name? }
           def accept
             return unless load_invitation
 
@@ -99,7 +106,7 @@ module Spree
           end
 
           def signup_params(invitation)
-            params.permit(:password, :password_confirmation, :first_name, :last_name).
+            params.permit(*declared_permitted_attributes).
               merge(email: invitation.email)
           end