atol 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4959c1454e46f59413f73210058077f89a59eb076d698d1b9b18d3fe9c5df262
-  data.tar.gz: 82ecf864b3a298e28e96c845177809e9a11a72be7e27feedd05c95a6b86a3452
+  metadata.gz: 17a1f879f910bd053721385602bc4e3c158dc10625534db847d78bdb54ee75e4
+  data.tar.gz: 8408f2c974e2e49c3dd89745e942cc06375fbcbf050d843015fdd17d8839eae4
 SHA512:
-  metadata.gz: ee8fbffc698f9f766c57d9d2651ff66763841c683e8d1a082664cf9b82b222ccc11cda53bfca79561f33009a9caac566cb1e13e64613ed18c4abb2dbb3e98af1
-  data.tar.gz: 4bc13aae1a3a6a0b5942c1de81dd724ca496289c584254fc622b103fabb1834471c9b7c01bc065f5f880cdbfcda30c2752172dde4f7e661c51ec5674d6b0102d
+  metadata.gz: 05c52df6c9b2bfcd04c47a09a2e71f1e1eec304809cba41c1e858431c6a141eeca774191ebd8488c88a97225dad0a3524af12d9bc018d0c66a29a0a279b81698
+  data.tar.gz: 5e034691a9b942dab227b3c2341b1379aebe787d6b71b9eee895387c8caee014e17da56a1588b2479d9852c21e5fe5646ef2ef7bcb15fc26141e4be7bdc90c37

data/.rubocop.yml

@@ -11,4 +11,6 @@ Metrics/LineLength:
 
 Metrics/ParameterLists:
   Exclude:
-    - lib/atol/request/post_document/item/body.rb
+    - lib/atol/request/post_document/item/body.rb
+    - lib/atol/request/post_document/sell/body.rb
+    - lib/atol/request/post_document/correction/v5/body.rb

data/README.md

@@ -255,6 +255,46 @@ Atol::Request::PostDocument::Sell::Body.new(
 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23
 ```
 
+#### Кастомные payments
+
+По умолчанию `Sell::Body` формирует один платёж с типом из конфигурации (`default_payment_type`) и суммой, равной итогу позиций. Если нужны другие виды оплаты (например, зачёт аванса — тег 1215, тип `2`), можно передать массив объектов `Atol::Request::PostDocument::Payment` явно. Сумма платежей должна совпадать с итогом позиций, иначе конструктор бросит `Atol::PaymentsTotalMismatchError`.
+
+```ruby
+payments = [
+  Atol::Request::PostDocument::Payment.new(
+    type: Atol::Request::PostDocument::Payment::PREPAID_TYPE,
+    sum: 200.0
+  )
+]
+Atol::Request::PostDocument::Sell::Body.new(
+  external_id: 123,
+  email: 'example@example.com',
+  items: [item],
+  payments: payments
+).to_json
+```
+
+Виды оплаты (`type`) — константы класса `Atol::Request::PostDocument::Payment`: `CASH_TYPE` наличные (1031), `CASHLESS_TYPE` безналичный (1081), `PREPAID_TYPE` предоплата/зачёт аванса (1215), `POSTPAID_TYPE` постоплата/кредит (1216), `COUNTER_PROVISION_TYPE` встречное предоставление (1217), `EXTENDED_5_TYPE`–`EXTENDED_9_TYPE` расширенные.
+
+#### Чек коррекции для версии V5
+
+Для тела чека коррекции используется класс `Atol::Request::PostDocument::Correction::Body` — он выбирает реализацию по `config.api_url`, как и `Item::Body`. Реализован только ФФД 1.2 (`Correction::V5::Body`, операции `sell_refund_correction`, `sell_correction` и т.п.); для v4-эндпоинта (ФФД 1.05) тело коррекции не реализовано и конструктор бросит `Atol::Request::PostDocument::Correction::Body::BadApiUrlError`.
+
+Обязательные аргументы: `external_id`, `items`, `correction_type` (`self` или `instruction`) и `base_date` (дата корректируемого расчёта в формате `dd.mm.yyyy`, тег 1178), а также хотя бы один контакт клиента — `phone` или `email`. Необязательные: `base_number` — номер документа-основания (тег 1179, не более 32 байт); `additional_check_props` — дополнительный реквизит чека/БСО (тег 1192, не более 16 байт); и `payments` (как и в `Sell::Body`, при отсутствии формируется один платёж из `default_payment_type` с суммой, равной итогу позиций; переданная сумма платежей должна совпадать с итогом позиций).
+
+```ruby
+body = Atol::Request::PostDocument::Correction::Body.new(
+  external_id: 123,
+  email: 'example@example.com',
+  items: [...],
+  correction_type: 'self',
+  base_date: '01.01.2026',
+  base_number: '12345'
+).to_json
+
+Atol::Transaction::PostDocument.new(operation: :sell_refund_correction, token: token, body: body).call
+```
+
 #### Отправка документа
 
 Когда токен и тело запроса составлены, остается только сделать post-запрос.

data/lib/atol/errors.rb

@@ -18,6 +18,9 @@ module Atol
   class StateMissingUuidError < StandardError; end
   class StateNotFoundError < StandardError; end
   class ZeroItemQuantityError < StandardError; end
+  class BadPaymentError < StandardError; end
+  class EmptyPaymentsError < StandardError; end
+  class PaymentsTotalMismatchError < StandardError; end
 
   ERRORS = Hash[
       0 => BadJSONError,

data/lib/atol/request/post_document/correction/body.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Atol
+  module Request
+    class PostDocument
+      module Correction
+        class Body
+          BadApiUrlError = Class.new(StandardError)
+
+          attr_reader :instance
+
+          def initialize(**kwargs)
+            config = kwargs[:config] || Atol.config
+            @instance = case config.api_url
+                        when Atol::Version::V5, Atol::Version::V5_TEST
+                          Atol::Request::PostDocument::Correction::V5::Body.new(**kwargs)
+                        when Atol::Version::V4, Atol::Version::V4_TEST
+                          raise BadApiUrlError, 'correction body for the v4 api is not implemented'
+                        else
+                          raise BadApiUrlError
+                        end
+          end
+
+          def to_h
+            instance.to_h
+          end
+
+          def to_json(*args)
+            instance.to_json(*args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/atol/request/post_document/correction/v5/body.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'atol/errors'
+require 'atol/request/post_document/payment'
+
+module Atol
+  module Request
+    class PostDocument
+      module Correction
+        module V5
+          class Body
+            class BadCorrectionTypeError < StandardError; end
+            class BadCorrectionBaseDateError < StandardError; end
+            class BadCorrectionBaseNumberError < StandardError; end
+            class BadAdditionalCheckPropsError < StandardError; end
+
+            CORRECTION_TYPES = %w[self instruction].freeze
+            BASE_DATE_FORMAT = /\A\d{2}\.\d{2}\.\d{4}\z/
+            BASE_NUMBER_MAX_BYTESIZE = 32
+            ADDITIONAL_CHECK_PROPS_MAX_BYTESIZE = 16
+
+            def initialize(external_id:, items:, correction_type:, base_date:, phone: '', email: '',
+                           payments: nil, base_number: nil, additional_check_props: nil, config: nil, **options)
+              raise(Atol::EmptyClientContactError) if phone.empty? && email.empty?
+              raise(Atol::EmptySellItemsError) if items.empty?
+              raise(BadCorrectionTypeError) unless CORRECTION_TYPES.include?(correction_type)
+              raise(BadCorrectionBaseDateError) unless base_date.to_s.match?(BASE_DATE_FORMAT)
+              raise(BadCorrectionBaseNumberError) if base_number && base_number.to_s.bytesize > BASE_NUMBER_MAX_BYTESIZE
+              if additional_check_props && additional_check_props.to_s.bytesize > ADDITIONAL_CHECK_PROPS_MAX_BYTESIZE
+                raise(BadAdditionalCheckPropsError)
+              end
+
+              total = items.sum { |item| item[:sum] }
+              validate_payments!(payments, total)
+
+              @config = config || Atol.config
+              @external_id = external_id
+              @phone = phone
+              @email = email
+              @items = items
+              @correction_type = correction_type
+              @base_date = base_date
+              @base_number = base_number
+              @additional_check_props = additional_check_props
+              @total = total
+              @payments = payments
+            end
+
+            def to_h
+              build_body.clone
+            end
+
+            def to_json(*_args)
+              build_body.to_json
+            end
+
+            private
+
+            attr_reader :config, :external_id, :phone, :email, :items, :payments,
+                        :correction_type, :base_date, :base_number, :additional_check_props, :total
+
+            def validate_payments!(payments, total)
+              return if payments.nil?
+
+              raise(Atol::EmptyPaymentsError) if payments.empty?
+              raise(Atol::BadPaymentError) if payments.any? { |payment| !payment.is_a?(Payment) }
+              raise(Atol::PaymentsTotalMismatchError) unless payments.sum(&:sum).round(2) == total.round(2)
+            end
+
+            def build_body
+              {
+                external_id: external_id,
+                correction: correction,
+                service: service,
+                timestamp: Time.now.strftime(Atol::TIMESTAMP_FORMAT)
+              }
+            end
+
+            def correction
+              result = {
+                client: client,
+                company: company,
+                correction_info: correction_info,
+                items: items,
+                payments: build_payments,
+                total: total,
+                internet: config.internet
+              }
+              result[:additional_check_props] = additional_check_props if additional_check_props
+
+              result
+            end
+
+            def client
+              result = {}
+              result[:email] = email unless email.empty?
+              result[:phone] = phone unless phone.empty?
+
+              result
+            end
+
+            def company
+              {
+                inn: config.inn.to_s,
+                sno: config.default_sno,
+                payment_address: config.payment_address,
+                email: config.company_email
+              }
+            end
+
+            def build_payments
+              (payments || [Payment.new(type: config.default_payment_type, sum: total)]).map(&:to_h)
+            end
+
+            def service
+              config.callback_url ? { callback_url: config.callback_url } : {}
+            end
+
+            def correction_info
+              info = { type: correction_type, base_date: base_date }
+              info[:base_number] = base_number if base_number
+
+              info
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/atol/request/post_document/payment.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'atol/errors'
+
+module Atol
+  module Request
+    class PostDocument
+      class Payment
+        CASH_TYPE = 0                   # наличные
+        CASHLESS_TYPE = 1               # безналичный
+        PREPAID_TYPE = 2                # предоплата/зачёт аванса (тег 1215)
+        POSTPAID_TYPE = 3               # постоплата/кредит
+        COUNTER_PROVISION_TYPE = 4      # встречное предоставление
+        EXTENDED_5_TYPE = 5             # расширенный тип оплаты 5
+        EXTENDED_6_TYPE = 6             # расширенный тип оплаты 6
+        EXTENDED_7_TYPE = 7             # расширенный тип оплаты 7
+        EXTENDED_8_TYPE = 8             # расширенный тип оплаты 8
+        EXTENDED_9_TYPE = 9             # расширенный тип оплаты 9
+
+        TYPES = [
+          CASH_TYPE, CASHLESS_TYPE, PREPAID_TYPE, POSTPAID_TYPE, COUNTER_PROVISION_TYPE,
+          EXTENDED_5_TYPE, EXTENDED_6_TYPE, EXTENDED_7_TYPE, EXTENDED_8_TYPE, EXTENDED_9_TYPE
+        ].freeze
+
+        attr_reader :type, :sum
+
+        def initialize(type:, sum:)
+          raise(Atol::BadPaymentError, 'not allowed type') unless TYPES.include?(type)
+          raise(Atol::BadPaymentError, 'sum must be zero or a positive number') unless sum.is_a?(Numeric) && sum >= 0
+
+          @type = type
+          @sum = sum
+        end
+
+        def to_h
+          { sum: sum, type: type }
+        end
+      end
+    end
+  end
+end

data/lib/atol/request/post_document/sell/body.rb

@@ -1,82 +1,88 @@
 # frozen_string_literal: true
 
 require 'atol/errors'
+require 'atol/request/post_document/payment'
 
 module Atol
   module Request
     class PostDocument
       module Sell
         class Body
-          def initialize(external_id:, phone: '', email: '', items:, config: nil, **options)
+          def initialize(external_id:, phone: '', email: '', items:, payments: nil, config: nil, **options)
             raise(Atol::EmptyClientContactError) if phone.empty? && email.empty?
             raise(Atol::EmptySellItemsError) if items.empty?
 
+            total = items.sum { |item| item[:sum] }
+            validate_payments!(payments, total)
+
             @config = config || Atol.config
             @external_id = external_id
             @phone = phone
             @email = email
             @items = items
+            @total = total
+            @payments = payments
           end
 
           def to_h
-            body.clone
+            build_body.clone
           end
 
           def to_json(*_args)
-            body.to_json
+            build_body.to_json
           end
 
           private
 
-          def body
-            body_template.tap do |result|
-              receipt = result[:receipt]
-              client = receipt[:client]
+          attr_reader :config, :external_id, :phone, :email, :items, :payments, :total
 
-              result[:external_id] = @external_id
-              result[:service][:callback_url] = @config.callback_url if @config.callback_url
+          def validate_payments!(payments, total)
+            return if payments.nil?
 
-              add_client_data(client)
-              add_receipt_data(receipt)
-            end
+            raise(Atol::EmptyPaymentsError) if payments.empty?
+            raise(Atol::BadPaymentError) if payments.any? { |payment| !payment.is_a?(Payment) }
+            raise(Atol::PaymentsTotalMismatchError) unless payments.sum(&:sum).round(2) == total.round(2)
           end
 
-          def body_template
+          def build_body
             {
+              external_id: external_id,
               receipt: {
-                client: {},
-                company: {
-                  inn: @config.inn.to_s,
-                  sno: @config.default_sno,
-                  payment_address: @config.payment_address,
-                  email: @config.company_email
-                },
-                items: [],
-                payments: [
-                  {
-                    sum: 0,
-                    type: @config.default_payment_type
-                  }
-                ]
+                client: client,
+                company: company,
+                items: items,
+                payments: build_payments,
+                total: total,
+                internet: config.internet
               },
-              service: {},
+              service: service,
               timestamp: Time.now.strftime(Atol::TIMESTAMP_FORMAT)
             }
           end
 
-          def add_client_data(client)
-            client[:email] = @email unless @email.empty?
-            client[:phone] = @phone unless @phone.empty?
+          def client
+            result = {}
+            result[:email] = email unless email.empty?
+            result[:phone] = phone unless phone.empty?
+
+            result
+          end
+
+          def company
+            {
+              inn: config.inn.to_s,
+              sno: config.default_sno,
+              payment_address: config.payment_address,
+              email: config.company_email
+            }
           end
 
-          def add_receipt_data(receipt)
-            receipt[:total] = receipt[:payments][0][:sum] = total
-            receipt[:items] = @items
-            receipt[:internet] = @config.internet
+          def build_payments
+            (payments || [Payment.new(type: config.default_payment_type, sum: total)]).map(&:to_h)
           end
 
-          def total
-            @total ||= @items.inject(0) { |sum, item| sum += item[:sum] }
+          def service
+            config.callback_url ? { callback_url: config.callback_url } : {}
           end
         end
       end

data/lib/atol/request/post_document.rb

@@ -6,6 +6,8 @@ require 'atol/request/post_document/item/body'
 require 'atol/request/post_document/item/v4/body'
 require 'atol/request/post_document/item/v5/body'
 require 'atol/request/post_document/sell/body'
+require 'atol/request/post_document/correction/body'
+require 'atol/request/post_document/correction/v5/body'
 
 module Atol
   module Request

data/lib/atol/version.rb

@@ -8,6 +8,6 @@ module Atol
     V4_TEST = 'https://testonline.atol.ru/possystem/v4'
     V5_TEST = 'https://testonline.atol.ru/possystem/v5'
 
-    LIB = '1.1.0'
+    LIB = '1.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atol
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - GeorgeGorbanev
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: anyway_config
@@ -94,7 +94,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description:
+description: 
 email:
 - GeorgeGorbanev@gmail.com
 executables: []
@@ -119,9 +119,12 @@ files:
 - lib/atol/request/get_document_state.rb
 - lib/atol/request/get_token.rb
 - lib/atol/request/post_document.rb
+- lib/atol/request/post_document/correction/body.rb
+- lib/atol/request/post_document/correction/v5/body.rb
 - lib/atol/request/post_document/item/body.rb
 - lib/atol/request/post_document/item/v4/body.rb
 - lib/atol/request/post_document/item/v5/body.rb
+- lib/atol/request/post_document/payment.rb
 - lib/atol/request/post_document/sell/body.rb
 - lib/atol/transaction.rb
 - lib/atol/transaction/get_document_state.rb
@@ -132,7 +135,7 @@ homepage: https://github.com/sputnik8/atol-rb
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -147,8 +150,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: ATOL KaaS client for Ruby
 test_files: []