assinafy 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2a0b97db3a9ad302307e31bccf8f06751fe310dd253417bb129ad921b0a4b3f
-  data.tar.gz: 94eb893e22a78777a0b4102d572e274e0f22c5b50cd3768d348f2deac69541ab
+  metadata.gz: 1d6db456898234647465325a55c4580054a8ab93f39aff3d6ca067ffe6be9e49
+  data.tar.gz: 55577984ae91aec1ad66715a9b34a8ae10e991f015d6f4e3fe01f5bebf2b9503
 SHA512:
-  metadata.gz: 43838b1c27e22fc5210a8e877a4e1897f50030a6e32801cf490f101de6d18805ed79bff013120801ce90ab53369531142bf678cbe0e04f543139aa72790bab11
-  data.tar.gz: f0e442b567d84643b2237ec21edf5b59de9155268451986dcdcc19f841ccf1514e1fd11e112fedc0ff1b8c04439feb411fec7ec37bc06128a86409996745798e
+  metadata.gz: 93a92268707f3afa45e7f16c837ab3ded90b7ab8859060ff48a0d7eeb81a244dde3b53ada834852de4f83df7e72f738bbffc1468e8ae7de24dfffba56709edb6
+  data.tar.gz: 384b02e9dd54fb89ea78dc61b6f7a507e8e317431d30996b0dcfd16f4a6d3251a03821d0f6d59d28541b2425a24cbd98062c68b2945f0ef2fb252af8569a7ad4

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## [2.1.0] - 2026-10-28
+
+### Added
+
+- `ContractResource` and `client.contracts` cover listing, reading, updating, relating, renewing and terminating
+  the contract terms tracked on documents, including nullable fields and optimistic `updated_at` preconditions.
+- User notification preferences support `ContractRenewalNotice`, `ContractExpiring`, `ContractExpired` and
+  `ContractRenewed`.
+
+### Changed
+
+- New or changed webhook endpoint URLs must be absolute HTTPS URLs; invalid URLs raise `ValidationError` before a
+  request.
+- Contract, document, assignment, webhook and reminder-cost response fields reflect the current API contract.
+
+## [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:
 
@@ -688,7 +691,7 @@ See [Errors](#errors) for the full hierarchy.
 
 ## Resource reference
 
-`Assinafy::Client` exposes thirteen accessors — twelve API resources plus the local `webhook_verifier` helper:
+`Assinafy::Client` exposes fourteen accessors — thirteen API resources plus the local `webhook_verifier` helper:
 
 | Accessor                    | What it covers                                                     |
 | --------------------------- | ------------------------------------------------------------------ |
@@ -697,6 +700,7 @@ See [Errors](#errors) for the full hierarchy.
 | `client.accounts`           | Account CRUD, theme, KPI stats, brand logo                         |
 | `client.users`              | User profile, notification preferences, cross-account KPIs         |
 | `client.documents`          | Upload, list, search, rename, download, delete, verify, tags       |
+| `client.contracts`          | Contract terms, amendments, renewals, terminations                 |
 | `client.signers`            | Workspace signer CRUD + signer self-service endpoints              |
 | `client.signer_documents`   | Signer-authenticated multi-document operations + search            |
 | `client.assignments`        | List/create/sign/decline/resend/estimate assignments               |
@@ -778,6 +782,27 @@ client.documents.signing_progress('document-id')   # => { signed: 1, total: 2, p
 An Array `tags` filter is sent as comma-separated tag IDs. The tag arrays of `replace_tags`/`append_tags` take tag
 IDs.
 
+### Contracts
+
+```ruby
+contract = client.contracts.update(
+  'document-id',
+  status: 'active', counterparty_name: 'Example Ltda', value: 120_000, currency: 'BRL',
+  start_date: '2026-11-01', end_date: '2027-10-31', auto_renew: true,
+  renewal_term_months: 12, notice_period_days: 30
+)
+
+client.contracts.get('document-id')
+client.contracts.list(status: ['active'], ending_within_days: 30)
+client.contracts.related('document-id')
+client.contracts.renew('document-id', term: contract['term'], updated_at: contract['updated_at'])
+client.contracts.terminate('document-id', reason: 'Ended by the parties')
+```
+
+`update` is partial and preserves explicit `nil` values as JSON `null`. Link an amendment document with
+`parent_document_id` and `relation_type`. Reads require OAuth scope `documents:read`; writes require
+`documents:write` and a plan with contract tracking. `get` and `related` return `nil` when no tracked terms exist.
+
 ### Signers (workspace CRUD)
 
 ```ruby

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.
 
 ---
 
@@ -963,6 +966,38 @@ verificacao['agreement_code']  # código impresso no certificado do documento
 Ela devolve o resultado da Assinafy; não valida independentemente a assinatura do PDF nem a
 cadeia de certificação.
 
+### Acompanhar o contrato
+
+Quando o plano da conta inclui acompanhamento de contratos, registre os termos no documento e
+use o `updated_at` devolvido pela API como precondição para evitar sobrescrever uma alteração
+concorrente:
+
+```ruby
+contrato = client.contracts.update(
+  documento['id'],
+  status: 'active',
+  counterparty_name: 'Empresa Exemplo Ltda',
+  value: 120_000,
+  currency: 'BRL',
+  start_date: '2026-11-01',
+  end_date: '2027-10-31',
+  auto_renew: true,
+  renewal_term_months: 12,
+  notice_period_days: 30
+)
+
+client.contracts.get(documento['id'])
+client.contracts.list(status: ['active'], ending_within_days: 30)
+client.contracts.related(documento['id'])
+client.contracts.renew(documento['id'], term: contrato['term'], updated_at: contrato['updated_at'])
+client.contracts.terminate(documento['id'], reason: 'Encerrado pelas partes')
+```
+
+`update` é parcial e preserva `nil` como JSON `null` para limpar campos. Um documento de aditivo
+pode ser ligado com `parent_document_id` e `relation_type`. As leituras usam o escopo OAuth
+`documents:read`; alterações usam `documents:write` e exigem que o plano tenha acompanhamento de
+contratos. `get` e `related` devolvem `nil` quando o documento não tem termos acompanhados.
+
 ---
 
 ## 12. Organizar e limpar
@@ -1069,6 +1104,7 @@ end
 | `client.accounts` | workspaces, tema, KPIs, logo |
 | `client.users` | perfil próprio, KPIs, preferências de notificação |
 | `client.documents` | upload, listagem, download, ciclo de vida, tags, verificação |
+| `client.contracts` | termos, aditivos, renovações e encerramentos de contratos |
 | `client.signers` | CRUD de signatários e todo o autoatendimento do signatário |
 | `client.signer_documents` | documentos do signatário, assinar/recusar em lote |
 | `client.assignments` | pedidos de assinatura, custos, reenvios, assinatura, recusa |

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-16 from
-> `https://api.assinafy.com.br/v1/docs/openapi.json` (85 paths, 112 operations, 45 schemas).
+> Contract source: Assinafy API v1 OpenAPI 3.1.0, retrieved 2026-10-28 from
+> `https://api.assinafy.com.br/v1/docs/openapi.json` (90 paths, 118 operations, 49 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
@@ -50,6 +50,12 @@ Required parameters and object properties are marked with `*`.
 | GET | `/v1/accounts/{accountId}` | `AccountResource#get` | Bearer token or `X-Api-Key` | path `accountId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`Account`](#account) } |
 | PUT | `/v1/accounts/{accountId}` | `AccountResource#update` | Bearer token or `X-Api-Key` | path `accountId*`: string | required; `application/json` object { `name`: string; `notification_sender_type`: string } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`Account`](#account) } |
 | DELETE | `/v1/accounts/{accountId}` | `AccountResource#delete` | Bearer token or `X-Api-Key` | path `accountId*`: string | optional; `application/json` object { `force`: boolean } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<any> } |
+| GET | `/v1/accounts/{accountId}/contracts` | `ContractResource#list` | Bearer token or `X-Api-Key`; OAuth `documents:read` | path `accountId*`: string<br>query `status`: comma-separated array of `draft`, `active`, `expired`, `terminated`<br>query `counterparty`, `search`, `end_date_from`, `end_date_to`, `ending_within_days`, `external_system`, `external_id`, `sort`, `expand`, `page`, `per-page` | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`DocumentContract`](#documentcontract)> }; pagination headers become `{ data:, meta: }` |
+| GET | `/v1/accounts/{accountId}/documents/{documentId}/contract` | `ContractResource#get` | Bearer token or `X-Api-Key`; OAuth `documents:read` | path `accountId*`: string<br>path `documentId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`DocumentContract`](#documentcontract) or [`DocumentContractAmendment`](#documentcontractamendment) }; SDK returns `nil` on `404` |
+| PUT | `/v1/accounts/{accountId}/documents/{documentId}/contract` | `ContractResource#update` | Bearer token or `X-Api-Key`; OAuth `documents:write` | path `accountId*`: string<br>path `documentId*`: string | required non-empty [`DocumentContractInput`](#documentcontractinput); explicit `nil` is sent as JSON null | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`DocumentContract`](#documentcontract) or [`DocumentContractAmendment`](#documentcontractamendment) }; `403` without contract tracking, `409` on stale `updated_at` |
+| GET | `/v1/accounts/{accountId}/documents/{documentId}/contract/related` | `ContractResource#related` | Bearer token or `X-Api-Key`; OAuth `documents:read` | path `accountId*`: string<br>path `documentId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: root [`DocumentContract`](#documentcontract) with `amendments` }; SDK returns `nil` on `404` |
+| POST | `/v1/accounts/{accountId}/documents/{documentId}/contract/renew` | `ContractResource#renew` | Bearer token or `X-Api-Key`; OAuth `documents:write` | path `accountId*`: string<br>path `documentId*`: string | optional; `application/json` object { `end_date`: string (date, nullable); `value`: number (nullable); `term`: integer; `updated_at`: string (date-time) }; a valid request requires `term` or `end_date` | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`DocumentContract`](#documentcontract) }; `403` without contract tracking, `409` on stale `updated_at` |
+| POST | `/v1/accounts/{accountId}/documents/{documentId}/contract/terminate` | `ContractResource#terminate` | Bearer token or `X-Api-Key`; OAuth `documents:write` | path `accountId*`: string<br>path `documentId*`: string | optional; `application/json` object { `reason`: string (nullable, max 500); `updated_at`: string (date-time) } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`DocumentContract`](#documentcontract) }; `403` without contract tracking, `409` on stale `updated_at` |
 | GET | `/v1/accounts/{accountId}/documents` | `DocumentResource#list` | Bearer token or `X-Api-Key` | path `accountId*`: string<br>query `status`: string<br>query `method`: string<br>query `search`: string<br>query `tags`: string<br>query `sort`: string<br>query `page`: integer<br>query `per-page`: integer | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`Document`](#document)> } |
 | POST | `/v1/accounts/{accountId}/documents` | `DocumentResource#upload` | Bearer token or `X-Api-Key` | path `accountId*`: string | required; `multipart/form-data` object { `file*`: string (binary) } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`Document`](#document) } |
 | GET | `/v1/accounts/{accountId}/documents/search` | `DocumentResource#search` | Bearer token or `X-Api-Key` | path `accountId*`: string<br>query `search`: string<br>query `status`: string<br>query `page`: integer<br>query `per-page`: integer | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`Document`](#document)> } |
@@ -111,7 +117,7 @@ Required parameters and object properties are marked with `*`.
 | POST | `/v1/documents/{documentId}/assignments/{assignmentId}` | `AssignmentResource#sign` | `signer-access-code` query parameter | path `documentId*`: string<br>path `assignmentId*`: string | required; `application/json` Array<object { `itemId*`: string; `fieldId*`: string; `pageId*`: string; `value*`: string }> | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: object } |
 | 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) } |
+| 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`: [`ResendCostEstimate`](#resendcostestimate) } |
 | 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 |
@@ -151,8 +157,8 @@ Required parameters and object properties are marked with `*`.
 | PUT | `/v1/users/self/mfa/totp/confirm` | `AuthResource#confirm_totp_enrollment` | Bearer token or `X-Api-Key` | None | required; `application/json` object { `id*`: string (SDK `method_id:`); `code*`: string; `password`: string (password); `reauth_code`: string } — `password` or `reauth_code` only when replacing a confirmed method | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: object { `recovery_codes`: Array<string> (shown once) } } |
 | POST | `/v1/users/self/mfa/recovery-codes` | `AuthResource#regenerate_recovery_codes` | Bearer token or `X-Api-Key` | None | required; `application/json` object { `password`: string (password); `code`: string } — one of the two is required (checked locally) | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: object { `recovery_codes`: Array<string> } } |
 | DELETE | `/v1/users/self/mfa/{customId}` | `AuthResource#delete_mfa_method` | Bearer token or `X-Api-Key` | path `customId*`: string | required; `application/json` object { `password`: string (password); `code`: string } — one of the two is required (checked locally) | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: object { `is_mfa_enabled`: boolean } } |
-| GET | `/v1/users/self/notification-preferences` | `UserResource#notification_preferences` | Bearer token or `X-Api-Key` | None | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`NotificationPreferences`](#notificationpreferences) } |
-| PUT | `/v1/users/self/notification-preferences` | `UserResource#update_notification_preferences` | Bearer token or `X-Api-Key` | None | required; `application/json` [`NotificationPreferences`](#notificationpreferences) | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`NotificationPreferences`](#notificationpreferences) } |
+| GET | `/v1/users/self/notification-preferences` | `UserResource#notification_preferences` | User bearer token or `X-Api-Key`; unavailable to third-party OAuth apps | None | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`NotificationPreferences`](#notificationpreferences) } |
+| PUT | `/v1/users/self/notification-preferences` | `UserResource#update_notification_preferences` | User bearer token or `X-Api-Key`; unavailable to third-party OAuth apps | None | required; `application/json` [`NotificationPreferences`](#notificationpreferences) | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`NotificationPreferences`](#notificationpreferences) } |
 | GET | `/v1/users/self/stats` | `UserResource#stats` | Bearer token or `X-Api-Key` | query `granularity`: string<br>query `month`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`DocumentStatsRow`](#documentstatsrow)> } |
 | POST | `/v1/verify` | `SignerResource#verify_email` | `signer-access-code` query parameter | None | required; `application/json` object { `verification-code*`: string } | `200` `application/json` [`Envelope`](#envelope) |
 | GET | `/v1/webhooks/event-types` | `WebhookResource#list_event_types` | Bearer token or `X-Api-Key` | None | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`WebhookEventType`](#webhookeventtype)> } |
@@ -249,6 +255,21 @@ locally together with the `.pdf` extension and `%PDF-` header.
 with commas; matching documents carry every listed tag. `DocumentResource#replace_tags` and `#append_tags` accept
 arrays of tag IDs. Use a tag ID with `DocumentResource#detach_tag`.
 
+### Contract tracking
+
+Contract terms belong to an existing document; setting terms never uploads, sends, or signs the document.
+`ContractResource#update` creates or partially changes the terms. Explicit `nil` values remain JSON null so they
+clear nullable fields. To record a signed amendment, renewal, or termination instrument, upload that document and
+set its `parent_document_id`, `relation_type`, and changed terms; the delta applies after the instrument is
+certificated. `#get` reads the terms or an instrument, and `#related` always reads the root family.
+
+The hourly lifecycle moves active contracts through notice, expiry, and automatic renewal. `#renew` starts the
+next term immediately; sending the current `term` makes a lost-response retry safe. `#terminate` closes the
+contract and records its optional reason. Writers can send the `updated_at` they read as an optimistic-lock
+precondition; the API refuses a stale write with `409`. Reads remain available without the contract-tracking
+plan, while writes answer `403` when the plan lacks the feature. OAuth reads require `documents:read`, and writes
+require `documents:write`.
+
 ### KPI statistics
 
 `UserResource#stats` and `AccountResource#stats` validate `granularity` (`monthly` or `daily`) and `month`
@@ -308,9 +329,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`,
@@ -351,7 +378,9 @@ if lost, delete and recreate the endpoint. `#list_endpoints(url: registered_url)
 `#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`.
+oldest endpoint; `#register` accepts only `url`, `email`, `events`, and `is_active`. New or changed endpoint URLs
+must be absolute HTTPS URLs; the SDK rejects other schemes locally, while the API also refuses private, loopback,
+link-local, and other reserved destination addresses.
 
 Each delivery is a JSON `POST` carrying `webhook-id` (stable across attempts of one event to one endpoint; use it to
 deduplicate), `webhook-timestamp` (Unix seconds), and, when signing is enabled, `webhook-signature`. Any `2xx` is
@@ -379,7 +408,7 @@ return-value, and usage details.
 | `Assinafy::Client.from_config`, `.from_hash` | Construct a client from string- or symbol-keyed configuration. | [`client.rb`](../lib/assinafy/client.rb) |
 | `Client#faraday_connection` | Return the configured Faraday connection for advanced integration. | [`client.rb`](../lib/assinafy/client.rb) |
 | `Client#upload_and_request_signatures` | Upload, optionally wait, create signers, and create a virtual assignment. | [`client.rb`](../lib/assinafy/client.rb) |
-| `Client#auth`, `#oauth`, `#accounts`, `#users`, `#documents`, `#signers`, `#signer_documents`, `#assignments`, `#webhooks`, `#templates`, `#fields`, `#tags`, `#webhook_verifier` | Return the client's resource and helper instances. | [`client.rb`](../lib/assinafy/client.rb) |
+| `Client#auth`, `#oauth`, `#accounts`, `#users`, `#documents`, `#contracts`, `#signers`, `#signer_documents`, `#assignments`, `#webhooks`, `#templates`, `#fields`, `#tags`, `#webhook_verifier` | Return the client's resource and helper instances. | [`client.rb`](../lib/assinafy/client.rb) |
 | `Assinafy::Configuration.new`, `.from_hash` | Build configuration directly or from string/symbol keys. | [`configuration.rb`](../lib/assinafy/configuration.rb) |
 | `Configuration#auth_headers` | Return the selected API-key, bearer, or empty authentication header set. | [`configuration.rb`](../lib/assinafy/configuration.rb) |
 | Configuration readers/writers: `api_key`, `token`, `account_id`, `base_url`, `webhook_secret`, `timeout`, `logger` | Read or update configuration values; `base_url=` and `timeout=` validate like the constructor. Construct a new client to apply changes. | [`configuration.rb`](../lib/assinafy/configuration.rb) |
@@ -433,6 +462,8 @@ A workspace account (organization).
 | `notification_sender_type` | string | No | No | enum: `["User", "Account"]` |
 | `roles` | Array<string> | No | No | — |
 | `is_delete_allowed` | boolean | No | No | — |
+| `limits` | object | No | No | Current-plan limits; present only on the single-account response. More keys may be added. |
+| `limits.webhook_endpoints` | integer | No | No | Maximum webhook endpoints: 1, or 3 with the Multiple Webhooks feature. |
 | `created_at` | string (date-time) | No | No | — |
 
 ### AccountTheme
@@ -460,7 +491,9 @@ A request for signers to sign a document.
 | --- | --- | --- | --- | --- |
 | `resource` | string | No | No | — |
 | `id` | string | No | No | — |
-| `sender_email` | string (email) | No | No | — |
+| `document_id` | string | No | Yes | Document this assignment belongs to; null only after the document is deleted. |
+| `created_at` | string (date-time) | No | No | — |
+| `sender_email` | string (email) | No | Yes | Null once the sender has deleted their account. |
 | `method` | string | No | No | enum: `["virtual", "collect"]` |
 | `expires_at` | string (date-time) | No | Yes | — |
 | `message` | string | No | Yes | — |
@@ -602,12 +635,14 @@ A document and its current lifecycle state.
 | `artifacts` | object | No | No | Artifact download URLs keyed by name. Always `original`, plus `thumbnail` once one exists. A certificated document also carries `certificated`, `certificate-page` and `bundle`, and `pades` when it was signed with a digital certificate — the PAdES version holds the signers' ICP-Brasil signatures, which certification flattens out of the certificated PDF. |
 | `is_closed` | boolean | No | No | — |
 | `signing_url` | string | No | No | — |
+| `verification_code` | string | No | Yes | Code printed on the certificate page; null until certificated. |
+| `verification_url` | string (uri) | No | Yes | Public verification page; null until certificated. |
 | `decline_reason` | string | No | Yes | — |
 | `declined_by` | any JSON value | No | Yes | — |
 | `tags` | Array<object> | No | No | — |
 | `tags[].id` | string | No | No | — |
 | `tags[].name` | string | No | No | — |
-| `assignment` | object | No | Yes | Expanded assignment data when included via ?expand=assignment; null otherwise. |
+| `assignment` | object | No | Yes | Included by list/details/signer-list/template-generation responses; search and upload omit it. Only rename follows `?expand=assignment`. |
 | `assignment.resource` | string | No | No | — |
 | `assignment.id` | string | No | No | — |
 | `assignment.sender_email` | string (email) | No | No | — |
@@ -620,6 +655,7 @@ A document and its current lifecycle state.
 | `assignment.summary` | [`AssignmentSummary`](#assignmentsummary) | No | No | — |
 | `assignment.signing_urls` | Array<[`SigningUrl`](#signingurl)> | No | No | — |
 | `pages` | Array<[`DocumentPage`](#documentpage)> | No | No | — |
+| `has_contract` | boolean | No | No | Only on workspace `GET /documents/{documentId}` when contract tracking is available. A missing key means unknown. |
 | `created_at` | string (date-time) | No | No | — |
 | `updated_at` | string (date-time) | No | No | — |
 
@@ -638,6 +674,85 @@ A document activity event.
 | `origin.user-agent` | string | No | No | — |
 | `created_at` | string (date-time) | No | No | — |
 
+### DocumentContract
+
+Contract terms tracked on a document. The single-contract and related-family reads can include amendments; the
+workspace list can include the document when `expand=document` is requested.
+
+| Property | Type | Required | Nullable | Constraints / description |
+| --- | --- | --- | --- | --- |
+| `resource` | string | No | No | `document_contract` in single-resource responses. |
+| `document_id` | string | No | No | Document that owns the terms. |
+| `status` | string | No | No | enum: `["draft", "active", "expired", "terminated"]` |
+| `counterparty_name` | string | No | Yes | — |
+| `counterparty_taxpayer_id` | string | No | Yes | Normalized CPF/CNPJ, digits only. |
+| `value` | number | No | Yes | At most two decimal places. |
+| `currency` | string | No | Yes | ISO 4217 code; defaults to BRL when a value is set. |
+| `start_date` | string (date) | No | Yes | — |
+| `end_date` | string (date) | No | Yes | — |
+| `auto_renew` | boolean | No | No | — |
+| `renewal_term_months` | integer | No | Yes | — |
+| `notice_period_days` | integer | No | Yes | — |
+| `term` | integer | No | No | Renewal term number, starting at 1. |
+| `owner_id` | string | No | Yes | Active workspace member responsible for lifecycle email. |
+| `metadata` | object | No | Yes | Up to 50 caller-defined string values. |
+| `external_references` | Array<object> | No | No | IDs in outside systems, sorted by system and ID. |
+| `external_references[].system` | string | No | No | Outside system name. |
+| `external_references[].id` | string | No | No | ID in that system. |
+| `document` | [`Document`](#document) | No | No | Only on list results with `expand=document`. |
+| `amendments` | Array<[`DocumentContractAmendment`](#documentcontractamendment)> | No | No | Only on single-contract/family reads. |
+| `created_at` | string (date-time) | No | No | — |
+| `updated_at` | string (date-time) | No | No | Moves on every direct or lifecycle change. |
+
+### DocumentContractAmendment
+
+A document linked as an amendment, renewal, or termination instrument. Its terms are a delta applied to the
+parent after this document is certificated.
+
+| Property | Type | Required | Nullable | Constraints / description |
+| --- | --- | --- | --- | --- |
+| `resource` | string | No | No | `document_contract_amendment` in single-resource responses. |
+| `document_id` | string | No | No | The instrument document. |
+| `document_name` | string | No | No | Instrument document name. |
+| `parent_document_id` | string | No | No | Root contract document. |
+| `relation_type` | string | No | No | enum: `["amendment", "renewal", "termination"]` |
+| `number` | integer | No | Yes | Applied position; null while pending. |
+| `status` | string | No | No | enum: `["pending", "applied"]` |
+| `document_status` | string | No | No | Current lifecycle status of the instrument document. |
+| `apply_error` | string | No | Yes | Why a signed instrument has not applied yet. |
+| `currency` | string | No | Yes | Currency used by amount values in `terms` and `changes`. |
+| `terms` | object | No | Yes | Only contract terms changed by this instrument. |
+| `changes` | object | No | Yes | Changed fields as `{ from:, to: }`, previewed while pending and fixed once applied. |
+| `applied_at` | string (date-time) | No | Yes | — |
+| `created_at` | string (date-time) | No | No | — |
+| `updated_at` | string (date-time) | No | No | — |
+
+### DocumentContractInput
+
+Partial body for setting terms or linking an instrument. Only sent fields change. JSON null clears a nullable
+term; for a pending instrument it removes that term from the delta. `external_references` replaces the whole list.
+
+| Property | Type | Required | Nullable | Constraints / description |
+| --- | --- | --- | --- | --- |
+| `status` | string | No | No | enum: `["draft", "active", "expired", "terminated"]`; closed statuses are creation-only. |
+| `counterparty_name` | string | No | Yes | Maximum 255 characters. |
+| `counterparty_taxpayer_id` | string | No | Yes | Valid formatted or unformatted CPF/CNPJ. |
+| `value` | number | No | Yes | 0–9,999,999,999,999.99; at most two decimal places. |
+| `currency` | string | No | Yes | Three-letter code, stored uppercase. |
+| `start_date` | string (date) | No | Yes | `YYYY-MM-DD`, year 1000 or later. |
+| `end_date` | string (date) | No | Yes | On or after `start_date`. |
+| `auto_renew` | boolean | No | Yes | Null resets to false. |
+| `renewal_term_months` | integer | No | Yes | 1–600; defaults to 12 when unset. |
+| `notice_period_days` | integer | No | Yes | 0–3650. |
+| `owner_id` | string | No | Yes | Active member of the workspace. |
+| `metadata` | object | No | Yes | Up to 50 keys of 1–40 letters, digits, `_`, `-`, or `.`, each holding at most 500 characters. |
+| `external_references` | Array<object> | No | Yes | At most 20; null or an empty array clears the list. |
+| `external_references[].system` | string | Yes | No | Up to 64 letters, digits, `_`, `-`, or `.`; stored lowercase. |
+| `external_references[].id` | string | Yes | No | Up to 255 characters. |
+| `parent_document_id` | string | No | Yes | Links to a contract family; null unlinks a pending instrument. |
+| `relation_type` | string | No | No | Required for the first link; enum: `["amendment", "renewal", "termination"]`. |
+| `updated_at` | string (date-time) | No | Yes | Optional optimistic-lock value; a stale value returns `409`. Null is last-write-wins. |
+
 ### DocumentPage
 
 | Property | Type | Required | Nullable | Constraints / description |
@@ -789,6 +904,10 @@ Owner-facing document notifications, keyed by notification type. `true` means th
 | `DocumentProcessingFailed` | boolean | No | No | An uploaded document could not be processed. |
 | `TemplateProcessingFailed` | boolean | No | No | A template could not be processed. |
 | `SignerWhatsappFailed` | boolean | No | No | A WhatsApp notification to a signer could not be delivered. |
+| `ContractRenewalNotice` | boolean | No | No | A tracked contract entered its notice period. |
+| `ContractExpiring` | boolean | No | No | A tracked contract ends in 45 or 30 days. |
+| `ContractExpired` | boolean | No | No | A tracked contract ended without renewal. |
+| `ContractRenewed` | boolean | No | No | A tracked contract was automatically renewed into its next term. |
 
 ### OAuthRevokeRequest
 
@@ -819,6 +938,20 @@ Body of `POST /v1/oauth/token`. Sent form-encoded per RFC 6749, or as JSON.
 | `subject_token_type` | string | No | No | enum: `["urn:ietf:params:oauth:token-type:access_token"]`; Token-exchange grant only. Required; only `urn:ietf:params:oauth:token-type:access_token` is supported. |
 | `requested_token_type` | string | No | No | enum: `["urn:ietf:params:oauth:token-type:access_token"]`; Token-exchange grant only. Optional; when present it must agree with the only type this server issues. |
 
+### ResendCostEstimate
+
+Credits needed to resend one signer's notification. A reminder consumes no document allowance.
+
+| Property | Type | Required | Nullable | Constraints / description |
+| --- | --- | --- | --- | --- |
+| `total` | number | No | No | Sum of the breakdown costs. |
+| `breakdown` | Array<object> | No | No | Per-charge resend costs. |
+| `breakdown[].code` | string | No | No | For example `NotificationWhatsappResend`. |
+| `breakdown[].name` | string | No | No | Human-readable charge name. |
+| `breakdown[].cost` | number | No | No | Credits charged for this item. |
+| `credit_balance` | number | No | Yes | Available credits; null when credits are unlimited. |
+| `has_sufficient_credits` | boolean | No | No | Whether the workspace can pay for the resend. |
+
 ### Signer
 
 A signing party belonging to a workspace account.
@@ -981,6 +1114,10 @@ A single webhook delivery-history entry.
 | `endpoint` | string | No | Yes | URL that received the request. |
 | `payload` | object | No | Yes | JSON payload sent to the endpoint. |
 | `delivered` | boolean | No | No | Whether delivery succeeded. |
+| `webhook_id` | string | No | Yes | Stable `webhook-id` header across attempts of this event to this endpoint. |
+| `attempt` | integer | No | Yes | Attempt number, starting at 1. |
+| `kind` | string | No | No | enum: `["scheduled", "probe", "manual"]` |
+| `will_retry` | boolean | No | No | Whether another attempt follows this entry. |
 | `http_status` | integer | No | Yes | HTTP status returned (null if connection failed). |
 | `response_body` | string | No | Yes | Endpoint response body, truncated to 2000 chars. |
 | `error` | string | No | Yes | Delivery error message, if any. |
@@ -993,12 +1130,15 @@ A URL that receives the account's webhook events. Every active endpoint subscrib
 
 | Property | Type | Required | Nullable | Constraints / description |
 | --- | --- | --- | --- | --- |
+| `resource` | string | No | No | Always `activity_event_subscription` in single-resource responses. |
 | `id` | string | No | No | Endpoint ID. |
 | `name` | string | No | Yes | Label to tell endpoints apart. |
-| `url` | string (uri) | No | No | URL that receives the events (http or https). |
+| `url` | string (uri) | No | No | HTTPS URL that receives the events. |
 | `email` | string (email) | No | No | Contact email for delivery-failure notices. |
 | `events` | Array<string> | No | No | Event types delivered to this endpoint. |
 | `is_active` | boolean | No | No | Whether events are delivered to this endpoint. |
+| `is_held` | boolean | No | No | Whether deliveries are paused after repeated failures. |
+| `held_since` | integer | No | Yes | Unix timestamp when the pause began; null while deliveries run. |
 | `signing_enabled` | boolean | No | No | Whether deliveries carry a `webhook-signature` header. |
 | `created_at` | string (date-time) | No | No | — |
 | `updated_at` | string (date-time) | No | No | — |
@@ -1048,6 +1188,8 @@ An account's webhook subscription configuration: the account's oldest webhook en
 | --- | --- | --- | --- | --- |
 | `events` | Array<string> | No | No | Event types subscribed for delivery. |
 | `is_active` | boolean | No | No | Whether webhook delivery is active. |
+| `is_held` | boolean | No | No | Whether deliveries are paused after repeated failures. |
+| `held_since` | integer | No | Yes | Unix timestamp when the pause began; null while deliveries run. |
 | `url` | string | No | Yes | Webhook endpoint URL. |
 | `email` | string | No | Yes | Contact email for delivery notices. |
 | `updated_at` | string (date-time) | No | Yes | — |

data/lib/assinafy/client.rb

@@ -33,6 +33,8 @@ module Assinafy
     attr_reader :users
     # @return [Resources::DocumentResource]
     attr_reader :documents
+    # @return [Resources::ContractResource]
+    attr_reader :contracts
     # @return [Resources::SignerResource]
     attr_reader :signers
     # @return [Resources::SignerDocumentResource]
@@ -84,6 +86,7 @@ module Assinafy
       @accounts         = Resources::AccountResource.new(@connection, account_id, @logger)
       @users            = Resources::UserResource.new(@connection, nil, @logger)
       @documents        = Resources::DocumentResource.new(@connection, account_id, @logger)
+      @contracts        = Resources::ContractResource.new(@connection, account_id, @logger)
       @signers          = Resources::SignerResource.new(@connection, account_id, @logger)
       @signer_documents = Resources::SignerDocumentResource.new(@connection, nil, @logger)
       @assignments      = Resources::AssignmentResource.new(@connection, account_id, @logger)
@@ -190,6 +193,7 @@ module Assinafy
     #   #     },
     #   #     assignment: {
     #   #       "resource" => "assignment", "id" => "assignment-id",
+    #   #       "document_id" => "document-id", "created_at" => "2026-06-05T21:21:19Z",
     #   #       "sender_email" => "sender@example.com", "method" => "virtual",
     #   #       "expires_at" => nil, "message" => "Please review and sign",
     #   #       "signers" => [{ "id" => "signer-id", "full_name" => "Example Signer",

data/lib/assinafy/resources/account_resource.rb

@@ -90,6 +90,7 @@ module Assinafy
       #     'name' => 'MT',
       #     'primary_color' => nil,
       #     'secondary_color' => nil,
+      #     'limits' => { 'webhook_endpoints' => 1 },
       #     'created_at' => '2026-05-12T18:05:11Z'
       #   }
       def get(account_id_override = nil)

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 }
@@ -291,6 +303,8 @@ module Assinafy
       #     data: [
       #       {
       #         'id' => 'assignment-id',
+      #         'document_id' => 'document-id',
+      #         'created_at' => '2026-06-05T21:21:19Z',
       #         'sender_email' => 'sender@example.com',
       #         'method' => 'virtual',
       #         'expires_at' => nil,
@@ -330,6 +344,7 @@ module Assinafy
       #   #   "message" => "Please sign" }
       #   # => {
       #   #   "resource" => "assignment", "id" => "assignment-id",
+      #   #   "document_id" => "document-id", "created_at" => "2026-06-05T21:21:19Z",
       #   #   "sender_email" => "sender@example.com", "method" => "virtual",
       #   #   "expires_at" => nil, "message" => "Please sign",
       #   #   "signers" => [{ "id" => "signer-id", "full_name" => "Example Signer",
@@ -463,9 +478,7 @@ module Assinafy
       # @param document_id   [String]
       # @param assignment_id [String]
       # @param signer_id     [String]
-      # @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)
+      # @return [Hash] resend cost (`total`, `breakdown`, `credit_balance`, `has_sufficient_credits`)
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
       # @raise [Assinafy::ValidationError] on invalid required input
@@ -474,13 +487,11 @@ module Assinafy
       #   resource.estimate_resend_cost("document-id", "assignment-id", "signer-id")
       #   # (no request body)
       #   # => {
-      #   #   "documents" => 1, "credits" => 0.45, "needs_extra_document" => false,
-      #   #   "extra_document_cost" => 0, "total_credits" => 0.45,
-      #   #   "breakdown" => [{ "code" => "NotificationWhatsapp",
-      #   #                     "name" => "Whatsapp Notification", "cost" => 0.45,
-      #   #                     "quantity" => 1, "unit_cost" => 0.45 }],
-      #   #   "document_balance" => 10, "credit_balance" => 100,
-      #   #   "has_sufficient_resources" => true, "blocking_reason" => nil, "message" => nil
+      #   #   "total" => 0.45,
+      #   #   "breakdown" => [{ "code" => "NotificationWhatsappResend",
+      #   #                     "name" => "Whatsapp Notification Resend", "cost" => 0.45 }],
+      #   #   "credit_balance" => 100,
+      #   #   "has_sufficient_credits" => true
       #   # }
       def estimate_resend_cost(document_id, assignment_id, signer_id)
         doc_id = require_id(document_id, 'Document ID')