EviPostSubmit

Web service parameters

This operation allows to submit a notarial letter or document with the following data:

LookupKey[optional]: Identifier allocated by the user, it can be used later to locate evidence through the query web service (Query).
Document: Document or letter to be signed by the parties (in PDF Base64).
RecipientName: Name of the recipient of the letter.
RecipientLegalName: Name or corporate name of the recipient of letter.
RecipientAddress: Information about recipient’s location:
- StreetAddress: Recipient’s mailing address.
- PostalCode: Recipient’s postal code.
- Locality: Recipient’s locality.
- Region: Recipient’s province.
- Country: Recipient’s country (for example ES).
- PostOfficeBoxAddress: Recipient’s post office box address.
RecipientPhone: Recipient’s mobile phone number.
RecipientEmail: E-mail address of the recipient of the message.
IssuerName: Name or corporate name of message issuer.
IssuerLegalName: Legal name or corporate name of message issuer.
IssuerAddress: Information about message issuer’s location.
- StreetAddress: Issuer’s mailing address.
- PostalCode: Issuer’s postal code.
- Locality: Message issuer’s locality.
- Region: Message issuer’s province.
- Country: Issuer’s country (for example ES).
- PostOfficeBoxAddress: Issuer’s post office box address.
IssuerPhone: Issuer’s mobile phone number.
IssuerEmail: E-mail address of the issuer of the message.
IssuerComments: Additional comments that the issuer of the message may make.
Language [optional]: It represents the evidence language. Values that can be indicated are type:
- en (Default)
- es
- ca
- it
- pt
- fr
- de
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.
- PostServiceType: Values to be displayed are as follows:
  - Registered: Default value, sends an EviPost with physical postal delivery equivalent to a burofax.
  - Letter: Reserved value, you need to talk to support to use this type of service. An EviPost is sent to the printing and enveloping provider, the process can end according to the following cases:
    - By default, it ends with the delivery of the printed letter to a logistics operator.
    - By informing the parameters EnableDeliveryReceipt, EnableDeliveryAttempts and DeliveryAttemptsNumber, it ends with the delivery or attempted delivery of the printed letter to the addressee by a logistics operator.
- OnlineRetentionPeriod [optional]: ime (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.
- CertificationLevel: It specifies the level of tracking and certification that will be applied to the message (EviMail, EviSms, EviNotice). 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 valu. 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: 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. 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.
  - AdvancedContentOnSubmitAndOnClose: Several affidavits (one for each event) and timestamp. The content certification affidavit and the affidavit receipt will show the body of the message. In addition, an affidavit will be generated after the tracking ends.
- AffidavitsOnDemandEnabled: It allows to activate the affidavit generation upon request capability. AffidavitProfile value needs to be AdvancedContentOnSubmit, AdvancedContentOnClose, or AdvancedContentOnSubmitAndOnClose.
- 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).
  - 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 question raised in EvidenceAccessControlChallenge.
- CustomFields: They allow to include internal fields when submitting contracts that will be used later in the searches, and whose objective is to allow business validations to be included before submitting contracts. The information included in this node is displayed in LookupKey:
  - CustomField: within the node CustomFields ,1 a n CustomField can be included. Fields that may be completed are as follows:
    - Key: Identifier or key of CustomField. Compulsory.
    - Label: Association of Notaries number.
    - Value: License number.
    - IsLookupKey: It can only contain two values: true or false. If true then the value included within the lookupkey and indexed to increase the speed of searching.
    - TypeName: Type of field to be displayed.
      - Text: it allows to include any type of text.
    - DefaultValue: It allows to include a default value within CustomField.
    - DefaultValueIsForced: If true then the value is required to be included.
    - Required: It can only contain two values: true or false. If true then the value is compulsory.
    - ValidationRegex: It allows to include regex expressions that will validate whether or not the entered value complies with these regular expressions. If it is not met, the validation message or validation messages will be displayed.
    - ValidationMessage: Validation message when the value entered does not comply with the regular expression.
    - MaxLength: Number representing the maximum length that the additional field will have.
- 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:
  - Processed: Postal communication has been locally processed. Then it will be sent to the communication system.
  - Dispatched: The request has been dispatched to the communication system. Then it will be prepared to be sent to the postal operator.
  - Sent: The postal communication has been sent to the postal operator or messaging service associated to the recipient; from now on the system will manage the process of reception.
  - Delivered: The postal communication has been sent to the final recipient. The recipient accepted or rejected it.
  - Closed: Sending process of postal communication has completed, so events are no longer expected and its custody will proceed, if applicable.

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

"PushNotificationFilter":["STRING"]

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.

Example of request in JSON

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

{
	"LookupKey":"a2R4S25kWiu79fsbubSXkw==",
	"Document":"[ATENTTION: BASE64 for the PDF file would appear here]",
	"RecipientName":"ENTREGADO - Juan English",
	"RecipientLegalName":"Juan Valido",
	"RecipientAddress":
	{
			"StreetAddress":"Gran via 74, 5.. A",
			"PostalCode":"28014"
			"Locality":"Madrid",
			"Region":"Madrid",
			"Country":"ES"
	}
	"IssuerName":"Pedro Comprador",
	"IssuerLegalName":"Pedro valido",
	"IssuerAddress":
	{
		"StreetAddress":"c/ Gran Via, 1,1- A",
		"PostalCode":"28001",
		"Locality":"entregado",
		"Region":"Madrid",
		"Country":"ES"
	}
	"IssuerPhone":"+34677888777","
	"IssuerEmail":"pedro.comprador@gmail.com",
	"IssuerComments":"Sending on March.",
	"Options":
	{
		"PostServiceType":"Registered",
		"CertificationLevel":"Advanced",
		"NotaryRetentionPeriod":"5",
		"OnlineRetentionPeriod":"1",
		"CustomFields":
		[
			{
				"Key":"CollegiateMemberId",
				"Label":"Number of notarial college",
				"Value:"Collegiate member number",
				"IsLookupKey":false
			},
			{
				"Key":"ProtocolId",
				"Label":"Protocolo",
				"Value:"573/2014",
				"IsLookupKey":false
			}
		]
	}
}

Note: for a higher compression BASE64 of PDF file has been replaced by the tag "[ATTENTION: BASE64 for the PDF file would appear here]"

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

Example of answer in JSON

{
	"uniqueId":"69819c3e-0c0e-42b3-a792-a33b014a13a2"
}

Idempotence Activation

There is the option to activate the idempotency capability to avoid sending the same EviPost 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).

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 EviPost:

EventIdentifier: Identifier of the event.
EventType: Type of event.
EventDate: 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.
- Sender: Name of the sender.
- Recipient: Name of the recipient.
- 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:

Dispatched / Sent:
- TransmissionDetails: Technical detail of notification/sending.
Delivered:
- Details: Delivery details.
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 push notification answer (PROCESSED):

{
	"Identifier": "600a41fd-d96b-4c4b-abb2-a87000d7da3f",
	"EvidenceId": "bae409d127de4b18b97ca87000c75b1c",
	"EvidenceType": "eviPost",
	"Kind": "Processed",
	"Date": "2018-01-22T12:05:53.5875507Z",
	"Site": "pruebas",
	"Owner": "Pruebas evicertia",
	"OwnerEmail": "pruebas@evicertia.com"
	"AdditionalData": {
		"Sender": "Issuer name",
		"Recipient": "Issuer name",
		"LookupKey": "push-nofitication-test",
		"State": "Processed",
		"CreationDate": "2018-01-22T13:05:49.9850990+01:00",
		"ExtraData": "{\"myId\": \"99cf386b-1590-4ddb-af68-607b3e7c1194\", \"myCreationDate\": \"2018-01-22T12:54:00.4367924+01:00\"}
	}
}

Page tree

EviPostSubmit

Web service parameters

Idempotence Activation

Push notifications