Firmar con certificado

Introducción

El servicio web permite realizar la firma en el servidor de documentos PDF de forma que añadiendo diferentes capas de seguridad al documento de forma que:

1. La firma electrónica protege la integridad del documento. Garantiza que no se haya modificado desde que se firmó.
2. Permite firmar con los datos biométricos del firmante garantizando su la identidad del firmante.
3. Al firmar con un certificado asegura el origen de la firma.
4. Adicionalmente suma un sello de tiempo avalando el momento exacto de la firma electrónica.

Cabecera de las peticiones

AuthToken: token de autenticación y autorización

<soapenv:Header>
   <edat:AuthToken>
       <edat:token>token de acceso</edat:token>
   </edat:AuthToken>
</soapenv:Header>

 

GenerateOTP

Método que genera un PIN OTP (One-Time Password) y lo envía al teléfono del firmate a través de mediante SMS, de esta forma se garantiza la identidad del firmante.

Los mensajes se envían con nuestro proveedor de SMS, y si desea integrar el suyo contacte con nosotros.

<GenerateOTP xmlns="http://www.edatalia.com/">
  <document>
    <content>documento codificado en base64</content>
  </document>
  <otp>
    <type>Siempre se debe informar el valor sms</type>
    <sms>
      <sessionCode>Identificador de sesión, para relacionar documento y petición.</sessionCode>
      <userId>Identificador de usuario, para relacionar documento y petición</userId>
      <sendTo>Número de teléfono móvil del firmante</sendTo>
      <sendText>Texto que se envía junto con el código OTP, Introduzca el código ##OTP## para validar la firma del documento</sendText>
    </sms>
  </otp>
</GenerateOTP>

Respuesta

<GenerateOTPResponse xmlns="http://www.edatalia.com/">
   <GenerateOTPResult>
      <code>S0 si el envío se ha realizado correctamente, código de error en otro caso</code>
   </GenerateOTPResult>
</GenerateOTPResponse>

 

Sign

Permite firmar con certificado electrónico un documento PDF.

<Sign xmlns="http://www.edatalia.com/">
  <document>
    <type>pdf</type>
    <content>documento codificado en base64</content>
    <password>Opcional, si el documento tiene contraseña se debe informar aquí</password>
  </document>
  <!-- Sobre el widget que se visualiza en el documento con los datos de la firma -->
  <widget>
    <width>ancho</width>
    <height>alto</height>
    <type>float o fixed</type>
    <!-- si type=fixed, el posicionamiento es fijo. Informar esta sección -->
    <fixed>
      <page>Número de página</page>
      <x>Desplazamiento horizontal</x>
      <y>Desplazamiento vertival</y>
    </fixed>
    <!-- fin posicionamiento fijo -->
    <!-- si type=float, el posicionamiento es en base a un texto, informar esta sección --> 
    <float>
      <text>Texto a buscar en el documento</text>
      <gapX>Desplazamiento relativo en horizontal respecto del texto</gapX>
      <gapY>Desplazamiento relativo en vertical respecto del texto</gapY>
    </float>
    <!-- fin posicionamiento es en base a un texto -->
    <customText>Opcional. Texto en base64 para visualizar dentro del widget</customText>
    <jpg>Opcional.imagen de fondo del widget codificado en base64</jpg>
  </widget>
  <!-- OBLIGATORIO INICIO de datos del certificado de firma -->
  <signCert>
    <type>obligatorio p12</type>
    <p12>Certificado codificado en base64</p12>
    <password>Contraseña en base64</password>
  </signCert>
  <!-- FIN de datos del certificado de firma -->
  <!-- OPCIONAL INICIO datos añadir TSA  -->
  <tsp>
    <activate>1 si se activa el sello de tiempo</activate>
    <url>url de acceso a la TSA</url>
    <user>Usuario</user>
    <password>Contraseña</password>
  </tsp>
  <!-- FIN datos añadir TSA  -->
  <!-- OPCIONAL INICIO datos añadir validación OCSP del certificado -->
  <ocsp>
    <activate>1 si se activa el servicio OCSP</activate>
    <url>url de acceso a la OCSP</url>
    <user>usuario de acceso a OCSP</user>
    <password>contraseña</password>
  </ocsp>
  <!-- FIN datos añadir validación OCSP del certificado -->
  <!-- OPCIONAL propiedades de la firma para visualizar con Adobe Reader -->
  <properties>
    <pdf>
      <certify>1 si se desea certificar el documento</certify>
      <author>autor de la firma</author>
      <reason>motivo</reason>
      <contact>datos de contacto</contact>
      <location>dirección</location>
    </pdf>
  </properties>
  <!-- fin propiedades de firma -->
</Sign>

Respuesta:

<SignResponse xmlns="http://www.edatalia.com/">
  <SignResult>
    <code>0 si el proceso ha finalizado correctamente, código de error en otro caso</code>
    <error>Descripción del error</error>
    <documentSigned>Documento firmado codificado en base64</documentSigned>
  </SignResult>
</SignResponse>

 

SignBio

Firma electrónica de documentos con certificado electrónico incorporando datos biométricos del firmante. Los datos biométricos se han obtenido con herramientas externas a la solución.

<SignBio xmlns="http://www.edatalia.com/">
  <document>
    <type>PDF</type>
    <content>Documento PDF codificado en base64</content>
    <password>Opcional. Contraseña del documento si este la tiene</password>
  </document>
  <!-- inicio del bloque de datos biométricos -->
  <bioData>
    <type>siempre hs</type>
    <hs>
      <type>raw o spp</type>
      <raw>
        <content>Datos biométricos obtenidos a través de componentes ecoSignature JWS en plano codificados en base64</content>
        <isEncrypted>1 si están encriptados, 0 en otro caso</isEncrypted>
        <jpg>Grafo de la firma</jpg>
      </raw>
      <spp>
        <header>Datos biométricos obtenidos con Android o HTML5 codificados en base64</header>
        <encBiodata>string</encBiodata>
        <jpg>Grafo de la firma en base64</jpg>
      </spp>
    </hs>
    <encKey>Clave de cifrado en base64</encKey>
  </bioData>
  <!-- fin del bloque de datos biométricos -->
  <!-- bloque con la información sobre el posicionamiento del widget de firma-->
  <widget>
    <width>Obligatorio. Ancho del widget de firma</width>
    <height>Obligatorio. Alto del widget de firma</height>
    <type>fixed o float</type>
    <!-- Opcional, si type=fixed, el posicionamiento del widget es fijo-->
    <fixed>
      <page>Número de página</page>
      <x>Posición horizontal</x>
      <y>Posición vertical</y>
    </fixed>
    <!-- fin posicionamiento fijo -->
    <!-- Opcional. Si type=float, el posicionamiento del widget se realiza en base a un texto del documento informar esta sección-->
    <float>
      <text>Texto a buscar para posicionar el widget</text>
      <gapX>Desplazamiento relativo en horizontal respecto del texto a buscar</gapX>
      <gapY>Desplazamiento relativo en vertical respecto del texto a buscar</gapY>
    </float>
    <!-- fin posicionamiento flotante -->
    <customText>Opcional. Si se desea añadir un texto al widget de firma informar codificado en base64</customText>
  </widget>
  <!-- Opcional, se puede añadir una firma adicional con certificado al documento -->
  <signCert>
    <type>valor p12</type>
    <p12>Certificado codificado en base64</p12>
    <password>Contraseña cifrada en base64</password>
  </signCert>
  <!-- fin firma adicional con certificado -->
  <!-- opcional añadir marca TSP -->
  <tsp>
    <activate>1 si se activa la marca TSP</activate>
    <url>dirección donde está publicada la TSA</url>
    <user>Usuario de la TSA</user>
    <password>Contraseña</password>
  </tsp>
  <!-- fin marca TSP -->
  <!-- Opcional validación OCSP -->
  <ocsp>
    <activate>1 si se activa la validación </activate>
    <url>url de acceso al servicio</url>
    <user>Usuario</user>
    <password>Contraseña</password>
  </ocsp>
  <!-- Opcional propiedades de la firma para visualizar con Adobe Reader -->
  <properties>
    <pdf>
      <certify>1 si se desea certificar el documento</certify>
      <author>Autor de la firma</author>
      <reason>Motivo de la firma</reason>
      <contact>Datos de contacto</contact>
      <location>Dirección de contacto</location>
    </pdf>
  </properties>
  <!-- fin propiedades de la firma -->
</SignBio>

Respuesta:

<SignBioResponse xmlns="http://www.edatalia.com/">
  <SignBioResult>
    <code>0 si el proceso finalizó correctamente, código de error en otro caso</code>
    <error>Descripción del error</error>
    <documentSigned>Documento PDF codificado en base64</documentSigned>
  </SignBioResult>
</SignBioResponse>

Si no tiene una herramienta para capturar los datos biométricos puede explorar las soluciones de firma presencial, aquí.

SignBioOTC

Firma biométrica con certificado de un solo uso OTC (One-Time Certificate). El proceso genera un certificado OTC, a nombre del firmante con el que se firma electrónicamente para proteger la integridad del documento. Incorpora tanto los datos biométricos del firmante para garantizar la identidad del mismo como el sello de tiempo para avalar el momento exacto de la firma electrónica.

<SignBioOTC xmlns="http://www.edatalia.com/">
  <document>
    <type>Siempre con el valor, pdf</type>
    <content>Documento PDF codificado en base64</content>
    <password>Opcional, si el documento tiene contraseña informar aquí</password>
  </document>
  <bioData>
    <type>raw o spp</type>
    <hs>
      <type>raw o spp</type>
      <raw>
        <content>Datos biométricos en plano obtenido con componentes ecoSignature JWS codificados en base64</content>
        <isEncrypted>1 si están encriptados, 0 en otro caso</isEncrypted>
        <jpg>grafo del documento en base64</jpg>
      </raw>
      <spp>
        <header>Datos biométricos en plano obtenido con el componente HTML5 o SDK Android codificados en base64</header>
        <encBiodata>1 si los datos están encriptados</encBiodata>
        <jpg>Grafo de la firma codificado en base64</jpg>
      </spp>
    </hs>
    <encKey>Certificado de cifrado codificado en base64</encKey>
  </bioData>
  <!-- inicio bloque generación certificado OTC -->
  <otc>
    <type>valores: edatalia o fp</type>
    <!-- inicio si type=edatalia, CA = edatalia -->
    <edatalia>
      <commonName>Nombre y Apellidos</commonName>
      <organization>Descripción de la organización</organization>
      <organizationalUnit>Descripción de la unidad</organizationalUnit>
      <email>correo electrónico</email>
      <phone>Teléfono</phone>
      <extra>Información extra</extra>
      <extraHardware>Información extra</extraHardware>
    </edatalia>
    <!-- FIN bloque CA = edatalia --> 
    <!-- inicio si type=fp, CA = Firma Profesional-->
    <fp>
      <name>Nombre del firmante</name>
      <surname>Primer apellido del firmante</surname>
      <surname2>Segundo apellido del firmante</surname2>
      <email>Correo electrónico</email>
      <document>DNI, pasaporte</document>
      <organization>Organización</organization>
      <country>País</country>
    </fp>
    <!-- fin entidad certificadora es Firma Profesional -->
  </otc>
  <!-- fin bloque generación certificado OTC -->
  <!-- inicio bloque propiedades del widget de firma -->
  <widget>
    <width>Ancho</width>
    <height>Alto</height>
    <type>fixed o float</type>
    <!-- Optativo, si el posicionamiento es fijo (type=fixed), informar este bloque -->
    <fixed>
      <page>Número de página</page>
      <x>Posición horizontal</x>
      <y>Posición vertical</y>
    </fixed>
    <!-- fin bloque posicionamiento fijo -->
    <!-- Optativo, si el posicionamiento es relativo (type=float) en base a un texto, informar este bloque -->
    <float>
      <text>Texto a buscar dentro del documento PDF para posicionar la firma</text>
      <gapX>Desplazamiento en horizontal en base al texto buscado</gapX>
      <gapY>Desplazamiento en vertical en base al texto buscado</gapY>
    </float>
    <!-- fin bloque posicionamiento relativo en base a un texto -->
    <customText>Opcional. Si se quiere añadir un texto dentro del widget, informar codificado en base64</customText>
  </widget>
  <!-- fin bloque propiedades del widget de firma-->
  <!-- inicio bloque añadir marca TSP -->
  <tsp>
    <activate>1 s se activa añadir TSP</activate>
    <url>Dirección de acceso al servicio TimeStamp</url>
    <user>Usuario</user>
    <password>Contraseña</password>
  </tsp>
  <!-- fin bloque añadir marca TSP -->
  <!-- Opcional bloque añadir propiedades al documento para visualizar con Adobe Reader -->
  <properties>
    <pdf>
      <certify>Opcional. 1 si se desea certificar el documento</certify>
      <reason>Opcional. Motivo</reason>
      <contact>Opcional. Datos de contacto</contact>
      <location>Opcional. Dirección de contacto</location>
    </pdf>
  </properties>
  <!-- Fin bloque añadir propiedades al documento para visualizar con Adobe Reader -->
</SignBioOTC>

Respuesta:

<SignBioOTCResponse xmlns="http://www.edatalia.com/">
  <SignBioOTCResult>
    <code>0 si el proceso ha finalizado correctamente, código de error en otro caso</code>
    <error>Descripción del error</error>
    <documentSigned>Documento PDF firmado codificado en base64</documentSigned>
  </SignBioOTCResult>
</SignBioOTCResponse>

 

SignOTC

El método SignOTC permite la firma con certificado de un solo uso OTC (One-Time Certificate).

  1. Se genera un certificado OTC, a nombre del firmante, con el que se firma electrónicamente para proteger la integridad del documento.
  2. Recibe un documento firmado y le aplica un resellado. Por defecto, se aplica el sello de tiempo de firmar.online.

 

<SignOTC xmlns="http://www.edatalia.com/">
  <document>
    <type>pdf, valor obligatorio</type>
    <content>Documento PDF codificado en base64</content>
    <password>Opcional, contraseña del documento si este la tiene</password>
  </document>
  <otp>
    <type>valor sms</type>
    <sms>
      <sessionCode>Identificador de sesión asociado al documento, debe coincidir con los dados al método GenerateOTP</sessionCode>
      <userId>Identificador de usuario asociado al documento, debe coincidir con los dados al método GenerateOTP</userId>
      <otpCode>Código OTP (generado para el documento con el método GenerateOTP)</otpCode>
    </sms>
  </otp>
  <!-- inicio bloque de datos para la generación del certificado OTC -->
  <otc>
    <type>edatalia o fp (firma profesional)</type>
    <!-- inicio, si type=edatalia como CA -->
    <edatalia>
      <commonName>Nombre</commonName>
      <organization>Organización</organization>
      <organizationalUnit>Unidad</organizationalUnit>
      <email>Correo electrónico</email>
      <phone>Teléfono</phone>
      <extra>Información extra</extra>
      <extraHardware>Información extra II</extraHardware>
    </edatalia>
    <!-- fin CA = edatalia -->
    <!-- inicio si type=fp, CA Firma Profesional-->
    <fp>
      <name>Nombre</name>
      <surname>Apellido 1</surname>
      <surname2>Apellido 2</surname2>
      <email>Correo electrónico</email>
      <document>DNI, pasaporte...etc</document>
      <organization>Organización</organization>
      <country>País</country>
    </fp>
    <!-- fin si type=fp, CA Firma Profesional--> 
  </otc>
  <!-- fin bloque de datos para la generación del certificado OTC -->
  <!-- inicio bloque propiedades del widget -->
  <widget>
    <width>Ancho</width>
    <height>Alto</height>
    <type>float o fixed</type>
    <!-- Opcional inicio bloque posicionamiento fijo-->
    <fixed>
      <page>Número de página</page>
      <x>Posición horizontal</x>
      <y>Posición vertical</y>
    </fixed>
    <!-- fin bloque posicionamiento fijo-->
    <!-- Opcional incio bloque posicionamiento relativo -->
    <float>
      <text>Texto a buscar dentro del documento pdf</text>
      <gapX>Desplazamiento horizontal relativo al texto buscado</gapX>
      <gapY>Desplazamiento vertical relativo al texto buscado</gapY>
    </float>
    <!-- fin bloque posicionamiento relativo -->
    <customText>Opcional. Texto para añadir al widget codificado en base64</customText>
    <jpg>Opcional. Imagen de fondo en formato jpg para añadir al widget codificado en base64</jpg>
  </widget>
  <!-- fin bloque de datos propiedades del widget -->
  <!-- inicio bloque de datos para añadir una marca timestamp al documento -->
  <tsp>
    <activate>1 si se activa el TSP</activate>
    <url>Url del servicio timestamp</url>
    <user>Usuario</user>
    <password>Contraseña</password>
  </tsp>
  <!-- fin bloque de datos para añadir una marca timestamp al documento -->
  <!-- inicio bloque de datos para propiedades al documento que se visualizan con Adobe Reader -->
 <properties>
    <pdf>
      <certify>Opcional. Valor 1 si se desea certificar el documento</certify>
      <reason>Opcional. Motivo</reason>
      <contact>Opcional. Datos de contacto</contact>
      <location>Opcional. Dirección de contacto</location>
    </pdf>
  </properties>
  <!-- fin bloque de datos para propiedades al documento que se visualizan con Adobe Reader -->
</SignOTC>

Respuesta:

  <SignOTCResult>
    <code>0 si el proceso se ha ejecutado correctamente, código de error en otro caso.</code>
    <error>Descripción del error</error>
    <documentSigned>PDF firmado codificado en base64</documentSigned>
  </SignOTCResult>
</SignOTCResponse>

 

TimeStamp

Añade un sello de tiempo al documento a un documento firmado. Por defecto, se aplica el sello de tiempo de firmar.online.

<TimeStamp xmlns="http://www.edatalia.com/">
  <document>
    <type>pdf, valor obligatorio</type>
    <content>Documento PDF codificado en base64</content>
  </document>
  <tsp>
    <url>Dirección del servicio timeStamp</url>
    <user>Usuario</user>
    <password>Contraseña</password>
  </tsp>
</TimeStamp>

Respuesta:

<TimeStampResponse xmlns="http://www.edatalia.com/">
  <TimeStampResult>
    <code>si el proceso finaliza normalmente devuelve el valor 0, código de error en otro caso</code>
    <error>Descripción del error</error>
    <documentSigned>Documento PDF firmado codificado en base64</documentSigned>
  </TimeStampResult>
</TimeStampResponse>

 

Ejemplo SOAP-UI

Puede descargar un proyecto ejemplo desde aquí