assinafy 1.11.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c9d44ba9996ee18372b0c965c691f9a74695b98ffd85ebe5e43ae29a4f3b662
-  data.tar.gz: a0313ec17a476c5439eab8fd004936c337b4b99e14323b8dfd864553b68f22d9
+  metadata.gz: d2a0b97db3a9ad302307e31bccf8f06751fe310dd253417bb129ad921b0a4b3f
+  data.tar.gz: 94eb893e22a78777a0b4102d572e274e0f22c5b50cd3768d348f2deac69541ab
 SHA512:
-  metadata.gz: 4a3e1ef28628add0a0e5abfc6f59f09f5ea0fe09c067a6fbb8cb3b767771590479bb8493b525ce389d2a572f15eea8257ed9a1ba47e68e7be1297603777febbd
-  data.tar.gz: 159e300170cd02a74d7668084362b5c80f5e99eea2653e2fd5f9faa0a838446b3987f9d5cd9df131cf0f2feba6a0dd50fdae0de4351ebba213c92e942ea3d529
+  metadata.gz: 43838b1c27e22fc5210a8e877a4e1897f50030a6e32801cf490f101de6d18805ed79bff013120801ce90ab53369531142bf678cbe0e04f543139aa72790bab11
+  data.tar.gz: f0e442b567d84643b2237ec21edf5b59de9155268451986dcdcc19f841ccf1514e1fd11e112fedc0ff1b8c04439feb411fec7ec37bc06128a86409996745798e

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## [2.0.0] - 2026-10-16
+
+### Added
+
+- `IdDocumentFaceMatchBasic` biometric verification in assignments, cost estimates and template generation,
+  paired with either Email or Whatsapp notifications.
+- `SignerResource#identity_verification` and `#start_identity_verification` for hosted identity verification
+  with explicit biometric-processing consent and signer-only authentication.
+- `AssignmentResource#identity_review`, `#identity_review_image` and `#decide_identity_review` for account
+  reviewers to inspect evidence and approve or reject a biometric identity review.
+- `WebhookResource#list_endpoints(url:)` filters by exact URL, and `#delete_endpoint_by_url` removes the endpoint
+  registered with that URL.
+
 ## [1.11.1] - 2026-10-12
 
 ### Added

data/README.en.md

@@ -388,6 +388,7 @@ the missing side is inferred from the other, and when both are omitted both defa
 | `Email` *(default)* | One-time code (OTP) by email before signing | `Email` | 0 credits |
 | `Whatsapp` | One-time code (OTP) over WhatsApp; needs `whatsapp_phone_number` and a paid plan | `Whatsapp` | 0.45 credits (the WhatsApp notification) |
 | `DigitalCertificate` | Signs with their own ICP-Brasil certificate (A1/A3), producing a qualified PAdES signature | `Email` **or** `Whatsapp` | 0.5 credits + its notification (0 or 0.45) |
+| `IdDocumentFaceMatchBasic` | Government ID photos, a photo holding the ID and liveness; requires its account feature and a valid CPF in `government_id` | `Email` **or** `Whatsapp` | Per-signer fee + notification; request an estimate |
 
 - Send exactly one channel in `notification_methods` (a one-element array).
 - The certificate charge appears in the cost breakdown under the code `SignatureDigitalCertificate`. Resending a
@@ -517,6 +518,48 @@ signing.assignments.decline(
 )
 ```
 
+**Biometric signers** use `verification_method: 'IdDocumentFaceMatchBasic'` with exactly one Email or Whatsapp
+notification in virtual/collect assignments or template generation. Store a valid CPF in the signer's
+`government_id` first and call `estimate_cost` or `estimate_cost_from_template` for the current price.
+The OTP example above applies to Email/Whatsapp. For biometrics, read the verification state and collect explicit
+biometric-processing consent before starting:
+
+```ruby
+state = signing.signers.identity_verification(signer_access_code: access_code)
+# => { 'can_start' => true, 'status' => nil, 'url' => nil, 'expires_at' => nil, 'completed_at' => nil }
+
+# After the signer explicitly consents to biometric processing:
+session = signing.signers.start_identity_verification(consent: true, signer_access_code: access_code)
+# => { 'id' => 'verification-id', 'url' => 'https://verify.assinafy.com.br/c/session#t=token-placeholder',
+#      'expires_at' => '2026-10-16T13:00:00Z' }
+```
+
+Open the capture URL unchanged, including its `#t=` fragment. It is a bearer link: keep it out of logs and browser
+storage. For an existing Pending session, use the URL from `identity_verification`. `can_start` is true only
+before any session or after Expired; restarting an Expired session costs nothing extra. Declined or Abandoned
+requires a new document and assignment.
+
+InReview lets the signer view, confirm data and sign while account review holds certification. After all signers
+sign, the document can be `pending_identity_review`. The account reviewer uses workspace credentials:
+
+```ruby
+review = client.assignments.identity_review(document.fetch('id'), assignment.fetch('id'), signer.fetch('id'))
+# => SignerIdentityReview: status, reason_codes, evidence_available, expected, document, matches,
+#    checks, images, ruleset_version, evidence_sha256 and decision metadata
+image = client.assignments.identity_review_image(document.fetch('id'), assignment.fetch('id'), signer.fetch('id'), 'face')
+# => JPEG, PNG or PDF bytes, depending on the name listed in review['images']; do not cache
+
+# After the reviewer checks the evidence:
+client.assignments.decide_identity_review(
+  document.fetch('id'), assignment.fetch('id'), signer.fetch('id'), decision: 'Approved', note: 'Identity checked'
+)
+```
+
+`decision: 'Rejected'` cancels the document and notifies signers and copy receivers. The optional note accepts at
+most 2000 characters, goes to activities and the provider, and is never shown to the signer. Images exist only
+during InReview. Observe signer_identity_review_required, signer_identity_review_approved,
+signer_identity_review_rejected, signer_identity_verified and signer_identity_verification_failed events.
+
 **A1/A3 certificate signers** complete their signature in Assinafy's hosted signing flow, opened from
 `assignment['signing_urls']`: they accept the terms, confirm their data, and sign with their A1 or A3 certificate
 through the Web PKI browser extension. The ordinary signing endpoint rejects certificate signers, and the SDK does
@@ -538,7 +581,7 @@ endpoint = client.webhooks.create_endpoint(
   name:            'ERP',
   signing_enabled: true
 )
-secret = client.webhooks.endpoint_secret(endpoint.fetch('id'))['secret']  # => "whsec_..."
+secret = endpoint.fetch('secret') # returned once on creation; store it immediately, including for OAuth apps
 ```
 
 - `create_endpoint` requires `url`, `email`, and `events`; `name`, `is_active` (default `true`), and
@@ -548,7 +591,9 @@ secret = client.webhooks.endpoint_secret(endpoint.fetch('id'))['secret']  # => "
   endpoint has none and keeps the current one otherwise; `false` discards it.
 - `rotate_endpoint_secret(id)` returns a new secret; the old one stops working immediately.
 - Reading and rotating secrets is not available to OAuth applications — use an API key or a user session token.
-  Both answer `400` when signing is disabled.
+  Both answer `400` when signing is disabled. An OAuth app that loses its secret must delete and recreate the endpoint.
+- `list_endpoints(url: registered_url)` filters by exact URL; `delete_endpoint_by_url(registered_url)` removes
+  that endpoint and returns `nil` (`404` when no endpoint matches).
 
 **Delivery contract.** Each delivery is a `POST` with an `application/json` body and the headers `webhook-id`
 (identical on every attempt of the same event to the same endpoint — deduplicate on it), `webhook-timestamp`

data/README.md

@@ -519,6 +519,7 @@ dois, ambos assumem `Email`.
 | `Email` *(padrão)* | código de uso único (OTP) por e-mail, exigido antes de assinar | `Email` | 0 crédito |
 | `Whatsapp` | código de uso único (OTP) por WhatsApp; exige `whatsapp_phone_number` e plano pago | `Whatsapp` | 0,45 crédito (a notificação por WhatsApp) |
 | `DigitalCertificate` | o signatário assina com o **próprio certificado ICP-Brasil (A1/A3)**, gerando uma assinatura **PAdES qualificada** | `Email` **ou** `Whatsapp` | 0,5 crédito + a notificação (0 ou 0,45) |
+| `IdDocumentFaceMatchBasic` | documento de identidade, foto segurando o documento e prova de vida; exige o recurso na conta e CPF válido em `government_id` | `Email` **ou** `Whatsapp` | tarifa por signatário + notificação; consulte a estimativa |
 
 - Informe **exatamente um** canal em `notification_methods` (um array de um elemento).
 - O custo do certificado digital aparece na estimativa com o código `SignatureDigitalCertificate`.
@@ -717,6 +718,55 @@ signatario_client.assignments.decline(
 signatario_client.signer_documents.decline_multiple([doc['id']], decline_reason: 'Não', signer_access_code: codigo)
 ```
 
+### Signatários com verificação biométrica
+
+Na criação do assignment (virtual ou collect), ou em `create_from_template`, envie
+`verification_method: 'IdDocumentFaceMatchBasic'` e exatamente um canal de notificação.
+Cadastre o CPF válido do signatário em `government_id` antes de criar o assignment. Use
+`estimate_cost` ou `estimate_cost_from_template` para obter o custo antes de enviar.
+
+O fluxo de OTP acima se aplica a `Email` e `Whatsapp`. Para biometria, consulte o estado com o
+código de acesso do signatário e abra uma sessão somente após obter o consentimento explícito:
+
+```ruby
+estado = signatario_client.signers.identity_verification(signer_access_code: codigo)
+# => { 'can_start' => true, 'status' => nil, 'url' => nil, 'expires_at' => nil, 'completed_at' => nil }
+
+# Após o consentimento explícito do signatário para o processamento biométrico:
+sessao = signatario_client.signers.start_identity_verification(consent: true, signer_access_code: codigo)
+# => { 'id' => 'verification-id', 'url' => 'https://verify.assinafy.com.br/c/session#t=token-placeholder',
+#      'expires_at' => '2026-10-16T13:00:00Z' }
+```
+
+Abra `sessao['url']` sem alterar a URL nem o fragmento `#t=`; ela concede acesso à captura e não
+deve aparecer em logs ou armazenamento do navegador. Se já houver uma sessão `Pending`, use a
+URL retornada por `identity_verification`. `can_start` só é verdadeiro antes da primeira sessão
+ou após `Expired`; reiniciar uma sessão expirada não cobra novamente. `Declined` e `Abandoned`
+exigem um novo documento e assignment.
+
+Em `InReview`, o signatário continua visualizando, confirmando dados e assinando, mas a certificação
+aguarda a revisão da conta. Depois de todas as assinaturas, o documento pode ficar em
+`pending_identity_review`. Com as credenciais do workspace, o revisor consulta e decide:
+
+```ruby
+revisao = client.assignments.identity_review(doc['id'], assignment['id'], signatario['id'])
+# => SignerIdentityReview: status, reason_codes, evidence_available, expected, document,
+#    matches, checks, images, ruleset_version, evidence_sha256 e dados da decisão
+imagem = client.assignments.identity_review_image(doc['id'], assignment['id'], signatario['id'], 'face')
+# => bytes JPEG, PNG ou PDF, conforme o nome retornado em revisao['images']; não armazenar em cache
+
+# Após o revisor conferir as evidências:
+client.assignments.decide_identity_review(
+  doc['id'], assignment['id'], signatario['id'], decision: 'Approved', note: 'Identidade conferida'
+)
+```
+
+`decision: 'Rejected'` cancela o documento e notifica signatários e destinatários de cópia.
+A nota opcional aceita até 2000 caracteres, fica na atividade e vai ao provedor; não é mostrada
+ao signatário. As imagens só ficam disponíveis durante `InReview`. Acompanhe também os eventos
+`signer_identity_review_required`, `signer_identity_review_approved`, `signer_identity_review_rejected`,
+`signer_identity_verified` e `signer_identity_verification_failed`.
+
 ### Signatários com certificado A1/A3
 
 O signatário por certificado digital conclui a assinatura no fluxo hospedado da Assinafy, aberto
@@ -749,9 +799,11 @@ endpoint = client.webhooks.create_endpoint(
 endpoint['id'] # => "webhook-endpoint-id"
 
 client.webhooks.list_endpoints                              # do mais antigo ao mais novo
+client.webhooks.list_endpoints(url: 'https://app.example.com/webhooks/assinafy') # URL exata
 client.webhooks.get_endpoint('webhook-endpoint-id')
 client.webhooks.update_endpoint('webhook-endpoint-id', is_active: false)   # só os campos enviados
 client.webhooks.delete_endpoint('webhook-endpoint-id')                     # => nil, libera a vaga
+client.webhooks.delete_endpoint_by_url('https://app.example.com/webhooks/assinafy') # => nil
 ```
 
 - `create_endpoint` exige `url`, `email` e `events`; `name`, `is_active` (padrão `true`) e
@@ -763,6 +815,10 @@ client.webhooks.delete_endpoint('webhook-endpoint-id')                     # =>
 
 ### Segredo de assinatura
 
+Com `signing_enabled: true`, `create_endpoint` devolve o segredo uma única vez em
+`endpoint['secret']`. Guarde esse valor na criação, inclusive em aplicativos OAuth. Se o segredo
+de um aplicativo OAuth for perdido, exclua e recrie o endpoint.
+
 ```ruby
 segredo = client.webhooks.endpoint_secret('webhook-endpoint-id')
 segredo['secret'] # => "whsec_..."

data/docs/API_REFERENCE.md

@@ -1,7 +1,7 @@
 # Assinafy Ruby SDK API Reference
 
-> Contract source: Assinafy API v1 OpenAPI 3.1.0, retrieved 2026-10-12 from
-> `https://api.assinafy.com.br/v1/docs/openapi.json` (81 paths, 106 operations, 44 schemas).
+> Contract source: Assinafy API v1 OpenAPI 3.1.0, retrieved 2026-10-16 from
+> `https://api.assinafy.com.br/v1/docs/openapi.json` (85 paths, 112 operations, 45 schemas).
 > `scripts/check_api_contract.rb` validates contract compatibility weekly.
 
 This is the SDK-facing contract reference. Paths below are wire paths; Ruby methods return the unwrapped
@@ -82,8 +82,9 @@ Required parameters and object properties are marked with `*`.
 | POST | `/v1/accounts/{accountId}/templates/{templateId}/documents/estimate-cost` | `DocumentResource#estimate_cost_from_template` | Bearer token or `X-Api-Key` | path `accountId*`: string<br>path `templateId*`: string | required; `application/json` object { `signers*`: Array<object { `role_id*`: string; `verification_method`: string; `notification_methods`: Array<string> }> } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`CostEstimate`](#costestimate) } |
 | GET | `/v1/accounts/{accountId}/theme` | `AccountResource#theme` | Bearer token or `X-Api-Key` | path `accountId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`AccountTheme`](#accounttheme) } |
 | GET | `/v1/accounts/{accountId}/webhooks` | `WebhookResource#list_dispatches` | Bearer token or `X-Api-Key` | path `accountId*`: string<br>query `endpoint_id`: string<br>query `event`: string<br>query `delivered`: string<br>query `from`: integer<br>query `to`: integer<br>query `page`: integer<br>query `per-page`: integer | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`WebhookDispatch`](#webhookdispatch)> } |
-| GET | `/v1/accounts/{accountId}/webhooks/endpoints` | `WebhookResource#list_endpoints` | Bearer token or `X-Api-Key`; OAuth `account:read` | path `accountId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`WebhookEndpoint`](#webhookendpoint)> } |
-| POST | `/v1/accounts/{accountId}/webhooks/endpoints` | `WebhookResource#create_endpoint` | Bearer token or `X-Api-Key`; OAuth `webhooks:write` | path `accountId*`: string | required; `application/json` object { `url*`: string (uri); `email*`: string (email); `events*`: Array<string>; `name`: string; `is_active`: boolean; `signing_enabled`: boolean }; unknown keys raise `ValidationError` locally | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`WebhookEndpoint`](#webhookendpoint) }; `400` duplicate URL, `403` past the plan limit (1 endpoint, 3 on paid plans) |
+| GET | `/v1/accounts/{accountId}/webhooks/endpoints` | `WebhookResource#list_endpoints` | Bearer token or `X-Api-Key`; OAuth `account:read` | path `accountId*`: string; query `url`: exact registered URL | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`WebhookEndpoint`](#webhookendpoint)> } |
+| POST | `/v1/accounts/{accountId}/webhooks/endpoints` | `WebhookResource#create_endpoint` | Bearer token or `X-Api-Key`; OAuth `webhooks:write` | path `accountId*`: string | required; `application/json` object { `url*`: string (uri); `email*`: string (email); `events*`: Array<string>; `name`: string; `is_active`: boolean; `signing_enabled`: boolean }; unknown keys raise `ValidationError` locally | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`WebhookEndpoint`](#webhookendpoint) with `secret`: string when signing_enabled is true (returned once) }; `400` duplicate URL, `403` past the plan limit (1 endpoint, 3 on paid plans) |
+| DELETE | `/v1/accounts/{accountId}/webhooks/endpoints` | `WebhookResource#delete_endpoint_by_url` | Bearer token or `X-Api-Key`; OAuth `webhooks:write` | path `accountId*`: string; query `url*`: exact registered URL | None | `200` envelope data `[]`; SDK returns `nil`; `404` when no endpoint matches |
 | GET | `/v1/accounts/{accountId}/webhooks/endpoints/{endpointId}` | `WebhookResource#get_endpoint` | Bearer token or `X-Api-Key`; OAuth `account:read` | path `accountId*`: string<br>path `endpointId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`WebhookEndpoint`](#webhookendpoint) } |
 | PUT | `/v1/accounts/{accountId}/webhooks/endpoints/{endpointId}` | `WebhookResource#update_endpoint` | Bearer token or `X-Api-Key`; OAuth `webhooks:write` | path `accountId*`: string<br>path `endpointId*`: string | required; `application/json` object { `url`: string (uri); `email`: string (email); `events`: Array<string>; `name`: string; `is_active`: boolean; `signing_enabled`: boolean } — partial; at least one field | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`WebhookEndpoint`](#webhookendpoint) } |
 | DELETE | `/v1/accounts/{accountId}/webhooks/endpoints/{endpointId}` | `WebhookResource#delete_endpoint` | Bearer token or `X-Api-Key`; OAuth `webhooks:write` | path `accountId*`: string<br>path `endpointId*`: string | None | `200` `application/json` [`Envelope`](#envelope); SDK returns `nil` |
@@ -111,6 +112,9 @@ Required parameters and object properties are marked with `*`.
 | PUT | `/v1/documents/{documentId}/assignments/{assignmentId}/reject` | `AssignmentResource#decline` | `signer-access-code` query parameter | path `documentId*`: string<br>path `assignmentId*`: string | required; `application/json` object { `decline_reason*`: string } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<any> } |
 | PUT | `/v1/documents/{documentId}/assignments/{assignmentId}/reset-expiration` | `AssignmentResource#reset_expiration` | Bearer token or `X-Api-Key` | path `documentId*`: string<br>path `assignmentId*`: string | required; `application/json` object { `expires_at*`: string (date-time) or `null` to clear } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`Assignment`](#assignment) } |
 | POST | `/v1/documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/estimate-resend-cost` | `AssignmentResource#estimate_resend_cost` | Bearer token or `X-Api-Key` | path `documentId*`: string<br>path `assignmentId*`: string<br>path `signerId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`CostEstimate`](#costestimate) } |
+| GET | `/v1/documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/identity-verification` | `AssignmentResource#identity_review` | Bearer token or `X-Api-Key` | path `documentId*`, `assignmentId*`, `signerId*`: string | None | `200` envelope data [`SignerIdentityReview`](#signeridentityreview); `404` when no verification exists |
+| GET | `/v1/documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/identity-verification/images/{name}` | `AssignmentResource#identity_review_image` | Bearer token or `X-Api-Key` | path `documentId*`, `assignmentId*`, `signerId*`: string; `name*`: enum `document_front`, `document_back`, `document_pdf`, `face` | None | `200` binary `image/jpeg`, `image/png` or `application/pdf`, `Cache-Control: no-store`; `404` unless evidence exists and review is InReview |
+| POST | `/v1/documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/identity-verification/review` | `AssignmentResource#decide_identity_review` | Bearer token or `X-Api-Key` | path `documentId*`, `assignmentId*`, `signerId*`: string | required; `application/json` { `decision*`: enum `Approved`, `Rejected`; `note`: string or null (max 2000 characters) } | `200` envelope data [`SignerIdentityReview`](#signeridentityreview); `400` unless InReview and document is pending_signature or pending_identity_review |
 | PUT | `/v1/documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/resend` | `AssignmentResource#resend_notification` | Bearer token or `X-Api-Key` | path `documentId*`: string<br>path `assignmentId*`: string<br>path `signerId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: object { `is_sent`: boolean; `document_id`: string; `signer_id`: string } } |
 | GET | `/v1/documents/{documentId}/assignments/{assignmentId}/whatsapp-notifications` | `AssignmentResource#whatsapp_notifications` | Bearer token or `X-Api-Key` | path `documentId*`: string<br>path `assignmentId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`WhatsappNotification`](#whatsappnotification)> } |
 | GET | `/v1/documents/{documentId}/download/{artifactName}` | `DocumentResource#download` | Bearer token or `X-Api-Key` | path `documentId*`: string<br>path `artifactName*`: string | None | `200` `application/pdf` string (binary) |
@@ -132,6 +136,8 @@ Required parameters and object properties are marked with `*`.
 | PUT | `/v1/signers/documents/decline-multiple` | `SignerDocumentResource#decline_multiple` | `signer-access-code` query parameter | None | required; `application/json` object { `document_ids*`: Array<string>; `decline_reason*`: string } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<any> } |
 | PUT | `/v1/signers/documents/sign-multiple` | `SignerDocumentResource#sign_multiple` | `signer-access-code` query parameter | None | required; `application/json` object { `document_ids*`: Array<string> } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<any> } |
 | GET | `/v1/signers/self` | `SignerResource#self_data` | `signer-access-code` query parameter | None | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`SignerSelf`](#signerself) } |
+| GET | `/v1/signers/identity-verification` | `SignerResource#identity_verification` | `signer-access-code` query parameter | None | None | `200` envelope data { `can_start`: boolean; `status`: string or null; `url`: string or null (bearer capture URL, preserve fragment); `expires_at`: date-time or null; `completed_at`: date-time or null } |
+| POST | `/v1/signers/identity-verification` | `SignerResource#start_identity_verification` | `signer-access-code` query parameter | None | required; `application/json` { `consent*`: true } | `200` envelope data { `id`: string; `url`: string (bearer capture URL, preserve fragment); `expires_at`: date-time or null }; `400` unless no session exists or the last session Expired |
 | GET | `/v1/signers/{signerId}/document` | `SignerDocumentResource#current` | `signer-access-code` query parameter | path `signerId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`Document`](#document) } |
 | GET | `/v1/signers/{signerId}/documents` | `SignerDocumentResource#list` (signer code); `#list_as_workspace` (Bearer token or `X-Api-Key`) | `signer-access-code` query parameter, or workspace credentials | path `signerId*`: string<br>query `page`: integer<br>query `per-page`: integer | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`Document`](#document)> } |
 | GET | `/v1/signers/{signerId}/documents/search` | `SignerDocumentResource#search` (signer code); `#search_as_workspace` (Bearer token or `X-Api-Key`) | `signer-access-code` query parameter, or workspace credentials | path `signerId*`: string<br>query `search`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`Document`](#document)> } |
@@ -294,7 +300,7 @@ look successful while the connection stays active.
 
 Verification and notification methods are coupled per signer: the omitted side is inferred from the other, and
 when both are omitted both are `Email`. Exactly one notification method is allowed. Allowed pairs: `Email` with
-`Email`, `Whatsapp` with `Whatsapp`, and `DigitalCertificate` with either. `Email` costs 0 credits; `Whatsapp`
+`Email`, `Whatsapp` with `Whatsapp`, and `DigitalCertificate` or `IdDocumentFaceMatchBasic` with either. `Email` costs 0 credits; `Whatsapp`
 costs 0.45 credits (its WhatsApp notification, paid plans only); `DigitalCertificate` costs 0.5 credits per signer
 on top of its notification, shown in cost estimates under the breakdown code `SignatureDigitalCertificate`.
 
@@ -311,10 +317,38 @@ Certificate signers complete the signature in Assinafy's hosted signing flow, re
 `/signers/certificate/complete`), whose authentication and request/response schemas are not part of the OpenAPI
 contract. Once the flow completes, the `pades` artifact returns the qualified signature.
 
+### Biometric identity verification
+
+`IdDocumentFaceMatchBasic` requires its account feature and a valid CPF in the signer's `government_id`.
+It uses government ID photos, a photo holding the ID and liveness, and adds a per-signer fee to the chosen
+Email or Whatsapp notification. Call `estimate_cost` or `estimate_cost_from_template` for the current total.
+Both assignment methods and template generation accept this verification method.
+
+With the signer access code, read `signers.identity_verification`; after the signer explicitly consents to
+biometric processing, call `signers.start_identity_verification(consent: true, signer_access_code: code)`.
+Open the returned capture URL unchanged, including its fragment; it is a bearer link, so keep it out of logs
+and browser storage. The status response backfills pending provider decisions. `can_start` is true only before
+any session or after Expired; Pending, InReview, Approved, Declined and Abandoned cannot restart. A restart
+replaces an Expired session without another charge. Declined or Abandoned requires a new document and assignment.
+
+During InReview the signer may view, confirm data and sign. Certification waits for account approval; once all
+signers sign, the document can be `pending_identity_review`. Read `assignments.identity_review`, download only
+names from its `images` with `identity_review_image`, and submit `decide_identity_review(decision: 'Approved')`
+or `decision: 'Rejected'` while the document is pending_signature or pending_identity_review. Rejection cancels
+the document and notifies signers and copy receivers. Optional `note:` (at most 2000 characters) is recorded in
+activities and sent to the provider; it is never shown to the signer. Images are fetched from the provider,
+available only during InReview, and must not be cached. The review retains summaries, with `evidence_available`
+false when none is retained or fetched. Direct approvals expose evidence through the signer_identity_verified
+activity instead. Observe signer_identity_review_required, signer_identity_review_approved,
+signer_identity_review_rejected, signer_identity_verified and signer_identity_verification_failed events.
+
 ### Webhook endpoints and deliveries
 
 An account can have 1 webhook endpoint, or up to 3 on paid plans; each has a distinct URL, its own events, and its
-own signing setting, and every active endpoint subscribed to an event receives it. `WebhookResource#create_endpoint`
+own signing setting, and every active endpoint subscribed to an event receives it. Creation with
+`signing_enabled: true` returns a `secret` once: store it immediately. OAuth apps cannot read or rotate it later;
+if lost, delete and recreate the endpoint. `#list_endpoints(url: registered_url)` finds an exact URL match and
+`#delete_endpoint_by_url(registered_url)` deletes that endpoint, returning `nil`. `WebhookResource#create_endpoint`
 and `#update_endpoint` accept only `url`, `email`, `events`, `name`, `is_active`, and `signing_enabled`.
 `#register`, `#get`, and `#inactivate` (`/webhooks/subscriptions`, `/webhooks/inactivate`) act on the account's
 oldest endpoint; `#register` accepts only `url`, `email`, `events`, and `is_active`.
@@ -369,7 +403,7 @@ return-value, and usage details.
 | `Assinafy::OAuthError.new`, `.from_response`, `#error`, `#error_description` | Represent an OAuth endpoint failure; subclasses `ApiError`, so existing rescue clauses keep working. | [`errors.rb`](../lib/assinafy/errors.rb) |
 | `Assinafy::OAuth.generate_code_verifier`, `.code_challenge`, `.generate_state`, `.normalize_scope`, `.validate_code_verifier!`, `.authorization_url` | Build the PKCE pair, CSRF state, and authorization URL for the browser half of the OAuth flow. No network request. | [`oauth.rb`](../lib/assinafy/oauth.rb) |
 | `Assinafy::OAuth::AUTHORIZATION_SERVER`, `::AUTHORIZATION_SERVER_METADATA_URL`, `::AUTHORIZATION_ENDPOINT`, `::CODE_CHALLENGE_METHOD`, `::SCOPES` | Published authorization-server endpoints and scopes. | [`oauth.rb`](../lib/assinafy/oauth.rb) |
-| `AssignmentResource::VERIFICATION_METHODS`, `::NOTIFICATION_METHODS` | The signer verification (`Email`, `Whatsapp`, `DigitalCertificate`) and notification (`Email`, `Whatsapp`) enums, validated locally by `build_payload`. | [`assignment_resource.rb`](../lib/assinafy/resources/assignment_resource.rb) |
+| `AssignmentResource::VERIFICATION_METHODS`, `::NOTIFICATION_METHODS` | The signer verification (`Email`, `Whatsapp`, `DigitalCertificate`, `IdDocumentFaceMatchBasic`) and notification (`Email`, `Whatsapp`) enums, validated locally by `build_payload`. | [`assignment_resource.rb`](../lib/assinafy/resources/assignment_resource.rb) |
 | `Assinafy::Utils.handle_assinafy_response`, `.clean_params`, `.query_params`, `.body_params`, `.require_email`, `.require_expiration` | Internal public helpers used by resources for envelope and parameter normalization; applications should prefer resource methods. | [`utils.rb`](../lib/assinafy/utils.rb) |
 | `Assinafy::NullLogger#debug`, `#info`, `#warn`, `#error`, `#fatal`, `#unknown` | Internal no-op logger methods used when no logger is configured. | [`null_logger.rb`](../lib/assinafy/null_logger.rb) |
 | `Assinafy::VERSION` | Published SDK version constant. | [`version.rb`](../lib/assinafy/version.rb) |
@@ -466,6 +500,8 @@ A signer within an assignment: the base Signer plus per-assignment verification/
 | `notified` | boolean | No | Yes | — |
 | `completed` | boolean | No | Yes | Only present in account-owner contexts. |
 | `notification_history` | Array<[`NotificationHistoryEntry`](#notificationhistoryentry)> | No | Yes | Per-channel delivery history for this signer (email + WhatsApp), most-recent send order. |
+| `government_id` | string | No | Yes | Signer's normalized CPF (11 digits) or CNPJ (14 characters; may be alphanumeric). |
+| `identity_verification_status` | string | No | Yes | Latest identity-document verification status; `InReview` means the account must decide it before the document can be certificated. enum: `["Pending", "InReview", "Approved", "Declined", "Expired", "Abandoned"]` |
 
 ### AssignmentSummary
 
@@ -795,6 +831,47 @@ A signing party belonging to a workspace account.
 | `email` | string (email) | No | Yes | — |
 | `whatsapp_phone_number` | string | No | Yes | E.164 format; normalized on save. |
 | `has_accepted_terms` | boolean | No | No | — |
+| `government_id` | string | No | Yes | Signer's normalized CPF (11 digits) or CNPJ (14 characters; may be alphanumeric). |
+
+### SignerIdentityReview
+
+Account review of a biometric identity verification. Images are available only during InReview.
+
+| Property | Type | Required | Nullable | Constraints / description |
+| --- | --- | --- | --- | --- |
+| `id` | string | No | No | — |
+| `status` | string | No | No | — enum: `["Pending", "InReview", "Approved", "Declined", "Expired", "Abandoned"]` |
+| `provider` | string | No | No | — enum: `["AssinafyVerify"]` |
+| `verification_method` | string | No | No | — enum: `["IdDocumentFaceMatchBasic"]` |
+| `reason_codes` | Array<object> | No | No | Why the provider sent it to review, in its order. Unknown codes have the code as description. |
+| `reason_codes[].code` | string | No | No | — |
+| `reason_codes[].description` | string | No | No | — |
+| `evidence_available` | boolean | No | No | — |
+| `expected` | object | No | Yes | What the signer was registered with. |
+| `expected.name` | string | No | Yes | — |
+| `expected.cpf` | string | No | Yes | — |
+| `document` | object | No | Yes | What was read from the document. |
+| `document.type` | string | No | Yes | — |
+| `document.name` | string | No | Yes | — |
+| `document.cpf` | string | No | Yes | — |
+| `matches` | object | No | Yes | — |
+| `matches.cpf` | boolean | No | Yes | — |
+| `matches.name` | number | No | Yes | Name similarity, 0-1. |
+| `matches.birth_date` | boolean | No | Yes | — |
+| `checks` | Array<object> | No | No | — |
+| `checks[].name` | string | No | No | — |
+| `checks[].result` | string | No | No | pass, review, skipped, or a failure result. |
+| `checks[].score` | number | No | Yes | — |
+| `checks[].reasons` | Array<string> | No | No | — |
+| `images` | Array<string> | No | No | The evidence images the reviewer can open with **Signer identity review image**, in display order: `document_front`, `document_back`, `document_pdf`, `face`. Only while `status` is `InReview`; empty once decided. |
+| `ruleset_version` | string | No | Yes | — |
+| `evidence_sha256` | string | No | Yes | — |
+| `reviewed_by` | object | No | Yes | — |
+| `reviewed_by.id` | string | No | No | — |
+| `reviewed_by.name` | string | No | No | — |
+| `reviewed_at` | string (date-time) | No | Yes | — |
+| `review_note` | string | No | Yes | — |
+| `completed_at` | string (date-time) | No | Yes | — |
 
 ### SignerSelf
 
@@ -811,6 +888,8 @@ The current signer, as returned by `GET /v1/signers/self`. Extends Signer with t
 | `has_signature` | boolean | No | No | Whether the signer has a saved signature image stored. |
 | `has_initial` | boolean | No | No | Whether the signer has a saved initials image stored. |
 | `is_signature_reusable` | boolean | No | No | Whether the signer opted to reuse their saved signature/initials in future processes. When false, clients should not pre-render the saved image even if `has_signature`/`has_initial` is true. |
+| `government_id` | string | No | Yes | Signer's normalized CPF (11 digits) or CNPJ (14 characters; may be alphanumeric). |
+| `verification_method` | string | No | No | How this signature request verifies the signer. `Email`/`Whatsapp` ask for the 6-digit code; `IdDocumentFaceMatchBasic` runs the identity document check instead (see **Identity document verification status**). enum: `["Email", "Whatsapp", "DigitalCertificate", "IdDocumentFaceMatchBasic"]` |
 
 ### SigningUrl
 

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
@@ -244,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')
@@ -488,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]
@@ -626,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/signer_resource.rb

@@ -149,7 +149,7 @@ module Assinafy
       # @option payload [String] :email
       # @option payload [String] :whatsapp_phone_number E.164; normalized on save
       # @option payload [String] :phone alias for `:whatsapp_phone_number`
-      # @option payload [String] :government_id CPF/CNPJ; digits only on save
+      # @option payload [String] :government_id CPF (digits) or CNPJ (may be alphanumeric); normalized on save
       # @param account_id_override [String, nil]
       # @return [Hash] updated signer object (envelope `data` unwrapped)
       # @raise [Assinafy::ApiError] on an unsuccessful API response
@@ -273,6 +273,60 @@ module Assinafy
         end
       end
 
+      # Read the signer's biometric verification state. Only an absent or Expired
+      # session can start again. InReview permits signing while account review
+      # holds certification; Declined or Abandoned needs a new document and assignment.
+      #
+      # @param signer_access_code [String]
+      # @return [Hash] can_start, status, url, expires_at and completed_at (nullable except can_start)
+      # @raise [Assinafy::ApiError] on an unsuccessful API response
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on a missing or invalid access code
+      # @see GET /signers/identity-verification
+      # @example Read state with signer-only authentication
+      #   client.signers.identity_verification(signer_access_code: 'signer-access-code')
+      #   # GET /signers/identity-verification?signer-access-code=signer-access-code (no body)
+      #   # => { 'can_start' => false, 'status' => 'Pending',
+      #   #      'url' => 'https://verify.assinafy.com.br/c/session-id#t=token-placeholder',
+      #   #      'expires_at' => '2026-10-16T13:00:00Z', 'completed_at' => nil }
+      #   # The URL is a bearer link: open it intact, including its fragment; never log or cache it.
+      def identity_verification(signer_access_code:)
+        code = require_signer_access_code(signer_access_code)
+
+        call('Failed to fetch signer identity verification') do
+          http_get('signers/identity-verification', { signer_access_code: code }, workspace_auth: false)
+        end
+      end
+
+      # Record explicit biometric-processing consent and open the hosted verification
+      # session. Restart is allowed only after Expired; it incurs no additional fee.
+      #
+      # @param consent [Boolean] must be true, supplied explicitly by the signer
+      # @param signer_access_code [String]
+      # @return [Hash] id, hosted capture url and nullable expires_at
+      # @raise [Assinafy::ApiError] on failure; 400 when a session already exists and is not Expired
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on missing consent or an invalid access code
+      # @see POST /signers/identity-verification
+      # @example Start with signer-only authentication after collecting consent
+      #   client.signers.start_identity_verification(consent: true, signer_access_code: 'signer-access-code')
+      #   # POST /signers/identity-verification?signer-access-code=signer-access-code
+      #   # Body: { 'consent' => true }
+      #   # => { 'id' => 'verification-id',
+      #   #      'url' => 'https://verify.assinafy.com.br/c/session-id#t=token-placeholder',
+      #   #      'expires_at' => '2026-10-16T13:00:00Z' }
+      #   # Redirect to url unchanged, including its fragment; never log or cache the bearer link.
+      def start_identity_verification(consent:, signer_access_code:)
+        raise ValidationError.new('Biometric processing requires explicit consent: true') unless consent == true
+
+        code = require_signer_access_code(signer_access_code)
+
+        call('Failed to start signer identity verification') do
+          http_post('signers/identity-verification', body_params(consent: consent),
+                    { signer_access_code: code }, workspace_auth: false)
+        end
+      end
+
       # Accept the platform's terms of use as the signer.
       #
       # The `signer-access-code` is sent as the documented query parameter (the

data/lib/assinafy/resources/webhook_resource.rb

@@ -49,11 +49,11 @@ module Assinafy
       #   # }
       #   # => unwrapped data payload returned:
       #   # {
-      #   #   events:     ["document_ready", "document_prepared"],
-      #   #   is_active:  true,
-      #   #   url:        "https://example.com/webhook",
-      #   #   email:      "ops@example.com",
-      #   #   updated_at: "2026-06-05T21:13:24Z"
+      #   #   'events' => ["document_ready", "document_prepared"],
+      #   #   'is_active' => true,
+      #   #   'url' => "https://example.com/webhook",
+      #   #   'email' => "ops@example.com",
+      #   #   'updated_at' => "2026-06-05T21:13:24Z"
       #   # }
       def register(payload, account_id_override = nil)
         body   = { is_active: true }.merge(webhook_body(payload, SUBSCRIPTION_FIELDS, REQUIRED_FIELDS))
@@ -82,11 +82,11 @@ module Assinafy
       #   # GET /accounts/{account_id}/webhooks/subscriptions
       #   # => unwrapped data payload returned (nil if no subscription exists):
       #   # {
-      #   #   events:     ["document_ready", "signer_signed_document"],
-      #   #   is_active:  false,
-      #   #   url:        "https://example.com/sdk-smoke-webhook",
-      #   #   email:      "webhook@example.com",
-      #   #   updated_at: "2026-06-05T21:13:24Z"
+      #   #   'events' => ["document_ready", "signer_signed_document"],
+      #   #   'is_active' => false,
+      #   #   'url' => "https://example.com/sdk-smoke-webhook",
+      #   #   'email' => "webhook@example.com",
+      #   #   'updated_at' => "2026-06-05T21:13:24Z"
       #   # }
       def get(account_id_override = nil)
         acc_id = account_id(account_id_override)
@@ -111,11 +111,11 @@ module Assinafy
       #   # PUT /accounts/{account_id}/webhooks/inactivate  (no request body)
       #   # => unwrapped data payload returned:
       #   # {
-      #   #   events:     ["document_ready", "document_prepared"],
-      #   #   is_active:  false,
-      #   #   url:        "https://example.com/webhook",
-      #   #   email:      "ops@example.com",
-      #   #   updated_at: "2026-06-05T21:13:24Z"
+      #   #   'events' => ["document_ready", "document_prepared"],
+      #   #   'is_active' => false,
+      #   #   'url' => "https://example.com/webhook",
+      #   #   'email' => "ops@example.com",
+      #   #   'updated_at' => "2026-06-05T21:13:24Z"
       #   # }
       def inactivate(account_id_override = nil)
         acc_id = account_id(account_id_override)
@@ -129,7 +129,7 @@ module Assinafy
 
       # Catalogue of supported event-type identifiers.
       #
-      # @return [Array<Hash>] each entry is { id:, description: } (18 event types available)
+      # @return [Array<Hash>] each entry is { id:, description: }
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
       # @raise [Assinafy::ValidationError] on invalid required input
@@ -137,17 +137,17 @@ module Assinafy
       # @example List subscribable event types
       #   client.webhooks.list_event_types
       #   # GET /webhooks/event-types
-      #   # => unwrapped data payload returned (18 entries):
+      #   # => unwrapped data payload returned:
       #   # [
-      #   #   { id: "document_uploaded",        description: "Triggered when the User has uploaded a Document" },
-      #   #   { id: "document_metadata_ready",  description: "Triggered when the document is ready to be prepared..." },
-      #   #   { id: "document_prepared",        description: "Triggered when the User prepares a Document." },
-      #   #   { id: "assignment_created",       description: "Triggered when the User created an assignment..." },
-      #   #   { id: "signature_requested",      description: "Triggered when the User requested signature..." },
-      #   #   { id: "document_ready",           description: "Triggered when the last Signer signs the Document..." },
-      #   #   { id: "signer_created",           description: "Triggered when the User created a Signer" },
-      #   #   { id: "signer_email_verified",    description: "Triggered when Signer's email has been verified..." }
-      #   #   # ... (see docs for the full 18-event catalogue)
+      #   #   { 'id' => "document_uploaded", 'description' => "Document uploaded" },
+      #   #   { 'id' => "document_metadata_ready", 'description' => "Document metadata ready" },
+      #   #   { 'id' => "document_prepared", 'description' => "Document prepared" },
+      #   #   { 'id' => "assignment_created", 'description' => "Assignment created" },
+      #   #   { 'id' => "signature_requested", 'description' => "Signature requested" },
+      #   #   { 'id' => "document_ready", 'description' => "All signers signed" },
+      #   #   { 'id' => "signer_created", 'description' => "Signer created" },
+      #   #   { 'id' => "signer_email_verified", 'description' => "Signer email verified" }
+      #   #   # ... (read list_event_types for the complete current catalogue)
       #   # ]
       def list_event_types
         call_array('Failed to list webhook event types') do
@@ -172,17 +172,17 @@ module Assinafy
       #   # {
       #   #   data: [
       #   #     {
-      #   #       id:            "dispatch-id",
+      #   #       'id' => "dispatch-id",
       #   #       event:         "signature_requested",
       #   #       activity_id:   15431,
       #   #       endpoint:      "https://example.com/webhook",
-      #   #       payload:       { id: 15431, event: "signature_requested", object: {}, subject: {}, payload: {} },
+      #   #       payload:       { 'id' => 15431, event: "signature_requested", object: {}, subject: {}, payload: {} },
       #   #       delivered:     false,
       #   #       http_status:   404,
       #   #       response_body: "{\"success\":false,...}",
       #   #       error:         "Client error: `POST https://example.com/webhook` resulted in a 404 ...",
-      #   #       created_at:    "2026-07-20T15:57:38Z",
-      #   #       updated_at:    "2026-07-20T15:57:38Z"
+      #   #       'created_at' => "2026-07-20T15:57:38Z",
+      #   #       'updated_at' => "2026-07-20T15:57:38Z"
       #   #     }
       #   #     # ... (see docs for full dispatch shape)
       #   #   ],
@@ -211,17 +211,17 @@ module Assinafy
       #   # => unwrapped data payload returned:
       #   # {
       #   #   resource:      "activity_dispatching_history",
-      #   #   id:            "dispatch-id",
+      #   #   'id' => "dispatch-id",
       #   #   event:         "signature_requested",
       #   #   activity_id:   15431,
       #   #   endpoint:      "https://example.com/webhook",
-      #   #   payload:       { id: 15431, event: "signature_requested", object: {}, subject: {} },
+      #   #   payload:       { 'id' => 15431, event: "signature_requested", object: {}, subject: {} },
       #   #   delivered:     true,
       #   #   http_status:   200,
       #   #   response_body: "OK",
       #   #   error:         nil,
-      #   #   created_at:    "2026-07-20T15:57:38Z",
-      #   #   updated_at:    "2026-07-20T15:57:39Z"
+      #   #   'created_at' => "2026-07-20T15:57:38Z",
+      #   #   'updated_at' => "2026-07-20T15:57:39Z"
       #   # }
       def retry_dispatch(dispatch_id, account_id_override = nil)
         acc_id = account_id(account_id_override)
@@ -235,6 +235,7 @@ module Assinafy
       # List the account's webhook endpoints, oldest first.
       #
       # @param account_id_override [String, nil]
+      # @param url [String, nil] filter by the exact registered URL
       # @return [Array<Hash>] webhook endpoint objects
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
@@ -246,29 +247,31 @@ module Assinafy
       #   # => unwrapped data payload returned:
       #   # [
       #   #   {
-      #   #     id:              "webhook-endpoint-id",
-      #   #     name:            "ERP",
-      #   #     url:             "https://example.com/webhooks/assinafy",
-      #   #     email:           "ops@example.com",
-      #   #     events:          ["document_ready", "signer_signed_document"],
-      #   #     is_active:       true,
-      #   #     signing_enabled: true,
-      #   #     created_at:      "2026-10-01T12:00:00Z",
-      #   #     updated_at:      "2026-10-01T12:00:00Z"
+      #   #     'id' => "webhook-endpoint-id",
+      #   #     'name' => "ERP",
+      #   #     'url' => "https://example.com/webhooks/assinafy",
+      #   #     'email' => "ops@example.com",
+      #   #     'events' => ["document_ready", "signer_signed_document"],
+      #   #     'is_active' => true,
+      #   #     'signing_enabled' => true,
+      #   #     'created_at' => "2026-10-01T12:00:00Z",
+      #   #     'updated_at' => "2026-10-01T12:00:00Z"
       #   #   }
       #   # ]
-      def list_endpoints(account_id_override = nil)
+      def list_endpoints(account_id_override = nil, url: nil)
         acc_id = account_id(account_id_override)
+        require_string(url, 'Webhook URL') unless url.nil?
 
         call_array('Failed to list webhook endpoints') do
-          http_get("accounts/#{acc_id}/webhooks/endpoints")
+          http_get("accounts/#{acc_id}/webhooks/endpoints", { url: url })
         end
       end
 
       # Register a new webhook endpoint. Each endpoint of an account needs a
       # distinct `url`. Creating one past the plan's limit (1, or 3 on paid
       # plans) answers `403`. With `signing_enabled: true` a signing secret is
-      # generated; read it with {#endpoint_secret}.
+      # generated and returned once under `secret`. Store it from this response,
+      # especially for OAuth apps, which cannot call {#endpoint_secret}.
       #
       # @param payload [Hash]
       # @option payload [String]        :url             http(s) URL that receives the events (required)
@@ -301,9 +304,10 @@ module Assinafy
       #   #   "signing_enabled": true
       #   # }
       #   # => unwrapped data payload returned (same shape as {#list_endpoints} entries):
-      #   # { id: "webhook-endpoint-id", name: "ERP", url: "https://example.com/webhooks/assinafy",
-      #   #   email: "ops@example.com", events: [...], is_active: true, signing_enabled: true,
-      #   #   created_at: "2026-10-01T12:00:00Z", updated_at: "2026-10-01T12:00:00Z" }
+      #   # { 'id' => "webhook-endpoint-id", 'name' => "ERP", 'url' => "https://example.com/webhooks/assinafy",
+      #   #   'email' => "ops@example.com", 'events' => [...], 'is_active' => true, 'signing_enabled' => true,
+      #   #   'created_at' => "2026-10-01T12:00:00Z", 'updated_at' => "2026-10-01T12:00:00Z",
+      #   #   'secret' => 'whsec_secret-placeholder' } # secret appears only on creation with signing enabled
       def create_endpoint(payload, account_id_override = nil)
         body   = webhook_body(payload, ENDPOINT_FIELDS, REQUIRED_FIELDS)
         acc_id = account_id(account_id_override)
@@ -327,7 +331,7 @@ module Assinafy
       # @example Fetch an endpoint
       #   client.webhooks.get_endpoint('webhook-endpoint-id')
       #   # GET /accounts/{account_id}/webhooks/endpoints/webhook-endpoint-id
-      #   # => { id: "webhook-endpoint-id", name: "ERP", url: "https://example.com/webhooks/assinafy", ... }
+      #   # => { 'id' => "webhook-endpoint-id", 'name' => "ERP", 'url' => "https://example.com/webhooks/assinafy", ... }
       def get_endpoint(endpoint_id, account_id_override = nil)
         call('Failed to fetch webhook endpoint') do
           http_get(endpoint_path(endpoint_id, account_id_override))
@@ -351,7 +355,7 @@ module Assinafy
       #   # PUT /accounts/{account_id}/webhooks/endpoints/webhook-endpoint-id
       #   # request body sent by the SDK:
       #   # { "is_active": false }
-      #   # => { id: "webhook-endpoint-id", is_active: false, ... }
+      #   # => { 'id' => "webhook-endpoint-id", 'is_active' => false, ... }
       def update_endpoint(endpoint_id, payload, account_id_override = nil)
         body = webhook_body(payload, ENDPOINT_FIELDS, [])
         raise ValidationError.new('Webhook endpoint update must change at least one field') if body.empty?
@@ -386,13 +390,37 @@ module Assinafy
         end
       end
 
+      # Delete the endpoint registered with an exact URL and free its slot.
+      # Requires webhooks:write for OAuth applications.
+      #
+      # @param url [String] exact URL used when registering the endpoint
+      # @param account_id_override [String, nil]
+      # @return [nil] the SDK discards the empty data array on success
+      # @raise [Assinafy::ApiError] on failure; 404 when the workspace has no matching endpoint
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid URL or account ID
+      # @see DELETE /accounts/{account_id}/webhooks/endpoints
+      # @example Remove an integration by its registered URL
+      #   client.webhooks.delete_endpoint_by_url('https://app.example.com/webhooks/assinafy')
+      #   # DELETE /accounts/{account_id}/webhooks/endpoints?url=https%3A%2F%2Fapp.example.com%2Fwebhooks%2Fassinafy
+      #   # No request body. Response envelope data: []
+      #   # => nil
+      def delete_endpoint_by_url(url, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        target = require_string(url, 'Webhook URL')
+
+        call_void('Failed to delete webhook endpoint by URL') do
+          http_delete("accounts/#{acc_id}/webhooks/endpoints", { url: target })
+        end
+      end
+
       # Read the Standard Webhooks secret that signs deliveries to an endpoint.
       # Pass it to {Assinafy::Support::WebhookVerifier}. Not available to OAuth
       # applications; use an API key or a user access token.
       #
       # @param endpoint_id [String]
       # @param account_id_override [String, nil]
-      # @return [Hash] `{ secret: "whsec_..." }`
+      # @return [Hash] `{ "secret" => "whsec_..." }`
       # @raise [Assinafy::ApiError] `400` when signing is disabled; `404` on an unknown ID
       # @raise [Assinafy::NetworkError] on transport or TLS failure
       # @raise [Assinafy::ValidationError] on invalid required input
@@ -400,7 +428,7 @@ module Assinafy
       # @example Read the signing secret
       #   client.webhooks.endpoint_secret('webhook-endpoint-id')
       #   # GET /accounts/{account_id}/webhooks/endpoints/webhook-endpoint-id/secret
-      #   # => { secret: "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" }
+      #   # => { 'secret' => "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" }
       def endpoint_secret(endpoint_id, account_id_override = nil)
         call('Failed to fetch webhook endpoint secret') do
           http_get("#{endpoint_path(endpoint_id, account_id_override)}/secret")
@@ -413,7 +441,7 @@ module Assinafy
       #
       # @param endpoint_id [String]
       # @param account_id_override [String, nil]
-      # @return [Hash] `{ secret: "whsec_..." }` (the new secret)
+      # @return [Hash] `{ "secret" => "whsec_..." }` (the new secret)
       # @raise [Assinafy::ApiError] `400` when signing is disabled; `404` on an unknown ID
       # @raise [Assinafy::NetworkError] on transport or TLS failure
       # @raise [Assinafy::ValidationError] on invalid required input
@@ -421,7 +449,7 @@ module Assinafy
       # @example Rotate the signing secret
       #   client.webhooks.rotate_endpoint_secret('webhook-endpoint-id')
       #   # POST /accounts/{account_id}/webhooks/endpoints/webhook-endpoint-id/secret/rotate  (no request body)
-      #   # => { secret: "whsec_new-secret-placeholder" }
+      #   # => { 'secret' => "whsec_new-secret-placeholder" }
       def rotate_endpoint_secret(endpoint_id, account_id_override = nil)
         path = endpoint_path(endpoint_id, account_id_override)
 

data/lib/assinafy/support/webhook_verifier.rb

@@ -20,7 +20,7 @@ module Assinafy
     # with a hex HMAC-SHA256.
     #
     # @example Verify a signed delivery (Rack / Rails)
-    #   secret   = client.webhooks.endpoint_secret('webhook-endpoint-id')[:secret]
+    #   secret   = client.webhooks.endpoint_secret('webhook-endpoint-id').fetch('secret')
     #   verifier = Assinafy::Support::WebhookVerifier.new(secret)
     #   raw_body = request.body.read
     #   return head(:unauthorized) unless verifier.verify_delivery(raw_body, request.headers)

data/lib/assinafy/version.rb

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

data/sig/assinafy.rbs

@@ -295,6 +295,8 @@ module Assinafy
       def delete: (String signer_id, ?String? account_id_override) -> nil
       def find_by_email: (String email, ?String? account_id_override) -> api_object?
       def self_data: (signer_access_code: String) -> api_object
+      def identity_verification: (signer_access_code: String) -> api_object
+      def start_identity_verification: (consent: bool, signer_access_code: String) -> api_object
       def accept_terms: (signer_access_code: String) -> nil
       def verify_email: (verification_code: String, signer_access_code: String) -> nil
       def confirm_data: (String document_id, params payload, signer_access_code: String) -> api_object
@@ -335,6 +337,7 @@ module Assinafy
       VERIFICATION_METHODS: Array[String]
       NOTIFICATION_METHODS: Array[String]
       SIGN_ITEM_KEY_MAP: Hash[String, String]
+      IDENTITY_REVIEW_IMAGES: Array[String]
 
       def self.build_payload: (params payload, ?params options) -> Hash[String, untyped]
       def list: (?params params, ?String? account_id_override) -> list_result
@@ -343,6 +346,15 @@ module Assinafy
       def reset_expiration: (String document_id, String assignment_id, String? expires_at) -> api_object
       def resend_notification: (String document_id, String assignment_id, String signer_id) -> api_object
       def estimate_resend_cost: (String document_id, String assignment_id, String signer_id) -> api_object
+      def identity_review: (String document_id, String assignment_id, String signer_id) -> api_object
+      def identity_review_image: (String document_id, String assignment_id, String signer_id, String name) -> String
+      def decide_identity_review: (
+        String document_id,
+        String assignment_id,
+        String signer_id,
+        decision: String,
+        ?note: String?
+      ) -> api_object
       def signer_document: (signer_access_code: String, ?has_accepted_terms: bool?) -> api_object
       def sign: (String document_id, String assignment_id, Array[params] items, signer_access_code: String) -> api_object
       def decline: (
@@ -362,11 +374,12 @@ module Assinafy
       def list_event_types: () -> Array[api_object]
       def list_dispatches: (?params params, ?String? account_id_override) -> list_result
       def retry_dispatch: (String dispatch_id, ?String? account_id_override) -> api_object
-      def list_endpoints: (?String? account_id_override) -> Array[api_object]
+      def list_endpoints: (?String? account_id_override, ?url: String?) -> Array[api_object]
       def create_endpoint: (params payload, ?String? account_id_override) -> api_object
       def get_endpoint: (String endpoint_id, ?String? account_id_override) -> api_object
       def update_endpoint: (String endpoint_id, params payload, ?String? account_id_override) -> api_object
       def delete_endpoint: (String endpoint_id, ?String? account_id_override) -> nil
+      def delete_endpoint_by_url: (String url, ?String? account_id_override) -> nil
       def endpoint_secret: (String endpoint_id, ?String? account_id_override) -> api_object
       def rotate_endpoint_secret: (String endpoint_id, ?String? account_id_override) -> api_object
     end

metadata

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