Signature/sign

From SafeStamper API documentation
Jump to navigation Jump to search

Uploads a document for signing

This operation receives HTML text that will be converted to PDF. Any CSS or image file used by this HTML must be referenced using a full URL that is publicly accessible. You may also use <style> blocks for CSS styles and data urls for images and other files. This HTML should be simple and only include formatted text and images. It will be sanitized before its conversion to PDF, removing any problematic content such as javascript code.

You can upload a PDF file instead using signature/sign-pdf.

For each signature, the signer name and email is provided.

An email or SMS will be sent to each document signer with an URL they must visit to sign the document. When all signers have added their signature, a signature certificate will be generated and sent to all the document signers, and to the document sender e-mail address if specified.

Document signing process status can be queried using signature/status.

If your API client has a callback URL, it will receive the following callbacks:

  • DOCUMENT_SIGNATURE: When a signer signs the document
  • SIGNATURE_CERTIFICATE: When the document signature certificate is ready

These callbacks receive the same JSON as returned from signature/status.

URL

https://www.safestamper.com/api/signature/sign

Parameters

  • sharedkey: Your API client shared key
  • authkey: Authorization key, if needed
  • html: HTML of the document to sign
  • title: Document title
  • lang: Language for signer e-mails and signature pages (default: es)
    • es: Spanish
    • en: English
  • signaturemode: How the signers will sign the document (default: GRAPHIC)
    • GRAPHIC: Graphic signature
    • SMS: One-time code sent by SMS
  • sendername: Name of the person or organization that sends this document to its signers. It will be referenced in the e-mail that the signers receive.
  • senderemail: E-mail address of the person or organization that sends this document to its signers (optional). If included, the signed document certificate will also be sent to this e-mail address.
  • signernameN: Signer name for signature N
  • notifymodeN: How to send the signature link to signer N (default: EMAIL)
    • EMAIL: Send link by e-mail
    • SMS: Send link by SMS
  • signeremailN: Signer e-mail address for signature N. Required for EMAIL notifymode
  • signerphoneN: Signer mobile phone number for signature N. Required for SMS notifymode
    • Phone number must include country prefix and no spaces or hyphens (eg. +34123456789)
  • signerlangN: Language for communication with signer N. Optional, defaults to document language (lang parameter).
  • signature: Parameters signature, as explained in Signature parameter

Returns

A JSON object with the following fields:

  • code: Document code
  • title: Document title
  • senderName: Sender name
  • senderEmail: Sender e-mail address
  • entryDate: Date of upload
  • state: Document state
    • PENDING: The document doesn't have all its signatures
    • SIGNED: The document has all its signatures and it has generated a signing certificate
  • certificateCode: Code of the signature certificate, if it has already been generated (for SIGNED documents)
  • certificateUrl: Validation URL of the signature certificate, if it has already been generated (for SIGNED documents)
    • If the document status is queried when the document has just been signed by its last signer, it may be in SIGNED state, but the certificate may still be in process and the URL will not be available.
  • signatures: The list of signatures
    • signerName: Signer name
    • signerEmail: Signer e-mail address
    • state: Signature state
      • PENDING: The signer has not answered yet
      • SIGNED: The signer has signed the document
    • signerIP: IP address from which the document was signed
    • signatureDate: Date of signature


HTTP Errors

  • 403 Forbidden, the sharedkey or parameter signature are not valid
  • 401 Unauthorized, the authkey is not valid
  • 400 Parameter errors
  • 429 Your Safe Stamper user has no certification credits available
  • 430 Your Safe Stamper user has no storage space available

Example

This example uploads a document with 2 signers

REQUEST (line jumps are not included in the request):

https://www.safestamper.com/api/signature/sign
?sharedkey=5hmpod0d2vx7fnh6ysxab3olz
&html=<html>
      <body><h1>Test Document</h2><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p></body>
      </html>
&title=Test Document
&sendername=John Doe
&senderemail=john@example.com
&lang=es
&signatureid1=signature1
&signername1=Anne Example
&signeremail1=anne@example.com
&signatureid2=signature2
&signername2=Bernie Beans
&signeremail2=bernie@example.com
&signature=602382cc08c8db6929d2aac76ee13fc1266294e1

RESPONSE:

{
  "code":"b508e6e9-e5f6-4bb5-beef-c89bf6b50764",
  "title":"Test Document",
  "senderName":"John Doe",
  "senderEmail":"john@example.com",
  "state":"PENDING",
  "entryDate":"2019-07-29T09:18:46Z",
  "signatures":[
    { 
      "signerName":"Anne Example",
      "signerEmail":"anne@example.com",
      "state":"PENDING"
    },
    {
      "signerName":"Bernie Beans",
      "signerEmail":"bernie@example.com",
      "state":"PENDING"
    }
  ]
}