Last modified: 2022-10-28

API REST

OneSpan Sign ha creado una Digital Mortgage Solution capaz de almacenar una nota electrónica de una transacción hipotecaria en un almacén digital. Para una transacción determinada, OneSpan Sign almacena una sola nota electrónica en formato de documento SMART.

Ciertas configuraciones de la API REST asociadas a una transacción de OneSpan Sign pueden especificar qué documento debe guardarse en el almacén, y en qué organización y almacén debe almacenarse. Después del almacenamiento, el documento SMART original se elimina de la base de datos de OneSpan Sign.

eOriginal y OneSpan ambos proporcionan almacenes de notas electrónicas. En las siguientes secciones, se describe cómo usar sus almacenes:

Las plantillas de documento SMART que OneSpan Sign utiliza para las transacciones que involucran hipotecas admiten secciones ARC dentro del formulario. Esta función es exigida por la Federal Home Loan Mortgage Corporation de los EE. UU. (también conocida como la Freddie Mac).

Crear una transacción o plantilla con la API REST siempre implica ciertas configuraciones estándar (consulte Configuración de la Experiencia para firmantes).

Si desea ver todas las llamadas existentes, consulte nuestra Especificación de API abierta interactiva. Desde ahí puede descargar el archivo YAML de nuestra API REST, buscar extremos específicos en esa API e incluso probar algunas llamadas.

Cuando un intento de eDeposit documents en un almacén de eOriginal falla, OneSpan Sign envía una notificación al remitente de la transacción asociada a través de un evento de devolución de llamada. Una vez que el esfuerzo de guardar un documento sufre un error no recuperable, OneSpan Sign envía al remitente un correo electrónico acerca del fallo. El formulario de este correo electrónico no se puede personalizar.

Usar un almacén de eOriginal

Si desea almacenar una nota electrónica en un almacén de eOriginal, lo primero que debe hacer es solicitar a nuestro Equipo de asistencia que habilite esta funcionalidad para su cuenta.

Para indicar a OneSpan Sign que se almacene una nota electrónica en un almacén de eOriginal, los integradores deben agregar los dos campos siguientes al campo data de la transacción:

eOriginal almacena una nota electrónica de una transacción de OneSpan Sign, junto con el Registro de auditoría de la transacción.

Si una transacción hipotecaria tiene un documento SMART y uno o más PDF: (1) un almacén de eOriginal puede almacenar todos esos documentos para la transacción; (2) la pista de auditoría de eOriginal enumera todos los eventos relacionados con la transacción y sus múltiples documentos.

enote_data_section

Este campo contiene una cadena XML codificada en base64. Esa cadena contiene suficiente información para crear el documento SMART (incluido el valor del préstamo, los detalles del prestatario y la dirección de la propiedad hipotecada).

Este campo debe formatearse utilizando el formato XML en la sección Data > Main (Datos > Principal) de la especificación MISMO SMART Document 1.02.

Ejemplo

A continuación, se muestra un ejemplo de un valor enote_data_section decodificado 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

Este campo debe ser una cadena JSON codificada con Base-64. Cuando se decodifica el campo, se pueden ver los parámetros de la siguiente tabla.

Parámetro ¿Obligatorio? Descripción
vaultCredentials

Este objeto JSON contiene las credenciales de autenticación para acceder a la API del servicio eCore de eOriginal. Este objeto debe contener los siguientes campos obligatorios:

  • username: ID de inicio de sesión de API del usuario de API que realizará la operación de depósito de almacén.
  • orgName: el nombre abreviado de la organización dentro del servicio eCore de eOriginal, donde se almacenará la nota electrónica.

  • apiKey clave de API de 32 caracteres del usuario de la API.

Este objeto JSON también contiene el siguiente campo opcional (se utilizará un valor predeterminado si no se especifica el campo endpoint):

  • endpoint: el entorno de eOriginal en el que se depositarán los documentos. Los valores posibles son:

    • testondemand: puede ser: (i) uno de los dos valores admitidos para las cuentas de Sandbox; (ii) el valor predeterminado para las cuentas de Sandbox.

    • previewondemand: este es el otro valor admitido para las cuentas de Sandbox.

    • ondemand: puede ser: (i) el único valor admitido para las cuentas de producción; (ii) el valor predeterminado para las cuentas de producción.

enote_name Nombre que se le dará a la nota electrónica en la transacción asociada de OneSpan Sign (y posteriormente a la nota electrónica en el almacén de eOriginal).
document_type Este parámetro se utiliza en el servicio eCore de eOriginal para clasificar documentos de acuerdo con su proceso asociado dentro de su negocio. Debe coincidir con un Tipo de documento que se haya configurado para la organización del cliente del servicio eCore de eOriginal.
loanOriginators

El valor de este parámetro es una matriz JSON que debe contener una o más entradas, cada una de las cuales tiene los siguientes tres elementos:

  • nmlsId: un identificador asignado a la entidad emisora del préstamo por Nationwide Mortgage Licensing System And Registry
  • unparsedName: el nombre de la persona u organización que originó el préstamo
  • nonPersonEntityIndicator: los valores posibles son Y y N. Y indica que estos datos de la entidad emisora del préstamo representan una organización. N indica que estos datos de la entidad emisora del préstamo representan a un individuo.
version No Versión del protocolo que se utilizará. Actualmente, el único valor admitido es Mortgage-2.0.
enote_template_name No

Nombre de la plantilla que se utilizará para crear el documento SMART. Los valores admitidos son:

  • template_3200_enote.xml: se utiliza para el formulario Multistate Fixed Rate eNote 3200e.

  • template_3244-1_enote.xml: se utiliza para el formulario Texas Home Equity eNote 3244.1.

  • template_3244-2_enote.xml: se utiliza para el formulario Texas Home Equity eNote Second Lien.

additionalDocumentsToVault No

El valor de este parámetro es una matriz JSON que debe contener una o más entradas. Cada entrada: (1) contiene información de almacenamiento para un documento específico; (2) debe tener los siguientes campos obligatorios:

  • documentId: ID del documento de OneSpan Sign que se guardará en el almacén con el servicio eCore de eOriginal. Este documento suele ser un préstamo. El valor de este parámetro debe coincidir con el ID de documento de un documento de la transacción.

  • loanId: ID único del préstamo, de acuerdo con el sistema del cliente

  • loanAmount: monto original del préstamo en centavos de dólar estadounidense

  • lender: el nombre del prestamista de este préstamo

  • type: este parámetro se utiliza en el servicio eCore de eOriginal para clasificar documentos de acuerdo con su proceso asociado dentro de su negocio. Debe coincidir con un Tipo de documento que se haya configurado para la organización del cliente del servicio eCore de eOriginal.

postRegisterOption No

Después de que la copia autorizada de un documento se almacena en un almacén de eOriginal, se elimina de OneSpan Sign. Este parámetro especifica cómo se reemplazará esta copia autorizada en OneSpan Sign. Los valores admitidos son:

  • watermark_doc (predeterminado): después de que se guarda un documento, el contenido PDF firmado se marca con una marca de agua, se aplana y se guarda en OneSpan Sign.

  • blank_doc: después de que se guarda un documento, el contenido PDF firmado se reemplaza en OneSpan Sign con un documento en blanco.

Nota: Los clientes no pueden descargar la copia autorizada de un documento que se depositará en un almacén de eOriginal. Si intentan hacerlo, terminarán descargando una copia no autorizada aplanada cuya cada página llevará la marca de agua Copia no autorizada.

customFields No

Este objeto JSON contiene datos que se agregarán a la transacción eOriginal como campos personalizados.

Este objeto puede contener cualquier campo siempre que su nombre coincida con el de un campo personalizado configurado para la organización del cliente del servicio eCore de eOriginal.

Ejemplo

A continuación, se muestra un ejemplo de un valor enote_vaulting_data decodificado 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"
    },
}

Usar un almacén de OneSpan

Para indicar a OneSpan Sign que se almacene una nota electrónica en un almacén de OneSpan, los integradores deben agregar los dos campos siguientes al campo data de la transacción:

enote-data-section

Este campo contiene una cadena XML codificada en base64. Esa cadena contiene suficiente información para crear el documento SMART (incluido el valor del préstamo, los detalles del prestatario y la dirección de la propiedad hipotecada).

Este campo debe formatearse utilizando el formato XML en la sección Data > Main (Datos > Principal) de la especificación MISMO SMART Document 1.02.

Ejemplo

A continuación, se muestra un ejemplo de un valor enote_data_section decodificado 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

Este campo contiene una cadena JSON codificada en base64 que contiene a su vez los siguientes parámetros.

Los almacenes OneSpan se administran mediante el producto e-Vault Manager de la empresa.

Parámetro ¿Obligatorio? Descripción
enote_name Nombre que se le dará a la nota electrónica en la transacción asociada de OneSpan Sign (y posteriormente a la nota electrónica del el e-Vault Manager)
org_uid ID único de la Organización. Este es el mismo ID de organización usado por los usuarios cuando inician sesión en la consola del e-Vault Manager.
vault_id ID numérico del almacén en el que se almacenará la nota electrónica. Un administrador de la organización puede ver el ID del almacén al ver los detalles del almacén en la consola de e-Vault Manager.
transaction_name Nombre que se dará a la transacción de e-Vault Manager utilizada para registrar la nota electrónica con e-Vault Manager
loanOriginators

El valor de este parámetro es una matriz JSON que debe contener una o más entradas, cada una de las cuales tiene los siguientes tres elementos:

  • nmlsId: un identificador asignado a la entidad emisora del préstamo por Nationwide Mortgage Licensing System And Registry

  • unparsedName: el nombre de la persona u organización que originó el préstamo
  • nonPersonEntityIndicator: los valores posibles son Y y N. Y indica que estos datos de la entidad emisora del préstamo representan una organización. N indica que estos datos de la entidad emisora del préstamo representan a un individuo.
enote_template_name No

Nombre de la plantilla que se utilizará para crear el documento SMART. Los valores admitidos son:

  • template_3200_enote.xml: se utiliza para el formulario Multistate Fixed Rate eNote 3200e.
  • template_3244-1_enote.xml: se utiliza para el formulario Texas Home Equity eNote 3244.1.

  • template_3244-2_enote.xml: se utiliza para el formulario Texas Home Equity eNote Second Lien.

Ejemplo

A continuación, se muestra un ejemplo de un valor enote_attribute decodificado 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"
    }]
}

Formulario de correo electrónico para un error de almacenamiento

Si un intento de guardar una nota electrónica falla, OneSpan Sign utiliza el siguiente formulario para enviar al remitente de la transacción asociada un correo electrónico acerca del error.

Este formulario no se puede personalizar.

<?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 notificación de fallo anterior no se enviará si se produce alguno de los siguientes errores dentro del campo de JSON vaulting_data:

Error Lo que devuelve la solicitud POST /api/packages
El campo documentId del parámetro documentsToVault es incorrecto (es decir, no es un documentID en la transacción). 200
El campo username del parámetro vaultCredentials es incorrecto. 200
El campo apiKey del parámetro vaultCredentials es incorrecto.

500

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

El campo orgName del parámetro vaultCredentials es incorrecto, pero el campo apiKey es correcto.

500

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

JSON incorrecto: por ejemplo, hacer referencia a vaultCredentials como valutCredentials. 200
Was this information helpful?
X