You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 11 Current »

This operation allows to submit an EviMail message with the following data:

NOTE 1.- All information about EviNotice in this help is deprecated. To issue and EviNotice you can use API v2 - EviNoticeSubmit (API V2) 


  • LookupKey [optional]: Identifier allocated by the user. It can be used later to locate evidence through the query web service (Query).
  • Body: Subject of the message to be sent.
  • IssuerName: Name or corporate name of message issuer (por example, The name and Fiscal Identity Number (NIF) of the issuer company).
  • Recipient: Data about the message’s recipient:
    • LegalName [optional]: Name or corporate name of the recipient of the email (for example, The name and Fiscal Identity Number (NIF) of the recipient company).
    • EmailAddress: E-mail address of the recipient of the message.
  • CarbonCopy: Data relating to the recipient of the copy of the message:
    • Name [optional]: Name or company name of the recipient of the copy of the message (e.g. the name and VAT number of the recipient company).
    • EmailAddress: E-mail address of the recipient of the copy of the message.
  • Options: Sending/processing options of the message:
    • CostCentre [optional]: In terms of invoicing, it allows to group sendings. In order to automate invoicing and to allocate expense.
    • CertificationLevel: It specifies the level of tracking and certification that will be applied to the message (EviMail, EviSms, EviNotice – Deprecated –). Values to be displayed are as follows:
      • None: 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 is the default value. This parameter is important for invoicing purposes.
    • AffidavitProfile: It specifies what and how the affidavits will be generated during the process. This parameter is important for invoicing purposes. Values to be displayed are as follows:
      • None: None affidavit will be generated.
      • Basic: The affidavit (proof) will be generated after the tracking ends. This is the default value in case of selecting Standard in CertificationLevel.
      • AdvancedContentOnSubmit: Several affidavits (one for each event) and timestamp. The content certification affidavit will show the body of the message and the attachments flagged as IncludeOnAffidavits. This is the default value in case of selecting Advanced in CertificationLevel.
      • AdvancedContentOnClose: Several affidavits (one for each event) and timestamp. Generation of an affidavit (receipt) when the tracking of status is over. The affidavit receipt will show the body of the message and the attachments flagged as IncludeOnAffidavits.
      • AdvancedContentOnSubmitAndOnClose: Several affidavits (one for each event) and timestamp. The content certification affidavit and the affidavit receipt will show the body of the message and the attachments flagged as IncludeOnAffidavits. Moreover, it will generate an affidavit (receipt) when the tracking of status is over.
    • AffidavitsOnDemandEnabled: It allows to activate the affidavit generation upon request capability. AffidavitProfile value needs to be AdvancedContentOnSubmit, AdvancedContentOnClose, or AdvancedContentOnSubmitAndOnClose*.
    • TimeToLive (minutes): Time (in minutes) that the message/contract will be available before proceeding to close the tracking of the message. 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.
      • Number of minutes.
    • HideBanners: : It specifies if the message will appear with the CERTIFICATE logos, or it will be sent without logos for commercial purposes. The default value is False, which shows that it will be sent with Evicertia CERTIFICATE logos. Values to be displayed are as follows:
      • True or 1: No logos to be displayed.
      • False or 0: Some logos are displayed.
    • Language [optional]: It represents the evidence language. Values ​​that can be indicated are type:
      • en (Default)
      • es
      • ca
      • it
      • pt
      • fr
      • de
      • ro
    • 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
      • ro
    • EvidenceAccessControlMethod: Access control method to the custody. Values to be displayed are as follows:
      • 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.
      • Challenge: Challenge question/answer, The operation will be carried out if the question selected as challenge by the issuer to be answered correctly.
      • Session: Users of related sites (issuer/recipient).
      • Public: Anyone who knows the link will be able to access the content.
      • 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.
    • OnlineRetentionPeriod [optional]: Time (in years) of online retention. Default value is 1 year. This parameter is important for invoicing purposes.
    • NotaryRetentionPeriod [optional]: If enabled, 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 NotaryRetentionPeriod greater than zero (0) years is selected.
    • DeliveryMode [optional]: E-mail delivery mode:
      • Forward: Default option, content of the email and its attachments is delivered directly to the recipient. This type of sending is an EviMail or certified email.
      • Notify: The recipient will receive a link instead of the content, and in order to view the content, he/she must click that link. This type of sending is an EviNotice to email.
    • DeliverySignMethod [optional]: - Deprecated - Security mechanism to be used to sign (a consent), (it only applies when DeliveryMode = Notify, EviNotice).
      • Challenge: Challenge question/answer. The operation will be carried out if the question selected as challenge by the issuer to be answered correctly.
      • WebClick: Click in web through safe link or locator. The operation will be carried out if the reference or locator of the message is known.
      • 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.
        • 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:
        • DeliverySignChallenge: Question asked when the signature method is Challenge.
        • DeliverySignChallengeResponse: Answer to the previous question.
        • DeliverySignFixedEmail: Email account to send the PIN to when the chosen method is EmailPin.
        • DeliverySignFixedMobile: Mobile phone number to send the PIN to when the signing method is MobilePin.
    • 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: The recipient has no option to decline.
    • CommitmentOptions [optional]: Text appearing both in the EviMail button sent by email and in the checks of EVICERTIA page to reach an agreement. Possible values are as follows:
      • Disabled, there is no button in EviMail.
      • Accept, text "Accept" appears in EviMail and check "Accept" appears on the agreement page.
      • Reject, text "Reject" appears in EviMail and check "Reject" appears on the agreement page
      • AcceptOrReject, text "Accept/Reject" appears in EviMail and checks "Accept" and "Reject"appear on the agreement page.
    • CommitmentCommentsAllowed [optional]: It 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 "CommitmentOptions" must be different from "Disabled".
      • False: 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”
    • FromDisplayName [optional]: It specifies the name of the issuer of the email.
    • PushNotificationUrl: 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: List of events you would like to be notified of in PushNotificationUrl. Possible values are:
      • Ready: The message has been locally processed. It will be subsequently sent.
      • Sent: The message 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 message and will then try to send it to the final recipient.
      • Delivered: The message has been delivered to the final recipient, but the content still has not been opened/read.
      • Read: The message has been opened/read by the final recipient.
      • Failed: The message has failed to be delivered to the recipient for any reason. This is not a final state.
      • Replied: The recipient has answered accepting or rejecting the message.
      • Closed: End of the tracking of status, for which reason no more notifications or answers are expected and the notarial deposit will follow.
      • AffidavitPublished: A new Affidavit has been generated, it was requested on demand by the issuer and will contain the information collected so far.

In the case of JSON it should be reported as follows: "PushNotificationFilter":["STRING"]

    • 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: An Affidavit will be generated when:
        • The system successfully sent the message to the server of the organisation managing the recipient's mailbox.
        • The system could not credit the sending of the message to the server of the organisation managing the recipient's mailbox.
      • 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.
      • 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.
      • 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.
      • Event: An Affidavit will be generated when the system received an event considered relevant that does not have a specific Kind of affidavit.
      • Failed: An Affidavit will be generated when the system received a finalising error that makes it impossible to continue processing the file.
  • PushNotificationExtraData: 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.
  • Attachments[optional]: List of message attachments:
    • DisplayName: Name of the attachment.
    • FileName: Name of the file.
    • Data: Content (bytes) of the file to be attached.
    • MimeType[optional]: Information on mime type of attachment.
    • ContentId[optional]: Mime identifier of the attachment.
    • ContentDescription[optional]: Mime description of the attachment.
    • Attributes: Attributes that you want to indicate about the attachment [optional].
      • Attribute: This property will contain as many Attribute nodes as necessary and within them different key-values will be assigned.
        • Key: Name of the key.
        • Value: Value for the previous key.
      • The following are the key-values that can be used in this node:
        • Key = IncludeOnAffidavits, Value = true, indicates that the annex will be included in the affidavits.

        • An example of an attachment node with an attributes node is shown below.

          [
	{
		"UniqueId":"00000000-0000-0000-0000-000000000000",
		"CreationDate":"0001-01-01T00:00:00",
		"EvidenceUniqueId":"00000000-0000-0000-0000-000000000000",
		"DisplayName":"4kb.pdf",
		"Filename":"4kb.pdf",
		"Data":"[ATTENTION: here would be the BASE64 of the attachment in PDF format.]",
		"Attributes": [
			{
				"Key":"IncludeOnAffidavits",
				"Value":true
			}
		]
	}
]
Example of request in JSON
POST https://app.evicertia.com/api/EviMail/Submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Host: app.evicertia.com

{
	"LookupKey":"EviMail",
	"Subject":"WS test",
	"Body":"Hola",
	"IssuerName":"ElJuanGAllego",
	"Recipient":
	{
		"LegalName":"JGM",
		"EmailAddress":"juan@gallegomolero.es"
	},
	"CarbonCopy": [
 		{
            "name": "PGG",
            "emailAddress": "pablo@garcia.com" 
        },
 		{
            "name": "JLL",
            "emailAddress": "joseluis@lozano.com" 
   		}
    ],  
	"Attachments":
	[
		{
			"UniqueId": "00000000-0000-0000-0000-000000000000",
			"CreationDate": "0001-01-01T00:00:00",
			"EvidenceUniqueId": "00000000-0000-0000-0000-000000000000",
			"DisplayName": "4kb.pdf",
			"Filename": "4kb.pdf",
			"Data": "[ATENTTION: BASE64 for PDF file would appear here]"
		}
	],
	"Options": {}
}



In case of successful sending, the identifier allocated to the evidence (eviId) that can be used later to consult its state is returned.


Example of answer in JSON



{
	"eviId": "87ffa214e7734bd59b8da8ef00fd80f8"
}



Idempotence Activation

There is the option to activate the idempotency capability to avoid sending the same EviMail 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 about parameters

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.

Push notifications

This method allows to report changes in the state of an evidence, without the need to periodically check its status.

Every time an evidence changes its state, the user will be notified through a POST to the url shown as a parameter of the request.

Please find here below the common information returned for any push notification for an EviMail/EviNotice (Deprecated):

  • Identifier: Identifier of the event.
  • Kind:  Mnemonic of the notification received.
  • Date: Date of event.
  • EvidenceId: Identifier of evidence.
  • EvidenceType: Type of evidence.
  • Site: Name of user’s site.
  • Owner: Name of site’s user.
  • OwnerEmail: Email of site’s user.
  • AdditionalData: Additional information in the form of a key-value:
    • From: Issuer’s email adress.
    • To: Recipient’s email address..
    • Subject: Subject indicated by the issuer.
    • LookupKey: Identifier allocated by the user, it can be used later to locate evidence through the query web service (Query).
    • State: Name of the evidence state.
    • CreationDate: Creation date.


In addition, depending on the type of event, specific properties will be added in AdditionalData:

  • Sent:
    • XmissionDetails: Technical detail of delivery process.
  • Dispatched / Delivered / Read:
    • Progress: Title of the progress.
    • Description: Detailed description of the progress.
  • Replied:
    • Kind: Action carried out by the signatory user.
    • Comments: Comments made by the signatory user.
  • Closed:
    • Outcome: Result of processing.


In the case where additional data is indicated in the PushNotificationExtraData parameter, it will be added in a property called ExtraData inside AdditionalData


Example of a push notification answer (SENT):
{
	"Identifier": "1234",
	"EvidenceId": "2aca3ea149f943879726a87000c1f704",
	"EvidenceType": "eviMail",
	"Kind": "Sent",
	"Date": "2018-01-22T12:46:32.4830752+01:00",
	"Site": "pruebas",
	"Owner": "Pruebas evicertia",
	"OwnerEmail": "pruebas@evicertia.com",
	"AdditionalData": {
		"From": "pruebas@evicertia.com",
		"To": "pruebas-receptor@evicertia.com",
		"Subject": "Prueba notificación push...",
		"LookupKey": "prueba-notificacion-push",
		"State": "Enviado",
		"CreationDate": "2018-01-22T12:46:12.3113880+01:00",
		"XmissionDetails": "* Processing emails for domain evicertia.com.\n* Resolving Mail Exchaner (MX) DNS...",
		"ExtraData": "{\"myId\": \"99cf386b-1590-4ddb-af68-607b3e7c1194\", \"myCreationDate\": \"2018-01-22T12:54:00.4367924+01:00\"}
	}
}





  • No labels