Saltar al contenido

¡Transforma tus conexiones en dinero para el final del año con nuestro nuevo Programa de Indicación de Clientes! Descubre más

Esta documentación es para la versión 4 y posteriores de App Builder, el nuevo nombre de Vinyl. Accede a la documentación de Vinyl aquí.

Guía de conexión de DocuSign para Jitterbit App Builder

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 su uso como servicio en una aplicación.

Nota

Necesitará agregar extremos adicionales según las necesidades de su aplicación. Para obtener más información, aquí está 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 del ambiente sandbox de DocuSign

  1. Inicie sesión en DocuSign aquí: https://account-d.docusign.com/

  2. Haga clic en Configuración en la esquina superior derecha de la página de aterrizaje.

  3. En la barra lateral izquierda, desplácese hacia abajo hasta Integraciones y haga clic en Aplicaciones y claves.

  4. Cree una aplicación haciendo clic en el botón AGREGAR APLICACIÓN Y CLAVE DE INTEGRACIÓN.

    archivo adjunto

  5. Escriba el nombre de la aplicación (en este ejemplo es * App Builder DocuSign*)

  6. 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
  7. Haga clic en el botón + AGREGAR CLAVE SECRETA debajo de Autenticación y copie este valor, necesita esta clave y no podrá ver la clave completa más tarde.

  8. 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 usa otra herramienta de desarrollo de API, consulte su documentación)

  9. Haga clic en Guardar

  10. Haga clic en Plantillas en el menú de la barra superior.

  11. 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.

  12. Nombre su modelo y cargue un documento, haga clic en Siguiente; opcionalmente, agregue áreas de firma al documento, luego haga clic en Guardar.

  13. 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 usando cartero

  1. Cree una nueva solicitud POST con los siguientes parámetros:

    • URL: https://account-d.docusign.com/oauth/token >/

    • Autorización: Autorizació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

  2. 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
    
  3. Después de pulsar Intro con la URL anterior, copie el contenido del campo URL y péguelo en un lugar visible (es muy largo). Copie el valor después de code= y antes de &state= (este es su valor de code), péguelo en el valor del paso URL de esta sección y haga clic en Enviar en Postman. **Este paso debe realizarse rápidamente, ya que el token de actualización del navegador web solo tarda unos 2 minutos. **

    archivo adjunto

Configurar la API del token de actualización en App Builder

  1. Desde el menú Conectar, haga clic en el enlace Conectarse a su empresa

  2. Haga clic en Servidores de datos en el lado izquierdo y haga clic en Crear

  3. 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

    adjunto

  4. Haga clic en Guardar.

Agregar un extremo de API

  1. 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.

  2. En el panel Extremos en la parte inferior izquierda, haga clic en Crear

  3. Agregue los siguientes detalles:

    • Nombre: Nombra tu extremo

    • Extremo: /oauth/token

    • Método: POST

  4. 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 del cartero}

Este valor se encuentra en la pestaña Encabezados de Postman, después de la llamada POST para recuperar el token de actualización. Indicará básico seguido de un ID largo. (Quizás deba 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

![archivo adjunto](/_download/images/vinyl/pdf/30/media/image5.jpeg){ style="width:6.42746in;height:3.56341in" }
  1. Haga clic en Guardar

  2. Haga clic en Probar conexión para obtener el token de acceso para el siguiente paso

  3. Añada los parámetros de consulta a la entrada de ejemplo como se indica a continuación:

    { "grant_type": "refresh_token", "refresh_token": "<refresh token from postman>"}
    
  4. Haga clic en Importar

Configurar App Builder para DocuSign

  1. Desde el menú Conectar, haga clic en el enlace Conectarse a su empresa

  2. Haga clic en Servidores de datos en el lado izquierdo y haga clic en Crear

  3. 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

    archivo adjunto

Agregar un extremo de API para la modelo de DocuSign

  1. 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.

  2. En el panel Extremos en la parte inferior izquierda, haga clic en Crear

  3. Agregue los siguientes detalles:

    • Nombre: Nombra tu extremo

    • Extremo: /v2/accounts/<AccountID>/envelopes

    • Método: POST

  4. 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 firma".

      • Tipo: Consulta

      • Dirección: Entrada

    • Parámetro 4

      • Nombre: Asunto del correo electrónico

      • 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

  5. 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.

  6. 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

  1. En el panel Extremos en la parte inferior izquierda, haga clic en Crear

  2. Agregue los siguientes detalles:

    • Nombre: Nombra tu extremo

    • Extremo: /v2/accounts/<AccountID>/envelopes/<EnvelopeID>

    • Método: GET

  3. 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

  4. 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

  1. Desde el IDE de App Builder, haga clic en Crear su aplicación

  2. Haga clic en Capa de almacenamiento de datos y, en Servicios web, busque la API Rest de DocuSign que creó en el paso anterior.

  3. Haga clic en el icono de engranaje Tablas

  4. Para cada tabla, haga doble clic en la tabla y haga clic en Configuración de casos extremos

  5. En Acceso público, haga clic en Permitir lectura y Permitir escritura

  6. 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 las reglas de App Builder para DocuSign

Agregar columnas para la información de DocuSign

  1. Desde el IDE de App Builder, haga clic en Crear su aplicación

  2. Haga clic en Capa de lógica empresarial y busque la fuente de datos en la que desea almacenar la información de DocuSign

  3. 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*

  4. 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).

  5. 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))

  6. 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

  7. 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 de XP para insertar credenciales en el token después de la llamada

  1. Desde el paso anterior, vuelva al App Workbench.

  2. En el panel central, haga clic en Agregar una regla de negocio para crear un nuevo objeto de negocio.

  3. Complete los siguientes datos:

    • Nombre: Tabla (Insertar token de acceso de actualización)

    • Propósito: XP CRUD

    • Desmarque "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)

    Interfaz gráfica de usuario, descripción de la aplicación generada automáticamente

  4. En el panel Tablas, haga clic en +Tablas y agregue la tabla de la fuente de datos donde se almacena la información de DocuSign. En este caso, ParamDocusign.

  5. 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.

    archivo adjunto

Crear una regla de actualización de XP para actualizar el token de acceso

  1. Desde el paso anterior, vuelva al App Workbench.

  2. En el panel central, haga clic en Agregar una regla de negocio para crear un nuevo objeto de negocio.

  3. Complete los siguientes datos:

    • Nombre: Tabla (Actualizar token de acceso)

    • Propósito: XP CRUD

    • Desmarque "Omitir capa empresarial"

    • Acción: Actualizar

    • Fecha de origen Fuente: La primera API REST que creó para actualizar el token de acceso

    • Fuente 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

    archivo adjunto

  4. 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).

  5. Haga clic en Todos para agregar todas las columnas de la tabla

  6. Busque la columna llamada access_token y oriéntela a la columna DocusignClientIDSecretID que creó en la tabla.

  7. Agregue ID de cuenta API a ParamDocusign como una columna e ingrese su valor

  8. Agregue ID de cuenta API como parámetro en el Extremo del token de actualización e ingrese su valor

  9. En la regla de actualización, configure el ID de cuenta de API del token de actualización como destino del ID de cuenta de ParamDocuSign en la vinculación de tipos y configúrelo como PK. Esto tiene la ventaja adicional de que, si decide agregar más cuentas de DocuSign a la aplicación, esto facilitará la configuración.

    archivo adjunto

Crear un cronograma para ejecutar el evento de actualización del token de acceso

  1. Dado que el token de acceso caduca y debe actualizarse periódicamente, agregue esta regla a un evento y cree una programación.

  2. Cree el evento navegando a la capa de lógica de negocio 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 como "Lanzar mediante programación con simultaneidad máxima: 1".

    Interfaz gráfica de usuario, descripción de la aplicación generada automáticamente

  3. En Acciones, haga clic en Registrar existente y agregue la regla CRUD creada anteriormente: Tabla (Actualizar token de acceso de actualización).

  4. A continuación, dirígete a App Builder Monitor (en la esquina inferior izquierda)  Programaciones. Asigna un nombre a tu programación y selecciona la aplicación donde se creará el evento que creaste para la regla. Deja la frecuencia en "Ejecución periódica de la programación". En "Información de programación", define la frecuencia de ejecución de la programación; se recomiendan 4 horas.

    archivo adjunto

    adjunto

Ahora que actualiza su token de acceso de forma programada, puede mantener la 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 tener costos, como devolver un archivo mediante un webhook. Otra opción es usar el complemento HTTP retriever

Promoción de la aplicación a la producción de DocuSign

Cuando los extremos y las reglas CRUD que ha creado funcionen correctamente, estará listo para promocionar esta aplicación a DocuSign Production. Para ello, deberá revisar la API en DocuSign. Para aprobar la revisión, debe realizar 20 llamadas a la API correctamente en un solo día.

  1. 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

  2. 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.

  3. Un administrador de DocuSign revisará y autenticará manualmente la solicitud; esto puede demorar hasta 3 días hábiles.

  4. Tras la autenticación de Go-Live, se deberán repetir los pasos anteriores con las credenciales de DocuSign de producción. La clave de integración no se modificará, pero las demás credenciales serán diferentes y deberán actualizarse en Postman y App Builder.

  5. Cambios en 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 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