🚀 API Integration Documentation

📝 E-Sign API

Create electronic signature sessions, track their status, and download signed documents programmatically.

curl -X POST https://www.smarttoolpdf.com/api/v1/esign/create/ \
  -H "X-API-Key: stpdf_test_YOUR_KEY" \
  -H "X-API-Secret: YOUR_SECRET" \
  -F "file=@contract.pdf" \
  -F "signer_email=john.doe@example.com" \
  -F "signer_name=John Doe"

import requests

url = "https://www.smarttoolpdf.com/api/v1/esign/create/"
headers = {
    "X-API-Key": "stpdf_test_YOUR_KEY",
    "X-API-Secret": "YOUR_SECRET"
}
files = {"file": open("contract.pdf", "rb")}
data = {
    "signer_email": "john.doe@example.com",
    "signer_name": "John Doe"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

{
  "success": true,
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "otp_sent",
  "signing_url": "https://smarttoolpdf.com/esign/sign/a1b2c3d4-.../",
  "message": "Session created and OTP sent"
}

curl -X GET https://www.smarttoolpdf.com/api/v1/esign/status/SESSION_ID/ \
  -H "X-API-Key: stpdf_test_YOUR_KEY" \
  -H "X-API-Secret: YOUR_SECRET"

{
  "success": true,
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "signed",
  "created_at": "2025-12-04T10:00:00Z",
  "signed_at": "2025-12-04T10:15:30Z",
  "is_expired": false
}

curl -X GET https://www.smarttoolpdf.com/api/v1/esign/download/SESSION_ID/ \
  -H "X-API-Key: stpdf_test_YOUR_KEY" \
  -H "X-API-Secret: YOUR_SECRET" \
  -o signed_document.pdf

import requests

session_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
url = f"https://www.smarttoolpdf.com/api/v1/esign/download/{session_id}/"
headers = {
    "X-API-Key": "stpdf_test_YOUR_KEY",
    "X-API-Secret": "YOUR_SECRET"
}

response = requests.get(url, headers=headers)
with open("signed_document.pdf", "wb") as f:
    f.write(response.content)

🔔 Webhook Notifications

Configure webhooks to receive real-time notifications when events occur in your API integrations.

Configuring Webhooks

To set up webhooks:

1. Log in to your Merchant Dashboard
2. Navigate to Webhooks section
3. Enter your webhook URL
4. Save your webhook secret for signature verification
5. Enable webhooks

Supported Events

Webhook Payload Structure

Example payload for esign.signed event:

{
  "event": "esign.signed",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "signed",
  "signer_email": "john.doe@example.com",
  "signer_name": "John Doe",
  "created_at": "2025-12-04T10:00:00Z",
  "signed_at": "2025-12-04T10:15:30Z",
  "signed_file": {
    "name": "contract.pdf",
    "download_url": "/api/v1/esign/download/a1b2c3d4-.../",
    "expires_at": "2025-12-05T10:00:00Z"
  }
}

Webhook Headers

Every webhook request includes these headers:

Content-Type: application/json
X-Webhook-Signature: 
X-Webhook-Event: esign.signed
User-Agent: SmartToolPDF-Webhook/1.0

Verifying Webhook Signatures

Important: Always verify the webhook signature to ensure the request is authentic and hasn't been tampered with.

Python Example

import hmac
import hashlib
import json

def verify_webhook(payload, signature, secret):
    """Verify webhook signature using HMAC-SHA256"""
    message = json.dumps(payload, sort_keys=True).encode('utf-8')
    expected = hmac.new(
        secret.encode('utf-8'),
        message,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your webhook handler:
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    webhook_secret = "your_webhook_secret"
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.json
    
    if not verify_webhook(payload, signature, webhook_secret):
        return "Invalid signature", 401
    
    # Process the webhook
    event = payload.get('event')
    
    if event == 'esign.signed':
        session_id = payload['session_id']
        # Download the signed PDF, update your database, etc.
        print(f"Document signed: {session_id}")
    
    return "OK", 200

Node.js Example

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
    const message = JSON.stringify(payload, Object.keys(payload).sort());
    const expected = crypto
        .createHmac('sha256', secret)
        .update(message)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

app.post('/webhook', (req, res) => {
    const webhookSecret = 'your_webhook_secret';
    const signature = req.headers['x-webhook-signature'];
    const payload = req.body;
    
    if (!verifyWebhook(payload, signature, webhookSecret)) {
        return res.status(401).send('Invalid signature');
    }
    
    // Process the webhook
    const event = payload.event;
    
    if (event === 'esign.signed') {
        console.log(`Document signed: ${payload.session_id}`);
        // Download PDF, update database, etc.
    }
    
    res.status(200).send('OK');
});

Best Practices

• Always verify signatures: Never trust webhook data without verifying the signature
• Use HTTPS: Your webhook endpoint must use HTTPS in production
• Respond quickly: Return a 200 status code within 5 seconds
• Handle retries: We'll retry failed webhooks up to 3 times with exponential backoff
• Be idempotent: Handle duplicate webhook deliveries gracefully
• Log everything: Keep logs of all webhook deliveries for debugging

Retry Policy

If your webhook endpoint fails to respond or returns an error:

• Attempt 1: Immediate delivery
• Attempt 2: 2 minutes after first failure
• Attempt 3: 4 minutes after second failure
• Attempt 4: 8 minutes after third failure

After 4 failed attempts, the webhook delivery is marked as failed and no further retries are attempted.

📚 API Reference

⚠️ Error Codes

Error Response Format

{
  "success": false,
  "error": "Error message here",
  "code": "ERROR_CODE",
  "details": "Additional error details"
}

⏱️ Rate Limits

API requests are rate-limited based on your subscription plan:

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1638360000

🔒 Security Best Practices

• Keep credentials secure: Never commit API keys to version control
• Use environment variables: Store credentials in environment variables or secure vaults
• Rotate keys regularly: Generate new API keys periodically
• Use HTTPS only: Always make API requests over HTTPS
• Validate webhook signatures: Always verify webhook signatures before processing
• Implement IP whitelisting: Configure IP restrictions in your merchant dashboard
• Monitor usage: Regularly check your API usage logs for suspicious activity

🌍 Supported Regions

Our API is currently available in the following regions:

📞 Support & Resources

Need Help?

• Email Support: smarttoolpdf@gmail.com
• Merchant Dashboard: View your usage and manage API keys
• Status Page: Check our service status and uptime
• GitHub Examples: Sample code and integration examples (Coming Soon)

Changelog