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.

Attributes

Checked against a live response, not only the collection — which omits isActive, extraFields and firstDueDate from its GET /contract/:id examples even though the API returns them.

There is no status field on a contract. is_active is how you tell an open contract from a closed one.

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 included from Deprecatable

#deprecate

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

#amount ⇒ Float (readonly)

Returns contract value.

Returns:

  • (Float) —

    contract value



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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)



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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_summary ⇒ String? (readonly)

Returns short description.

Returns:

  • (String, nil) —

    short description



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#cost_center_id ⇒ Integer? (readonly)

Returns cost centre — present on read, rejected on create.

Returns:

  • (Integer, nil) —

    cost centre — present on read, rejected on create



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#date_sales_generation ⇒ String? (readonly)

Returns when sales are generated from the contract.

Returns:

  • (String, nil) —

    when sales are generated from the contract



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#due_day ⇒ Integer (readonly)

Returns day of the month the contract falls due.

Returns:

  • (Integer) —

    day of the month the contract falls due



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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 closing date. May be in the future on an active contract — a scheduled close is not a closed contract.

Returns:

  • (String, nil) —

    closing date. May be in the future on an active contract — a scheduled close is not a closed contract.



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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_reason_id ⇒ Integer? (readonly)

Returns closing-reason id.

Returns:

  • (Integer, nil) —

    closing-reason id



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#fidelity_date ⇒ String? (readonly)

Returns loyalty date.

Returns:

  • (String, nil) —

    loyalty date



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#first_due_date ⇒ String? (readonly)

Returns due date of the first instalment.

Returns:

  • (String, nil) —

    due date of the first instalment



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#had_prorata ⇒ Boolean (readonly)

Returns whether pro rata was applied.

Returns:

  • (Boolean) —

    whether pro rata was applied



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#is_active ⇒ Boolean (readonly)

Returns whether the contract is open.

Returns:

  • (Boolean) —

    whether the contract is open



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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_frequency ⇒ String (readonly)

Returns monthly, bimonthly, quarterly, semester or yearly.

Returns:

  • (String) —

    monthly, bimonthly, quarterly, semester or yearly



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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

#seller_id ⇒ Integer? (readonly)

Returns seller (user) id.

Returns:

  • (Integer, nil) —

    seller (user) id



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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



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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/conexa/resources/contract.rb', line 108

class Contract < Model
  primary_key_attribute :contract_id

  # Is this contract open?
  #
  # Reads +is_active+, which is what the API sends. It used to compare a
  # +status+ field that contracts have never had, so it answered +false+ for an
  # active contract — the answer that makes a caller create a second one.
  #
  # Deliberately not derived from +end_date+: an active contract can carry a
  # future closing date, so a present +end_date+ does not mean closed.
  #
  # **Prefer {#ended?} over `!active?`.** Ruby cannot tell +nil+ from +false+
  # through `!`, so `!active?` reads an *unknown* contract as closed — the
  # same "treat unknown as inactive" that this fix exists to remove. `ended?`
  # preserves the nil.
  #
  # @return [Boolean, nil] nil when the response did not carry +is_active+,
  #   rather than a guess
  def active?
    value = is_active
    value.nil? ? nil : !!value
  end

  # Is this contract closed?
  # @see #active?
  # @return [Boolean, nil] nil when the response did not carry +is_active+
  def ended?
    value = active?
    value.nil? ? nil : !value
  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:



188
189
190
 
# File 'lib/conexa/resources/contract.rb', line 188

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.



181
182
183
 
# File 'lib/conexa/resources/contract.rb', line 181

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:



173
174
175
 
# File 'lib/conexa/resources/contract.rb', line 173

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

Instance Method Details

#active? ⇒ Boolean?

Is this contract open?

Reads is_active, which is what the API sends. It used to compare a status field that contracts have never had, so it answered false for an active contract — the answer that makes a caller create a second one.

Deliberately not derived from end_date: an active contract can carry a future closing date, so a present end_date does not mean closed.

Prefer #ended? over !active?. Ruby cannot tell nil from false through !, so !active? reads an unknown contract as closed — the same "treat unknown as inactive" that this fix exists to remove. ended? preserves the nil.

Returns:

  • (Boolean, nil) —

    nil when the response did not carry is_active, rather than a guess



127
128
129
130
 
# File 'lib/conexa/resources/contract.rb', line 127

def active?
  value = is_active
  value.nil? ? nil : !!value
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) 


166
167
168
169
170
 
# File 'lib/conexa/resources/contract.rb', line 166

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?

Is this contract closed?

Returns:

  • (Boolean, nil) —

    nil when the response did not carry is_active

See Also:



135
136
137
138
 
# File 'lib/conexa/resources/contract.rb', line 135

def ended?
  value = active?
  value.nil? ? nil : !value
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) 


161
162
163
164
165
 
# File 'lib/conexa/resources/contract.rb', line 161

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