assinafy 1.11.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97dcce395cbee3bd4a632650550becfd07d6fa291da434678d1a31de4488d103
-  data.tar.gz: 4cde25cfc6221e23378892c4fa19d7779046b65642bc33dc734756f712c2aab8
+  metadata.gz: d2a0b97db3a9ad302307e31bccf8f06751fe310dd253417bb129ad921b0a4b3f
+  data.tar.gz: 94eb893e22a78777a0b4102d572e274e0f22c5b50cd3768d348f2deac69541ab
 SHA512:
-  metadata.gz: 437fad120c4ec641767a2241f0e03589e14ea31b3407b603c85e7284476526711cd8d8f8732573d2ab4348aa9387cbfa077e43061ff91e1728eeda766b6c51f2
-  data.tar.gz: 9c2e1b81591e038d449145fa3f97f7b2b90f98fbfede435f01cd14fbfbb6b9d62805df762e39a01c0e9de7a8d9e729371d3b88e63b5049fb7ac29b0c10d01b88
+  metadata.gz: 43838b1c27e22fc5210a8e877a4e1897f50030a6e32801cf490f101de6d18805ed79bff013120801ce90ab53369531142bf678cbe0e04f543139aa72790bab11
+  data.tar.gz: f0e442b567d84643b2237ec21edf5b59de9155268451986dcdcc19f841ccf1514e1fd11e112fedc0ff1b8c04439feb411fec7ec37bc06128a86409996745798e

data/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## [2.0.0] - 2026-10-16
+
+### Added
+
+- `IdDocumentFaceMatchBasic` biometric verification in assignments, cost estimates and template generation,
+  paired with either Email or Whatsapp notifications.
+- `SignerResource#identity_verification` and `#start_identity_verification` for hosted identity verification
+  with explicit biometric-processing consent and signer-only authentication.
+- `AssignmentResource#identity_review`, `#identity_review_image` and `#decide_identity_review` for account
+  reviewers to inspect evidence and approve or reject a biometric identity review.
+- `WebhookResource#list_endpoints(url:)` filters by exact URL, and `#delete_endpoint_by_url` removes the endpoint
+  registered with that URL.
+
+## [1.11.1] - 2026-10-12
+
+### Added
+
+- `Assinafy::ApiError#rate_limit` returns `{ limit:, remaining:, reset: }` from the `X-Rate-Limit-*` headers, and
+  `#retry_after` returns the `Retry-After` seconds of a `429 Too Many Requests`.
+- `SignerDocumentResource#list_as_workspace` and `#search_as_workspace` list and search a signer's documents with
+  the workspace API key or token.
+
+### Changed
+
+- `DocumentResource#send_token` always sends `{ "channel": "email", "recipient": "<signer email>" }`, as the API
+  requires, and returns `{ document, channel, recipient }`. `recipient:` (or the earlier `email:`) must be an email
+  address; calls without a recipient, with a `whatsapp` channel, or with a phone number now raise
+  `ValidationError`.
+- `SignerDocumentResource#list` and `#search` require the signer access code and never send workspace
+  credentials. Calls that relied on omitting the code to use the API key now raise `ValidationError`; switch them
+  to `#list_as_workspace` / `#search_as_workspace`.
+- `FieldResource#validate` and `#validate_multiple` raise `ValidationError` for an explicit `signer_access_code:
+  nil` instead of falling back to workspace credentials. Omitting the keyword still uses workspace credentials.
+- `AssignmentResource#estimate_cost` accepts payloads without `signers` or `entries`, which the API treats as
+  optional.
+- `DocumentResource#search` and `SignerDocumentResource#search` accept a `nil` search term and omit `search`.
+- `FieldResource#create` sends an explicit `regex: nil` as JSON `null`.
+- `DocumentResource#rename` rejects names longer than 255 characters before sending.
+
 ## 1.11.0
 
 ### Added

data/README.en.md

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

data/README.md

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

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

data/lib/assinafy/errors.rb

@@ -52,6 +52,32 @@ module Assinafy
       @error_code = response_data['code']
     end
 
+    # Rate-limit window reported by the `X-Rate-Limit-Limit`, `X-Rate-Limit-Remaining` and
+    # `X-Rate-Limit-Reset` response headers. Only the headers present are included.
+    #
+    # @return [Hash{Symbol=>Integer}, nil] `{ limit:, remaining:, reset: }` (reset in seconds), or nil
+    # @example
+    #   e.rate_limit # => { limit: 60, remaining: 0, reset: 42 }
+    def rate_limit
+      context[:rate_limit]
+    end
+
+    # Seconds to wait before retrying, from the `Retry-After` header of a `429 Too Many Requests`.
+    #
+    # @return [Integer, nil]
+    # @example Back off on a rate-limited request
+    #   begin
+    #     client.documents.list
+    #   rescue Assinafy::ApiError => e
+    #     raise unless e.status_code == 429
+    #
+    #     sleep(e.retry_after || 1)
+    #     retry
+    #   end
+    def retry_after
+      context[:retry_after]
+    end
+
     # Build an {ApiError} from an HTTP status and parsed body. Reads the human
     # message from `message`, `error`, or `name` (in that order).
     #