cdek_api_client 0.2.0 → 0.3.0

data/lib/cdek_api_client/api/order.rb

@@ -29,8 +29,63 @@ module CDEKApiClient
         handle_response(response)
       end
 
+      # Deletes an order by its UUID.
+      #
+      # @param order_uuid [String] the UUID of the order to delete.
+      # @return [Hash] the response from the API.
+      def delete(order_uuid)
+        validate_uuid(order_uuid)
+        response = @client.request('delete', "orders/#{order_uuid}")
+        handle_response(response)
+      end
+
+      # Cancels an order by its UUID.
+      #
+      # @param order_uuid [String] the UUID of the order to cancel.
+      # @return [Hash] the response from the API.
+      def cancel(order_uuid)
+        validate_uuid(order_uuid)
+        response = @client.request('post', "orders/#{order_uuid}/refusal")
+        handle_response(response)
+      end
+
+      # Updates an existing order.
+      #
+      # @param order_data [CDEKApiClient::Entities::OrderData] the updated order data.
+      # @return [Hash] the response from the API.
+      def update(order_data)
+        response = @client.request('patch', 'orders', body: order_data)
+        handle_response(response)
+      end
+
+      # Gets order information by CDEK number.
+      #
+      # @param cdek_number [String] the CDEK order number.
+      # @return [Hash] the order information.
+      def get_by_cdek_number(cdek_number)
+        response = @client.request('get', 'orders', query: { cdek_number: cdek_number })
+        handle_response(response)
+      end
+
+      # Gets order information by IM number.
+      #
+      # @param im_number [String] the IM order number.
+      # @return [Hash] the order information.
+      def get_by_im_number(im_number)
+        response = @client.request('get', 'orders', query: { im_number: im_number })
+        handle_response(response)
+      end
+
       private
 
+      # Validates UUID format.
+      #
+      # @param uuid [String] the UUID to validate.
+      # @raise [ArgumentError] if the UUID format is invalid.
+      def validate_uuid(uuid)
+        @client.validate_uuid(uuid)
+      end
+
       # Handles the response from the API.
       #
       # @param response [Net::HTTPResponse] the response from the API.

data/lib/cdek_api_client/api/payment.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  module API
+    # Handles payment and registry-related API requests.
+    class Payment
+      # Initializes the Payment object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Gets payment information for a specific date.
+      #
+      # @param date [String] the date in YYYY-MM-DD format.
+      # @return [Hash] the payment information.
+      def get_payments(date)
+        response = @client.request('get', 'payment', query: { date: date })
+        handle_response(response)
+      end
+
+      # Gets check information.
+      #
+      # @param check_data [CDEKApiClient::Entities::Check] the check data.
+      # @return [Hash] the check information.
+      def get_checks(check_data)
+        response = @client.request('get', 'check', query: check_data)
+        handle_response(response)
+      end
+
+      # Gets registry information for a specific date.
+      #
+      # @param date [String] the date in YYYY-MM-DD format.
+      # @return [Hash] the registry information.
+      def get_registries(date)
+        response = @client.request('get', 'registries', query: { date: date })
+        handle_response(response)
+      end
+
+      private
+
+      # Handles the response from the API.
+      #
+      # @param response [Net::HTTPResponse] the response from the API.
+      # @return [Hash] the parsed response.
+      def handle_response(response)
+        @client.send(:handle_response, response)
+      end
+    end
+  end
+end

data/lib/cdek_api_client/api/print.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  module API
+    # Handles print-related API requests (barcodes and invoices).
+    class Print
+      # Initializes the Print object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Creates a barcode for an order.
+      #
+      # @param barcode_data [CDEKApiClient::Entities::Barcode] the barcode data.
+      # @return [Hash] the response from the API.
+      def create_barcode(barcode_data)
+        response = @client.request('post', 'print/barcodes', body: barcode_data)
+        handle_response(response)
+      end
+
+      # Gets barcode information by UUID.
+      #
+      # @param barcode_uuid [String] the UUID of the barcode.
+      # @return [Hash] the barcode information.
+      def get_barcode(barcode_uuid)
+        response = @client.request('get', "print/barcodes/#{barcode_uuid}")
+        handle_response(response)
+      end
+
+      # Gets barcode PDF by UUID.
+      #
+      # @param barcode_uuid [String] the UUID of the barcode.
+      # @return [String] the PDF content.
+      def get_barcode_pdf(barcode_uuid)
+        response = @client.request('get', "print/barcodes/#{barcode_uuid}.pdf")
+        handle_binary_response(response)
+      end
+
+      # Creates an invoice for an order.
+      #
+      # @param invoice_data [CDEKApiClient::Entities::Invoice] the invoice data.
+      # @return [Hash] the response from the API.
+      def create_invoice(invoice_data)
+        response = @client.request('post', 'print/orders', body: invoice_data)
+        handle_response(response)
+      end
+
+      # Gets invoice information by UUID.
+      #
+      # @param invoice_uuid [String] the UUID of the invoice.
+      # @return [Hash] the invoice information.
+      def get_invoice(invoice_uuid)
+        response = @client.request('get', "print/orders/#{invoice_uuid}")
+        handle_response(response)
+      end
+
+      # Gets invoice PDF by UUID.
+      #
+      # @param invoice_uuid [String] the UUID of the invoice.
+      # @return [String] the PDF content.
+      def get_invoice_pdf(invoice_uuid)
+        response = @client.request('get', "print/orders/#{invoice_uuid}.pdf")
+        handle_binary_response(response)
+      end
+
+      private
+
+      # Handles the response from the API.
+      #
+      # @param response [Net::HTTPResponse] the response from the API.
+      # @return [Hash] the parsed response.
+      def handle_response(response)
+        @client.send(:handle_response, response)
+      end
+
+      # Handles binary responses (PDF files).
+      #
+      # @param response [Net::HTTPResponse] the response from the API.
+      # @return [String] the binary content.
+      def handle_binary_response(response)
+        case response
+        when Net::HTTPSuccess
+          response.body
+        else
+          handle_response(response)
+        end
+      end
+    end
+  end
+end

data/lib/cdek_api_client/api/tariff.rb

@@ -18,6 +18,15 @@ module CDEKApiClient
       def calculate(tariff_data)
         @client.request('post', 'calculator/tariff', body: tariff_data)
       end
+
+      # Calculates all available tariffs.
+      #
+      # @param tariff_data [CDEKApiClient::Entities::TariffData] the data for the tariff calculation.
+      # @return [Array<Hash>] the list of available tariffs.
+      def calculate_list(tariff_data)
+        response = @client.request('post', 'calculator/tarifflist', body: tariff_data)
+        response.is_a?(Hash) && response.key?('tariff_codes') ? response['tariff_codes'] : response
+      end
     end
   end
 end

data/lib/cdek_api_client/api/track_order.rb

@@ -22,7 +22,7 @@ module CDEKApiClient
       def get(order_uuid)
         validate_uuid(order_uuid)
 
-        response = @client.auth_connection.get(format(TRACK_ORDER_URL, uuid: order_uuid))
+        response = @client.request('get', "orders/#{order_uuid}")
         handle_response(response)
       end
 
@@ -33,7 +33,7 @@ module CDEKApiClient
       # @param uuid [String] the UUID to validate.
       # @raise [ArgumentError] if the UUID is invalid.
       def validate_uuid(uuid)
-        @client.send(:validate_uuid, uuid)
+        @client.validate_uuid(uuid)
       end
 
       # Handles the response from the API.

data/lib/cdek_api_client/api/webhook.rb

@@ -20,6 +20,21 @@ module CDEKApiClient
         @client.send(:handle_response, response)
       end
 
+      # Registers a new webhook with simple parameters.
+      #
+      # @param url [String] the URL where the webhook will send data.
+      # @param event_types [Array<String>] the list of event types for the webhook.
+      # @param type [String] the type of webhook (default: 'WEBHOOK').
+      # @return [Hash] the response from the API.
+      def register_simple(url, event_types, type: 'WEBHOOK')
+        webhook_data = CDEKApiClient::Entities::Webhook.new(
+          url: url,
+          type: type,
+          event_types: event_types
+        )
+        register(webhook_data)
+      end
+
       # Retrieves a list of registered webhooks.
       #
       # @return [Array<Hash>] the list of webhooks.
@@ -28,12 +43,29 @@ module CDEKApiClient
         @client.send(:handle_response, response)
       end
 
-      # Deletes a webhook by its ID.
+      # Retrieves a list of all registered webhooks.
+      #
+      # @return [Array<Hash>] the list of webhooks.
+      def list_all
+        response = @client.request('get', 'webhooks')
+        @client.send(:handle_response, response)
+      end
+
+      # Retrieves information about a specific webhook by its UUID.
+      #
+      # @param webhook_uuid [String] the UUID of the webhook.
+      # @return [Hash] the webhook information.
+      def get(webhook_uuid)
+        response = @client.request('get', "webhooks/#{webhook_uuid}")
+        @client.send(:handle_response, response)
+      end
+
+      # Deletes a webhook by its UUID.
       #
-      # @param webhook_id [String] the ID of the webhook to delete.
+      # @param webhook_uuid [String] the UUID of the webhook to delete.
       # @return [Hash] the response from the API.
-      def delete(webhook_id)
-        response = @client.request('delete', "webhooks/#{webhook_id}")
+      def delete(webhook_uuid)
+        response = @client.request('delete', "webhooks/#{webhook_uuid}")
         @client.send(:handle_response, response)
       end
     end

data/lib/cdek_api_client/client.rb

@@ -4,43 +4,62 @@ require 'net/http'
 require 'uri'
 require 'json'
 require 'logger'
+require_relative 'config'
+require_relative 'api/courier'
 require_relative 'api/location'
 require_relative 'api/order'
+require_relative 'api/payment'
+require_relative 'api/print'
 require_relative 'api/tariff'
 require_relative 'api/webhook'
+require_relative 'entities/auth_response'
+require_relative 'entities/auth_error_response'
 
 module CDEKApiClient
   # Client class for interacting with the CDEK API.
   class Client
-    BASE_URL = ENV.fetch('CDEK_API_URL', 'https://api.edu.cdek.ru/v2')
-    TOKEN_URL = "#{BASE_URL}/oauth/token".freeze
-
+    # @return [String] the base API URL
+    attr_reader :base_url
     # @return [String] the access token for API authentication.
     attr_reader :token
     # @return [Logger] the logger instance.
     attr_reader :logger
-    # @return [CDEKApiClient::Order] the order API interface.
-    attr_reader :order
+    # @return [CDEKApiClient::Courier] the courier API interface.
+    attr_reader :courier
     # @return [CDEKApiClient::Location] the location API interface.
     attr_reader :location
+    # @return [CDEKApiClient::Order] the order API interface.
+    attr_reader :order
+    # @return [CDEKApiClient::Payment] the payment API interface.
+    attr_reader :payment
+    # @return [CDEKApiClient::Print] the print API interface.
+    attr_reader :print
     # @return [CDEKApiClient::Tariff] the tariff API interface.
     attr_reader :tariff
     # @return [CDEKApiClient::Webhook] the webhook API interface.
     attr_reader :webhook
 
-    # Initializes the client with API credentials and logger.
+    # Initializes the client with API credentials and configuration.
     #
     # @param client_id [String] the client ID.
     # @param client_secret [String] the client secret.
+    # @param environment [Symbol, String] the API environment (:production or :demo).
+    #   Defaults to :demo or value from CDEK_API_ENV environment variable.
+    # @param base_url [String] custom API base URL (overrides environment).
+    #   Defaults to value from CDEK_API_URL environment variable or environment default.
     # @param logger [Logger] the logger instance.
-    def initialize(client_id, client_secret, logger: Logger.new($stdout))
+    def initialize(client_id, client_secret, environment: nil, base_url: nil, logger: Logger.new($stdout))
       @client_id = client_id
       @client_secret = client_secret
+      @base_url = Config.base_url(environment: environment, custom_url: base_url)
       @logger = logger
       @token = authenticate
 
-      @order = CDEKApiClient::API::Order.new(self)
+      @courier = CDEKApiClient::API::Courier.new(self)
       @location = CDEKApiClient::API::Location.new(self)
+      @order = CDEKApiClient::API::Order.new(self)
+      @payment = CDEKApiClient::API::Payment.new(self)
+      @print = CDEKApiClient::API::Print.new(self)
       @tariff = CDEKApiClient::API::Tariff.new(self)
       @webhook = CDEKApiClient::API::Webhook.new(self)
     end
@@ -50,16 +69,49 @@ module CDEKApiClient
     # @return [String] the access token.
     # @raise [StandardError] if authentication fails.
     def authenticate
-      uri = URI(TOKEN_URL)
-      response = Net::HTTP.post_form(uri, {
-                                       grant_type: 'client_credentials',
-                                       client_id: @client_id,
-                                       client_secret: @client_secret
-                                     })
+      uri = URI(Config.token_url(custom_url: @base_url))
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
 
-      raise "Error getting token: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+      request = Net::HTTP::Post.new(uri)
+      request.set_form_data(
+        'grant_type' => 'client_credentials',
+        'client_id' => @client_id,
+        'client_secret' => @client_secret
+      )
 
-      JSON.parse(response.body)['access_token']
+      response = http.request(request)
+
+      case response
+      when Net::HTTPSuccess
+        begin
+          data = JSON.parse(response.body)
+          auth_response = CDEKApiClient::Entities::AuthResponse.new(
+            access_token: data['access_token'],
+            token_type: data['token_type'],
+            expires_in: data['expires_in'],
+            scope: data['scope'],
+            jti: data['jti']
+          )
+          @logger.info("Successfully authenticated, token expires in #{auth_response.expires_in} seconds")
+          auth_response.access_token
+        rescue JSON::ParserError => e
+          raise "Failed to parse authentication response: #{e.message}"
+        rescue ArgumentError => e
+          raise "Invalid authentication response format: #{e.message}"
+        end
+      else
+        begin
+          error_data = JSON.parse(response.body)
+          error_response = CDEKApiClient::Entities::AuthErrorResponse.new(
+            error: error_data['error'],
+            error_description: error_data['error_description']
+          )
+          raise "Authentication failed: #{error_response.error} - #{error_response.error_description}"
+        rescue JSON::ParserError, ArgumentError
+          raise "Authentication failed with HTTP #{response.code}: #{response.body}"
+        end
+      end
     end
 
     # Makes an HTTP request to the API.
@@ -67,9 +119,11 @@ module CDEKApiClient
     # @param method [String] the HTTP method (e.g., 'get', 'post').
     # @param path [String] the API endpoint path.
     # @param body [Hash, nil] the request body.
+    # @param query [Hash, nil] the query parameters.
     # @return [Hash, Array] the parsed response.
-    def request(method, path, body: nil)
-      uri = URI("#{BASE_URL}/#{path}")
+    def request(method, path, body: nil, query: nil)
+      uri = URI("#{@base_url}/#{path}")
+      uri.query = URI.encode_www_form(query) if query
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
       request = build_request(method, uri, body)
@@ -80,6 +134,10 @@ module CDEKApiClient
       { 'error' => e.message }
     end
 
+    def validate_uuid(uuid)
+      raise ArgumentError, 'Invalid UUID format' unless uuid&.match?(/\A[\da-f]{8}-([\da-f]{4}-){3}[\da-f]{12}\z/i)
+    end
+
     private
 
     # Builds an HTTP request with the specified method, URI, and body.
@@ -112,8 +170,9 @@ module CDEKApiClient
       when Array, Hash
         response
       else
+        parsed_response = parse_json(response.body) if response.body
         log_error("Unexpected response type: #{response.class}")
-        { 'error' => "Unexpected response type: #{response.class}" }
+        { 'error' => parsed_response || "Unexpected response type: #{response.class}" }
       end
     rescue JSON::ParserError => e
       log_error("Failed to parse response: #{e.message}")

data/lib/cdek_api_client/config.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  # Configuration module for CDEK API Client
+  module Config
+    # Available API environments
+    PRODUCTION = 'production'
+    DEMO = 'demo'
+
+    # API endpoints for different environments
+    ENDPOINTS = {
+      PRODUCTION => 'https://api.cdek.ru/v2',
+      DEMO => 'https://api.edu.cdek.ru/v2'
+    }.freeze
+
+    class << self
+      # Get the base URL for the current configuration
+      # @param environment [String, Symbol] The environment (:production, :demo, 'production', 'demo')
+      # @param custom_url [String] Custom API URL (overrides environment)
+      # @return [String] The base API URL
+      def base_url(environment: nil, custom_url: nil)
+        return custom_url if custom_url
+
+        env = environment&.to_s&.downcase || ENV.fetch('CDEK_API_ENV', DEMO)
+        ENDPOINTS.fetch(env) do
+          raise ArgumentError, "Unknown environment: #{env}. Use :production or :demo"
+        end
+      end
+
+      # Get the token URL for authentication
+      # @param environment [String, Symbol] The environment
+      # @param custom_url [String] Custom API URL
+      # @return [String] The OAuth token URL
+      def token_url(environment: nil, custom_url: nil)
+        "#{base_url(environment: environment, custom_url: custom_url)}/oauth/token"
+      end
+    end
+  end
+end

data/lib/cdek_api_client/entities/agreement.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'validatable'
+
+module CDEKApiClient
+  module Entities
+    # Represents an agreement entity for delivery agreements in the CDEK API.
+    class Agreement
+      include Validatable
+
+      attr_accessor :cdek_number, :date, :time_from, :time_to, :comment, :delivery_point, :to_location
+
+      validates :cdek_number, type: :string, presence: true
+      validates :date, type: :string, presence: true
+      validates :time_from, type: :string, presence: true
+      validates :time_to, type: :string, presence: true
+      validates :comment, type: :string, presence: false
+      validates :delivery_point, type: :string, presence: false
+      validates :to_location, type: :hash, presence: false
+
+      # Initializes a new Agreement object.
+      #
+      # @param cdek_number [String] the CDEK order number.
+      # @param date [String] the delivery date in YYYY-MM-DD format.
+      # @param time_from [String] the start time in HH:MM format.
+      # @param time_to [String] the end time in HH:MM format.
+      # @param comment [String] the comment for the agreement.
+      # @param delivery_point [String] the delivery point code.
+      # @param to_location [Location] the delivery location.
+      # @raise [ArgumentError] if any attribute validation fails.
+      def initialize(cdek_number:, date:, time_from:, time_to:, comment: nil, delivery_point: nil, to_location: nil)
+        @cdek_number = cdek_number
+        @date = date
+        @time_from = time_from
+        @time_to = time_to
+        @comment = comment
+        @delivery_point = delivery_point
+        @to_location = to_location
+        validate!
+      end
+
+      # Converts the Agreement object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Agreement.
+      def to_json(*_args)
+        data = {
+          cdek_number: @cdek_number,
+          date: @date,
+          time_from: @time_from,
+          time_to: @time_to
+        }
+        data[:comment] = @comment if @comment
+        data[:delivery_point] = @delivery_point if @delivery_point
+        data[:to_location] = @to_location if @to_location
+        data.to_json
+      end
+    end
+  end
+end

data/lib/cdek_api_client/entities/auth_error_response.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'validatable'
+
+module CDEKApiClient
+  module Entities
+    # Represents an OAuth authentication error response from the CDEK API.
+    class AuthErrorResponse
+      include Validatable
+
+      attr_accessor :error, :error_description
+
+      validates :error, type: :string, presence: true
+      validates :error_description, type: :string, presence: true
+
+      # Initializes a new AuthErrorResponse object.
+      #
+      # @param error [String] the error code.
+      # @param error_description [String] the human-readable error description.
+      # @raise [ArgumentError] if any attribute validation fails.
+      def initialize(error:, error_description:)
+        @error = error
+        @error_description = error_description
+        validate!
+      end
+
+      # Converts the AuthErrorResponse object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the AuthErrorResponse.
+      def to_json(*_args)
+        {
+          error: @error,
+          error_description: @error_description
+        }.to_json
+      end
+    end
+  end
+end

data/lib/cdek_api_client/entities/auth_response.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'validatable'
+
+module CDEKApiClient
+  module Entities
+    # Represents an OAuth authentication response from the CDEK API.
+    class AuthResponse
+      include Validatable
+
+      attr_accessor :access_token, :token_type, :expires_in, :scope, :jti
+
+      validates :access_token, type: :string, presence: true
+      validates :token_type, type: :string, presence: true
+      validates :expires_in, type: :integer, presence: true
+      validates :scope, type: :string, presence: true
+      validates :jti, type: :string, presence: true
+
+      # Initializes a new AuthResponse object.
+      #
+      # @param access_token [String] the access token for API authentication.
+      # @param token_type [String] the type of token (usually "Bearer").
+      # @param expires_in [Integer] the number of seconds until the token expires.
+      # @param scope [String] the scope of the token.
+      # @param jti [String] the unique identifier for the token.
+      # @raise [ArgumentError] if any attribute validation fails.
+      def initialize(access_token:, token_type:, expires_in:, scope:, jti:)
+        @access_token = access_token
+        @token_type = token_type
+        @expires_in = expires_in
+        @scope = scope
+        @jti = jti
+        validate!
+      end
+
+      # Converts the AuthResponse object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the AuthResponse.
+      def to_json(*_args)
+        {
+          access_token: @access_token,
+          token_type: @token_type,
+          expires_in: @expires_in,
+          scope: @scope,
+          jti: @jti
+        }.to_json
+      end
+    end
+  end
+end