Manual SOAP WS Firma ENCERTIFICATE, BIOMETRIC, AUTOMATED, UNDEFINED, OWN_CERTIFICATE. ... date...
Transcript of Manual SOAP WS Firma ENCERTIFICATE, BIOMETRIC, AUTOMATED, UNDEFINED, OWN_CERTIFICATE. ... date...
USER GUIDE2
WS INTEGRATION · SOAP
1. Introduction
2. WSDL
3. Create signature request
3.1 Function
3.2 Input
3.3 Output
4. Create signature request with template
4.1 Function
4.2 Input
4.3 Output
5. Cancel a document
5.1 Function
5.2 Input
5.3 Output
6. Query the status of a document
6.1 Function
6.2 Input
6.3 Output
7. Retrieve the detail of a document
7.1 Function
7.2 Input
7.3 Output
8. List all documents
8.1 Function
8.2 Input
8.3 Output
9. List of completed documents
9.1 Function
9.2 Input
9.3 Output
10. List Expired documents
10.1 Function
10.2 Input
10.3 Output
4
5
6
6
6
7
7
7
7
8
9
9
9
9
9
9
10
10
10
10
11
11
14
14
14
14
15
15
15
15
16
16
16
16
Index
USER GUIDE3
11. List pending documents
11.1 Function
11.2 Input
11.3 Output
12. List Cancelled Documents
12.1 Function
12.2 Input
12.3 Output
13. Error Codes
14. States
14.1 Document status
14.2 State of signatories
17
17
17
17
18
18
18
18
19
20
20
20
WS INTEGRATION · SOAP
1. IntroductionIntegration with Docuten through Web Services (SOAP), both for the creation of new signature requests, consultation of documents by state or the recovery of the complete detail of each of the requests.
USER GUIDE4
WS INTEGRATION · SOAP
2. WSDL
USER GUIDE5
Environment
STAGING
PROD
Path
http://test.docuten.com/services/DocumentsWS?wsdl
*Consult
WS INTEGRATION · SOAP
3. Create signature request
USER GUIDE6
Method name createRequest
Create a signature request for a given document.
3.1 Function
3.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
Object that contains the data of the document to be signed. Mandatory.document Document
expirationDate datetime Maximum date to complete the signatures. Optional.
People who have to sign the document. Mandatory.signers Signer[]
metadata Metadata[] Metadata to associate with the docu-ment. Optional.
Document Annexes, if any, packaged in a zip and encoded in Base64. Optional.attachments String
content String Content of the document encoded in Base64. Mandatory.
Description of the document. Optional.description String
filename String Name of the file. Mandatory.
Title for the signature request. Mandatory.title String
Signer Email of the signatory. Mandatory.email address String
mobile String Mobile phone. Optional.
Name of the signatory. Mandatory.name String
WS INTEGRATION · SOAP
USER GUIDE7
nif String NIF/NIE/CIF of the signatory. Mandatory.
Signature type. Mandatory. Values: CERTIFICATE, BIOMETRIC, AUTOMATED,UNDEFINED, OWN_CERTIFICATE.
signatureType String
Metadata Name of the label. Mandatory.name String
value String Value to be taken by the label. Mandatory.
DocumentResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
Identifier assigned to the document that will allow subsequent consultations using it.
documentId String
3.3 Output
4. Create signature request with template
Method name createTemplateRequest
Create a signature request using a given template (PDF form).
4.1 Function
4.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
Object that contains the template data to use. Mandatory.template Template
expirationDate datetime Maximum date to complete the signatures. Optional.
WS INTEGRATION · SOAP
USER GUIDE8
People who have to sign the document. Mandatory.signers Signer[]
metadata Metadata[] Metadata to associate with the docu-ment. Optional.
Signer Email of the signatory. Mandatory.email address String
mobile String Mobile phone. Optional.
Name of the signatory. Mandatory.name String
nif String NIF/NIE/CIF of the signatory. Mandatory.
Signature type. Mandatory. Values: CERTIFICATE, BIOMETRIC, AUTOMATED,UNDEFINED, OWN_CERTIFICATE.
signatureType String
Template Identifier of the template to use. Mandatory.identifier String
values TemplateValue[] Values to be entered in the fields in the template. Mandatory.
Template Value Name of the field in the template. Mandatory.key String
value String The value to be taken by the field. Mandatory.
Metadata Name of the label. Mandatory.name String
value String Value to be taken by the label. Mandatory.
DocumentResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
Identifier assigned to the document that will allow subsequent consultations using it.
documentId String
4.3 Output
WS INTEGRATION · SOAP
5. Cancel a document
USER GUIDE9
Method name cancelDocument
This function requests the cancellation of a document already sent to Docuten.
5.1 Function
5.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
Identifier assigned to the document.identifier String
reason String Reason for cancellation.
DocumentCancellationResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
5.3 Output
6. Document status query
Method name getDocumentStatus
Get the current status of a document sent to be signed through Docuten.
6.1 Function
WS INTEGRATION · SOAP
USER GUIDE10
6.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
Identifier assigned to the document.identifier String
DocumentCancellationResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
6.3 Output
status DocumentStatus Object with the detail of the state.
Document Status Unique identifier of the document.identifier String
signaturesDone int Number of signatures made.
The total number of signatures defined for the document.signaturesTotal int
stateName String Name of the current status of the request.
Request status code.stateCode String
7. Retrieve the detail of a document
Method name getDocumentDetail
Get the complete detail of a document sent to sign through Docuten.
7.1 Function
WS INTEGRATION · SOAP
USER GUIDE11
7.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
Identifier assigned to the document.identifier String
DocumentDetailResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
7.3 Output
documentDetail documentDetail Object with the detail of the document.
Document Detail Title of the signature request.title String
fileName String Name of the file.
Unique identifier of the document.identifier String
date datetime Date of creation of the signature request.
The maximum date set to complete signatures.expirationDate datetime
stateName String Name of the current status of the request.
Request status code.stateCode String
messages DocumentMessage[] List of messages exchanged around the document.
List of signatories to the document.signers DocumentSigner[]
history DocumentHistory[] Document history.
Number of signatures made.signaturesDone int
signatures Total int The total number of signatures defined for the document.
Direct URL for downloading the document.
url String
WS INTEGRATION · SOAP
USER GUIDE12
Direct URL to a thumbnail size of the first page of the document.thumbnailUrl String
content String Content of the document encoded in Base64.
Values collected in the form.templateValues TemplateValue[]
DocumentMessage
Name of the person who sends the message.name String
message String Text of the sent message.
date datetime Date on which the message is sent.
Document Signer Name of the signatory.name String
email String Email of the signatory
Mobile phone of the signatory.mobile String
nif String NIF/NIE/CIF of the signatory.
Signature order.order int
sentDate datetime Date of notification to the signatory.
Date of signature.signatureDate datetime
rejectDate datetime Date of rejection of the request for signature.
Reason for rejection.rejectReason String
state String Status code.
Type of signature to be made / madesignatureType String
isValidSignature boolean Indicates whether the signature made is valid.
Organization to which the signatory belongs. Only for certified signatures.
certOrganization String
email String Email of the person sending the message.
WS INTEGRATION · SOAP
USER GUIDE13
Signatory certificate issuing authori-ty. Only for certified signatures.certCa String
certSignerName StringName of the owner of the signing certificate. Only for certified signatu-res.
Name on the signature. Only for biometric signatures.
biometricSignatureName String
biometricSignatureLocation String
Location where the signature was made. Only for biometric signatures
Device from which the signature was made. Only for biometric signatures.
biometricSignatureDevice String
DocumentHistory
Person/system that originates the action.user String
InitialState String Initial state of the document.
endState String Final state of the document.
action String Action taken.
date datetime Date the action is performed.
Template Value The name of the field in the template.key String
value String Value entered in the field.
WS INTEGRATION · SOAP
USER GUIDE14
8.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
DocumentListResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
8.3 Output
documents DocumentListItem[] List of documents.
DocumentListItem
Title of the signature request.title String
fileName String Name of the file.
Identifier assigned to the document.identifier String
date datetime Date of creation of the signature request.
The maximum date set to complete signatures.expirationDate datetime
stateName String Name of the current status of the request.
Request status code.stateCode String
8. List all documents
Method name getAllDocs
Get a list of all documents sent through Docuten.
8.1 Function
WS INTEGRATION · SOAP
USER GUIDE15
9.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
DocumentListResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
9.3 Output
documents DocumentListItem[] List of documents.
DocumentListItem
Title of the signature request.title String
fileName String Name of the file.
Identifier assigned to the document.identifier String
date datetime Date of creation of the signature request.
The maximum date set to complete signatures.expirationDate datetime
stateName String Name of the current status of the request.
Request status code.stateCode String
9. List finished documents
Method name getDocsEnded
Obtain a list with all the documents of which all the requested signatures have been completed.
9.1 Function
WS INTEGRATION · SOAP
USER GUIDE16
10.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
DocumentListResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
10.3 Output
documents DocumentListItem[] List of documents.
DocumentListItem
Title of the signature request.title String
fileName String Name of the file.
Identifier assigned to the document.identifier String
date datetime Date of creation of the signature request.
The maximum date set to complete signatures.expirationDate datetime
stateName String Name of the current status of the request.
Request status code.stateCode String
10. List expired documents
Method name getDocsExpired
Obtain a list of all the documents from which the maximum date defined in the application was reached without completing all the requested signatures.
10.1 Function
WS INTEGRATION · SOAP
USER GUIDE17
11.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
DocumentListResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
11.3 Output
documents DocumentListItem[] List of documents.
DocumentListItem
Title of the signature request.title String
fileName String Name of the file.
Identifier assigned to the document.identifier String
date datetime Date of creation of the signature request.
The maximum date set to complete signatures.expirationDate datetime
stateName String Name of the current status of the request.
Request status code.stateCode String
11. List pending documents
Method name getDocsPending
Obtain a list of all documents for which all signatures have not yet been completed.
11.1 Function
WS INTEGRATION · SOAP
USER GUIDE18
12.2 Input
Input parameters Identifier of the application it invokes. Mandatory.appkey String
appToken String Secret of the application it invokes. Mandatory.
DocumentListResponse
Code indicating the result of the operation.responseCode int
responseDesc String Description associated with the response code.
12.3 Output
documents DocumentListItem[] List of documents.
DocumentListItem
Title of the signature request.title String
fileName String Name of the file.
Identifier assigned to the document.identifier String
date datetime Date of creation of the signature request.
The maximum date set to complete signatures.expirationDate datetime
stateName String Name of the current status of the request.
Request status code.stateCode String
12. List cancelled documents
Method name getDocsCancelled
Obtain a list with all canceled.
12.1 Function
WS INTEGRATION · SOAP
USER GUIDE19
13. Error codes
Code
0
1
Description
OK
The credentials indicated are not correct
9
12
Invalid document identifier
The file sent is not valid
14
15
Invalid file name.
The specified owner is invalid
16
17
The specified owner name is invalid
Owner's email is invalid
18
19
At least one signatory must be indicated
The name of the signatory is invalid
20
21
The email address given to the signatory is invalid
Invalid template
22
99
Invalid template filename
Unknown error
The error codes returned by the application along with their description are listed below.
WS INTEGRATION · SOAP
USER GUIDE20
14. States
Code
CREATED
PENDING
Description
Document created.
Pending completion of signatures.
REJECTED
EXPIRED
Rejected. One of the signatories refused to sign the document.
Expired. The established expiration date was reached without all signaturesbeing collected.
ENDED
CANCELED
Finished. All signatures were collected.
Canceled.
VALIDATION_PENDING
INVALIDATED
Pending validation.
Invalidated.
Existing states are listed below, differentiating States from signatory documents.
14.1 Document states
Code
CREATED
SENT
Description
The signatory has been recorded but has not yet been notified.
The signatory has been notified of the request for signature.
OPENED
EXPIRED
The signatory has opened the document.
The expiry date was reached without the signatory completing the signature.
REJECTED
SIGNED
The signatory refused to sign the document.
The signatory completed the signature.
VALIDATION_PENDING
INVALIDATED
Pending validation.
Invalidated.
14.2 States of the signatories
VALIDATED Validated.
WS INTEGRATION · SOAP
Customer Service(+34) 981 269 [email protected]