En este artículo explicaremos los 5 puntos básicos de una integración API que recomendamos que tengas en cuenta en tu desarrollo.
Si todavía no has seguido los pasos para empezar con la integración API, hazlo aquí.
Recomendamos que consultes el apartado de nuestro centro de ayuda dedicado a la integración API para encontrar más información.
1. Integración API: Creación de firma
Los parámetros más importantes a utilizar para realizar una petición de firma serían:
recipients: lista de destinatarios (firmante, validador, cc)
delivery_type: si no se indica, va a ser por defecto por email
files (documentos PDF en formato binario) o templates (plantillas Signaturit)
widgets: parámetros de los widgets
type: firma simple o avanzada
Otros parámetros que se suelen usar en esta llamada:
Word Anchor: permite fijar un widget en relación a una palabra que haya en el documento. Por ejemplo, se usa para fijar el widget de firma cuando en el documento aparece la palabra “Firmar”. Este parámetro es el que recomendamos usar cuando se envían a firmar documentos dinámicos.
Si la palabra en cuestión se usa varias veces en el documento, aparecerá un campo de firma para cada palabra.
Parámetro data: se usa para introducir valores en un campo de formulario. Estos campos se pueden crear desde el apartado Plantillas del dashboard de Signaturit, o se pueden introducir en el PDF con un programa de edición.
De esta forma, en cuanto el ID del campo corresponda con un campo del PDF, este valor se estampará directamente en el documento.
Te recomendamos este artículo de nuestro centro de ayuda para poder entender mejor el funcionamiento.
Reminders: son recordatorios que se envían a los firmantes. Se tiene que indicar cada cuánto se quiere enviar un recordatorio automático al firmante en caso que no haya firmado el documento.
Si se trata de un documento con múltiples firmantes, siempre se va a enviar el recordatorio a quién no haya firmado todavía.
Un recordatorio siempre se va a enviar por el mismo delivery_type del envío, siempre que sea por email o SMS.
2. Integración API: Branding
Mediante el banding podéis personalizar ciertos aspectos de la comunicación, como son las plantillas de los correos enviados a los firmantes o los colores.
Se pueden crear los brandings que deseéis, cada uno con sus características (p.e se puede crear un branding por idioma). Cada vez que creéis un branding, obtendréis un branding ID que se tendrá que indicar en las llamadas de Create Signature. El branding que va a aparecer por defecto si no se indica branding_id es el último creado.
Las principales plantillas de correo electrónico enviadas a los firmantes que se pueden customizar completamente mediante HTML son:
'signatures_request' → petición de firma
'signatures_receipt' → firma completada, copia del documento firmado
'pending_sign' → recordatorio firma
'document_canceled' → cancelación de firma
Puedes leer más sobre branding aquí.
3. Integración API: Suscripciones
Subscriptions permite suscribirse a eventos específicos y así recibir alertas en tiempo real sobre los procesos de firma. Se trata de una llamada concreta en la que indicáis la URL en la que queréis recibir eventos y a los eventos a los que os queréis suscribir.
Los eventos a los que recomendamos suscribirse son los siguientes:
'email_bounced'
'email_deferred'
'document_completed'
'document_declined'
'document_canceled'
'audit_trail_completed'
4. Integración API: Descarga del documento firmado
El documento firmado se puede descargar del sistema de Signaturit y cargar en vuestro sistema CRM, ERP o Gestor documental. Este documento estará disponible cuando se reciba el evento de “document_completed”.
También os podéis descargar el documento probatorio con esta llamada.
5. Integración API: Paso a producción
Finalmente, una vez la integración esté completa, pasaréis a producción siguiendo estas instrucciones.
Para ello, únicamente se deberá cambiar el token de Sandbox por el de producción y la URL endpoint.