This operation allows to submit an EviNotice with the following data:
Subject: Subject of the EviNotice to be sent.
Body: Body (may a html) of the EviNotice.
RecipientAddress: Recipient's email address or a phone number (E.164).
RecipientDisplayName [optional]: Recipient's display name.
RecipientLegalName [optional]: Name or corporate name of the recipient of the email (for example, The name and Fiscal Identity Number (NIF) of the recipient company).
IssuerLegalName [optional]: Name or corporate name of EviNotice issuer (por example, The name and Fiscal Identity Number (NIF) of the issuer company).
From [Optional] :E-mail address with which the FROM of the EviMail e-mail will be configured. The submit will validate that the address is configured in the sending user's account and that the domain is verified.
Example: "From": "custom from <custom-from@mydomain.com>".
ReplyTo [Optional]: E-mail address with which the reply-To and in-Reply-to header of the e-mail sent to the signatory is configured.
LookupKey [optional]: Identifier allocated by the user. It can be used later to locate evidence through the query web service (Query).
CustomLayoutLogoUrl [optional]: Allows to set a custom logo URL. This logo will be used to replace the existing logo during the delivery process.
Attachments [optional]: List of attachments:
Data: Content (bytes) of the file to be attached.
FileName [optional]: Name of the file.
DisplayName [optional]: Name of the attachment.
MimeType [optional]: Information on mime type of attachment.
ContentId [optional]: Mime identifier of the attachment.
ContentEncoding [optional]: Encoding of the attachment.
ContentDescription [optional]: Mime description of the attachment.
IncludeOnAffidavits [optional]: Boolean to may render this attachment on a AffidavitOnDemand request.
CertificationLevel [optional]: It specifies the level of tracking and certification that will be applied to the EviNotice. Values to be displayed are as follows:
None (Deprecated): None – Only tracking of status, alerts and traceability.
Standard: Standard – Generation of an Affidavit (receipt) when the tracking of status is over.
Advanced: Advanced – several Affidavits (one for each event) and timestamp. This parameter is important for invoicing purposes.
QERDS: Applies a level of certification compliant with the eIDAS Qualified eIDAS Certified Electronic Delivery Service, including Recipient identification and registration.
Note !: For QERDS the authentication will be with a 2FA, you must authenticate with user/pwd, as usual, and with a client certificate, for that, please, you must put in contact with our support team who help you to issue the client certificate, in staging and live environment.
QERDSProfile [optional]. This parameter defines the profile that will be used to identify the recipient in the case is not yet a registered user of Evicertia's QERDS service; the site must have its configuration the profiles that can be used.
Uanataca::VideoId::Email - The Recipient will be identified in an unassigned video conference process and with subsequent operator approval. This profile must be selected if sending an EviNotice to an email address.
Uanataca::VideoId::Mobile - The Recipient will be identified in a video conferencing process with subsequent operator approval. This profile must be selected if you are sending an EviNotice to a phone number via SMS.
Bit4Id::SPIDOnly::Email - Recipient will be identified through the Italian digital identification system. This profile must be selected if you are sending an EviNotice to an email address.
Bit4Id::SPIDOnly::Mobile - The Recipient will be identified through the Italian digital identification system. This profile should be selected if you are sending an EviNotice to a phone number via SMS.
QERDSEnrollmentAllowed [optional]: This parameter is used only for QERDS Communications. QERDS notifications require the Recipient to be a user identified by the platform. With this parameter the sender can decide whether or not the process will identify the user in case the user is not yet identified:
True - If the user is not identified, the process will launch the identification process defined in the QERDSProfile parameter.
False - If the user is not identified, the process shall terminate.
QERDSProfile [optional]. This parameter defines the profile that will be used to identify the recipient in the case is not yet a registered user of Evicertia's QERDS service; the site must have its configuration the profiles that can be used.
Uanataca::VideoId::Email - The Recipient will be identified in an unassigned video conference process and with subsequent operator approval. This profile must be selected if sending an EviNotice to an email address.
Uanataca::VideoId::Mobile - The Recipient will be identified in a video conferencing process with subsequent operator approval. This profile must be selected if you are sending an EviNotice to a phone number via SMS.
Bit4Id::SPIDOnly::Email - Recipient will be identified through the Italian digital identification system. This profile must be selected if you are sending an EviNotice to an email address.
Bit4Id::SPIDOnly::Mobile - The Recipient will be identified through the Italian digital identification system. This profile should be selected if you are sending an EviNotice to a phone number via SMS.
RecipientLegalIdRequired [optional]: Boolean indicating whether the sender wants to identify the Recipient by matching the reported document type and number. For QERDS notification the parameter is mandatory.
RecipientLegalIdKind: Type of user identification. At the moment the valid types are: IDC:ES (Spanish National Identity Card, PAS:ES (Spanish Passport), PAS:IT (Italian Passport), TIN:IT (Italian Fiscal Code). The parameter is mandatory if RecipientLegalIdRequired = true and CertificationLevel is not QERDS.
AffidavitKinds [optional]: List of Affidavit kinds. It specifies which Affidavits will be generated during the process. This parameter is important for invoicing purposes. Values to be displayed are as follows:
Submitted: An Affidavit will be generated when the message has been processed locally, its contents certified and ready for further transmission.
SubmittedAdvanced: An Affidavit will be generated when the message was processed locally, its contents certified and included in the Affidavit, ready for further transmission.
TransmissionResult: (For SMS sendings) An Affidavit will be generated when:
The system successfully sent the message to the server of the organisation.
The system could not credit the sending of the message to the server of the organisation
Received: An affidavit will be generated when the system confirmed the acknowledgement of receipt of notification.
DeliveryResult: An Affidavit will be generated when:
The system received confirmation of the delivery of the message.
The system received confirmation that the message was undeliverable.
Refused: An affidavit will be generated when the user, without seeing the message, exercised the option to refuse the notification.
Read: An Affidavit will be generated when the system confirmed the opening/reading of the message.
Committed: An Affidavit will be generated when:
The recipient made a formal statement accepting the message and its contents.
The recipient made a formal statement rejecting the message and its contents.
CommittedAdvanced: An Affidavit will be generated when:
The recipient made a formal statement accepting the message and its contents. The content will be included in the Affidavit.
The recipient made a formal statement rejecting the message and its contents. The content will be included in the Affidavit.
Closed: An Affidavit will be generated when the system terminated the processing of the message when the tracking expiry date was reached.
ClosedAdvanced: An Affidavit will be generated when the system terminated the processing of the message when the tracking expiry date was reached. The content will be included in the Affidavit.
Event: An Affidavit will be generated when the system received an event considered relevant that does not have a specific Kind of affidavit.
Complete: An Affidavit will be generated when the system terminated the processing of the message when the tracking expiry date was reached and generated a tracking summary.
CompleteAdvanced: An Affidavit will be generated when the system terminated the processing of the message when the tracking expiry date was reached and generated a tracking summary. The content will be included in the Affidavit.
OnDemand: An Affidavit will be generated when the system issued a new affidavit (on demand) at the request of the issuer with the information collected so far.
Failed: An Affidavit will be generated when the system received a finalising error that makes it impossible to continue processing the file.
DispatchedAdvanced: An Affidavit will be generated when the notification is sent to the recipient, after rendering the template provided by the client.
FileDownloaded: Affidavits will be generated when the recipient has downloaded one or more files attached to the message during the lifetime of the evidence.
EvidenceAccessControlMethod [optional]: Access control method to the custody. Values to be displayed are as follows:
AutoChallenge: (Default) Request of random known data, the operation will be carried out if a random question about a known data, such as the e-mail address of the recipient, is answered correctly.
Public: Anyone who knows the link will be able to access the content.
Challenge: Challenge question/answer, The operation will be carried out if the question selected as challenge by the issuer to be answered correctly.
Other values that should only be reported if the corresponding method has been selected are as follows:
EvidenceAccessControlChallenge: If option Challenge has been selected as EvidenceAccessControlMethod this is where you specify the question.
EvidenceAccessControlChallengeResponse: If option Challenge has been selected as EvidenceAccessControlMethod this is where you specify the answer to the question raised in EvidenceAccessControlChallenge.
NotificationPolicy [optional]: Define the delivery channel of the EviNotice if RecipientAddress is a mobile phone number (E. 164).
SmsOnly : This value indicates that the channel for sending the EviNotice is by SMS.
WhatsAppOnly: This value indicates that the channel for sending the EviNotice is via WhatsApp.
SmsThenWhatsApp: This value indicates that the main sending channel is by SMS and in case of failure in all retries the sending is done by WhatsApp.
WhatsAppThenSms: This value indicates that the main sending channel is by WhatsApp and in case of failure in all retries the sending is done by SMS.
Empty: It is sent by the default channel which is SMS.
DeliverySignMethod [optional]: Security mechanism to be used to sign (a consent).
WebClick: (Default) Click in web through safe link or locator. The operation will be carried out if the reference or locator of the EviNotice is known.
Challenge: Challenge question/answer. The operation will be carried out if the question selected as challenge by the issuer to be answered correctly.
Other values that should only be reported if the corresponding method has been selected are as follows:
DeliverySignChallenge: Question asked when the signature method is Challenge.
DeliverySignChallengeResponse: Answer to the previous question.
MobilePin: Security code PIN sent to mobile phone. The operation will be carried out after identifying the user that accesses or signs, requesting a random PIN sent to his mobile phone.
Other values that should only be reported if the corresponding method has been selected are as follows:
DeliverySignFixedMobile: Mobile phone number (E.164) to send the PIN to when the signing method is MobilePin.
WhatsAppPinPolicy: Indicates the default value for the PIN sending policy by WhatsApp. It only applies when the signature method is MobilePin.
Disabled: The WhatsApp channel is not enabled to send the PIN. Corresponds to the Normal delivery policy (by SMS).
Optional: The WhatsApp channel is enabled to send the PIN as an alternative to SMS.
Fallback: The WhatsApp channel is enabled to send the PIN only on retry.
EmailPin: Security code PIN sent to e-mail. The operation will be carried out after identifying the user that accesses or signs, requesting a random PIN sent to his e-mail address.
Other values that should only be reported if the corresponding method has been selected are as follows:
DeliverySignFixedEmail: Email account to send the PIN to when the chosen method is EmailPin.
*Note: The PIN code has a life time of 60 minutes, after this time it will be necessary to request another PIN code. The number of 9 attempts to correctly enter the PIN code sent is also established.
CommitmentChoice [optional]: Text appearing to reach an agreement. Possible values are as follows:
Disabled: (Default) There is no button.
Accept: Text "Accept" appears and check "Accept" appears on the agreement page.
Reject: Text "Reject" appears and check "Reject" appears on the agreement page
AcceptOrReject: Text "Accept/Reject" appears and checks "Accept" and "Reject"appear on the agreement page.
CommitmentCommentsAllowed [optional]: Boolean which indicates whether or not to include comments in the acceptance or rejection of the agreement.
True: Comments are allowed. This is the default value, but "CommitmentChoice" must be different from "Disabled".
False: (Default) Comments are not allowed.
RejectReasons [optional]: Specifies a list of reasons for rejection, which will be displayed to the user in a drop-down so that he/she can select one of them, must be used together with the parameters:
CommitmentOptions : “Reject” or “AcceptOrReject”
CommitmentCommentsAllowed : True
AcceptReasons [optional] : Specifies a list of acceptance reasons, which will be displayed to the user in a drop-down so that he/she can select one of them. must be used together with the parameters:
CommitmentOptions : “Accept” or “AcceptorReject”
CommitmentCommentsAllowed : True
RequireRejectReason [optional]: Boolean parameter, which indicates whether it is mandatory to indicate a reason for rejection to confirm a notification. Default value is false. must be used together with the parameters:
CommitmentOptions : “Reject” or “AcceptorReject”
RequireAcceptReason [optional]: Boolean parameter, which indicates whether it is mandatory to indicate a reason for acceptance to confirm a notification. Default value is false. must be used together with the parameters:
CommitmentOptions : “Accept” or “AcceptorReject”
PushNotificationUrl [optional]: URL of contract’s issuer to which EVICERTIA will do a POST when an event related to the contract occurs, sending a JSON with information about the event Therefore, the issuer can develop a controller that allows to capture these requests and proceed to update the status of the contracts in its own information systems. In case of not being able to push the indicated URL, the platform has a system of 10 retries with the following times between retries: 30 Seconds, 30 Seconds, 2 minutes, 5 minutes, 10 minutes, 30 minutes, 1 Hour, 5 Hours, 15 hours, 1 Day and 6 Hours.
PushNotificationFilter [optional]: List of Pushes you would like to be notified of in PushNotificationUrl. Possible values are:
Processed: The EviNotice has been locally processed. It will be subsequently sent.
Sent: The EviNotice has been sent to the server or the operator that manages the mailbox or device of recipient: from now on the system will manage the process of reception.
Dispatched: The messaging service serving the recipient has accepted of the EviNotice and will then try to send it to the final recipient.
Delivered: The EviNotice has been delivered to the final recipient, but the content still has not been opened/read.
Received: The user has made use of the link attached to the EviNotice.
Read: The EviNotice has been opened/read by the final recipient.
Replied: The recipient has answered accepting or rejecting the EviNotice.
Closed: End of the tracking of status, for which reason no more notifications or answers are expected and the notarial deposit will follow.
Failed: The EviNotice has failed to be delivered to the recipient for any reason. This is not a final state.
AffidavitPublished: A new Affidavit has been generated, it was requested on demand by the issuer and will contain the information collected so far.
PushNotificationExtraData [optional]: Text field in which the issuer of the contract may indicate additional data. These data will be sent later in each push notification that is made.
NotificationLayout [optional]: : It specifies if the EviNotice will appear with the CERTIFICATE logos, or it will be sent without logos for commercial purposes. Values to be displayed are as follows:
Certified: (Default) Some logos are displayed.
AsIs: No logos to be displayed.
TimeToLive [optional]: Time (in minutes) that the EviNotice/contract will be available before proceeding to close the tracking of the EviNotice. In those cases in which the notification/contract is accessible via a link, once that period has elapsed and if it has never been accessed, this link is no longer available.
OnlineRetentionPeriod [optional]: Time in years that a recipient can access custody of evidence. Default value is 1 year. This parameter is important for invoicing purposes.
NotaryRetention [optional]: Boolean. If true, a 5-year notarial retention will be applied; otherwise nothing will be applied. This parameter is important for invoicing purposes.
NotaryProfile [optional]: Notary’s identifier who will carry out custody at the notary’s office This parameter must be reported if NotaryRetention is true.
Language [optional]: It represents the evidence language. Values that can be indicated are type:
en (Default)
es
ca
it
pt
fr
de
AffidavitLanguage [optional]: It represents the language in which you want to generate the Affidavits. Values that can be indicated are type:
en (Default)
es
ca
it
pt
CostCentre [optional]: In terms of invoicing, it allows to group sendings. In order to automate invoicing and to allocate expense.
AllowRefusal [optional]: Indicates whether the recipient is given the option to refuse to view the content of a notification. By default its value is False. Possible values are:
True: The recipient is given the option to refuse to view the content of a notification.
False: (Default) The recipient has no option to decline.
SmsNotifyTemplate [optional]: Template to be used by SMS.
NotificationTemplate: Contains the identifier of the template to be used in the communication. The use of this parameter triggers the generation of the 'DispatchedAdvanced' Affidavit, regardless of whether it was requested in the affidavitKind or not.
NotificationTemplateValues: It contains an array of value keys, where the variables defined in the template content and the value it receives in the emission are reported.
Reminders: Set how often notification reminders will be made.
Initial: String, time interval in ISO8601 format specifying the number of days or weeks after which the first notification reminder will be issued (from the EviNotice issue date).
Repeat: String, Time interval in ISO8601 format indicating the frequency with which the set configuration for notification reminders is repeated.
Days: Array, indicates the days of the week on which notification reminders will be sent. This field is configured as a list of the days of the week in English, separated by ",". Default: [ Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday ]
TimeRange: Array, indicates the time ranges selected for sending notification reminders. Allowed time ranges:
FROM08TO10: 08:00 - 10:00
FROM10TO12: 10:00 - 12:00
FROM12TO15: 12:00 - 15:00
FROM15TO19: 15:00 - 19:00
FROM19TO22: 19:00 - 22:00
Default: [FROM08TO10, FROM10TO12, FROM12TO15, FROM15TO19, FROM19TO22]
Max: Number, indicates the maximum number of notification reminders that can be sent during the lifetime of the process.
Stop: String, time interval in ISO8601 format representing the deadline for sending the last notification reminder.
TimeZone: String, name of the TimeZone (with the values of the TimeZones Etc/GMT) to be used for the calculation of the time when the reminders will be sent. Default: Etc/GMT0
EnforceTrackingUntilTimeToLive [optional]: This field allows to delay the closing of the EviNotice saga until the set TTL is reached. It can only be used in conjunction with the AffidavitKind EviNoticeContentDownload.
True: The EviNotice saga shall remain open until the defined TimeToLive (TTL) value is reached, regardless of whether a final event has already occurred as Accepted, Rejected or Read.
False (Default): The closing of the saga will take place immediately after one of the aforementioned final events, provided that there are no active CommitmentOptions.
POST https://app.evicertia.com/api/v2/EviNotice/Submit HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Host: app.evicertia.com
{
"Subject": "Hello world",
"Body": "Lorem ipsum dolor sit amet",
"RecipientAddress": "pruebas@evicertia.com",
"IssuerLegalName": "Evicertia",
"LookupKey": "dev",
"Attachments": [
{
"FileName" : "Example.pdf",
"Data": "Pdf's B64."
}
],
"CertificationLevel": "Advanced",
"AffidavitKinds": ["SubmittedAdvanced", "CompleteAdvanced", "OnDemand"],
"CommitmentChoice": "AcceptOrReject",
"CommitmentCommentsAllowed": true,
"PushNotificationUrl": "https://www.mysite.org/url/to/push",
"PushNotificationFilter": ["Processed", "Sent", "Received"],
"OnlineRetentionPeriod": 10,
"Language": "es",
"AffidavitLanguage": "es"
} |
In case of successful sending, the identifier allocated to the evidence that can be used later to consult its state is returned.
{
"Subject": "Hello world",
"Body": "Lorem ipsum dolor sit amet",
"RecipientAddress": "pruebas@evicertia.com",
"IssuerLegalName": "Evicertia",
"LookupKey": "dev",
"CertificationLevel": "QERDS",
"QERDSEnrollmentAllowed" : true,
"QERDSProfile" : "Uanataca::VideoId::Email",
"RecipientLegalIdRequired" : true,
"RecipientLegalIdKind": "PAS:ES",
"RecipientLegalIdValue" : "747834734",
"AffidavitKinds": ["SubmittedAdvanced", "CompleteAdvanced", "OnDemand"],
"CommitmentChoice": "AcceptOrReject",
"CommitmentCommentsAllowed": true,
"PushNotificationUrl": "https://www.mysite.org/url/to/push",
"PushNotificationFilter": ["Processed", "Sent", "Received"],
"OnlineRetentionPeriod": 10,
"Language": "es",
"AffidavitLanguage": "es"
} |
{
"Id":"dd24e27d-2d84-4f74-a7f0-a23b018ab798"
} |
{
"Identifier": "0188d313-e2a9-4293-b995-c36324c889a7",
"Kind": "Received",
"Date": "2023-06-19T09:54:35.7608150Z",
"EvidenceId": "0188d313642147089ab0c1398514df49",
"EvidenceType": "eviNotice",
"Site": "xxxxxx",
"OwnerEmail": "xxx@correo.es",
"AdditionalData": {
"From": "xxxx@correo.es",
"To": "xxxx@correo.com",
"Subject": "notification about your insurance car",
"State": "Received",
"CreationDate": "2023-06-19T09:54:03.7486430Z",
"Progress": "Received of the notification confirmed",
"Description": "The system confirmed, via open link, that the recipient received the notification with an attached link allowing the user to access the content, but the content has not yet been opened/read.",
"IpAddress": "188.26.211.105",
"BrowserData": "Chrome",
"UserLanguages": "es-ES, es;q=0.9"
}
} |
There is the option to activate the idempotency capability to avoid sending the same EviNotice more than once in case of repeated submitting. For that, a request with the name "X-Evi-IdempotencyToken" must be added to the request headers, adding as a value some random text (the use of a GUID is recommended).
More information is given below and examples of the parameters are given, so that they are understood more easily. This section is organized in alphabetical order.