Guía de Conexión de DocuSign¶

Descripción General¶

Esta guía describe los requisitos del sistema y las instrucciones para conectar App Builder a un servidor de base de datos de Docusign Online como prerrequisito para ser utilizado como servicio en una aplicación.

Nota

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

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 más reciente
Postman v9.10 o más reciente

Instrucciones de Conexión¶

Adquirir Credenciales Desde el Sandbox de DocuSign¶

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 (en este ejemplo, App Builder docuSign)
Copie la clave de integración y guárdela para el siguiente paso
- También utilizará el ID de cuenta de API y el URI base de la cuenta en pasos posteriores
Haga clic en el botón + AGREGAR CLAVE SECRETA debajo de Autenticación y copie este valor, necesitará esta clave y no podrá ver la clave completa más tarde.
Desplácese hacia abajo hasta Configuración adicional y agregue esta URI de redireccionamiento: https://oauth.pstmn.io/v1/callback (Esto solo se aplica cuando se usa Postman; si se usa otra herramienta de desarrollo de 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.
Nombre su modelo y cargue un documento, haga clic en Siguiente; opcionalmente, agregue áreas de firma al documento, luego haga clic en Guardar.
Debajo del 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 Mediante el Cartero¶

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: grant_type
  - Valor: código_de_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 están 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 pulsar Enter con la URL anterior, copia lo que está en el campo URL y pégalo en algún lugar donde puedas ver la URL completa (es extremadamente larga). Copia el valor después de code= y antes de &state=, este es tu valor de code, pégalo en el Valor del paso 1 de esta sección y haz clic en Enviar en Postman. **Este paso debe realizarse rápidamente, el token de actualización del navegador web solo dura unos 2 minutos. **

Configurar la API del Token de Actualización en App Builder¶

Desde 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
- Tipo de contenido de la solicitud: Formulario
- Tipo de contenido de la respuesta: JSON
Haga clic en Guardar.

Agregar un Extremo de 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: Nombra tu 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 dato: Cadena
  - Valor de prueba: Básico {Autorización de Postman}
    
    Este valor se puede encontrar en la pestaña Encabezados de 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 los encabezados ocultos)
  - Tipo: Encabezado
  - Dirección: Entrada
- Parámetro 2
  - Nombre: grant_type
  - Tipo de dato: Cadena
  - Valor de prueba: refresh_token
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 3
  - Nombre: refresh_token
  - Tipo de dato: 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 App Builder para DocuSign¶

Desde 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, primera sección de referencia)
- Tipo de contenido de la solicitud: JSON
- Tipo de contenido de respuesta: JSON

Agregar un Extremo de API para la Modelo de 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: Nombra tu 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: AccountID
  - Tipo de dato: Cadena
  - Valor de prueba: ID de cuenta de API de DocuSign Sandbox (consulte la primera sección)
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 2
  - Nombre: Autorización
  - Tipo de dato: Cadena
  - Valor de prueba: Portador <Returned Access Token from the Token API>
  - Tipo: Encabezado
  - Dirección: Entrada
- Parámetro 3
  - Nombre: EmailBody
  - Tipo de dato: Cadena
  - Valor de prueba: Cuerpo del Correo de su elección, en este ejemplo, "Un documento necesita firmarse"
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 4
  - Nombre: EmailSubject
  - Tipo de dato: 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 dato: Cadena
  - Valor de prueba: enviado
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 6
  - Nombre: TemplateID
  - Tipo de dato: 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 EnvelopeID 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 de API para el Estado del Documento¶

En el panel Extremos en la parte inferior izquierda, haga clic en Crear
Agregue los siguientes detalles:
- Nombre: Nombra tu extremo
- Extremo: /v2/accounts/<AccountID>/envelopes/<EnvelopeID>
- Método: GET
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: AccountID
  - Tipo de dato: Cadena
  - Valor de prueba: ID de cuenta de API de DocuSign Sandbox (consulte la primera sección)
  - Tipo: Consulta
  - Dirección: Entrada
- Parámetro 2
  - Nombre: Autorización
  - Tipo de dato: Cadena
  - Valor de prueba: Portador <Returned Access Token from the Token API>
  - Tipo: Encabezado
  - Dirección: Entrada
- Parámetro 3
  - Nombre: EnvelopeID
  - Tipo de dato: Cadena
  - Valor de prueba: ID de 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 el App Builder IDE, haga clic en Construya su 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 la información de DocuSign.

Configurar App Builder reglas para DocuSign¶

Agregar Columnas para la Información de DocuSign¶

Desde el App Builder IDE, haga clic en Construya su 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 Origen de datos de la capa empresarial, en el lado derecho, haga clic en Vincular orígenes 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 icono de Business Objects y busque la tabla donde desea almacenar la configuración de DocuSign (en este ejemplo se utilizará ParamDocusign).
En la tabla, crea las siguientes columnas:
- URL base de Docusign (NVarchar(50))
- Tipo de concesión de Docusign (NVarchar(50))
- Token de actualización de Docusign (NVarchar(-1))
- ID de cliente de Docusign (NVarchar(-1))
Después de crear las columnas, haga clic en Resultados y agregue valores a las siguientes columnas:
- DocusignBaseURL: La URL base del ambiente sandbox de DocuSign
- DocusignGrantType: El valor de cadena literal 'refresh_token'
- DocusignRefreshToken: el parámetro de extremo refresh_token en la API REST de token (la primera API REST que creó)
- DocusignClientIDSecretID: El parámetro del 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 Rol (estos son parámetros de plantilla de DocuSign).

Crear una Regla de Inserción XP para Insertar Credenciales en el Token Después de la Llamada¶

Desde el paso anterior, vuelva a App Workbench.
En el panel central, haga clic en Agregar una regla de negocio para crear un nuevo objeto de negocio.
Complete los siguientes datos:
- Nombre: Tabla (Insertar token de acceso de actualización)
- Propósito: XP CRUD
- Desmarque la opción "Omitir capa empresarial"
- Acción: Insertar
- Fecha de origen 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 la fuente de datos de origen 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; apúntelas a sus columnas correspondientes en la tabla Token como se muestra a continuación.

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

Desde el paso anterior, vuelva a App Workbench.
En el panel central, haga clic en Agregar una regla de negocio para crear un nuevo objeto de negocio.
Complete los siguientes datos:
- Nombre: Tabla (Actualizar token de acceso)
- Propósito: XP CRUD
- Desmarque la opción "Omitir capa empresarial"
- Acción: Actualizar
- Fecha de origen Fuente: La primera API REST que creó para actualizar el token de acceso
- Origen de datos de destino: donde se encuentra la tabla con 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 llamada access_token y oriéntela a la columna DocusignClientIDSecretID que creó en la tabla.
Agregue API Account ID 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, configure el ID de cuenta de API del token de actualización para que tenga como objetivo el 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 ayudará a adaptar esa configuración.

Crear un Cronograma para Ejecutar el Evento de Actualización del Token de Acceso¶

Debido a que el token de acceso vence y debe actualizarse periódicamente, agregue esta regla a un evento y cree un cronograma.
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: RefreshToken
- Ámbito de actualización: Fila
Nota

Asegúrate de que en Caso extremo el Tipo de ejecución esté configurado en Iniciar mediante programación con máxima simultaneidad: 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 App Builder monitor (en la esquina inferior izquierda)  Programaciones. Nombre su programación y elija la aplicación donde se creará el evento que creó para la regla. Deje la frecuencia como está en "Ejecución periódica de la programación". En Información de programación, establezca la frecuencia de ejecución de la programación; se recomiendan 4 horas.

Ahora que está actualizando su token de acceso según un cronograma, 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 de estado del documento y plantilla creados en la segunda API REST.

Algunas funciones pueden implicar costos, como devolver un archivo mediante un webhook. Otra opción es usar el complemento HTTP retriever.

Promoción de la Aplicación en la Producción de DocuSign¶

Cuando los extremos y las reglas CRUD que ha creado funcionen de manera uniforme, estará listo para promover esta aplicación a DocuSign Production. Para ello, deberá hacer que se revise la API en DocuSign. Para aprobar la revisión, debe tener 20 llamadas a la API correctas en un solo día.

Navegue hasta el enlace de DocuSign Sandbox, 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 marcha e ingrese una fecha con 20 o más llamadas API exitosas
Un administrador de DocuSign revisará y autenticará manualmente la solicitud; esto puede demorar hasta 3 días hábiles.
Una vez autenticado el Go-Live, será necesario repetir los pasos anteriores con las credenciales de DocuSign de producción. La clave de integración permanecerá sin cambios, pero las demás credenciales serán diferentes y deberán actualizarse en Postman y App Builder.
Cambios en los pasos anteriores:
- En Postman, crea 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 usar en los POST, GET y las URLs de recuperación 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