assinafy 1.9.0 → 1.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c202496157dd16d5ae51e1e6416ca30ab0d6ec3665ffa6dead88219214c82b8
-  data.tar.gz: 9c07ecf32a3c9e9e94d964d56f6f38dc8c670d2cc011059d4c14409e79972b9e
+  metadata.gz: d8a12972c20d3f42452948edca772428326d37eafaf2354286bd9d3285bb6bf2
+  data.tar.gz: ad4b481584b05d052d7f44cde2a0cc7c99873e127031c30c60662c0a95dbca40
 SHA512:
-  metadata.gz: 4bd51928265eb56100d62653932be2145442efb23e4708007070a027aeaff0e96678014c4d2a5b39ca2a9dcb37c6a13e5caf3b16798e28b6ad2ad535ef937068
-  data.tar.gz: 7c1c6a6f07f0794b685b414195161f9832c74e9e196adff5f8713b26b44d7b94c188651184144af0b7393ad8bfea97d601a0e350c7165d2a4709356bcda0743a
+  metadata.gz: 8990224d37bac65328f95e7bdae28c999381f33fa64f1cfe300f3fffc124e8e98ab4e8e8473802534b1155ec06fc5c8080ffffb8a809118abf8d58cc661ad6a7
+  data.tar.gz: 35be652f65fa20a29cef34f3487f4af98ac9e94d613ec51c816b24ee879ed436b4c168aaeb51f32fef81864a9b7e54824812fa713693b2e7235e424ae407f085

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## 1.10.1
+
+- Update the pinned Ruby setup action to support Ruby 4.0.7 in CI and release workflows.
+
+## 1.10.0
+
+- Support the RFC 8693 token-exchange grant for Assinafy-provisioned internal service clients.
+- Validate OAuth grant parameters, PKCE challenges, authorization URLs, and token response shapes.
+- Validate assignment deadlines, notification and verification method combinations, and signing steps before requests.
+- Validate template role and signer IDs, distinct role assignments, and editor field payloads before document creation.
+- Validate contact addresses, scalar payload fields, decline-reason lengths, and finite polling intervals consistently.
+- Expand the document workflow guides, OAuth integration instructions, and API schema reference.
+- Use Ruby 4.0.7 for the development and release toolchain.
+
 ## 1.9.0
 
 - `OAuthResource#refresh`, and `#token` with the `refresh_token` grant, raise `Assinafy::Error` instead of

data/README.en.md

@@ -57,6 +57,7 @@ client = Assinafy::Client.new(
 )
 
 document = client.documents.upload({ file_path: './contract.pdf' })
+document = client.documents.wait_until_ready(document.fetch('id'))
 signer   = client.signers.create(full_name: 'Alice Silva', email: 'alice@example.com')
 
 assignment = client.assignments.create(
@@ -72,6 +73,7 @@ puts assignment['id']
 ## Configuration
 
 ```ruby
+require 'logger'
 client = Assinafy::Client.new(
   api_key:        'your-api-key',
   token:          nil,
@@ -270,6 +272,11 @@ client.oauth.authorization_server_metadata['code_challenge_methods_supported']
 `authorization_server_metadata` reaches a different host, so — like `/oauth/token` and `/oauth/revoke` — the SDK
 sends it with no workspace credentials attached.
 
+**Internal service clients.** The advertised RFC 8693 token-exchange grant is restricted to
+Assinafy-provisioned confidential service clients. Marketplace apps use PKCE authorization code
+and refresh. `client.oauth.token` accepts token exchange with `client_secret`, `subject_token`,
+`subject_token_type`, and `resource`; it issues no refresh token.
+
 **Errors.** OAuth routes answer with the flat RFC 6749 object rather than this API's envelope, so the SDK raises
 `Assinafy::OAuthError` (a subclass of `Assinafy::ApiError`):
 
@@ -343,11 +350,11 @@ client.documents.append_tags('document-id', ['tag-id-3'])
 # The deployed sandbox also accepts existing tag names in these arrays.
 client.documents.detach_tag('document-id', 'tag-id')
 
-# Template-driven creation
+# Template-driven creation (a template with one configured Signer role)
 client.documents.create_from_template(
   'template-id',
   [{ role_id: 'role', id: 'signer-id', verification_method: 'Email', notification_methods: ['Email'] }],
-  { name: 'Contract', message: 'Please sign', expires_at: '2026-12-31T23:59:00Z' }
+  { name: 'Contract', message: 'Please sign', expires_at: '2099-12-31T23:59:00Z' }
 )
 client.documents.estimate_cost_from_template(
   'template-id',
@@ -401,7 +408,7 @@ client.assignments.create(
   method:         'virtual',
   signers:        [{ id: 'signer-1', verification_method: 'Email', notification_methods: ['Email'], step: 1 }],
   message:        'Please sign',
-  expires_at:     '2026-12-31T23:59:00Z',
+  expires_at:     '2099-12-31T23:59:00Z',
   copy_receivers: ['cc-signer-id']
 )
 
@@ -417,7 +424,7 @@ client.assignments.create(
 
 client.assignments.list                                       # GET /assignments (scoped to the account)
 client.assignments.estimate_cost('document-id', signers: [{ verification_method: 'Whatsapp' }])
-client.assignments.reset_expiration('document-id', 'assignment-id', '2026-12-31T23:59:00Z')
+client.assignments.reset_expiration('document-id', 'assignment-id', '2099-12-31T23:59:00Z')
 client.assignments.reset_expiration('document-id', 'assignment-id', nil) # clears the expiry
 client.assignments.resend_notification('document-id', 'assignment-id', 'signer-id')
 client.assignments.estimate_resend_cost('document-id', 'assignment-id', 'signer-id')
@@ -436,6 +443,11 @@ client.assignments.decline('document-id', 'assignment-id', decline_reason: 'Clau
 
 > The `sign` request body is the API's camelCase body-key exception. This SDK accepts the snake_case keys (`item_id`, `field_id`, `page_id`, `value`) shown above and maps them to `itemId/fieldId/pageId/value` automatically. CamelCase input is also passed through unchanged. Assignment listing separately uses the live-required `accountId` query parameter.
 
+Use exactly one notification channel per signer: `Email` verification pairs with `Email`,
+`Whatsapp` pairs with `Whatsapp`, and `DigitalCertificate` permits either. If any signer has a
+`step`, all must have one, with contiguous steps starting at 1. A certificate signer must be alone
+in its step. Deadlines require a timezone and must be at least one hour in the future.
+
 ### Signer documents (multi-document workflows)
 
 ```ruby
@@ -459,7 +471,12 @@ client.templates.delete('template-id')
 client.templates.download_page('template-id', 'page-id')   # binary image bytes
 ```
 
-> Template endpoints (`get`/`create`/`update`/`delete`/`download_page`) are live-verified against the sandbox but are not part of the current OpenAPI document. `create` requires a source file (`multipart/form-data`); the template name defaults to the uploaded file's name.
+> Template endpoints (`get`/`create`/`update`/`delete`/`download_page`) are supported by the deployed API but are not part of the current OpenAPI document. `create` requires a source file (`multipart/form-data`); the template name defaults to the uploaded file's name.
+
+A template upload initially contains an `Editor` role. Configure at least one `Signer` role and its
+fields in the Assinafy application before generating a document. Supply one entry per role, each with
+a distinct existing signer ID; `role_id` comes from the template's `roles` array. Cost estimation
+requires `role_id` but can omit the signer ID.
 
 ### Tags
 
@@ -639,16 +656,18 @@ assignment = client.assignments.create(
   method:     'virtual',
   signers:    [signer_request],
   message:    'Please review and sign.',
-  expires_at: '2026-12-31T23:59:00Z'
+  expires_at: '2099-12-31T23:59:00Z'
 )
 # => Assignment, including signing_urls
 ```
 
-The template alternative binds a signer to a template role and creates the document and assignment together:
+For a template configured with exactly one `Signer` role, the alternative binds the existing signer
+to that role and creates the document and assignment together. Templates with more roles require
+a distinct signer entry for each role:
 
 ```ruby
 role_signer = {
-  role_id:              template.fetch('roles').first.fetch('id'),
+  role_id:              template.fetch('roles').find { |role| role['assignment_type'] == 'Signer' }.fetch('id'),
   id:                   signer.fetch('id'),
   verification_method:  'Email',
   notification_methods: ['Email']
@@ -721,7 +740,8 @@ signer is created.
 Requesting the method is fully supported. Completing the signature is not: the two-step handshake
 (`/signers/certificate/start`, `/signers/certificate/complete`) is absent from the API v1 machine contract — its
 authentication and request/response schemas are not published — so the SDK does not expose those completion
-calls rather than guess at their payloads. Contact Assinafy before enabling a digital-certificate signing flow.
+calls. Direct A1/A3 signers to Assinafy's hosted signing flow using the returned `signing_urls`;
+contact Assinafy for a published contract before integrating the handshake directly.
 Once it completes, the `pades` artifact returns the qualified signature.
 
 ### 7. Inspect, tag, download, and verify
@@ -734,7 +754,8 @@ tags = client.documents.append_tags(document_id, ['tag-id']) # => Array<Tag>
 client.documents.replace_tags(document_id, tags.map { |tag| tag.fetch('id') })
 
 original_pdf = client.documents.download(document_id, 'original')
-signed_pdf = client.documents.download(document_id, 'pades')
+signed_pdf = client.documents.download(document_id, 'certificated')
+# For documents completed with ICP-Brasil certificates: download(document_id, 'pades')
 certificate_pdf = client.documents.download(document_id, 'certificated')
 
 verification = client.documents.verify('signature-hash-from-assinafy')
@@ -787,10 +808,10 @@ result = client.upload_and_request_signatures(
   source:  { file_path: './contract.pdf' },
   signers: [
     { full_name: 'Alice Silva', email: 'alice@example.com' },
-    { full_name: 'Bob Costa',   whatsapp_phone_number: '+5548999990000' }
+    { full_name: 'Bob Costa',   email: 'bob@example.com' }
   ],
   message:    'Please sign.',
-  expires_at: '2026-12-31T23:59:00Z'
+  expires_at: '2099-12-31T23:59:00Z'
 )
 
 puts result[:document]['id']
@@ -841,10 +862,16 @@ ASSINAFY_API_KEY=... \
 ASSINAFY_ACCOUNT_ID=... \
 ASSINAFY_TEST_EMAIL=recipient1@example.com \
 ASSINAFY_TEST_EMAIL2=recipient2@example.com \
+ASSINAFY_TEMPLATE_ID=configured-template-id \
 ASSINAFY_BASE_URL=https://sandbox.assinafy.com.br/v1 \
 bundle exec rspec spec/integration
 ```
 
+`ASSINAFY_TEMPLATE_ID` must identify a sandbox template with a `Signer` role configured in the
+application. Without it, the positive template-generation example is skipped. Supply different test
+recipients for its roles. OAuth browser consent is tested separately with a registered app, an HTTPS
+callback, and the matching authorization server; sandbox keys are not production OAuth credentials.
+
 > These tests create and clean up real resources and, for the assignment flow, send real signature-request emails to the addresses in `ASSINAFY_TEST_EMAIL` / `ASSINAFY_TEST_EMAIL2`.
 
 ## Contributing

data/README.md

@@ -83,6 +83,7 @@ A Assinafy aceita três credenciais. Escolha pela pergunta "**quem** está agind
 
 ```ruby
 require 'assinafy'
+require 'logger'
 
 client = Assinafy::Client.new(
   api_key:        ENV.fetch('ASSINAFY_API_KEY'),
@@ -127,7 +128,7 @@ O caminho mais curto do PDF até o pedido de assinatura:
 ```ruby
 resultado = client.upload_and_request_signatures(
   source:  './contrato.pdf',
-  signers: [{ full_name: 'Ana Silva', email: 'ana@exemplo.com.br' }],
+  signers: [{ full_name: 'Ana Silva', email: 'ana@example.com' }],
   message: 'Por favor, assine o contrato em anexo.'
 )
 
@@ -192,18 +193,20 @@ Erros de rede durante a espera são tolerados e reprocessados; um status termina
 ```ruby
 signatario = client.signers.create(
   full_name:             'Ana Silva',
-  email:                 'ana@exemplo.com.br',
-  whatsapp_phone_number: '+5511999999999',  # obrigatório para verificação por WhatsApp
-  government_id:         '00000000000'      # obrigatório para certificado digital
+  email:                 'ana@example.com',
+  whatsapp_phone_number: '+5500000000000'   # substitua por um número de teste válido
 )
 signatario['id'] # => "19e6b92e7895332ed9708535d8c"
+
+# Para certificado digital, cadastre o CPF/CNPJ real autorizado antes do assignment:
+client.signers.update(signatario['id'], government_id: ENV.fetch('ASSINAFY_SIGNER_GOVERNMENT_ID'))
 ```
 
 Signatários pertencem à conta e podem ser reaproveitados entre documentos:
 
 ```ruby
-existente = client.signers.find_by_email('ana@exemplo.com.br')  # paginação percorrida pelo SDK
-signatario = existente || client.signers.create(full_name: 'Ana Silva', email: 'ana@exemplo.com.br')
+existente = client.signers.find_by_email('ana@example.com')  # paginação percorrida pelo SDK
+signatario = existente || client.signers.create(full_name: 'Ana Silva', email: 'ana@example.com')
 ```
 
 ### 4.4 Estimar o custo (opcional, recomendado)
@@ -233,7 +236,7 @@ assignment = client.assignments.create(
     { id: signatario['id'], verification_method: 'Email', notification_methods: ['Email'], step: 1 }
   ],
   message:        'Por favor, assine o contrato em anexo.',
-  expires_at:     '2026-12-31T23:59:00Z',
+  expires_at:     '2099-12-31T23:59:00Z',
   copy_receivers: []                       # IDs que só recebem cópia
 )
 
@@ -241,8 +244,9 @@ assignment['signing_urls']
 # => [{ 'signer_id' => '19e6b...', 'url' => 'https://.../sign/...' }]
 ```
 
-`step` define a ordem: todos do passo 1 assinam antes do passo 2. Omita para assinatura
-simultânea.
+`step` define a ordem: todos do passo 1 assinam antes do passo 2. Se informado para um
+signatário, informe para todos, em uma sequência contínua iniciada em 1. Omita para assinatura
+simultânea. `expires_at` deve ter fuso horário e estar pelo menos uma hora no futuro.
 
 **`collect`** — campos posicionados página a página.
 
@@ -349,7 +353,7 @@ client.assignments.resend_notification(documento['id'], assignment['id'], signat
 Estender o prazo:
 
 ```ruby
-client.assignments.reset_expiration(documento['id'], assignment['id'], '2027-01-31T23:59:00Z')
+client.assignments.reset_expiration(documento['id'], assignment['id'], '2099-01-31T23:59:00Z')
 ```
 
 Para acompanhar sem polling, use [webhooks](#8-webhooks).
@@ -417,7 +421,7 @@ session[:assinafy_issuer]        = Assinafy::OAuth::AUTHORIZATION_SERVER # emiss
 
 redirect_to Assinafy::OAuth.authorization_url(
   client_id:     ENV.fetch('ASSINAFY_CLIENT_ID'),
-  redirect_uri:  'https://app.exemplo.com.br/oauth/callback',
+  redirect_uri:  'https://app.example.com/oauth/callback',
   code_verifier: verificador,
   scope:         %w[documents:read documents:write offline_access],
   state:         state
@@ -442,7 +446,7 @@ tokens = Assinafy::Client.new.oauth.exchange_code(
   code:          params.fetch(:code),
   client_id:     ENV.fetch('ASSINAFY_CLIENT_ID'),
   code_verifier: session.delete(:assinafy_code_verifier),
-  redirect_uri:  'https://app.exemplo.com.br/oauth/callback'
+  redirect_uri:  'https://app.example.com/oauth/callback'
 )
 
 tokens['access_token']   # => "..."
@@ -533,6 +537,13 @@ servidor['token_endpoint']                    # => "https://api.assinafy.com.br/
 servidor['code_challenge_methods_supported']  # => ["S256"]
 ```
 
+### Clientes internos de serviço
+
+O servidor também publica o grant RFC 8693 `urn:ietf:params:oauth:grant-type:token-exchange`.
+Ele é reservado a clientes confidenciais internos provisionados pela Assinafy; aplicativos de
+marketplace usam autorização com PKCE e renovação. O método `client.oauth.token` aceita esse grant,
+com `client_secret`, `subject_token`, `subject_token_type` e `resource`. Ele não emite refresh token.
+
 ### Erros OAuth
 
 Os endpoints OAuth respondem com o objeto plano da RFC 6749, não com o envelope da API. O SDK
@@ -572,7 +583,7 @@ Os valores aceitos estão publicados em
 valida localmente: um valor fora do enum levanta `ValidationError` **antes** de a requisição
 sair — e portanto antes de qualquer signatário ser criado para aquele assignment.
 
-Combinações permitidas: `Email` → notifica por `Email`; `Whatsapp` → notifica por `Whatsapp`;
+Informe exatamente um canal em `notification_methods`. Combinações permitidas: `Email` → notifica por `Email`; `Whatsapp` → notifica por `Whatsapp`;
 `DigitalCertificate` → notifica por `Email` **ou** `Whatsapp`.
 
 ### Certificado digital ICP-Brasil (A1/A3)
@@ -590,7 +601,7 @@ client.assignments.create(
 )
 ```
 
-Antes de abrir o assignment, o signatário precisa confirmar os dados de identidade e aceitar os
+Antes de concluir a assinatura, o signatário precisa confirmar os dados de identidade e aceitar os
 termos. O endpoint comum de assinatura **rejeita** signatários por certificado — a assinatura
 deles é produzida por um handshake de dois passos com a extensão Web PKI:
 
@@ -603,7 +614,8 @@ POST /v1/signers/certificate/complete  → data.signerName
 > Essas duas rotas são extensões que **não constam do documento OpenAPI publicado**: a
 > autenticação e os esquemas de requisição/resposta delas não são documentados. Como envolveria
 > adivinhar o payload, o SDK **não** expõe essas duas chamadas — fale com a Assinafy antes de
-> habilitar o fluxo em produção.
+> integrar essas rotas diretamente. Para A1/A3, direcione o signatário ao fluxo hospedado
+> de assinatura da Assinafy usando `assignment['signing_urls']`.
 
 Concluído o fluxo, baixar o artefato `pades` devolve a assinatura PAdES qualificada.
 
@@ -624,15 +636,19 @@ client.templates.download_page(template['id'], pagina_id)
 client.templates.delete(template['id'])
 ```
 
-Gerar um documento a partir de um template:
+Configure os papéis e campos no aplicativo Assinafy antes de gerar documentos. O upload cria
+um papel `Editor`; a geração exige pelo menos um papel `Signer`. Use um signatário já existente
+e diferente para cada papel. `role_id` vem de `template['roles']`, e `id` é o ID do signatário.
+
+Gerar um documento a partir de um template com um único papel `Signer`:
 
 ```ruby
 client.documents.estimate_cost_from_template(
-  template['id'], [{ full_name: 'Ana Silva', email: 'ana@exemplo.com.br' }]
+  template['id'], [{ role_id: 'papel-assinante-id', id: signatario['id'] }]
 )
 
 documento = client.documents.create_from_template(
-  template['id'], [{ full_name: 'Ana Silva', email: 'ana@exemplo.com.br' }]
+  template['id'], [{ role_id: 'papel-assinante-id', id: signatario['id'] }]
 )
 ```
 
@@ -641,7 +657,7 @@ documento = client.documents.create_from_template(
 Definições de campo reutilizáveis, com validação opcional por regex:
 
 ```ruby
-campo = client.fields.create(name: 'CPF', type: 'text', regex: '\A\d{11}\z')
+campo = client.fields.create(name: 'CPF', type: 'text', regex: '/^\d{11}$/')
 client.fields.types      # tipos de campo disponíveis
 client.fields.list
 client.fields.validate(campo['id'], '12345678901')
@@ -673,9 +689,9 @@ Registrar a assinatura de eventos da conta:
 client.webhooks.list_event_types  # eventos disponíveis
 
 client.webhooks.register(
-  url:       'https://app.exemplo.com.br/webhooks/assinafy',
-  email:     'ops@exemplo.com.br',   # para avisos de falha de entrega
-  events:    %w[document.completed signer.declined],
+  url:       'https://app.example.com/webhooks/assinafy',
+  email:     'ops@example.com',   # para avisos de falha de entrega
+  events:    %w[document_ready document_prepared signer_signed_document],
   is_active: true
 )
 
@@ -685,20 +701,22 @@ client.webhooks.list_dispatches
 client.webhooks.retry_dispatch(dispatch_id)
 ```
 
-Verificar a assinatura HMAC-SHA256 do payload recebido:
+A API não publica um esquema de assinatura para os webhooks enviados. O verificador HMAC-SHA256
+local é opcional: use-o quando um gateway seu assina o corpo bruto com um segredo compartilhado.
+O cabeçalho abaixo é inserido por esse gateway, e não pela Assinafy:
 
 ```ruby
 verificador = client.webhook_verifier   # usa o webhook_secret do cliente
 
 post '/webhooks/assinafy' do
   corpo      = request.body.read
-  assinatura = request.env['HTTP_X_ASSINAFY_SIGNATURE']
+  assinatura = request.env['HTTP_X_WEBHOOK_SIGNATURE']
 
   halt 401 unless verificador.verify(corpo, assinatura)
 
   evento = verificador.extract_event(corpo)
   case verificador.event_type(evento)
-  when 'document.completed' then processar(verificador.event_data(evento))
+  when 'signer_signed_document' then processar(verificador.event_object(evento))
   end
 
   200
@@ -853,6 +871,20 @@ método novo chega à gem sem uma.
 - [CHANGELOG.md](CHANGELOG.md) — histórico de versões
 - [Documentação da API](https://api.assinafy.com.br/v1/docs)
 
+## Desenvolvimento e testes
+
+```bash
+bundle exec rake spec
+bundle exec rubocop
+bundle exec bundler-audit check --update
+rbs -I sig validate
+ruby scripts/check_api_contract.rb
+```
+
+A [suíte sandbox](spec/integration/live_sandbox_spec.rb) fica fora da execução padrão.
+Veja os [pré-requisitos e variáveis](README.en.md#live-integration-tests), incluindo um template
+com papel `Signer` para testar a geração. Os testes enviam e-mails e removem os recursos criados.
+
 ## Licença
 
 Distribuído sob a licença [MIT](LICENSE).