View Source

This operation allows to submit from EVICERTIA an EviSMS 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 an evidence through the query web service (EviSMSQuery).
Subject: Subject of SMS.
Text: Content of SMS to be sent.
IssuerName: Name of the issuer (maximum 10 characters).
Recipient: Data about the message’s recipient:
- LegalName: Name or corporate name of the recipient of the email (for example, The name and Fiscal Identity Number (NIF) of the recipient company).
- PhoneNumber: Message recipient’s mobile phone number.
Options: Sending/processing options of the message.
- CostCentre [optional]: In terms of invoicing, it allows to group sendings. 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 (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 is the default value. This parameter is important for invoicing purposes.
- AffidavitKind [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 phone number.
    - The system could not credit the sending of the message to the server of the organisation managing the recipient's phone number.
  - 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.
  - 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.
  - Event: An Affidavit will be generated when the system received an event considered relevant that does not have a specific Kind of affidavit.
- 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 (Deprecated): None affidavit will be generated.
  - Basic: Generation of an affidavit (receipt) when the tracking of status is over. 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 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 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 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.
  - 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 o 1: No logos to be displayed.
  - False o 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.
  - Public: Registered user, authentication by local registered user user/password.
  - Session: Users of related sites (issuer/recipient).
  - 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 Challenge has been selected as EvidenceAccessControlMethod this is where you specify the answer to the question raised in EvidenceAccessControlChallenge.
- 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.
- 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 It should appear if a NotaryRetentionPeriod greater than (0) years is selected.
- DeliveryMode: SMS delivery mode:
  - Forward: Default option, content of the SMS is delivered directly to the recipient. This type of sending is an EviSMS or certified SMS.
  - Notify ( Deprecated ): The recipient will receive a link instead of the content, and in order to view the content, he/she must click that link. With this type of sending you can attach any type of content to the SMS.This type of sending is an EviNotice to mobile phone.
    - Sendings of EviNotice to mobile phone allow to send the attachments with the contents.
- 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.
- EviSmsNotifyTemplate : – Deprecated –Template to be used by SMS (it shall only apply when DeliveryMode = Notify, EviNotice).
- 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] – Deprecated –: Text appearing in the checks of EVICERTIA web page to see the notification made, (it only applies when DeliveryMode = Notify, EviNotice). Possible values are as follows:
  - Disabled, there is no button in EviSms.
  - Accept, text "Accept" appears in EviSms and check "Accept" appears on the agreement page.
  - Reject, text "Reject" appears in EviSms 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]: – Deprecated – It indicates whether or not to include comments in the acceptance or rejection of the agreement (it only applies when DeliveryMode = Notify, EviNotice).
  - True: Comments are allowed. This is the default value, but "CommitmentOptions" must be different from "Disabled"
  - False: Comments are not allowed.
- 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. 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: 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.
  - Replied: The recipient has answered accepting or rejecting the message.
  - Failed: The message has failed to be delivered to the recipient for any reason. This is not a final state.
  - Closed: End of the tracking of status, for which reason no more notifications or answers are expected and the notarial deposit will follow.
- 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: – Deprecated – List of message attachments (shall only apply when DeliveryMode = Notify, EviNotice):

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
			}
		]
	}
]

In the case of JSON it should be reported as follows:

"PushNotificationFilter":["STRING"]

POST https://app.evicertia.com/api/EviSms/Submit HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Host: app.evicertia.com

{
	"LookupKey":"Evi",
	"Text":"Hi This is a certified SMS",
	"IssuerName":"JGM",
	"Recipient":
	{
		"LegalName":"Juan Gallego",
		"PhoneNumber":"+34xxxxx"
	}
	"Options":
	{
		"CertificationLevel":"Advanced",
		"TimeToLive":10500
	}
}

POST https://app.evicertia.com/api/EviSms/Submit HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Host: app.evicertia.com
{
	"lookupKey": "xxx",
	"subject":"xxx",
	"text": "xxx",
	"issuerName": "xx",
	"recipient":{
		"LegalName":"Juan Gallego",
		"PhoneNumber":"+34xxxxx"
	},
	"Options":{
		"DeliveryMode":"Notify",
		"CommitmentOptions": "Disabled",
		"CertificationLevel":"Advanced",
	},
	"Attachments": {
		"DisplayName": "xxx",
		"Filename": "xxxx",
		"MimeType": "application/pdf",
		"Data": "pdf en base 64"
	}
}

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

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

Idempotence Activation

There is the option to activate the idempotency capability to avoid sending the same EviSMS 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.Cada vez que una evidencia cambie de estado, se notidficará al usuario un POST a la url que indique como parámetro de la petición.

Please find here below the common information returned for any push notification for an EviSms:

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.
- Source: Name of the issuer.
- Destination: Name of the recipient.
- 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

{
	"Identifier": "1335",
	"EvidenceId": "d9a581ae02584cf6b925a87000c4be22",
	"EvidenceType": "eviSMS",
	"Kind": "Ready",
	"Date": "2018-01-22T12:56:22.4367924+01:00",
	"Site": "pruebas",
	"Owner": "Pruebas evicertia",
	"OwnerEmail": "pruebas@evicertia.com"
	"AdditionalData": {
		"Source": "Issuer Name",
		"LookupKey": "push-notification-test",
		"State": "In progress",
		"CreationDate": "2018-01-22T12:56:19.1306690+01:00",
		"ExtraData": "{\"myId\": \"99cf386b-1590-4ddb-af68-607b3e7c1194\", \"myCreationDate\": \"2018-01-22T12:54:00.4367924+01:00\"}
	}
}