Documentazione delle API

Copia// Node.js 18+ — client: https://signotp.com/sviluppatori/signotp-client.mjs
import fs from 'node:fs/promises';
import { SignOtpClient } from './signotp-client.mjs';

const signotp = new SignOtpClient({ apiKey: process.env.SIGNOTP_API_KEY });

const { guid, signUrl } = await signotp.startSigning({
  text: 'Gentile cliente,\nla preghiamo di firmare il contratto allegato.',
  email: 'contratti@azienda.it',
  callbackUrl: 'https://erp.azienda.it/signotp/callback', // facoltativo
  pdfBytes: await fs.readFile('contratto.pdf'),
});

console.log(guid);    // salvalo: identifica la pratica
console.log(signUrl); // invialo al cliente (es. via email)

Copia// .NET 6+ — client: https://signotp.com/sviluppatori/SignOtpClient.cs
using SignOtp;

using var signotp = new SignOtpClient(Environment.GetEnvironmentVariable("SIGNOTP_API_KEY")!);

var result = await signotp.StartSigningAsync(
    new CreateRequest(
        Text: "Gentile cliente,\nla preghiamo di firmare il contratto allegato.",
        Email: "contratti@azienda.it",
        CallbackUrl: "https://erp.azienda.it/signotp/callback"), // facoltativo
    await File.ReadAllBytesAsync("contratto.pdf"));

Console.WriteLine(result.Guid);    // salvalo: identifica la pratica
Console.WriteLine(result.SignUrl); // invialo al cliente (es. via email)

Copia# 1) crea la pratica
curl -X POST https://api.signotp.com/v1/requests \
  -H "x-api-key: $SIGNOTP_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Gentile cliente,\nla preghiamo di firmare.","email":"contratti@azienda.it"}'

# 2) carica il PDF sulla upload.url restituita (senza x-api-key)
curl -X PUT "<upload.url>" -H "Content-Type: application/pdf" --data-binary @contratto.pdf

# 3) finalizza: la risposta contiene signUrl
curl -X POST https://api.signotp.com/v1/requests/<guid>/finalize -H "x-api-key: $SIGNOTP_API_KEY"

Copiaconst created = await signotp.createRequest({
  text: 'Gentile cliente,\nla preghiamo di firmare il documento.',
  email: 'contratti@azienda.it',
  callbackUrl: 'https://erp.azienda.it/signotp/callback',
  // existingUid: 'Xk3P9aQ2mZr7Lw0Bv5Nt8c', // nuovo documento sulla stessa pratica
});

Copiavar created = await signotp.CreateRequestAsync(new CreateRequest(
    Text: "Gentile cliente,\nla preghiamo di firmare il documento.",
    Email: "contratti@azienda.it",
    CallbackUrl: "https://erp.azienda.it/signotp/callback"
    // , ExistingUid: "Xk3P9aQ2mZr7Lw0Bv5Nt8c"   // nuovo documento sulla stessa pratica
));

Copia{
  "guid": "Xk3P9aQ2mZr7Lw0Bv5Nt8c",
  "docNumber": 1,
  "fileName": "Xk3P9aQ2mZr7Lw0Bv5Nt8c_01.pdf",
  "status": "UPLOAD_PENDING",
  "upload": {
    "method": "PUT",
    "url": "https://signotp-documents.s3.eu-south-1.amazonaws.com/Xk3P…_01.pdf?X-Amz-…",
    "headers": { "Content-Type": "application/pdf" },
    "expiresAt": "2026-11-13T18:15:00.000Z",
    "maxBytes": 20971520
  },
  "finalizeUrl": "https://api.signotp.com/v1/requests/Xk3P9aQ2mZr7Lw0Bv5Nt8c/finalize"
}

Copiaawait signotp.uploadPdf(created.upload, await fs.readFile('contratto.pdf'));

Copiaawait signotp.UploadPdfAsync(created.Upload, await File.ReadAllBytesAsync("contratto.pdf"));

Copiacurl -X PUT "<upload.url>" -H "Content-Type: application/pdf" --data-binary @contratto.pdf

Copiaconst doc = await signotp.finalize(created.guid);
// doc.signUrl -> https://sms.signotp.com/Xk3P9aQ2mZr7Lw0Bv5Nt8c

Copiavar doc = await signotp.FinalizeAsync(created.Guid);
// doc.SignUrl -> https://sms.signotp.com/Xk3P9aQ2mZr7Lw0Bv5Nt8c

Copia{
  "guid": "Xk3P9aQ2mZr7Lw0Bv5Nt8c",
  "docNumber": 1,
  "fileName": "Xk3P9aQ2mZr7Lw0Bv5Nt8c_01.pdf",
  "status": "READY",
  "pages": 3,
  "sha256": "9f2c…e41a",
  "signUrl": "https://sms.signotp.com/Xk3P9aQ2mZr7Lw0Bv5Nt8c"
}

Copiaconst pratica = await signotp.getRequest(guid);
const doc = pratica.documents.at(-1);
if (doc.status === 'SIGNED') console.log('Firmato il', doc.signed.signedAt, 'da', doc.signed.phone);

Copiavar pratica = await signotp.GetRequestAsync(guid);
var docs = pratica.GetProperty("documents");
var doc = docs[docs.GetArrayLength() - 1];
if (doc.GetProperty("status").GetString() == "SIGNED")
    Console.WriteLine($"Firmato il {doc.GetProperty("signed").GetProperty("signedAt")}");

Copia{
  "guid": "Xk3P9aQ2mZr7Lw0Bv5Nt8c",
  "createdAt": "2026-11-13T17:00:00.000Z",
  "updatedAt": "2026-11-13T17:20:31.412Z",
  "sender": { "text": "Gentile cliente,\n…", "email": "contratti@azienda.it" },
  "callbackUrl": "https://erp.azienda.it/signotp/callback",
  "currentDoc": 1,
  "signUrl": "https://sms.signotp.com/Xk3P9aQ2mZr7Lw0Bv5Nt8c",
  "documents": [
    {
      "docNumber": 1,
      "fileName": "Xk3P9aQ2mZr7Lw0Bv5Nt8c_01.pdf",
      "status": "SIGNED",
      "pages": 3,
      "sha256": "9f2c…e41a",
      "originalUrl": "https://api.signotp.com/v1/requests/Xk3P…/documents/01/original",
      "signed": {
        "fileName": "Xk3P9aQ2mZr7Lw0Bv5Nt8c_01_signed.pdf",
        "signedAt": "2026-11-13T17:20:31.412Z",
        "phone": "+393331234567",
        "ip": "93.41.12.7",
        "userAgent": "Mozilla/5.0 …",
        "sha256": "1b7d…08aa",
        "downloadUrl": "https://api.signotp.com/v1/requests/Xk3P…/documents/01/signed"
      },
      "callback": { "ok": true, "httpStatus": 200, "attempts": 1 }
    }
  ]
}

Copiaconst pdf = await signotp.download(guid, 1);            // PDF firmato
// const original = await signotp.download(guid, 1, 'original');
await fs.writeFile(`${guid}_01_signed.pdf`, pdf);

Copiavar pdf = await signotp.DownloadAsync(guid, 1);         // PDF firmato
// var original = await signotp.DownloadAsync(guid, 1, signed: false);
await File.WriteAllBytesAsync($"{guid}_01_signed.pdf", pdf);

Copiacurl -L -o firmato.pdf https://api.signotp.com/v1/requests/<guid>/documents/01/signed \
  -H "x-api-key: $SIGNOTP_API_KEY"

Copia// Express: serve il corpo "grezzo" per verificare la firma
import express from 'express';
import { verifyCallback } from './signotp-client.mjs';

const app = express();
app.post('/signotp/callback', express.raw({ type: 'application/json' }), async (req, res) => {
  const rawBody = req.body.toString('utf8');
  const valid = verifyCallback({
    rawBody,
    timestamp: req.get('X-SignOTP-Timestamp'),
    signature: req.get('X-SignOTP-Signature'),
    secret: process.env.SIGNOTP_WEBHOOK_SECRET,
  });
  if (!valid) return res.sendStatus(401);

  const evt = JSON.parse(rawBody);
  if (evt.event === 'document.signed') {
    // es. scarica subito il PDF firmato (link valido circa 1 ora)
    const pdf = Buffer.from(await (await fetch(evt.signedPdfUrl)).arrayBuffer());
    // … salva pdf, aggiorna il gestionale con evt.guid / evt.docNumber
  }
  res.sendStatus(200); // rispondere 2xx entro 5 secondi
});
app.listen(3000);

Copia// ASP.NET Core (minimal API)
using SignOtp;
using System.Text.Json;

var app = WebApplication.Create(args);
var secret = Environment.GetEnvironmentVariable("SIGNOTP_WEBHOOK_SECRET")!;

app.MapPost("/signotp/callback", async (HttpRequest req) =>
{
    using var reader = new StreamReader(req.Body);
    var rawBody = await reader.ReadToEndAsync();
    if (!SignOtpWebhook.Verify(rawBody, req.Headers["X-SignOTP-Timestamp"], req.Headers["X-SignOTP-Signature"], secret))
        return Results.Unauthorized();

    var evt = JsonSerializer.Deserialize<SignedCallback>(rawBody, SignOtpClient.Json)!;
    if (evt.Event == "document.signed")
    {
        // es. scarica subito il PDF firmato (link valido circa 1 ora)
        using var http = new HttpClient();
        var pdf = await http.GetByteArrayAsync(evt.SignedPdfUrl);
        // … salva pdf, aggiorna il gestionale con evt.Guid / evt.DocNumber
    }
    return Results.Ok(); // rispondere 2xx entro 5 secondi
});
app.Run();

Copiaimport { SignOtpError } from './signotp-client.mjs';

try {
  await signotp.finalize(guid);
} catch (err) {
  if (err instanceof SignOtpError && err.code === 'UPLOAD_NOT_FOUND') {
    // il PDF non è stato caricato: ripetere l'upload
  } else throw err;
}

Copiatry
{
    await signotp.FinalizeAsync(guid);
}
catch (SignOtpException ex) when (ex.Code == "UPLOAD_NOT_FOUND")
{
    // il PDF non è stato caricato: ripetere l'upload
}