E-Stamp API Workflow

create + upload → send (202) → e-stamp pending → stamped PDF attached → recipients notified
                                      └──── terminal failure → manual retry

import { readFile } from "node:fs/promises";
import { SignSecureClient } from "@signsecure/sdk";

const client = new SignSecureClient({
  apiKey: process.env.SIGNSECURE_API_KEY,
});

const pdf = await readFile("./service-agreement.pdf");
const envelope = await client.envelopes.createAndUpload(pdf, {
  fileName: "service-agreement.pdf",
  title: "Service Agreement",
  recipients: [
    {
      name: "Authorized Signer",
      email: "signer@example.com",
      order: 1,
      role: "signer",
      signatureMethod: "electronic",
      signaturePlacement: {
        type: "text",
        searchText: "Authorized Signatory",
        position: "below",
      },
    },
  ],
  workflow: {
    mode: "sequential",
    estampEnabled: true,
    estampConfig: {
      state: "KA",
      article: "Affidavit",
      amount: "100",
      considerationAmount: "50000",
      payee: "first-party",
      hardcopy: "n",
      firstParty: {
        name: "Acme Private Limited",
        email: "legal@acme.example",
        mobile: "",
        address: "Bengaluru, Karnataka",
      },
      secondParty: {
        name: "Example Industries",
        email: "legal@example.test",
        mobile: "",
        address: "Mumbai, Maharashtra",
      },
    },
  },
});

const queued = await client.envelopes.send(envelope.id);
if ("estamp" in queued) {
  console.log(queued.status);       // "estamping"
  console.log(queued.estampStatus); // "queued"
}

curl -X POST "https://api.signpad.signsecure.in/api/v1/envelopes" \
  -H "Authorization: Bearer $SIGNSECURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "service-agreement.pdf",
    "title": "Service Agreement",
    "recipients": [{
      "name": "Authorized Signer",
      "email": "signer@example.com",
      "order": 1,
      "role": "signer",
      "signatureMethod": "electronic",
      "signaturePlacement": {
        "type": "text",
        "searchText": "Authorized Signatory",
        "position": "below"
      }
    }],
    "workflow": {
      "mode": "sequential",
      "estampEnabled": true,
      "estampConfig": {
        "state": "KA",
        "article": "Affidavit",
        "amount": "100",
        "considerationAmount": "50000",
        "payee": "first-party",
        "hardcopy": "n",
        "firstParty": {
          "name": "Acme Private Limited",
          "email": "legal@acme.example",
          "mobile": "",
          "address": "Bengaluru, Karnataka"
        },
        "secondParty": {
          "name": "Example Industries",
          "email": "legal@example.test",
          "mobile": "",
          "address": "Mumbai, Maharashtra"
        }
      }
    }
  }'

curl -X POST \
  "https://api.signpad.signsecure.in/api/v1/envelopes/$ENVELOPE_ID/send" \
  -H "Authorization: Bearer $SIGNSECURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "success": true,
  "estamp": true,
  "estampStatus": "queued",
  "message": "E-stamp requested. Recipients will be notified when the document is ready.",
  "envelopeId": "env_abc123",
  "status": "estamping"
}

{
  "id": "evt_01J...",
  "event": "document.estamp.completed",
  "createdAt": "2026-07-22T10:15:00.000Z",
  "data": {
    "envelopeId": "env_abc123",
    "title": "Service Agreement",
    "status": "completed",
    "transactionId": "txn_123",
    "reference": "ref_123",
    "certificateId": "cert_123",
    "documentId": "doc_123",
    "occurredAt": "2026-07-22T10:15:00.000Z"
  }
}

{
  "id": "evt_01J...",
  "event": "document.estamp.failed",
  "createdAt": "2026-07-22T10:15:00.000Z",
  "data": {
    "envelopeId": "env_abc123",
    "title": "Service Agreement",
    "status": "failed",
    "transactionId": "txn_123",
    "reference": "ref_123",
    "error": "Provider reported an e-stamp failure.",
    "occurredAt": "2026-07-22T10:15:00.000Z"
  }
}

curl \
  "https://api.signpad.signsecure.in/api/v1/envelopes/$ENVELOPE_ID/status" \
  -H "Authorization: Bearer $SIGNSECURE_API_KEY"

{
  "envelopeId": "env_abc123",
  "status": "estamping",
  "estamp": {
    "enabled": true,
    "status": "pending",
    "transactionId": "txn_123",
    "reference": "ref_123",
    "certificateId": null,
    "initiatedAt": "2026-07-22T10:00:00.000Z",
    "pollAttempts": 1,
    "lastError": null
  }
}

curl -X POST \
  "https://api.signpad.signsecure.in/api/v1/envelopes/$ENVELOPE_ID/estamp/check" \
  -H "Authorization: Bearer $SIGNSECURE_API_KEY"