cdek_api_client 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e5151f9c6ed46e58d4badbc2e0055c42eea0ebc8f3139451924465197409126
-  data.tar.gz: 3761dd1c518d946e8a076ac6533dfd8424051f8835db193ea34a87db52db5018
+  metadata.gz: 58ba9a5e50a195b86b5736b86d6b4d0cf0b9af02857bed94ab004a5b1cde5819
+  data.tar.gz: c719a6ea6706e18a5d887223b57c344070649e980cd37e16c7e1db5a957652f7
 SHA512:
-  metadata.gz: c46a9e46713e5702ed3c0f5eb1f004b8d5a3657693b82f922db860201cb365b520d84a68854e7b150f5f82442de04591cc82a8c2e3d5600588430c443cedf64b
-  data.tar.gz: 4edeb61dbf81279666897852d794dd88ad36ec26ed09d13f0e937290dc6abd1d2ad2ceaef61632ad43e5ce3274f9f350a980ce29e2e092a659e46897471cbc44
+  metadata.gz: 7b824446b954f88c27a799681e67a4932c38fe5a61fd7157d92213c194f750d750fdda9dbe287bdc690bf94d3e2a2c101bbe2983e3c06fa5095815870dd54abd
+  data.tar.gz: e3ca1b0bb0370819a5fcf5dc44cbfe3bf42fc18e2b185e792ddd2e6622a732afcf050e6dee430abc042f28ab21f831965ba376eb21caf6933b9f01022941fae0

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+> [!NOTE]  
+> The format is based on [Keep a Changelog],
+> and this project adheres to [Semantic Versioning].
+
+## [Unreleased]
+
+/
+
+## [0.3.0] - 2026-01-18
+
+### Added
+
+- Added Courier API for managing delivery agreements, courier intakes, and delivery intervals
+- Added Payment API for payment-related operations
+- Added Print API for document printing functionality
+- Added new entities: Agreement, AuthResponse, AuthErrorResponse, Barcode, Check, IntakeAvailableDaysRequest, IntakeAvailableDaysResponse, Intakes, Invoice
+- Improved authentication error handling with dedicated AuthResponse and AuthErrorResponse entities
+- Added comprehensive release checklist (RELEASE.md) following 2026 RubyGems best practices
+
+### Changed
+
+- Updated gemspec metadata to follow 2026 RubyGems standards:
+  - Fixed all URIs to use HTTPS instead of HTTP
+  - Added `bug_tracker_uri` metadata field
+  - Added `documentation_uri` metadata field
+  - Updated `changelog_uri` to point directly to CHANGELOG.md file
+- Updated GitHub repository description and added relevant topics for better discoverability
+- Fixed GitHub Actions workflow syntax issue in Ruby setup step
+
+## [0.2.1] - 2024-07-22
+
+### Added
+
+- Added new commands to the `Makefile` for tagging a new version and pushing it to GitHub.
+
+### Changed
+
+- Updated links to Changelog and the Gem homepage in the gemspec.
+
+### Fixed
+
+- Fixed issues with previous release details and documentation.
+
+## [0.2.0] - 2024-07-22
+
+### Added
+
+- Improved error handling and response parsing in the `Client` class.
+- Updated `README.md` with detailed usage examples, including fetching and saving location data with optional live data fetching.
+
+### Changed
+
+- Refactored code structure for better organization.
+- Updated specs for `Client` and `API` classes.
+
+## [0.1.0] - 2024-07-22
+
+- Initial release
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Semantic Versioning]: https://semver.org/spec/v2.0.0.html
+
+<!-- Versions -->
+
+[unreleased]: https://github.com/SamyRai/cdek_api_client/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/SamyRai/cdek_api_client/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/SamyRai/cdek_api_client/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/SamyRai/cdek_api_client/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/SamyRai/cdek_api_client/releases/tag/v0.1.0
+
+```
+
+```

data/README.md

@@ -8,7 +8,7 @@
 - [Татарча](README_TAT.md)
 - [English](README.md)
 
-**Important:** This gem is in the early stages of development and it is shared as it is. Any support for development or feedback is welcome; please check the [Contributing](#contributing) section for more information.
+> [!WARNING] >**Important:** This gem is in the early stages of development and it is shared as it is. Any support for development or feedback is welcome; please check the [Contributing](#contributing) section for more information.
 
 ## Overview
 
@@ -16,10 +16,13 @@ CDEK ([СДЭК](https://www.cdek.ru/)) is a big logistics company in Russia, th
 
 The `cdek_api_client` gem offers a clean and robust interface to interact with the CDEK API, ensuring maintainable code with proper validations. This gem supports the following features:
 
-- Creating and tracking orders
-- Calculating tariffs
-- Retrieving location data (cities, regions, postal codes, and offices)
-- Managing webhooks
+- **Order Management**: Creating, tracking, updating, canceling, deleting, and retrieving orders by various identifiers
+- **Tariff Calculation**: Calculating single tariffs, tariff lists, and enhanced tariff calculations with services
+- **Location Services**: Retrieving cities, regions, postal codes, delivery offices, and coordinates
+- **Print/Documents**: Creating and retrieving barcodes, invoices, and other printable documents (PDF)
+- **Courier Services**: Managing delivery agreements and intake requests for courier pickup
+- **Payment Services**: Retrieving payment information, check data, and payment registries
+- **Webhook Management**: Registering, listing, managing, and deleting webhooks for real-time notifications
 
 ## Table of Contents
 
@@ -28,9 +31,15 @@ The `cdek_api_client` gem offers a clean and robust interface to interact with t
   - [Initialization](#initialization)
   - [Creating an Order](#creating-an-order)
   - [Tracking an Order](#tracking-an-order)
+  - [Order Management](#order-management)
   - [Calculating Tariff](#calculating-tariff)
+  - [Enhanced Tariff Calculation](#enhanced-tariff-calculation)
   - [Getting Location Data](#getting-location-data)
+  - [Print and Documents](#print-and-documents)
+  - [Courier Services](#courier-services)
+  - [Payment Services](#payment-services)
   - [Setting Up Webhooks](#setting-up-webhooks)
+  - [Enhanced Webhook Management](#enhanced-webhook-management)
   - [Fetching and Saving Location Data](#fetching-and-saving-location-data)
 - [Entities](#entities)
   - [OrderData](#orderdata)
@@ -38,6 +47,12 @@ The `cdek_api_client` gem offers a clean and robust interface to interact with t
   - [Sender](#sender)
   - [Package](#package)
   - [Item](#item)
+  - [Barcode](#barcode)
+  - [Invoice](#invoice)
+  - [Agreement](#agreement)
+  - [Intakes](#intakes)
+  - [Check](#check)
+- [Schema Management](#schema-management)
 - [TODO List](#todo-list)
 - [Changelog](#changelog)
 - [Contributing](#contributing)
@@ -272,6 +287,246 @@ rescue => e
 end
 ```
 
+### Order Management
+
+The gem provides comprehensive order management capabilities beyond basic creation and tracking:
+
+```ruby
+# Delete an order
+begin
+  response = client.order.delete('order-uuid')
+  puts "Order deleted: #{response}"
+rescue => e
+  puts "Error deleting order: #{e.message}"
+end
+
+# Cancel an order (refusal)
+begin
+  response = client.order.cancel('order-uuid')
+  puts "Order canceled: #{response}"
+rescue => e
+  puts "Error canceling order: #{e.message}"
+end
+
+# Update an order
+updated_order_data = # ... create updated order data
+begin
+  response = client.order.update(updated_order_data)
+  puts "Order updated: #{response}"
+rescue => e
+  puts "Error updating order: #{e.message}"
+end
+
+# Get order by UUID
+begin
+  order_info = client.order.get('order-uuid')
+  puts "Order info: #{order_info}"
+rescue => e
+  puts "Error getting order: #{e.message}"
+end
+
+# Get order by CDEK number
+begin
+  order_info = client.order.get_by_cdek_number('123456789')
+  puts "Order info: #{order_info}"
+rescue => e
+  puts "Error getting order: #{e.message}"
+end
+
+# Get order by IM number
+begin
+  order_info = client.order.get_by_im_number('ORDER123')
+  puts "Order info: #{order_info}"
+rescue => e
+  puts "Error getting order: #{e.message}"
+end
+
+# Create client return order
+client_return_data = CDEKApiClient::Entities::OrderData.new(
+  type: 1,
+  tariff_code: 1,
+  packages: [package]
+)
+begin
+  response = client.order.create_client_return('original-order-uuid', client_return_data)
+  puts "Client return created: #{response}"
+rescue => e
+  puts "Error creating client return: #{e.message}"
+end
+
+# Get intakes for an order
+begin
+  intakes = client.order.get_intakes('order-uuid')
+  puts "Order intakes: #{intakes}"
+rescue => e
+  puts "Error getting intakes: #{e.message}"
+end
+```
+
+### Print and Documents
+
+Generate and retrieve printable documents like barcodes and invoices:
+
+```ruby
+# Create barcode
+barcode_data = CDEKApiClient::Entities::Barcode.with_orders_uuid('order-uuid')
+begin
+  response = client.print.create_barcode(barcode_data)
+  puts "Barcode created: #{response}"
+rescue => e
+  puts "Error creating barcode: #{e.message}"
+end
+
+# Get barcode PDF
+begin
+  pdf_content = client.print.get_barcode_pdf('barcode-uuid')
+  File.write('barcode.pdf', pdf_content)
+rescue => e
+  puts "Error getting barcode PDF: #{e.message}"
+end
+
+# Create invoice
+invoice_data = CDEKApiClient::Entities::Invoice.with_orders_uuid('order-uuid')
+begin
+  response = client.print.create_invoice(invoice_data)
+  puts "Invoice created: #{response}"
+rescue => e
+  puts "Error creating invoice: #{e.message}"
+end
+
+# Get invoice PDF
+begin
+  pdf_content = client.print.get_invoice_pdf('invoice-uuid')
+  File.write('invoice.pdf', pdf_content)
+rescue => e
+  puts "Error getting invoice PDF: #{e.message}"
+end
+```
+
+### Courier Services
+
+Manage delivery agreements and courier intake requests:
+
+```ruby
+# Create delivery agreement
+agreement_data = CDEKApiClient::Entities::Agreement.new(
+  cdek_number: '123456789',
+  date: '2024-01-17',
+  time_from: '10:00',
+  time_to: '18:00',
+  comment: 'Delivery agreement'
+)
+begin
+  response = client.courier.create_agreement(agreement_data)
+  puts "Agreement created: #{response}"
+rescue => e
+  puts "Error creating agreement: #{e.message}"
+end
+
+# Create courier intake request
+intake_data = CDEKApiClient::Entities::Intakes.new(
+  cdek_number: '123456789',
+  intake_date: '2024-01-17',
+  intake_time_from: '10:00',
+  intake_time_to: '18:00',
+  name: 'Cargo description',
+  sender: { name: 'Sender Name', phones: [{ number: '+79001234567' }] },
+  from_location: { code: 44, address: 'Pickup Address' }
+)
+begin
+  response = client.courier.create_intake(intake_data)
+  puts "Intake created: #{response}"
+rescue => e
+  puts "Error creating intake: #{e.message}"
+end
+
+# Delete intake request
+begin
+  response = client.courier.delete_intake('intake-uuid')
+  puts "Intake deleted: #{response}"
+rescue => e
+  puts "Error deleting intake: #{e.message}"
+end
+```
+
+### Payment Services
+
+Retrieve payment and check information:
+
+```ruby
+# Get payments for a date
+begin
+  payments = client.payment.get_payments('2024-01-17')
+  puts "Payments: #{payments}"
+rescue => e
+  puts "Error getting payments: #{e.message}"
+end
+
+# Get checks
+check_data = CDEKApiClient::Entities::Check.new(
+  cdek_number: '123456789',
+  date: '2024-01-17'
+)
+begin
+  checks = client.payment.get_checks(check_data.to_query_params)
+  puts "Checks: #{checks}"
+rescue => e
+  puts "Error getting checks: #{e.message}"
+end
+
+# Get payment registries
+begin
+  registries = client.payment.get_registries('2024-01-17')
+  puts "Registries: #{registries}"
+rescue => e
+  puts "Error getting registries: #{e.message}"
+end
+```
+
+### Enhanced Tariff Calculation
+
+Calculate all available tariffs at once:
+
+```ruby
+# Calculate tariff list
+begin
+  tariffs = client.tariff.calculate_list(tariff_data)
+  puts "Available tariffs: #{tariffs}"
+rescue => e
+  puts "Error calculating tariffs: #{e.message}"
+end
+```
+
+### Enhanced Webhook Management
+
+List and manage webhooks:
+
+```ruby
+# List all webhooks
+begin
+  webhooks = client.webhook.list_all
+  puts "All webhooks: #{webhooks}"
+rescue => e
+  puts "Error listing webhooks: #{e.message}"
+end
+
+# Get specific webhook
+begin
+  webhook = client.webhook.get('webhook-uuid')
+  puts "Webhook: #{webhook}"
+rescue => e
+  puts "Error getting webhook: #{e.message}"
+end
+
+# Delete webhook by UUID
+begin
+  response = client.webhook.delete('webhook-uuid')
+  puts "Webhook deleted: #{response}"
+rescue => e
+  puts "Error deleting webhook: #{e.message}"
+end
+```
+
 ### Entities
 
 ### OrderData
@@ -338,27 +593,127 @@ Attributes:
 - `weight` (Integer, required): The weight of the item.
 - `amount` (Integer, required): The amount of the item.
 
+### Barcode
+
+Represents barcode creation data for printing.
+
+Attributes:
+
+- `orders` (Array, required): List of orders for barcode generation.
+- `copy_count` (Integer): Number of copies (default: 1).
+- `format` (String): Print format (A4, A5, A6, A7).
+- `lang` (String): Language code (RUS, ENG, DEU, ITA, TUR, CES, KOR, LIT, LAT).
+
+### Invoice
+
+Represents invoice creation data for printing.
+
+Attributes:
+
+- `orders` (Array, required): List of orders for invoice generation.
+- `copy_count` (Integer): Number of copies (default: 2).
+- `type` (String): Invoice type (tpl_russia, tpl_china, tpl_armenia, tpl_english, tpl_italian, tpl_korean, tpl_latvian, tpl_lithuanian, tpl_german, tpl_turkish, tpl_czech, tpl_thailand, tpl_invoice).
+
+### Agreement
+
+Represents delivery agreement data.
+
+Attributes:
+
+- `cdek_number` (String, required): CDEK order number.
+- `order_uuid` (String): Order UUID.
+- `date` (String, required): Delivery date.
+- `time_from` (String, required): Start time.
+- `time_to` (String, required): End time.
+- `comment` (String): Comment.
+- `delivery_point` (String): Delivery point code.
+- `to_location` (Hash): Delivery location details.
+
+### Intakes
+
+Represents courier intake request data.
+
+Attributes:
+
+- `cdek_number` (String): CDEK order number.
+- `order_uuid` (String): Order UUID.
+- `intake_date` (String, required): Intake date.
+- `intake_time_from` (String, required): Start time.
+- `intake_time_to` (String, required): End time.
+- `lunch_time_from` (String): Lunch start time.
+- `lunch_time_to` (String): Lunch end time.
+- `name` (String, required): Cargo description.
+- `need_call` (Boolean): Whether a call is needed.
+- `comment` (String): Comment for courier.
+- `courier_power_of_attorney` (Boolean): Courier needs power of attorney.
+- `courier_identity_card` (Boolean): Courier needs identity card.
+- `sender` (Hash, required): Sender contact information.
+- `from_location` (Hash, required): Pickup location details.
+- `weight` (Integer): Cargo weight in grams.
+- `length` (Integer): Cargo length in cm.
+- `width` (Integer): Cargo width in cm.
+- `height` (Integer): Cargo height in cm.
+
+### Check
+
+Represents check query data.
+
+Attributes:
+
+- `order_uuid` (String): Order UUID.
+- `cdek_number` (String): CDEK order number.
+- `date` (String): Date for check retrieval.
+
+## Schema Management
+
+The gem includes a schema management system to keep API definitions up-to-date. The `pull_cdek_schemas.rb` script fetches the latest OpenAPI schemas from CDEK's documentation and organizes them.
+
+### Pulling Latest Schemas
+
+```ruby
+# Run the schema pull script
+ruby pull_cdek_schemas.rb
+
+# This will:
+# 1. Fetch API documentation from CDEK
+# 2. Parse and organize schemas
+# 3. Save to cdek_api_schemas.json
+# 4. Display analysis of available endpoints
+```
+
+### Schema Analysis
+
+The script analyzes and organizes:
+- **5 main API schemas** from CDEK documentation
+- **40 unique endpoints** across all schemas
+- Complete endpoint mapping with HTTP methods
+- Metadata for each schema version
+
+### Automated Updates
+
+Run the schema pull script periodically to stay updated with the latest CDEK API changes:
+
+```bash
+# Add to cron or CI/CD pipeline
+0 2 * * * cd /path/to/gem && ruby pull_cdek_schemas.rb
+```
+
 ## TODO List
 
 - [x] Restructure the codebase for better organization.
 - [x] Add mappings for CDEK internal codes.
-- [ ] Add more API endpoints and data entities.
+- [x] Add more API endpoints and data entities (Order management, Print/Documents, Courier services, Payment services).
+- [x] Implement schema management system.
+- [x] Add comprehensive documentation in English, Russian, and Tatar.
 - [ ] Check all attributes for required and optional fields.
-- [ ] Add documentation for all classes and methods.
+- [x] Add documentation for all classes and methods.
+- [ ] Refine entity validations.
+- [ ] Add more comprehensive error handling.
+- [ ] Add rate limiting support.
 
 ## Changelog
 
-### v0.2.1
-
-- **Updated**: Changed links to Changelog and the Gem homepage in the gemspec.
-- **Added**: Add new commands to a `Makefile` for tagging a new version and pushing it to GitHub.
-
-### v0.2.0
-
-- **Added**: Improved error handling and response parsing in `Client`.
-- **Updated**: Code structure for better organization.
-- **Updated**: Specs for `Client` and `API` classes.
-- **Updated**: `README.md` with detailed usage examples, including fetching and saving location data with optional live data fetching.
+(See [CHANGELOG.md](CHANGELOG.md))
 
 ## Contributing
 

data/lib/cdek_api_client/api/courier.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  module API
+    # Handles courier-related API requests (agreements and intakes).
+    class Courier
+      # Initializes the Courier object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Creates a delivery agreement.
+      #
+      # @param agreement_data [CDEKApiClient::Entities::Agreement] the agreement data.
+      # @return [Hash] the response from the API.
+      def create_agreement(agreement_data)
+        response = @client.request('post', 'delivery', body: agreement_data)
+        handle_response(response)
+      end
+
+      # Gets agreement information by UUID.
+      #
+      # @param agreement_uuid [String] the UUID of the agreement.
+      # @return [Hash] the agreement information.
+      def get_agreement(agreement_uuid)
+        validate_uuid(agreement_uuid)
+        response = @client.request('get', "delivery/#{agreement_uuid}")
+        handle_response(response)
+      end
+
+      # Creates a courier intake request.
+      #
+      # @param intake_data [CDEKApiClient::Entities::Intakes] the intake data.
+      # @return [Hash] the response from the API.
+      def create_intake(intake_data)
+        response = @client.request('post', 'intakes', body: intake_data)
+        handle_response(response)
+      end
+
+      # Gets intake information by UUID.
+      #
+      # @param intake_uuid [String] the UUID of the intake.
+      # @return [Hash] the intake information.
+      def get_intake(intake_uuid)
+        validate_uuid(intake_uuid)
+        response = @client.request('get', "intakes/#{intake_uuid}")
+        handle_response(response)
+      end
+
+      # Deletes an intake request by UUID.
+      #
+      # @param intake_uuid [String] the UUID of the intake to delete.
+      # @return [Hash] the response from the API.
+      def delete_intake(intake_uuid)
+        validate_uuid(intake_uuid)
+        response = @client.request('delete', "intakes/#{intake_uuid}")
+        handle_response(response)
+      end
+
+      # Gets available days for courier intake.
+      #
+      # @param request_data [CDEKApiClient::Entities::IntakeAvailableDaysRequest] the request data.
+      # @return [Hash] the available days information.
+      def create_intake_available_days(request_data)
+        response = @client.request('post', 'intakes/availableDays', body: request_data)
+        handle_response(response)
+      end
+
+      # Gets available delivery intervals for an order.
+      #
+      # @param cdek_number [String, nil] the CDEK order number.
+      # @param order_uuid [String, nil] the order UUID.
+      # @return [Hash] the available delivery intervals.
+      def get_delivery_intervals(cdek_number: nil, order_uuid: nil)
+        query = {}
+        query[:cdek_number] = cdek_number if cdek_number
+        query[:order_uuid] = order_uuid if order_uuid
+
+        response = @client.request('get', 'delivery/intervals', query: query)
+        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.
+      # @return [Hash] the parsed response.
+      def handle_response(response)
+        @client.send(:handle_response, response)
+      end
+    end
+  end
+end

data/lib/cdek_api_client/api/location.rb

@@ -37,23 +37,23 @@ module CDEKApiClient
         use_live_data ? @client.request('get', 'deliverypoints') : read_data_from_file('offices_mapping.json')
       end
 
-      # Retrieves a list of postal codes.
+      # Retrieves a list of postal codes for a specific city.
       #
-      # @param city_code [String, nil] the city code to filter postal codes.
+      # @param city_code [String] the city code to filter postal codes.
       # @param use_live_data [Boolean] whether to use live data or cached data.
       # @return [Array<Hash>] list of postal codes.
-      def postal_codes(city_code = nil, use_live_data: false)
-        if use_live_data
-          if city_code
-            @client.request('get',
-                            "location/postalcodes?code=#{city_code}")
-          else
-            @client.request('get',
-                            'location/postalcodes')
-          end
-        else
-          read_data_from_file('postal_codes_mapping.json')
+      def postal_codes(city_code, use_live_data: false)
+        if city_code.nil? || (city_code.respond_to?(:empty?) && city_code.empty?)
+          raise ArgumentError,
+                'city_code is required'
         end
+
+        response = if use_live_data
+                     @client.request('get', "location/postalcodes?code=#{city_code}")
+                   else
+                     read_data_from_file("postal_codes_#{city_code}_mapping.json")
+                   end
+        response.is_a?(Hash) && response.key?('postal_codes') ? response['postal_codes'] : response
       end
 
       private
@@ -64,7 +64,7 @@ module CDEKApiClient
       # @return [Hash] the parsed JSON data from the file.
       def read_data_from_file(filename)
         file_path = File.join('data', filename)
-        JSON.parse(File.read(file_path))
+        JSON.parse(File.read(file_path, encoding: 'UTF-8'))
       rescue StandardError => e
         @client.logger.error("Failed to read data from file: #{e.message}")
         { 'error' => e.message }