@assinafy/sdk 2.1.2 → 2.3.0

package/README.md

@@ -1,41 +1,73 @@
 # @assinafy/sdk
 
-TypeScript SDK for the [Assinafy API](https://api.assinafy.com.br/v1/docs) — a Brazilian digital signature platform.
+*Português · [Read in English](README.en.md)*
 
-Covers all 89 operations in the current official OpenAPI document: accounts,
-authentication, users, documents, assignments, signers, signer-side flows,
-templates, tags, fields, webhooks, branding, statistics, and the high-level
-`uploadAndRequestSignatures` workflow. Five additional template-management
-routes used by existing integrations and two legacy browser URL helpers are
-retained for compatibility.
+SDK oficial em TypeScript para a [API Assinafy](https://api.assinafy.com.br/v1/docs) — plataforma
+brasileira de assinatura eletrônica de documentos.
 
-See [API coverage](docs/API_COVERAGE.md) for the operation map and
-[compatibility notes](docs/COMPATIBILITY.md) for deployment-specific request
-and response variants.
+Cobre as 93 operações do documento OpenAPI oficial: contas, autenticação, aplicações OAuth 2.1,
+usuários, documentos, assignments, signatários, fluxos do lado do signatário, templates, tags,
+campos, webhooks, identidade visual, estatísticas e o fluxo de alto nível
+`uploadAndRequestSignatures`. Cinco rotas adicionais de gestão de templates usadas por integrações
+existentes e dois helpers de URL de navegador são mantidos por compatibilidade.
 
-## Requirements
+O mapa operação a operação está em [docs/API_COVERAGE.md](docs/API_COVERAGE.md); as variações por
+deploy, em [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
 
-- Node.js 22+ for the built-in `FormData` / `Blob` APIs used by uploads. Packed
-  CJS and ESM imports are tested on 22 (maintenance LTS), 24 (active LTS), and
-  26 (Current); Node 20 reached end-of-life in April 2026 and is unsupported.
-- or Bun 1.4.0 (the version pinned for development and CI)
+## Sumário
 
-## Installation
+Este documento vai da instalação ao fluxo completo de assinatura e, depois, ao detalhe de cada
+recurso. Leia na ordem na primeira vez; use como referência depois.
+
+**Preparação** — [Requisitos](#requisitos) · [Instalação](#instalação) ·
+[Início rápido](#início-rápido) · [Autenticação](#autenticação) ·
+[Aplicações OAuth](#aplicações-oauth) · [Configuração](#configuração)
+([limite de requisições](#limite-de-requisições), [fábricas](#fábricas)) ·
+[Cobertura de endpoints](#cobertura-de-endpoints)
+
+**O fluxo ponta a ponta** — [Ciclo de vida do documento](#ciclo-de-vida-do-documento):
+[envio do PDF](#1-envie-o-pdf) → [signatários](#2-crie-ou-reaproveite-os-signatários-por-e-mail) →
+[orçamento e pedido de assinatura](#3-orce-depois-peça-as-assinaturas) →
+[o lado do signatário](#4-conclua-o-fluxo-do-signatário-por-e-mail) →
+[conclusão e artefatos](#5-acompanhe-a-conclusão-e-baixe-os-artefatos)
+
+**Detalhe por recurso** — [Referência de recursos](#referência-de-recursos):
+[documentos](#documentos) · [signatários](#signatários) · [assignments](#assignments) ·
+[ramos pagos de assinatura](#ramos-pagos-de-assinatura) · [templates](#templates) · [tags](#tags) ·
+[workspaces](#workspaces) · [definições de campo](#definições-de-campo) ·
+[autenticação e chaves de API](#autenticação--gestão-de-chaves-de-api) ·
+[usuário autenticado](#usuário-autenticado) · [webhooks](#webhooks)
+([verificação](#verificação-de-webhooks)) ·
+[endpoints do signatário](#endpoints-do-signatário)
+
+**O restante** — [Helper de alto nível](#helper-de-alto-nível) · [Erros](#erros) ·
+[Ambientes](#ambientes) · [Desenvolvimento](#desenvolvimento) · [Licença](#licença)
+
+## Requisitos
+
+- Node.js 22+ (usa as APIs nativas `FormData` / `Blob` para upload). Os imports CJS e ESM
+  empacotados são testados no 22 (LTS de manutenção), 24 (LTS ativo) e 26 (Current). O Node 20
+  chegou ao fim da vida em abril de 2026 e não é suportado.
+- ou Bun 1.4.0 (versão fixada no desenvolvimento e na CI)
+
+## Instalação
 
 ```bash
 npm install @assinafy/sdk
-# or
+# ou
 bun add @assinafy/sdk
 ```
 
-The package is published to both [npmjs.com](https://www.npmjs.com/package/@assinafy/sdk) and [GitHub Packages](https://github.com/assinafy/typescript-sdk/packages). To install from GitHub Packages, add to your `.npmrc`:
+O pacote é publicado no [npmjs.com](https://www.npmjs.com/package/@assinafy/sdk) e no
+[GitHub Packages](https://github.com/assinafy/typescript-sdk/packages). Para instalar do GitHub
+Packages, adicione ao seu `.npmrc`:
 
 ```
 @assinafy:registry=https://npm.pkg.github.com
 //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
 ```
 
-## Quick start
+## Início rápido
 
 ```ts
 import { AssinafyClient } from '@assinafy/sdk';
@@ -47,140 +79,278 @@ const client = new AssinafyClient({
   baseUrl,
 });
 
-const result = await client.uploadAndRequestSignatures({
-  source: { filePath: './contract.pdf' },
+const resultado = await client.uploadAndRequestSignatures({
+  source: { filePath: './contrato.pdf' },
   signers: [
-    { name: 'John Doe', email: 'john@example.com' },
-    { name: 'Jane Smith', email: 'jane@example.com' },
+    { name: 'João Silva', email: 'joao@exemplo.com.br' },
+    { name: 'Maria Souza', email: 'maria@exemplo.com.br' },
   ],
-  message: 'Please sign this contract',
+  message: 'Por favor, assine este contrato',
 });
 
-console.log('Document ID:', result.document.id);
-console.log('Assignment ID:', result.assignment.id);
+console.log('ID do documento:', resultado.document.id);
+console.log('ID do assignment:', resultado.assignment.id);
 ```
 
-This path uses email verification and notification for every signer. WhatsApp
-and ICP-Brasil certificate signing have separate prerequisites and costs; see
-[Paid signing branches](#paid-signing-branches) before enabling either one.
+Esse caminho usa verificação e notificação por e-mail para todos os signatários. WhatsApp e
+certificado digital ICP-Brasil têm pré-requisitos e custos próprios — veja
+[Ramos pagos de assinatura](#ramos-pagos-de-assinatura) antes de habilitar qualquer um dos dois.
+
+## Autenticação
+
+A API aceita três credenciais. A escolha depende de **em qual workspace** você está agindo.
 
-## Authentication
+| Credencial | Age sobre | Use quando |
+| --- | --- | --- |
+| `apiKey` (`X-Api-Key`) | **Seu próprio** workspace | Você automatiza a sua conta. Recomendada para serviços de back-end. |
+| `token` (`Authorization: Bearer`) | O usuário autenticado | Você obteve uma sessão com `auth.login()`. |
+| Token de acesso OAuth (`Authorization: Bearer`) | O workspace **de outra pessoa**, com autorização dela | Você constrói um app que outras pessoas conectam. Veja [Aplicações OAuth](#aplicações-oauth). |
 
-The API supports two authentication methods. Prefer `apiKey` — it maps to the `X-Api-Key` header recommended by Assinafy for backend services.
+Prefira `apiKey` para integração servidor a servidor — corresponde ao header `X-Api-Key`
+recomendado pela Assinafy.
 
 ```ts
-// Preferred: X-Api-Key header
+// Preferido: header X-Api-Key
 new AssinafyClient({ apiKey: 'k_xxx', accountId: 'acc_xxx' });
 
-// Access token: Authorization: Bearer <token>
+// Token de acesso: Authorization: Bearer <token>
 new AssinafyClient({ token: 'jwt_xxx', accountId: 'acc_xxx' });
 ```
 
-Credentials are optional at construction time. A credentialless client uses a
-separate, auth-free transport for public authentication and signer-access-code
-operations, so an API key or Bearer token is never attached accidentally:
+As credenciais são opcionais na construção. Um cliente sem credenciais usa um transporte separado,
+sem autenticação, para as operações públicas e as que usam código de acesso do signatário — assim
+uma chave de API ou token Bearer nunca é anexada por acidente:
 
 ```ts
-const publicClient = new AssinafyClient({
+const clientePublico = new AssinafyClient({
   baseUrl: 'https://sandbox.assinafy.com.br/v1',
 });
 
-await publicClient.auth.login('me@example.com', 'password');
-await publicClient.documents.getPublic(documentId);
-await publicClient.signerDocuments.self(signerAccessCode);
+await clientePublico.auth.login('eu@exemplo.com.br', 'senha');
+await clientePublico.documents.getPublic(documentId);
+await clientePublico.signerDocuments.self(signerAccessCode);
 ```
 
-Protected methods still require `apiKey` or `token`; the API returns its normal
-`401` response if one is called without credentials.
+Métodos protegidos continuam exigindo `apiKey` ou `token`; sem credencial, a API devolve o `401`
+normal.
 
-Every SDK transport, including public and signer-access-code requests, sends
-`User-Agent: Assinafy-Typescript-SDK/v<VERSION>`, where `<VERSION>` is the
-installed package version. The exact value is also exported as
-`SDK_USER_AGENT` for custom transport checks and observability rules.
+Todos os transportes do SDK — inclusive os públicos e os por código de acesso — enviam
+`User-Agent: Assinafy-Typescript-SDK/v<VERSÃO>`, onde `<VERSÃO>` é a versão instalada do pacote. O
+valor exato também é exportado como `SDK_USER_AGENT`.
 
-## Configuration
+## Aplicações OAuth
 
-| Option          | Type     | Default                                 | Description                                   |
-| --------------- | -------- | --------------------------------------- | --------------------------------------------- |
-| `apiKey`        | string   | —                                       | Preferred credential (sent as `X-Api-Key`).   |
-| `token`         | string   | —                                       | Access token (sent as `Authorization: Bearer`). |
-| `accountId`     | string   | —                                       | Default workspace/account ID.                  |
-| `baseUrl`       | string   | `https://api.assinafy.com.br/v1`        | Absolute HTTP(S) API base without credentials, query, or fragment. |
-| `webhookSecret` | string   | —                                       | Opt-in HMAC secret used by `WebhookVerifier`; see its [contract caveat](docs/COMPATIBILITY.md#webhook-signature-verification-is-not-in-the-openapi-contract). |
-| `timeout`       | number   | `30000`                                 | Request timeout in milliseconds.               |
-| `maxRetries`    | number   | `2`                                     | Auto-retries eligible HTTP 429 responses, honoring `Retry-After`. `0` disables. |
-| `logger`        | `Logger` | no-op                                   | Optional `{debug,info,warn,error}` logger.     |
+Use OAuth quando o seu produto for conectado **pelos usuários dele** aos workspaces **deles** na
+Assinafy, sem que você jamais tenha a senha ou a chave de API dessas pessoas. Para automatizar o seu
+próprio workspace nada disso é necessário — continue com a chave de API.
 
-### Rate limiting
+Registre a aplicação no app da Assinafy em **Configurações → Aplicações OAuth → Nova aplicação**.
+Você define as URIs de redirecionamento (`https://`, sem fragmento, comparadas caractere a
+caractere), as permissões máximas que a aplicação poderá pedir, e se ela é **confidencial** (roda no
+seu servidor e recebe um `client_secret`) ou **pública** (roda no dispositivo do usuário, só PKCE).
+Aplicações não são criadas pela API.
 
-On an HTTP `429`, the client automatically retries up to `maxRetries` times,
-waiting for the server-provided `Retry-After` (or `X-Rate-Limit-Reset`) delay
-before each attempt. Automatic replay is limited to read-safe `GET`, `HEAD`,
-`OPTIONS`, and `DELETE` requests. `GET /sign` is excluded because it records
-that the signer viewed the assignment. Writes are not replayed by default.
-A non-empty `Idempotency-Key` opts a custom request into SDK replay, but it is
-not part of the current Assinafy OpenAPI contract: confirm that the target
-route deduplicates that key server-side first. No other HTTP status is retried.
+O fluxo passa por dois hosts de propósito: a tela de consentimento fica no servidor de autorização
+(`https://auth.assinafy.com.br`), enquanto os endpoints de token, revogação e userinfo ficam nesta
+API. Leia os dois da descoberta em vez de fixá-los no código.
 
-### Factories
+```ts
+import { AssinafyClient, OAuthError } from '@assinafy/sdk';
+
+const client = new AssinafyClient();                  // nenhuma credencial necessária
+
+// 1 — antes de redirecionar o usuário. Guarde a requisição inteira na sessão dele:
+//     `state` e `issuer` provam que o callback é seu, `codeVerifier` completa o
+//     PKCE e `nonce` valida o id_token.
+const requisicao = await client.oauth.createAuthorizationUrl({
+  clientId: process.env.ASSINAFY_CLIENT_ID!,
+  redirectUri: 'https://meuapp.com.br/oauth/callback',
+  scopes: ['documents:read', 'documents:write', 'offline_access'],
+});
+sessao.oauth = requisicao;
+resposta.redirect(requisicao.url);                    // navegação de página inteira
+
+// 2 — em https://meuapp.com.br/oauth/callback
+const { code } = client.oauth.readAuthorizationCallback(query, sessao.oauth);
+const tokens = await client.oauth.exchangeCode({
+  code,
+  codeVerifier: sessao.oauth.codeVerifier,
+  redirectUri: 'https://meuapp.com.br/oauth/callback',
+  clientId: process.env.ASSINAFY_CLIENT_ID!,
+  clientSecret: process.env.ASSINAFY_CLIENT_SECRET,   // só aplicações confidenciais
+});
+// → { access_token, token_type: 'Bearer', expires_in: 3600,
+//     scope: 'documents:read documents:write',
+//     refresh_token?, id_token? }
+
+// 3 — um token vale para EXATAMENTE UM workspace: o que o usuário escolheu.
+const conectado = new AssinafyClient({ token: tokens.access_token });
+const { data } = await conectado.workspaces.list();
+const accountId = data[0]?.id;                        // guarde junto com os tokens
+
+// 4 — renove antes de completar uma hora (exige `offline_access`)
+const renovado = await client.oauth.refreshToken({
+  refreshToken: conexao.refreshToken,
+  clientId: process.env.ASSINAFY_CLIENT_ID!,
+  clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+});
+await conexao.save({ refreshToken: renovado.refresh_token });  // ANTES de usar
+
+// 5 — quando o usuário desconectar
+await client.oauth.revokeToken({
+  token: conexao.refreshToken,
+  tokenTypeHint: 'refresh_token',
+  clientId: process.env.ASSINAFY_CLIENT_ID!,
+  clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+});
+```
+
+Descoberta e identidade, quando precisar:
+
+```ts
+await client.oauth.getProtectedResourceMetadata();    // RFC 9728, na raiz do host da API
+await client.oauth.getAuthorizationServerMetadata();  // RFC 8414, em auth.assinafy.com.br
+await client.oauth.getUserInfo(tokens.access_token);  // claims OIDC; exige `openid`
+```
+
+### Permissões (escopos)
+
+| Escopo | Permite ao seu app |
+| --- | --- |
+| `documents:read` | Ler documentos, seus signatários, assignments e atividades |
+| `documents:write` | Criar documentos e enviá-los para assinatura |
+| `templates:read` | Ler templates |
+| `templates:write` | Criar e alterar templates |
+| `account:read` | Ler perfil, tema e logotipo do workspace |
+| `openid` | Receber um `id_token` identificando o usuário |
+| `profile` | Ler o nome do usuário |
+| `email` | Ler o e-mail do usuário e se está verificado |
+| `offline_access` | Receber um refresh token |
+
+Peça o mínimo: o usuário aprova todos ou nenhum. Leia o `scope` devolvido pelo endpoint de token em
+vez de supor que o pedido foi atendido por inteiro — `offline_access` nunca aparece ali, porque é um
+sinal de requisição, não uma permissão. Faturamento, membros do workspace, credenciais e
+administração nunca são alcançáveis por um token OAuth, quaisquer que sejam seus escopos.
+
+### O que o SDK garante para você
+
+- Um verificador RFC 7636 (S256) e um `state` novos a cada tentativa.
+- `state` comparado em tempo constante e `iss` conferido (RFC 9207) **antes** de qualquer confiança
+  na resposta.
+- O `issuer` do documento RFC 8414 conferido contra a URL de onde ele veio.
+- `redirect_uri` obrigatoriamente `https://` absoluta e sem fragmento.
+- O indicador de recurso RFC 8707 preenchido com a origem da API configurada e mantido idêntico
+  entre a etapa de autorização e a de token.
+
+### Tratamento de falhas
+
+```ts
+try {
+  await conectado.documents.upload({ filePath: './contrato.pdf' });
+} catch (erro) {
+  if (erro instanceof ApiError && erro.challenge?.error === 'insufficient_scope') {
+    // Reconecte pedindo erro.challenge.scope — por exemplo 'documents:write'.
+  }
+}
+```
+
+| Situação | O que você vê | O que fazer |
+| --- | --- | --- |
+| O usuário recusou | `OAuthError` com `error: 'access_denied'` em `readAuthorizationCallback` | Nada; avise o usuário |
+| Código usado, expirado (60 s) ou divergente | `OAuthError` `invalid_grant` | Recomece o fluxo de autorização |
+| Refresh token reutilizado ou expirado | `OAuthError` `invalid_grant` | A conexão inteira acabou; peça para reconectar |
+| `client_id`/segredo errado, app desativado | `OAuthError` `invalid_client` | Corrija a configuração; repetir não resolve |
+| Token expirado ou revogado | `ApiError` `401` | Renove; se falhar, peça para reconectar |
+| Falta de permissão | `ApiError` `403` com `challenge.error === 'insufficient_scope'` | Reconecte pedindo `challenge.scope` |
+| `403` sem challenge | `ApiError` `403` | Outro workspace, ou área que OAuth não alcança |
+
+Refresh tokens **rotacionam**: cada renovação devolve um novo e aposenta o anterior, e reutilizar um
+token aposentado encerra a conexão inteira. Persista o novo valor antes de usar a resposta, trate um
+timeout como "talvez tenha funcionado" — releia o token guardado em vez de repetir às cegas — e
+nunca renove a mesma conexão duas vezes em paralelo. Uma conexão dura 30 dias a partir da aprovação,
+por mais que seja renovada, e os endpoints de autorização e token aceitam 50 requisições por minuto
+por IP.
+
+Assistentes de IA como Claude, Claude Code e ChatGPT se conectam à Assinafy pelas próprias
+configurações de conector; seus usuários não precisam que você registre nada para eles.
+
+## Configuração
+
+| Opção           | Tipo     | Padrão                           | Descrição |
+| --------------- | -------- | -------------------------------- | --------- |
+| `apiKey`        | string   | —                                | Credencial preferida (enviada como `X-Api-Key`). |
+| `token`         | string   | —                                | Token de acesso (enviado como `Authorization: Bearer`). Serve também para tokens OAuth. |
+| `accountId`     | string   | —                                | ID padrão da conta / workspace. |
+| `baseUrl`       | string   | `https://api.assinafy.com.br/v1` | Base absoluta da API, sem credenciais, query ou fragmento. Precisa ser `https`, salvo em loopback. |
+| `webhookSecret` | string   | —                                | Segredo HMAC opcional usado pelo `WebhookVerifier`; veja a [ressalva de contrato](docs/COMPATIBILITY.md#webhook-signature-verification-is-not-in-the-openapi-contract). |
+| `timeout`       | number   | `30000`                          | Timeout da requisição, em milissegundos. |
+| `maxRetries`    | number   | `2`                              | Retenta automaticamente respostas `429` elegíveis, respeitando `Retry-After`. `0` desativa. |
+| `logger`        | `Logger` | no-op                            | Logger opcional `{debug,info,warn,error}`. |
+
+### Limite de requisições
+
+Em um HTTP `429` o cliente retenta até `maxRetries` vezes, aguardando o `Retry-After` (ou
+`X-Rate-Limit-Reset`) devolvido pelo servidor antes de cada tentativa. A repetição automática vale
+apenas para `GET`, `HEAD`, `OPTIONS` e `DELETE`, que são seguros de repetir. `GET /sign` fica de
+fora porque registra que o signatário visualizou o assignment. Escritas não são repetidas por
+padrão. Um `Idempotency-Key` não vazio inscreve uma requisição customizada na repetição do SDK, mas
+ele **não** faz parte do contrato OpenAPI atual: confirme antes que a rota alvo de fato deduplica
+essa chave no servidor. Nenhum outro status é retentado.
+
+### Fábricas
 
 ```ts
-// Positional factory
-const client = AssinafyClient.create('api-key', 'account-id');
+// Fábrica posicional
+const client = AssinafyClient.create('chave-de-api', 'id-da-conta');
 
-// From a plain object (accepts snake_case or camelCase keys)
+// A partir de um objeto simples (aceita chaves snake_case ou camelCase)
 const client = AssinafyClient.fromConfig({
   api_key: process.env.ASSINAFY_API_KEY!,
   account_id: process.env.ASSINAFY_ACCOUNT_ID!,
 });
 ```
 
-## Endpoint coverage
-
-All 89 operations documented at https://api.assinafy.com.br/v1/docs are
-covered. The table below is the resource-level summary; the detailed operation
-ledger is in [docs/API_COVERAGE.md](docs/API_COVERAGE.md).
-
-| Resource              | Endpoints                                                                                                                                                                                                                                          |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client.documents`    | list, **search**, upload, details, get, **rename**, activities, waitUntilReady, download, thumbnail, downloadPage, statuses, delete, verify, createFromTemplate, estimateCostFromTemplate, getPublic, sendToken, listTags, replaceTags, addTags, detachTag, isFullySigned, getSigningProgress |
-| `client.signers`      | create, get, list, update, delete, findByEmail                                                                                                                                                                                                     |
-| `client.assignments`  | **list**, create, estimateCost, resetExpiration, resendNotification, estimateResendCost, listWhatsAppNotifications                                                                                                                                  |
-| `client.templates`    | **create**, list, get, **update**, **delete**, downloadPage                                                                                                                                                                                        |
-| `client.tags`         | list, create, update, delete                                                                                                                                                                                                                       |
-| `client.workspaces`   | create, list, get, update, delete, getTheme, downloadLogo, uploadLogo, deleteLogo, getStats                                                                                                                                                        |
-| `client.webhooks`     | register, get, inactivate, listEventTypes, listDispatches, retryDispatch                                                                                                                                                                           |
-| `client.fields`       | create, list, get, update, delete, validate, validateMultiple, listTypes                                                                                                                                                                           |
-| `client.auth`         | getSocialLoginUrl, getSocialLoginCallbackUrl, login, socialLogin, linkSocialLogin, createApiKey, getApiKey, deleteApiKey, changePassword, requestPasswordReset, resetPassword                                                                      |
-| `client.users`        | getCurrent, getStats, getNotificationPreferences, updateNotificationPreferences                                                                                                                                                                  |
-| `client.signerDocuments` | getCurrent, list, **search**, download, signMultiple, declineMultiple, self, acceptTerms, verifyEmail, confirmData, uploadSignature, downloadSignature, getAssignment, sign, decline                                                            |
-| `client.webhookVerifier` | verify, extractEvent, getEventType, getEventData                                                                                                                                                                                                |
-
-Every HTTP wrapper has TypeScript-checked request/response shapes and
-method-level JSDoc covering the wire payload, return shape, validation,
-relevant API errors, and a copyable example. Reusable and OpenAPI schema-level
-payloads are exported as named types; small method-local option bags remain
-inline in the generated declarations. Editors expose the reference on hover,
-and declaration files ship with the package. The coverage ledger links those
-typed methods back to each upstream operation without duplicating the schema.
-
-## Document lifecycle
-
-The normal integration has an account-owner phase, a signer phase, and a final
-artifact phase. The example below keeps every signer on email and uses a
-`virtual` assignment, so no page coordinates or paid notification channel are
-required.
-
-### 1. Upload the PDF
+## Cobertura de endpoints
+
+As 93 operações documentadas em https://api.assinafy.com.br/v1/docs estão cobertas. A tabela abaixo
+é o resumo por recurso; o mapa detalhado por operação está em
+[docs/API_COVERAGE.md](docs/API_COVERAGE.md).
+
+| Recurso | Endpoints |
+| --- | --- |
+| `client.documents` | list, search, upload, details, get, rename, activities, waitUntilReady, download, thumbnail, downloadPage, statuses, delete, verify, createFromTemplate, estimateCostFromTemplate, getPublic, sendToken, listTags, replaceTags, addTags, detachTag, isFullySigned, getSigningProgress |
+| `client.signers` | create, get, list, update, delete, findByEmail |
+| `client.assignments` | list, create, estimateCost, resetExpiration, resendNotification, estimateResendCost, listWhatsAppNotifications |
+| `client.templates` | create, list, get, update, delete, downloadPage |
+| `client.tags` | list, create, update, delete |
+| `client.workspaces` | create, list, get, update, delete, getTheme, downloadLogo, uploadLogo, deleteLogo, getStats |
+| `client.webhooks` | register, get, inactivate, listEventTypes, listDispatches, retryDispatch |
+| `client.fields` | create, list, get, update, delete, validate, validateMultiple, listTypes |
+| `client.oauth` | **getProtectedResourceMetadata**, **getAuthorizationServerMetadata**, **createAuthorizationUrl**, **readAuthorizationCallback**, **exchangeCode**, **refreshToken**, **revokeToken**, **getUserInfo** |
+| `client.auth` | getSocialLoginUrl, getSocialLoginCallbackUrl, login, socialLogin, linkSocialLogin, createApiKey, getApiKey, deleteApiKey, changePassword, requestPasswordReset, resetPassword |
+| `client.users` | getCurrent, getStats, getNotificationPreferences, updateNotificationPreferences |
+| `client.signerDocuments` | getCurrent, list, search, download, signMultiple, declineMultiple, self, acceptTerms, verifyEmail, confirmData, uploadSignature, downloadSignature, getAssignment, sign, decline |
+| `client.webhookVerifier` | verify, extractEvent, getEventType, getEventData |
+
+Todo wrapper HTTP tem tipos de requisição e resposta verificados pelo TypeScript e JSDoc por método,
+cobrindo o payload de rede, o formato de retorno, validação, erros relevantes da API e um exemplo
+copiável. As declarações acompanham o pacote.
+
+## Ciclo de vida do documento
+
+A integração normal tem uma fase do dono da conta, uma fase do signatário e uma fase final de
+artefatos. O exemplo abaixo mantém todos os signatários no e-mail e usa um assignment `virtual`,
+então não exige coordenadas de página nem canal pago de notificação.
+
+### 1. Envie o PDF
 
 ```ts
-const uploaded = await client.documents.upload({ filePath: './contract.pdf' });
+const enviado = await client.documents.upload({ filePath: './contrato.pdf' });
 ```
 
-The official multipart body contains the `file` part. The SDK also supports a
-display-name override (used as that file part's filename) and an optional JSON
-`metadata` part for deployments that accept it. A successful response is
-`IDocumentUploadResponse`:
+O corpo multipart oficial contém a parte `file`. O SDK também aceita um nome de exibição (usado como
+nome de arquivo dessa parte) e uma parte JSON `metadata` opcional, para deploys que a aceitem. A
+resposta de sucesso é `IDocumentUploadResponse`:
 
 ```ts
 {
@@ -210,37 +380,36 @@ display-name override (used as that file part's filename) and an optional JSON
 }
 ```
 
-`DocumentStatus` covers `uploading`, `uploaded`, `metadata_processing`,
-`metadata_ready`, `pending_signature`, `expired`, `certificating`,
-`certificated`, `rejected_by_signer`, `rejected_by_user`, and `failed`.
+`DocumentStatus` cobre `uploading`, `uploaded`, `metadata_processing`, `metadata_ready`,
+`pending_signature`, `expired`, `certificating`, `certificated`, `rejected_by_signer`,
+`rejected_by_user` e `failed`.
 
-Uploads must be PDFs, at most 25 MB and at most 2,000 pages. The SDK checks the
-extension, size, and `%PDF-` header before sending. A new upload can have an
-empty `pages` array until metadata processing finishes. Wait before creating a
-`collect` assignment because its fields refer to rendered page IDs; a
-`virtual` assignment may be created immediately.
+O envio precisa ser um PDF de no máximo 25 MB e 2.000 páginas. O SDK confere extensão, tamanho e o
+cabeçalho `%PDF-` antes de enviar. Um upload novo pode ter `pages` vazio até o processamento de
+metadados terminar. Espere antes de criar um assignment `collect`, porque seus campos referenciam
+IDs de páginas renderizadas; um assignment `virtual` pode ser criado imediatamente.
 
 ```ts
-const prepared = await client.documents.waitUntilReady(uploaded.id, {
+const preparado = await client.documents.waitUntilReady(enviado.id, {
   maxWaitMs: 30_000,
   pollIntervalMs: 2_000,
 });
 ```
 
-### 2. Create or reuse the email signers
+### 2. Crie ou reaproveite os signatários por e-mail
 
 ```ts
-const signerA = await client.signers.create({
-  full_name: 'John Doe',
-  email: 'john@example.com',
+const signatarioA = await client.signers.create({
+  full_name: 'João Silva',
+  email: 'joao@exemplo.com.br',
 });
-const signerB = await client.signers.create({
-  full_name: 'Jane Smith',
-  email: 'jane@example.com',
+const signatarioB = await client.signers.create({
+  full_name: 'Maria Souza',
+  email: 'maria@exemplo.com.br',
 });
 ```
 
-The wire body is `{ full_name, email }`. Each response is an `ISigner`:
+O corpo de rede é `{ full_name, email }`. Cada resposta é um `ISigner`:
 
 ```ts
 {
@@ -249,35 +418,34 @@ The wire body is `{ full_name, email }`. Each response is an `ISigner`:
   full_name: string;
   email: string | null;
   whatsapp_phone_number?: string | null;
-  cpf?: string | null;                // compatibility type; not echoed by the API
+  cpf?: string | null;                // tipo de compatibilidade; a API não devolve
   has_accepted_terms?: boolean;
-  has_signature?: boolean;            // signer-self response only
-  has_initial?: boolean;              // signer-self response only
-  is_signature_reusable?: boolean;    // signer-self response only
+  has_signature?: boolean;            // só na resposta de signers/self
+  has_initial?: boolean;              // só na resposta de signers/self
+  is_signature_reusable?: boolean;    // só na resposta de signers/self
   metadata?: Record<string, unknown>;
 }
 ```
 
-When an email is present, `signers.create()` first looks up that email in the
-workspace and reuses the matching signer; a name-only or phone-only request
-always creates a new signer.
+Quando há e-mail, `signers.create()` primeiro procura esse endereço no workspace e reaproveita o
+signatário correspondente; uma requisição só com nome ou só com telefone sempre cria um novo.
 
-### 3. Price, then request signatures
+### 3. Orce, depois peça as assinaturas
 
-Cost estimation takes channel descriptors, not signer IDs:
+A estimativa de custo recebe descritores de canal, não IDs de signatário:
 
 ```ts
-const estimate = await client.assignments.estimateCost(uploaded.id, {
+const estimativa = await client.assignments.estimateCost(enviado.id, {
   method: 'virtual',
-  signers: [{}, {}], // `{}` selects Email for each signer
+  signers: [{}, {}], // `{}` seleciona Email para cada signatário
 });
 
-if (!estimate.has_sufficient_resources) {
-  throw new Error(estimate.blocking_reason ?? estimate.message ?? 'Insufficient resources');
+if (!estimativa.has_sufficient_resources) {
+  throw new Error(estimativa.blocking_reason ?? estimativa.message ?? 'Recursos insuficientes');
 }
 ```
 
-The response is `ICostEstimate`:
+A resposta é `ICostEstimate`:
 
 ```ts
 {
@@ -295,21 +463,21 @@ The response is `ICostEstimate`:
 }
 ```
 
-Create the email assignment only after accepting that estimate:
+Crie o assignment por e-mail só depois de aceitar essa estimativa:
 
 ```ts
-const assignment = await client.assignments.create(uploaded.id, {
+const assignment = await client.assignments.create(enviado.id, {
   method: 'virtual',
   signers: [
-    { id: signerA.id, verification_method: 'Email', notification_methods: ['Email'] },
-    { id: signerB.id, verification_method: 'Email', notification_methods: ['Email'] },
+    { id: signatarioA.id, verification_method: 'Email', notification_methods: ['Email'] },
+    { id: signatarioB.id, verification_method: 'Email', notification_methods: ['Email'] },
   ],
-  message: 'Please review and sign',
+  message: 'Por favor, revise e assine',
   expires_at: '2027-12-31T23:59:00Z',
 });
 ```
 
-The request returns an `IAssignment`:
+A requisição devolve um `IAssignment`:
 
 ```ts
 {
@@ -332,240 +500,232 @@ The request returns an `IAssignment`:
 }
 ```
 
-The URLs and delivered messages contain signer credentials; treat them as
-secrets.
+As URLs e as mensagens entregues contêm credenciais do signatário; trate-as como segredo.
 
-### 4. Complete the email signer flow
+### 4. Conclua o fluxo do signatário por e-mail
 
-Assinafy sends each signer a link containing their access code and sends the
-one-time verification code through the selected channel. Neither value is
-returned as a standalone owner-side API field. A custom signer portal must
-obtain both values from the signer-delivery flow; do not manufacture them or
-log them.
+A Assinafy envia a cada signatário um link com o código de acesso dele e manda o código de
+verificação de uso único pelo canal escolhido. Nenhum dos dois valores é devolvido como campo
+autônomo do lado do dono da conta. Um portal de assinatura próprio precisa obter os dois pelo fluxo
+de entrega ao signatário; não os fabrique nem os registre em log.
 
 ```ts
-// Signer-side client: no account API credential is needed or sent.
-const signerClient = new AssinafyClient({
-  baseUrl,
-});
+// Cliente do signatário: nenhuma credencial da conta é necessária nem enviada.
+const clienteSignatario = new AssinafyClient({ baseUrl });
 
-const self = await signerClient.signerDocuments.self(accessCode); // ISignerSelf
+const self = await clienteSignatario.signerDocuments.self(accessCode); // ISignerSelf
 
 // Query: signer-access-code=<accessCode>
-// Body: { 'verification-code': '<six-digit code>' }
-await signerClient.signerDocuments.verifyEmail({
+// Corpo: { 'verification-code': '<código de seis dígitos>' }
+await clienteSignatario.signerDocuments.verifyEmail({
   signerAccessCode: accessCode,
   verificationCode,
 }); // Promise<void>
 
-const confirmed = await signerClient.signerDocuments.confirmData(
-  uploaded.id,
+const confirmado = await clienteSignatario.signerDocuments.confirmData(
+  enviado.id,
   accessCode,
   { full_name: self.full_name, email: self.email ?? undefined },
 ); // ISigner
 
-const signable = await signerClient.signerDocuments.getAssignment(accessCode, true);
-// `getAssignment` returns IDocumentDetailsResponse and records that the signer
-// viewed the assignment. Do not issue it merely as a health check.
+const assinavel = await clienteSignatario.signerDocuments.getAssignment(accessCode, true);
+// `getAssignment` devolve IDocumentDetailsResponse e registra que o signatário
+// visualizou o assignment. Não use como simples healthcheck.
 
-await signerClient.signerDocuments.signMultiple([signable.id], accessCode);
-// Wire body: { document_ids: [signable.id] }; acknowledgement has no data.
+await clienteSignatario.signerDocuments.signMultiple([assinavel.id], accessCode);
+// Corpo de rede: { document_ids: [assinavel.id] }; o reconhecimento não traz dados.
 ```
 
-Repeat this phase separately for each signer with that signer's own access code
-and one-time code. The two signers in this example share the default step and
-can sign in parallel.
+Repita esta fase separadamente para cada signatário, com o código de acesso e o código de uso único
+dele. Os dois signatários deste exemplo compartilham o passo padrão e podem assinar em paralelo.
 
-`signMultiple` is only for `virtual` assignments. For `collect`, read
-`signable.assignment.items`, then call `sign(documentId, assignmentId,
-accessCode, entries)` with a non-empty array of
-`{ itemId, fieldId, pageId, value }`. A virtual signer must confirm their data
-before signing. A `DigitalCertificate` signer cannot call `sign`; that branch
-uses Assinafy's certificate-start and certificate-complete flow, which is not
-part of this SDK's current 89-operation surface.
+`signMultiple` serve apenas a assignments `virtual`. Para `collect`, leia `assinavel.assignment.items`
+e chame `sign(documentId, assignmentId, accessCode, entries)` com um array não vazio de
+`{ itemId, fieldId, pageId, value }`. Um signatário virtual precisa confirmar os dados antes de
+assinar. Um signatário `DigitalCertificate` não pode usar `sign`; esse ramo passa pelo fluxo de
+certificado da Assinafy, descrito em
+[Certificado digital ICP-Brasil](#certificado-digital-icp-brasil).
 
-### 5. Observe completion and download artifacts
+### 5. Acompanhe a conclusão e baixe os artefatos
 
-Subscribe to `document_ready` for event-driven completion, or fetch
-`documents.details(documentId)` until `status === 'certificated'`. Webhook
-deliveries can repeat, so use their numeric `id` as an
-idempotency key. Once complete:
+Assine o evento `document_ready` para saber da conclusão por evento, ou consulte
+`documents.details(documentId)` até `status === 'certificated'`. As entregas de webhook podem se
+repetir — use o `id` numérico como chave de idempotência. Concluído:
 
 ```ts
-const finalDocument = await client.documents.details(uploaded.id);
-const signedPdf = await client.documents.download(uploaded.id, 'certificated');
-const certificatePage = await client.documents.download(uploaded.id, 'certificate-page');
-const bundleZip = await client.documents.download(uploaded.id, 'bundle');
+const documentoFinal = await client.documents.details(enviado.id);
+const pdfAssinado = await client.documents.download(enviado.id, 'certificated');
+const paginaCertificado = await client.documents.download(enviado.id, 'certificate-page');
+const pacoteZip = await client.documents.download(enviado.id, 'bundle');
 
-// Validate an Assinafy signature hash when your workflow has extracted it.
-const validation = await client.documents.verify(documentSignatureHash);
+// Valide um hash de assinatura Assinafy que o seu fluxo tenha extraído.
+const validacao = await client.documents.verify(documentSignatureHash);
 ```
 
-`original`, `certificated`, and `certificate-page` are PDFs. `bundle` is a ZIP
-containing those three artifacts and also `pades` when the document had an
-ICP-Brasil certificate signer. The `pades` PDF exists only for documents that
-had certificate signers. An artifact can return `404` before generation has
-finished. `decline_reason` is included in document details only when the access
-token belongs to the document creator.
+`original`, `certificated` e `certificate-page` são PDFs. `bundle` é um ZIP com esses três artefatos
+e também o `pades` quando o documento teve signatário por certificado ICP-Brasil. O PDF `pades`
+existe apenas nesses documentos. Um artefato pode devolver `404` antes de terminar de ser gerado.
+`decline_reason` só aparece nos detalhes do documento quando o token pertence a quem criou o
+documento.
 
-## Resource reference
+## Referência de recursos
 
-Most account-scoped methods accept an optional `accountId` that overrides the
-client default. Workspace `get`, `update`, `delete`, branding, and statistics
-methods always require an explicit account ID.
+A maioria dos métodos com escopo de conta aceita um `accountId` opcional que sobrepõe o padrão do
+cliente. Os métodos de workspace `get`, `update`, `delete`, identidade visual e estatísticas sempre
+exigem um ID de conta explícito.
 
-### Documents
+### Documentos
 
 ```ts
-// Upload from a file path (recommended)
+// Envio a partir de um caminho de arquivo (recomendado)
 const doc = await client.documents.upload(
-  { filePath: './contract.pdf' },
-  { name: 'Service agreement', metadata: { type: 'service' } },
+  { filePath: './contrato.pdf' },
+  { name: 'Contrato de prestação', metadata: { tipo: 'servico' } },
 );
-// `name` and `metadata` are compatibility multipart parts outside the published
-// file-only request schema.
-// `name` is optional and defaults to the file's own name. The API derives the
-// display name from the uploaded filename and appends `.pdf` when absent, so
-// the document above is stored as 'Service agreement.pdf'. Accents are
-// transliterated by the API ('Contrato de Serviço' → 'Contrato de Servico.pdf').
+// `name` e `metadata` são partes multipart de compatibilidade, fora do schema
+// oficial (que só define o arquivo). `name` é opcional e assume o nome do
+// arquivo. A API deriva o nome de exibição do arquivo enviado e acrescenta
+// `.pdf` quando falta, então o documento acima é salvo como
+// 'Contrato de prestação.pdf'. A API translitera acentos
+// ('Contrato de Serviço' → 'Contrato de Servico.pdf').
 // → {
 //   resource: 'document', id: '1031…', account_id: '102d…', template_id: null,
-//   name: 'Service agreement.pdf', status: 'uploaded',
+//   name: 'Contrato de prestacao.pdf', status: 'uploaded',
 //   artifacts: { original: 'https://…/download/original' },
 //   signing_url: 'https://app…/sign/1031…',
-//   pages: [],                 // populated once status reaches `metadata_ready`
+//   pages: [],                 // preenchido quando o status chega a `metadata_ready`
 //   tags: [], is_closed: false, created_at: '2026-…', updated_at: '2026-…'
 // }
 
-// …or from a Buffer already in memory
-await client.documents.upload({ buffer, fileName: 'contract.pdf' });
+// …ou a partir de um Buffer já em memória
+await client.documents.upload({ buffer, fileName: 'contrato.pdf' });
 
-// List → { data: IDocumentListItem[], meta?: { current_page, per_page, total, last_page } }
-const { data, meta } = await client.documents.list({ page: 1, per_page: 20, sort: 'updated_at' });
+// Listagem → { data: IDocumentListItem[], meta?: { current_page, per_page, total, last_page } }
+const { data, meta } = await client.documents.list({ page: 1, 'per-page': 20, sort: 'updated_at' });
 
-// Search is the lightweight alternative to list: same item shape, but the API
-// skips the expanded `assignment`/`pages`. Prefer it for name lookups.
-const hits = await client.documents.search({ search: 'agreement', status: 'pending_signature', 'per-page': 20 });
+// `search` é a alternativa leve a `list`: mesmo formato de item, mas a API não
+// expande `assignment`/`pages`. Prefira-a para buscar por nome.
+const achados = await client.documents.search({ search: 'contrato', status: 'pending_signature', 'per-page': 20 });
 
 await client.documents.details(doc.id);
 await client.documents.activities(doc.id);
 await client.documents.waitUntilReady(doc.id, { maxWaitMs: 30_000 });
 
-// Rename. The API rejects this with 400 while the document is still in
-// `metadata_processing`, so await waitUntilReady() first on a fresh upload.
-// (Passing `name` to upload() avoids both the round-trip and the race.)
-await client.documents.rename(doc.id, 'Signed service agreement.pdf');
+// Renomear. A API responde 400 enquanto o documento está em
+// `metadata_processing`, então chame waitUntilReady() antes em um upload novo.
+// (Passar `name` ao upload() evita tanto a ida extra quanto a corrida.)
+await client.documents.rename(doc.id, 'Contrato assinado.pdf');
 
-await client.documents.download(doc.id, 'certificated');   // signed PDF
+await client.documents.download(doc.id, 'certificated');    // PDF assinado
 await client.documents.download(doc.id, 'certificate-page');
 await client.documents.download(doc.id, 'bundle');          // ZIP
-// `pades` exists only when at least one signer used DigitalCertificate.
+// `pades` existe apenas quando algum signatário usou DigitalCertificate.
 await client.documents.download(doc.id, 'pades');
 await client.documents.thumbnail(doc.id);
 await client.documents.downloadPage(doc.id, pageId);
 
-await client.documents.statuses();                          // list every status code + deletable flag
+await client.documents.statuses();                          // todos os códigos de status + flag deletable
 await client.documents.isFullySigned(doc.id);
 await client.documents.getSigningProgress(doc.id);
 await client.documents.delete(doc.id);
 
-// Verify a signed document by its Assinafy signature hash
+// Verifique um documento assinado pelo hash de assinatura Assinafy
 await client.documents.verify('FE32EDDADE7CBDDCBB934E7402047450B0E59C02');
 
-// Public endpoints (no auth)
+// Endpoints públicos (sem autenticação)
 await client.documents.getPublic(doc.id);
-// Official request body: { email: 'jane@example.com' }
-await client.documents.sendToken(doc.id, 'jane@example.com');
+// Corpo oficial: { email: 'maria@exemplo.com.br' }
+await client.documents.sendToken(doc.id, 'maria@exemplo.com.br');
 
-// Explicit compatibility overload for older deployments:
+// Sobrecarga explícita de compatibilidade para deploys mais antigos:
 // { recipient: '+5548999990000', channel: 'whatsapp' }
 await client.documents.sendToken(doc.id, '+5548999990000', 'whatsapp');
 
-// The current OpenAPI contract requires existing tag IDs.
-const contractsTag = await client.tags.create({ name: 'Contracts' });
-const quarterTag = await client.tags.create({ name: '2026-Q1' });
-const urgentTag = await client.tags.create({ name: 'Urgent' });
+// O contrato OpenAPI atual exige IDs de tags já existentes.
+const tagContratos = await client.tags.create({ name: 'Contratos' });
+const tagTrimestre = await client.tags.create({ name: '2026-T1' });
+const tagUrgente = await client.tags.create({ name: 'Urgente' });
 await client.documents.listTags(doc.id);
-await client.documents.replaceTags(doc.id, [contractsTag.id, quarterTag.id]); // [] detaches all
-await client.documents.addTags(doc.id, [urgentTag.id]);                         // append
-await client.documents.detachTag(doc.id, urgentTag.id); // → { detached: true }
+await client.documents.replaceTags(doc.id, [tagContratos.id, tagTrimestre.id]); // [] desanexa tudo
+await client.documents.addTags(doc.id, [tagUrgente.id]);                          // acrescenta
+await client.documents.detachTag(doc.id, tagUrgente.id); // → { detached: true }
 ```
 
-Uploads are validated locally: only `.pdf` files up to 25 MB whose bytes begin
-with the PDF magic header (`%PDF-`) are accepted. The API also limits documents
-to 2,000 pages.
+Os uploads são validados localmente: só arquivos `.pdf` de até 25 MB cujos bytes começam com o
+cabeçalho mágico (`%PDF-`) são aceitos. A API também limita o documento a 2.000 páginas.
 
-Page and artifact URLs embedded in JSON responses still require the same
-account authentication as their download operations. Prefer
-`documents.downloadPage()` and `documents.download()` so the SDK applies the
-credential and returns a `Buffer`. `bundle` contains `original`, `certificated`,
-and `certificate-page`, plus `pades` when available.
+As URLs de página e de artefato embutidas nas respostas JSON continuam exigindo a mesma autenticação
+de conta das operações de download. Prefira `documents.downloadPage()` e `documents.download()`,
+que aplicam a credencial e devolvem um `Buffer`. `bundle` contém `original`, `certificated` e
+`certificate-page`, mais o `pades` quando existir.
 
-List endpoints return `{ data, meta }` where `meta` is populated from the `X-Pagination-*` headers returned by the API.
+As listagens devolvem `{ data, meta }`, com `meta` preenchido a partir dos headers
+`X-Pagination-*`. Dois comportamentos da API merecem atenção porque são silenciosos, não erros:
 
-### Signers
+- Só o `per-page` com hífen é lido. `per_page` é aceito e ignorado, caindo para 20 linhas — por isso
+  o SDK reescreve `per_page` como `per-page` em toda listagem, e um `per-page` explícito vence
+  quando os dois são enviados.
+- `per-page` é limitado a **50**. Pedir 100 devolve 50 linhas com `200`. A constante exportada
+  `MAX_LIST_PAGE_SIZE` é esse teto; pagine com `page` em vez de pedir páginas maiores, e confie no
+  `meta.per_page` mais do que no valor pedido.
+
+### Signatários
 
 ```ts
 await client.signers.create({
-  full_name: 'John Doe',
-  email: 'john@example.com',
-  cpf: '123.456.789-00', // legacy compatibility input; non-digits are stripped
+  full_name: 'João Silva',
+  email: 'joao@exemplo.com.br',
+  cpf: '123.456.789-00', // entrada de compatibilidade; não dígitos são removidos
 });
-// → { id: '19e6…', full_name: 'John Doe', email: 'john@example.com',
+// → { id: '19e6…', full_name: 'João Silva', email: 'joao@exemplo.com.br',
 //     whatsapp_phone_number: null, has_accepted_terms: false }
-// (note: `cpf` is accepted on input but never echoed back by the API)
-
-// Both contacts are optional. A name-only signer cannot be notified until a
-// contact is added.
-await client.signers.create({ full_name: 'Contact Pending' });
+// (observação: `cpf` é aceito na entrada, mas a API nunca o devolve)
 
-await client.signers.create({
-  full_name: 'Jane Doe',
-  email: 'jane@example.com',
-});
+// Ambos os contatos são opcionais. Um signatário só com nome não pode ser
+// notificado até que um contato seja adicionado.
+await client.signers.create({ full_name: 'Contato Pendente' });
 
 await client.signers.get(signerId);
-await client.signers.list({ page: 1, per_page: 50, search: 'john' });
+await client.signers.list({ page: 1, 'per-page': 50, search: 'joao' });
 await client.signers.update(signerId, {
-  full_name: 'Johnny Doe',
-  government_id: '390.533.447-05', // official update field; sent as digits
+  full_name: 'João da Silva',
+  government_id: '390.533.447-05', // campo oficial de atualização; enviado só com dígitos
 });
 await client.signers.delete(signerId);
 
-const existing = await client.signers.findByEmail('john@example.com');
+const existente = await client.signers.findByEmail('joao@exemplo.com.br');
 ```
 
-When an `email` is supplied, `signers.create()` is idempotent by email: it
-reuses an existing signer when the same email is already present in the
-workspace. Signers without email are always created fresh. See
-[Paid signing branches](#paid-signing-branches) for phone-only signers.
+Quando um `email` é informado, `signers.create()` é idempotente por e-mail: reaproveita o signatário
+existente com o mesmo endereço no workspace. Signatários sem e-mail são sempre criados do zero. Veja
+[Ramos pagos de assinatura](#ramos-pagos-de-assinatura) para signatários só com telefone.
 
 ### Assignments
 
 ```ts
-// List every assignment in the workspace.
+// Lista todos os assignments do workspace.
 // → { data: IAssignment[], meta?: { current_page, per_page, total, last_page } }
 const { data, meta } = await client.assignments.list({ page: 1, 'per-page': 20 });
 
-// Signers may be ids or objects — the SDK normalises to the API shape.
+// Signatários podem ser ids ou objetos — o SDK normaliza para o formato da API.
 await client.assignments.create(documentId, {
   method: 'virtual',
   signers: ['signer-1', 'signer-2'],
-  message: 'Please review and sign',
+  message: 'Por favor, revise e assine',
   expires_at: '2027-12-31T23:59:00Z',
-  copy_receivers: ['copy-recipient-signer-id'],
+  copy_receivers: ['id-do-signatario-em-copia'],
 });
 
-// Sequential signing: `step` controls signing order (parallel within a step).
+// Assinatura sequencial: `step` controla a ordem (paralelo dentro de um passo).
 await client.assignments.create(documentId, {
   method: 'virtual',
   signers: [
     { id: 'signer-1', step: 1 },
-    { id: 'signer-2', step: 2 }, // notified only after step 1 finishes
+    { id: 'signer-2', step: 2 }, // notificado só depois que o passo 1 terminar
   ],
 });
 
-// Collect fields use 150-DPI page-image pixels measured from the upper-left.
+// Campos de `collect` usam pixels da imagem de página a 150 DPI, medidos do canto superior esquerdo.
 await client.assignments.create(documentId, {
   method: 'collect',
   signers: [{ id: signerId }],
@@ -582,8 +742,8 @@ await client.assignments.create(documentId, {
   }],
 });
 
-// Estimate cost (the endpoint prices channel descriptors, not signer IDs) → ICostEstimate
-await client.assignments.estimateCost(documentId, { signers: [{}] }); // default Email
+// Estimativa de custo (o endpoint orça descritores de canal, não IDs) → ICostEstimate
+await client.assignments.estimateCost(documentId, { signers: [{}] }); // Email padrão
 // → {
 //   documents: 1, credits: 0, needs_extra_document: false, extra_document_cost: 0,
 //   total_credits: 0, breakdown: [], document_balance: 67, credit_balance: 0,
@@ -591,88 +751,108 @@ await client.assignments.estimateCost(documentId, { signers: [{}] }); // default
 // }
 
 await client.assignments.resetExpiration(documentId, assignmentId, '2027-06-30T00:00:00Z');
-// Compatibility only: the published request requires a date-time string.
-// Confirm target support before using `null` to clear an expiration.
+// Só compatibilidade: a requisição publicada exige uma data-hora.
+// Confirme o suporte do destino antes de usar `null` para limpar a expiração.
 await client.assignments.resetExpiration(documentId, assignmentId, null);
 
 await client.assignments.resendNotification(documentId, assignmentId, signerId);
 // → { is_sent: true, document_id: '…', signer_id: '…' }
 
-const resendCost = await client.assignments.estimateResendCost(documentId, assignmentId, signerId);
-// Official response: ICostEstimate. Older deployments can return the compact
-// IResendCostEstimate branch with `total` and `has_sufficient_credits`; narrow
-// with `'total_credits' in resendCost` before reading branch-specific fields.
+const custoReenvio = await client.assignments.estimateResendCost(documentId, assignmentId, signerId);
+// Resposta oficial: ICostEstimate. Deploys antigos podem devolver o ramo compacto
+// IResendCostEstimate, com `total` e `has_sufficient_credits`; estreite com
+// `'total_credits' in custoReenvio` antes de ler campos específicos de um ramo.
 ```
 
-The `create` response is an `IAssignment`: `{ id, method, signers: [...],
+A resposta de `create` é um `IAssignment`: `{ id, method, signers: [...],
 items: [{ display_settings, ... }], signing_urls: [{ signer_id, url }], … }`.
 
-For backwards compatibility, the SDK also accepts legacy `signer_ids` and `signerIds` payloads and rewrites them to the current `signers: [{ id }]` format expected by the API.
+Por compatibilidade, o SDK também aceita os payloads antigos `signer_ids` e `signerIds` e os
+reescreve no formato atual `signers: [{ id }]` esperado pela API.
 
-**Cancelling a signature request.** Assinafy has no workspace-side "cancel" endpoint. To stop a pending request either delete the document (when its status is deletable) or have the signer decline:
+**Cancelar um pedido de assinatura.** A Assinafy não tem endpoint de cancelamento do lado do
+workspace. Para interromper um pedido pendente, apague o documento (quando o status permitir) ou
+peça que o signatário recuse:
 
 ```ts
-await client.documents.delete(documentId);                                  // workspace-side
-await client.signerDocuments.decline(documentId, assignmentId, accessCode, 'No longer needed'); // signer-side
+await client.documents.delete(documentId);                                       // lado do workspace
+await client.signerDocuments.decline(documentId, assignmentId, accessCode, 'Não é mais necessário'); // lado do signatário
 ```
 
-### Paid signing branches
+### Ramos pagos de assinatura
 
-Keep the email flow as the default. Enable either branch below only after the
-workspace has the required plan or feature and the returned cost estimate is
-acceptable.
+Mantenha o fluxo por e-mail como padrão. Habilite os ramos abaixo apenas depois de confirmar que a
+conta tem o plano ou recurso necessário e que a estimativa de custo é aceitável.
 
-#### WhatsApp verification and notification
+O método de verificação e o de notificação são **acoplados**: envie um, os dois ou nenhum — o lado
+que faltar é inferido. Sem nenhum dos dois, ambos assumem `Email`.
 
-WhatsApp is available only on paid subscriptions and costs 0.45 credit per
-notification. Create a phone-only signer or add a phone to an existing signer,
-then request the `Whatsapp` channel explicitly:
+| Verificação | Como o signatário prova quem é | Notificação permitida | Custo por signatário |
+| --- | --- | --- | --- |
+| `Email` *(padrão)* | Código de uso único (OTP) por e-mail | `Email` | Gratuito |
+| `Whatsapp` | Código de uso único (OTP) por WhatsApp | `Whatsapp` | 0,45 crédito (a notificação), só em planos pagos |
+| `DigitalCertificate` | O signatário assina com o **próprio certificado ICP-Brasil — A1 ou A3 —** pela extensão Web PKI, gerando uma assinatura **PAdES qualificada** | `Email` **ou** `Whatsapp` | 2 créditos + a notificação |
+
+Apenas um método de notificação por signatário. O SDK recusa uma combinação inválida antes da
+requisição; a API responderia `400`.
+
+#### Verificação e notificação por WhatsApp
+
+Disponível apenas em assinaturas pagas, a 0,45 crédito por notificação. Crie um signatário só com
+telefone (ou adicione telefone a um existente) e peça o canal `Whatsapp` explicitamente:
 
 ```ts
-const phoneSigner = await client.signers.create({
-  full_name: 'Mobile Signer',
+const signatarioTelefone = await client.signers.create({
+  full_name: 'Signatário Mobile',
   whatsapp_phone_number: '+5511999990000',
 });
 
-const whatsappCost = await client.assignments.estimateCost(documentId, {
+const custoWhatsapp = await client.assignments.estimateCost(documentId, {
   method: 'virtual',
   signers: [{ verification_method: 'Whatsapp', notification_methods: ['Whatsapp'] }],
 });
 
-const whatsappAssignment = await client.assignments.create(documentId, {
+const assignmentWhatsapp = await client.assignments.create(documentId, {
   method: 'virtual',
   signers: [{
-    id: phoneSigner.id,
+    id: signatarioTelefone.id,
     verification_method: 'Whatsapp',
     notification_methods: ['Whatsapp'],
   }],
 });
 
-const notices = await client.assignments.listWhatsAppNotifications(
+const avisos = await client.assignments.listWhatsAppNotifications(
   documentId,
-  whatsappAssignment.id,
+  assignmentWhatsapp.id,
 );
 // IWhatsAppNotification[]:
 // [{ sent_at, header, body, buttons: [{ text, url? }], phone_number, signer_id }]
 ```
 
-The high-level helper selects this paid branch for a signer that has a phone
-number but no email. Button URLs can contain signer credentials; do not log or
-forward them outside the signing flow.
+O helper de alto nível escolhe esse ramo pago automaticamente para um signatário que tenha telefone
+e não tenha e-mail. As URLs dos botões podem conter credenciais do signatário — não registre em log
+nem encaminhe fora do fluxo de assinatura.
 
-#### ICP-Brasil digital certificate
+#### Certificado digital ICP-Brasil
 
-`DigitalCertificate` requires the account feature, a CPF or CNPJ in the
-signer's `government_id`, and exactly one certificate signer in that signing
-step. It costs two credits per certificate signer in addition to the selected
-notification cost.
+`DigitalCertificate` exige o recurso **Certificado Digital** na conta (planos Standard e Pro), CPF ou
+CNPJ em `government_id` do signatário, e exatamente **um signatário por certificado naquele passo de
+assinatura**. Custa 2 créditos por signatário, além do custo da notificação escolhida.
+
+**A1 e A3 são mídias de certificado**, escolhidas pelo próprio signatário no navegador na hora de
+assinar: A1 fica em software (um arquivo na máquina) e A3 em hardware (token ou cartão). A API
+modela as duas com o único valor `DigitalCertificate` — não existe campo `A1`/`A3` a enviar, e a
+assinatura PAdES resultante é qualificada nos dois casos.
+
+Um CPF exige o certificado daquela pessoa (e-CPF, ou e-CNPJ que a nomeie como representante legal);
+um CNPJ exige um e-CNPJ da empresa, de qualquer um dos seus representantes.
 
 ```ts
-const certificateSigner = await client.signers.update(signerId, {
+const signatarioCertificado = await client.signers.update(signerId, {
   government_id: '390.533.447-05',
 });
 
-const certificateCost = await client.assignments.estimateCost(documentId, {
+const custoCertificado = await client.assignments.estimateCost(documentId, {
   method: 'virtual',
   signers: [{ verification_method: 'DigitalCertificate', notification_methods: ['Email'] }],
 });
@@ -680,7 +860,7 @@ const certificateCost = await client.assignments.estimateCost(documentId, {
 await client.assignments.create(documentId, {
   method: 'virtual',
   signers: [{
-    id: certificateSigner.id,
+    id: signatarioCertificado.id,
     step: 1,
     verification_method: 'DigitalCertificate',
     notification_methods: ['Email'],
@@ -688,27 +868,37 @@ await client.assignments.create(documentId, {
 });
 ```
 
-Before opening the assignment, the signer must confirm identity data and accept
-terms with `confirmData(..., { has_accepted_terms: true })` or `acceptTerms()`.
-The regular `sign()` endpoint rejects certificate signers; they complete the
-ICP-Brasil flow through Assinafy's browser integration. After completion,
-`documents.download(documentId, 'pades')` returns the qualified PAdES artifact.
+Antes de abrir o assignment, o signatário precisa confirmar os dados de identidade e aceitar os
+termos, com `confirmData(..., { has_accepted_terms: true })` ou `acceptTerms()`.
+
+O endpoint comum `sign()` **rejeita** signatários por certificado: a assinatura deles é produzida por
+um handshake de dois passos com a extensão Web PKI, pela integração de navegador da Assinafy.
+
+```
+POST /v1/signers/certificate/start     → data.token   (token da operação Web PKI)
+        ↓  o navegador assina o token com o certificado do signatário
+POST /v1/signers/certificate/complete  → data.signerName
+```
+
+> Essas duas rotas são extensões implantadas **somente em produção**: o sandbox não as expõe e elas
+> não constam do documento OpenAPI publicado.
+
+Concluído o fluxo, `documents.download(documentId, 'pades')` devolve o artefato PAdES qualificado.
 
 ### Templates
 
-`templates.list()` is part of the current OpenAPI document. Existing
-integrations can also use five template-management routes—`create`, `get`,
-`update`, `delete`, and `downloadPage`—that are absent from that document. See
-[compatibility notes](docs/COMPATIBILITY.md#template-management-extensions).
-Template status casing can vary by deployment; normalize with
-`template.status.toLowerCase()` when branching on it.
+`templates.list()` faz parte do documento OpenAPI atual. Integrações existentes também podem usar
+cinco rotas de gestão de templates — `create`, `get`, `update`, `delete` e `downloadPage` — ausentes
+daquele documento; veja as
+[notas de compatibilidade](docs/COMPATIBILITY.md#template-management-extensions). A caixa do status
+de template varia por deploy; normalize com `template.status.toLowerCase()` antes de comparar.
 
 ```ts
-// Create a template by uploading a PDF (multipart). The template starts in
-// an uploaded state and becomes ready once its pages are processed.
-const created = await client.templates.create(
-  { filePath: './nda.pdf' },          // or { buffer, fileName: 'nda.pdf' }
-  { name: 'NDA template' },
+// Cria um template enviando um PDF (multipart). O template começa enviado e
+// fica pronto quando suas páginas são processadas.
+const criado = await client.templates.create(
+  { filePath: './nda.pdf' },          // ou { buffer, fileName: 'nda.pdf' }
+  { name: 'Template de NDA' },
 );
 // →
 // {
@@ -718,28 +908,28 @@ const created = await client.templates.create(
 //   pages: [], tags: [], created_at: '2026-…', updated_at: '2026-…'
 // }
 
-const { data, meta } = await client.templates.list({ search: 'NDA', per_page: 20 });
-const template = await client.templates.get(created.id);   // includes pages[] + default_document_tags
-await client.templates.update(created.id, { name: 'NDA v2', message: 'Please sign' });
-const firstPage = template.pages?.[0];
-if (firstPage) await client.templates.downloadPage(created.id, firstPage.id); // → Buffer (JPEG)
-await client.templates.delete(created.id);
-
-// Create a document from an existing, configured template. Fresh uploads have
-// only an Editor role; add signer roles in Assinafy's editor first.
-const configured = await client.templates.get(templateId);
-const signerRole = configured.roles?.find(
-  (role) => typeof role.assignment_type === 'string'
-    && role.assignment_type.toLowerCase() !== 'editor',
+const { data, meta } = await client.templates.list({ search: 'NDA', 'per-page': 20 });
+const template = await client.templates.get(criado.id);   // inclui pages[] + default_document_tags
+await client.templates.update(criado.id, { name: 'NDA v2', message: 'Por favor, assine' });
+const primeiraPagina = template.pages?.[0];
+if (primeiraPagina) await client.templates.downloadPage(criado.id, primeiraPagina.id); // → Buffer (JPEG)
+await client.templates.delete(criado.id);
+
+// Cria um documento a partir de um template já configurado. Uploads novos têm
+// apenas o papel Editor; adicione papéis de signatário no editor da Assinafy antes.
+const configurado = await client.templates.get(templateId);
+const papelSignatario = configurado.roles?.find(
+  (papel) => typeof papel.assignment_type === 'string'
+    && papel.assignment_type.toLowerCase() !== 'editor',
 );
-if (!signerRole) throw new Error('Template has no signer role');
+if (!papelSignatario) throw new Error('O template não tem papel de signatário');
 await client.documents.createFromTemplate(
   templateId,
-  [{ role_id: signerRole.id, id: signerId, verification_method: 'Email', notification_methods: ['Email'] }],
-  { name: 'NDA - John Doe', message: 'Please sign at your earliest convenience.' },
+  [{ role_id: papelSignatario.id, id: signerId, verification_method: 'Email', notification_methods: ['Email'] }],
+  { name: 'NDA - João Silva', message: 'Por favor, assine assim que puder.' },
 );
 
-// Estimate the cost before creating → ICostEstimate
+// Estime o custo antes de criar → ICostEstimate
 await client.documents.estimateCostFromTemplate(templateId, [
   { role_id: 'role_id', verification_method: 'Email', notification_methods: ['Email'] },
 ]);
@@ -747,41 +937,42 @@ await client.documents.estimateCostFromTemplate(templateId, [
 //     has_sufficient_resources: true, blocking_reason: null, breakdown: [], … }
 ```
 
-Template signer descriptors also accept
-`verification_method: 'DigitalCertificate'` with the same prerequisites under
-[ICP-Brasil digital certificate](#icp-brasil-digital-certificate).
+Os descritores de signatário de template também aceitam
+`verification_method: 'DigitalCertificate'`, com os mesmos pré-requisitos de
+[Certificado digital ICP-Brasil](#certificado-digital-icp-brasil).
 
-Template creation only uploads the PDF and provisions the default editor role —
-configure roles/fields in the Assinafy editor (or the web UI) afterwards.
-The `download_url` values in template page objects are protected URLs; prefer
-`templates.downloadPage()` so the API credential is attached.
+Criar um template apenas envia o PDF e provisiona o papel de editor padrão — configure papéis e
+campos no editor da Assinafy depois. Os `download_url` dos objetos de página do template são URLs
+protegidas; prefira `templates.downloadPage()`, que anexa a credencial da API.
 
 ### Tags
 
-Workspace-scoped labels that can be attached to documents and templates. Tag names are unique per workspace (case-insensitive).
+Rótulos com escopo de workspace que podem ser anexados a documentos e templates. Os nomes são únicos
+por workspace (sem diferenciar maiúsculas).
 
 ```ts
-await client.tags.list({ search: 'contract' });          // ITag[]
-const tag = await client.tags.create({ name: 'Contracts', color: 'ff8800' });
-await client.tags.update(tag.id, { name: 'Sales Contracts' });
-await client.tags.update(tag.id, { color: null });        // clear the color
-await client.tags.delete(tag.id);                         // 409 if still attached
-await client.tags.delete(tag.id, { force: true });        // detach everywhere, then delete
+await client.tags.list({ search: 'contrato' });           // ITag[]
+const tag = await client.tags.create({ name: 'Contratos', color: 'ff8800' });
+await client.tags.update(tag.id, { name: 'Contratos Comerciais' });
+await client.tags.update(tag.id, { color: null });        // limpa a cor
+await client.tags.delete(tag.id);                         // 409 se ainda estiver anexada
+await client.tags.delete(tag.id, { force: true });        // desanexa de tudo e apaga
 ```
 
-Attach/detach tags on a specific document via `client.documents.listTags / replaceTags / addTags / detachTag` (see [Documents](#documents)).
+Anexe/desanexe tags em um documento específico com `client.documents.listTags / replaceTags /
+addTags / detachTag` (veja [Documentos](#documentos)).
 
 ### Workspaces
 
-The official create/update request schemas define `name` and
-`notification_sender_type`. The sandbox also accepts the color fields shown
-below; they are retained as a documented compatibility extension.
+Os schemas oficiais de criação/atualização definem `name` e `notification_sender_type`. O sandbox
+também aceita os campos de cor abaixo; eles ficam mantidos como extensão de compatibilidade
+documentada.
 
 ```ts
-// Colours are 6-char hex WITHOUT a leading '#' (unlike tags, which strip it).
-// '#ff0066' is rejected — the account endpoints want exactly 6 characters.
+// As cores são hex de 6 caracteres SEM '#' inicial (ao contrário das tags, que o removem).
+// '#ff0066' é rejeitado — os endpoints de conta querem exatamente 6 caracteres.
 await client.workspaces.create({
-  name: 'My Workspace',
+  name: 'Meu Workspace',
   notification_sender_type: 'Account',
   primary_color: 'ff0066',
   secondary_color: '0066ff',
@@ -790,13 +981,13 @@ await client.workspaces.create({
 await client.workspaces.list();
 await client.workspaces.get(accountId);
 await client.workspaces.update(accountId, {
-  name: 'Renamed',
+  name: 'Renomeado',
   notification_sender_type: 'User',
   primary_color: '112233',
 });
 
-// Branding
-const theme = await client.workspaces.getTheme(accountId);
+// Identidade visual
+const tema = await client.workspaces.getTheme(accountId);
 const logo = await client.workspaces.downloadLogo(accountId); // Buffer
 await client.workspaces.uploadLogo(accountId, { filePath: './logo.png' });
 await client.workspaces.uploadLogo(accountId, {
@@ -806,7 +997,7 @@ await client.workspaces.uploadLogo(accountId, {
 });
 await client.workspaces.deleteLogo(accountId);
 
-// Latest 12 months by default; daily statistics require a YYYY-MM month.
+// Últimos 12 meses por padrão; estatísticas diárias exigem um mês YYYY-MM.
 await client.workspaces.getStats(accountId);
 await client.workspaces.getStats(accountId, {
   granularity: 'daily',
@@ -814,97 +1005,100 @@ await client.workspaces.getStats(accountId, {
 });
 
 await client.workspaces.delete(accountId);
-// `force` cancels an active paid subscription as part of account deletion. It
-// is not a general bypass for unrelated deletion restrictions.
-await client.workspaces.delete(restrictedAccountId, { force: true });
+// `force` cancela uma assinatura paga ativa como parte da exclusão da conta. Não
+// é um atalho geral para outras restrições de exclusão.
+await client.workspaces.delete(contaRestrita, { force: true });
 ```
 
-### Field definitions
+### Definições de campo
 
-Custom field types used by `collect`-method assignments.
+Tipos de campo personalizados usados por assignments com método `collect`.
 
 ```ts
-await client.fields.create({ type: 'text', name: 'Contract Number' });
+await client.fields.create({ type: 'text', name: 'Número do contrato' });
 await client.fields.list({ include_inactive: true, include_standard: true });
 await client.fields.get(fieldId);
-await client.fields.update(fieldId, { name: 'Updated Name' });
+await client.fields.update(fieldId, { name: 'Nome atualizado' });
 await client.fields.delete(fieldId);
 
-// Validate a single value (signer-access-code only required for signer-side calls)
+// Valida um único valor (o código de acesso só é exigido nas chamadas do signatário)
 await client.fields.validate(fieldId, '400.676.228-36', { signerAccessCode });
 
-// Validate multiple values at once
+// Valida vários valores de uma vez
 await client.fields.validateMultiple(
   [
     { field_id: 'f1', value: '1111111111111' },
-    { field_id: 'f2', value: 'value@example.com' },
+    { field_id: 'f2', value: 'valor@exemplo.com.br' },
   ],
   { signerAccessCode },
 );
 
-// Catalog of every field type the platform recognises
+// Catálogo de todos os tipos de campo reconhecidos pela plataforma
 await client.fields.listTypes();
 ```
 
-### Authentication / API key management
+### Autenticação / gestão de chaves de API
 
-Most server-side integrations should just use `X-Api-Key` directly. Use these endpoints when you need to bootstrap a session for a human user.
+A maioria das integrações de servidor deve usar `X-Api-Key` diretamente. Use estes endpoints quando
+precisar abrir uma sessão para uma pessoa. Para apps conectados por terceiros, use
+[Aplicações OAuth](#aplicações-oauth).
 
 ```ts
-// Browser OAuth: redirect the user to this URL. The callback helper returns the
-// Assinafy callback URL for provider configuration; neither follows a redirect.
-const oauthStart = client.auth.getSocialLoginUrl('google');
-const oauthCallback = client.auth.getSocialLoginCallbackUrl();
+// OAuth de navegador (rota de compatibilidade): redirecione o usuário para esta URL.
+// O helper de callback devolve a URL de retorno da Assinafy para configurar o
+// provedor; nenhum dos dois segue o redirecionamento.
+const inicioOauth = client.auth.getSocialLoginUrl('google');
+const callbackOauth = client.auth.getSocialLoginCallbackUrl();
 
-const { access_token, user, accounts } = await client.auth.login('me@example.com', 'pw');
+const { access_token, user, accounts } = await client.auth.login('eu@exemplo.com.br', 'senha');
 await client.auth.socialLogin({ provider: 'google', token: 'google-id-token', has_accepted_terms: true });
 await client.auth.linkSocialLogin({ provider: 'google', token: 'google-id-token' });
 
-// Personal API key
-await client.auth.createApiKey('current-password');
-await client.auth.getApiKey();                     // → { api_key: '****...nBNr' } or null
+// Chave de API pessoal
+await client.auth.createApiKey('senha-atual');
+await client.auth.getApiKey();                     // → { api_key: '****...nBNr' } ou null
 await client.auth.deleteApiKey();
 
-// Password lifecycle
-await client.auth.changePassword({ email, password: 'current', new_password: 'next' });
-await client.auth.requestPasswordReset('me@example.com');
-await client.auth.resetPassword({ email, token: 'tk', new_password: 'next' });
+// Ciclo de vida da senha
+await client.auth.changePassword({ email, password: 'atual', new_password: 'nova' });
+await client.auth.requestPasswordReset('eu@exemplo.com.br');
+await client.auth.resetPassword({ email, token: 'tk', new_password: 'nova' });
 ```
 
-### Authenticated user
+### Usuário autenticado
 
 ```ts
-const user = await client.users.getCurrent();
+const usuario = await client.users.getCurrent();
 // → { id, name, email, telephone, government_id, is_email_verified,
 //     has_accepted_terms, created_at, to_be_deleted_at }
 
-// Cross-account document funnel, latest 12 monthly periods by default.
-const monthly = await client.users.getStats();
-const daily = await client.users.getStats({
+// Funil de documentos entre contas, últimos 12 períodos mensais por padrão.
+const mensal = await client.users.getStats();
+const diario = await client.users.getStats({
   granularity: 'daily',
   month: '2026-06',
 });
-// Each row includes period, upload/send/certification totals, notification
-// counts for email/WhatsApp/bypass, verification counts for
-// email/WhatsApp/bypass/digital-certificate, viewed, and completed counts.
+// Cada linha traz período, totais de envio/remessa/certificação, contagens de
+// notificação por e-mail/WhatsApp/bypass, contagens de verificação por
+// e-mail/WhatsApp/bypass/certificado digital, visualizados e concluídos.
 
-const preferences = await client.users.getNotificationPreferences();
+const preferencias = await client.users.getNotificationPreferences();
 await client.users.updateNotificationPreferences({
   SignerDeclined: false,
   DocumentExpired: false,
 });
-// Updates merge: omitted keys keep their current value. Both methods return
-// the complete nine-key notification preference map.
+// A atualização é um merge: chaves omitidas mantêm o valor atual. Os dois
+// métodos devolvem o mapa completo de nove preferências.
 ```
 
 ### Webhooks
 
 ```ts
 await client.webhooks.register({
-  url: 'https://example.com/webhooks/assinafy',
-  email: 'admin@example.com',
+  url: 'https://exemplo.com.br/webhooks/assinafy',
+  email: 'admin@exemplo.com.br',
   is_active: true,
-  // events defaults to the current SDK default set below
+  // `events` assume o conjunto padrão do SDK, abaixo
   events: [
     'document_ready',
     'document_prepared',
@@ -915,26 +1109,25 @@ await client.webhooks.register({
 });
 
 await client.webhooks.get();          // IWebhookSubscription | null
-await client.webhooks.inactivate();   // stop deliveries (no delete route exists)
+await client.webhooks.inactivate();   // interrompe entregas (não existe rota de exclusão)
 await client.webhooks.listEventTypes();
-const history = await client.webhooks.listDispatches({
+const historico = await client.webhooks.listDispatches({
   delivered: false,
   page: 1,
   'per-page': 20,
 }); // { data: IWebhookDispatch[], meta?: PaginationMeta }
-const retried = await client.webhooks.retryDispatch(dispatchId); // IWebhookDispatch
+const reenviado = await client.webhooks.retryDispatch(dispatchId); // IWebhookDispatch
 ```
 
-`register` sends `{ events, is_active, url, email }` and returns
-`{ events, is_active, url, email, updated_at? }`. Assinafy delivers each event
-as an HTTP `POST` with `Content-Type: application/json` and `Connection: close`.
-Any `2xx` is success. There are at most two automatic attempts, separated by
-three seconds. After ten consecutive failed events, ordinary delivery pauses
-and about 5% of later events are attempted until one succeeds; use
-`retryDispatch()` for an immediate manual redelivery. The dispatch history
-retains only the first 2,000 characters of the receiver's response body.
+`register` envia `{ events, is_active, url, email }` e devolve
+`{ events, is_active, url, email, updated_at? }`. A Assinafy entrega cada evento como um `POST` HTTP
+com `Content-Type: application/json` e `Connection: close`. Qualquer `2xx` é sucesso. São no máximo
+duas tentativas automáticas, com três segundos de intervalo. Depois de dez eventos falhos
+consecutivos, a entrega comum é pausada e cerca de 5% dos eventos seguintes são tentados até um dar
+certo; use `retryDispatch()` para reenviar manualmente na hora. O histórico guarda apenas os
+primeiros 2.000 caracteres do corpo de resposta do receptor.
 
-Each history or retry result is an `IWebhookDispatch`:
+Cada item do histórico (ou resultado de reenvio) é um `IWebhookDispatch`:
 
 ```ts
 {
@@ -953,25 +1146,25 @@ Each history or retry result is an `IWebhookDispatch`:
 }
 ```
 
-Every delivery body uses this envelope:
+Todo corpo de entrega usa este envelope:
 
 ```ts
 {
-  id: number;                         // use for idempotent processing
+  id: number;                         // use para processamento idempotente
   event: string;
   message: string | null;
   payload: Record<string, unknown> | null;
   origin: { ip?: string; 'user-agent'?: string } | null;
-  created_at: number;                 // Unix seconds
+  created_at: number;                 // segundos Unix
   subject: { type: 'User' | 'Signer' | 'Account' | 'Document' | 'Template'; [key: string]: unknown };
   object: { type: 'User' | 'Signer' | 'Account' | 'Document' | 'Template'; [key: string]: unknown };
   account_id: string;
 }
 ```
 
-Event-specific values are:
+Os valores por evento são:
 
-| `event` | `subject.type` | `object.type` | `payload` keys |
+| `event` | `subject.type` | `object.type` | chaves de `payload` |
 | --- | --- | --- | --- |
 | `document_uploaded` | `User` | `Document` | — |
 | `document_metadata_ready` | `User` | `Document` | — |
@@ -979,7 +1172,7 @@ Event-specific values are:
 | `assignment_created` | `User` | `Document` | `user_name`, `user_email`, `user_telephone` |
 | `document_ready` | `Account` | `Document` | — |
 | `document_processing_failed` | `Account` | `Document` | `error_message` |
-| `signature_requested` | `User` | `Document` | `signer_email`, `signer_full_name`, or `signer_whatsapp_phone_number`, according to channel |
+| `signature_requested` | `User` | `Document` | `signer_email`, `signer_full_name` ou `signer_whatsapp_phone_number`, conforme o canal |
 | `signer_created` | `User` | `Signer` | `signer_full_name` |
 | `signer_email_verified` | `Signer` | `Document` | `signer_email` |
 | `signer_whatsapp_verified` | `Signer` | `Document` | `signer_whatsapp_phone_number` |
@@ -992,21 +1185,19 @@ Event-specific values are:
 | `template_processed` | `User` | `Template` | — |
 | `template_processing_failed` | `Account` | `Template` | `error_message` |
 
-`payload`, `subject`, and `object` are event-dependent. Accept unknown fields
-for forward compatibility and acknowledge only after durable, idempotent
-processing. Non-`2xx` responses, timeouts, and connection failures all count as
-failed deliveries. `assignment_created` and `document_metadata_ready` have no
-guaranteed ordering. For account entities, Assinafy removes the `integration`
-property before delivery.
+`payload`, `subject` e `object` dependem do evento. Aceite campos desconhecidos para compatibilidade
+futura e só confirme o recebimento depois de um processamento durável e idempotente. Respostas
+não-`2xx`, timeouts e falhas de conexão contam como entregas falhas. `assignment_created` e
+`document_metadata_ready` não têm ordem garantida. Para entidades de conta, a Assinafy remove a
+propriedade `integration` antes de entregar.
 
-### Webhook verification
+### Verificação de webhooks
 
-`WebhookVerifier` is an opt-in HMAC-SHA256 utility for integrations whose
-Assinafy environment provides a shared secret and signature header. The
-current official OpenAPI document does **not** define a webhook signature
-scheme or header name. Confirm the delivery contract for your environment
-before enabling this check; do not reject production callbacks based on an
-assumed header. The example below uses an application-configured header name.
+`WebhookVerifier` é um utilitário HMAC-SHA256 opcional, para integrações cujo ambiente Assinafy
+forneça um segredo compartilhado e um header de assinatura. O documento OpenAPI oficial atual
+**não** define esquema nem nome de header de assinatura de webhook. Confirme o contrato de entrega
+do seu ambiente antes de habilitar essa checagem; não rejeite callbacks de produção com base em um
+header presumido. O exemplo abaixo usa um nome de header configurado pela aplicação.
 
 ```ts
 import express from 'express';
@@ -1014,159 +1205,209 @@ import express from 'express';
 const webhookSecret = process.env.ASSINAFY_WEBHOOK_SECRET;
 const signatureHeader = process.env.ASSINAFY_SIGNATURE_HEADER;
 if (!webhookSecret || !signatureHeader) {
-  throw new Error('This deployment has no confirmed webhook-signature contract');
+  throw new Error('Este ambiente não tem contrato confirmado de assinatura de webhook');
 }
 
 const webhookClient = new AssinafyClient({ webhookSecret });
 
 app.post('/webhooks/assinafy', express.raw({ type: 'application/json' }), (req, res) => {
-  const signature = req.header(signatureHeader) ?? '';
-  const rawBody = req.body as Buffer;
+  const assinatura = req.header(signatureHeader) ?? '';
+  const corpoBruto = req.body as Buffer;
 
-  if (!webhookClient.webhookVerifier.verify(rawBody, signature)) {
-    return res.status(401).send('Invalid signature');
+  if (!webhookClient.webhookVerifier.verify(corpoBruto, assinatura)) {
+    return res.status(401).send('Assinatura inválida');
   }
 
-  const event = webhookClient.webhookVerifier.extractEvent(rawBody);
-  const type = webhookClient.webhookVerifier.getEventType(event);
-  const data = webhookClient.webhookVerifier.getEventData(event);
+  const evento = webhookClient.webhookVerifier.extractEvent(corpoBruto);
+  const tipo = webhookClient.webhookVerifier.getEventType(evento);
+  const dados = webhookClient.webhookVerifier.getEventData(evento);
 
-  switch (type) {
-    case 'document_ready':            break;
-    case 'signer_signed_document':    break;
-    case 'signer_rejected_document':  break;
-    case 'document_processing_failed':break;
+  switch (tipo) {
+    case 'document_ready':             break;
+    case 'signer_signed_document':     break;
+    case 'signer_rejected_document':   break;
+    case 'document_processing_failed': break;
   }
   res.sendStatus(200);
 });
 ```
 
-### Signer-side endpoints
+### Endpoints do signatário
 
-For building custom signer portals. Most calls require the `signer-access-code`
-URL parameter that Assinafy emails/whatsapps to the signer. Artifact download is
-the documented public exception; its optional fourth access-code argument exists
-only for compatibility with deployments that still expect the legacy query.
+Para construir portais de assinatura próprios. Quase todas as chamadas exigem o parâmetro de URL
+`signer-access-code` que a Assinafy envia ao signatário por e-mail/WhatsApp. O download de artefato
+é a exceção pública documentada; seu quarto argumento opcional de código de acesso existe apenas por
+compatibilidade com deploys que ainda esperam a query antiga.
 
 ```ts
 await client.signerDocuments.self(accessCode);
 await client.signerDocuments.verifyEmail({ signerAccessCode: accessCode, verificationCode: '123456' });
 
 await client.signerDocuments.getCurrent(signerId, accessCode);
-const { data } = await client.signerDocuments.list(signerId, accessCode, { per_page: 20 });
-// Signer-side counterpart of documents.search(), authorised by the access code.
-const found = await client.signerDocuments.search(signerId, accessCode, 'invoice');
+const { data } = await client.signerDocuments.list(signerId, accessCode, { 'per-page': 20 });
+// Equivalente a documents.search() do lado do signatário, autorizado pelo código de acesso.
+const achados = await client.signerDocuments.search(signerId, accessCode, 'nota fiscal');
 await client.signerDocuments.download(signerId, documentId, 'original');
-// Available only after an ICP-Brasil certificate signer completes signing.
+// Disponível só depois que um signatário por certificado ICP-Brasil concluir a assinatura.
 await client.signerDocuments.download(signerId, documentId, 'pades');
 
 await client.signerDocuments.confirmData(documentId, accessCode, {
-  email: 'me@example.com',
-  full_name: 'Example Signer',
+  email: 'eu@exemplo.com.br',
+  full_name: 'Signatário Exemplo',
   government_id: '123.456.789-00',
   has_accepted_terms: true,
 });
-// Alternatively, accept terms separately before getAssignment():
+// Como alternativa, aceite os termos separadamente antes de getAssignment():
 // await client.signerDocuments.acceptTerms(accessCode);
 
-// Signature image management ({ reuse: true } persists it for future documents)
+// Gestão da imagem de assinatura ({ reuse: true } guarda para documentos futuros)
 await client.signerDocuments.uploadSignature(accessCode, pngBuffer, { imageType: 'signature', reuse: true });
 await client.signerDocuments.downloadSignature(accessCode, 'signature');
 
-// Sign / decline
-const signable = await client.signerDocuments.getAssignment(accessCode);
-// `sign()` is for collect assignments and requires every placed field value.
+// Assinar / recusar
+const assinavel = await client.signerDocuments.getAssignment(accessCode);
+// `sign()` é para assignments collect e exige o valor de cada campo posicionado.
 await client.signerDocuments.sign(documentId, assignmentId, accessCode, [
-  { itemId, fieldId, pageId, value: 'Signed by John' },
+  { itemId, fieldId, pageId, value: 'Assinado por João' },
 ]);
-await client.signerDocuments.decline(documentId, assignmentId, accessCode, 'Not authorized');
+await client.signerDocuments.decline(documentId, assignmentId, accessCode, 'Sem autorização');
 
-// `signMultiple()` is for virtual assignments only.
+// `signMultiple()` é só para assignments virtual.
 await client.signerDocuments.signMultiple(['doc-1', 'doc-2'], accessCode);
-await client.signerDocuments.declineMultiple(['doc-1'], 'Unfavorable terms', accessCode);
+await client.signerDocuments.declineMultiple(['doc-1'], 'Condições desfavoráveis', accessCode);
 ```
 
-`sign()` also requires virtual signers to have confirmed their data first, but
-virtual assignments should normally use `signMultiple()`. Certificate signers
-cannot use `sign()`; see [Paid signing branches](#paid-signing-branches).
+`sign()` também exige que signatários virtuais já tenham confirmado os dados, mas assignments
+virtuais normalmente devem usar `signMultiple()`. Signatários por certificado não podem usar
+`sign()`; veja [Ramos pagos de assinatura](#ramos-pagos-de-assinatura).
 
-## High-level helper
+## Helper de alto nível
 
-Uploads a PDF, reuses or creates signers by email, creates a virtual assignment
-immediately, and optionally waits for processing before returning.
+Envia um PDF, reaproveita ou cria signatários por e-mail, cria um assignment virtual imediatamente e,
+opcionalmente, espera o processamento antes de retornar.
 
 ```ts
-const result = await client.uploadAndRequestSignatures({
-  source: { filePath: './contract.pdf' },
+const resultado = await client.uploadAndRequestSignatures({
+  source: { filePath: './contrato.pdf' },
   signers: [
-    { name: 'John', email: 'john@example.com' },
-    { name: 'Jane', email: 'jane@example.com' },
+    { name: 'João', email: 'joao@exemplo.com.br' },
+    { name: 'Maria', email: 'maria@exemplo.com.br' },
   ],
-  message: 'Please sign',
-  metadata: { year: 2026 }, // compatibility upload part; omit for file-only wire format
+  message: 'Por favor, assine',
+  metadata: { ano: 2026 }, // parte de compatibilidade; omita para o formato só-arquivo
   waitForReady: true,
   waitOptions: { maxWaitMs: 30_000, pollIntervalMs: 1_000 },
   expiresAt: '2027-12-31T00:00:00Z',
-  copyReceivers: ['existing-copy-recipient-signer-id'],
+  copyReceivers: ['id-de-signatario-em-copia'],
 });
 
-result.document;   // fully-processed IDocumentDetailsResponse (waitForReady: true, the default);
-                   // the raw IDocumentUploadResponse when waitForReady: false
-result.assignment; // IAssignment
-result.signer_ids; // string[]
+resultado.document;   // IDocumentDetailsResponse já processado (waitForReady: true, o padrão);
+                      // o IDocumentUploadResponse cru quando waitForReady: false
+resultado.assignment; // IAssignment
+resultado.signer_ids; // string[]
 ```
 
-`waitForReady: false` skips post-assignment polling and returns the initial
-upload response. With the default `true`, the helper creates the assignment first and
-then waits for the current document details. Both production and sandbox allow
-virtual assignments in `uploaded` and `metadata_processing` and promote them
-automatically; only `collect` assignments require rendered pages.
-Every signer above uses the default email channel. A phone-only signer selects
-the paid WhatsApp branch described earlier. `copyReceivers` accepts existing
-signer IDs, not email addresses; check the returned assignment before treating
-a copy receiver as registered.
+`waitForReady: false` pula a espera pós-assignment e devolve a resposta inicial do upload. Com o
+padrão `true`, o helper cria o assignment primeiro e só então espera os detalhes atuais do
+documento. Produção e sandbox permitem assignments virtuais em `uploaded` e `metadata_processing` e
+os promovem automaticamente; só assignments `collect` exigem páginas renderizadas. Todos os
+signatários acima usam o canal de e-mail padrão. Um signatário só com telefone seleciona o ramo pago
+de WhatsApp descrito antes. `copyReceivers` aceita IDs de signatários existentes, não endereços de
+e-mail; confira o assignment devolvido antes de considerar uma cópia registrada.
 
-The helper is not transactional. A post-assignment polling error includes the
-created `documentId`, `assignmentId`, and `signerIds` in its `context` (and in
-`ValidationError.errors` for timeouts); inspect those IDs before deciding
-whether to retry the workflow.
+O helper não é transacional. Um erro depois do assignment inclui `documentId`, `assignmentId` e
+`signerIds` criados no `context` do erro (e em `ValidationError.errors` para timeouts); inspecione
+esses IDs antes de decidir se repete o fluxo.
 
-## Errors
+## Erros
 
-HTTP methods reject with an `AssinafyError` subclass. Synchronous helpers such
-as `getSocialLoginUrl()` can throw `ValidationError` before any request.
+Os métodos HTTP rejeitam com uma subclasse de `AssinafyError`. Helpers síncronos como
+`getSocialLoginUrl()` e `readAuthorizationCallback()` podem lançar antes de qualquer requisição.
+
+| Classe | Quando | O que inspecionar |
+| --- | --- | --- |
+| `ValidationError` | O SDK recusou a entrada antes de enviar | `err.errors` |
+| `OAuthError` | Um endpoint OAuth devolveu `{ error, error_description }`, ou o callback trouxe `?error=` | `err.error`, `err.errorDescription` |
+| `ApiError` | A API respondeu com status de falha | `err.statusCode`, `err.responseData`, `err.challenge` |
+| `NetworkError` | DNS, conexão ou timeout | `err.message` (já sem credenciais) |
+| `AssinafyError` | Classe base de todas as acima | `err.context` |
 
 ```ts
-import { ApiError, ValidationError, NetworkError, AssinafyError } from '@assinafy/sdk';
+import { ApiError, OAuthError, ValidationError, NetworkError, AssinafyError } from '@assinafy/sdk';
 
 try {
   await client.documents.upload({ filePath: './x.pdf' });
 } catch (err) {
   if (err instanceof ValidationError) {
-    console.error('Validation failed:', err.errors);
+    console.error('Falha de validação:', err.errors);
+  } else if (err instanceof OAuthError) {
+    // OAuthError estende ApiError; ramifique pelo código RFC 6749, não pela mensagem.
+    console.error('Erro OAuth:', err.error, err.errorDescription);
   } else if (err instanceof ApiError) {
-    console.error(`API error ${err.statusCode}:`, err.responseData);
+    console.error(`Erro da API ${err.statusCode}:`, err.responseData);
+    // `err.challenge` traz o header WWW-Authenticate já interpretado quando a API
+    // envia um — em um 403 ele nomeia o escopo OAuth que está faltando.
   } else if (err instanceof NetworkError) {
-    console.error('Network error:', err.message);
+    console.error('Erro de rede:', err.message);
   } else if (err instanceof AssinafyError) {
-    console.error('SDK error:', err.message, err.context);
+    console.error('Erro do SDK:', err.message, err.context);
   }
 }
 ```
 
-## Development
+## Ambientes
+
+| | |
+| --- | --- |
+| Produção | `https://api.assinafy.com.br/v1` |
+| Sandbox | `https://sandbox.assinafy.com.br/v1` |
+
+O sandbox é gratuito e espelha a produção para testar a integração de ponta a ponta, com a exceção
+das rotas de certificado digital, que existem apenas em produção.
+
+O sandbox tem servidor de autorização próprio em `https://auth-sandbox.assinafy.com.br`, com a tela
+de consentimento em `/oauth/authorize`. Os documentos de descoberta dele, porém, não são
+alcançáveis: o nginx do sandbox recusa qualquer caminho iniciado por ponto, então `/.well-known/…`
+nunca chega à aplicação. Informe os endpoints explicitamente para pular a descoberta:
+
+```ts
+const client = new AssinafyClient({ baseUrl: 'https://sandbox.assinafy.com.br/v1' });
+
+const requisicao = await client.oauth.createAuthorizationUrl({
+  clientId: process.env.ASSINAFY_CLIENT_ID!,
+  redirectUri: 'https://meuapp.com.br/oauth/callback',
+  scopes: ['documents:read'],
+  issuer: 'https://auth-sandbox.assinafy.com.br',
+  authorizationEndpoint: 'https://auth-sandbox.assinafy.com.br/oauth/authorize',
+});
+```
+
+Os endpoints de token, revogação e userinfo seguem o `baseUrl` configurado. Confirme que o deploy de
+sandbox os expõe antes de rodar a etapa de troca por lá — veja
+[docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
+
+## Desenvolvimento
 
 ```bash
 bun install --frozen-lockfile
-bun run typecheck    # source, script, and test type checks
+bun run typecheck    # tipos de src, scripts e testes
 bun run lint
-bun test             # bun:test suites
+bun test             # suítes bun:test
 bun run test:coverage
 bun run build        # tsup → dist/ (CJS + ESM + .d.ts)
 bun run lint:pkg     # publint + arethetypeswrong
-bun run verify       # complete local release gate
+bun run audit:api    # confere o SDK contra o OpenAPI publicado
+bun run verify       # portão completo de release local
 ```
 
-## License
+## Documentação
+
+- **[README.en.md](README.en.md)** — a mesma referência completa, em inglês
+- [docs/API_COVERAGE.md](docs/API_COVERAGE.md) — mapa de operações
+- [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) — variações de requisição e resposta por deploy
+- [docs/RELEASING.md](docs/RELEASING.md) — processo de publicação
+- [Documentação da API](https://api.assinafy.com.br/v1/docs)
+
+## Licença
 
-MIT
+Distribuído sob a licença [MIT](LICENSE).