Ejemplos rápidos de integración

Nota: Todas las referencias a ficheros o documentos codificados con Base64 se muestran truncadas para facilitar la lectura de esta documentación.

Autenticación de usuario, operaciones de consulta

La aplicación tercera "SAMPLE APP" quiere autenticar a un usuario para consultar los datos del usuario, cuyo código es sample_user.

Requisitos previos:

  • La aplicación debe estar dada de alta como sistema cliente en Viafirma Fortress
  • Se le debe haber provisto de un client_id. En este ejemplo será sample_app
  • Se le debe haber provisto de un client_secret. En este ejemplo será 12345
  • Se le debe haber configurado una URL de retorno permitida: http://www.example.com/auth

En el momento en que la aplicación "SAMPLE APP" quiera realizar la autenticación del usuario contra Viafirma Fortress, lo redireccionará a una URL:

{viafirma_fortress_url}/oauth2/v1/auth?
scope=profile&
state=&
redirect_uri=http://www.example.com/auth&
response_type=code&
client_id=sample_app&
user_code=sample_user

En esta URL se le presentarán al usuario los distintos factores de autenticación de Viafirma Fortress en los que esté enrolado. Utilizará alguno de ellos para autenticarse y autorizar la operación. Una vez finalizado el proceso, Viafirma Fortress devolverá el control a la aplicación "SAMPLE APP", redirigiendo a la URL de retorno: http://www.example.com/auth?state=&code=e2470412-33cc-467a-b357-880fe621920f

A esta URL se le enviará como parámetro de URL el valor del código de autorización, con el cual podrá solicitar un token de acceso con el que operar (p. ej. obtener información sobre el estado del usuario).

Para obtener ese token de acceso, la aplicación "SAMPLE APP" realizará una petición a Viafirma Fortress:

  • Método: POST
  • URL: https://fortress.viafirma.com/fortress/oauth2/v1/token
  • Parámetros:
    • code: Cuyo valor es el código de autorización obtenido previamente: "e2470412-33cc-467a-b357-880fe621920f"
    • client_id: Cuyo valor es el determinado en Viafirma Fortress para la aplicación "SAMPLE APP": "sample_app"
    • client_secret: Cuyo valor es el determinado en Viafirma Fortress para la aplicación "SAMPLE APP": "12345"
    • redirect_uri: Cuyo valor es la URL de retorno para la que se hizo la petición de autorización: "http://www.example.com/auth"
    • grant_type: Este valor es fijo: "authorization_code"

El resultado de esta petición POST será:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer"
}

Una vez obtenidos estos valores, podemos considerar que el usuario ha sido autenticado correctamente. Podremos, además, usar el valor de access_token para realizar operaciones de consulta sobre la API de Viafirma Fortress (p. ej. obtener el estado del usuario, los certificados de un usuario "scope=CERTIFICATES"o el detalle de un certificado "scope=CERTIFICATE").

Firma de un documento PDF

La aplicación tercera "SAMPLE APP" quiere que el usuario sample_user firme un documento PDF.

Requisitos previos:

  • La aplicación debe estar dada de alta como sistema cliente en Viafirma Fortress
  • Se le debe haber provisto de un client_id. En este ejemplo será sample_app
  • Se le debe haber provisto de un client_secret. En este ejemplo será 12345
  • Se le debe haber configurado una URL de retorno permitida: http://www.example.com/sign

Obtención token de cliente

En el momento en que la aplicación "SAMPLE APP" quiera comenzar la operación de firma del documento PDF, deberá obtener un token de sistema cliente.

Para obtener ese token de acceso, la aplicación "SAMPLE APP" realizará una petición a Viafirma Fortress:

  • Método: POST
  • URL: https://fortress.viafirma.com/fortress/oauth2/v1/token
  • Parámetros:
    • client_id: Cuyo valor es el determinado en Viafirma Fortress para la aplicación "SAMPLE APP": "sample_app"
    • client_secret: Cuyo valor es el determinado en Viafirma Fortress para la aplicación "SAMPLE APP": "12345"
    • redirect_uri: Cuyo valor es la URL de retorno para la que se hizo la petición de autorización: "http://www.example.com/auth/response"
    • grant_type: Este valor es fijo: "client_credentials"
https://fortress.viafirma.com/fortress/oauth2/v1/token?
grant_type=client_credentials&
redirect_uri=http://www.example.com/auth/response&
client_id=sample_app&
client_secret=12345

El resultado de esta petición POST será:

{
  "access_token": "666b3b58ecb54db784e2eafdfc66e113",
  "expires_in": 3920,
  "token_type": "Bearer"
}

Solicitud de Firma

Con el access_token resultante de la llamada, el sistema cliente llamará al método signature:

Método: POST
URL: https://fortress.viafirma.com/fortress/api/v1/signature
Header de la petición: Authorization: Bearer 666b3b58ecb54db784e2eafdfc66e113

{
  "userCode": "abcde",
  "redirectUri": "http://localhost:8080/fortress-demo/sign",
  "signatureConfigurations": [
    {
      "signatureType": "PADES_LTA",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "tsa": {
        "type": "URL",
        "url": "https://testservices.viafirma.com/via-tsa/tsa"
      },
      "document": {
        "name": "example.pdf",
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd0aC..."
      },
      "padesConfiguration": {
        "stamper": {
          "csvPath": "http://localhost:7080/fortress/v#",
          "logoB64": "iVBORw0KGgoAAAANSUhEUgA...",
          "page": 1,
          "type": "QR_BARCODE128",
          "xAxis": 80,
          "yAxis": 700
        }
      }
    }
  ]
}

En el cuerpo del método el sistema debe incluir un json con el siguiente formato:

  • userCode: código de usuario
  • redirectUri: Uri donde debe redirigir la operación una vez finalizada
  • signatureConfigurations: por cada documento a firmar, se deberá indicar el documento, el tipo de firma y las políticas de firma.

El resultado de esta petición POST será:

{
  "authCode": "d8e3d98dc20e46188fd067df28048934",
  "exeCode": "cae2c9fe4f4b41888d42ac18a88096a2"
}

Autorización de la solicitud de firma

En el momento en que la aplicación "SAMPLE APP" quiera comenzar la operación de firma del documento PDF, redireccionará al usuario a una URL para que autorice la operación de firma y seleccione el certificado a emplear:

https://sandbox.viafirma.com/fortress/oauth2/v1/auth?signature_code=7b3e77ad2aef4e479c2ae39f497cfe0c&scope=signature&client_id=fortress-dem&redirect_uri=https%3A%2F%2Fsandbox.viafirma.com%2fortress-demo%2Fsign%2Fresponse

En esta URL se le presentarán al usuario los distintos factores de autenticación de Viafirma Fortress en los que esté enrolado. Utilizará alguno de ellos para autenticarse y autorizar la operación de firma. Una vez autenticado, se le mostrarán los distintos certificados que Viafirma Fortress esté custodiando para este usuario, para que seleccione con cuál quiere realizar la firma.

Ejecutar Firma

Una vez obtenidos estos valores, podemos considerar que el usuario ha sido autenticado correctamente y ha autorizado la operación de firma, con lo que se podrá llamar al servicio de firma. Para ello, se realiza una petición a Viafirma Fortress, incluyendo el token de acceso y el identificador de certificado obtenidos en el paso anterior:

  • Método HTTP: POST
  • URL: https://fortress.viafirma.com/fortress/api/v1/signature/cae2c9fe4f4b41888d42ac18a88096a2/execute Header de la petición: Authorization: Bearer 666b3b58ecb54db784e2eafdfc66e113

La respuesta de este servicio será:

{
  "documentB64": "LjMKJcTl8u...",
  "mimeType": "application/pdf",
  "signatureCode": "TFOR-TRES-SOAK-OF1O-TXFR-5151-8007-9109-77"
}

En el atributo documentB64 tendremos el documento firmado (codificado en Base64), y en signatureCode el identificador de firma.

Extensión de Firma

Con el access_token resultante de la llamada, el sistema cliente llamará al método extend:

Método: POST
URL: https://fortress.viafirma.com/fortress/api/v1/signature/extend
Header de la petición: Authorization: Bearer 666b3b58ecb54db784e2eafdfc66e113

{
  "userCode": "abcde",
  "redirectUri": "http://localhost:8080/fortress-demo/extend",
  "extendSignatureConfigurations": [
    {
      "signatureType": "PADES_LTA",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "tsa": {
        "type": "URL",
        "url": "https://testservices.viafirma.com/via-tsa/tsa"
      },
      "document": {
        "name": "example.pdf",
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd0aC..."
      },
      "padesConfiguration": {
        "stamper": {
          "csvPath": "http://localhost:7080/fortress/v#",
          "logoB64": "iVBORw0KGgoAAAANSUhEUgA...",
          "page": 1,
          "type": "QR_BARCODE128",
          "xAxis": 80,
          "yAxis": 700
        }
      }
    }
  ]
}

En el cuerpo del método el sistema debe incluir un json con el siguiente formato:

  • userCode: código de usuario
  • redirectUri: Uri donde debe redirigir la operación una vez finalizada
  • extendSignatureConfigurations: por cada documento a firmar, se deberá indicar el documento, el tipo de firma y las políticas de firma.

El resultado de esta petición POST será:

{
  "ref": "d8e3d98dc20e46188fd067df28048934",
  "bytesB64": "MIMBKM8GCSqGSIb3DQEHAqCDASi/MIMBKLoCAQUxDzANBglghkgBZQMEAgEFADCC1QsGCSqGSIb3DQEHAaCC1PwEgtT4JVBERi0xLjMKJcTl8uXrp..."
}

results matching ""

    No results matching ""