Viafirma Documents

Integración de aplicaciones

Viafirma Documents ofrece una capa de servicio REST FULL segurizados con OAuth 1.0 que permite la integracion con soluciones de terceras dadas de alta en el sistema.

Los servicios REST están documentados haciendo uso del proyecto http://swagger.io en su versión 1.2 con lo que una vez logado en el backend si accede a la url https://ci.viafirma.com/documents/api-docs/ indicando el api_key public-key puede acceder a la documentación de los servicios rest que necesitará para la integración de su aplicación con la solución Viafirma Documents como puede ver en la siguiente imagen

Swagger image

SDK Java

Para facilitar la integración de aplicaciones terceras desarrolladas en Java y haciendo uso del proyecto swagger hemos generado un cliente Java que pretende facilitar la integración puede acceder a su repositorio de GitHub https://github.com/viavansi/documents-sdk-java que contiene el cliente para acceder a los servicios REST y JUnit (test unitarios) que ayuden a probar la integración, de igual forma puede acceder a la documentación del mismo desde el siguiente enlace http://doc.viafirma.com/documents-sdk-java

Callback de respuesta a la aplicación tercera

Cuando solicita una petición a viafirma documents via api puede indicar la url de un servio donde recibir la respuesta asíncrona de la petición cuando esta finalize.

En el proyecto https://github.com/viavansi/ms-callback puede consultar una implementación de ejemplo de un servlet en el que recibir la notificaciones de las solicitudes finalizadas.

Acceso al API Rest con OAuth 1.0

Los servicios REST expuestos por viafirma documents están segurizados con OAuth. Para más información se puede consultar la Documentación oficial de OAuth 1.0.

Desde la administración de aplicaciones del backend, podremos configurar la seguridad de acceso al API dos formas:

  • OAuth a nivel de aplicación
  • OAuth a nivel de usuario

Main image

OAuth 1.0 a nivel de aplicación

Solo es necesario conocer las credenciales de acceso de la aplicación y en las peticiones solo se registra la información de la aplicación solicitante.

Se deben de informar los parámetros Consumer Key y Consumer Secret de OAuth, que serán informados en el header de la petición, tal y como se describe a continuación:

OAuth realm="http://dev.viafirma.com/documents/api/v1/messages",
oauth_consumer_key="com.viafirma.mobile.services.crm",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1422479283",
oauth_nonce="kUBrJA",
oauth_version="1.0",
oauth_signature="zVPxPedplikqrNI0Tmq3GPzMzL0%3D"

En las siguientes capturas podemos ver un ejemplo de acceso al API Rest con el cliente Postman:

OAuth 1

OAuth 2

OAuth 1.0 a nivel de usuario

En este caso es necesario conocer las credenciales de acceso de la aplicación y los datos de acceso de un usuario válido en el sistema, en las peticiones solo se registra la información de la aplicación solicitante y del usuario solicitante.

Se deben informar los parámetros Consumer Key, Consumer Secret, Token y Token Secret de OAuth.

Como resultado, en la cabecera de la petición http debemos informar el parámetro Authorization en el Header de la petición:

OAuth realm="http://dev.viafirma.com/documents/api/v1/oauth/accessToken",
oauth_consumer_key="com.viafirma.mobile.services.demo",
oauth_token="48a0bad01f064a69a19d310c5d71c3b6",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1423584275",
oauth_nonce="dN876B",
oauth_version="1.0",
oauth_signature="8pI9Lg7qVuYO0IoEpCV%2BmX5qqJM%3D"

En las siguientes capturas podemos ver un ejemplo de acceso al API REST con el cliente Postman:

En primer lugar necesitamos pedir un token de acceso haciendo uso de las credenciales de acceso a nuestra aplicación:

OAuth 4

OAuth 5

Tras obtener y aceptar el token, copletamos la petición con los datos del usuario:

OAuth 6

OAuth 7

Tras esto, podremos usar el token durante un periodo de tiempo predefinido en el backend, por ejemplo, 30 min. Transcurrido este tiempo, el token caducará y tendremos que solicitar uno nuevo.

OAuth 8

OAuth 9

Ejemplo de token caducado

OAuth 10

Ejemplos de acceso a los servicios REST desde Postman

Recuperar un mensajes procesado
GET a http://dev.viafirma.com/documents/api/v1/documents/DRAFTED/1422479367884R127/1422479367884R127D140

Send message

Construye PDF a partir de datos de mensaje

En la pestaña de OAuth de postman tenemos que indicar los valores correctos en los campos 'Consumer Key' y 'Consumer Secret' tal cual podemos ver en la siguiente captura

Configure Oauth

Realizar una petición:

POST http://dev.viafirma.com/documents/api/v1/messages

Send message

Enviando el siguiente json IMPORTANTE el código del workflow tiene que ser EX005

{
  "version" : "00001",
  "workflow" : {
    "code" : "EX005",
    "history" : [ ]
  },
  "notification" : {
    "text" : "Generar pdf",
    "detail" : "Ejemplo que solo genera un pdf y ejecuta el callback según lo tenga configurado"
  },
  "document" : {
    "templateCode" : "022_example",
    "templateType" : "docx",
    "items" : [ {
      "key" : "KEY_01",
      "type" : "text",
      "label" : "KEY_01"
    }, {
      "key" : "KEY_02",
      "type" : "text",
      "label" : "KEY_02"
    }, {
      "key" : "KEY_03",
      "type" : "text",
      "label" : "KEY_03"
    }, {
      "key" : "KEY_04",
      "type" : "text",
      "label" : "KEY_04"
    } ]
  }
}