Class: Mercadopago::RequestOptions

Inherits:
Object
  • Object
show all
Defined in:
lib/mercadopago/config/request_options.rb

Overview

Encapsulates per-request configuration: authentication, timeouts, retry policy, and optional MercadoPago partner/platform headers.

An instance is created automatically by SDK#initialize but can also be built manually and passed to individual resource calls via the request_options: keyword to override the SDK defaults.

Examples:

Override timeout for a single call

opts = Mercadopago::RequestOptions.new(access_token: token, connection_timeout: 120.0)
sdk.payment.get(123, request_options: opts)

Constant Summary collapse

DEFAULT_RETRY_ON = 
[429, 500, 502, 503, 504].freeze
DEFAULT_MAX_DELAY = 
30_000

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(access_token: nil, connection_timeout: 60.0, custom_headers: nil, corporation_id: nil, integrator_id: nil, platform_id: nil, max_retries: 3, initial_delay_ms: nil, max_delay_ms: DEFAULT_MAX_DELAY, jitter: false, retry_on: nil, on_retry: nil) ⇒ RequestOptions

Builds a new request configuration.

Parameters:

  • access_token (String, nil) (defaults to: nil) —

    OAuth access token

  • connection_timeout (Float) (defaults to: 60.0) —

    HTTP timeout in seconds

  • custom_headers (Hash, nil) (defaults to: nil) —

    additional headers to include

  • corporation_id (String, nil) (defaults to: nil) —

    corporation identifier for partner integrations

  • integrator_id (String, nil) (defaults to: nil) —

    integrator identifier for certified partners

  • platform_id (String, nil) (defaults to: nil) —

    platform identifier for marketplace integrations

  • max_retries (Integer) (defaults to: 3) —

    retry limit for transient failures (429, 5xx)

  • initial_delay_ms (Integer, nil) (defaults to: nil) —

    initial backoff delay in ms

  • max_delay_ms (Integer) (defaults to: DEFAULT_MAX_DELAY) —

    maximum backoff delay cap in ms

  • jitter (Boolean) (defaults to: false) —

    add SecureRandom jitter to retry delay

  • retry_on (Array<Integer>, nil) (defaults to: nil) —

    HTTP status codes to retry

  • on_retry (Proc, nil) (defaults to: nil) —

    callback invoked before each retry

Raises:

  • (TypeError) —

    if any parameter is not the expected type



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/mercadopago/config/request_options.rb', line 61

def initialize(access_token: nil,
               connection_timeout: 60.0,
               custom_headers: nil,
               corporation_id: nil,
               integrator_id: nil,
               platform_id: nil,
               max_retries: 3,
               initial_delay_ms: nil,
               max_delay_ms: DEFAULT_MAX_DELAY,
               jitter: false,
               retry_on: nil,
               on_retry: nil)
  self.access_token = access_token
  self.connection_timeout = connection_timeout
  self.custom_headers = custom_headers
  self.corporation_id = corporation_id
  self.integrator_id = integrator_id
  self.platform_id = platform_id
  self.max_retries = max_retries
  @initial_delay_ms = initial_delay_ms
  @max_delay_ms     = max_delay_ms
  @jitter           = jitter
  @retry_on         = retry_on
  @on_retry         = on_retry

  @config = Config.new
end

Instance Attribute Details

#access_token ⇒ String?

Returns OAuth access token used for Bearer authentication.

Returns:

  • (String, nil) —

    OAuth access token used for Bearer authentication



43
44
45
 
# File 'lib/mercadopago/config/request_options.rb', line 43

def access_token
  @access_token
end

#connection_timeout ⇒ Float

Returns HTTP timeout in seconds (default: 60.0).

Returns:

  • (Float) —

    HTTP timeout in seconds (default: 60.0)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#corporation_id ⇒ String?

Returns MercadoPago corporation identifier (x-corporation-id header).

Returns:

  • (String, nil) —

    MercadoPago corporation identifier (x-corporation-id header)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#custom_headers ⇒ Hash?

Returns extra headers merged into every request.

Returns:

  • (Hash, nil) —

    extra headers merged into every request



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#initial_delay_ms ⇒ Integer? (readonly)

Returns initial backoff delay in ms (nil = SDK default).

Returns:

  • (Integer, nil) —

    initial backoff delay in ms (nil = SDK default)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#integrator_id ⇒ String?

Returns MercadoPago integrator identifier (x-integrator-id header).

Returns:

  • (String, nil) —

    MercadoPago integrator identifier (x-integrator-id header)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#jitter ⇒ Boolean (readonly)

Returns add random jitter to retry delay using SecureRandom.

Returns:

  • (Boolean) —

    add random jitter to retry delay using SecureRandom



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#max_delay_ms ⇒ Integer (readonly)

Returns maximum backoff delay cap in ms (default: 30_000).

Returns:

  • (Integer) —

    maximum backoff delay cap in ms (default: 30_000)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#max_retries ⇒ Integer

Returns maximum automatic retries on transient HTTP errors (default: 3).

Returns:

  • (Integer) —

    maximum automatic retries on transient HTTP errors (default: 3)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#on_retry ⇒ Object (readonly)

Returns the value of attribute on_retry.



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#platform_id ⇒ String?

Returns MercadoPago platform identifier (x-platform-id header).

Returns:

  • (String, nil) —

    MercadoPago platform identifier (x-platform-id header)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

#retry_on ⇒ Array<Integer>? (readonly)

Returns HTTP status codes to retry (nil = DEFAULT_RETRY_ON).

Returns:

  • (Array<Integer>, nil) —

    HTTP status codes to retry (nil = DEFAULT_RETRY_ON)



43
44
 
# File 'lib/mercadopago/config/request_options.rb', line 43

attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
:platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry

Instance Method Details

#get_headers ⇒ Hash

Builds the full HTTP headers hash for a request.

Includes authorization, tracking, idempotency, user-agent, and any optional partner/custom headers. A unique idempotency key (UUID v4) is generated on every call.

Returns:

  • (Hash) —

    merged headers ready to be sent with the HTTP request



96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/mercadopago/config/request_options.rb', line 96

def get_headers
  headers = { 'Authorization': "Bearer #{@access_token}",
              'x-product-id' => @config.product_id,
              'x-tracking-id' => @config.tracking_id,
              'x-idempotency-key' => SecureRandom.uuid,
              'User-Agent' => @config.user_agent,
              'Accept': @config.mime_json }

  headers['x-corporation-id'] = @corporation_id unless @corporation_id.nil?
  headers['x-integrator-id'] = @integrator_id unless @integrator_id.nil?
  headers['x-platform-id'] = @platform_id unless @platform_id.nil?

  merge_custom_headers(headers)
end