belpost 0.7.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5555f3f61fcb03030a1e5fd226abac810104277326db2ee42b505656ff0f3ce8
-  data.tar.gz: 585c4832344b4cfa9a654e4605926bacd605bf854e77e21391910de03d3d22db
+  metadata.gz: 43a87cdb950f04f9508bd0facb45918b68d17fc2442f6dd6ef9a0698e350950d
+  data.tar.gz: 24fe3c8cbde4d7ddc4e5cd5d21f03a6f9001c5820fdad7fcea0dcb06013c5909
 SHA512:
-  metadata.gz: eaf547611c62aa03df55771a57d4405ea1352b04cf9fe3fddd04f1120b3df24a100a38e4f449e7dcadffa1a7b1bd58101212425d263d7e168b448712af597d5c
-  data.tar.gz: 4eb26318bd0e28467e50a31caa184880fab8276e331efcd7240723124ebf3795615d47eca35516f7f0d5048dbf3bb44663bb25182815d807fd4aef9d59313899
+  metadata.gz: 8a90de8d13d830d5eb68b0fbbfa9374495f699cd66932b4c2d6e422348a494e6f9f4b46d30b3e8444f50e7d73fc28175cc1fe78036927b878a14c95108131dd1
+  data.tar.gz: c9bedc78bd654b6624ee3f20b7e292e78c4a0de11ed957763c367d7eadcd3ca719a65f4f2a805b2b1a8951d9afac621a05f97a5864cfc805d2161193d00f5e31

data/CHANGELOG.md

@@ -1,4 +1,52 @@
-# Changelog
+## [0.11.0] - 2025-04-23
+### Added
+- Added support for finding addresses by postal code via `find_addresses_by_postcode` method
+- Added new validation schema for postal codes
+- Added comprehensive tests for the new endpoint
+
+## [0.9.3] - 2025-04-18
+### Added
+- A new `list_batches` method in the Client class that:
+  - Supports pagination with the page parameter
+  - Allows filtering by batch status (committed or uncommitted)
+  - Enables limiting results per page with the per_page parameter
+  - Provides search functionality by batch number
+
+## [0.9.2] - 2025-04-17
+### Added
+- Added support for ecommerce-specific parameters:
+  - `negotiated_rate`
+  - `is_declared_value`
+  - `is_partial_receipt`
+  - `postal_items_in_ops`
+
+## [0.9.1] - 2025-04-16
+### Added
+- New `PostalDeliveryTypes` module for centralized management of postal delivery types
+- Tests for the `PostalDeliveryTypes` module
+
+## [0.9.0] - 2025-04-15
+### Changed
+- Refactored API paths into a separate module `Belpost::ApiPaths` for better maintainability
+- Moved all hardcoded API endpoints into constants in `api_paths.rb`
+- Updated all client methods to use the new API path constants
+- Updated tests to use the new API path constants
+
+### Added
+- Added batch retrieval functionality via `find_batch_by_id` method
+- Support for finding batch mailings by their ID with validation
+- New module `Belpost::ApiPaths` with organized API endpoint constants:
+  - Batch mailing paths
+  - Postal deliveries paths
+  - Geo directory paths
+
+## [0.8.0] - 2025-04-14
+### Added
+- Added batch mailing functionality via `create_batch` method
+- Support for creating batch mailings with various delivery types
+- Added comprehensive validation for batch mailing data
+- Added new models and schemas for batch mailing
+- Added tests for batch mailing functionality
 
 ## [0.7.0] - 2025-04-01
 ### Added

data/README.md

@@ -308,6 +308,54 @@ postcodes = client.search_postcode(
 puts postcodes
 ```
 
+### Finding addresses by postal code
+
+```ruby
+client = Belpost::Client.new
+addresses = client.find_addresses_by_postcode("210001")
+puts addresses
+```
+
+### Finding a batch by ID
+
+```ruby
+client = Belpost::Client.new
+batch = client.find_batch_by_id(123)
+puts batch
+```
+
+### Listing and searching for batches
+
+```ruby
+client = Belpost::Client.new
+
+# Get all batches with default pagination
+batches = client.list_batches
+puts "Total batches: #{batches["total"]}"
+
+# Get a specific page of results
+batches = client.list_batches(page: 2)
+
+# Filter by status (committed or uncommitted)
+committed_batches = client.list_batches(status: "committed")
+uncommitted_batches = client.list_batches(status: "uncommitted")
+
+# Set the number of batches per page
+batches = client.list_batches(per_page: 50)
+
+# Search for a specific batch by number
+batch_number = 12345
+search_results = client.list_batches(search: batch_number)
+
+# Combine multiple parameters
+filtered_batches = client.list_batches(
+  page: 2,
+  status: "committed",
+  per_page: 25,
+  search: 12345
+)
+```
+
 ## Error handling
 
 The client may throw the following exceptions:

data/belpost.gemspec

@@ -33,5 +33,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "dotenv"
+  spec.add_dependency "dry-schema", "~> 1.0"
   spec.add_dependency "dry-validation", "~> 1.0"
 end

data/lib/belpost/api_paths.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Belpost
+  # Constants for API paths
+  module ApiPaths
+    # Batch mailing paths
+    BATCH_MAILING_LIST = "/api/v1/business/batch-mailing/list"
+    BATCH_MAILING_DOCUMENTS = "/api/v1/business/batch-mailing/documents"
+    BATCH_MAILING_ITEM = "/api/v1/business/batch-mailing/item"
+    BATCH_MAILING_DUPLICATE = "/api/v1/business/batch-mailing/list/:id/duplicate"
+    BATCH_MAILING_DUPLICATE_FULL = "/api/v1/business/batch-mailing/list/:id/duplicate-full"
+    BATCH_MAILING_COMMIT = "/api/v1/business/batch-mailing/list/:id/commit"
+    BATCH_MAILING_GENERATE_BLANK = "/api/v1/business/batch-mailing/list/:id/generate-blank"
+    BATCH_MAILING_LIST_ITEM = "/api/v1/business/batch-mailing/list/:id/item"
+
+    # Postal deliveries paths
+    POSTAL_DELIVERIES = "/api/v1/business/postal-deliveries"
+    POSTAL_DELIVERIES_HS_CODES = "/api/v1/business/postal-deliveries/hs-codes/list"
+    POSTAL_DELIVERIES_VALIDATION = "/api/v1/business/postal-deliveries/validation"
+    POSTAL_DELIVERIES_COUNTRIES = "/api/v1/business/postal-deliveries/countries"
+
+    # Geo directory paths
+    GEO_DIRECTORY_SEARCH_ADDRESS = "/api/v1/business/geo-directory/search-address"
+    GEO_DIRECTORY_POSTCODE = "/api/v1/business/geo-directory/postcode"
+    GEO_DIRECTORY_ADDRESSES = "/api/v1/business/geo-directory/addresses"
+  end
+end

data/lib/belpost/api_service.rb

@@ -151,7 +151,6 @@ module Belpost
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true if uri.scheme == "https"
       http.read_timeout = @timeout
-
       begin
         response = http.request(request)
         handle_response(response)
@@ -191,7 +190,7 @@ module Belpost
 
     def handle_response(response)
       case response.code
-      when "200"
+      when "200", "201"
         response
       when "401", "403"
         raise AuthenticationError.new(

data/lib/belpost/client.rb

@@ -2,8 +2,14 @@
 
 require_relative "api_service"
 require_relative "models/parcel"
+require_relative "models/batch"
+require_relative "models/batch_item"
 require_relative "models/api_response"
 require_relative "validations/address_schema"
+require_relative "validations/batch_schema"
+require_relative "validations/batch_item_schema"
+require_relative "validations/postcode_schema"
+require_relative "api_paths"
 
 module Belpost
   # Main client class for interacting with the BelPost API.
@@ -23,6 +29,41 @@ module Belpost
       )
     end
 
+    # Creates a new batch mailing by sending a POST request to the API.
+    #
+    # @param batch_data [Hash] The data for the batch mailing.
+    # @return [Hash] The parsed JSON response from the API.
+    # @raise [Belpost::InvalidRequestError] If the request data is invalid.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def create_batch(batch_data)
+      validation_result = Validation::BatchSchema.new.call(batch_data)
+      raise ValidationError, "Invalid batch data: #{validation_result.errors.to_h}" unless validation_result.success?
+
+      batch = Models::Batch.new(batch_data)
+      response = @api_service.post(ApiPaths::BATCH_MAILING_LIST, batch.to_h)
+      response.to_h
+    end
+
+    # Creates new items in a batch by sending a POST request to the API.
+    #
+    # @param batch_id [Integer] The ID of the batch where items should be added.
+    # @param items_data [Hash] The data for the batch items to create.
+    # @return [Hash] The parsed JSON response from the API.
+    # @raise [Belpost::InvalidRequestError] If the request data is invalid.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def create_batch_items(batch_id, items_data)
+      raise ValidationError, "Batch ID must be provided" if batch_id.nil?
+      raise ValidationError, "Batch ID must be a positive integer" unless batch_id.is_a?(Integer) && batch_id.positive?
+
+      validation_result = Validation::BatchItemSchema.call(items_data)
+      raise ValidationError, "Invalid batch item data: #{validation_result.errors.to_h}" unless validation_result.success?
+
+      batch_item = Models::BatchItem.new(items_data)
+      path = ApiPaths::BATCH_MAILING_LIST_ITEM.gsub(':id', batch_id.to_s)
+      response = @api_service.post(path, batch_item.to_h)
+      response.to_h
+    end
+
     # Creates a new postal parcel by sending a POST request to the API.
     #
     # @param parcel_data [Hash] The data for the postal parcel.
@@ -31,12 +72,10 @@ module Belpost
     # @raise [Belpost::ApiError] If the API returns an error response.
     def create_parcel(parcel_data)
       validation_result = Validation::ParcelSchema.call(parcel_data)
-      unless validation_result.success?
-        raise ValidationError, "Invalid parcel data: #{validation_result.errors.to_h}"
-      end
+      raise ValidationError, "Invalid parcel data: #{validation_result.errors.to_h}" unless validation_result.success?
 
       parcel = Models::Parcel.new(parcel_data)
-      response = @api_service.post("/api/v1/business/postal-deliveries", parcel.to_h)
+      response = @api_service.post(ApiPaths::POSTAL_DELIVERIES, parcel.to_h)
       response.to_h
     end
 
@@ -45,7 +84,7 @@ module Belpost
     # @return [Array<Hash>] The HS codes tree as an array of hashes.
     # @raise [Belpost::ApiError] If the API returns an error response.
     def fetch_hs_codes
-      response = @api_service.get("/api/v1/business/postal-deliveries/hs-codes/list")
+      response = @api_service.get(ApiPaths::POSTAL_DELIVERIES_HS_CODES)
       response.to_h
     end
 
@@ -56,7 +95,7 @@ module Belpost
     # @raise [Belpost::ApiError] If the API returns an error response.
     def validate_postal_delivery(country_code)
       country_code = country_code.upcase
-      response = @api_service.get("/api/v1/business/postal-deliveries/validation/#{country_code}")
+      response = @api_service.get("#{ApiPaths::POSTAL_DELIVERIES_VALIDATION}/#{country_code}")
       response.to_h
     end
 
@@ -65,7 +104,20 @@ module Belpost
     # @return [Hash] The parsed JSON response containing available countries.
     # @raise [Belpost::ApiError] If the API returns an error response.
     def fetch_available_countries
-      response = @api_service.get("/api/v1/business/postal-deliveries/countries")
+      response = @api_service.get(ApiPaths::POSTAL_DELIVERIES_COUNTRIES)
+      response.to_h
+    end
+
+    # Finds a batch by its ID.
+    #
+    # @param id [Integer] The ID of the batch to find.
+    # @return [Hash] The batch data if found.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def find_batch_by_id(id)
+      raise ValidationError, "ID must be provided" if id.nil?
+      raise ValidationError, "ID must be a positive integer" unless id.is_a?(Integer) && id.positive?
+
+      response = @api_service.get("#{ApiPaths::BATCH_MAILING_LIST}/#{id}")
       response.to_h
     end
 
@@ -86,7 +138,21 @@ module Belpost
       raise ValidationError, "Address must be filled" if address.empty?
 
       formatted_address = format_address(address)
-      response = @api_service.get("/api/v1/business/geo-directory/search-address", { search: formatted_address })
+      response = @api_service.get(ApiPaths::GEO_DIRECTORY_SEARCH_ADDRESS, { search: formatted_address })
+      response.to_h
+    end
+
+    # Searches for addresses belonging to a specific postal code (postcode).
+    #
+    # @param postcode [String] The postal code to search for (6 digits)
+    # @return [Array<Hash>] An array of addresses belonging to the specified postal code
+    # @raise [Belpost::ValidationError] If the postcode is invalid
+    # @raise [Belpost::ApiError] If the API returns an error response
+    def find_addresses_by_postcode(postcode)
+      validation_result = Validation::PostcodeSchema.new.call(postcode: postcode)
+      raise ValidationError, "Invalid postcode: #{validation_result.errors.to_h}" unless validation_result.success?
+
+      response = @api_service.get(ApiPaths::GEO_DIRECTORY_ADDRESSES, { postcode: postcode })
       response.to_h
     end
 
@@ -113,7 +179,55 @@ module Belpost
       params[:building] = format_building_number(building) if building
       params[:limit] = limit
 
-      response = @api_service.get("/api/v1/business/geo-directory/postcode", params)
+      response = @api_service.get(ApiPaths::GEO_DIRECTORY_POSTCODE, params)
+      response.to_h
+    end
+
+    # Lists all batches with optional filtering.
+    #
+    # @param page [Integer] The page number for pagination (optional, default: 1, must be > 0)
+    # @param status [String] Filter by status: 'committed' or 'uncommitted' (optional)
+    # @param per_page [Integer] Number of items per page (optional)
+    # @param search [Integer] Search by batch number (optional)
+    # @return [Hash] The parsed JSON response containing batch list with pagination details
+    # @raise [Belpost::ValidationError] If   parameters are invalid
+    # @raise [Belpost::ApiError] If the API returns an error response
+    def list_batches(page: 1, status: nil, per_page: nil, search: nil)
+      params = {}
+
+      # Validate page parameter
+      if page
+        raise ValidationError, "Page must be an integer" unless page.is_a?(Integer)
+        raise ValidationError, "Page must be greater than 0" unless page.positive?
+
+        params[:page] = page
+      end
+
+      # Validate status parameter
+      if status
+        unless %w[committed uncommitted].include?(status)
+          raise ValidationError, "Status must be 'committed' or 'uncommitted'"
+        end
+
+        params[:status] = status
+      end
+
+      # Validate per_page parameter
+      if per_page
+        raise ValidationError, "Per page must be an integer" unless per_page.is_a?(Integer)
+        raise ValidationError, "Per page must be positive" unless per_page.positive?
+
+        params[:perPage] = per_page
+      end
+
+      # Validate search parameter
+      if search
+        raise ValidationError, "Search must be an integer" unless search.is_a?(Integer)
+
+        params[:search] = search
+      end
+
+      response = @api_service.get(ApiPaths::BATCH_MAILING_LIST, params)
       response.to_h
     end
 
@@ -132,11 +246,11 @@ module Belpost
       return building unless building
 
       building.gsub(/\s+/, " ")
-             .gsub(/\s*корпус\s*(\d+)\s*/i, '/\1')
-             .gsub(/\s*корп\s*(\d+)\s*/i, '/\1')
-             .gsub(/\s*кор\s*(\d+)\s*/i, '/\1')
-             .gsub(/\s*к\s*(\d+)\s*/i, '/\1')
-             .strip
+              .gsub(/\s*корпус\s*(\d+)\s*/i, '/\1')
+              .gsub(/\s*корп\s*(\d+)\s*/i, '/\1')
+              .gsub(/\s*кор\s*(\d+)\s*/i, '/\1')
+              .gsub(/\s*к\s*(\d+)\s*/i, '/\1')
+              .strip
     end
   end
 end

data/lib/belpost/configuration.rb

@@ -9,7 +9,7 @@ module Belpost
     def initialize
       @base_url = ENV.fetch("BELPOST_API_URL", "https://api.belpost.by")
       @jwt_token = ENV.fetch("BELPOST_JWT_TOKEN", nil)
-      
+
       # Convert timeout to integer with a fallback to default
       begin
         @timeout = Integer(ENV.fetch("BELPOST_TIMEOUT", 10))
@@ -17,14 +17,14 @@ module Belpost
         @timeout = 10
       end
     end
-    
+
     # Validates that all required configuration is present
     # @raise [Belpost::ConfigurationError] If required configuration is missing
     def validate!
       raise ConfigurationError, "Base URL is required" if base_url.nil?
       raise ConfigurationError, "JWT token is required" if jwt_token.nil?
     end
-    
+
     # Returns a hash representation of the configuration
     # @return [Hash] The configuration as a hash
     def to_h

data/lib/belpost/models/batch.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Belpost
+  module Models
+    # Model class for batch mailing
+    class Batch
+      attr_reader :postal_delivery_type, :direction, :payment_type, :negotiated_rate,
+                  :name, :card_number, :postal_items_in_ops, :category, :is_document,
+                  :is_declared_value, :is_partial_receipt
+
+      def initialize(data)
+        @postal_delivery_type = data[:postal_delivery_type]
+        @direction = data[:direction]
+        @payment_type = data[:payment_type]
+        @negotiated_rate = data[:negotiated_rate]
+        @name = data[:name]
+        @card_number = data[:card_number]
+        @postal_items_in_ops = data[:postal_items_in_ops]
+        @category = data[:category]
+        @is_document = data[:is_document]
+        @is_declared_value = data[:is_declared_value]
+        @is_partial_receipt = data[:is_partial_receipt]
+      end
+
+      def to_h
+        {
+          postal_delivery_type: @postal_delivery_type,
+          direction: @direction,
+          payment_type: @payment_type,
+          negotiated_rate: @negotiated_rate,
+          name: @name,
+          card_number: @card_number,
+          postal_items_in_ops: @postal_items_in_ops,
+          category: @category,
+          is_document: @is_document,
+          is_declared_value: @is_declared_value,
+          is_partial_receipt: @is_partial_receipt
+        }.compact
+      end
+    end
+  end
+end

data/lib/belpost/models/batch_item.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Belpost
+  module Models
+    # Model class for batch item
+    class BatchItem
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      def to_h
+        data
+      end
+
+      def to_json(*_args)
+        data.to_json
+      end
+    end
+  end
+end 

data/lib/belpost/models/customs_declaration.rb

@@ -50,8 +50,7 @@ module Belpost
       def valid?
         return false if @category && !VALID_CATEGORIES.include?(@category)
         return false if @category == "other" && @explanation.nil?
-        
-        # Проверка наличия обязательных полей для коммерческих отправлений
+
         if %w[merchandise sample returned_goods].include?(@category)
           return false if @items.empty?
           return false if @price.empty?
@@ -61,4 +60,4 @@ module Belpost
       end
     end
   end
-end 
+end

data/lib/belpost/models/parcel_builder.rb

@@ -194,23 +194,19 @@ module Belpost
       private
 
       def validate!
-        # Проверка обязательных полей
         raise ValidationError, "Weight is required" unless @data.dig(:parcel, :measures, :weight)
         raise ValidationError, "Sender type is required" unless @data.dig(:sender, :type)
         raise ValidationError, "Recipient type is required" unless @data.dig(:recipient, :type)
 
-        # Проверка логики
         if @data.dig(:addons, :cash_on_delivery) && !@data.dig(:addons, :declared_value)
           raise ValidationError, "Declared value is required when cash on delivery is set"
         end
 
-        # Проверка международных отправлений
-        if @data.dig(:parcel, :arrival, :country) != "BY"
-          if @data[:cp72].nil? || @data[:cp72].empty?
-            raise ValidationError, "Customs declaration is required for international parcels"
-          end
-        end
+        return unless @data.dig(:parcel, :arrival, :country) != "BY"
+        return unless @data[:cp72].nil? || @data[:cp72].empty?
+
+        raise ValidationError, "Customs declaration is required for international parcels"
       end
     end
   end
-end 
+end

data/lib/belpost/postal_delivery_types.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Belpost
+  # Module for managing postal delivery types in the Belpost system.
+  # Provides a centralized way to handle and validate different types of postal deliveries.
+  #
+  # @example Validating a postal delivery type
+  #   Belpost::PostalDeliveryTypes.valid?("ordered_small_package") # => true
+  #
+  # @example Getting all available types
+  #   Belpost::PostalDeliveryTypes.all # => [:ordered_small_package, :letter_declare_value, ...]
+  #
+  # @example Getting a description for a type
+  #   Belpost::PostalDeliveryTypes.description("ordered_small_package") # => "Заказной мелкий пакет республиканский"
+  #
+  # @note All types are frozen to prevent modification at runtime
+  module PostalDeliveryTypes
+    # Hash containing all valid postal delivery types with their Russian descriptions
+    # @return [Hash<Symbol, String>] frozen hash of postal delivery types and their descriptions
+    TYPES = {
+      ordered_small_package: "Заказной мелкий пакет республиканский",
+      letter_declare_value: "Письмо с объявленной ценностью республиканское",
+      package: "Простая посылка республиканская (без ОЦ)",
+      ems: "Республиканское отправление EMS",
+      ordered_parcel_post: "Заказная бандероль республиканская",
+      ordered_letter: "Заказное письмо республиканское",
+      ordered_postcard: "Заказная почтовая карточка республиканская",
+      small_package_declare_value: "Мелкий пакет с объявленной ценностью республиканский",
+      package_declare_value: "Посылка с объявленной ценностью республиканская",
+      ecommerce_economical: "Отправление E-commerce Эконом",
+      ecommerce_standard: "Отправление E-commerce Стандарт",
+      ecommerce_elite: "Отправление E-commerce Элит",
+      ecommerce_express: "Отправление E-commerce Экспресс",
+      ecommerce_light: "Отправление E-commerce Лайт",
+      ecommerce_optima: "Отправление E-commerce Оптима"
+    }.freeze
+
+    # Validation rules for each postal delivery type
+    # @return [Hash<Symbol, Hash>] frozen hash of validation rules for each type
+    VALIDATION_RULES = {
+      ecommerce_economical: {
+        negotiated_rate: false,
+        declared_value: [true, false],
+        partial_receipt: false,
+        postal_items_in_ops: true
+      },
+      ecommerce_standard: {
+        negotiated_rate: false,
+        declared_value: [true, false],
+        partial_receipt: false,
+        postal_items_in_ops: [true, false]
+      },
+      ecommerce_elite: {
+        negotiated_rate: false,
+        declared_value: [true, false],
+        partial_receipt: false,
+        postal_items_in_ops: [true, false]
+      },
+      ecommerce_express: {
+        negotiated_rate: false,
+        declared_value: [true, false],
+        partial_receipt: false,
+        postal_items_in_ops: [true, false]
+      },
+      ecommerce_light: {
+        negotiated_rate: false,
+        declared_value: [true, false],
+        partial_receipt: false,
+        postal_items_in_ops: true
+      },
+      ecommerce_optima: {
+        negotiated_rate: false,
+        declared_value: [true, false],
+        partial_receipt: false,
+        postal_items_in_ops: [true, false]
+      }
+    }.freeze
+
+    # Checks if the given type is a valid postal delivery type
+    # @param type [String, Symbol, nil] the type to validate
+    # @return [Boolean] true if the type is valid, false otherwise
+    def self.valid?(type)
+      return false if type.nil?
+
+      TYPES.key?(type.to_sym)
+    rescue NoMethodError
+      false
+    end
+
+    # Returns all valid postal delivery types
+    # @return [Array<Symbol>] array of all valid postal delivery type symbols
+    def self.all
+      TYPES.keys
+    end
+
+    # Returns the Russian description for a given postal delivery type
+    # @param type [String, Symbol] the type to get the description for
+    # @return [String, nil] the description if the type is valid, nil otherwise
+    def self.description(type)
+      TYPES[type.to_sym]
+    rescue NoMethodError
+      nil
+    end
+
+    # Returns validation rules for a given postal delivery type
+    # @param type [String, Symbol] the type to get rules for
+    # @return [Hash, nil] the validation rules if the type has them, nil otherwise
+    def self.validation_rules(type)
+      VALIDATION_RULES[type.to_sym]
+    rescue NoMethodError
+      nil
+    end
+
+    # Validates if the given parameters match the rules for the given type
+    # @param type [String, Symbol] the postal delivery type
+    # @param params [Hash] the parameters to validate
+    # @return [Array<String>] array of error messages, empty if validation passes
+    def self.validate_params(type, params)
+      rules = validation_rules(type)
+      return [] unless rules
+
+      errors = []
+      type_sym = type.to_sym
+
+      # Check negotiated_rate
+      if rules[:negotiated_rate] != params[:negotiated_rate]
+        errors << "negotiated_rate must be #{rules[:negotiated_rate]} for #{type_sym}"
+      end
+
+      # Check declared_value
+      if rules[:declared_value] && !rules[:declared_value].include?(params[:is_declared_value])
+        errors << "is_declared_value must be one of #{rules[:declared_value]} for #{type_sym}"
+      end
+
+      # Check partial_receipt
+      if rules[:partial_receipt] != params[:is_partial_receipt]
+        errors << "is_partial_receipt must be #{rules[:partial_receipt]} for #{type_sym}"
+      end
+
+      # Check postal_items_in_ops
+      if rules[:postal_items_in_ops]
+        if rules[:postal_items_in_ops].is_a?(Array)
+          unless rules[:postal_items_in_ops].include?(params[:postal_items_in_ops])
+            errors << "postal_items_in_ops must be one of #{rules[:postal_items_in_ops]} for #{type_sym}"
+          end
+        elsif rules[:postal_items_in_ops] != params[:postal_items_in_ops]
+          errors << if rules[:postal_items_in_ops] == true
+                      "postal_items_in_ops must be one of [true] for #{type_sym}"
+                    else
+                      "postal_items_in_ops must be #{rules[:postal_items_in_ops]} for #{type_sym}"
+                    end
+        end
+      end
+
+      errors
+    end
+  end
+end