RubyGems - assinafy - Versions diffs - 2.0.1 → 2.1.0 - Mend

assinafy 2.0.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +15 -0
data/README.en.md +23 -1
data/README.md +33 -0
data/docs/API_REFERENCE.md +146 -10
data/lib/assinafy/client.rb +4 -0
data/lib/assinafy/resources/account_resource.rb +1 -0
data/lib/assinafy/resources/assignment_resource.rb +9 -10
data/lib/assinafy/resources/contract_resource.rb +450 -0
data/lib/assinafy/resources/document_resource.rb +3 -0
data/lib/assinafy/resources/user_resource.rb +18 -6
data/lib/assinafy/resources/webhook_resource.rb +35 -5
data/lib/assinafy/version.rb +1 -1
data/lib/assinafy.rb +1 -0
data/sig/assinafy.rbs +18 -0
metadata +4 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83473f4fd075a7c665a16ee6ea6c38c64c548927930221d24ecd468cce1f4203
-  data.tar.gz: 57c81beb685fe09baf9de80eb36abc628d224952b2b08e582d19e24ecb402c16
+  metadata.gz: 1d6db456898234647465325a55c4580054a8ab93f39aff3d6ca067ffe6be9e49
+  data.tar.gz: 55577984ae91aec1ad66715a9b34a8ae10e991f015d6f4e3fe01f5bebf2b9503
 SHA512:
-  metadata.gz: dda868b4808b8885693edc57d8825eaf25a31dd628395180f651bd479a2b59ced524205683900812aa61654b2e79a7c69a110ca8c99c54ea084f21ea3515640a
-  data.tar.gz: ba6c518504f42fddaa0f9cfe4f58b0bfe6e23a83255f2cee5ef1a76551fba72b628f8ea448ba93b24201b055fd41c2ee95882534c3eedfb334f49a5b23cb5439
+  metadata.gz: 93a92268707f3afa45e7f16c837ab3ded90b7ab8859060ff48a0d7eeb81a244dde3b53ada834852de4f83df7e72f738bbffc1468e8ae7de24dfffba56709edb6
+  data.tar.gz: 384b02e9dd54fb89ea78dc61b6f7a507e8e317431d30996b0dcfd16f4a6d3251a03821d0f6d59d28541b2425a24cbd98062c68b2945f0ef2fb252af8569a7ad4

data/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,21 @@
 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

data/README.en.md CHANGED Viewed

@@ -691,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                                                     |
 | --------------------------- | ------------------------------------------------------------------ |
@@ -700,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               |
@@ -781,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 CHANGED Viewed

@@ -966,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
@@ -1072,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 CHANGED Viewed

@@ -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`
@@ -357,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
@@ -385,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) |
@@ -439,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
@@ -466,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 | — |
@@ -608,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 | — |
@@ -626,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 | — |
@@ -644,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 |
@@ -795,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
@@ -825,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.
@@ -987,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. |
@@ -999,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 | — |
@@ -1054,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -303,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,
@@ -342,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",
@@ -475,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
@@ -486,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')

data/lib/assinafy/resources/contract_resource.rb ADDED Viewed

@@ -0,0 +1,450 @@
+# frozen_string_literal: true
+module Assinafy
+  module Resources
+    # Contract terms tracked on workspace documents, including amendments,
+    # renewals, terminations, and lifecycle queries.
+    class ContractResource < BaseResource
+      STATUSES       = %w[draft active expired terminated].freeze
+      RELATION_TYPES = %w[amendment renewal termination].freeze
+      SORTS           = %w[end_date -end_date updated_at -updated_at].freeze
+      LIST_FIELDS     = %w[
+        status counterparty search end_date_from end_date_to ending_within_days
+        external_system external_id sort expand page per-page
+      ].freeze
+      UPDATE_FIELDS = %w[
+        status counterparty_name counterparty_taxpayer_id value currency start_date end_date
+        auto_renew renewal_term_months notice_period_days owner_id metadata external_references
+        parent_document_id relation_type updated_at
+      ].freeze
+      RENEW_FIELDS     = %w[end_date value term updated_at].freeze
+      TERMINATE_FIELDS = %w[reason updated_at].freeze
+      # List tracked contracts in a workspace, most recently updated first.
+      #
+      # @param params [Hash] optional filters: `status`, `counterparty`, `search`,
+      #   `end_date_from`, `end_date_to`, `ending_within_days`, `external_system`,
+      #   `external_id`, `sort`, `expand`, `page`, and `per_page`
+      # @param account_id_override [String, nil]
+      # @return [Hash{Symbol=>Array,Hash}] `{ data: [...], meta: { ... } }`
+      # @raise [Assinafy::ApiError] on an unsuccessful API response
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid filters or account ID
+      # @see GET /accounts/{accountId}/contracts
+      # @example List active contracts ending in the next 30 days
+      #   client.contracts.list(status: ['active'], ending_within_days: 30, expand: 'document')
+      #   # Request: GET /accounts/{accountId}/contracts?status=active&ending_within_days=30&expand=document
+      #   # => {
+      #   #   data: [{
+      #   #     'resource' => 'document_contract', 'document_id' => 'document-id',
+      #   #     'status' => 'active', 'counterparty_name' => 'Example Ltda',
+      #   #     'counterparty_taxpayer_id' => '11222333000181', 'value' => 120000.50,
+      #   #     'currency' => 'BRL', 'start_date' => '2026-11-01', 'end_date' => '2027-10-31',
+      #   #     'auto_renew' => true, 'renewal_term_months' => 12, 'notice_period_days' => 30,
+      #   #     'term' => 1, 'owner_id' => 'user-id', 'metadata' => { 'crm_stage' => 'won' },
+      #   #     'external_references' => [{ 'system' => 'hubspot', 'id' => '98765' }],
+      #   #     'document' => { 'id' => 'document-id', 'name' => 'agreement.pdf', 'status' => 'certificated' },
+      #   #     'created_at' => '2026-10-23T12:00:00Z', 'updated_at' => '2026-10-23T12:00:00Z'
+      #   #   }],
+      #   #   meta: { current_page: 1, per_page: 20, total: 1, last_page: 1 }
+      #   # }
+      def list(params = {}, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        query  = contract_list_params(params)
+        call_list('Failed to list contracts') do
+          http_get("accounts/#{acc_id}/contracts", query)
+        end
+      end
+      # Fetch the contract terms or pending/applied amendment linked to a document.
+      # Returns `nil` when the document has no tracked contract terms.
+      #
+      # @param document_id [String]
+      # @param account_id_override [String, nil]
+      # @return [Hash, nil] a DocumentContract or DocumentContractAmendment
+      # @raise [Assinafy::ApiError] on an unsuccessful response other than 404
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on an invalid ID
+      # @see GET /accounts/{accountId}/documents/{documentId}/contract
+      # @example Read a contract and its amendments
+      #   client.contracts.get('document-id')
+      #   # Request: GET /accounts/{accountId}/documents/document-id/contract
+      #   # => {
+      #   #   'resource' => 'document_contract', 'document_id' => 'document-id', 'status' => 'active',
+      #   #   'counterparty_name' => 'Example Ltda', 'counterparty_taxpayer_id' => '11222333000181',
+      #   #   'value' => 130000, 'currency' => 'BRL', 'start_date' => '2026-11-01',
+      #   #   'end_date' => '2028-06-30', 'auto_renew' => true, 'renewal_term_months' => 12,
+      #   #   'notice_period_days' => 30, 'term' => 2, 'owner_id' => 'user-id',
+      #   #   'metadata' => { 'crm_stage' => 'won' },
+      #   #   'external_references' => [{ 'system' => 'hubspot', 'id' => '98765' }],
+      #   #   'amendments' => [{
+      #   #     'resource' => 'document_contract_amendment', 'document_id' => 'amendment-id',
+      #   #     'document_name' => 'Amendment 1.pdf', 'parent_document_id' => 'document-id',
+      #   #     'relation_type' => 'amendment', 'number' => 1, 'status' => 'applied',
+      #   #     'document_status' => 'certificated', 'apply_error' => nil, 'currency' => 'BRL',
+      #   #     'terms' => { 'value' => 130000, 'end_date' => '2028-06-30' },
+      #   #     'changes' => { 'value' => { 'from' => 120000.50, 'to' => 130000 } },
+      #   #     'applied_at' => '2027-05-12T18:20:00Z',
+      #   #     'created_at' => '2027-05-10T15:00:00Z', 'updated_at' => '2027-05-12T18:20:00Z'
+      #   #   }],
+      #   #   'created_at' => '2026-10-23T12:00:00Z', 'updated_at' => '2027-05-12T18:20:00Z'
+      #   # }
+      def get(document_id, account_id_override = nil)
+        call_optional('Failed to fetch contract') do
+          http_get(contract_path(document_id, account_id_override))
+        end
+      end
+      # Create or partially update contract terms, or link a document as an
+      # amendment, renewal, or termination instrument. Explicit `nil` values
+      # are sent as JSON null because the API uses them to clear terms.
+      #
+      # @param document_id [String]
+      # @param payload [Hash] at least one DocumentContractInput property
+      # @param account_id_override [String, nil]
+      # @return [Hash] the saved DocumentContract or DocumentContractAmendment
+      # @raise [Assinafy::ApiError] including 403 without the plan and 409 on a stale `updated_at`
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid IDs or payload fields
+      # @see PUT /accounts/{accountId}/documents/{documentId}/contract
+      # @example Set a document's contract terms
+      #   client.contracts.update(
+      #     'document-id', status: 'active', counterparty_name: 'Example Ltda',
+      #     value: 120000.50, currency: 'BRL', start_date: '2026-11-01', end_date: '2027-10-31',
+      #     auto_renew: true, renewal_term_months: 12, notice_period_days: 30,
+      #     metadata: { crm_stage: 'won' },
+      #     external_references: [{ system: 'hubspot', id: '98765' }]
+      #   )
+      #   # Request body:
+      #   # { "status":"active", "counterparty_name":"Example Ltda", "value":120000.5,
+      #   #   "currency":"BRL", "start_date":"2026-11-01", "end_date":"2027-10-31",
+      #   #   "auto_renew":true, "renewal_term_months":12, "notice_period_days":30,
+      #   #   "metadata":{"crm_stage":"won"},
+      #   #   "external_references":[{"system":"hubspot","id":"98765"}] }
+      #   # => { 'resource' => 'document_contract', 'document_id' => 'document-id', 'status' => 'active',
+      #   #      'counterparty_name' => 'Example Ltda', 'counterparty_taxpayer_id' => nil,
+      #   #      'value' => 120000.50, 'currency' => 'BRL', 'start_date' => '2026-11-01',
+      #   #      'end_date' => '2027-10-31', 'auto_renew' => true, 'renewal_term_months' => 12,
+      #   #      'notice_period_days' => 30, 'term' => 1, 'owner_id' => nil,
+      #   #      'metadata' => { 'crm_stage' => 'won' },
+      #   #      'external_references' => [{ 'system' => 'hubspot', 'id' => '98765' }],
+      #   #      'created_at' => '2026-10-23T12:00:00Z', 'updated_at' => '2026-10-23T12:00:00Z' }
+      # @example Link a signed amendment and preserve nulls
+      #   client.contracts.update(
+      #     'amendment-id', parent_document_id: 'document-id', relation_type: 'amendment',
+      #     value: 130000, counterparty_name: nil
+      #   )
+      #   # Request body includes "counterparty_name": null.
+      def update(document_id, payload, account_id_override = nil)
+        body = contract_payload(payload, UPDATE_FIELDS, 'Contract payload')
+        raise ValidationError.new('Contract payload must change at least one field') if body.empty?
+        validate_contract_input!(body)
+        call('Failed to update contract') do
+          http_put(contract_path(document_id, account_id_override), body)
+        end
+      end
+      # Fetch the root contract and every related amendment, renewal, and
+      # termination document. Returns `nil` when the document has no family.
+      #
+      # @param document_id [String]
+      # @param account_id_override [String, nil]
+      # @return [Hash, nil] root DocumentContract with `amendments`
+      # @raise [Assinafy::ApiError] on an unsuccessful response other than 404
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on an invalid ID
+      # @see GET /accounts/{accountId}/documents/{documentId}/contract/related
+      # @example Read a family from one of its amendments
+      #   client.contracts.related('amendment-id')
+      #   # Request: GET /accounts/{accountId}/documents/amendment-id/contract/related
+      #   # => { 'resource' => 'document_contract', 'document_id' => 'document-id', 'status' => 'active',
+      #   #      'counterparty_name' => 'Example Ltda', 'counterparty_taxpayer_id' => '11222333000181',
+      #   #      'value' => 130000, 'currency' => 'BRL', 'start_date' => '2026-11-01',
+      #   #      'end_date' => '2028-06-30', 'auto_renew' => true, 'renewal_term_months' => 12,
+      #   #      'notice_period_days' => 30, 'term' => 2, 'owner_id' => 'user-id',
+      #   #      'metadata' => nil, 'external_references' => [],
+      #   #      'amendments' => [{ 'document_id' => 'amendment-id', 'relation_type' => 'amendment',
+      #   #                          'number' => 1, 'status' => 'applied', 'terms' => { 'value' => 130000 } }],
+      #   #      'created_at' => '2026-10-23T12:00:00Z', 'updated_at' => '2027-05-12T18:20:00Z' }
+      def related(document_id, account_id_override = nil)
+        call_optional('Failed to fetch related contracts') do
+          http_get("#{contract_path(document_id, account_id_override)}/related")
+        end
+      end
+      # Start the contract's next term. Send the current `term` for an
+      # idempotent term-based renewal, or an explicit later `end_date`.
+      # Explicit `value: nil` clears the contract value.
+      #
+      # @param document_id [String]
+      # @param payload [Hash] `term` or `end_date`, plus optional `value` and `updated_at`
+      # @param account_id_override [String, nil]
+      # @return [Hash] the renewed DocumentContract
+      # @raise [Assinafy::ApiError] including 403 without the plan and 409 on a stale `updated_at`
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid IDs or payload fields
+      # @see POST /accounts/{accountId}/documents/{documentId}/contract/renew
+      # @example Renew from the current term
+      #   client.contracts.renew('document-id', term: 1, value: 126000)
+      #   # Request body: { "term": 1, "value": 126000 }
+      #   # => { 'resource' => 'document_contract', 'document_id' => 'document-id', 'status' => 'active',
+      #   #      'counterparty_name' => 'Example Ltda', 'counterparty_taxpayer_id' => '11222333000181',
+      #   #      'value' => 126000, 'currency' => 'BRL', 'start_date' => '2026-11-01',
+      #   #      'end_date' => '2028-10-31', 'auto_renew' => true, 'renewal_term_months' => 12,
+      #   #      'notice_period_days' => 30, 'term' => 2, 'owner_id' => 'user-id',
+      #   #      'metadata' => nil, 'external_references' => [],
+      #   #      'created_at' => '2026-10-23T12:00:00Z', 'updated_at' => '2027-10-15T09:30:00Z' }
+      def renew(document_id, payload, account_id_override = nil)
+        body = contract_payload(payload, RENEW_FIELDS, 'Contract renewal payload')
+        validate_renewal!(body)
+        call('Failed to renew contract') do
+          http_post("#{contract_path(document_id, account_id_override)}/renew", body)
+        end
+      end
+      # Terminate a contract and stop lifecycle alerts. The optional reason is
+      # recorded in the document activity event.
+      #
+      # @param document_id [String]
+      # @param payload [Hash] optional `reason` and optimistic-lock `updated_at`
+      # @param account_id_override [String, nil]
+      # @return [Hash] the terminated DocumentContract
+      # @raise [Assinafy::ApiError] including 403 without the plan and 409 on a stale `updated_at`
+      # @raise [Assinafy::NetworkError] on transport or TLS failure
+      # @raise [Assinafy::ValidationError] on invalid IDs or payload fields
+      # @see POST /accounts/{accountId}/documents/{documentId}/contract/terminate
+      # @example Terminate with a reason
+      #   client.contracts.terminate('document-id', reason: 'Supplier replaced')
+      #   # Request body: { "reason": "Supplier replaced" }
+      #   # => { 'resource' => 'document_contract', 'document_id' => 'document-id', 'status' => 'terminated',
+      #   #      'counterparty_name' => 'Example Ltda', 'counterparty_taxpayer_id' => '11222333000181',
+      #   #      'value' => 120000.50, 'currency' => 'BRL', 'start_date' => '2026-11-01',
+      #   #      'end_date' => '2027-10-31', 'auto_renew' => true, 'renewal_term_months' => 12,
+      #   #      'notice_period_days' => 30, 'term' => 1, 'owner_id' => 'user-id',
+      #   #      'metadata' => nil, 'external_references' => [],
+      #   #      'created_at' => '2026-10-23T12:00:00Z', 'updated_at' => '2027-03-02T14:00:00Z' }
+      def terminate(document_id, payload = {}, account_id_override = nil)
+        body = contract_payload(payload, TERMINATE_FIELDS, 'Contract termination payload')
+        validate_optional_string!(body, 'reason', 'Termination reason', max_length: 500)
+        validate_optional_string!(body, 'updated_at', 'updated_at')
+        call('Failed to terminate contract') do
+          http_post("#{contract_path(document_id, account_id_override)}/terminate", body)
+        end
+      end
+      private
+      def contract_path(document_id, account_id_override)
+        doc_id = require_id(document_id, 'Document ID')
+        "accounts/#{account_id(account_id_override)}/documents/#{doc_id}/contract"
+      end
+      def contract_list_params(params)
+        query = query_params(require_payload(params, 'Contract filters'))
+        reject_unknown_fields!(query, LIST_FIELDS, 'contract filters')
+        validate_status_filter!(query)
+        %w[counterparty search external_system external_id].each do |field|
+          validate_optional_string!(query, field, field)
+        end
+        %w[end_date_from end_date_to].each { |field| validate_optional_date!(query, field) }
+        if query['end_date_from'] && query['end_date_to'] && query['end_date_from'] > query['end_date_to']
+          raise ValidationError.new('end_date_from must not be after end_date_to')
+        end
+        if query.key?('ending_within_days')
+          validate_integer!(query['ending_within_days'], 'ending_within_days', 0, 3650)
+        end
+        validate_integer!(query['page'], 'page', 1) if query.key?('page')
+        validate_integer!(query['per-page'], 'per_page', 1, 100) if query.key?('per-page')
+        validate_enum!(query, 'sort', SORTS)
+        validate_enum!(query, 'expand', %w[document])
+        query
+      end
+      def validate_status_filter!(query)
+        return unless query.key?('status')
+        statuses = query['status'].is_a?(Array) ? query['status'] : query['status'].to_s.split(',')
+        unless !statuses.empty? && statuses.all? { |status| status.is_a?(String) && STATUSES.include?(status) }
+          raise ValidationError.new("status must contain only: #{STATUSES.join(', ')}")
+        end
+        query['status'] = statuses.join(',')
+      end
+      def contract_payload(payload, allowed, name)
+        raw  = require_payload(payload, name)
+        body = body_params(raw)
+        raw.each { |key, value| body[key.to_s] = nil if value.nil? }
+        reject_unknown_fields!(body, allowed, name.downcase)
+        body
+      end
+      def validate_contract_input!(body)
+        validate_enum!(body, 'status', STATUSES)
+        validate_enum!(body, 'relation_type', RELATION_TYPES)
+        validate_contract_strings!(body)
+        validate_contract_dates!(body)
+        validate_contract_numbers!(body)
+        validate_contract_collections!(body)
+      end
+      def validate_contract_strings!(body)
+        validate_optional_string!(body, 'counterparty_name', 'counterparty_name', max_length: 255)
+        validate_optional_string!(body, 'counterparty_taxpayer_id', 'counterparty_taxpayer_id')
+        validate_optional_string!(body, 'owner_id', 'owner_id')
+        validate_optional_timestamp!(body, 'updated_at')
+        validate_parent_document_id!(body)
+        validate_currency!(body)
+      end
+      def validate_contract_dates!(body)
+        %w[start_date end_date].each { |field| validate_optional_date!(body, field, minimum_year: 1000) }
+        if body['start_date'] && body['end_date'] && body['start_date'] > body['end_date']
+          raise ValidationError.new('end_date must not be before start_date')
+        end
+      end
+      def validate_contract_numbers!(body)
+        if body.key?('value') && !body['value'].nil?
+          validate_number!(body['value'], 'value', 0, 9_999_999_999_999.99)
+        end
+        validate_boolean!(body, 'auto_renew')
+        validate_integer!(body['renewal_term_months'], 'renewal_term_months', 1, 600) if body['renewal_term_months']
+        validate_integer!(body['notice_period_days'], 'notice_period_days', 0, 3650) if body['notice_period_days']
+      end
+      def validate_contract_collections!(body)
+        validate_metadata!(body['metadata']) if body.key?('metadata') && !body['metadata'].nil?
+        if body.key?('external_references') && !body['external_references'].nil?
+          validate_external_references!(body['external_references'])
+        end
+      end
+      def validate_renewal!(body)
+        unless body['term'] || body['end_date']
+          raise ValidationError.new('Contract renewal requires term or end_date')
+        end
+        validate_optional_date!(body, 'end_date')
+        validate_integer!(body['term'], 'term', 1) if body.key?('term')
+        validate_number!(body['value'], 'value', 0, 9_999_999_999_999.99) if body.key?('value') && !body['value'].nil?
+        validate_optional_timestamp!(body, 'updated_at')
+      end
+      def validate_parent_document_id!(body)
+        return unless body.key?('parent_document_id') && !body['parent_document_id'].nil?
+        require_id(body['parent_document_id'], 'parent_document_id')
+      end
+      def validate_currency!(body)
+        return unless body.key?('currency') && !body['currency'].nil?
+        currency = require_string(body['currency'], 'currency')
+        raise ValidationError.new('currency must be a three-letter code') unless currency.match?(/\A[A-Za-z]{3}\z/)
+      end
+      def validate_optional_date!(body, field, minimum_year: nil)
+        return unless body.key?(field) && !body[field].nil?
+        value = require_string(body[field], field)
+        date = Date.iso8601(value)
+        raise ArgumentError unless value.match?(/\A\d{4}-\d{2}-\d{2}\z/) && (!minimum_year || date.year >= minimum_year)
+      rescue ArgumentError
+        raise ValidationError.new("#{field} must be YYYY-MM-DD")
+      end
+      def validate_optional_string!(body, field, name, max_length: nil)
+        return unless body.key?(field) && !body[field].nil?
+        require_string(body[field], name, max_length: max_length)
+      end
+      def validate_enum!(body, field, allowed)
+        return unless body.key?(field)
+        value = require_string(body[field], field)
+        return if allowed.include?(value)
+        raise ValidationError.new("#{field} must be one of: #{allowed.join(', ')}")
+      end
+      def validate_boolean!(body, field)
+        require_boolean(body[field], field) if body.key?(field) && !body[field].nil?
+      end
+      def validate_optional_timestamp!(body, field)
+        return unless body.key?(field) && !body[field].nil?
+        value = require_string(body[field], field)
+        DateTime.iso8601(value)
+        return if value.match?(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/)
+        raise ArgumentError
+      rescue ArgumentError
+        raise ValidationError.new("#{field} must be an ISO 8601 timestamp with a timezone")
+      end
+      def validate_integer!(value, name, minimum, maximum = nil)
+        valid = value.is_a?(Integer) && value >= minimum && (maximum.nil? || value <= maximum)
+        return if valid
+        range = maximum ? "between #{minimum} and #{maximum}" : "at least #{minimum}"
+        raise ValidationError.new("#{name} must be an Integer #{range}")
+      end
+      def validate_number!(value, name, minimum, maximum = nil)
+        number = value.is_a?(Integer) || value.is_a?(Float)
+        finite = number && (!value.respond_to?(:finite?) || value.finite?)
+        valid = finite && value.round(2) == value && value >= minimum && (maximum.nil? || value <= maximum)
+        return if valid
+        raise ValidationError.new("#{name} must be a finite number in the documented range")
+      end
+      def validate_metadata!(metadata)
+        unless metadata.is_a?(Hash) && metadata.length <= 50
+          raise ValidationError.new('metadata must be a Hash with at most 50 entries')
+        end
+        metadata.each do |key, value|
+          valid_key = key.to_s.match?(/\A[A-Za-z0-9_.-]{1,40}\z/)
+          valid_value = value.is_a?(String) && value.length <= 500
+          next if valid_key && valid_value
+          raise ValidationError.new('metadata keys or values are invalid')
+        end
+      end
+      def validate_external_references!(references)
+        unless references.is_a?(Array) && references.length <= 20
+          raise ValidationError.new('external_references must be an Array with at most 20 entries')
+        end
+        references.each do |reference|
+          unless reference.is_a?(Hash)
+            raise ValidationError.new('Each external reference must be a Hash')
+          end
+          ref = reference.transform_keys(&:to_s)
+          system = require_string(ref['system'], 'External reference system', max_length: 64)
+          require_string(ref['id'], 'External reference ID', max_length: 255)
+          unless system.match?(/\A[A-Za-z0-9_.-]+\z/)
+            raise ValidationError.new('External reference system contains invalid characters')
+          end
+        end
+      end
+      def reject_unknown_fields!(body, allowed, name)
+        unknown = body.keys - allowed
+        raise ValidationError.new("Unknown #{name}: #{unknown.join(', ')}") unless unknown.empty?
+      end
+    end
+  end
+end

data/lib/assinafy/resources/document_resource.rb CHANGED Viewed

@@ -40,6 +40,8 @@ module Assinafy
       #     },
       #     'is_closed' => false,
       #     'signing_url' => 'https://app-sandbox.assinafy.com.br/sign/document-id',
+      #     'verification_code' => nil,
+      #     'verification_url' => nil,
       #     'decline_reason' => nil,
       #     'declined_by' => nil,
       #     'tags' => [],
@@ -233,6 +235,7 @@ module Assinafy
       #     'declined_by' => nil,
       #     'tags' => [],
       #     'assignment' => nil,
+      #     'has_contract' => false,
       #     'pages' => [
       #       { 'id' => 'page-id', 'number' => 1, 'height' => 1651,
       #         'width' => 1275, 'download_url' => 'https://sandbox.assinafy.com.br/v1/documents/.../download' }

data/lib/assinafy/resources/user_resource.rb CHANGED Viewed

@@ -16,6 +16,10 @@ module Assinafy
         DocumentProcessingFailed
         TemplateProcessingFailed
         SignerWhatsappFailed
+        ContractRenewalNotice
+        ContractExpiring
+        ContractExpired
+        ContractRenewed
       ].freeze
       # Fetch the authenticated user's profile. The current OpenAPI response is
@@ -117,11 +121,11 @@ module Assinafy
         end
       end
-      # Fetch all owner-facing document email preferences. All nine keys are
+      # Fetch all owner-facing document and contract email preferences. All thirteen keys are
       # returned and default to true. Account and security email is not
       # configurable through this endpoint.
       #
-      # @return [Hash{String=>Boolean}] all nine documented preference codes
+      # @return [Hash{String=>Boolean}] all thirteen documented preference codes
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
       # @raise [Assinafy::ValidationError] on invalid required input
@@ -139,7 +143,11 @@ module Assinafy
       #     'DocumentExpirationReset' => true,
       #     'DocumentProcessingFailed' => true,
       #     'TemplateProcessingFailed' => true,
-      #     'SignerWhatsappFailed' => true
+      #     'SignerWhatsappFailed' => true,
+      #     'ContractRenewalNotice' => true,
+      #     'ContractExpiring' => true,
+      #     'ContractExpired' => true,
+      #     'ContractRenewed' => true
       #   }
       def notification_preferences
         call('Failed to fetch notification preferences') do
@@ -147,10 +155,10 @@ module Assinafy
         end
       end
-      # Merge selected owner-facing document email preferences.
+      # Merge selected owner-facing document and contract email preferences.
       #
       # Omitted keys keep their current values. The API returns the full
-      # nine-key map shown by {#notification_preferences}.
+      # thirteen-key map shown by {#notification_preferences}.
       #
       # @param preferences [Hash{String,Symbol=>Boolean}] non-empty partial map
       # @return [Hash{String=>Boolean}] the full updated map
@@ -174,7 +182,11 @@ module Assinafy
       #     'DocumentExpirationReset' => true,
       #     'DocumentProcessingFailed' => true,
       #     'TemplateProcessingFailed' => true,
-      #     'SignerWhatsappFailed' => true
+      #     'SignerWhatsappFailed' => true,
+      #     'ContractRenewalNotice' => true,
+      #     'ContractExpiring' => true,
+      #     'ContractExpired' => true,
+      #     'ContractRenewed' => true
       #   }
       def update_notification_preferences(preferences)
         preferences = require_payload(preferences, 'Notification preferences')

data/lib/assinafy/resources/webhook_resource.rb CHANGED Viewed

@@ -28,7 +28,8 @@ module Assinafy
       # @option payload [Array<String>] :events    event-type IDs (see {#list_event_types})
       # @option payload [Boolean]       :is_active default `true` when omitted
       # @param account_id_override [String, nil]
-      # @return [Hash] the subscription object: { events:, is_active:, url:, email:, updated_at: }
+      # @return [Hash] the subscription object: { events:, is_active:, is_held:, held_since:, url:, email:,
+      #   updated_at: }
       # @raise [Assinafy::ApiError] on an unsuccessful API response
       # @raise [Assinafy::NetworkError] on transport or TLS failure
       # @raise [Assinafy::ValidationError] on invalid required input
@@ -51,6 +52,8 @@ module Assinafy
       #   # {
       #   #   'events' => ["document_ready", "document_prepared"],
       #   #   'is_active' => true,
+      #   #   'is_held' => false,
+      #   #   'held_since' => nil,
       #   #   'url' => "https://example.com/webhook",
       #   #   'email' => "ops@example.com",
       #   #   'updated_at' => "2026-06-05T21:13:24Z"
@@ -84,6 +87,8 @@ module Assinafy
       #   # {
       #   #   'events' => ["document_ready", "signer_signed_document"],
       #   #   'is_active' => false,
+      #   #   'is_held' => false,
+      #   #   'held_since' => nil,
       #   #   'url' => "https://example.com/sdk-smoke-webhook",
       #   #   'email' => "webhook@example.com",
       #   #   'updated_at' => "2026-06-05T21:13:24Z"
@@ -113,6 +118,8 @@ module Assinafy
       #   # {
       #   #   'events' => ["document_ready", "document_prepared"],
       #   #   'is_active' => false,
+      #   #   'is_held' => false,
+      #   #   'held_since' => nil,
       #   #   'url' => "https://example.com/webhook",
       #   #   'email' => "ops@example.com",
       #   #   'updated_at' => "2026-06-05T21:13:24Z"
@@ -178,6 +185,10 @@ module Assinafy
       #   #       endpoint:      "https://example.com/webhook",
       #   #       payload:       { 'id' => 15431, event: "signature_requested", object: {}, subject: {}, payload: {} },
       #   #       delivered:     false,
+      #   #       webhook_id:    "webhook-id-placeholder",
+      #   #       attempt:       2,
+      #   #       kind:          "scheduled",
+      #   #       will_retry:    false,
       #   #       http_status:   404,
       #   #       response_body: "{\"success\":false,...}",
       #   #       error:         "Client error: `POST https://example.com/webhook` resulted in a 404 ...",
@@ -217,6 +228,10 @@ module Assinafy
       #   #   endpoint:      "https://example.com/webhook",
       #   #   payload:       { 'id' => 15431, event: "signature_requested", object: {}, subject: {} },
       #   #   delivered:     true,
+      #   #   webhook_id:    "webhook-id-placeholder",
+      #   #   attempt:       1,
+      #   #   kind:          "manual",
+      #   #   will_retry:    false,
       #   #   http_status:   200,
       #   #   response_body: "OK",
       #   #   error:         nil,
@@ -247,12 +262,15 @@ module Assinafy
       #   # => unwrapped data payload returned:
       #   # [
       #   #   {
+      #   #     'resource' => "activity_event_subscription",
       #   #     '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,
+      #   #     'is_held' => false,
+      #   #     'held_since' => nil,
       #   #     'signing_enabled' => true,
       #   #     'created_at' => "2026-10-01T12:00:00Z",
       #   #     'updated_at' => "2026-10-01T12:00:00Z"
@@ -274,7 +292,7 @@ module Assinafy
       # especially for OAuth apps, which cannot call {#endpoint_secret}.
       #
       # @param payload [Hash]
-      # @option payload [String]        :url             http(s) URL that receives the events (required)
+      # @option payload [String]        :url             HTTPS URL that receives the events (required)
       # @option payload [String]        :email           contact email for delivery-failure notices (required)
       # @option payload [Array<String>] :events          event-type IDs (see {#list_event_types}) (required)
       # @option payload [String]        :name            label to tell endpoints apart
@@ -304,8 +322,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,
+      #   # { 'resource' => "activity_event_subscription", 'id' => "webhook-endpoint-id", 'name' => "ERP",
+      #   #   'url' => "https://example.com/webhooks/assinafy", 'email' => "ops@example.com",
+      #   #   'events' => [...], 'is_active' => true, 'is_held' => false, 'held_since' => nil,
+      #   #   '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)
@@ -481,7 +501,7 @@ module Assinafy
       end
       def validate_webhook_fields!(body)
-        require_string(body[:url], 'Webhook URL') if body.key?(:url)
+        validate_webhook_url!(body[:url]) if body.key?(:url)
         Utils.require_email(body[:email]) if body.key?(:email)
         require_string(body[:name], 'Webhook name') if body.key?(:name)
         %i[is_active signing_enabled].each { |key| require_boolean(body[key], key.to_s) if body.key?(key) }
@@ -492,6 +512,16 @@ module Assinafy
         raise ValidationError.new('Webhook events must be non-empty Strings')
       end
+      def validate_webhook_url!(value)
+        url = require_string(value, 'Webhook URL')
+        uri = URI.parse(url)
+        return if uri.is_a?(URI::HTTPS) && uri.host && !uri.host.empty?
+        raise ValidationError.new('Webhook URL must be an absolute HTTPS URL')
+      rescue URI::InvalidURIError
+        raise ValidationError.new('Webhook URL must be an absolute HTTPS URL')
+      end
     end
   end
 end

data/lib/assinafy/version.rb CHANGED Viewed

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

data/lib/assinafy.rb CHANGED Viewed

@@ -17,6 +17,7 @@ require_relative 'assinafy/resources/oauth_resource'
 require_relative 'assinafy/resources/account_resource'
 require_relative 'assinafy/resources/user_resource'
 require_relative 'assinafy/resources/document_resource'
+require_relative 'assinafy/resources/contract_resource'
 require_relative 'assinafy/resources/signer_resource'
 require_relative 'assinafy/resources/signer_document_resource'
 require_relative 'assinafy/resources/assignment_resource'

data/sig/assinafy.rbs CHANGED Viewed

@@ -283,6 +283,23 @@ module Assinafy
       def signing_progress: (String document_id) -> signing_progress
     end
+    class ContractResource < BaseResource
+      STATUSES: Array[String]
+      RELATION_TYPES: Array[String]
+      SORTS: Array[String]
+      LIST_FIELDS: Array[String]
+      UPDATE_FIELDS: Array[String]
+      RENEW_FIELDS: Array[String]
+      TERMINATE_FIELDS: Array[String]
+      def list: (?params params, ?String? account_id_override) -> list_result
+      def get: (String document_id, ?String? account_id_override) -> api_object?
+      def update: (String document_id, params payload, ?String? account_id_override) -> api_object
+      def related: (String document_id, ?String? account_id_override) -> api_object?
+      def renew: (String document_id, params payload, ?String? account_id_override) -> api_object
+      def terminate: (String document_id, ?params payload, ?String? account_id_override) -> api_object
+    end
     class SignerResource < BaseResource
       EMAIL_REGEX: Regexp
       SIGNATURE_TYPES: Array[String]
@@ -445,6 +462,7 @@ module Assinafy
     attr_reader accounts: Resources::AccountResource
     attr_reader users: Resources::UserResource
     attr_reader documents: Resources::DocumentResource
+    attr_reader contracts: Resources::ContractResource
     attr_reader signers: Resources::SignerResource
     attr_reader signer_documents: Resources::SignerDocumentResource
     attr_reader assignments: Resources::AssignmentResource

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: assinafy
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Assinafy SDK Contributors
@@ -134,8 +134,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 description: Ruby SDK for Assinafy. Covers the documented authentication, OAuth 2.1,
-  account, user, document, signer, assignment, webhook, template, tag, and field APIs,
-  plus the high-level upload_and_request_signatures helper.
+  account, user, document, contract, signer, assignment, webhook, template, tag, and
+  field APIs, plus the high-level upload_and_request_signatures helper.
 email:
 - sdk@assinafy.com.br
 executables: []
@@ -157,6 +157,7 @@ files:
 - lib/assinafy/resources/assignment_resource.rb
 - lib/assinafy/resources/auth_resource.rb
 - lib/assinafy/resources/base_resource.rb
+- lib/assinafy/resources/contract_resource.rb
 - lib/assinafy/resources/document_resource.rb
 - lib/assinafy/resources/field_resource.rb
 - lib/assinafy/resources/oauth_resource.rb