Firma Web

Última revisión: 31 Octubre 2019

Se parte del caso de uso siguiente:

  • Origen de la solicitud. Aplicación web integrada con el API Viafirma.
  • Origen del PDF. Generado por Viafirma a partir de plantilla.
  • Destino. Firma a distancia, a través de una notificación remitida al firmante mediante un email, SMS o ambos, y donde se le invita a acceder a una página web para proceder a la firma.
Descripción
SERVICIO MESSAGE
URL /api/v3/messages/
SEGURIDAD
METHOD POST
CONTENT/APPLICATION JSON
{
"groupCode" : "string",
"workflow" : {
"type" : "WEB"
},
"notification" : {
"text" : "string",
"detail" : "string",
"sharedLink" : {
"appCode" : "string",
"email" : "string",
"phone" : "string",
"subject" : "string"
}
},
"document" : {
"templateCode" : “string”,
"readRequired" :
"true|false",
"watermarkText" : "string",
"formRequired" : "true|fasle"
},
"callbackMails" : "string",
"callbackURL" : "string"
}
PARAMS groupCode: código del grupo autorizado; el API debe tener permisos sobre el grupo indicado, y en caso de indicar un código de plantilla o de política, estas deben estar autorizados al grupo.
workflow.type: WEB para firmas remotas, en la que el sistema notifica al destinatario o destinatarios mediante EMAIL y/o SMS. Indicado para su uso con el módulo de firma web. APP para enviar documento mediante notificación push a un dispositivo iOS o Android donde previamente se haya instalado la app de Viafirma. PRESENTIAL pensado para integradores que deseen embeber la página de firma web en sus aplicaciones, obteniendo como resultado un atributo LINK que será el que deban presentar a su usuario, embebiéndolo en una web-view, pop-up, i-frame o similar.
notification.text: (OPCIONAL) título de la notificación enviada a la app; también se usa para el título (1a línea) de la tarjeta mostrada en la bandeja de entrada. Si no se informa se usará por defecto el título configurado en la plantilla utilizada.
notification.detail: (OPCIONAL) descripción de la notificación enviada a la app; también se usa para la descripción (2a línea) de la tarjeta mostrada en la bandeja de entrada. Si no se informa se usará por defecto la descripción configurada en la plantilla utilizada.
notificacion.sharedLink.appCode: (OPCIONAL) si defines un código de app móvil habilitarás en la página de firma un enlace a la app para que el usuario proceda a la firma desde la app, la cual podrá descargar en ese mismo momento o simplemente usarla si ya la tiene. Ten en cuenta que si hace uso de esta opción, el diseño (CSS) de la página de firma tiene que contemplar esta opción; podrías tener unas hojas de estilo (CSS) donde el contenedor (div) que muestra los enlaces a la app esté oculto.
notificacion.sharedLink.email: solo en caso de que optes por una notificación MAIL o MAIL_SMS, aquí es donde informarás el email del destinatario.
notificacion.sharedLink.phone: solo en caso de que optes por una notificación SMS o MAIL_SMS, aquí es donde informarás el número de teléfono móvil del destinatario. Es OBLIGATORIO usar el identificador de país en formato +99, por ejemplo, para España usar +34 delante del número.
notificacion.sharedLink.subject: (OPCIONAL) aquí puedes definir el asunto del correo. Si no lo indicas se usará por defecto el que hayas configurado en tu plantilla, y si en tu plantilla no lo has configurado, se usará por defecto el asunto configurado a nivel global.
document.templateCode: identificador de la plantilla gestionada por Viafirma. Una plantilla incluye documento, políticas, notificaciones, etc. Consulta las opciones de gestión de plantillas para conocer más posibilidades de uso.
document.readRequired: (OPCIONAL) se usa para forzar al avance de todas las páginas que tuviera el documento. Una vez realizado se Uso del API Página 13 de 46 habilita el panel de políticas que permite continuar con el proceso de firma. Si no se indica este param su valor por defecto es false.
Document.formRequired: (OPCIONAL) valores permitidos true y false, y si se habilita, muestra en la pantalla de firma el formulario previamente diseñado y asociado a la plantilla.
document.watermarkText: (OPCIONAL) se usa para pintar una marca de agua, en diagonal, sobre el visor del documento que se se desea firmar. Si no se indica este param su valor por defecto es “Preview”.
callbackMails: (OPCIONAL) se usa para informar mediante correo electrónico al finalizar el proceso. Se pueden usar varias direcciones de correo separadas por coma. El contenido del correo (asunto y cuerpo) se puede configurar en la plantilla (recomendado), y también se puede configurar en el propio servicio (ver objeto Customization en la documentación oficial del producto). Los estados por defecto en los que se notifica por email son SUCCESS, EXPIRED, ERROR y REJECTED. Para definir estados distintos sobre los que realizar el callbackMail revisar la configuración avanzada del Grupo afectado.
callbackURL: (OPCIONAL) se usa para informar mediante un POST a la URL indicada al finalizar el proceso. Se pueden usar URLs que estén securizadas con Basic Auth, en cuyo caso habría que usar el param “callbackAuthorization” (más información en https://doc.viafirma.com/documents/api/latest/es/response_callback.html). Este param también se puede configurar en los ajustes de la plantilla.
RESPONSE 200: HTTP status code 200/OK

Response content type: string

Recibirás el messageCode del proceso generado con el que podrás gestionarlo en el resto de servicios.
Respuestas alternativas en caso de fallo: se devolverán HTTP status codes distintos de 200/OK. En ese caso siempre se devolverá un JSON que describe el problema:

    {
      "code": "string",
      "type": "string",
      "message": "string",
      "trace": "string"
    }

POST SAMPLE

    {
      "groupCode": "<here_your_groupCode>",
      "workflow": {
        "type": "WEB"
      },
      "notification": {
        "text": "Nuevo contrato pendiente de firma.",
        "detail": "Núm. Contrato AA9988",
        "sharedLink": {
        "appCode": "com.viafirma.documents",
        "email": "<here_signer_email>",
        "subject": "Viafirma: firma de contrato"
      },
      "document" : {
        "templateCode": "<here_your_templateCode>",
        "readRequired": false,
        "watermarkText": "Preview",
        "formRequired": false
      },
      "callbackMails": "<here_your_email>",     
      "callbackURL": "<here_your_system_callback>"
    }

results matching ""

    No results matching ""