assinafy 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2a0b97db3a9ad302307e31bccf8f06751fe310dd253417bb129ad921b0a4b3f
-  data.tar.gz: 94eb893e22a78777a0b4102d572e274e0f22c5b50cd3768d348f2deac69541ab
+  metadata.gz: 83473f4fd075a7c665a16ee6ea6c38c64c548927930221d24ecd468cce1f4203
+  data.tar.gz: 57c81beb685fe09baf9de80eb36abc628d224952b2b08e582d19e24ecb402c16
 SHA512:
-  metadata.gz: 43838b1c27e22fc5210a8e877a4e1897f50030a6e32801cf490f101de6d18805ed79bff013120801ce90ab53369531142bf678cbe0e04f543139aa72790bab11
-  data.tar.gz: f0e442b567d84643b2237ec21edf5b59de9155268451986dcdcc19f841ccf1514e1fd11e112fedc0ff1b8c04439feb411fec7ec37bc06128a86409996745798e
+  metadata.gz: dda868b4808b8885693edc57d8825eaf25a31dd628395180f651bd479a2b59ced524205683900812aa61654b2e79a7c69a110ca8c99c54ea084f21ea3515640a
+  data.tar.gz: ba6c518504f42fddaa0f9cfe4f58b0bfe6e23a83255f2cee5ef1a76551fba72b628f8ea448ba93b24201b055fd41c2ee95882534c3eedfb334f49a5b23cb5439

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## [2.0.1] - 2026-10-19
+
+### Fixed
+
+- Assignment creation and cost estimation reject `DigitalCertificate` signers unless the assignment method is
+  `virtual`, before an unsignable collect assignment can invite the signer or consume credits. The local
+  `ValidationError` exposes the stable code `digital_certificate_requires_virtual` in `errors[:code]`.
+
 ## [2.0.0] - 2026-10-16
 
 ### Added

data/README.en.md

@@ -394,9 +394,11 @@ the missing side is inferred from the other, and when both are omitted both defa
 - The certificate charge appears in the cost breakdown under the code `SignatureDigitalCertificate`. Resending a
   notification charges the notification again.
 - `DigitalCertificate` needs the Digital Certificate account feature (Standard and Pro plans), a CPF or CNPJ in the
-  signer's `government_id`, and the signer alone in its signing step. A CPF requires that person's 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.
+  signer's `government_id`, a `method: 'virtual'` assignment, and the signer alone in its signing step. A collect
+  assignment, including one inferred from a template with positioned signer fields, cannot use certificate
+  signing. Direct assignment creation and estimation reject it with `ValidationError` code
+  `digital_certificate_requires_virtual`. A CPF requires that person's 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.
 - `AssignmentResource::VERIFICATION_METHODS` and `::NOTIFICATION_METHODS` publish the enums. `build_payload`
   validates values, pairings, and `step` locally, so a typo fails before the request is sent.
 
@@ -433,10 +435,11 @@ assignment = client.assignments.create(
 assignment['signing_urls'] # => [{ 'signer_id' => 'signer-id', 'url' => 'https://.../sign/...' }, ...]
 ```
 
-`virtual` has no positioned fields; `collect` adds `entries` of positioned fields (see
-[Assignments](#assignments)). Both require a non-empty `signers` array. Steps are all-or-none, positive, and
-contiguous from 1; equal steps sign in parallel, and each step is notified when the previous one finishes. A
-certificate signer is alone in its step. Deadlines are zoned ISO 8601 and at least one hour ahead.
+`virtual` has no positioned fields and is required for `DigitalCertificate`; `collect` adds `entries` of
+positioned fields (see [Assignments](#assignments)). Both require a non-empty `signers` array. Steps are
+all-or-none, positive, and contiguous from 1; equal steps sign in parallel, and each step is notified when the
+previous one finishes. A certificate signer is alone in its step. Deadlines are zoned ISO 8601 and at least one
+hour ahead.
 
 For a template, bind one distinct existing signer to each role and create the document and assignment together:
 

data/README.md

@@ -531,9 +531,12 @@ dois, ambos assumem `Email`.
 ### Certificado digital ICP-Brasil (A1/A3)
 
 Exige o recurso **Certificado Digital** na conta (planos Standard e Pro), CPF ou CNPJ em
-`government_id` do signatário, e que cada signatário por certificado esteja **sozinho no seu
-passo**. Um CPF exige o certificado daquela pessoa (e-CPF, ou e-CNPJ que a nomeie como
-representante legal); um CNPJ exige um e-CNPJ da empresa, de qualquer um de seus representantes.
+`government_id` do signatário, assignment com `method: 'virtual'` e que cada signatário por certificado esteja
+**sozinho no seu passo**. Um assignment `collect`, inclusive quando inferido de um template com campos de
+signatário posicionados, não aceita certificado digital. A criação e a estimativa diretas levantam
+`ValidationError` com o código estável `digital_certificate_requires_virtual`. Um CPF exige o certificado daquela
+pessoa (e-CPF, ou e-CNPJ que a nomeie como representante legal); um CNPJ exige um e-CNPJ da empresa, de qualquer
+um de seus representantes.
 
 ---
 

data/docs/API_REFERENCE.md

@@ -308,9 +308,15 @@ on top of its notification, shown in cost estimates under the breakdown code `Si
 
 `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate (A1 or A3) through the Web PKI
 browser extension, producing a qualified PAdES signature. It requires the Digital Certificate account feature, a
-CPF or CNPJ in the signer's `government_id` (accepted by both `SignerResource#create` and `#update`), and that the
-signer is alone in its signing step. A CPF requires that person's 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.
+CPF or CNPJ in the signer's `government_id` (accepted by both `SignerResource#create` and `#update`), a
+`method: 'virtual'` assignment, and that the signer is alone in its signing step. `AssignmentResource#create` and
+`#estimate_cost` reject any other assignment method with `ValidationError`; its stable
+`errors[:code]` is `digital_certificate_requires_virtual`. A CPF requires that person's 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.
+
+A template with positioned signer fields creates a collect assignment, so it cannot be used with a
+`DigitalCertificate` signer. Use a template without positioned signer fields for certificate signing.
 
 Certificate signers complete the signature in Assinafy's hosted signing flow, reached through the assignment's
 `signing_urls`. The SDK does not wrap the two-step Web PKI handshake (`/signers/certificate/start`,

data/lib/assinafy/resources/assignment_resource.rb

@@ -11,6 +11,7 @@ module Assinafy
     class AssignmentResource < BaseResource
       OPTIONAL_FIELDS   = %i[message expires_at copy_receivers].freeze
       METHODS           = %w[virtual collect].freeze
+      DIGITAL_CERTIFICATE_REQUIRES_VIRTUAL = 'digital_certificate_requires_virtual'
 
       # How a signer's identity is verified before they may sign, set per signer
       # on the assignment. When omitted it is inferred from
@@ -24,7 +25,7 @@ module Assinafy
       #   certificate (A1 or A3), producing a qualified PAdES signature.
       #   Requires the Digital Certificate feature, a CPF or CNPJ in the
       #   signer's `government_id`, and that the signer is alone in its signing
-      #   step. Charged 0.5 credits per signer on top of its notification
+      #   step on a virtual assignment. Charged 0.5 credits per signer on top of its notification
       #   (breakdown code `SignatureDigitalCertificate`). A CPF requires that person's
       #   certificate (an e-CPF, or an e-CNPJ naming them as legal
       #   representative); a CNPJ requires an e-CNPJ for that company, from any
@@ -124,6 +125,7 @@ module Assinafy
 
           result = { method: method }
           normalised = signers.map { |ref| normalise_signer_ref(ref, options) }
+          validate_certificate_method!(method, normalised)
           validate_signing_steps!(normalised)
           result[:signers] = normalised unless normalised.empty?
           OPTIONAL_FIELDS.each { |key| result[key] = p[key] if p[key] }
@@ -254,6 +256,16 @@ module Assinafy
           raise ValidationError.new('notification_methods must match the verification_method')
         end
 
+        def validate_certificate_method!(method, signers)
+          return if method == 'virtual'
+          return unless signers.any? { |signer| signer[:verification_method] == 'DigitalCertificate' }
+
+          raise ValidationError.new(
+            'DigitalCertificate signers require method: virtual',
+            { code: DIGITAL_CERTIFICATE_REQUIRES_VIRTUAL, method: method }
+          )
+        end
+
         def validate_signing_steps!(signers)
           steps = signers.map { |signer| signer[:step] }
           contiguous = steps.compact.uniq.sort.each_with_index.all? { |step, index| step == index + 1 }

data/lib/assinafy/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Assinafy
-  VERSION = '2.0.0'
+  VERSION = '2.0.1'
   USER_AGENT = "Assinafy-Ruby-SDK/v#{VERSION}".freeze
 end

data/sig/assinafy.rbs

@@ -336,6 +336,7 @@ module Assinafy
       METHODS: Array[String]
       VERIFICATION_METHODS: Array[String]
       NOTIFICATION_METHODS: Array[String]
+      DIGITAL_CERTIFICATE_REQUIRES_VIRTUAL: String
       SIGN_ITEM_KEY_MAP: Hash[String, String]
       IDENTITY_REVIEW_IMAGES: Array[String]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: assinafy
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Assinafy SDK Contributors