Class: Assinafy::Resources::FieldResource

Inherits:
BaseResource show all
Defined in:
lib/assinafy/resources/field_resource.rb,
sig/assinafy.rbs

Overview

Field definitions (reusable input fields) and per-value validation.

See https://api.assinafy.com.br/v1/docs#field-definition for the documentation of these endpoints.

Constant Summary

Constants inherited from BaseResource

BaseResource::AUTH_HEADERS, BaseResource::PAGINATION_HEADERS, BaseResource::PATH_SEGMENT

Instance Method Summary collapse

Methods inherited from BaseResource

#initialize

Constructor Details

This class inherits a constructor from Assinafy::Resources::BaseResource

Instance Method Details

#create(payload, account_id_override = nil) ⇒ Hash

Create a field definition.

Examples:

Create a text field

field = client.fields.create(type: 'text', name: 'customer-reference')

# Request body the SDK sends:
#   { "type": "text", "name": "customer-reference" }

# => {
#   "resource"       => "field_definition",
#   "id"             => "1032009e858cc1f859ccf3a61229",
#   "name"           => "customer-reference",
#   "type"           => "text",
#   "regex"          => nil,
#   "is_pre_defined" => false,
#   "is_active"      => true,
#   "is_required"    => true,
#   "is_standard"    => false,
#   "is_read_only"   => false,
#   "is_visible"     => true
# }

Parameters:

  • payload (Hash)
  • account_id_override (String, nil) (defaults to: nil)

Options Hash (payload):

  • :type (String) —

    required — e.g. text, cpf, email — see #types

  • :name (String) —

    required — display label

  • :regex (String) —

    optional validation regex (text fields)

  • :is_required (Boolean) —

    default true

Returns:

  • (Hash) —

    the created field definition (envelope data unwrapped)

See Also:

  • /accounts/{accountId}/fields


39
40
41
42
43
44
45
46
 
# File 'lib/assinafy/resources/field_resource.rb', line 39

def create(payload,  = nil)
  acc_id = ()
  body   = body_params(require_payload(payload))

  call('Failed to create field definition') do
    http_post("accounts/#{acc_id}/fields", body)
  end
end

#delete(field_id, account_id_override = nil) ⇒ nil

Delete a field definition. Fields used by any document cannot be deleted.

Examples:

Delete a field definition

client.fields.delete('1032009e858cc1f859ccf3a61229')
# => nil

Parameters:

  • field_id (String)
  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (nil) —

    the API returns data: []; the SDK normalizes this to nil

See Also:

  • /accounts/{account_id}/fields/{field_id}


170
171
172
173
174
175
176
177
 
# File 'lib/assinafy/resources/field_resource.rb', line 170

def delete(field_id,  = nil)
  acc_id = ()
  fid    = require_id(field_id, 'Field ID')

  call_void('Failed to delete field definition') do
    http_delete("accounts/#{acc_id}/fields/#{fid}")
  end
end

#get(field_id, account_id_override = nil) ⇒ Hash

Fetch a field definition by ID.

Examples:

Fetch one field definition

field = client.fields.get('1032009e858cc1f859ccf3a61229')

# => {
#   "resource"       => "field_definition",
#   "id"             => "1032009e858cc1f859ccf3a61229",
#   "name"           => "customer-reference",
#   "type"           => "text",
#   "regex"          => nil,
#   "is_pre_defined" => false,
#   "is_active"      => true,
#   "is_required"    => true,
#   "is_standard"    => false,
#   "is_read_only"   => false,
#   "is_visible"     => true
# }

Parameters:

  • field_id (String)
  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (Hash) —

    the field definition (envelope data unwrapped)

See Also:

  • /accounts/{accountId}/fields/{field_id}


108
109
110
111
112
113
114
115
 
# File 'lib/assinafy/resources/field_resource.rb', line 108

def get(field_id,  = nil)
  acc_id = ()
  fid    = require_id(field_id, 'Field ID')

  call('Failed to fetch field definition') do
    http_get("accounts/#{acc_id}/fields/#{fid}")
  end
end

#list(params = {}, account_id_override = nil) ⇒ Hash{Symbol=>Array,nil}

List field definitions.

NOTE: this endpoint does not send pagination headers, so meta is always nil here (unlike other list endpoints which return a pagination Hash).

Examples:

List including inactive fields

result = client.fields.list(include_inactive: true)

# => {
#   data: [
#     {
#       "id"             => "field-id",
#       "name"           => "Nome",
#       "type"           => "personName",
#       "regex"          => nil,
#       "is_pre_defined" => true,
#       "is_active"      => true,
#       "is_required"    => false,
#       "is_standard"    => false,
#       "is_read_only"   => false,
#       "is_visible"     => true
#     }
#     # ... (one Hash per field definition)
#   ],
#   meta: nil # this endpoint sends no pagination headers
# }

Parameters:

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

    include_inactive, include_standard

  • account_id_override (String, nil) (defaults to: nil)

Returns:

  • (Hash{Symbol=>Array,nil}) —

    { data: [...], meta: nil }

See Also:

  • /accounts/{accountId}/fields


78
79
80
81
82
83
84
 
# File 'lib/assinafy/resources/field_resource.rb', line 78

def list(params = {},  = nil)
  acc_id = ()

  call_list('Failed to list field definitions') do
    http_get("accounts/#{acc_id}/fields", params)
  end
end

#types ⇒ Array<Hash{String=>String}>

List the catalog of supported field types.

Examples:

List supported field types

types = client.fields.types

# => [
#   { "type" => "personName",  "name" => "Nome" },
#   { "type" => "cpf",         "name" => "CPF" },
#   { "type" => "phoneNumber", "name" => "Número de Telefone" },
#   { "type" => "postalCode",  "name" => "CEP" },
#   { "type" => "email",       "name" => "E-mail" },
#   { "type" => "cnpj",        "name" => "CNPJ" },
#   { "type" => "companyName", "name" => "Nome da empresa" },
#   { "type" => "email",       "name" => "E-mail" }, # the live catalog lists "email" twice
#   { "type" => "text",        "name" => "Texto" },
#   { "type" => "number",      "name" => "Número" },
#   { "type" => "date",        "name" => "Data" }
# ]

Returns:

  • (Array<Hash{String=>String}>) —

    each entry is { "type" =>, "name" => }

See Also:

  • /field-types


275
276
277
278
279
 
# File 'lib/assinafy/resources/field_resource.rb', line 275

def types
  call_array('Failed to list field types') do
    http_get('field-types')
  end
end

#update(field_id, payload, account_id_override = nil) ⇒ Hash

Update a field definition. The update endpoint accepts only name, regex, and is_active (unlike #create, it does not accept type or is_required).

Examples:

Rename a field definition

field = client.fields.update('1032009e858cc1f859ccf3a61229', name: 'New Field Name')

# Request body the SDK sends:
#   { "name": "New Field Name" }

# => {
#   "resource"       => "field_definition",
#   "id"             => "1032009e858cc1f859ccf3a61229",
#   "name"           => "New Field Name",
#   "type"           => "text",
#   "regex"          => nil,
#   "is_pre_defined" => false,
#   "is_active"      => true,
#   "is_required"    => true,
#   "is_standard"    => false,
#   "is_read_only"   => false,
#   "is_visible"     => true
# }

Parameters:

  • field_id (String)
  • payload (Hash)
  • account_id_override (String, nil) (defaults to: nil)

Options Hash (payload):

  • :name (String) —

    display label

  • :regex (String) —

    validation regex (text fields)

  • :is_active (Boolean) —

    enable/disable the field

Returns:

  • (Hash) —

    the updated field definition (envelope data unwrapped)

See Also:

  • /accounts/{account_id}/fields/{field_id}


148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/assinafy/resources/field_resource.rb', line 148

def update(field_id, payload,  = nil)
  acc_id = ()
  fid    = require_id(field_id, 'Field ID')
  raw    = require_payload(payload)
  body   = body_params(raw)
  body['regex'] = nil if (raw.key?(:regex) && raw[:regex].nil?) ||
                         (raw.key?('regex') && raw['regex'].nil?)

  call('Failed to update field definition') do
    http_put("accounts/#{acc_id}/fields/#{fid}", body)
  end
end

#validate(field_id, value, account_id_override = nil, signer_access_code: nil) ⇒ Hash{String=>Object}

Validate a single value against a field definition.

The OpenAPI declares workspace Authorization. The deployed API also accepts signer-access-code authentication; pass signer_access_code: to use that compatibility path without sending workspace credentials.

Examples:

Validate a value (workspace auth)

result = client.fields.validate('1032009e858cc1f859ccf3a61229', 'Some text')

# Request body the SDK sends:
#   { "value": "Some text" }

# => { "type" => "text", "success" => true, "error_message" => "" }

Validate as a signer (signer-access-code auth, sent as a query param)

client.fields.validate('field-id', 'Some text', signer_access_code: 'signer-access-code')
# => { "type" => "text", "success" => true, "error_message" => "" }

Parameters:

  • field_id (String)
  • value (Object)
  • account_id_override (String, nil) (defaults to: nil)
  • signer_access_code (String, nil) (defaults to: nil)

Returns:

  • (Hash{String=>Object}) —

    { "type" =>, "success" =>, "error_message" => }

Raises:

See Also:

  • /accounts/{accountId}/fields/{field_id}/validate


202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/assinafy/resources/field_resource.rb', line 202

def validate(field_id, value,  = nil, signer_access_code: nil)
  acc_id      = ()
  fid         = require_id(field_id, 'Field ID')
  raise ValidationError.new('Field value is required') if value.nil?

  access_code = signer_access_code.nil? ? nil : require_signer_access_code(signer_access_code)

  call('Failed to validate field value') do
    http_post("accounts/#{acc_id}/fields/#{fid}/validate", body_params(value: value),
              { signer_access_code: access_code }, workspace_auth: access_code.nil?)
  end
end

#validate_multiple(values, account_id_override = nil, signer_access_code: nil) ⇒ Array<Hash>

Validate many { field_id:, value: } pairs in a single call.

As with #validate, signer-access-code support is a deployed-API compatibility extension beyond the current OpenAPI security declaration.

Examples:

Validate several values at once

results = client.fields.validate_multiple([
  { field_id: '63488ffb7adf435aba319787', value: '1111111111111' },
  { field_id: '63488ffb0461cebb70775497', value: 'user@example.com' }
])

# Request body the SDK sends (an array, not an object):
#   [
#     { "field_id": "63488ffb7adf435aba319787", "value": "1111111111111" },
#     { "field_id": "63488ffb0461cebb70775497", "value": "user@example.com" }
#   ]

# => [
#   { "field_id" => "63488ffb7adf435aba319787", "type" => "cpf",
#     "success" => false, "error_message" => "Invalid CPF." },
#   { "field_id" => "63488ffb0461cebb70775497", "type" => "email",
#     "success" => true, "error_message" => "" }
# ]

Parameters:

  • values (Array<Hash>)
  • account_id_override (String, nil) (defaults to: nil)
  • signer_access_code (String, nil) (defaults to: nil)

Returns:

  • (Array<Hash>) —

    one validation Hash per input, each carrying its field_id

See Also:

  • /accounts/{accountId}/fields/validate-multiple


243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/assinafy/resources/field_resource.rb', line 243

def validate_multiple(values,  = nil, signer_access_code: nil)
  acc_id      = ()
  list        = require_array(values, 'Field values')
  access_code = signer_access_code.nil? ? nil : require_signer_access_code(signer_access_code)

  call_array('Failed to validate field values') do
    http_post("accounts/#{acc_id}/fields/validate-multiple",
              list.map { |item| field_value_payload(item) },
              { signer_access_code: access_code }, workspace_auth: access_code.nil?)
  end
end