unclaimed_draft.rb in hellosign-ruby-sdk-3.7.1

- old
+ new

@@ -23,51 +23,56 @@
 #
 
 module HelloSign
   module Api
 
-    #
-    # Contains all the api calls for the UnclaimedDraft resource.
-    # Take a look at our {https://app.hellosign.com/api/reference#UnclaimedDraft unclaimed draft document}
-    # for more information about this.
-    #
-    # @author [hellosign]
-    #
-    module UnclaimedDraft
-
       #
-      # Creates a new Draft that can be claimed using the claim URL.
-      # The first authenticated user to access the URL will claim the Draft and will be shown either the "Sign and send" or the "Request signature" page with the Draft loaded.
-      # Subsequent access to the claim URL will result in a 404 not found.
-      # If the type is "send_document" then only the file parameter is required.
-      # If the type is "request_signature", then the identities of the signers and optionally
-      # the location of signing elements on the page are also required.
-      # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1.
-      # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
-      # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
-      # @option opts [String] type The type of unclaimed draft to create. Use "send_document" to create a claimable file, and "request_signature" for a claimable signature request. If the type is "request_signature" then signers name and email_address are not optional.
-      # @option opts [String] subject The subject in the email that will be sent to the signers.
-      # @option opts [String] message The custom message in the email that will be sent to the signers.
-      # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional)
+      # Contains all the API calls for the UnclaimedDraft resource.
+      # Take a look at our API documentation for creating UnclaimedDrafts (https://app.hellosign.com/api/reference#UnclaimedDraft)
+      # for more information about this.
       #
-      # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys:
-      #   * :name (String) Sender' name
-      #   * :email_address (String) Sender's email address
-      #   * :order (Integer) The order the signer is required to sign in (optional)
-      #   * :pin (Integer) The 4-digit code that will secure this signer's signature page. You must have a business plan to use this feature. (optional)
-      # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed.
-      # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the document with Text Tags.
-      # @option opts [String] form_fields_per_document
+      # @author [hellosign]
       #
-      # @return [HelloSign::Resource::UnclaimedDraft] a UnclaimedDraft object
+      module UnclaimedDraft
+
       #
-      # @example send_document
+      # Creates a new UnclaimedDraft that can be claimed using the claim_url.
+      # The first authenticated user to access the claim_url claims the Draft and will be shown either the "Sign and send" or the "Request signature" page with the Draft loaded.
+      # Subsequent access to the claim_url will result in a 404 not found error.
+      # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional)
+      # @option opts [Array<String>] files Specified file path(s) to upload file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [Array<String>] file_urls URL(s) for HelloSign to download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [String] type The type of UnclaimedDraft to create. Use "send_document" to create a claimable file, and "request_signature" for a claimable signature request.
+      #   * For "send_document," only the file parameter is required.
+      #   * For "request_signature," then signer name and email_address are required.
+      # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional)
+      # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional)
+      # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys: (optional)
+      #   * :name (String) Signer's name
+      #   * :email_address (String) Signer's email address
+      #   * :order (Integer) The order the signers are required to sign in (optional)
+      # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the document with Text Tags or form_fields_per_document (optional)
+      #   * :name (String) Custom field name or "Field Label"
+      #   * :value (String) The value of the field. This data will appear on the SignatureRequest.
+      # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed. (optional)
+      # @option opts [String] signing_redirect_url The URL you want the signer(s) redirected to after they successfully sign. (optional)
+      # @option opts [Boolean] use_text_tags Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional)
+      # @option opts [Boolean] hide_text_tags Indicates whether the Text Tags should be removed automatically. Note that this is not the preferred method. Defaults to 0. (optional)
+      # @option opts [Boolean] use_preexisting_fields Sets the detection of predefined PDF fields. Defaults to 0. (optional)
+      # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional)
+      # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional)
+      # @option opts [Boolean] allow_reassign Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)
+      # @option opts [Array<Hash>] form_fields_per_document The fields that should appear on the document. (optional)
+      #
+      # @return [HelloSign::Resource::UnclaimedDraft] an UnclaimedDraft object
+      #
+      # @example type: send_document
       #   unclaimed_draft = @client.create_unclaimed_draft(
       #     :test_mode => 1,
       #     :files => ['NDA.pdf', 'AppendixA.pdf']
       #   )
-      # @example request_signature
+      # @example type: request_signature
       #   unclaimed_draft = @client.create_unclaimed_draft(
       #     :test_mode => 1,
       #     :type => 'request_signature',
       #     :subject => 'The NDA we talked about',
       #     :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
@@ -100,31 +105,42 @@
 
         HelloSign::Resource::UnclaimedDraft.new post('/unclaimed_draft/create', :body => opts)
       end
 
       #
-      # Creates a new embedded unclaimed draft object that can be launched in an iframe using the claim URL.
-      # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1.
-      # @option opts [Integer] is_for_embedded_signing set this to 1 to to mix embedded requesting and embedded signing.
-      # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
-      # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
-      # @option opts [String] type The type of unclaimed draft to create. Should be "request_signature" for a claimable signature request. If the type is "request_signature" then signers name and email_address are not optional.
-      # @option opts [String] subject The subject in the email that will be sent to the signers.
-      # @option opts [String] requester_email_address The email address of the requester.
-      # @option opts [String] message The custom message in the email that will be sent to the signers.
+      # Creates a new Embedded UnclaimedDraft object that can be launched in an iFrame using the claim_url.
+      # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional)
+      # @option opts [String] client_id The API App Client ID associated with the UnclaimedDraft.
+      # @option opts [Array<String>] files Specified file path(s) to upload file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [Array<String>] file_urls URL(s) for HelloSign to download the file(s) to send for signature. Currently we only support use of either the files parameter or file_urls parameter, not both.
+      # @option opts [String] requester_email_address The email address of the requester, if "request_signature" type.
+      # @option opts [String] type The type of UnclaimedDraft to create. Use "send_document" to create a claimable file, and "request_signature" for a claimable signature request.
+      #   * For "send_document," only the file parameter is required.
+      #   * For "request_signature," then signer name and email_address are required.
+      # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional)
+      # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional)
+      # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys: (optional)
+      #   * :name (String) Signer's name
+      #   * :email_address (String) Signer's email address
+      #   * :order (Integer) The order the signers are required to sign in (optional)
+      # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed. (optional)
       # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional)
+      # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the document with Text Tags or form_fields_per_document (optional)
+      #   * :name (String) Custom field name or "Field Label"
+      #   * :value (String) The value of the field. This data will appear on the SignatureRequest.
+      # @option opts [Boolean] use_text_tags Indicates whether the SignatureRequest should have Text Tags enabled. Defaults to 0. (optional)
+      # @option opts [Boolean] hide_text_tags Indicates whether the Text Tags should be removed automatically. Note that this is not the preferred method. Defaults to 0. (optional)
+      # @option opts [Boolean] use_preexisting_fields Sets the detection of predefined PDF fields. Defaults to 0. (optional)
+      # @option opts [Boolean] is_for_embedded_signing Enable the UnclaimedDraft to be used for an Embedded SignatureRequest. Defaults to 0. (optional)
+      # @option opts [Boolean] skip_me_now Disables the "Me (Now)" option for the preparer. Not available for type "send_document." Defaults to 0. (optional)
+      # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional)
+      # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional)
+      # @option opts [Boolean] allow_reassign Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)
+      # @option opts [Array<Hash>] form_fields_per_document The fields that should appear on the document. (optional)
       #
-      # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys:
-      #   * :name (String) Sender' name
-      #   * :email_address (String) Sender's email address
-      #   * :order (Integer) The order the signer is required to sign in (optional)
-      #   * :pin (Integer) The 4-digit code that will secure this signer's signature page. You must have a business plan to use this feature. (optional)
-      # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed.
-      # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present on the document with Text Tags.
+      # @return [HelloSign::Resource::UnclaimedDraft] an UnclaimedDraft object
       #
-      # @return [HelloSign::Resource::UnclaimedDraft] a UnclaimedDraft object
-      #
       # @example request_signature
       #   unclaimed_draft = @client.create_embedded_unclaimed_draft(
       #     :test_mode => 1,
       #     :type => 'request_signature',
       #     :subject => 'The NDA we talked about',
@@ -150,36 +166,49 @@
       #
       def create_embedded_unclaimed_draft(opts)
         opts[:client_id] ||= self.client_id
         prepare_files opts
         prepare_custom_fields opts
-        
+
         if opts[:type] == 'request_signature' || opts[:type] == 'send_document'
           prepare_signers opts
         end
 
         HelloSign::Resource::UnclaimedDraft.new post('/unclaimed_draft/create_embedded', :body => opts)
       end
 
-
       #
-      # Creates a new embedded unclaimed draft object from a template that can be launched in an iframe using the claim URL.
-      # @option opts [Integer] test_mode (0) Whether this is a test, the signature request will not be legally binding if set to 1.
-      # @option opts [String] subject The subject in the email that will be sent to the signers.
-      # @option opts [String] requester_email_address The email address of the requester.
-      # @option opts [String] message The custom message in the email that will be sent to the signers.
+      # Creates a new Embedded UnclaimedDraft object from a Template that can be launched in an iFrame using the claim_url.
+      # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional)
+      # @option opts [String] client_id The API App Client ID associated with the UnclaimedDraft.
+      # @option opts [String] template_id The Template ID to use when creating the UnclaimedDraft.
+      #   * Use template_ids[%i%] if using multiple templates, replacing %i% with an integer to indicate the order of the Templates
+      # @option opts [String] requester_email_address The email address of the requester, if "request_signature" type.
+      # @option opts [String] title The title you want to assign to the SignatureRequest. (optional)
+      # @option opts [String] subject The subject in the email that will be sent to the signer(s). (optional)
+      # @option opts [String] message The custom message in the email that will be sent to the signer(s). (optional)
+      # @option opts [Array<Hash>] signers List of signers
+      #   * :role (String) The signer role indicated on the Template. Note that the role name is case sensitive.
+      #   * :name (String) Signer's name
+      #   * :email_address (String) Signer's email address
+      # @option opts [Array<Hash>] ccs The individual(s) to be CC'd on the SignatureRequest. Required when a CC role exists for the Template.
+      #   * :role (String) The CC role indicated on the Template. Note that the role name is case sensitive.
+      #   * :email_address (String) CC Recipient's email address
       # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional)
+      # @option opts [String] requesting_redirect_url The URL you want the requester redirected to after they successfully request a SignatureRequest. (optional)
+      # @option opts [Hash] metadata Key-value data attached to the SignatureRequest. (optional)
+      # @option opts [Array<Hash>] custom_fields An array of custom merge fields, representing those present in the Template. (optional)
+      #   * :name (String) Custom field name or "Field Label"
+      #   * :value (String) The value of the field. This data will appear on the SignatureRequest.
+      # @option opts [Array<String>] files Use files to indicate the uploaded file(s) to append to the SignatureRequest. (optional)
+      # @option opts [Array<String>] file_urls Use file_urls to have HelloSign download the file(s) to append to the SignatureRequest. (optional)
+      # @option opts [Boolean] skip_me_now Disables the "Me (Now)" option for the preparer. Not available for type "send_document." Defaults to 0. (optional)
+      # @option opts [Boolean] allow_decline Allows signers to decline the SignatureRequest. Defaults to 0. (optional)
+      # @option opts [Boolean] allow_reassign Allows signers to reassign the SignatureRequest to another signer. Defaults to 0. (optional)
       #
-      # @option opts [Array<Hash>] signers List of signers, each item is a Hash with these keys:
-      #   * :name (String) Sender' name
-      #   * :email_address (String) Sender's email address
-      #   * :order (Integer) The order the signer is required to sign in (optional)
-      #   * :pin (Integer) The 4-digit code that will secure this signer's signature page. You must have a business plan to use this feature. (optional)
-      # @option opts [Array<String>] cc_email_addresses The email addresses that should be CCed.
+      # @return [HelloSign::Resource::UnclaimedDraft] an UnclaimedDraft object
       #
-      # @return [HelloSign::Resource::UnclaimedDraft] a UnclaimedDraft object
-      #
       # @example request_signature
       #   unclaimed_draft = @client.create_embedded_unclaimed_draft_with_template(
       #     :test_mode => 1,
       #     :subject => 'The NDA we talked about',
       #     :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
@@ -216,9 +245,28 @@
         prepare_templates opts
         prepare_files opts
         HelloSign::Resource::UnclaimedDraft.new post('/unclaimed_draft/create_embedded_with_template', :body => opts)
       end
 
+      #
+      # Creates a new SignatureRequest from an Embedded UnclaimedDraft. This UnclaimedDraft can be
+      # edited using the claim_url.
+      # @option opts [String] signature_request_id The SignatureRequest ID to edit and resend.
+      # @option opts [String] client_id The API App Client ID associated with the UnclaimedDraft.
+      # @option opts [Boolean] test_mode Indicates if this is a test SignatureRequest, it will not be legally binding if set to 1. A boolean value is also accepted. Defaults to 0. (optional)
+      # @option opts [String] requesting_redirect_url The URL you want the requester redirected to after they successfully request a SignatureRequest. (optional)
+      # @option opts [String] signing_redirect_url The URL you want the signer redirected to after they successfully sign. (optional)
+      # @option opts [Boolean] is_for_embedded_signing Enable the UnclaimedDraft to be used for an Embedded SignatureRequest. Defaults to 0. (optional)
+      #
+      # @return [HelloSign::Resource::UnclaimedDraft] an UnclaimedDraft object
+      #
+      # @example
+      #   unclaimed_draft = @client.edit_and_resend_unclaimed_draft(
+      #     :signature_request_id => '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
+      #     :test_mode => 1,
+      #     :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
+      #   )
+      #
       def edit_and_resend_unclaimed_draft(opts)
         signature_request_id = opts.delete(:signature_request_id)
         path = "/unclaimed_draft/edit_and_resend/#{signature_request_id}"
         HelloSign::Resource::UnclaimedDraft.new post(path, :body => opts)
       end