assinafy 1.11.0 → 2.0.0

data/lib/assinafy/resources/assignment_resource.rb

@@ -29,7 +29,10 @@ module Assinafy
       #   certificate (an e-CPF, or an e-CNPJ naming them as legal
       #   representative); a CNPJ requires an e-CNPJ for that company, from any
       #   of its representatives.
-      VERIFICATION_METHODS = %w[Email Whatsapp DigitalCertificate].freeze
+      # - `IdDocumentFaceMatchBasic` — government ID photos, face match and liveness.
+      #   Requires its account feature and a valid CPF in `government_id`; priced per signer.
+      VERIFICATION_METHODS = %w[Email Whatsapp DigitalCertificate IdDocumentFaceMatchBasic].freeze
+      IDENTITY_REVIEW_IMAGES = %w[document_front document_back document_pdf face].freeze
 
       # Channels used to notify a signer of the request. Exactly one per signer;
       # WhatsApp incurs an additional cost and is available only on paid
@@ -52,12 +55,14 @@ module Assinafy
         # - `signers: [{ id:, verification_method:, notification_methods:, step: }]`
         # - Legacy `signer_ids:`/`signerIds:` arrays of IDs
         #
-        # @note Both methods require top-level `signers`; `collect` additionally
-        #   requires positioned `entries`.
+        # @note Creation requires top-level `signers` for both methods, and `collect` additionally
+        #   requires positioned `entries`; both are optional in estimate-cost payloads.
         # @param payload [Hash]
         # @param options [Hash]
         # @option options [Boolean] :allow_signers_without_id allow estimate-cost
         #   payloads where method-only signer descriptors carry no id
+        # @option options [Boolean] :require_signers (true) false for estimate-cost payloads, where
+        #   `signers` and `entries` are optional; an empty `signers` list is then omitted
         # @return [Hash] string-keyed body suitable for {#create} / {#estimate_cost}
         # @raise [Assinafy::ValidationError] on missing required fields
         # @example Bare signer IDs are normalised into { id: } hashes (virtual method)
@@ -114,12 +119,13 @@ module Assinafy
           entries = p[:entries]
           method  = (p[:method] || 'virtual').to_s
 
-          validate_method!(method, signers, entries, p)
+          validate_method!(method, signers, entries, p, options.fetch(:require_signers, true))
           validate_optional_fields!(p)
 
           result = { method: method }
-          result[:signers] = signers.map { |ref| normalise_signer_ref(ref, options) }
-          validate_signing_steps!(result[:signers])
+          normalised = signers.map { |ref| normalise_signer_ref(ref, options) }
+          validate_signing_steps!(normalised)
+          result[:signers] = normalised unless normalised.empty?
           OPTIONAL_FIELDS.each { |key| result[key] = p[key] if p[key] }
           result[:entries] = entries if entries
           Utils.body_params(result)
@@ -127,13 +133,13 @@ module Assinafy
 
         private
 
-        def validate_method!(method, signers, entries, payload)
+        def validate_method!(method, signers, entries, payload, require_signers)
           unless METHODS.include?(method)
             raise ValidationError.new("Assignment method must be one of: #{METHODS.join(', ')}")
           end
+          return unless require_signers
 
-          # `signers` is required for both methods: creation needs to know who signs, and the
-          # estimate is priced per signer. Positioned fields do not replace this list.
+          # Creation needs `signers` for both methods; positioned fields do not replace this list.
           if signers.empty?
             raise ValidationError.new(
               'At least one signer is required',
@@ -241,7 +247,8 @@ module Assinafy
         def validate_method_pair!(signer)
           verification = signer[:verification_method]
           notification = signer[:notification_methods]&.first
-          return if verification.nil? || notification.nil? || verification == 'DigitalCertificate'
+          return if verification.nil? || notification.nil? ||
+                    %w[DigitalCertificate IdDocumentFaceMatchBasic].include?(verification)
           return if verification == notification
 
           raise ValidationError.new('notification_methods must match the verification_method')
@@ -356,7 +363,7 @@ module Assinafy
       # `id`. An empty descriptor (`{}`) defaults both methods to `Email`.
       #
       # @param document_id [String]
-      # @param payload     [Hash]
+      # @param payload     [Hash] `method`, and optional `signers` (method-only descriptors) and `entries`
       # @return [Hash] cost breakdown (documents, credits, needs_extra_document, extra_document_cost,
       #   total_credits, breakdown[], document_balance, credit_balance, has_sufficient_resources,
       #   blocking_reason, message)
@@ -379,7 +386,7 @@ module Assinafy
       #   # }
       def estimate_cost(document_id, payload)
         doc_id = require_id(document_id, 'Document ID')
-        body   = self.class.build_payload(payload, allow_signers_without_id: true)
+        body   = self.class.build_payload(payload, allow_signers_without_id: true, require_signers: false)
 
         call('Failed to estimate assignment cost') do
           http_post("documents/#{doc_id}/assignments/estimate-cost", body)
@@ -485,6 +492,95 @@ module Assinafy
         end
       end
 
+      # Read the account review of a signer's biometric identity verification.
+      # Evidence contains summaries; images are available only while InReview.
+      # The signer can sign during review, but certification awaits approval.
+      #
+      # @param document_id [String]
+      # @param assignment_id [String]
+      # @param signer_id [String]
+      # @return [Hash] SignerIdentityReview; see docs/API_REFERENCE.md#signeridentityreview for all fields
+      # @raise [Assinafy::ApiError] on failure, including 404 when no verification exists
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid IDs
+      # @see GET /documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/identity-verification
+      # @example Read an open review (no request body; workspace credentials)
+      #   client.assignments.identity_review('document-id', 'assignment-id', 'signer-id')
+      #   # => { 'id' => 'verification-id', 'status' => 'InReview', 'provider' => 'AssinafyVerify',
+      #   #      'verification_method' => 'IdDocumentFaceMatchBasic',
+      #   #      'reason_codes' => [{ 'code' => 'NAME_MISMATCH', 'description' => 'Name differs' }],
+      #   #      'evidence_available' => true, 'expected' => { 'name' => 'Example Signer', 'cpf' => nil },
+      #   #      'document' => { 'type' => 'CNH', 'name' => 'EXAMPLE SIGNER', 'cpf' => nil },
+      #   #      'matches' => { 'cpf' => true, 'name' => 0.52, 'birth_date' => nil },
+      #   #      'checks' => [{ 'name' => 'name', 'result' => 'review', 'score' => 0.52,
+      #   #                     'reasons' => ['NAME_MISMATCH'] }], 'images' => ['document_front', 'face'],
+      #   #      'ruleset_version' => '2026-10-12.2', 'evidence_sha256' => 'sha256-placeholder',
+      #   #      'reviewed_by' => nil, 'reviewed_at' => nil, 'review_note' => nil, 'completed_at' => nil }
+      def identity_review(document_id, assignment_id, signer_id)
+        path = identity_review_path(document_id, assignment_id, signer_id)
+
+        call('Failed to fetch signer identity review') { http_get(path) }
+      end
+
+      # Download one evidence image or document PDF while a review is InReview.
+      # Fetched from the provider on each call; keep the sensitive bytes out of logs and caches.
+      #
+      # @param document_id [String]
+      # @param assignment_id [String]
+      # @param signer_id [String]
+      # @param name [String] document_front, document_back, document_pdf or face, as listed in the review
+      # @return [String] binary JPEG, PNG or PDF bytes
+      # @raise [Assinafy::ApiError] on failure; 404 after a decision or when evidence is unavailable
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid IDs or image name
+      # @see GET /documents/{document}/assignments/{assignment}/signers/{signer}/identity-verification/images/{name}
+      # @example Read the face image (no request body; workspace credentials)
+      #   client.assignments.identity_review_image('document-id', 'assignment-id', 'signer-id', 'face')
+      #   # => "\x89PNG\r\n\x1A\n..." # binary String
+      def identity_review_image(document_id, assignment_id, signer_id, name)
+        path = identity_review_path(document_id, assignment_id, signer_id)
+        unless IDENTITY_REVIEW_IMAGES.include?(name)
+          raise ValidationError.new("Image name must be one of: #{IDENTITY_REVIEW_IMAGES.join(', ')}")
+        end
+
+        call_binary('Failed to download signer identity review image') { http_get("#{path}/images/#{name}") }
+      end
+
+      # Approve or reject an InReview identity verification. Rejection cancels the
+      # document and notifies every signer and copy receiver. The note is recorded
+      # in activities and sent to the provider; it is never shown to the signer.
+      #
+      # @param document_id [String]
+      # @param assignment_id [String]
+      # @param signer_id [String]
+      # @param decision [String] Approved or Rejected
+      # @param note [String, nil] optional review note, at most 2000 characters
+      # @return [Hash] SignerIdentityReview, the same fields as {#identity_review}, with the decision recorded
+      # @raise [Assinafy::ApiError] on failure; 400 unless InReview and awaiting signatures or identity review
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid IDs, decision or note
+      # @see POST /documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/identity-verification/review
+      # @example Approve a review with workspace credentials
+      #   client.assignments.decide_identity_review('document-id', 'assignment-id', 'signer-id',
+      #                                             decision: 'Approved', note: 'Identity checked')
+      #   # Body: { 'decision' => 'Approved', 'note' => 'Identity checked' }
+      #   # => the identity_review object with 'status' => 'Approved', 'images' => [],
+      #   #    'reviewed_by' => { 'id' => 'user-id', 'name' => 'Example Reviewer' },
+      #   #    'reviewed_at' => '2026-10-16T12:00:00Z', 'review_note' => 'Identity checked'
+      def decide_identity_review(document_id, assignment_id, signer_id, decision:, note: nil)
+        path = identity_review_path(document_id, assignment_id, signer_id)
+        unless %w[Approved Rejected].include?(decision)
+          raise ValidationError.new('Decision must be Approved or Rejected')
+        end
+        unless note.nil? || (note.is_a?(String) && note.length <= 2000)
+          raise ValidationError.new('Review note must be a String of at most 2000 characters')
+        end
+
+        call('Failed to decide signer identity review') do
+          http_post("#{path}/review", body_params(decision: decision, note: note))
+        end
+      end
+
       # Fetch the document a signer is being asked to sign (signer-access-code auth).
       #
       # @param signer_access_code  [String]
@@ -623,6 +719,13 @@ module Assinafy
 
       private
 
+      def identity_review_path(document_id, assignment_id, signer_id)
+        doc_id = require_id(document_id, 'Document ID')
+        asg_id = require_id(assignment_id, 'Assignment ID')
+        sid    = require_id(signer_id, 'Signer ID')
+        "documents/#{doc_id}/assignments/#{asg_id}/signers/#{sid}/identity-verification"
+      end
+
       def normalise_sign_item(item)
         normalised = require_payload(item, 'Assignment item').each_with_object({}) do |(key, value), result|
           raw = key.to_s

data/lib/assinafy/resources/base_resource.rb

@@ -17,6 +17,11 @@ module Assinafy
         total:        'x-pagination-total-count',
         last_page:    'x-pagination-page-count'
       }.freeze
+      RATE_LIMIT_HEADERS = {
+        limit:     'x-rate-limit-limit',
+        remaining: 'x-rate-limit-remaining',
+        reset:     'x-rate-limit-reset'
+      }.freeze
 
       # @param connection         [Faraday::Connection]
       # @param default_account_id [String, nil] used by `account_id` when no override is passed
@@ -297,23 +302,32 @@ module Assinafy
 
       # On a `403` the `WWW-Authenticate` challenge names the scope an OAuth
       # token is missing, which tells "reconnect with more scope" apart from
-      # "wrong workspace or role", so it travels with the error.
+      # "wrong workspace or role", so it travels with the error, as do the
+      # rate-limit headers a `429` needs for backing off.
       def check_status!(response, _label)
         return if (200..299).cover?(response.status)
 
-        raise with_challenge(error_class.from_response(response.status, response.body), response)
+        raise with_response_headers(error_class.from_response(response.status, response.body), response)
       end
 
-      # A 2xx envelope can still carry an error status, with the same challenge.
+      # A 2xx envelope can still carry an error status, with the same headers.
       def unwrap(response)
         Utils.handle_assinafy_response(response.body)
       rescue ApiError => e
-        raise with_challenge(e, response)
+        raise with_response_headers(e, response)
       end
 
-      def with_challenge(error, response)
-        challenge = response.headers&.[]('www-authenticate')
+      def with_response_headers(error, response)
+        headers = response.headers || {}
+        challenge = headers['www-authenticate']
         error.context[:www_authenticate] = challenge if challenge
+        rate_limit = RATE_LIMIT_HEADERS.filter_map do |key, header|
+          value = to_int(headers[header])
+          [key, value] if value
+        end.to_h
+        error.context[:rate_limit] = rate_limit unless rate_limit.empty?
+        retry_after = to_int(headers['retry-after'])
+        error.context[:retry_after] = retry_after if retry_after
         error
       end
 

data/lib/assinafy/resources/document_resource.rb

@@ -131,7 +131,7 @@ module Assinafy
       # Lightweight search over an account's documents (id/name/status/artifacts),
       # without the heavier per-document detail returned by {#list}.
       #
-      # @param query [String] free-text search term
+      # @param query [String, nil] optional free-text search term; nil omits `search`
       # @param params [Hash] extra query parameters (`status`, `page`, `per_page`, ...)
       # @param account_id_override [String, nil]
       # @return [Hash{Symbol=>Array,Hash}] `{ data: [...], meta: {..} | nil }`
@@ -162,10 +162,10 @@ module Assinafy
       #       # ... (one Hash per matching document)
       #     ]
       #   }
-      def search(query, params = {}, account_id_override = nil)
+      def search(query = nil, params = {}, account_id_override = nil)
         acc_id = account_id(account_id_override)
         filters = require_payload(params, 'Document search parameters')
-        require_string(query, 'Search query')
+        require_string(query, 'Search query') unless query.nil?
 
         call_list('Failed to search documents') do
           http_get("accounts/#{acc_id}/documents/search", filters.merge(search: query))
@@ -253,7 +253,7 @@ module Assinafy
       # Rename a document.
       #
       # @param document_id [String]
-      # @param name        [String] the new display name
+      # @param name        [String] the new display name (at most 255 characters)
       # @return [Hash] the updated document object (envelope `data` unwrapped)
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
@@ -281,7 +281,7 @@ module Assinafy
       #   }
       def rename(document_id, name)
         doc_id   = require_id(document_id, 'Document ID')
-        new_name = require_string(name, 'Name')
+        new_name = require_string(name, 'Name', max_length: 255)
 
         call('Failed to rename document') do
           http_patch("documents/#{doc_id}", body_params(name: new_name))
@@ -664,67 +664,41 @@ module Assinafy
         end
       end
 
-      # Send a 6-digit access token for the document to a signer (public endpoint).
-      # The current OpenAPI permits no body or an `{ email: }` body, while the
-      # deployed API requires `{ recipient:, channel: }` when a recipient is supplied.
+      # Email a 6-digit access token for the document to its signer (public endpoint;
+      # no workspace credentials are sent).
       #
       # @param document_id [String]
-      # @param recipient   [String, nil] deployed-API email address or WhatsApp phone number
-      # @param channel     [String, nil] deployed-API `email` or `whatsapp` channel
-      # @param email       [String, nil] email address for the current OpenAPI request shape
-      # @return [nil, Hash] `nil` for the OpenAPI's no-data envelope; the deployed
-      #   API returns `{ 'document' => {..}, 'channel' => String, 'recipient' => String }`
+      # @param recipient   [String] the signer's email address (required)
+      # @param channel     [String] delivery channel; only `"email"` is accepted
+      # @param email       [String, nil] earlier name for `recipient:`; sent as `recipient`
+      # @return [Hash] `{ 'document' => Hash, 'channel' => String, 'recipient' => String }`
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
-      # @raise [Assinafy::ValidationError] on invalid required input
+      # @raise [Assinafy::ValidationError] when the recipient is missing or not an email address,
+      #   when the channel is not `email`, or when both `recipient:` and `email:` are given
       # @see PUT /public/documents/{document_id}/send-token
-      # @example Ask the API to use the document's signer contact (no auth required)
-      #   client.documents.send_token('document-id')
+      # @example Email the access token to the signer (no auth required)
+      #   client.documents.send_token('document-id', recipient: 'signer@example.com')
       #
-      # @example Email a signer using the current OpenAPI request (no auth required)
       #   # Request: PUT /public/documents/{document_id}/send-token
-      #   # Body: { "email": "signer@example.com" }
-      #   client.documents.send_token('document-id', email: 'signer@example.com')
-      #
-      # @example Use the deployed-API request shape
-      #   # Body: { "recipient": "signer@example.com", "channel": "email" }
-      #   client.documents.send_token('document-id', recipient: 'signer@example.com', channel: 'email')
+      #   # Body: { "channel": "email", "recipient": "signer@example.com" }
       #
-      #   # Deployed-API response (unwrapped data payload):
-      #   {
-      #     'document' => {
-      #       'resource' => 'document',
-      #       'id' => 'doc1',
-      #       'name' => '1.pdf',
-      #       'page_count' => '1',
-      #       'created_by' => 'John Smith'
-      #     },
-      #     'channel' => 'email',
-      #     'recipient' => 'signer@example.com'
-      #   }
-      #   # => nil when the API returns the documented no-data envelope
-      def send_token(document_id, recipient: nil, channel: nil, email: nil)
+      #   # => {
+      #   #   'document'  => { 'resource' => 'document', 'id' => 'doc1', 'name' => '1.pdf',
+      #   #                    'page_count' => 1, 'created_by' => 'John Smith' },
+      #   #   'channel'   => 'email',
+      #   #   'recipient' => 'signer@example.com'
+      #   # }
+      def send_token(document_id, recipient: nil, channel: 'email', email: nil)
         doc_id = require_id(document_id, 'Document ID')
-        if email.nil? && recipient.nil? && channel.nil?
-          payload = nil
-        elsif !email.nil?
-          if recipient || channel
-            raise ValidationError.new('Use either email or recipient/channel, not both')
-          end
+        raise ValidationError.new('Use either recipient or email, not both') if recipient && email
+        raise ValidationError.new('Channel must be email') unless channel == 'email'
 
-          payload = { email: Utils.require_email(email) }
-        else
-          require_string(recipient, 'Recipient')
-          delivery_channel = require_present(channel, 'Channel').to_s
-          unless %w[email whatsapp].include?(delivery_channel)
-            raise ValidationError.new('Channel must be email or whatsapp')
-          end
-
-          payload = { recipient: recipient, channel: delivery_channel }
-        end
+        address = Utils.require_email(recipient || email)
 
         call('Failed to send signer token') do
-          http_put("public/documents/#{doc_id}/send-token", payload && body_params(payload), workspace_auth: false)
+          http_put("public/documents/#{doc_id}/send-token", { 'channel' => 'email', 'recipient' => address },
+                   workspace_auth: false)
         end
       end
 

data/lib/assinafy/resources/field_resource.rb

@@ -7,12 +7,17 @@ module Assinafy
     # See https://api.assinafy.com.br/v1/docs#field-definition for the
     # documentation of these endpoints.
     class FieldResource < BaseResource
+      # Default for `signer_access_code:`, telling an omitted keyword (workspace credentials)
+      # apart from an explicit nil (rejected).
+      WORKSPACE = Object.new.freeze
+      private_constant :WORKSPACE
+
       # Create a field definition.
       #
       # @param payload [Hash]
       # @option payload [String]  :type        required — e.g. `text`, `cpf`, `email` — see {#types}
       # @option payload [String]  :name        required — display label
-      # @option payload [String]  :regex       optional validation regex (text fields)
+      # @option payload [String, nil] :regex   optional validation regex (text fields); nil is sent as null
       # @option payload [Boolean] :is_required default `true`
       # @param account_id_override [String, nil]
       # @return [Hash] the created field definition (envelope `data` unwrapped)
@@ -41,7 +46,8 @@ module Assinafy
       #   # }
       def create(payload, account_id_override = nil)
         acc_id = account_id(account_id_override)
-        body   = body_params(require_payload(payload))
+        raw    = require_payload(payload)
+        body   = with_explicit_regex(raw, body_params(raw))
         require_string(body['name'], 'Field name')
         require_string(body['type'], 'Field type')
         require_boolean(body['is_required'], 'is_required') if body.key?('is_required')
@@ -163,9 +169,7 @@ module Assinafy
         acc_id = account_id(account_id_override)
         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?)
+        body   = with_explicit_regex(raw, body_params(raw))
         require_string(body['name'], 'Field name') if body.key?('name')
         require_boolean(body['is_active'], 'is_active') if body.key?('is_active')
 
@@ -197,14 +201,15 @@ module Assinafy
 
       # 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.
+      # The OpenAPI declares workspace Authorization, which is used when
+      # `signer_access_code:` is omitted. The deployed API also accepts the signer
+      # access code: when the keyword is given it must be a non-blank code, and
+      # only the code is sent (never the workspace credentials).
       #
       # @param field_id             [String]
       # @param value                [Object]
       # @param account_id_override  [String, nil]
-      # @param signer_access_code   [String, nil]
+      # @param signer_access_code   [String] optional keyword; nil or blank raises
       # @return [Hash{String=>Object}] `{ "type" =>, "success" =>, "error_message" => }`
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
@@ -221,12 +226,12 @@ module Assinafy
       # @example 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" => "" }
-      def validate(field_id, value, account_id_override = nil, signer_access_code: nil)
+      def validate(field_id, value, account_id_override = nil, signer_access_code: WORKSPACE)
         acc_id      = account_id(account_id_override)
         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)
+        access_code = field_access_code(signer_access_code)
 
         call('Failed to validate field value') do
           http_post("accounts/#{acc_id}/fields/#{fid}/validate", body_params(value: value),
@@ -236,12 +241,12 @@ module Assinafy
 
       # 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.
+      # As with {#validate}, omitting `signer_access_code:` uses the workspace
+      # credentials; giving it requires a non-blank code and sends only the code.
       #
       # @param values               [Array<Hash>]
       # @param account_id_override  [String, nil]
-      # @param signer_access_code   [String, nil]
+      # @param signer_access_code   [String] optional keyword; nil or blank raises
       # @return [Array<Hash>] one validation Hash per input, each carrying its `field_id`
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
@@ -265,10 +270,10 @@ module Assinafy
       #   #   { "field_id" => "field-id-2", "type" => "email",
       #   #     "success" => true, "error_message" => "" }
       #   # ]
-      def validate_multiple(values, account_id_override = nil, signer_access_code: nil)
+      def validate_multiple(values, account_id_override = nil, signer_access_code: WORKSPACE)
         acc_id      = account_id(account_id_override)
         list        = require_array(values, 'Field values')
-        access_code = signer_access_code.nil? ? nil : require_signer_access_code(signer_access_code)
+        access_code = field_access_code(signer_access_code)
 
         call_array('Failed to validate field values') do
           http_post("accounts/#{acc_id}/fields/validate-multiple",
@@ -308,6 +313,16 @@ module Assinafy
 
       private
 
+      def field_access_code(signer_access_code)
+        signer_access_code.equal?(WORKSPACE) ? nil : require_signer_access_code(signer_access_code)
+      end
+
+      # `regex` is nullable: an explicit nil is sent as JSON null to clear it.
+      def with_explicit_regex(raw, body)
+        body['regex'] = nil if [:regex, 'regex'].any? { |key| raw.key?(key) && raw[key].nil? }
+        body
+      end
+
       def field_value_payload(item)
         payload = require_payload(item, 'Field value')
         field_id = payload.key?(:field_id) ? payload[:field_id] : payload['field_id']