Module: ComplyanceSDK

Defined in:
lib/complyance_sdk.rb,
lib/complyance_sdk/railtie.rb,
lib/complyance_sdk/version.rb,
lib/complyance_sdk/erp/client.rb,
lib/complyance_sdk/http/client.rb,
lib/complyance_sdk/models/mode.rb,
lib/complyance_sdk/jobs/base_job.rb,
lib/complyance_sdk/models/source.rb,
lib/complyance_sdk/models/country.rb,
lib/complyance_sdk/models/purpose.rb,
lib/complyance_sdk/jobs/sidekiq_job.rb,
lib/complyance_sdk/models/operation.rb,
lib/complyance_sdk/config/sdk_config.rb,
lib/complyance_sdk/models/source_ref.rb,
lib/complyance_sdk/models/environment.rb,
lib/complyance_sdk/config/retry_config.rb,
lib/complyance_sdk/retry/retry_manager.rb,
lib/complyance_sdk/models/document_type.rb,
lib/complyance_sdk/models/policy_result.rb,
lib/complyance_sdk/models/unify_request.rb,
lib/complyance_sdk/retry/retry_strategy.rb,
lib/complyance_sdk/models/unify_response.rb,
lib/complyance_sdk/retry/circuit_breaker.rb,
lib/complyance_sdk/http/logging_middleware.rb,
lib/complyance_sdk/models/logical_doc_type.rb,
lib/complyance_sdk/exceptions/sdk_exception.rb,
lib/complyance_sdk/jobs/process_document_job.rb,
lib/complyance_sdk/middleware/rack_middleware.rb,
lib/complyance_sdk/generators/config_generator.rb,
lib/complyance_sdk/generators/install_generator.rb,
lib/complyance_sdk/models/gets_document_type_v2.rb,
lib/complyance_sdk/http/authentication_middleware.rb,
lib/complyance_sdk/models/country_policy_registry.rb,
lib/complyance_sdk/models/logical_doc_type_mapper.rb,
lib/complyance_sdk/queue/persistent_queue_manager.rb,
lib/complyance_sdk/exceptions/circuit_breaker_open_error.rb

Overview

Main module for the Complyance SDK

Defined Under Namespace

Modules: Config, ERP, Exceptions, Generators, HTTP, Jobs, Middleware, Models, Queue, Retry Classes: Railtie

Constant Summary collapse

VERSION = 
"3.0.5"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.configuration ⇒ Object

Returns the value of attribute configuration.



35
36
37
 
# File 'lib/complyance_sdk.rb', line 35

def configuration
  @configuration
end

Class Method Details

.cleanup_duplicate_files ⇒ Object

Clean up duplicate files across queue directories



642
643
644
645
646
647
648
 
# File 'lib/complyance_sdk.rb', line 642

def cleanup_duplicate_files
  if queue_manager
    queue_manager.cleanup_duplicate_files
  else
    raise ComplyanceSDK::Exceptions::ConfigurationError.new("Queue Manager is not initialized")
  end
end

.cleanup_old_success_files(days_to_keep) ⇒ Object

Clean up old success files

Parameters:

  • days_to_keep (Integer) —

    Number of days to keep success files



628
629
630
 
# File 'lib/complyance_sdk.rb', line 628

def cleanup_old_success_files(days_to_keep)
  queue_manager&.cleanup_old_success_files(days_to_keep)
end

.clear_all_queues ⇒ Object

Clear all files from the queue (emergency cleanup)



633
634
635
636
637
638
639
 
# File 'lib/complyance_sdk.rb', line 633

def clear_all_queues
  if queue_manager
    queue_manager.clear_all_queues
  else
    raise ComplyanceSDK::Exceptions::ConfigurationError.new("Queue Manager is not initialized")
  end
end

.configure(config = nil) {|config| ... } ⇒ ComplyanceSDK::Config::SDKConfig

Configure the SDK with the provided configuration

Parameters:

Yields:

  • (config) —

    Yields the configuration object for block-style configuration

Returns:



42
43
44
45
46
47
48
49
50
51
 
# File 'lib/complyance_sdk.rb', line 42

def configure(config = nil)
  self.configuration = config if config.is_a?(ComplyanceSDK::Config::SDKConfig)
  
  if block_given?
    self.configuration ||= ComplyanceSDK::Config::SDKConfig.new
    yield(configuration)
  end
  
  configuration
end

.configure_from_env ⇒ ComplyanceSDK::Config::SDKConfig

Configure the SDK from environment variables

Returns:



56
57
58
 
# File 'lib/complyance_sdk.rb', line 56

def configure_from_env
  self.configuration = ComplyanceSDK::Config::SDKConfig.from_env
end

.configure_from_rails(environment = nil) ⇒ ComplyanceSDK::Config::SDKConfig

Configure the SDK from Rails credentials

Parameters:

  • environment (Symbol) (defaults to: nil) —

    The Rails environment (:development, :production, etc.)

Returns:



64
65
66
 
# File 'lib/complyance_sdk.rb', line 64

def configure_from_rails(environment = nil)
  self.configuration = ComplyanceSDK::Config::SDKConfig.from_rails(environment)
end

.configured? ⇒ Boolean

Check if the SDK is configured

Returns:

  • (Boolean) —

    True if the SDK is configured, false otherwise



71
72
73
 
# File 'lib/complyance_sdk.rb', line 71

def configured?
  !configuration.nil? && configuration.valid?
end

.create_mapping(options = {}) ⇒ ComplyanceSDK::Models::UnifyResponse

Convenience method for creating field mappings

Parameters:

  • options (Hash) (defaults to: {}) —

    Mapping options

Options Hash (options):

  • :country (String) —

    Country code

  • :payload (Hash) —

    Sample payload for mapping

  • :source (ComplyanceSDK::Models::Source) —

    Source information

  • :document_type (Symbol) —

    Document type (default: :tax_invoice)

Returns:



308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/complyance_sdk.rb', line 308

def create_mapping(options = {})
  request = ComplyanceSDK::Models::UnifyRequest.new(
    source: options[:source] || default_source,
    document_type: options[:document_type] || :tax_invoice,
    country: options[:country],
    operation: :single,
    mode: :documents,
    purpose: :mapping,
    payload: options[:payload]
  )

  push_to_unify(request)
end

.create_mapping_logical(source_name, source_version, country, logical_type, payload) ⇒ ComplyanceSDK::Models::UnifyResponse

Convenience method to create mappings with logical document types

Parameters:

  • source_name (String) —

    The source name

  • source_version (String) —

    The source version

  • country (Symbol) —

    The country code

  • logical_type (Symbol) —

    The logical document type

  • payload (Hash) —

    The business data payload

Returns:



581
582
583
584
585
586
587
588
589
590
591
592
 
# File 'lib/complyance_sdk.rb', line 581

def create_mapping_logical(source_name, source_version, country, logical_type, payload)
  push_to_unify_logical(
    source_name,
    source_version,
    logical_type,
    country,
    :single,
    :documents,
    :mapping,
    payload
  )
end

.detailed_queue_status ⇒ Hash

Get detailed queue status

Returns:

  • (Hash) —

    Detailed queue status information



608
609
610
 
# File 'lib/complyance_sdk.rb', line 608

def detailed_queue_status
  queue_manager ? queue_manager.queue_status_detailed : { error: "Queue Manager is not initialized" }
end

.drain_queue(timeout_seconds = 30) ⇒ Object 



663
664
665
 
# File 'lib/complyance_sdk.rb', line 663

def drain_queue(timeout_seconds = 30)
  queue_manager ? queue_manager.drain_queue(timeout_seconds) : true
end

.get_document_status(document_id) ⇒ Hash

Get retrieval status by document ID.

Parameters:

  • document_id (String) —

    The document ID

Returns:

  • (Hash) —

    Raw retrieval response hash



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/complyance_sdk.rb', line 326

def get_document_status(document_id)
  unless configured?
    raise ComplyanceSDK::Exceptions::ConfigurationError.new(
      "SDK must be configured before making API calls"
    )
  end

  normalized = document_id.to_s.strip
  if normalized.empty?
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Document ID is required",
      suggestion: "Provide a valid documentId to fetch retrieval status."
    )
  end

  with_retry("get_document_status", { document_id: normalized }) do
    http_client.get("/api/v3/documents/#{URI.encode_www_form_component(normalized)}/status")
  end
end

.get_purchase_invoice(id) ⇒ Object 



678
679
680
681
682
683
684
685
686
687
688
689
 
# File 'lib/complyance_sdk.rb', line 678

def get_purchase_invoice(id)
  ensure_configured_for_purchase_api!

  if id.nil? || id.to_s.strip.empty?
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Purchase invoice id is required",
      context: { suggestion: "Provide a valid purchase invoice id." }
    )
  end

  http_client.get("/documents/#{URI.encode_www_form_component(id.to_s)}", { type: "purchases" })
end

.get_status(submission_id) ⇒ Object

Deprecated.

Use get_document_status(document_id).



359
360
361
 
# File 'lib/complyance_sdk.rb', line 359

def get_status(submission_id)
  get_submission_status(submission_id)
end

.get_submission_status(submission_id) ⇒ Hash

Deprecated submissionId polling endpoint.

Parameters:

  • submission_id (String) —

    The submission ID

Returns:

  • (Hash)

Raises:



350
351
352
353
354
355
356
 
# File 'lib/complyance_sdk.rb', line 350

def get_submission_status(submission_id)
  _unused = submission_id
  raise ComplyanceSDK::Exceptions::ValidationError.new(
    "submissionId status retrieval is no longer supported",
    suggestion: "Use get_document_status(document_id) for polling status and trace endpoints."
  )
end

.list_purchase_invoices(filters = {}) ⇒ Object 



672
673
674
675
676
 
# File 'lib/complyance_sdk.rb', line 672

def list_purchase_invoices(filters = {})
  ensure_configured_for_purchase_api!
  query = { type: "purchases" }.merge(filters.reject { |_key, value| value.nil? })
  http_client.get("/documents", query)
end

.pause_queue_processing ⇒ Object 



655
656
657
 
# File 'lib/complyance_sdk.rb', line 655

def pause_queue_processing
  queue_manager&.pause_processing
end

.process_pending_submissions ⇒ Object

Process pending submissions now



651
652
653
 
# File 'lib/complyance_sdk.rb', line 651

def process_pending_submissions
  queue_manager&.process_pending_submissions_now
end

.process_queued_submissions_first ⇒ Object

Process queued submissions before handling new requests



668
669
670
 
# File 'lib/complyance_sdk.rb', line 668

def process_queued_submissions_first
  queue_manager&.process_pending_submissions_now
end

.push_to_unify(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload, destinations = nil) ⇒ ComplyanceSDK::Models::UnifyResponse

Main API method for document processing (Java-style signature)

Parameters:

  • source_name (String) —

    The source name

  • source_version (String) —

    The source version

  • logical_doc_type (Symbol) —

    The logical document type

  • country (Symbol) —

    The country code

  • operation (Symbol) —

    The operation type

  • mode (Symbol) —

    The mode

  • purpose (Symbol) —

    The purpose

  • payload (Hash) —

    The business data payload

  • destinations (Array, nil) (defaults to: nil) —

    Optional destinations (auto-generated if nil)

Returns:



111
112
113
 
# File 'lib/complyance_sdk.rb', line 111

def push_to_unify(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload, destinations = nil)
  push_to_unify_logical(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload, destinations)
end

.push_to_unify_async(request, options = {}) ⇒ String, Object

Process a document asynchronously using background jobs

Parameters:

Options Hash (options):

  • :job_type (Symbol) —

    Job type (:active_job or :sidekiq)

  • :callback_url (String) —

    Optional callback URL

  • :callback_headers (Hash) —

    Optional callback headers

Returns:

  • (String, Object) —

    Job ID or job object



371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/complyance_sdk.rb', line 371

def push_to_unify_async(request, options = {})
  unless configured?
    raise ComplyanceSDK::Exceptions::ConfigurationError.new(
      "SDK must be configured before making API calls"
    )
  end

  # Convert hash to UnifyRequest if needed
  if request.is_a?(Hash)
    request = ComplyanceSDK::Models::UnifyRequest.from_h(request)
  end

  # Validate the request
  unless request.valid?
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Invalid request: #{request.errors.join(', ')}",
      context: { errors: request.errors }
    )
  end

  retry_manager.execute_async(
    request.to_h,
    job_type: options[:job_type] || :active_job,
    callback_url: options[:callback_url],
    callback_headers: options[:callback_headers] || {}
  )
end

.push_to_unify_from_json(source_name, source_version, logical_doc_type, country, operation, mode, purpose, json_payload, destinations = nil) ⇒ ComplyanceSDK::Models::UnifyResponse

Push to Unify API with logical document types using JSON string payload

Parameters:

  • source_name (String) —

    The source name

  • source_version (String) —

    The source version

  • logical_doc_type (Symbol) —

    The logical document type

  • country (Symbol) —

    The country code

  • operation (Symbol) —

    The operation type

  • mode (Symbol) —

    The mode

  • purpose (Symbol) —

    The purpose

  • json_payload (String) —

    The JSON string payload

  • destinations (Array, nil) (defaults to: nil) —

    Optional destinations (auto-generated if nil)

Returns:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/complyance_sdk.rb', line 127

def push_to_unify_from_json(source_name, source_version, logical_doc_type, country, operation, mode, purpose, json_payload, destinations = nil)
  if json_payload.nil? || json_payload.to_s.strip.empty?
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Payload is required but was null or empty",
      context: { 
        suggestion: 'Provide a non-empty JSON payload string. Example: \'{"invoiceNumber":"INV-123","amount":1000}\''
      }
    )
  end

  begin
    require 'json'
    payload_hash = JSON.parse(json_payload)
    
    unless payload_hash.is_a?(Hash)
      raise ComplyanceSDK::Exceptions::ValidationError.new(
        "Failed to parse JSON payload: parsed result is not a hash",
        context: { 
          suggestion: 'Ensure the payload is valid JSON and represents an object structure. Example: \'{"invoiceNumber":"INV-123"}\''
        }
      )
    end

    push_to_unify(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload_hash, destinations)
  rescue JSON::ParserError => parse_error
    payload_snippet = json_payload.length > 100 ? json_payload[0..99] + '...' : json_payload
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Failed to parse JSON payload: #{parse_error.message}",
      context: { 
        suggestion: 'Ensure the payload is valid JSON. Example: \'{"invoiceNumber":"INV-123","amount":1000}\'',
        payload_snippet: payload_snippet,
        parse_error: parse_error.message
      }
    )
  rescue ComplyanceSDK::Exceptions::ValidationError
    raise
  rescue StandardError => conversion_error
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Failed to parse JSON payload: #{conversion_error.message}",
      context: { 
        suggestion: 'Ensure the payload is valid JSON. Example: \'{"invoiceNumber":"INV-123","amount":1000}\'',
        conversion_error: conversion_error.message
      }
    )
  end
end

.push_to_unify_from_object(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload_object, destinations = nil) ⇒ ComplyanceSDK::Models::UnifyResponse

Push to Unify API with logical document types using object payload

Parameters:

  • source_name (String) —

    The source name

  • source_version (String) —

    The source version

  • logical_doc_type (Symbol) —

    The logical document type

  • country (Symbol) —

    The country code

  • operation (Symbol) —

    The operation type

  • mode (Symbol) —

    The mode

  • purpose (Symbol) —

    The purpose

  • payload_object (Object) —

    The object payload (any object that responds to to_h or has instance variables)

  • destinations (Array, nil) (defaults to: nil) —

    Optional destinations (auto-generated if nil)

Returns:



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/complyance_sdk.rb', line 186

def push_to_unify_from_object(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload_object, destinations = nil)
  if payload_object.nil?
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Payload object is required but was nil",
      context: { 
        suggestion: "Provide a valid payload object. Example: {invoice_number: 'INV-123', amount: 1000}"
      }
    )
  end

  begin
    # Convert object to hash
    payload_hash = if payload_object.is_a?(Hash)
                     payload_object
                   elsif payload_object.respond_to?(:to_h)
                     payload_object.to_h
                   elsif payload_object.respond_to?(:instance_variables)
                     # Convert object instance variables to hash
                     hash = {}
                     payload_object.instance_variables.each do |var|
                       key = var.to_s.delete('@')
                       hash[key] = payload_object.instance_variable_get(var)
                     end
                     hash
                   else
                     # Try JSON serialization for other objects
                     require 'json'
                     json_str = payload_object.to_json
                     JSON.parse(json_str)
                   end

    unless payload_hash.is_a?(Hash)
      raise ComplyanceSDK::Exceptions::ValidationError.new(
        "Failed to convert payload object to hash: conversion returned invalid result",
        context: { 
          suggestion: "Ensure the object structure is compatible with the SDK payload format. " +
                     "The object should be convertible to a hash structure."
        }
      )
    end

    push_to_unify(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload_hash, destinations)
  rescue ComplyanceSDK::Exceptions::ValidationError
    raise
  rescue StandardError => conversion_error
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Failed to convert payload object to hash: #{conversion_error.message}",
      context: { 
        suggestion: "Ensure the object structure is compatible with the SDK payload format. " +
                   "The object should be convertible to a hash. " +
                   "Example: {invoice_number: 'INV-123', amount: 1000} or a class with public attributes.",
        object_type: payload_object.class.name,
        conversion_error: conversion_error.message
      }
    )
  end
end

.push_to_unify_logical(source_name, source_version, logical_type, country, operation, mode, purpose, payload, destinations = nil) ⇒ ComplyanceSDK::Models::UnifyResponse

Push to Unify API with logical document types but full control over operation, mode, and purpose This is the primary method for all workflows with logical document types

Parameters:

  • source_name (String) —

    The source name

  • source_version (String) —

    The source version

  • logical_type (Symbol) —

    The logical document type

  • country (Symbol) —

    The country code

  • operation (Symbol) —

    The operation type

  • mode (Symbol) —

    The mode

  • purpose (Symbol) —

    The purpose

  • payload (Hash) —

    The business data payload

  • destinations (Array, nil) (defaults to: nil) —

    Optional destinations (auto-generated if nil)

Returns:



412
413
414
415
416
417
418
419
 
# File 'lib/complyance_sdk.rb', line 412

def push_to_unify_logical(source_name, source_version, logical_type, country, operation, mode, purpose, payload, destinations = nil)
  validate_required_parameter(logical_type, :logical_type, "Logical document type is required")
  policy = ComplyanceSDK::Models::CountryPolicyRegistry.evaluate(country, logical_type)
  merged_payload = deep_merge_into_meta_config(payload, policy.meta_config_flags)
  set_invoice_data_document_type(merged_payload, logical_type)
  document_type_v2 = ComplyanceSDK::Models::LogicalDocTypeMapper.to_gets_document_type_v2(logical_type)
  push_to_unify_v2(source_name, source_version, document_type_v2, country, operation, mode, purpose, merged_payload, destinations)
end

.push_to_unify_request(request) ⇒ ComplyanceSDK::Models::UnifyResponse

Main API method for document processing (UnifyRequest object)

Parameters:

Returns:



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/complyance_sdk.rb', line 248

def push_to_unify_request(request)
  unless configured?
    raise ComplyanceSDK::Exceptions::ConfigurationError.new(
      "SDK must be configured before making API calls"
    )
  end

  # Convert hash to UnifyRequest if needed
  if request.is_a?(Hash)
    request = ComplyanceSDK::Models::UnifyRequest.from_h(request)
  end

  # Validate the request
  unless request.valid?
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Invalid request: #{request.errors.join(', ')}",
      context: { errors: request.errors }
    )
  end

  # Make the API call with retry logic
  response_data = with_retry("push_to_unify", { request_id: request.metadata[:request_id] }) do
    http_client.post("", request.to_h)
  end

  # Convert response to UnifyResponse object
  ComplyanceSDK::Models::UnifyResponse.from_h(response_data)
end

.push_to_unify_v2(source_name, source_version, document_type_v2, country, operation, mode, purpose, payload, destinations = nil) ⇒ ComplyanceSDK::Models::UnifyResponse

Push to Unify API with GETS V2 document type

Parameters:

  • source_name (String) —

    The source name

  • source_version (String) —

    The source version

  • document_type_v2 (ComplyanceSDK::Models::GetsDocumentTypeV2) —

    The V2 document type

  • country (Symbol) —

    The country code

  • operation (Symbol) —

    The operation type

  • mode (Symbol) —

    The mode

  • purpose (Symbol) —

    The purpose

  • payload (Hash) —

    The business data payload

  • destinations (Array, nil) (defaults to: nil) —

    Optional destinations

Returns:



433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
 
# File 'lib/complyance_sdk.rb', line 433

def push_to_unify_v2(source_name, source_version, document_type_v2, country, operation, mode, purpose, payload, destinations = nil)
  unless configured?
    raise ComplyanceSDK::Exceptions::ConfigurationError.new(
      "SDK must be configured before making API calls"
    )
  end

  # Process queued submissions first before handling new requests
  process_queued_submissions_first

  # Validate required parameters
  # Handle source_name and source_version based on purpose
  final_source_name = if purpose == :mapping
                        # For MAPPING purpose, source_name and source_version are optional
                        source_name || ""
                      else
                        # For all other purposes, source_name is mandatory
                        if source_name.nil? || source_name.to_s.strip.empty?
                          raise ComplyanceSDK::Exceptions::ValidationError.new(
                            "Source name is required",
                            context: { field: :source_name }
                          )
                        end
                        source_name
                      end

  final_source_version = if purpose == :mapping
                           # For MAPPING purpose, source_version is optional
                           source_version || ""
                         else
                           # For all other purposes, source_version is mandatory
                           if source_version.nil? || source_version.to_s.strip.empty?
                             raise ComplyanceSDK::Exceptions::ValidationError.new(
                               "Source version is required",
                               context: { field: :source_version }
                             )
                           end
                           source_version
                         end

  # Validate other required parameters
  validate_required_parameter(document_type_v2, :document_type_v2, "GETS V2 documentType is required")
  validate_required_parameter(country, :country, "Country is required")
  validate_required_parameter(operation, :operation, "Operation is required")
  validate_required_parameter(mode, :mode, "Mode is required")
  validate_required_parameter(purpose, :purpose, "Purpose is required")
  validate_required_parameter(payload, :payload, "Payload is required")

  normalized_document_type_v2 = normalize_and_validate_document_type_v2(document_type_v2)

  # Validate country restrictions for current environment
  validate_country_for_environment(country, configuration.environment)

  request_payload = payload.dup
  set_payload_document_type_v2(request_payload, normalized_document_type_v2)
  set_invoice_data_document_type_from_v2(request_payload, normalized_document_type_v2.base)

  # Create source reference with type from configuration
  source_type = find_source_type(final_source_name, final_source_version)
  source_ref = ComplyanceSDK::Models::SourceRef.new(final_source_name, final_source_version, source_type)

  # Auto-generate destinations if none provided and auto-generation is enabled
  final_destinations = destinations || (configuration.auto_generate_tax_destination? ? 
                                      generate_default_destinations(country, normalized_document_type_v2.base) : [])

  # Build and send request using the resolved base document type
  push_to_unify_internal_with_document_type(
    source_ref,
    resolve_base_document_type_from_v2(normalized_document_type_v2.base),
    normalized_document_type_v2.base,
    country,
    operation,
    mode,
    purpose,
    request_payload,
    final_destinations,
    normalized_document_type_v2
  )
end

.push_to_unify_with_document_type(source_name, source_version, document_type, country, operation, mode, purpose, payload, destinations = nil) ⇒ Object 



513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/complyance_sdk.rb', line 513

def push_to_unify_with_document_type(source_name, source_version, document_type, country, operation, mode, purpose, payload, destinations = nil)
  push_to_unify_v2(
    source_name,
    source_version,
    document_type,
    country,
    operation,
    mode,
    purpose,
    payload,
    destinations
  )
end

.push_to_unify_with_source_ref(source_ref, logical_type, country, operation, mode, purpose, payload, destinations = nil) ⇒ ComplyanceSDK::Models::UnifyResponse

Push to Unify API with logical document types using SourceRef

Parameters:

  • source_ref (ComplyanceSDK::Models::SourceRef) —

    The source reference

  • logical_type (Symbol) —

    The logical document type

  • country (Symbol) —

    The country code

  • operation (Symbol) —

    The operation type

  • mode (Symbol) —

    The mode

  • purpose (Symbol) —

    The purpose

  • payload (Hash) —

    The business data payload

  • destinations (Array, nil) (defaults to: nil) —

    Optional destinations

Returns:



538
539
540
541
542
543
544
545
546
547
548
549
550
 
# File 'lib/complyance_sdk.rb', line 538

def push_to_unify_with_source_ref(source_ref, logical_type, country, operation, mode, purpose, payload, destinations = nil)
  push_to_unify_logical(
    source_ref.name,
    source_ref.version,
    logical_type,
    country,
    operation,
    mode,
    purpose,
    payload,
    destinations
  )
end

.queue_status ⇒ Hash

Get queue status and statistics

Returns:

  • (Hash) —

    Queue status information



597
598
599
600
601
602
603
 
# File 'lib/complyance_sdk.rb', line 597

def queue_status
  if queue_manager
    queue_manager.queue_status
  else
    { error: "Queue Manager is not initialized" }
  end
end

.queue_status_detailed ⇒ Object 



612
613
614
 
# File 'lib/complyance_sdk.rb', line 612

def queue_status_detailed
  detailed_queue_status
end

.resume_queue_processing ⇒ Object 



659
660
661
 
# File 'lib/complyance_sdk.rb', line 659

def resume_queue_processing
  queue_manager&.resume_processing
end

.retry_failed(queue_item_id) ⇒ Object 



621
622
623
 
# File 'lib/complyance_sdk.rb', line 621

def retry_failed(queue_item_id)
  queue_manager&.retry_failed(queue_item_id) || false
end

.retry_failed_submissions ⇒ Object

Retry failed submissions



617
618
619
 
# File 'lib/complyance_sdk.rb', line 617

def retry_failed_submissions
  queue_manager&.retry_failed_submissions
end

.retry_manager(redis_config = {}) ⇒ ComplyanceSDK::Retry::RetryManager

Get the retry manager instance

Parameters:

  • redis_config (Hash) (defaults to: {}) —

    Optional Redis configuration

Returns:



79
80
81
 
# File 'lib/complyance_sdk.rb', line 79

def retry_manager(redis_config = {})
  @retry_manager ||= ComplyanceSDK::Retry::RetryManager.new(configuration, redis_config)
end

.submit_invoice(options = {}) ⇒ ComplyanceSDK::Models::UnifyResponse

Convenience method for submitting invoices

Parameters:

  • options (Hash) (defaults to: {}) —

    Invoice submission options

Options Hash (options):

  • :country (String) —

    Country code

  • :payload (Hash) —

    Invoice payload

  • :source (ComplyanceSDK::Models::Source) —

    Source information

  • :document_type (Symbol) —

    Document type (default: :tax_invoice)

  • :purpose (Symbol) —

    Purpose (default: :invoicing)

Returns:



286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/complyance_sdk.rb', line 286

def submit_invoice(options = {})
  request = ComplyanceSDK::Models::UnifyRequest.new(
    source: options[:source] || default_source,
    document_type: options[:document_type] || :tax_invoice,
    country: options[:country],
    operation: :single,
    mode: :documents,
    purpose: options[:purpose] || :invoicing,
    payload: options[:payload]
  )

  push_to_unify(request)
end

.submit_invoice_logical(source_name, source_version, country, logical_type, payload) ⇒ ComplyanceSDK::Models::UnifyResponse

Convenience method to submit invoices with logical document types

Parameters:

  • source_name (String) —

    The source name

  • source_version (String) —

    The source version

  • country (Symbol) —

    The country code

  • logical_type (Symbol) —

    The logical document type

  • payload (Hash) —

    The business data payload

Returns:



560
561
562
563
564
565
566
567
568
569
570
571
 
# File 'lib/complyance_sdk.rb', line 560

def submit_invoice_logical(source_name, source_version, country, logical_type, payload)
  push_to_unify_logical(
    source_name,
    source_version,
    logical_type,
    country,
    :single,
    :documents,
    :invoicing,
    payload
  )
end

.verify_webhook_signature(payload, signature, secret, algorithm = "sha256") ⇒ Object 



691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
 
# File 'lib/complyance_sdk.rb', line 691

def verify_webhook_signature(payload, signature, secret, algorithm = "sha256")
  normalized_algorithm = algorithm.to_s.downcase
  unless %w[sha256 sha512].include?(normalized_algorithm)
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Unsupported webhook HMAC algorithm: #{algorithm}",
      context: { suggestion: "Use sha256 or sha512." }
    )
  end

  expected_signature = OpenSSL::HMAC.hexdigest(normalized_algorithm, secret.to_s, payload.to_s)
  unless secure_compare(expected_signature, signature.to_s.strip)
    raise ComplyanceSDK::Exceptions::ValidationError.new(
      "Webhook signature verification failed",
      context: {
        suggestion: "Ensure you use the raw request body and the correct webhook secret."
      }
    )
  end

  true
end

.with_retry(operation_name, context = {}) { ... } ⇒ Object

Execute an operation with retry logic

Parameters:

  • operation_name (String) —

    Name of the operation

  • context (Hash) (defaults to: {}) —

    Context information

Yields:

  • The block to execute

Returns:

  • The result of the block



89
90
91
92
93
94
95
96
97
 
# File 'lib/complyance_sdk.rb', line 89

def with_retry(operation_name, context = {})
  unless configured?
    raise ComplyanceSDK::Exceptions::ConfigurationError.new(
      "SDK must be configured before using retry functionality"
    )
  end

  retry_manager.execute(operation_name, context) { yield }
end