Añadir elementos al lote

Actualizado: 05-sep-2023

Con este método podrás agregar los elementos que serán firmados en el lote. Debes agregar como mínimo un elemento, y no podrás exceder el máximo indicado en la preparación del lote.

Como respuesta obtendrás un identificador temporal del documento, y en caso de no haber podido agregar el elemento al lote obtendrás un código y descripción de error.

Request

  • Método: POST
  • Servicio: /api/rest/services/preparesignature/addOperationFile
  • ContentType: application/JSON
{
    "operationId" : "string",
    "operationFile" : {
        "sourceId" : "string",
        "filename": "string",
        "signaturePolicy": {
            "signatureFormat" : "string",
            "signatureType" : "string"
        },
        "base64Content" : "string"
    }
}

Ejemplo:

{
    "operationId":"{operationId}",
    "operationFile":{
        "sourceId" : "Contract-Number-001",
        "filename":"my_contract_001.pdf",
        "signaturePolicy":{
            "signatureFormat":"PAdES_BASIC",
            "signatureType":"ATTACHED"
        },
        "base64Content":"JVBERi0xLjMKJcT..."

    }
}

Configuración obligatoria

  • operationId: (string) identificador obtenido en la response del servicio preparesignature.
  • operationFile:
    • sourceId:(string) identificador del documento en origen y que permita una fácil identificación por parte del integrador.
    • filename: (string) nombre del documento.
    • base64Content:(string) documento codificado en base64.
    • signaturePolicy:
      • signatureFormat: (string) formato de firma
      • signatureType: (string) tipo de envoltura

Política de Firma

signatureFormat, valores disponibles:

XMLSIG_ENVELOPING,
XADES_EPES_ENVELOPED,
CMS,
PDF_PKCS7,
XADES_T_ENVELOPED,
XADES_XL_ENVELOPED,
XADES_A_ENVELOPED,
CMS_DETACHED,
CMS_ATTACHED,
CAdES_BES,
CAdES_EPES,
CAdES_T,
CAdES_C,
CAdES_XL,
CAdES_A,
PAdES_BASIC,
PAdES_BES,
PAdES_EPES,
PDF_PKCS7_T,
XMLDSIG,
DIGITALIZED_SIGN,
BIOMETRIC_SIGN,
PKCS1_SHA1_RSA,
XADES_BES

signatureType, valores disponibles:

ENVELOPING,ENVELOPED,DETACHED,ATTACHED

Párametros opcionales de la política de firma

Junto a la política de firma puedes agregar params adicionales:

        "parameters":{
                "string":"string"
            }
  • DIGEST_METHOD (string) método de resumen utilizado. El valor por defecto en caso de omitir esta configuración será SHA256. Valores permitidos: SHA1,SHA256,SHA384,SHA512.
  • SIGNATURE_ALGORITHM (string) formato utilizado para la firma. Por defecto SHA256withRSA. Valores permitidos: SHA256withRSA, SHA384withRSA,SHA512withRSA.

Ejemplo:

        "parameters":{
                "DIGITAL_SIGN_PAGE":"1",
                "DIGEST_METHOD":"SHA256",
                "DIGITAL_SIGN_STAMPER_HIDE_STATUS":"true",
                "DIGITAL_SIGN_STAMPER_TYPE":"QR-BAR-H",
                "DIGITAL_SIGN_REASON":"Reason: xxxx",
                "DIGITAL_SIGN_RECTANGLE":"{\"x\":40,\"width\":550,\"y\":10,\"height\":75}",
                "SIGNATURE_ALGORITHM":"SHA256withRSA"
            }

Parámetros opcionales de la política de sellos de firma

Se incluirá dentro de la lista de parámetros permitidos en una política de firma:

  • DIGITAL_SIGN_PAGE: (string) número de la página en la que se imprimirá el stamper de firma. Valores disponibles: 0 para repetirlo en todas las páginas, -1 en la última, o el número de la página deseada.
  • DIGITAL_SIGN_LOCATION:(string) metadato asociado a la localización de la firma. Esta información suele mostrarse en visores avanzados de PDF como Adobe.
  • DIGITAL_SIGN_STAMPER_HIDE_STATUS:(string) activa o desactiva un mensaje de auto validación utilizado en algunos visores avanzados de PDF, como Adobe. Valores permitidos: true,false. Valor por defecto true.
  • DIGITAL_SIGN_STAMPER_TYPE:(string) tipo de stamper. Valores permitidos: QR-BAR-H,PDF417-H.
  • DIGITAL_SIGN_REASON:(string) metadato asociado al motivo de la firma. Esta información suele mostrarse en visores avanzados de PDF como Adobe.
  • DIGITAL_SIGN_CONTACT:(string) metadato asociado a la persona de contacto asociada a la firma. Esta información suele mostrarse en visores avanzados de PDF como Adobe.
  • DIGITAL_SIGN_RECTANGLE: (string) definición del rectángulo sobre el que se imprimirá el stamper de firma. Su configuración requiere ancho, alto y posiciones X,Y a contar desde el punto superior izquierdo del rectángulo. Esta información se debe informar con el siguiente formato: {\"x\":0,\"width\":0,\"y\":0,\"height\":0}", por ejemplo: {\"x\":40,\"width\":550,\"y\":10,\"height\":75}.

Ejemplo uso de sello de firma:

{
    "sessionId": "{{sessionId}}",
    "files": [
        {
        "filename":"{{filenameRandom}}",
        "signaturePolicy":{
            "signatureFormat":"PAdES_BES",
            "signatureType":"ATTACHED",
            "parameters":{
                "DIGITAL_SIGN_PAGE":"1",
                "DIGITAL_SIGN_LOCATION":"Sevilla",
                "DIGITAL_SIGN_STAMPER_HIDE_STATUS":"true",
                "DIGITAL_SIGN_STAMPER_TYPE":"QR-BAR-H",
                "DIGITAL_SIGN_REASON":"Acepto condiciones contrato AAA9992",
                "DIGITAL_SIGN_CONTACT":"John Doe",
                "DIGITAL_SIGN_RECTANGLE":"{\"x\":40,\"width\":550,\"y\":10,\"height\":75}"
            }
        },
        "base64Content":"JVBERi0xLjMK..."
        }
    ]
}

Response

Respuestas 200 OK

{
    "operationId": "string"
}

firma en Viafirma Desktop

A partir del operationId se debe construir la URL para la apertura por protocolo de Viafirma Desktop. Para ello seguiremos el siguiente patrón:

INSTRUCCIONES

copiar la siguiente URL y abrirla en un browser

viafirmawpfclient://?url={url}&operationId={operationId}&isParallel=true

NOTA: el método de procesamiento en paralelo solo está soportado en entornos en los que el sistema de caché utilizado por platform está basado en REDIS. En aquellos otros entornos con el sistema de caché basado en EHCACHE no tomará en cuenta este queryparam aunque sea informado en la apertura por protocolo.

donde:

  • url = corresponde a la URL del servidor de Viafirma Platform, por ejemplo, platform.viafirma.com/viafirma .
  • operationId = identificador obtenido en la response.
  • isParallel = true para activar el procesamiento del lote en paralelo, tanto en DESKTOP como en SERVIDOR.

Respuestas Error

En este conjunto de casos se controlan los casos previstos en los que un elemento no puede ser añadido a un lote.

Se controlan de forma específica los siguientes casos no permitidos:

  • documento corrupto
  • mala configuración del stamper de firma
  • mala configuración del formato de firma
  • número de elementos debe ser igual o menor que el máximo.

Todos los elementos que no se hayan agregado al lote por incumplir algunas de las validaciones realizadas en servidor no computarán sobre el total de elementos del lote.

Las respuestas dadas para estos casos será un Response Code 400 Bad Request, con un JSON en el body con la siguiente estructura.

{
    "documentTemporalId": null,
    "errorCode": "string",
    "errorMessage": "string"
}

Ejemplo:

{
    "documentTemporalId": null,
    "errorCode": "3001",
    "errorMessage": "Signature stamp are incorrectly positioned. Please check page number or rectangle coordinates and try again"
}

{
    "documentTemporalId": null,
    "errorCode": "500",
    "errorMessage": "The element you are trying to add exceeds the total number of elements allowed"
}

{
    "errorCode": "8002",
    "errorMessage": "The document seems to be damaged",
    "documentTemporalId": null
}

{
    "errorCode": "3001",
    "errorMessage": "Unsupported signature format, valid values: XMLSIG_ENVELOPING,XADES_EPES_ENVELOPED,CMS,PDF_PKCS7,XADES_T_ENVELOPED,XADES_XL_ENVELOPED,XADES_A_ENVELOPED,CMS_DETACHED,CMS_ATTACHED,CAdES_BES,CAdES_EPES,CAdES_T,CAdES_C,CAdES_XL,CAdES_A,PAdES_BASIC,PAdES_BES,PAdES_EPES,PDF_PKCS7_T,XMLDSIG,DIGITALIZED_SIGN,BIOMETRIC_SIGN,PKCS1_SHA1_RSA,XADES_BES",
    "documentTemporalId": null
}

results matching ""

    No results matching ""