Last modified: 2022-10-28

API REST

OneSpan Sign a créé une Digital Mortgage Solution qui permet de stocker dans une chambre forte numérique un billet électronique provenant d'une transaction hypothécaire. Pour une transaction donnée, OneSpan Sign met en coffre une seule e-note au format SMART Document.

Certains paramètres de l'API REST associés à une transaction OneSpan Sign peuvent spécifier quel document doit être mis en coffre-fort, et dans quelle organisation et quel coffre-fort il doit être stocké. Après avoir été mis en coffre-fort, le document SMART original est supprimé de la base de données de OneSpan Sign.

eOriginal et OneSpan fournissent tous les deux des coffres-forts pour les notes électroniques. Les sections suivantes décrivent comment utiliser leurs coffres-forts :

Les modèles de documents intelligents que OneSpan Sign utilise pour les transactions impliquant des prêts hypothécaires prennent en charge les sections ARC dans le modèle. Cette caractéristique est exigée par la Federal Home Loan Mortgage Corporation (également connue sous le nom de Freddie Mac) des États-Unis.

La création d'une transaction ou d'un modèle avec l'API REST implique toujours certains paramètres standard - voir Paramètres de Expérience du signataire.

Si vous souhaitez visualiser tous les appels existants, consultez notre Spécification API ouverte interactive. De là, vous pouvez télécharger le fichier YAML de notre API REST, rechercher des points d'extrémités spécifiques dans cette API, et même essayer quelques appels vous-même.

Chaque fois qu'une tentative de dépôt électronique de documents dans un coffre-fort eOriginal échoue, OneSpan Sign envoie une notification à l'expéditeur de la transaction associée via un événement de rappel. Une fois que l'effort de voute d'un document subit une erreur non récupérable, OneSpan Sign envoie à l'expéditeur un courriel électronique signalant l'échec. Le modèle du courriel ne peut pas être personnalisé.

Utilisation d'un coffre-fort eOriginal

Si vous souhaitez stocker une e-note dans un coffre-fort eOriginal, la première chose à faire est de demander à notre équipe de soutien d'activer cette fonctionnalité pour votre compte.

Pour demander à OneSpan Sign de stocker un e-Note dans un coffre-fort eOriginal, les intégrateurs doivent ajouter les deux champs suivants au champ data de la transaction :

eOriginal met en coffre-fort un e-Note provenant d'une transaction OneSpan Sign ainsi que le journal d'audit de la transaction.

Si une transaction hypothécaire comporte un document SMART et un ou plusieurs PDF : (1) un coffre-fort eOriginal peut stocker tous ces documents pour la transaction; (2) la piste d'audit eOriginal répertorie tous les événements liés à la transaction et à ses multiples documents.

enote_data_section

Ce champ contient une chaîne XML codée en base64. Cette chaîne contient suffisamment d'informations pour créer le document SMART (notamment la valeur du prêt, les coordonnées de l'emprunteur et l'adresse du bien hypothéqué).

Ce champ doit être formaté en utilisant le format XML dans la section Données > Principal de la spécification MISMO SMART Document 1.02.

Exemple

Voici un exemple de valeur enote_data_section décodée en Base64 :

<LOAN MISMOVersionIdentifier="2.3">
    <_APPLICATION>
        <LOAN_PRODUCT_DATA>
            <LOAN_FEATURES LienPriorityType="FirstLien" LoanMaturityDate="2030-01-01" OriginalPrincipalAndInterestPaymentAmount="1111.99" ScheduledFirstPaymentDate="2020-01-01">
                <LATE_CHARGE _GracePeriod="15" _Rate="5.000"></LATE_CHARGE>
                <NOTE_PAY_TO _City="Springfield" _PostalCode="99999" _State="MI" _StreetAddress="5555 Example Drive"></NOTE_PAY_TO>
            </LOAN_FEATURES>
        </LOAN_PRODUCT_DATA>
        <MERS MERS_MINNumber="100316200000000012"/>
        <MORTGAGE_TERMS LenderLoanIdentifier="999999999" NoteRatePercent="5.300" OriginalLoanAmount="205000.00" PaymentRemittanceDay="1"></MORTGAGE_TERMS>
        <PROPERTY _City="Greenfield" _County="Green" _PostalCode="00000" _State="CA" _StreetAddress="100 Main Street">
            <PARSED_STREET_ADDRESS _HouseNumber="100" _StreetName="Main Street"></PARSED_STREET_ADDRESS>
        </PROPERTY>
        <BORROWER BorrowerID="N1001" NonPersonEntityIndicator="N" _FirstName="Homer" _LastName="Homeowner" _MiddleName="J." _SSN="555555559" _SequenceIdentifier="1" _UnparsedName="HomerJHomeowner"></BORROWER>
        <BORROWER BorrowerID="N1002" NonPersonEntityIndicator="N" _FirstName="Patricia" _LastName="Purchaser" _MiddleName="P." _SSN="666666669" _SequenceIdentifier="2" _UnparsedName="PatriciaPPurchaser"></BORROWER>
    </_APPLICATION>
    <_CLOSING_DOCUMENTS>
        <EXECUTION _City="Orange" _Date="2020-01-01" _State="CA"></EXECUTION>
        <LENDER _UnparsedName="Sample Banking Group"></LENDER>
    </_CLOSING_DOCUMENTS>
</LOAN>

enote_vaulting_data

Ce champ doit être une chaîne JSON codée en Base-64. Lorsque le champ est décodé, les paramètres du tableau suivant peuvent être visualisés.

Paramètre Requis? Description
vaultCredentials Oui

Cet objet JSON contient les informations d'authentification pour accéder à l'API du service eCore d'eOriginal. Cet objet doit contenir les champs obligatoires suivants :

  • NomUtilisateur - ID de connexion à l'API de l'utilisateur de l'API qui effectuera l'opération de dépôt dans le coffre-fort.
  • orgName - Nom court de l'organisation au sein du service eCore d'eOriginal, où la e-Note sera stockée.

  • apiKey - Clé API de 32 caractères de l'utilisateur de l'API.

Cet objet JSON contient également le champ facultatif suivant (une valeur par défaut sera utilisée si le champ du point de terminaison n'est pas spécifié) :

  • Point final - L'environnement eOriginal dans lequel les documents seront déposés. Les valeurs possibles sont :

    • TestSurDemande - Il s'agit : (i) d'une des deux valeurs prises en charge pour les comptes Sandbox; (ii) de la valeur par défaut pour les comptes Sandbox.

    • AperçuSurDemande - Il s'agit de l'autre valeur prise en charge pour les comptes Sandbox.

    • ondemand - Il s'agit : (i) de la seule valeur prise en charge pour les comptes de production; (ii) de la valeur par défaut pour les comptes de production.

enote_name Oui Nom qui sera donné à l'e-Note dans la transaction OneSpan Sign associée (et plus tard à l'e-Note dans le coffre-fort eOriginal).
document_type Oui Ce paramètre est utilisé dans le service eCore d'eOriginal pour classer les documents en fonction du processus qui leur est associé dans votre entreprise. Cela doit correspondre à un type de document qui a été configuré pour votre service eOriginal eCore Customer Org.
loanOriginators Oui

La valeur de ce paramètre est un tableau JSON qui doit contenir une ou plusieurs entrées, dont chacune comporte les trois éléments suivants :

  • nmlsId - Identifiant attribué à l'initiateur du prêt par le Nationwide Mortgage Licensing System And Registry (système et registre de licences hypothécaires à l'échelle nationale)
  • NomNonInterprété - Nom de la personne ou de l'organisation à l'origine du prêt
  • IndicateurEntitéOrganisation - Les valeurs possibles sont O et N. O indique que les données relatives au prêteur représentent une organisation. N indique que les données relatives au prêteur représentent un individu.
version Non Version du protocole à utiliser. Actuellement, la seule valeur prise en charge est Hypothèque-2.0.
enote_template_name Non

Nom du modèle qui sera utilisé pour créer le document SMART. Les valeurs prises en charge sont les suivantes :

  • template_3200_enote.xml - Ceci est pour le formulaire Multistate Fixed Rate eNote 3200e.

  • template_3244-1_enote.xml - Il s'agit du formulaire Texas Home Equity eNote 3244.1.

  • template_3244-2_enote.xml - Il s'agit du formulaire Texas Home Equity eNote Second Lien.

additionalDocumentsToVault Non

La valeur de ce paramètre est un tableau JSON qui doit contenir une ou plusieurs entrées. Chaque entrée : (1) contient des informations sur la mise en coffre-fort d'un document spécifique; (2) doit comporter les champs obligatoires suivants :

  • documentId - ID du document OneSpan Sign qui sera mis en coffre-fort avec le service eCore d'eOriginal. Ce document est généralement un prêt. La valeur de ce paramètre doit correspondre à l'ID d'un document dans la transaction.

  • IdPrêt - ID unique du prêt, selon le système du client

  • MontantPrêt - Montant initial du prêt en cents USD

  • Prêteur - Nom du prêteur pour ce prêt

  • type - Paramètre utilisé dans le service eCore d'eOriginal pour classer les documents en fonction du processus qui leur est associé dans votre entreprise. Doit correspondre à un type de document qui a été configuré pour votre service eOriginal eCore Customer Org.

postRegisterOption Non

Une fois que la copie faisant autorité d'un document est mise en coffre-fort dans un coffre-fort eOriginal, elle est retirée de OneSpan Sign. Ce paramètre spécifie comment cette copie faisant autorité sera remplacée dans OneSpan Sign. Les valeurs prises en charge sont les suivantes :

  • watermark_doc (par défaut) - Après la mise en coffre d'un document, le contenu du PDF signé est marqué d'un filigrane, aplati et enregistré sur OneSpan Sign.

  • blank_doc - Après la mise en coffre-fort d'un document, le contenu du PDF signé est remplacé dans OneSpan Sign par un document vierge.

Remarque : Les clients ne peuvent pas télécharger la copie faisant autorité d'un document qui sera déposé dans un coffre-fort eOriginal. S'ils essaient de le faire, ils finiront par télécharger une copie non autorisée aplatie dont chaque page portera le filigrane Copie non autorisée.

customFields Non

Cet objet JSON contient des données qui seront ajoutées à la transaction eOriginal en tant que champs personnalisés.

Cet objet peut contenir n'importe quel champ tant que son nom correspond à celui d'un champ personnalisé configuré pour votre service eOriginal eCore Customer Org.

Exemple

Voici un exemple de valeur enote_vaulting_data décodée en Base64 :

{
    "version": "Mortgage-2.0",
    "vaultCredentials": {
        "username": "SampleUsername",
        "orgName": "SampleOrganization",
        "apiKey": "ok0Sample0ApiKey0Just0An0Example",
        "endpoint":"testondemand"
    },
    "enote_name": "enote",
    "enote_template_name": "template_3200_enote.xml",
    "document_type": "eNote",
    "loanOriginators": [{
        "nmlsId": "1000000",
        "unparsedName": "Sample Lender Person",
        "nonPersonEntityIndicator": "N"
    },
    {
        "nmlsId": "1323233",
        "unparsedName": "Sample Lender Corp.",
        "nonPersonEntityIndicator": "Y"
    }],
    "customFields": {
        "externalId":"123ABC",
        "customField2":"value"
    },
}

Utilisation d'un coffre-fort OneSpan

Pour demander à OneSpan Sign de stocker ue e-Note dans un coffre-fort OneSpan, les intégrateurs doivent ajouter les deux champs suivants au champ data de la transaction :

enote-data-section

Ce champ contient une chaîne XML codée en base64. Cette chaîne contient suffisamment d'informations pour créer le document SMART (notamment la valeur du prêt, les coordonnées de l'emprunteur et l'adresse du bien hypothéqué).

Ce champ doit être formaté en utilisant le format XML dans la section Données > Principal de la spécification MISMO SMART Document 1.02.

Exemple

Voici un exemple de valeur enote_data_section décodée en Base64 :

<LOAN MISMOVersionIdentifier="2.3">
    <_APPLICATION>
        <LOAN_PRODUCT_DATA>
            <LOAN_FEATURES LienPriorityType="FirstLien" LoanMaturityDate="2030-01-01" OriginalPrincipalAndInterestPaymentAmount="1111.99" ScheduledFirstPaymentDate="2020-01-01">
                <LATE_CHARGE _GracePeriod="15" _Rate="5.000"></LATE_CHARGE>
                <NOTE_PAY_TO _City="Springfield" _PostalCode="99999" _State="MI" _StreetAddress="5555 Example Drive"></NOTE_PAY_TO>
            </LOAN_FEATURES>
        </LOAN_PRODUCT_DATA>
        <MERS MERS_MINNumber="100316200000000012"/>
        <MORTGAGE_TERMS LenderLoanIdentifier="999999999" NoteRatePercent="5.300" OriginalLoanAmount="205000.00" PaymentRemittanceDay="1"></MORTGAGE_TERMS>
        <PROPERTY _City="Greenfield" _County="Green" _PostalCode="00000" _State="CA" _StreetAddress="100 Main Street">
            <PARSED_STREET_ADDRESS _HouseNumber="100" _StreetName="Main Street"></PARSED_STREET_ADDRESS>
        </PROPERTY>
        <BORROWER BorrowerID="N1001" NonPersonEntityIndicator="N" _FirstName="Homer" _LastName="Homeowner" _MiddleName="J." _SSN="555555559" _SequenceIdentifier="1" _UnparsedName="HomerJHomeowner"></BORROWER>
        <BORROWER BorrowerID="N1002" NonPersonEntityIndicator="N" _FirstName="Patricia" _LastName="Purchaser" _MiddleName="P." _SSN="666666669" _SequenceIdentifier="2" _UnparsedName="PatriciaPPurchaser"></BORROWER>
    </_APPLICATION>
    <_CLOSING_DOCUMENTS>
        <EXECUTION _City="Orange" _Date="2020-01-01" _State="CA"></EXECUTION>
        <LENDER _UnparsedName="Sample Banking Group"></LENDER>
    </_CLOSING_DOCUMENTS>
</LOAN>

enote_attribute

Ce champ contient une chaîne JSON codée en base64, qui contient à son tour les paramètres suivants.

Les coffres-fortsOneSpan sont administrés par le produit e-Vault Manager de l'entreprise.

Paramètre Requis? Description
enote_name Oui Nom qui sera donné à l'e-Note dans la transaction associée OneSpan Sign (et plus tard à l'e-Note dans e-Vault Manager)
org_uid Oui ID unique de l'organisation. Il s'agit du même ID d'organisation utilisé par les utilisateurs lorsqu'ils se connectent à la console e-Vault Manager.
vault_id Oui ID numérique du coffre-fort dans lequel l'e-Note sera stocké. Un administrateur d'organisation peut voir l'ID du coffre-fort en consultant les détails de l'espace de stockage dans la console e-Vault Manager.
transaction_name Oui Nom qui sera donné à la transaction du gestionnaire de coffre-fort électronique utilisée pour enregistrer l'e-note auprès du gestionnaire de coffre-fort électronique
loanOriginators Oui

La valeur de ce paramètre est un tableau JSON qui doit contenir une ou plusieurs entrées, dont chacune comporte les trois éléments suivants :

  • nmlsId - Identifiant attribué à l'initiateur du prêt par le Nationwide Mortgage Licensing System And Registry (système et registre de licences hypothécaires à l'échelle nationale)

  • NomNonInterprété - Nom de la personne ou de l'organisation à l'origine du prêt
  • IndicateurEntitéOrganisation - Les valeurs possibles sont O et N. O indique que les données relatives au prêteur représentent une organisation. N indique que les données relatives au prêteur représentent un individu.
enote_template_name Non

Nom du modèle qui sera utilisé pour créer le document SMART. Les valeurs prises en charge sont les suivantes :

  • template_3200_enote.xml - Ceci est pour le formulaire Multistate Fixed Rate eNote 3200e.
  • template_3244-1_enote.xml - Il s'agit du formulaire Texas Home Equity eNote 3244.1.

  • template_3244-2_enote.xml - Il s'agit du formulaire Texas Home Equity eNote Second Lien.

Exemple

Voici un exemple de valeur d'attribut enote_ décodée en Base64 :

{
    "enote_name": "enote",
    "enote_template_name": "template_3200_enote.xml",
    "transaction_name": "t",
    "org_uid": "org1",
    "vault_id": "1",
    "loanOriginators": [{
        "nmlsId": "1000000",
        "unparsedName": "Sample Lender Person",
        "nonPersonEntityIndicator": "N"
    },
    {
        "nmlsId": "1323233",
        "unparsedName": "Sample Lender Corp.",
        "nonPersonEntityIndicator": "Y"
    }]
}

Modèle de courriel pour un échec de mise en coffre-fort

Si une tentative de mise en coffre d'un e-Note échoue, OneSpan Sign utilise le modèle suivant pour envoyer à l'expéditeur de la transaction associée un courriel signalant l'échec.

Ce modèle ne peut pas être personnalisé.

<?xml version="1.0" encoding="UTF-8"?>
<email-template xmlns="urn:schema.awsng.silanis.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<from>
<email>[email protected]</email>
<display_name>OSS Support</display_name>
</from>
<to>
<address>
<email>%USER_EMAIL;</email>
<display_name>%USER_FIRST_NAME; %USER_LAST_NAME;</display_name>
</address>
</to>
​
<subject>e-Sign Ceremony Failure Notification</subject>
<body>
<content-type>text/html; charset="UTF-8"</content-type>
<content>
​
Dear %USER_FIRST_NAME; %USER_LAST_NAME;,<br/>
<br/>
An error has occurred for your package: <br/>
<br/>
%NOTIFICATION_MESSAGE;<br/>
<br/>
Should you have any problem, please contact OSS Support at [email protected]
.<br/>
<br/>
​
Thank you for e-signing.<br/>
<br/>
​
OSS Support
</content>
</body>
<priority>1</priority>
​
</email-template>

La notification d'échec ci-dessus ne sera pas envoyée si l'une des erreurs suivantes se produit dans le champ JSON vaulting_data :

Erreur Ce que la requête POST/api/paquets retourne
Le champ documentId du paramètre documentsAuCoffre est incorrect (c'est-à-dire qu'il ne s'agit pas d'un IdDocument dans la transaction). 200
Le champ NomUtilisateur du paramètre identifiantsCoffre est incorrect. 200
Le champ cléAPI du paramètre identifiantsCoffre est incorrect.

500

"messageKey": "error.internal.default","technical": "error.eslx.validation.eoclient.loginError”

Le champ nomOrg du paramètre identifiantsCoffre est incorrect, mais le champ cléAPI est correct.

500

"messageKey": "error.internal.default","technical": "error.eslx.validation.eoclient.loginError”

JSON incorrect - par exemple, référencement de identifiantsCoffre comme identifiantsCoffre. 200
Was this information helpful?
X