在Ruby on Rails网页中嵌入DocuSign模板实现签署功能求助

Hey there! Sounds like you’ve already nailed the backend integration with the DocuSign gem—awesome progress! Let’s walk through how to implement that in-browser signing flow you’re after, since the embedded signing docs can be a bit scattered at first.

First, the core of what you need is DocuSign’s Embedded Sign Ceremony—this lets you generate a unique URL that loads the signing form directly in your app (either via a popup or iframe). Here’s how to wire it up:

1. Add a Backend Action to Generate the Signing URL #

You’ll need a controller method to call DocuSign’s API and fetch the embedded signing URL. This uses the envelope ID you already get when creating a signing request via the terminal.

class DocusignController < ApplicationController
  # Add authentication (e.g., Devise's before_action :authenticate_user!) if needed
  def create_embedded_sign_url
    envelope_id = params[:envelope_id]
    recipient_id = "1" # Match the recipient ID you used when creating the envelope

    # Reuse your existing DocuSign client configuration
    client = DocuSign_eSign::ApiClient.new
    client.configure do |config|
      config.host = Rails.application.config.docusign_host
      config.default_headers["Authorization"] = "Bearer #{current_user.docusign_access_token}"
    end

    # Build the recipient view request
    view_request = DocuSign_eSign::RecipientViewRequest.new(
      return_url: docusign_sign_complete_url, # Where users land after signing
      authentication_method: "None", # Adjust to "Email" if you need stricter auth
      email: current_user.email,
      user_name: current_user.name,
      recipient_id: recipient_id
    )

    # Fetch the signing URL from DocuSign
    envelope_api = DocuSign_eSign::EnvelopesApi.new(client)
    view_response = envelope_api.create_recipient_view(
      Rails.application.config.docusign_account_id,
      envelope_id,
      view_request
    )

    render json: { sign_url: view_response.url }
  end

  # Callback page after signing is completed
  def sign_complete
    # Add post-sign logic here (e.g., update database, send confirmation emails)
    render "sign_complete"
  end
end

2. Add Frontend Button & JavaScript #

Next, add a button to your view that triggers the signing flow. Use JavaScript to call your new backend endpoint, then load the signing URL either in a popup or iframe.

<!-- In your view template (e.g., app/views/documents/show.html.erb) -->
<div>
  <h3>Ready to sign your document?</h3>
  <button id="startSignBtn" data-envelope-id="<%= @document.envelope_id %>">
    Open Signing Form
  </button>
  <!-- Optional container if you want to embed the form directly -->
  <div id="signingContainer"></div>
</div>

<script>
document.getElementById('startSignBtn').addEventListener('click', async function() {
  const envelopeId = this.dataset.envelopeId;
  
  // Fetch the signing URL from your Rails backend
  const response = await fetch('/docusign/create_embedded_sign_url', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-CSRF-Token': '<%= form_authenticity_token %>' // Critical for Rails CSRF protection
    },
    body: JSON.stringify({ envelope_id: envelopeId })
  });

  const data = await response.json();

  // Option 1: Open signing in a new popup window
  window.open(data.sign_url, 'DocuSignSigning', 'width=850,height=700,top=100,left=100');

  // Option 2: Embed directly in an iframe (uncomment to use)
  // const iframe = document.createElement('iframe');
  // iframe.src = data.sign_url;
  // iframe.style.width = '100%';
  // iframe.style.height = '800px';
  // document.getElementById('signingContainer').appendChild(iframe);
});
</script>

3. Update Your Routes #

Add these routes to config/routes.rb to map your controller actions:

Rails.application.routes.draw do
  # ... your existing routes ...
  post '/docusign/create_embedded_sign_url', to: 'docusign#create_embedded_sign_url'
  get '/docusign/sign_complete', to: 'docusign#sign_complete'
end

4. Key Things to Double-Check #

• Envelope Status: The envelope must be in sent state (not draft) to generate a signing URL. Ensure your existing backend code marks the envelope as sent when creating it.
• App Permissions: In your DocuSign Developer account, make sure your app has the signature scope enabled—this is required for embedded signing.
• Iframe Restrictions: If using an iframe, add your app’s domain to DocuSign’s Frame Ancestors list (under "Settings" > "App and Keys") to avoid browser security blocks.
• Error Handling: Add try/catch blocks in your controller and frontend to handle failures (e.g., invalid envelope ID, expired access token).

Once you’ve got this set up, clicking the button should load the DocuSign signing form directly in your app—no need for users to leave your website!

内容的提问来源于stack exchange，提问作者M. Straw