Class: Assinafy::Resources::SignerDocumentResource

Inherits:
BaseResource
  • Object
show all
Defined in:
lib/assinafy/resources/signer_document_resource.rb,
sig/assinafy.rbs

Overview

Signer-authenticated views over a signer's assigned documents.

Authentication varies by endpoint (verified against the live API):

See https://api.assinafy.com.br/v1/docs#signer for the full documentation of these endpoints.

Constant Summary

Constants inherited from BaseResource

BaseResource::AUTH_HEADERS, BaseResource::PAGINATION_HEADERS, BaseResource::PATH_SEGMENT

Instance Method Summary collapse

Methods inherited from BaseResource

#initialize

Constructor Details

This class inherits a constructor from Assinafy::Resources::BaseResource

Instance Method Details

#current(signer_id, signer_access_code:) ⇒ Hash Also known as: document

Fetch the signer's "current" document (the one referenced by the access code).

Resolves the document, assignment, and current signer directly from the access code; it does not require code verification or data confirmation. The shape mirrors the signing endpoints, and assignment.items is filtered to only the current signer's items.

Examples:

Fetch the document tied to an access code

doc = client.signer_documents.current('signer-id', signer_access_code: 'signer-access-code')

# => {
#   "id"             => "document-id",
#   "account_id"     => "account-id",
#   "name"           => "my_document.pdf",
#   "status"         => "metadata_ready",
#   "artifacts"      => { "original" => "https://...", "thumbnail" => "https://..." },
#   "is_closed"      => false,
#   "signing_url"    => "https://app.assinafy.com.br/sign/doc1",
#   "decline_reason" => nil,
#   "declined_by"    => nil,
#   "created_at"     => "2023-07-21T13:43:17Z",
#   "updated_at"     => "2023-07-21T13:43:17Z",
#   "current_signer" => { "id" => "signer-id", "full_name" => "Signer Name",
#                         "email" => "signer@example.com",
#                         "verification_method" => "Email", "notification_methods" => ["Email"] },
#   "assignment"     => { "id" => "1", "method" => "virtual", "items" => [{ ... }] }
#   # ... (see docs for full shape)
# }

Parameters:

  • signer_id (String)
  • signer_access_code (String)
  • signer_access_code: (String)

Returns:

  • (Hash) —

    the document (envelope data unwrapped)

See Also:

  • /signers/{signer_id}/document


50
51
52
53
54
55
56
57
 
# File 'lib/assinafy/resources/signer_document_resource.rb', line 50

def current(signer_id, signer_access_code:)
  sid         = require_id(signer_id, 'Signer ID')
  access_code = require_signer_access_code(signer_access_code)

  call('Failed to fetch signer document') do
    http_get("signers/#{sid}/document", { signer_access_code: access_code }, workspace_auth: false)
  end
end

#decline_multiple(document_ids, decline_reason:, signer_access_code:) ⇒ Array

Decline multiple documents in a single call.

Examples:

Decline two documents with a reason

client.signer_documents.decline_multiple(%w[document-1 document-2],
                                         decline_reason: 'Unfavorable terms.',
                                         signer_access_code: 'signer-access-code')

# Request body the SDK sends:
#   { "document_ids": ["document-1", "document-2"], "decline_reason": "Unfavorable terms." }

# => []

Parameters:

  • document_ids (Array<String>)
  • decline_reason (String)
  • signer_access_code (String)

Returns:

  • (Array) —

    empty array on success (envelope data unwrapped)

See Also:

  • /signers/documents/decline-multiple


183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/assinafy/resources/signer_document_resource.rb', line 183

def decline_multiple(document_ids, decline_reason:, signer_access_code:)
  ids         = require_array(document_ids, 'Document IDs').map { |id| require_id(id, 'Document ID') }
  reason      = require_string(decline_reason, 'Decline reason')
  access_code = require_signer_access_code(signer_access_code)

  call_array('Failed to decline documents') do
    http_put('signers/documents/decline-multiple',
             body_params(document_ids: ids, decline_reason: reason),
             { signer_access_code: access_code }, workspace_auth: false)
  end
end

#download(signer_id, document_id, artifact_name = 'certificated', signer_access_code: nil) ⇒ String

Download an artifact for one of the signer's documents.

This endpoint is public (no auth required) — only the document and artifact IDs are needed — so signer_access_code: is optional and omitted from the query when nil.

Examples:

Download the original PDF and write it to disk (no access code needed)

pdf = client.signer_documents.download('signer-id', 'document-id', 'original')

# Response is the raw artifact body (Content-Type: application/pdf):
#   => "%PDF-1.7\n..." (binary string)
File.binwrite('document.pdf', pdf)

Parameters:

  • signer_id (String)
  • document_id (String)
  • artifact_name (String) (defaults to: 'certificated') —

    original, certificated, certificate-page, pades, or bundle

  • signer_access_code (String, nil) (defaults to: nil) —

    retained for call compatibility; validated when present but never transmitted by this public endpoint

Returns:

  • (String) —

    binary file body (ASCII-8BIT), e.g. the raw PDF bytes

See Also:

  • /signers/{signer_id}/documents/{document_id}/download/{artifact_name}


215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/assinafy/resources/signer_document_resource.rb', line 215

def download(signer_id, document_id, artifact_name = 'certificated', signer_access_code: nil)
  sid = require_id(signer_id, 'Signer ID')
  did = require_id(document_id, 'Document ID')
  art = require_id(artifact_name, 'Artifact name')
  unless DocumentResource::ARTIFACT_TYPES.include?(art)
    raise ValidationError.new('Invalid artifact type', { artifact_name: artifact_name })
  end

  require_signer_access_code(signer_access_code) unless signer_access_code.nil?

  call_binary('Failed to download signer document') do
    http_get("signers/#{sid}/documents/#{did}/download/#{art}", {}, workspace_auth: false)
  end
end

#list(signer_id, params = {}, signer_access_code: nil) ⇒ Hash{Symbol=>Array,Hash}

List all documents the signer has access to, with pagination metadata. This endpoint accepts either the workspace X-Api-Key header or the signer access code, so signer_access_code: is optional here; when nil it is omitted from the query and the header auth is used.

Examples:

List the signer's documents with pagination

page = client.signer_documents.list('signer-id',
                                    { page: 1, per_page: 15 },
                                    signer_access_code: 'signer-access-code')

# => {
#   data: [
#     {
#       "id"         => "document-id",
#       "account_id" => "account-id",
#       "name"       => "my_document.pdf",
#       "status"     => "metadata_ready",
#       "assignment" => { "id" => "1", "method" => "virtual", "signers" => [{ ... }],
#                         "items" => [{ ... }], "summary" => { "signer_count" => 2, ... } },
#       "artifacts"  => { "original" => "https://...", "thumbnail" => "https://..." },
#       "pages"      => [{ "id" => "...", "number" => 1, "height" => 1, "width" => 1,
#                          "download_url" => "https://..." }],
#       "is_closed"  => false
#       # ... (see docs for full shape)
#     }
#   ],
#   meta: { current_page: 1, per_page: 15, total: 1, last_page: 1 }
# }

Parameters:

  • signer_id (String)
  • params (Hash) (defaults to: {}) —

    documented page and per_page query parameters

  • signer_access_code (String, nil) (defaults to: nil)
  • signer_access_code: (String, nil) (defaults to: nil)

Returns:

  • (Hash{Symbol=>Array,Hash}) —

    { data: [...], meta: { current_page:, per_page:, total:, last_page: } }

See Also:

  • /signers/{signer_id}/documents


94
95
96
97
98
99
100
101
102
 
# File 'lib/assinafy/resources/signer_document_resource.rb', line 94

def list(signer_id, params = {}, signer_access_code: nil)
  sid                = require_id(signer_id, 'Signer ID')
  query, access_code = signer_query(params, signer_access_code)

  call_list('Failed to list signer documents') do
    http_get("signers/#{sid}/documents", query.merge(signer_access_code: access_code),
             workspace_auth: access_code.nil?)
  end
end

#search(signer_id, query, params = {}, signer_access_code: nil) ⇒ Hash{Symbol=>Array,Hash}

Lightweight search over the signer's documents. Like #list, this accepts either the workspace X-Api-Key header or the signer access code, so signer_access_code: is optional.

Examples:

Search the signer's documents

page = client.signer_documents.search('signer-id', 'contract')

# Request: GET /signers/{signer_id}/documents/search?search=contract
# => {
#   data: [
#     { "id" => "document-id", "account_id" => "account-id", "name" => "contract.pdf",
#       "status" => "pending_signature", "template_id" => nil,
#       "artifacts" => { "original" => "https://...", "thumbnail" => "https://..." },
#       "is_closed" => false, "signing_url" => "https://...", "tags" => []
#       # ... search returns the lightweight document shape (no embedded assignment)
#     }
#   ],
#   meta: nil
# }

Parameters:

  • signer_id (String)
  • query (String) —

    free-text search term

  • params (Hash) (defaults to: {}) —

    optional deployment-specific query parameters

  • signer_access_code (String, nil) (defaults to: nil)
  • signer_access_code: (String, nil) (defaults to: nil)

Returns:

  • (Hash{Symbol=>Array,Hash}) —

    { data: [...], meta: {..} | nil }

See Also:

  • /signers/{signer_id}/documents/search


129
130
131
132
133
134
135
136
137
138
 
# File 'lib/assinafy/resources/signer_document_resource.rb', line 129

def search(signer_id, query, params = {}, signer_access_code: nil)
  sid                  = require_id(signer_id, 'Signer ID')
  filters, access_code = signer_query(params, signer_access_code)

  call_list('Failed to search signer documents') do
    http_get("signers/#{sid}/documents/search",
             filters.merge(search: query, signer_access_code: access_code),
             workspace_auth: access_code.nil?)
  end
end

#sign_multiple(document_ids, signer_access_code:) ⇒ Array

Sign multiple virtual-method documents in a single call.

Each document must be prepared for the "virtual" signature method.

Examples:

Sign two documents at once

client.signer_documents.sign_multiple(%w[document-1 document-2],
                                          signer_access_code: 'signer-access-code')

# Request body the SDK sends:
#   { "document_ids": ["document-1", "document-2"] }

# => []

Parameters:

  • document_ids (Array<String>)
  • signer_access_code (String)
  • signer_access_code: (String)

Returns:

  • (Array) —

    empty array on success (envelope data unwrapped)

See Also:

  • /signers/documents/sign-multiple


156
157
158
159
160
161
162
163
164
165
 
# File 'lib/assinafy/resources/signer_document_resource.rb', line 156

def sign_multiple(document_ids, signer_access_code:)
  ids         = require_array(document_ids, 'Document IDs').map { |id| require_id(id, 'Document ID') }
  access_code = require_signer_access_code(signer_access_code)

  call_array('Failed to sign documents') do
    http_put('signers/documents/sign-multiple',
             body_params(document_ids: ids),
             { signer_access_code: access_code }, workspace_auth: false)
  end
end