Interface definitions
Data transmission
The standard Retarus eSign Services interface provides data transmission via FTP or SFTP. Optional transmission via a VPN or a leased/dedicated line, etc., can also be mapped. The dedicated FTP account contains three directories:
Normally, an identically-named file, with the exception of the file extension (.xml), must exist for each electronic document. This XML file provides process control and must contain all of the data and parameters needed for signature provision and potential transmission.
Note the following regarding the transmission of data awaiting processing:
An upload via FTP/SFTP should follow the "Copy & Rename" method, i.e., each file awaiting transmission should be named, e.g., "tmp" or "part". After an error-free transmission, the file should receive its actual name, e.g., "pdf" or "xml". The advantage of using this method is that incomplete files (e.g., due to a network outage) are not processed because eSign will not process files with extensions such as "tmp" or "part".
The file awaiting signature is transferred before the XML control file. If only a signature is required (i.e., no transmission or additional services), the XML file is not required.
XML tags
XML tag designations are case sensitive, so please be certain that you accurately enter lower- and upper-case letters.
General XML tags
The following attributes can be set for each document to be processed. Some attributes are optional and require the activation of specific features.
Tag/attribute name | M/C/O | Description/application/parameter |
|---|---|---|
documentId | M | This DocumentID is the document’s ID and should be a unique key from your system (e.g., an invoice number). Maximum length: 32 alphanumeric characters. |
operator | C | This attribute is used to identify the originator of the signed document. Maximum length: 64 alphanumeric characters. |
billingCode | C | This tag may contain a billing code or your company’s freely defined indicator. Evaluation options are present in the individual reports as well as the invoices. Maximum length: 64 alphanumeric characters. |
skipBadge | C/O | Used to generate the badge (a graphic element that contains the link to a specific signed document in the Retarus eSign Archive), which is suppressed for this job. Possible parameters: “true” and “false” (default value). |
pdfBadgeConfigName | C/O | eSign supports various badge configurations. The corresponding data is sent to you after the configuration is created. |
pdfPatternSetName | C/O | Various parser configurations can be created for data extraction from different PDF documents. The corresponding attributes are sent to you after implementation. Potential parameter: “skip-pattern”, which leads to each data extraction being skipped. |
signatureVerificationReportConfigName | C/O | Used to manage various verification report layouts. Also used for optional voice management. |
M/C/O – designates, respectively, a Mandatory field, a field that Can be used, and an Optional field that is necessary for a supplementary feature.
XML tags for email transmission
The following additional configuratione options are available for delivery of signed documents via email:
Tag/attribute name | M/C/O | Description/application/parameter |
|---|---|---|
toAddresses | M | Multiple addresses can be deined here. Individual addresses must be separated using a comma (,), or a semicolon (;). The syntax format for email addresses is described in the annex. To avoid creating duplicates with identical contents, copies of signed invoices and/or credits should only be sent to the invoice issuer’s recipients. |
fromAddress | C | The email sender. The syntax format for email addresses is described in this document‘s annex. |
subject | C | Contents of the subject line |
charSet | C | The accompanying text’s character set |
textMimeType | C | Potential parameters:
|
mailText | C | Accompanying text (email body) |
mailSignatureName | C/O | The Retarus eSign Service can save your email signatures upon request. The file name can be freely defined; however, it must conform to the naming convention for file names. When this feature is activated, the corresponding text is added as an email signature to to the email which is awaiting transmission. Various languages can also be managed. |
fileName | C | The file name that contains the attached PDF document. Maximum length: 64 alphanumeric characters Long file names cannot be fully displayed in the verification report. |
feedbackChannelName | C/O | Manages a preconfigured feedback channel in the eSign Service whose function is to guide messages from primary processing through dedicated channels to the intended recipient. |
Retarus Archive
In the optional archive feature data is generally extracted from the PDF document, e.g., the Customer Number, the Invoice Number, or the invoice sum. If these values cannot be extracted from the document, the option of filling the following tags with corresponding data is available to you:
Tag/attribute name | M/C/O | Description/application/parameter |
|---|---|---|
docInvoiceNo | C/O | The document number of the file awaiting signature (e.g., invoice number, credit note number). |
docCustomerNo | C/O | The invoice creator’s customer number on file for the invoice recipient. |
docInvoiceDate | C/O | The date of the document that awaits signature. |
docInvoiceDateFormat | C/O | Format of the invoice date. |
docCurrency | C/O | Currency used in the document |
docInvoiceAmountFormat | C/O | Format of the invoice’s amount. |
docGrossValue | C/O | Document gross value |
docNetValue | C/O | Document’s net value |
docVatRegNo | C/O | The invoice recipient’s European Union value-added tax ID number. |
Application configuration
It’s possible to pre-configure certain values in the Application Configuration; i.e., you only have to add content to the tags in the XML file if they deviate from the standard/default values defined in the following tables.
Email transmission of the signed document
The following parameters can added for email delivery:
Parameter | Parameter reference Field in the XML file |
|---|---|
Default value for the sender address | fromAddress |
Default value for the character set | charSet |
Default value for the name of the PDF attachment within the email to be sent (e.g., | fileName |
Default value for the email subject | subject |
Standard text for the text accompanying the email (text or HTML) | mailText |
Default value for the format of the text accompanying the email | textMimeType |
Additional recipients of this document that are always supposed to receive a copy of this transmission. You should avoid having duplicate copies of an invoice. | toAddresses |
Storage of one or multiple default mail signature(s) or text(s) | mailSignatureName |
Email Bounce Management
The optional Email Bounce Management feature takes over the task of evaluating email bounces. When this function is activated, each outbound email receives a unique email address identifier. If this email is answered (either automatically or manually), it is clear that the bounce is from an eSign ID, i.e., associated with a signed document. A corresponding evaluation is sent to you via email with the associated link to the document in the eSign Archive. The following settings can be configured:
Parameter | Parameter reference Field in the XML file |
|---|---|
Domain for unique sender addresses per document and document recipient | |
Various feedback channel configurations for the dedicated transmission of notifications (e.g., error reports) from the eSign primary processing | feedbackChannelName |
Feedback
The Retarus eSign Service provides both signed documents and the corresponding status information via feedback channels. This service currently has two different configurable channels for the primary- (the provision of the service signature) and the secondary processing (transmission of the signed documents). These are, in particular:
Push feedback via email (Protocol: SMTP)
Pull feedback via preparation on a server (Protocol: FTP, SFTP)
Parameter | Parameter reference Field in the XML file |
|---|---|
Push Feedback | |
Flags whether positive push feedback is wanted | true / false |
List of the email recipients from whom feedback should be received. | |
The desired sender email address | |
Email subject line:
| |
Pull Feedback | |
Flags whether positive pull feedback is wanted | true / false |
Name of the folders in which the corresponding files with feedback information are supposed to be saved:
|
Using the Pull Feedback Channel, we make three files per signature job available to you for download:
The signed, and, if necessary, verified document (.pdf)
A file containing the processing status (.txt)
The control file (.xml)
The file names are augmented with certain information that ensures uniqueness and makes them easy to locate in the future when using specific data. The file name has the following structure:
TaskId-20071219-153439-7A34BDA8.stamped.Invoice_123.pdfTaskId-20071219-153439-7A34BDA8.Invoice_123.txtTaskId-20071219-153439-7A34BDA8.Invoice_123.xml
Field | Description/format | Example |
|---|---|---|
"TaskId" | Fixed expression, case sensitive | TaskId |
- | Hyphen, separator between fields | - |
Date | Processing date in YYYYMMTT format | 20071219 |
- | Hyphen, separator between fields | - |
Time | Processing date in HHMMSS format | 153439 |
- | Hyphen, separator between fields | - |
Random number | An 8-digit random number in hexadecimal format | 7A34BDA8 |
. | Period, separator between the fields | . |
Status | Optional document processing status (this only affects the signature object (here: .pdf)
| stamped |
- | Hyphen, separator between fields | - |
Original file name | The original document’s file name | Invoice_123.pdf |
Error sensitivity / error escalation
The processes’ reaction to errors has been conservatively designed, i.e., our systems and processes expect full compliance with syntax and the corresponding parameters. This is particularly applicable to tags that are associated with other tags. If errors are detected, the job is not processed.
Error escalation for email transmission
The email address syntax is checked as much as possible prior to the transmission of signed documents via email. If an email address is determined to be invalid, the primary processing (signing, any verification, archiving, etc.) is carried out completely. However, the email has to be sent from a sender’s “FROM” address. The email alias is then expanded to include the invalid email address as well as a corresponding error notification (e.g., invalid address). This function enables the determination of the correct email address and the subsequent email transmission to your invoice recipients, including the signed document(s).
General error escalation
Our Support Department is informed of all errors that occur during primary processing, and, if necessary, can contact you. Errors that are clearly associated can be reported using pre-determined escalation procedures.