DocuSign E-Signature Integration

The Portal uses DocuSign for electronic signature workflows, primarily for bills utility forms that require tenant signatures.

DocusignService

File: app/Services/DocusignService.php Package: docusign/esign-client (v8.0+)

Configuration

DOCUSIGN_URL=                    # OAuth base URL (e.g., account-d.docusign.com)
DOCUSIGN_API_URL=                # API base URL (e.g., https://demo.docusign.net/restapi)
DOCUSIGN_INTEGRATION_KEY=       # Integration/client key
DOCUSIGN_USER_ID=                # Impersonated user ID
DOCUSIGN_ACCOUNT_ID=             # DocuSign account ID
DOCUSIGN_PRIVATE_KEY=            # RSA private key for JWT authentication

All configured in config/app.php under docusign_* keys.

Authentication

Uses JWT (JSON Web Token) grant for server-to-server authentication:

1. Loads RSA private key from environment
2. Requests a JWT user token from DocuSign OAuth
3. Token is valid for 120 seconds
4. Authentication happens on every service instantiation (no token caching)

The getAuthenticaiton() method (note: typo in codebase) handles the full JWT flow.

Methods

makeEnvelope($utilityForm, $tenants)

Creates and sends a DocuSign envelope for signing.

Parameters:

• $utilityForm — HTML content of the utility form document
• $tenants — Array of tenant objects with email, name, and dob values

Process:

1. Base64-encodes the HTML form as a DocuSign document
2. Creates a signer for each tenant with:
   • Signature anchor: [{index}_SIGNATURE]
   • Date anchor: [{index}_DATE]
   • DOB anchor: [{index}_DOB] (only if DOB not already provided)
3. Creates an envelope definition with status sent (sends immediately)
4. Email subject: “Housr Bills Utility Form - Signature Required”

Returns the DocuSign EnvelopeResults object containing the envelope ID.

getBatchDocumentStatuses($documents)

Checks the signing status of multiple envelopes in batch.

Parameters:

• $documents — Laravel collection with envelope_id field

Returns: A collection keyed by envelope ID, each containing:

• status — Envelope status (e.g., “Sent”, “Completed”)
• completed — Count of signers who have completed
• total — Total number of signers
• signers — Array of signer details (name, email, status, completed flag)

Uses EnvelopesApi::listStatusChanges() with envelope IDs, then fetches recipient details for each envelope.

Usage

The DocuSign integration is used in the bills workflow:

1. Admin/system generates a utility form HTML document with anchor tags for each tenant
2. makeEnvelope() sends the document to all tenants for signature
3. getBatchDocumentStatuses() polls for completion status
4. The Portal displays signing progress in the documents/bills UI

Error Handling

• Authentication failures throw exceptions with descriptive messages
• Missing configuration throws \Exception with the specific missing variable
• Envelope creation errors are logged via error_log()
• Batch status errors return an empty collection gracefully