Clicksign Ruby SDK

source 'https://rubygems.org'

gem 'clicksign-ruby-sdk'

require 'clicksign'

Clicksign.configure do |c|
  c.api_key  = ENV.fetch('CLICKSIGN_API_KEY')
  c.environment = :sandbox   # ou :production — define base_url automaticamente
  # c.base_url = '...'      # opcional: sobrescreve o URL do ambiente
  c.open_timeout  = 2       # segundos (padrão)
  c.read_timeout  = 10
  c.write_timeout = 10
  c.max_retries   = 0       # retentativas automáticas (ver seção abaixo)
end

conta_a = Clicksign::Services.new(
  api_key: ENV['CLICKSIGN_TOKEN_CONTA_A'],
  environment: :production,
  max_retries: 2
)

conta_b = Clicksign::Services.new(
  api_key: ENV['CLICKSIGN_TOKEN_CONTA_B'],
  environment: :sandbox
)

conta_a.use do
  Clicksign::Resources::Notarial::Envelope.create(name: 'Contrato A')
end

conta_b.use do
  Clicksign::Resources::Notarial::Envelope.filter(status: 'draft').to_a
end

class EnvelopesController < ApplicationController
  def create
    current_tenant.clicksign_service.use do
      envelope = Clicksign::Resources::Notarial::Envelope.create(envelope_params)
      render json: { id: envelope.id }
    end
  end
end

client = Clicksign::Client.new(
  api_key: ENV['CLICKSIGN_API_KEY'],
  base_url: 'https://sandbox.clicksign.com/api/v3',
  open_timeout: 2,
  read_timeout: 30,
  max_retries: 3
)

response = client.get('/envelopes', params: { 'filter[status]' => 'draft' })
client.post('/envelopes', body: { data: { type: 'envelopes', attributes: { name: 'Novo' } } })

Clicksign.configure do |c|
  c.api_key     = ENV['CLICKSIGN_API_KEY']
  c.environment = :production
  c.max_retries = 3
end

Clicksign.on_request do |event|
  # event: :method, :path, :status, :duration_ms, :attempt
  Rails.logger.info "[Clicksign] #{event[:method]} #{event[:path]} → #{event[:status]} (#{event[:duration_ms]}ms)"
end

Clicksign.on_retry do |event|
  # event: :method, :path, :attempt, :max_retries, :error, :wait_ms
  Rails.logger.warn "[Clicksign] retry #{event[:attempt]}/#{event[:max_retries]} em #{event[:wait_ms]}ms"
end

Clicksign.on_error do |event|
  # event: :method, :path, :error, :status, :duration_ms
  Sentry.capture_exception(event[:error])
end

require 'clicksign'

Clicksign.configure do |c|
  c.api_key  = ENV['CLICKSIGN_API_KEY']
  c.base_url = 'https://sandbox.clicksign.com/api/v3'
end

Envelope = Clicksign::Resources::Notarial::Envelope

# Listar com filtro
drafts = Envelope.filter(status: 'draft').to_a
puts drafts.map { |e| [e.id, e.name, e.status] }

# Criar envelope (status inicial: draft)
envelope = Envelope.create(
  name: 'Contrato de prestação de serviços',
  locale: 'pt-BR',
  auto_close: true
)

puts envelope.id    # UUID do envelope
puts envelope.status # => "draft"

found = Envelope.retrieve(envelope.id)
found.update(name: 'Contrato — revisão 2')

found.delete

Envelope = Clicksign::Resources::Notarial::Envelope
Folder   = Clicksign::Resources::Folder

# Opcional: associar a uma pasta
folder = Folder.filter(in_root: true).first
envelope = Envelope.create(
  name: 'Proposta comercial #1042',
  folder_id: folder&.id,
  deadline_at: '2026-12-31T23:59:59.000-03:00',
  default_subject: 'Documentos para assinatura',
  default_message: 'Por favor, assine os documentos em anexo.'
)

Document = Clicksign::Resources::Notarial::Document

document = Document.create(
  envelope_id: envelope.id,
  filename: 'contrato.pdf',
  content_base64: 'data:application/pdf;base64,JVBERi0xLjQK...'
)

# Alternativas (mutuamente exclusivas na API):
# content_url: 'https://exemplo.com/arquivo.pdf'
# template: { key: template_id, data: {} }  # filename deve ser .doc ou .docx

# Listar documentos do envelope
Envelope.list_documents(envelope.id).each do |doc|
  puts "#{doc.id} — #{doc.filename} (#{doc.status})"
end

Signer = Clicksign::Resources::Notarial::Signer

signer = Signer.create(
  envelope_id:      envelope.id,
  name:             'Maria Silva',
  email:            'maria.silva@example.com',
  phone_number:     '11999998888',
  has_documentation: true,
  documentation:    '12345678909',
  refusable:        true,
  communicate_events: {
    signature_request:  'email',   # canal de convite para assinar
    signature_reminder: 'email',   # canal de lembrete automático
    document_signed:    'email',   # canal de confirmação pós-assinatura
  },
)

# Reenviar notificação por e-mail
signer.notify(message: 'Lembrete: seu documento aguarda assinatura.')

# Ou via classe
Signer.notify(signer.id, envelope_id: envelope.id, message: 'Lembrete de assinatura')

Requirement = Clicksign::Resources::Notarial::Requirement

rels = {
  document: { data: { type: 'documents', id: document.id } },
  signer:   { data: { type: 'signers',   id: signer.id } },
}

# Concordância (agree)
agree = Requirement.create(
  envelope_id: envelope.id,
  action: 'agree',
  role: 'sign',
  relationships: rels
)

# Evidência de autenticação (ex.: e-mail)
Requirement.create(
  envelope_id: envelope.id,
  action: 'provide_evidence',
  auth: 'email',
  relationships: rels
)

# Rubrica em todas as páginas
Requirement.create(
  envelope_id: envelope.id,
  action: 'rubricate',
  pages: 'all',
  relationships: rels
)

# Rubrica em campo específico do documento
Requirement.create(
  envelope_id: envelope.id,
  action: 'rubricate',
  rubric_field: 'campo_rubrica_1',
  relationships: rels
)

# Consultar
Requirement.retrieve(agree.id, envelope_id: envelope.id)
Envelope.list_requirements(envelope.id, 'signer.key': signer.id)
Requirement.list_for_document(document.id)
Requirement.list_for_signer(signer.id)

# Remover (envelope em draft)
agree.delete

BulkRequirement = Clicksign::Resources::Notarial::BulkRequirement

response = BulkRequirement.create(envelope_id: envelope.id) do |ops|
  ops.add_agree(
    signer_id: signer.id,
    document_id: document.id,
    role: 'sign'
  )
  ops.add_provide_evidence(
    signer_id: signer.id,
    document_id: document.id,
    auth: 'email'
  )
  ops.add_rubricate(
    signer_id: signer.id,
    document_id: document.id,
    pages: 'all'
  )
  # ops.remove(requirement_id: requisito_antigo.id)
end

if response.success?
  response.requirements.each { |r| puts "OK: #{r.id} (#{r.action})" }
else
  response.failures.each do |failure|
    puts "Falha na operação #{failure.index}: #{failure.errors}"
  end
end

activated = envelope.update(status: 'running')
puts activated.status # => "running"

SignatureWatcher = Clicksign::Resources::Notarial::SignatureWatcher
Event            = Clicksign::Resources::Notarial::Event

watcher = SignatureWatcher.create(
  envelope_id: envelope.id,
  email: 'compliance@empresa.com',
  kind: 'all_steps',
  attach_documents_enabled: true
)

# Eventos do envelope
Envelope.list_events(envelope.id)

# Eventos de um documento
Document.list_events(document.id, envelope_id: envelope.id)

# Criar evento de imagem no documento (comprovante JPEG)
Event.create_add_image(
  envelope_id: envelope.id,
  document_id: document.id,
  title: 'Comprovante de identidade',
  occurred_at: Time.now.iso8601,
  content_base64: 'data:image/jpeg;base64,...'
)

# Criar evento customizado — token_email ou token_sms
Event.create_custom(
  envelope_id: envelope.id,
  document_id: document.id,
  kind: 'token_email',           # ou 'token_sms'
  occurred_at: Time.now.iso8601,
  signer_name: 'Maria Silva',
  signer_email: 'maria@empresa.com',
  # signer_phone_number: '11988887777'  # obrigatório quando kind: 'token_sms'
)

# API de baixo nível — qualquer name customizado
Event.create(
  envelope_id: envelope.id,
  document_id: document.id,
  name: 'custom',
  data: { kind: 'token_email', signer_name: 'Maria Silva',
          signer_email: 'maria@empresa.com', occurred_at: Time.now.iso8601 }
)

# Sem filtros — retorna Array imediatamente
Webhook.list

# Com filtros ou chain — começa em filter
Envelope.filter(status: 'draft').to_a

Envelope
  .filter(status: 'running', name: 'Contrato')
  .with_includes('folder')   # sideload JSON:API (.include('folder') também funciona)
  .order('-created')
  .page(1)
  .per(20)
  .to_a

Template.filter(name: 'NDA padrão').first

Envelope.order('-created').first
Envelope.filter(status: 'draft').count

envelope.name          # método gerado dinamicamente
envelope['name']       # equivalente via operador []
envelope['status']     # útil quando a chave é uma variável

Envelope.filter(status: 'draft').each { |e| puts e.id }
Envelope.filter(status: 'running').map(&:name)
Envelope.order('-created').select { |e| e.auto_close }

Webhook = Clicksign::Resources::Webhook

hook = Webhook.create(
  endpoint: 'https://minhaapp.com/webhooks/clicksign',
  events: %w[sign close cancel add_signer],
  status: 'active'
)

hook.update(status: 'inactive')
hook.delete

User       = Clicksign::Resources::User
Membership = Clicksign::Resources::Membership

eu = User.me
puts "#{eu.name} <#{eu.email}>"

novo = User.create(
  name: 'João Integração',
  email: 'joao.integracao@example.com',
  phone_number: '11988887777'
)

Membership.create(role: 'admin', user_id: novo.id)

EnvelopeBulkCreation = Clicksign::Resources::EnvelopeBulkCreation

job = EnvelopeBulkCreation.create(
  envelope: { name: 'Contrato Lote', locale: 'pt-BR', auto_close: true },
  document: {
    filename: 'contrato.docx',
    content_base64: 'data:application/msword;base64,...'
  },
  signers: [
    {
      name: 'Carlos',
      email: 'carlos@example.com',
      requirements: [{ action: 'agree', role: 'sign', auth: 'email' }]
    }
  ]
)

puts job.job_id      # UUID do job enfileirado
puts job.enqueued_at # timestamp de enfileiramento

AccessControlList = Clicksign::Resources::AccessControlList

AccessControlList.create(folder_id: folder.id, group_id: group.id)
AccessControlList.destroy(folder_id: folder.id, group_id: group.id)

begin
  Envelope.retrieve('00000000-0000-0000-0000-000000000000')
rescue Clicksign::NotFoundError
  puts 'Envelope não encontrado'
rescue Clicksign::ValidationError => e
  puts "Dados inválidos: #{e.message}"
  puts e.response_body
rescue Clicksign::RateLimitError => e
  puts "Aguarde reset em #{e.rate_limit_reset}" if e.retryable?
rescue Clicksign::AuthenticationError
  puts 'Verifique CLICKSIGN_API_KEY'
end

Clicksign.configure do |c|
  c.api_key     = ENV['CLICKSIGN_API_KEY']
  c.environment = :sandbox
end

# Ou em multi-conta:
service = Clicksign::Services.new(
  api_key: ENV['CLICKSIGN_API_KEY'],
  environment: :sandbox
)