Signature/sign-pdf: Difference between revisions
api>Admin No edit summary |
m 1 revision imported |
(No difference)
|
Latest revision as of 07:27, 17 October 2023
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 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-pdf
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.
- 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
- 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:
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--
RESPONSE:
{ "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" } ] }