EviNoticeSubmit

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).
LookupKey [optional]: Identifier allocated by the user. It can be used later to locate evidence through the query web service (Query).
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: (Default) 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.
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.
- Unataca::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.
- Unataca::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.
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.
- NotificationDispatched: An Affidavit will be generated when the notification is sent to the recipient, after rendering the template provided by the client.
EvidenceAccessControlMethod [optional]: Access control method to the custody. Values to be displayed are as follows:
- Session: (Default) Users of related sites (issuer/recipient).
- 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.
- AutoChallenge: 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.
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.
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.
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.
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.
AcceptReasons [optional]: List of reasons to be displayed on signature process.
RequireAcceptReason [optional]: Boolean to ensure one accept reason was checked.
RejectReasons [optional]: List of reasons to be displayed on signature process.
RequireRejectReason [optional]: Boolean to ensure one reject reason was checked.
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) of online retention. 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..
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.

Example of request

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.

Example of answer

{
	"Id":"dd24e27d-2d84-4f74-a7f0-a23b018ab798"
}

Push notifications

Example of push notification answer

{
  "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" 
  }
}

Idempotence Activation

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).

Examples and further information

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.

Page tree

EviNoticeSubmit

Push notifications

Idempotence Activation

Examples and further information