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:20, 6 October 2021

2021-10-06T07:20:27Z

New page

Uploads a PDF document for signing

This operation must use an '''HTTP multipart/form-data post request'''.

You can send an HTML text instead using [[signature/sign]].

For each signature, the signer name and email or phone number must be 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-pdf</nowiki>

= Parameters =
* '''sharedkey''': Your API client shared key
* '''authkey''': Authkey to certificate as authorized user (not needed if your shared key is already linked to your user)
* '''pdf''': PDF document to sign
* '''title''': Document title
* '''lang''': Language to use in this document for the signatures page and for communication with signers (en,es)
** ''en'': English
** ''es'': Spanish (default)
* '''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]]
** '''NOTE:''' When calculating the signature use the file name as the value of ''pdf'' parameter

= Returns =

A JSON object, as returned by [[signature/status]] with the following fields:

* '''code''': Code of the document,
* '''title''': Title of the document,
* '''entryDate''': Date when the document was sent to sign
* '''senderName''': Name of sender
* '''senderEmail''': Email of the sender
* '''state''': State of the document (PENDING, SIGNED)
** ''PENDING'': The document has been sent to its signers, but not all signatures have been received yet.
** ''SIGNED'': The document has been signed by all its signers and is ready for download.
* '''certificateCode''': Signature certificate code for SIGNED documents
* '''certificateUrl''': Download URL for SIGNED documents
* '''signatures''': Signatures data
** '''signerName''': Name of signer
** '''signerEmail''': Email of signer
** '''state''': State of this signature
*** ''PENDING'': This signer has not signed the document yet.
*** ''SIGNED'': This signer has signed the document.
** '''signerIP''': IP from which the document was signed (for SIGNED signatures)
** '''signatureDate''': Date when the document was signed (for SIGNED signatures)

= HTTP Errors =

* '''401''' Unauthorized, the authkey is not valid
* '''403''' Forbidden, the sharedkey or signature are 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 =

REQUEST:
<pre>
https://www.safestamper.com/api/signature/sign-pdf

Content-Type: multipart/form-data;
boundary=90503bb6-f5b0-410f-97da-e86041ce17cd
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="authkey"

0dbb406d-cc0c-4ef8-ae80-971ed108c2f9
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="sharedkey"

axvmfqn8aex21mxhq5zsj7l482saxfu7j4hh
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="lang"

en
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="title"

Test PDF
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="sendername"

John Doe
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="senderemail"

johndoe@example.com
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="signername1"

Anne Example
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="signeremail1"

anne@example.com
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="signername2"

Bernie Beans
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="signeremail2"

bernie@example.com
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="signature"

508c8bf78d43577f1d41db0c7a3c67c07518681c
--90503bb6-f5b0-410f-97da-e86041ce17cd
Content-Disposition: form-data; name="pdf"; filename="lipsum.pdf"
Content-Type: null

<<< PDF contents >>>

--90503bb6-f5b0-410f-97da-e86041ce17cd--

</pre>

RESPONSE:
<pre>
{
"code":"0cdfbc8d-f9ad-4bb5-ba3b-2d33fe2d03bc",
"title":"Test PDF",
"senderName":"John Doe",
"senderEmail":"jguillo@gmail.com",
"state":"PENDING",
"entryDate":"2020-09-16T10:38:05Z",
"signatures":[
{
"signerName":"Anne Example",
"signerEmail":"anne@example.com",
"state":"PENDING"
},
{
"signerName":"Bernie Beans",
"signerEmail":"bernie@example.com",
"state":"PENDING"
}
]
}
</pre>

Signature/sign-pdf - Revision history

Adminwiki: 1 revision imported

api>Admin at 07:20, 6 October 2021