Adminwiki: 1 revision imported

2023-10-17T11:27:28Z

1 revision imported

← Older revision	Revision as of 07:27, 17 October 2023
(No difference)

api>Admin at 07:23, 6 October 2021

2021-10-06T07:23:03Z

New page

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 [http://wiki.developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs 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 [[API Overview#API callbacks|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 =
<nowiki>https://www.safestamper.com/api/signature/sign</nowiki>

= 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.
* '''signername''N''''': Signer name for signature N
* '''notifymode''N''''': How to send the signature link to signer N (default: EMAIL)
** ''EMAIL'': Send link by e-mail
** ''SMS'': Send link by SMS
* '''signeremail''N''''': Signer e-mail address for signature N. Required for EMAIL notifymode
* '''signerphone''N''''': Signer mobile phone number for signature N. Required for SMS notifymode
** Phone number must include country prefix and no spaces or hyphens (eg. +34123456789)
* '''signerlang''N''''': 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):
<pre>
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
</pre>

RESPONSE:
<pre>
{
"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"
}
]
}
</pre>

Signature/sign - Revision history

Adminwiki: 1 revision imported

api>Admin at 07:23, 6 October 2021