belpost 0.11.1 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9514e803064862ca1a9922d89527d3a97da9806105b3621d6c844405a8ee517d
-  data.tar.gz: '0274388346a6da307d7d27ccf1420893e35deb74d860a35a9bffc2e630f8f7a1'
+  metadata.gz: e4adf946e8f59bd6f7819db47ee253b758f285c1bdf6fac6ca326dea521902e1
+  data.tar.gz: 8e9490b37a3518193182dc6db5cf1e65c5a7f7f13fafdd6935dfd1c91d4c9c3a
 SHA512:
-  metadata.gz: 522b879eb66e52848f47c987195d801ee62b59ceb86d3cc54211287bf87b85452649413c4754623b5aba4ae1b463b3c6f17befef452c3b5720be4cc08083c550
-  data.tar.gz: 74a86bddb8eed2b813ddc73f1d0f1fc2bd9c6b00737cdf680060af06e0b38415abbe9fc0b8e4b600f36f4a885c1dfd0552d9d53ad4317da647202d9b24602a99
+  metadata.gz: e32a32e6561612bee6e576851bad30ada292cce9b3a6096c8db9298ce5c30f892095b8687e0353417505732abb87664f19173eb352957993d52257d76d4b1209
+  data.tar.gz: d38a5cf9783d0d7cac6ddeee2f8ff5c2cd5762b9c6d3a96da7da8a89470d98d9c6f52a3706bb0033c607b67e40100ceafe12f727efed16700f20859bada631ba

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [0.13.0] - 2025-04-25
+### Added
+- Added support for committing batch mailings via `commit_batch` method
+- Added ability to change batch status from "uncommitted" to "committed"
+
+## [0.12.1] - 2025-04-24
+### Added
+- Added Russian translations for batch statuses:
+  - 'uncommitted' -> 'В обработке' (in processing)
+  - 'committed' -> 'Сформирована' (formed)
+- New `BatchStatus` class for working with batch status values
+- Added `translate_batch_status` method for translating batch status values
+
+## [0.12.0] - 2025-04-24
+### Added
+- Added support for downloading batch mailing documents as ZIP archives via `download_batch_documents` method
+- New `get_binary` method in ApiService to handle binary data downloads
+
+## [0.11.2] - 2025-04-24
+### Added
+- Added support for generating address labels for batch mailings via `generate_batch_blanks` method
+- Support for generating address labels for shipments within batches with "In processing" status
+- Generation of PS112e form for batches with "is_partial_receipt" flag set to true that contain shipments with attachments
+
 ## [0.11.1] - 2025-04-24
 ### Changed
 - Enhanced validation for batch item schema to allow empty strings for `cash_on_delivery` and `declared_value` fields

data/README.md

@@ -356,6 +356,70 @@ filtered_batches = client.list_batches(
 )
 ```
 
+### Generating address labels for a batch
+
+```ruby
+client = Belpost::Client.new
+
+# Generate address labels for a batch with ID 17292
+documents = client.generate_batch_blanks(17292)
+puts documents
+
+# The response will contain document information with the following structure:
+# {
+#   "documents" => {
+#     "id" => 8660,
+#     "list_id" => 17292,
+#     "status" => "processing",
+#     "path" => nil,
+#     "expire_at" => nil,
+#     "created_at" => "2024-11-06 13:18:59",
+#     "updated_at" => "2024-11-06 16:03:36",
+#     "name" => "Партия (заказ) №91"
+#   }
+# }
+```
+
+Note: Address labels can only be generated for batches with the "In processing" status. When you make this request, all address labels for shipments within the batch will be regenerated. Label generation is available if the batch has the "has_documents_label" flag set to false.
+
+If the batch has the "is_partial_receipt" flag set to true and contains shipments with attachments, a PS112e form with attachment descriptions will be included in the response ZIP archive.
+
+### Committing a batch
+
+After a batch has been created and filled with items, you can commit it to change its status from "uncommitted" (or "В обработке") to "committed" (or "Сформирована").
+
+```ruby
+# Commit a batch with ID 19217
+result = client.commit_batch(19217)
+puts "New status: #{result["status"]}" # => "committed"
+```
+
+Note: You can only commit a batch that is currently uncommitted, has items, and includes contents if the batch has the "is_partial_receipt" flag set to true.
+
+### Downloading batch documents
+
+```ruby
+client = Belpost::Client.new
+
+# Generate address labels for a batch with ID 17292
+documents = client.generate_batch_blanks(17292)
+puts documents
+
+# The response will contain document information with the following structure:
+# {
+#   "documents" => {
+#     "id" => 8660,
+#     "list_id" => 17292,
+#     "status" => "processing",
+#     "path" => nil,
+#     "expire_at" => nil,
+#     "created_at" => "2024-11-06 13:18:59",
+#     "updated_at" => "2024-11-06 16:03:36",
+#     "name" => "Партия (заказ) №91"
+#   }
+# }
+```
+
 ## Error handling
 
 The client may throw the following exceptions:

data/lib/belpost/api_paths.rb

@@ -5,13 +5,14 @@ module Belpost
   module ApiPaths
     # Batch mailing paths
     BATCH_MAILING_LIST = "/api/v1/business/batch-mailing/list"
+    BATCH_MAILING_LIST_BY_ID = "/api/v1/business/batch-mailing/list/:id"
     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"
+    BATCH_MAILING_DOCUMENTS_DOWNLOAD = "/api/v1/batch-mailing/documents/:id/download"
 
     # Postal deliveries paths
     POSTAL_DELIVERIES = "/api/v1/business/postal-deliveries"

data/lib/belpost/api_service.rb

@@ -47,6 +47,31 @@ module Belpost
         end
       end
     end
+    
+    # Performs a GET request to the specified path and returns binary data.
+    #
+    # @param path [String] The API endpoint path.
+    # @param params [Hash] The query parameters (default: {}).
+    # @return [Hash] Hash containing binary data, status code and headers
+    def get_binary(path, params = {})
+      Retry.with_retry do
+        uri = URI("#{@base_url}#{path}")
+        uri.query = URI.encode_www_form(params) unless params.empty?
+        request = Net::HTTP::Get.new(uri)
+        add_headers(request)
+        request["Accept"] = "*/*"  # Override Accept header to receive any content type
+
+        log_request(request)
+        response = execute_request(uri, request)
+        log_response(response, binary: true)
+
+        {
+          data: response.body,
+          status_code: response.code.to_i,
+          headers: response.to_hash
+        }
+      end
+    end
 
     # Performs a POST request to the specified path with the given body.
     #
@@ -188,23 +213,58 @@ module Belpost
       end
     end
 
+    # Logs the HTTP request details.
+    #
+    # @param request [Net::HTTP::Request] The HTTP request object.
+    def log_request(request)
+      @logger.info("API Request: #{request.method} #{request.uri}")
+      @logger.debug("Request Headers: #{request.each_header.to_h}") if request.respond_to?(:each_header)
+      @logger.debug("Request Body: #{request.body}") if request.body
+    end
+
+    # Logs the HTTP response details.
+    #
+    # @param response [Net::HTTP::Response] The HTTP response object.
+    # @param binary [Boolean] If this is a binary response (default: false).
+    def log_response(response, binary: false)
+      status_message = response.respond_to?(:message) ? " #{response.message}" : ""
+      @logger.info("API Response: #{response.code}#{status_message}")
+      
+      if response.respond_to?(:each_header)
+        @logger.debug("Response Headers: #{response.each_header.to_h}")
+      elsif response.respond_to?(:to_hash)
+        @logger.debug("Response Headers: #{response.to_hash}")
+      end
+      
+      if binary
+        @logger.debug("Response Body: [BINARY DATA]")
+      else
+        @logger.debug("Response Body: #{response.body}")
+      end
+    end
+
+    # Handles the HTTP response.
+    #
+    # @param response [Net::HTTP::Response] The HTTP response object.
+    # @return [Net::HTTP::Response] The HTTP response object if successful.
+    # @raise [Belpost::ApiError] If the API returns an error response.
     def handle_response(response)
-      case response.code
-      when "200", "201"
+      case response.code.to_i
+      when 200..299
         response
-      when "401", "403"
+      when 401, 403
         raise AuthenticationError.new(
           "Authentication failed",
           status_code: response.code.to_i,
           response_body: response.body
         )
-      when "429"
+      when 429
         raise RateLimitError.new(
           "Rate limit exceeded",
           status_code: response.code.to_i,
           response_body: response.body
         )
-      when "400"
+      when 400
         raise InvalidRequestError.new(
           "Invalid request",
           status_code: response.code.to_i,
@@ -218,17 +278,5 @@ module Belpost
         )
       end
     end
-
-    def log_request(request)
-      @logger.info("Making #{request.method} request to #{request.uri}")
-      @logger.debug("Request headers: #{request.to_hash}")
-      @logger.debug("Request body: #{request.body}") if request.body
-    end
-
-    def log_response(response)
-      @logger.info("Received response with status #{response.code}")
-      @logger.debug("Response headers: #{response.to_hash}")
-      @logger.debug("Response body: #{response.body}")
-    end
   end
 end

data/lib/belpost/client.rb

@@ -4,6 +4,7 @@ require_relative "api_service"
 require_relative "models/parcel"
 require_relative "models/batch"
 require_relative "models/batch_item"
+require_relative "models/batch_status"
 require_relative "models/api_response"
 require_relative "validations/address_schema"
 require_relative "validations/batch_schema"
@@ -112,12 +113,14 @@ module Belpost
     #
     # @param id [Integer] The ID of the batch to find.
     # @return [Hash] The batch data if found.
+    # @raise [Belpost::ValidationError] If the ID parameter is invalid
     # @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}")
+      path = ApiPaths::BATCH_MAILING_LIST_BY_ID.gsub(':id', id.to_s)
+      response = @api_service.get(path)
       response.to_h
     end
 
@@ -205,7 +208,7 @@ module Belpost
 
       # Validate status parameter
       if status
-        unless %w[committed uncommitted].include?(status)
+        unless Models::BatchStatus.valid?(status)
           raise ValidationError, "Status must be 'committed' or 'uncommitted'"
         end
 
@@ -231,6 +234,84 @@ module Belpost
       response.to_h
     end
 
+    # Generates address labels for a batch mailing.
+    #
+    # This method allows generating address labels for shipments within a batch.
+    # Labels can only be generated for batches with the "In processing" status.
+    # When this request is made, all address labels for shipments within the batch will be regenerated.
+    # Label generation is available if the batch has the "has_documents_label" flag set to false.
+    #
+    # If the batch has the "is_partial_receipt" flag set to true and contains shipments with attachments,
+    # a PS112e form with attachment descriptions will be included in the response ZIP archive.
+    #
+    # If the batch has the "is_partial_receipt" flag set to true and contains shipments without attachments,
+    # address labels will not be generated for those shipments. Adding attachments to a shipment is mandatory
+    # for generating address labels in this case.
+    #
+    # @param batch_id [Integer] The ID of the batch to generate labels for
+    # @return [Hash] The parsed JSON response containing document information
+    # @raise [Belpost::ValidationError] If the batch_id parameter is invalid
+    # @raise [Belpost::ApiError] If the API returns an error response
+    def generate_batch_blanks(batch_id)
+      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?
+
+      path = ApiPaths::BATCH_MAILING_GENERATE_BLANK.gsub(':id', batch_id.to_s)
+      response = @api_service.post(path, {})
+      response.to_h
+    end
+
+    # Commits a batch mailing by its ID, changing status from "uncommitted" to "committed".
+    #
+    # This method can only commit a batch that is currently uncommitted, has items and 
+    # includes contents if the batch has "is_partial_receipt" flag set to true.
+    #
+    # @param batch_id [Integer] The ID of the batch to commit
+    # @return [Hash] The committed batch data with updated status
+    # @raise [Belpost::ValidationError] If the batch_id parameter is invalid
+    # @raise [Belpost::ApiError] If the API returns an error response
+    def commit_batch(batch_id)
+      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?
+
+      path = ApiPaths::BATCH_MAILING_COMMIT.gsub(':id', batch_id.to_s)
+      response = @api_service.post(path, {})
+      response.to_h
+    end
+
+    # Downloads batch mailing documents as a ZIP archive.
+    #
+    # This method retrieves a ZIP archive containing all documents related to a batch mailing.
+    # The response contains binary data that can be saved as a ZIP file.
+    #
+    # @param document_id [Integer] The ID of the document to download
+    # @return [Hash] Hash containing binary data, status code and headers
+    # @raise [Belpost::ValidationError] If the document_id parameter is invalid
+    # @raise [Belpost::ApiError] If the API returns an error response
+    def download_batch_documents(document_id)
+      raise ValidationError, "Document ID must be provided" if document_id.nil?
+      raise ValidationError, "Document ID must be a positive integer" unless document_id.is_a?(Integer) && document_id.positive?
+
+      path = ApiPaths::BATCH_MAILING_DOCUMENTS_DOWNLOAD.gsub(':id', document_id.to_s)
+      response = @api_service.get_binary(path)
+      
+      # Ensure we have the correct content type for a ZIP file
+      content_type = response[:headers]["content-type"]&.first
+      unless content_type && content_type.include?("application/zip")
+        @logger.warn("Expected ZIP file but got content type: #{content_type}")
+      end
+      
+      response
+    end
+
+    # Translates a batch status code to its Russian translation
+    #
+    # @param status [String] The status code ('uncommitted' or 'committed')
+    # @return [String] The Russian translation or the original status if not found
+    def translate_batch_status(status)
+      Models::BatchStatus.translate(status)
+    end
+
     private
 
     def format_address(address)

data/lib/belpost/models/batch_status.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Belpost
+  module Models
+    # Helper class for batch status translations and utilities
+    class BatchStatus
+      # Mapping of status codes to their Russian translations
+      TRANSLATIONS = {
+        "uncommitted" => "В обработке",
+        "committed" => "Сформирована"
+      }.freeze
+
+      # Get the Russian translation for a status
+      #
+      # @param status [String] The status code ('uncommitted' or 'committed')
+      # @return [String] The Russian translation or the original status if not found
+      def self.translate(status)
+        TRANSLATIONS[status] || status
+      end
+
+      # Get all possible statuses
+      #
+      # @return [Array<String>] Array of all possible status values
+      def self.all
+        %w[uncommitted committed]
+      end
+
+      # Check if a status is valid
+      #
+      # @param status [String] The status to check
+      # @return [Boolean] True if valid, false otherwise
+      def self.valid?(status)
+        all.include?(status)
+      end
+    end
+  end
+end 

data/lib/belpost/postal_delivery_types.rb

@@ -71,8 +71,7 @@ module Belpost
       ecommerce_optima: {
         negotiated_rate: false,
         declared_value: [true, false],
-        partial_receipt: false,
-        postal_items_in_ops: [true, false]
+        partial_receipt: false
       }
     }.freeze
 

data/lib/belpost/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belpost
-  VERSION = "0.11.1"
+  VERSION = "0.13.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belpost
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.1
 platform: ruby
 authors:
 - KuberLite
@@ -77,6 +77,7 @@ files:
 - lib/belpost/models/api_response.rb
 - lib/belpost/models/batch.rb
 - lib/belpost/models/batch_item.rb
+- lib/belpost/models/batch_status.rb
 - lib/belpost/models/customs_declaration.rb
 - lib/belpost/models/parcel.rb
 - lib/belpost/models/parcel_builder.rb