Class: Conexa::Contract

Inherits:
Model show all
Defined in:
lib/conexa/resources/contract.rb

Overview

Contract resource for recurring billing contracts

Creating a contract

Required: plan_id, customer_id, payment_frequency (+monthly+, bimonthly, quarterly, semester or yearly) and start_date.

Conexa::Contract.create(
plan_id: 5, customer_id: 127,
payment_frequency: 'monthly', start_date: '2026-01-01'
)

due_day is conditionally required and conditionally forbidden

Required on a customer's first contract (or when they use automatic invoicing); rejected on every later one, which inherits the customer's defaultDueDay:

422 CONTRACT_RECURRING_SALE_10
"The due day can not be informed for customers who already have a contract"

Code that always sends due_day works at onboarding and fails forever after. Read the code off the exception rather than the message:

rescue Conexa::ResponseError => e
retry_without_due_day if e.api_error_codes.include?('CONTRACT_RECURRING_SALE_10')
end

Creating, charging and settling in one call

generate_sales: 'firstOccurrenceSettleRetroactive' also generates and settles retroactive charges, and then requires expense_settlement. It replaces a three-call sequence in which each step can fail on its own.

Conexa::Contract.create(
plan_id: 5, customer_id: 127,
payment_frequency: 'monthly', start_date: '2026-01-01',
generate_sales: 'firstOccurrenceSettleRetroactive',
expense_settlement: { receiving_method_id: 53, account_id: 1 }
)

Other documented values: firstOccurrence (default), currentOccurrence, nextOccurrence.

Other documented fields

end_date, first_due_date (required when the customer uses automatic invoicing), fidelity_date, amount, discount_value, seller_id, contract_summary, notes, membership_fee, nfse_description, prorata_type (+startOfMonth+ / notCalculate / perDueDate), refund (an explicit nil opts out even when the plan configures one), complementary_services (array), extra_fields (array).

cost_center_id is not accepted on create — it 400s — even though it is present when the contract is read back.

Examples:

End a contract

Conexa::Contract.set_end_date(456, date: '2026-12-31')

Constant Summary

Constants inherited from ConexaObject

Conexa::ConexaObject::RESOURCES

Instance Attribute Summary collapse

Attributes inherited from ConexaObject

#attributes

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Model

all, #class_name, class_name, #create, create, #destroy, destroy, extract_page_size_or_params, #fetch, find_by, find_by_id, #id, #primary_key, primary_key_attribute, #primary_key_name, #save, #set_primary_key, show_url, underscored_class_name, url

Methods inherited from ConexaObject

#==, #[]=, convert, #empty?, #initialize, #respond_to_missing?, #to_hash, #unsaved_attributes

Constructor Details

This class inherits a constructor from Conexa::ConexaObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Conexa::ConexaObject

Instance Attribute Details

#billing_day ⇒ Integer (readonly)

Returns Billing day.

Returns:

  • (Integer) —

    Billing day



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#contract_id ⇒ Integer (readonly)

Returns Contract ID (also accessible as #id).

Returns:

  • (Integer) —

    Contract ID (also accessible as #id)



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#customer_id ⇒ Integer (readonly)

Returns Customer ID.

Returns:

  • (Integer) —

    Customer ID



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#end_date ⇒ String? (readonly)

Returns End date.

Returns:

  • (String, nil) —

    End date



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#payment_day ⇒ Integer (readonly)

Returns Payment day (1-28).

Returns:

  • (Integer) —

    Payment day (1-28)



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#plan_id ⇒ Integer? (readonly)

Returns Plan ID.

Returns:

  • (Integer, nil) —

    Plan ID



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#start_date ⇒ String (readonly)

Returns Start date.

Returns:

  • (String) —

    Start date



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#status ⇒ String (readonly)

Returns Status: active, ended, cancelled.

Returns:

  • (String) —

    Status: active, ended, cancelled



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

#value ⇒ Float (readonly)

Returns Contract value.

Returns:

  • (Float) —

    Contract value



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/conexa/resources/contract.rb', line 82

class Contract < Model
  primary_key_attribute :contract_id

  # Check if contract is active
  # @return [Boolean]
  def active?
    status == 'active'
  end

  # Check if contract is cancelled/ended
  # @return [Boolean]
  def ended?
    status == 'ended' || status == 'cancelled'
  end

  # Set this contract's end date — closing it, or amending an existing closure.
  #
  # The endpoint is documented as "encerra um contrato ativo **ou atualiza a
  # data de encerramento**": it both closes and amends, and a future date on an
  # already-closed contract **reopens** it. `end_contract` is kept as an alias,
  # but the name understates what the call does.
  #
  # A contract cannot be closed retroactively past a day that already has
  # invoiced sales (422 CONTRACT_RECURRING_SALE_23).
  #
  # The API may answer with an empty body on success.
  #
  # @param params [Hash]
  # @option params [String] :date required, yyyy-MM-dd — the closing date
  # @option params [Integer] :reason_id closing-reason id, from
  #   Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato
  # @option params [Boolean] :unlink_customer unlinks DDRs, mailboxes, extensions
  #   and recurring sales. Requires date <= today and no other active contracts;
  #   ends *all* the customer's recurring sales and cancels their uninvoiced sales.
  # @option params [String] :end_date deprecated alias for +:date+
  # @return [self]
  def set_end_date(params = {})
    params = self.class.normalize_end_params(params)
    Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
    self
  end
  alias_method :end_contract, :set_end_date

  class << self
    # Set a contract's end date by ID
    # @see #set_end_date
    # @param id [Integer, String] contract ID
    # @return [Contract]
    def set_end_date(id, params = {})
      find(id).set_end_date(params)
    end
    alias_method :end_contract, :set_end_date

    # @deprecated Use {Conexa::Util.normalize_end_date_param}, which both "end"
    #   endpoints share.
    # @api private
    def normalize_end_params(params)
      Util.normalize_end_date_param(params)
    end

    # Create contract with custom product items
    # @param params [Hash] contract params including :items array
    # @return [Contract]
    def create_with_products(params = {})
      create(params)
    end
  end
end

Class Method Details

.create_with_products(params = {}) ⇒ Contract

Create contract with custom product items

Parameters:

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

    contract params including :items array

Returns:



145
146
147
 
# File 'lib/conexa/resources/contract.rb', line 145

def create_with_products(params = {})
  create(params)
end

.normalize_end_params(params) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use Util.normalize_end_date_param, which both "end" endpoints share.



138
139
140
 
# File 'lib/conexa/resources/contract.rb', line 138

def normalize_end_params(params)
  Util.normalize_end_date_param(params)
end

.set_end_date(id, params = {}) ⇒ Contract Also known as: end_contract

Set a contract's end date by ID

Parameters:

  • id (Integer, String) —

    contract ID

Returns:

See Also:



130
131
132
 
# File 'lib/conexa/resources/contract.rb', line 130

def set_end_date(id, params = {})
  find(id).set_end_date(params)
end

Instance Method Details

#active? ⇒ Boolean

Check if contract is active

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/conexa/resources/contract.rb', line 87

def active?
  status == 'active'
end

#end_contract ⇒ self

Set this contract's end date — closing it, or amending an existing closure.

The endpoint is documented as "encerra um contrato ativo ou atualiza a data de encerramento": it both closes and amends, and a future date on an already-closed contract reopens it. end_contract is kept as an alias, but the name understates what the call does.

A contract cannot be closed retroactively past a day that already has invoiced sales (422 CONTRACT_RECURRING_SALE_23).

The API may answer with an empty body on success.

Parameters:

  • params (Hash)

Returns:

  • (self) 


123
124
125
126
127
 
# File 'lib/conexa/resources/contract.rb', line 123

def set_end_date(params = {})
  params = self.class.normalize_end_params(params)
  Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
  self
end

#ended? ⇒ Boolean

Check if contract is cancelled/ended

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/conexa/resources/contract.rb', line 93

def ended?
  status == 'ended' || status == 'cancelled'
end

#set_end_date(params = {}) ⇒ self

Set this contract's end date — closing it, or amending an existing closure.

The endpoint is documented as "encerra um contrato ativo ou atualiza a data de encerramento": it both closes and amends, and a future date on an already-closed contract reopens it. end_contract is kept as an alias, but the name understates what the call does.

A contract cannot be closed retroactively past a day that already has invoiced sales (422 CONTRACT_RECURRING_SALE_23).

The API may answer with an empty body on success.

Parameters:

  • params (Hash) (defaults to: {})

Options Hash (params):

  • :date (String) —

    required, yyyy-MM-dd — the closing date

  • :reason_id (Integer) —

    closing-reason id, from Listagem de Contratos > Outros Cadastros > Motivo de Encerramento de Contrato

  • :unlink_customer (Boolean) —

    unlinks DDRs, mailboxes, extensions and recurring sales. Requires date <= today and no other active contracts; ends all the customer's recurring sales and cancels their uninvoiced sales.

  • :end_date (String) —

    deprecated alias for :date

Returns:

  • (self) 


118
119
120
121
122
 
# File 'lib/conexa/resources/contract.rb', line 118

def set_end_date(params = {})
  params = self.class.normalize_end_params(params)
  Conexa::Request.patch(self.class.show_url("end", primary_key), params: params).call(class_name)
  self
end