feat(merchants): add raw data import (csv) for merchants (#1992)

* feat(merchants): add csv import endpoint for merchants

* docs: update endpoint docs

* fix(merchant): recommended ai fixes

spec/requests/api/v1/merchants_spec.rb

@@ -47,6 +47,43 @@ RSpec.describe 'API V1 Merchants', type: :request do
         run_test!
       end
     end
+
+    post 'Import merchants from CSV' do
+      tags 'Merchants'
+      security [ { apiKeyAuth: [] } ]
+      consumes 'multipart/form-data'
+      produces 'application/json'
+
+      parameter name: :file, in: :formData, type: :file, required: true,
+                description: 'CSV file with columns: name* (required), color, website_url'
+
+      response '201', 'merchants imported' do
+        schema '$ref' => '#/components/schemas/MerchantImportResult'
+
+        let(:file) do
+          Rack::Test::UploadedFile.new(
+            StringIO.new("name,color,website_url\nCoffee Shop,#e99537,https://coffeeshop.com"),
+            'text/csv',
+            true,
+            original_filename: 'merchants.csv'
+          )
+        end
+
+        run_test!
+      end
+
+      response '401', 'unauthorized' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+        let(:'X-Api-Key') { nil }
+        run_test!
+      end
+
+      response '422', 'missing file or invalid CSV' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+        let(:file) { nil }
+        run_test!
+      end
+    end
   end
 
   path '/api/v1/merchants/{id}' do

spec/swagger_helper.rb

@@ -571,6 +571,15 @@ RSpec.configure do |config|
               updated_at: { type: :string, format: :'date-time' }
             }
           },
+          MerchantImportResult: {
+            type: :object,
+            required: %w[imported skipped merchants],
+            properties: {
+              imported: { type: :integer, description: 'Number of merchants successfully created' },
+              skipped: { type: :integer, description: 'Number of rows skipped (duplicates or invalid)' },
+              merchants: { type: :array, items: { '$ref' => '#/components/schemas/MerchantDetail' } }
+            }
+          },
           Tag: {
             type: :object,
             required: %w[id name color],