Guía de Conexión de DocuSign 3.1¶

Descripción General¶

Esta guía describe los requisitos del sistema y las instrucciones para conectar Vinyl a un servidor de base de datos de Docusign Online como prerrequisito para ser utilizado como servicio en una aplicación. Para poder conectar tus servidores, debes tener instalado Vinyl 3.1.

Nota

Deberá agregar más extremos según las necesidades de su aplicación; para obtener más información, aquí está la guía de referencia oficial de la API de DocuSign ..

Requisitos del Sistema¶

Servidor de Base de Datos¶

Cuenta de desarrollador de DocuSign

Navegador Web del Cliente¶

Chrome TM 60 o más reciente
Firefox ® 55 o más reciente
Safari 11.0.2 o posterior
Cartero v9.10 o más reciente

Instrucciones de Conexión¶

Adquirir Credenciales de DocuSign Sandbox¶

Inicie sesión en DocuSign aquí: https://account-d.docusign.com/
Haga clic en Configuración en la esquina superior derecha de la página de aterrizaje.
En la barra lateral izquierda, desplácese hacia abajo hasta Integraciones y haga clic en Aplicaciones y claves.
Cree una aplicación haciendo clic en el botón AGREGAR APLICACIÓN Y CLAVE DE INTEGRACIÓN.
Escriba el nombre de la aplicación (este ejemplo es Vinyl DocuSign)
Copie la clave de integración y guárdela para el siguiente paso.
- También utilizará el ID de cuenta API y el URI base de la cuenta en pasos posteriores.
Haga clic en el botón + AGREGAR CLAVE SECRETA en Autenticación y copie este valor; necesita esta clave y no podrá verla completa más adelante.
Desplácese hacia abajo hasta Configuración adicional y agregue este URI de redireccionamiento: https://oauth.pstmn.io/v1/callback (Esto solo se aplica cuando se usa Postman; si usa otra herramienta de desarrollo API, consulte su documentación)
Haga clic en Guardar
Haga clic en Plantillas en el menú de la barra superior.
Haga clic en Nuevo en la esquina superior izquierda para crear una nueva modelo que se utilizará durante la configuración de la conexión.
Asigne un nombre a su modelo y cargue un documento, haga clic en Siguiente; Opcionalmente, agregue áreas de firma al documento y luego haga clic en Guardar.
Bajo el nombre de su nueva modelo, Haga clic en ID DE PLANTILLA, copie y guarde este valor; lo necesitará en un paso posterior.

Adquirir Token de Actualización Usando Postman¶

Cree una nueva solicitud POST con los siguientes parámetros:
- URL: https://account-d.docusign.com/oauth/token >/
- Autorización: autenticación básica
  - Nombre de usuario = Clave de integración de la sección anterior
  - Contraseña = Clave secreta de la sección anterior
- Cuerpo: x-www-form-urlunencoded
  - Clave: tipo_concesión
  - Valor: código_autorización
  - Clave: código
  - Valor: *obtendrás este segundo valor en el siguiente paso

En un navegador web, vaya al siguiente sitio web y sustituya los valores que se encuentran entre < y >, es decir. <value>.

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signatureextended&client_id=<Integration Key from DocuSign Sandbox>&state=a39fh23hnf23&redirect_uri=https://oauth.pstmn.io/v1/callback

Después de presionar Enter con el URI anterior, copie lo que hay en el campo URL y péguelo en algún lugar donde pueda ver la URL completa (es extremadamente larga). Copie el valor después de code= y antes de &state=, este es su valor de código, péguelo en el Valor del paso 1 de esta sección y haga clic en Enviar en Postman. **Este paso debe realizarse rápidamente, el token de actualización del navegador web solo dura aproximadamente 2 minutos. **

Configurar la API de Token de Actualización en Vinyl¶

En el menú Conectar, haga clic en el enlace Conectarse a su empresa
Haga clic en Servidores de datos en el lado izquierdo y haga clic en Crear.
Configure el servidor de la siguiente manera:
- Nombre: Nombre reconocible
- Tipo: API REST
- URL: https://account-d.docusign.com
- Solicitar tipo de contenido: Formulario
- Tipo de contenido de respuesta: JSON
Haga clic en Guardar.

Agregar un Extremo API¶

Cierre la ventana emergente Crear servidor de datos y luego haga clic en el nombre del servidor que acaba de crear en la lista de servidores de datos.
En el panel Extremos en la parte inferior izquierda, haga clic en Crear
Agregue los siguientes detalles:
- Nombre: asigne un nombre a su extremo
- Extremo: /oauth/token
- Método: POST
A continuación, agregará los siguientes parámetros de extremo haciendo clic en Crear en el panel Parámetros de Extremo en la parte superior derecha y agregará los siguientes detalles:
- Parámetro 1
  - Nombre: Autorización
  - Tipo de datos: Cadena
  - Valor de prueba: Básico {Autorización del cartero}
    
    Este valor se puede encontrar en la pestaña Encabezados en Postman después de la llamada POST para recuperar el token de actualización. Dirá básico seguido de una identificación larga. (Es posible que tengas que buscar en encabezados ocultos)
  - Tipo: Encabezado
  - Dirección: Entrada
- Parámetro 2
  - Nombre: tipo_concesión
  - Tipo de datos: Cadena
  - Valor de prueba: refresco_token
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 3
  - Nombre: refresco_token
  - Tipo de datos: Cadena
  - Valor de prueba: el token de actualización que recuperaste en Postman en el paso anterior
  - Tipo: Consulta
  - Dirección: Entrada
Haga clic en Guardar
Haga clic en Probar conexión para obtener el token de acceso para el siguiente paso.

Agregue a la entrada de muestra los parámetros de consulta de la siguiente manera:

{ "grant_type": "refresh_token", "refresh_token": "<refresh token from postman>"}

Haga clic en Importar

Configurar Vinyl para DocuSign¶

En el menú Conectar, haga clic en el enlace Conectarse a su empresa
Haga clic en Servidores de datos en el lado izquierdo y haga clic en Crear.
Configure el servidor de la siguiente manera:
- Nombre: Nombre reconocible
- Tipo: API REST
- URL: https://demo.docusign.net/restapi (Esto es de DocuSign Sandbox, referencia a la primera sección)
- Tipo de contenido de solicitud: JSON
- Tipo de contenido de respuesta: JSON

Agregar un Extremo API para la Plantilla DocuSign¶

Cierre la ventana emergente Crear servidor de datos y luego haga clic en el nombre del servidor que acaba de crear en la lista de servidores de datos.
En el panel Extremos en la parte inferior izquierda, haga clic en Crear
Agregue los siguientes detalles:
- Nombre: asigne un nombre a su extremo
- Extremo: /v2/accounts/<AccountID>/envelopes
- Método: POST
A continuación, agregará los siguientes parámetros de extremo haciendo clic en Crear en el panel Parámetros de Extremo en la parte superior derecha y agregará los siguientes detalles:
- Parámetro 1
  - Nombre: ID de cuenta
  - Tipo de datos: Cadena
  - Valor de prueba: ID de cuenta API de DocuSign Sandbox (consulte la primera sección)
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 2
  - Nombre: Autorización
  - Tipo de datos: Cadena
  - Valor de prueba: Portador <Returned Access Token from the Token API>
  - Tipo: Encabezado
  - Dirección: Entrada
- Parámetro 3
  - Nombre: Cuerpo de correo electrónico
  - Tipo de datos: Cadena
  - Valor de prueba: cuerpo del Correo de su elección; en este ejemplo, "Un documento necesita firma".
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 4
  - Nombre: Correo electrónicoAsunto
  - Tipo de datos: Cadena
  - Valor de prueba: asunto del Correo de su elección, en este ejemplo, "Firma"
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 5
  - Nombre: estado
  - Tipo de datos: Cadena
  - Valor de prueba: enviado
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 6
  - Nombre: ID de plantilla
  - Tipo de datos: Cadena
  - Valor de prueba: el ID de plantilla de la primera sección
  - Tipo: Consulta
  - Dirección: Entrada
Haga clic en Probar conexión para asegurarse de que los parámetros se hayan ingresado correctamente y para ver los resultados de la prueba; el SobreID se utilizará en el siguiente paso.
Haga clic en el botón Atrás en la parte superior izquierda para regresar a Servicio web y agregar un extremo adicional.

Agregar un Extremo API para el Estado del Documento¶

En el panel Extremos en la parte inferior izquierda, haga clic en Crear
Agregue los siguientes detalles:
- Nombre: asigne un nombre a su extremo
- Extremo: /v2/accounts/<AccountID>/envelopes/<EnvelopeID>
- Método: OBTENER
A continuación, agregará los siguientes parámetros de extremo haciendo clic en Crear en el panel Parámetros de Extremo en la parte superior derecha y agregará los siguientes detalles:
- Parámetro 1
  - Nombre: ID de cuenta
  - Tipo de datos: Cadena
  - Valor de prueba: ID de cuenta API de DocuSign Sandbox (consulte la primera sección)
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 2
  - Nombre: Autorización
  - Tipo de datos: Cadena
  - Valor de prueba: Portador <Returned Access Token from the Token API>
  - Tipo: Encabezado
  - Dirección: Entrada
- Parámetro 3
  - Nombre: ID de sobre
  - Tipo de datos: Cadena
  - Valor de prueba: ID del sobre que se devolvió al probar el extremo anterior
  - Tipo: Consulta
  - Dirección: Entrada
Haga clic en Probar conexión para asegurarse de que los parámetros se hayan ingresado correctamente y para ver los resultados de la prueba.

Hacer Públicas las Tablas de DocuSign para Su Uso Posterior¶

Desde Vinyl IDE, haga clic en Crea tu aplicación
Haga clic en Capa de almacenamiento de datos y en Servicios web busque la API Rest de DocuSign que creó en el paso anterior.
Haga clic en el icono de engranaje Tablas
Para cada tabla, haga doble clic en la tabla y haga clic en Configuración de casos extremos
En Acceso público, haga clic en Permitir lectura y Permitir escritura.
Realice los mismos pasos para la API REST del token de DocuSign y cualquier otro extremos que haya creado para DocuSign Information.

Configurar Reglas de Vinyl para DocuSign¶

Agregar Columnas para Información de DocuSign¶

Desde Vinyl IDE, haga clic en Crea tu aplicación
Haga clic en Capa de lógica empresarial y busque la fuente de datos en la que desea almacenar la información de DocuSign.
En el panel Fuente de datos de la capa empresarial en el lado derecho, haga clic en Vincular fuentes y agregue la API REST de DocuSign que creó en el paso anterior *asegúrese de haber marcado las tablas como Permitir lectura/escritura*
Haga clic en el ícono Business Objects y busque la tabla donde desea almacenar la configuración de DocuSign (este ejemplo usará ParamDocusign)
En la tabla, cree las siguientes columnas:
- DocusignBaseURL (NVarchar(50))
- DocusignGrantType (NVarchar(50))
- DocusignRefreshToken (NVarchar(-1))
- DocusignClientIDSecretID (NVarchar(-1))
Una vez creadas las columnas, haga clic en Resultados y agregue valores a las siguientes columnas:
- DocusignBaseURL: la URL base del ambiente limitado de DocuSign
- DocusignGrantType: el valor de cadena literal 'refresh_token'
- DocusignRefreshToken: el parámetro de extremo de actualización_token en la API REST del token (la primera API REST que creó)
- DocusignClientIDSecretID: el parámetro de extremo de autorización en la API REST del token
También puede agregar otras columnas para editarlas en la interfaz de usuario, como Cuerpo del Correo, Asunto del Correo y Función (estos son parámetros de la plantilla de DocuSign).

Cree una Regla de Inserción de XP para Insertar Credenciales en la Llamada POST del Token¶

Desde el paso anterior, regrese a App Workbench.
En el panel central, haga clic en Agregar una regla comercial para crear un nuevo objeto comercial.
Complete los siguientes detalles:
- Nombre: Tabla (Insertar token de acceso de actualización)
- Propósito: XP CRUD
- Desmarque "Omitir capa empresarial"
- Acción: Insertar
- Fuente Fecha Fuente: Base de datos donde se almacena la tabla con la información de DocuSign
- Fuente de datos de destino: la primera API REST que creó para actualizar el token de acceso
- Destino: tabla de la API de token de actualización (en este ejemplo, token)
En el panel Tablas, haga clic en +Tablas y agregue la tabla de su fuente de datos donde se almacena la información de DocuSign. En este caso, ParamDocusign.
En la pestaña de columnas, busque las columnas que designó para almacenar el token de actualización, el ClientID/SecretID y el tipo de concesión; oriéntelas a sus columnas correspondientes en la tabla Token como se muestra a continuación.

Cree una Regla de Actualización de XP para Actualizar el Token de Acceso¶

Desde el paso anterior, regrese a App Workbench.
En el panel central, haga clic en Agregar una regla comercial para crear un nuevo objeto comercial.
Complete los siguientes detalles:
- Nombre: Tabla (Actualizar token de acceso de actualización)
- Propósito: XP CRUD
- Desmarque "Omitir capa empresarial"
- Acción: Actualizar
- Fuente Fecha Fuente: La primera API REST que creó para actualizar el token de acceso
- Fuente de datos de destino: donde se encuentra la tabla con la información de DocuSign
- Destino: Tabla donde se almacena la información de DocuSign, ParamDocusign en este ejemplo
En el panel Tablas, haga clic en Crear y agregue la tabla con el token de acceso (este es el nombre del extremo que creó en la primera API REST).
Haga clic en Todos para agregar todas las columnas de la tabla.
Busque la columna denominada access_token y oriéntela a la columna DocusignClientIDSecretID que creó en la tabla.
Agregue ID de cuenta API a ParamDocusign como una columna e ingrese su valor
Agregue ID de cuenta API como parámetro en el Extremo del token de actualización e ingrese su valor
En la regla de actualización, establezca el ID de cuenta API del token de actualización para apuntar al ID de cuenta de ParamDocusign en el enlace de tipo y configúrelo como PK. Esto tiene el beneficio adicional de que si decide agregar más cuentas de DocuSign a la aplicación, esto le ayudará a adaptarse a esa configuración.

Crear Programación para Ejecutar el Evento de Token de Acceso de Actualización¶

Debido a que el token de acceso caduca y debe actualizarse periódicamente, agregue esta regla a un evento y cree una programación.
Cree el evento navegando a la capa de lógica empresarial y en la ventana emergente Eventos de ParamDocusign, haga clic en +Evento de tabla.
- Nombre: ActualizarToken
- Actualizar alcance: fila
Nota

Asegúrese de que en el caso Edge el Tipo de ejecución esté configurado en Iniciar mediante programación con simultaneidad máxima: 1.
En Acciones, haga clic en Registrar existente y agregue la regla CRUD creada anteriormente: Tabla (Actualizar token de acceso de actualización).
A continuación, navegue hasta Vinyl Monitor (en la esquina inferior izquierda)  Horarios. Asigne un nombre a su programación y elija la Aplicación donde se crea el evento que creó para la regla. Deje la frecuencia como está en "Ejecución periódica del cronograma". En Información de programación, establezca la frecuencia para que se ejecute la programación; se recomiendan 4 horas.

Ahora que está actualizando su token de acceso de forma programada, puede mantener una conexión con su API de DocuSign. Cree otras reglas CRUD de XP según sea necesario para enviar o recuperar información de la cuenta de DocuSign conectada, como los extremos Estado del documento y Plantilla creados en la segunda API REST.

Algunas capacidades pueden generar costos, como devolver un archivo mediante un webhook. Otra opción es usar el complemento de recuperación HTTP.

Promoción de Aplicaciones para la Producción de DocuSign¶

Cuando los extremos y las reglas CRUD que ha creado funcionen de manera consistente, estará listo para promover esta aplicación a DocuSign Production. Para hacer esto, necesitarás revisar la API en DocuSign. Para aprobar la revisión, debe realizar 20 llamadas API exitosas en un solo día.

Navegue hasta el enlace DocuSign Sandbox en el primer paso y haga clic en Administrador, luego haga clic en Aplicaciones y claves en el menú del lado izquierdo.
En Aplicaciones y claves de integración busque la aplicación que creó en el primer paso y haga clic en Acciones, luego seleccione Iniciar revisión de puesta en funcionamiento e ingrese una fecha con 20 o más llamadas API exitosas.
Un administrador de DocuSign revisará y autenticará manualmente la solicitud; esto puede tardar hasta 3 días hábiles.
Después de autenticar Go-Live, será necesario repetir los pasos anteriores con las credenciales de Production DocuSign. La clave de integración permanecerá sin cambios, pero las otras credenciales serán diferentes y deberán actualizarse en Postman y Vinyl.
Cambios a los pasos anteriores:
- En Postman, cree una nueva llamada GET con la URL: https://account.docusign.com/oauth/userinfo
- En la respuesta de la llamada GET, copie el "base_uri" para usarlo en las URLs de recuperación POST, GET y HTTP para el ambiente de producción.
- Al crear la API de token de actualización para producción, la URL es https://account.docusign.com