📄 GET /api/v1/agreements/generate

• Purpose: Generate loan agreement PDF from template with customer-specific data
• When Called: On page load of CM09 screen
• Authentication: JWT Bearer token from login session
• Response Time: <1 second (template merge + PDF generation)
• Output: PDF URL + HTML preview text

GET /api/v1/agreements/generate?application_id=APP-2025-001234
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "request_id": "req_cm09_20251123_153000",
  "status": "success",
  "agreement": {
    "id": "AGR-2025-001234",
    "application_id": "APP-2025-001234",
    "pdf_url": "/api/v1/agreements/AGR-2025-001234/download",
    "preview_html": "
This Business Loan Agreement...
",
    "terms": {
      "principal": 150000,
      "apr": 4.5,
      "term_months": 36,
      "monthly_payment": 4440,
      "total_repayment": 159840
    },
    "generated_at": "2025-11-23T15:30:00Z"
  },
  "processing_time_ms": 847
}

✍️ POST /api/v1/signatures/submit

• Purpose: Submit signed agreement with signature image and legal confirmations
• When Called: When customer clicks "Submit Signed Agreement" button
• Content-Type: application/json
• Rate Limit: 5 requests/minute per user (prevent duplicate submissions)
• Response Time: <2 seconds (includes DocuSign API call)

POST /api/v1/signatures/submit
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "application_id": "APP-2025-001234",
  "agreement_id": "AGR-2025-001234",
  "signature_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...",
  "legal_confirmations": {
    "terms_understood": true,
    "information_accurate": true,
    "legally_binding": true,
    "credit_monitoring_consent": true
  },
  "signer_details": {
    "name": "John Smith",
    "signing_date": "2025-11-23",
    "ip_address": "86.134.45.123",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)"
  }
}

{
  "request_id": "req_cm09_20251123_153130",
  "status": "success",
  "signature": {
    "id": "SIG-2025-001234",
    "application_id": "APP-2025-001234",
    "agreement_id": "AGR-2025-001234",
    "docusign_envelope_id": "a7f3c5d9-e8b2-4a1c-9f6d-3e4b5a7c8d9e",
    "signed_at": "2025-11-23T15:31:30Z",
    "signed_pdf_url": "/api/v1/agreements/AGR-2025-001234/signed"
  },
  "next_step": {
    "screen": "CM10",
    "action": "view_confirmation",
    "message": "Application submitted successfully!"
  },
  "processing_time_ms": 1847
}

📥 GET /api/v1/agreements/{id}/download

• Purpose: Download unsigned agreement PDF
• Content-Type: application/pdf
• Authorization: Only document owner can download
• Response: PDF file with proper headers for browser download

📥 GET /api/v1/agreements/{id}/signed

• Purpose: Download signed agreement PDF (after signature submission)
• Content-Type: application/pdf
• Features: Includes DocuSign certificate of completion as final page
• Retention: Stored for 7 years (regulatory requirement)

🔐 Security & Validation

• Signature Validation: Verify signature image is not blank (minimum 100 pixels of ink)
• Checkbox Validation: All 4 legal confirmations must be true
• IP Capture: Record IP address for non-repudiation
• User Agent: Capture browser/device info for audit
• Timestamp: Record exact signing time with millisecond precision
• Idempotency: Duplicate submissions return same signature ID

📝 Agreement Generation Engine

• Template: Pre-approved legal template with merge fields
• Data Merge: Insert customer/loan data into template (principal, APR, term, etc.)
• PDF Generation: Convert HTML template to PDF using Puppeteer/wkhtmltopdf
• Validation: Ensure all required fields populated before generation
• Storage: Save unsigned PDF to S3 with unique agreement ID

async function generateAgreement(applicationId) {
  // 1. Get application data
  const app = await Application.findById(applicationId);
  
  // 2. Load legal template
  const template = await loadTemplate('business_loan_agreement.html');
  
  // 3. Merge data into template
  const mergedHtml = template
    .replace('{{principal}}', formatCurrency(app.chosen_amount))
    .replace('{{apr}}', app.apr)
    .replace('{{term_months}}', app.chosen_term_months)
    .replace('{{monthly_payment}}', formatCurrency(app.monthly_payment))
    .replace('{{borrower_name}}', app.company_name)
    .replace('{{company_number}}', app.company_number)
    .replace('{{loan_purpose}}', app.specific_use);
  
  // 4. Generate PDF
  const pdf = await htmlToPdf(mergedHtml);
  
  // 5. Upload to S3
  const agreementId = generateAgreementId();
  const s3Key = `agreements/${applicationId}/${agreementId}.pdf`;
  await s3.upload(s3Key, pdf);
  
  // 6. Save metadata to database
  await Agreement.create({
    id: agreementId,
    application_id: applicationId,
    s3_key: s3Key,
    status: 'unsigned'
  });
  
  return { agreementId, s3Key, html: mergedHtml };
}

✅ Signature Validation Rules

• Not Blank: Signature canvas must have at least 100 pixels of ink (prevent blank submissions)
• All Checkboxes: All 4 legal confirmations must be checked
• Valid Format: Signature must be valid base64-encoded PNG image
• Size Limit: Signature image <500KB (prevent huge files)
• Agreement Exists: Agreement ID must exist and be in "unsigned" status

function validateSignature(signatureData, confirmations) {
  // Check all confirmations are true
  if (!confirmations.terms_understood || 
      !confirmations.information_accurate ||
      !confirmations.legally_binding ||
      !confirmations.credit_monitoring_consent) {
    throw new ValidationError("All confirmations required");
  }
  
  // Check signature is not blank
  const image = decodeBase64Image(signatureData);
  const inkPixels = countNonWhitePixels(image);
  if (inkPixels < 100) {
    throw new ValidationError("Signature appears blank");
  }
  
  // Check signature size
  if (signatureData.length > 500000) {
    throw new ValidationError("Signature image too large");
  }
  
  return true;
}

🔄 Status Transition Logic

• Before Signature: application.status = "documents_uploaded" (from CM08)
• After Signature: application.status = "signed"
• Agreement Status: agreement.status = "signed" (from "unsigned")
• Next Status: "completed" (after CM10 confirmation)

📋 DocuSign Envelope Creation

• Purpose: Create legally-binding e-signature envelope with audit trail
• Process: Upload agreement PDF → Add signature tab → Send to signer → Capture signature → Return signed PDF
• Certificate: DocuSign appends "Certificate of Completion" page with audit trail
• Compliance: Meets ESIGN Act and eIDAS requirements

📨 DocuSign Embedded Signing Flow

• Step 1: Create envelope with PDF document
• Step 2: Add signer (customer name + email)
• Step 3: Generate embedded signing URL (recipient view)
• Step 4: Display DocuSign iframe in AINA app
• Step 5: Capture signature events via webhook
• Step 6: Download signed PDF from DocuSign

async function createDocuSignEnvelope(agreementId, signerDetails) {
  // 1. Get PDF from S3
  const pdfBytes = await s3.download(agreementS3Key);
  
  // 2. Create envelope definition
  const envelopeDefinition = {
    emailSubject: "Sign Your AINA Loan Agreement",
    documents: [{
      documentBase64: pdfBytes.toString('base64'),
      name: "Loan Agreement",
      fileExtension: "pdf",
      documentId: "1"
    }],
    recipients: {
      signers: [{
        email: signerDetails.email,
        name: signerDetails.name,
        recipientId: "1",
        routingOrder: "1",
        tabs: {
          signHereTabs: [{
            documentId: "1",
            pageNumber: "7", // Last page
            xPosition: "100",
            yPosition: "200"
          }]
        }
      }]
    },
    status: "sent"
  };
  
  // 3. Create envelope via DocuSign API
  const envelope = await docusign.createEnvelope(envelopeDefinition);
  
  // 4. Generate embedded signing URL
  const viewRequest = {
    returnUrl: "https://aina.app/cm10-confirmation",
    authenticationMethod: "none",
    email: signerDetails.email,
    userName: signerDetails.name
  };
  
  const view = await docusign.createRecipientView(envelope.envelopeId, viewRequest);
  
  return {
    envelopeId: envelope.envelopeId,
    signingUrl: view.url
  };
}

🔔 Webhook Event Handling

• Endpoint: POST /api/v1/webhooks/docusign
• Events: envelope-sent, envelope-completed, recipient-signed
• Verification: Validate webhook signature (HMAC SHA256)
• Processing: Update application status, download signed PDF, trigger notifications

async function handleDocuSignWebhook(event) {
  // Verify webhook signature
  const isValid = verifyWebhookSignature(event);
  if (!isValid) throw new SecurityError("Invalid webhook");
  
  if (event.event === "envelope-completed") {
    const envelopeId = event.data.envelopeId;
    
    // Download signed PDF from DocuSign
    const signedPdf = await docusign.downloadDocument(envelopeId);
    
    // Upload to S3
    const s3Key = `agreements/${applicationId}/${agreementId}_signed.pdf`;
    await s3.upload(s3Key, signedPdf);
    
    // Update database
    await Agreement.update(agreementId, {
      status: 'signed',
      signed_pdf_s3_key: s3Key,
      docusign_envelope_id: envelopeId,
      signed_at: new Date()
    });
    
    // Update application status
    await Application.update(applicationId, {
      status: 'signed'
    });
    
    // Send notifications
    await sendSignedConfirmation(applicationId);
  }
}

📊 Analytics & Monitoring

• Signing Metrics: Track time to sign, abandonment rate, completion rate
• DocuSign Latency: Monitor API response times
• Error Tracking: Alert on failed envelope creation, webhook failures
• Conversion: Track CM08 → CM09 → CM10 funnel

🔐 Security Measures

• Webhook Verification: Validate HMAC signature on all DocuSign webhooks
• TLS Encryption: All DocuSign API calls use TLS 1.3
• Access Tokens: OAuth 2.0 with JWT tokens (refresh every hour)
• IP Whitelist: Only accept webhooks from DocuSign IP ranges

✍️ DocuSign eSignature API

• Purpose: Legally-binding electronic signatures with audit trail
• API Version: DocuSign REST API v2.1
• Authentication: OAuth 2.0 JWT Grant (service account)
• Environment: Production (api.docusign.net)
• Account Type: Business Pro ($40/user/month)

💰 DocuSign Pricing & Limits

• Plan: Business Pro - $40/user/month
• Envelopes: Unlimited envelopes per month
• API Calls: Rate limit 1,000 calls/hour per account
• Storage: Signed documents stored for 10 years
• Support: 24/7 phone + email support
• SLA: 99.99% uptime guarantee

🔐 Legal Compliance

• ESIGN Act (US): Electronic Signatures in Global and National Commerce Act compliant
• eIDAS (EU): Qualified electronic signature standard (Advanced Electronic Signature)
• UETA (US): Uniform Electronic Transactions Act compliant
• UK eIDAS: UK Electronic Identification and Trust Services compliant
• Admissibility: DocuSign signatures admissible in court in 180+ countries

📄 API Endpoints Used

• POST /envelopes: Create new signature envelope
• POST /envelopes/{id}/views/recipient: Generate embedded signing URL
• GET /envelopes/{id}/documents/{docId}: Download signed PDF
• GET /envelopes/{id}: Get envelope status
• POST /connect: Configure webhooks (Connect)

🔄 Alternative Providers Considered

• Adobe Sign: Similar features, $30/user/month (slightly cheaper)
• HelloSign (Dropbox Sign): $15/user/month (budget option, fewer features)
• PandaDoc: $19/user/month (good for proposals, less for legal docs)
• SignNow: $8/user/month (very basic, no embedded signing)

📊 agreements Table Schema

📊 signatures Table Schema

CREATE TABLE agreements (
    id VARCHAR(50) PRIMARY KEY,
    application_id VARCHAR(50) NOT NULL REFERENCES applications(id),
    unsigned_pdf_s3_key VARCHAR(500) NOT NULL,
    signed_pdf_s3_key VARCHAR(500),
    status VARCHAR(20) DEFAULT 'unsigned',
    docusign_envelope_id VARCHAR(100),
    generated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    signed_at TIMESTAMP
);

CREATE TABLE signatures (
    id VARCHAR(50) PRIMARY KEY,
    agreement_id VARCHAR(50) NOT NULL REFERENCES agreements(id),
    signature_image_s3_key VARCHAR(500) NOT NULL,
    signer_name VARCHAR(200) NOT NULL,
    signer_ip_address VARCHAR(45) NOT NULL,
    signer_user_agent TEXT,
    signed_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP,
    legal_confirmations JSONB NOT NULL
);

CREATE INDEX idx_agreements_app ON agreements(application_id);
CREATE INDEX idx_signatures_agreement ON signatures(agreement_id);

💾 Insert Signature Record

INSERT INTO signatures (
    id,
    agreement_id,
    signature_image_s3_key,
    signer_name,
    signer_ip_address,
    signer_user_agent,
    legal_confirmations
) VALUES (
    'SIG-2025-001234',
    'AGR-2025-001234',
    'signatures/APP-2025-001234/SIG-2025-001234.png',
    'John Smith',
    '86.134.45.123',
    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)',
    '{"terms_understood": true, "information_accurate": true, "legally_binding": true, "credit_monitoring_consent": true}'::jsonb
);

🔄 Update Application Status

UPDATE applications
SET
    current_status = 'signed',
    signed_at = CURRENT_TIMESTAMP,
    updated_at = CURRENT_TIMESTAMP
WHERE id = 'APP-2025-001234';

UPDATE agreements
SET
    status = 'signed',
    signed_pdf_s3_key = 'agreements/.../AGR-2025-001234_signed.pdf',
    docusign_envelope_id = 'a7f3c5d9-e8b2-4a1c-9f6d-3e4b5a7c8d9e',
    signed_at = CURRENT_TIMESTAMP
WHERE id = 'AGR-2025-001234';

📋 Audit Log (Elasticsearch)

{
  "event_type": "agreement_signed",
  "application_id": "APP-2025-001234",
  "agreement_id": "AGR-2025-001234",
  "signature_id": "SIG-2025-001234",
  "customer_id": "CUST-001234",
  "timestamp": "2025-11-23T15:31:30.847Z",
  "signer_details": {
    "name": "John Smith",
    "ip_address": "86.134.45.123",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)"
  },
  "legal_confirmations": {
    "terms_understood": true,
    "information_accurate": true,
    "legally_binding": true,
    "credit_monitoring_consent": true
  },
  "docusign": {
    "envelope_id": "a7f3c5d9-e8b2-4a1c-9f6d-3e4b5a7c8d9e",
    "certificate_url": "https://docusign.net/certificate/..."
  }
}

📊 Data Retention Policy

• Signed PDFs: Retained permanently in S3 (legal requirement)
• Signature Images: Retained for 7 years (regulatory compliance)
• Audit Logs: Retained for 7 years in Elasticsearch
• DocuSign Copies: DocuSign retains for 10 years (their policy)
• Unsigned PDFs: Can be purged after 90 days if agreement signed