Introducción
El servicio web permite realizar la firma en el servidor con certificados digitales de documentos PDF añadiendo diferentes capas de seguridad al documento de forma que:
- La firma electrónica protege la integridad del documento. Garantiza que no se haya modificado desde que se firmó.
- Permite firmar con los datos biométricos del firmante garantizando su la identidad del firmante.
- Al firmar con un certificado asegura el origen de la firma.
- Adicionalmente, suma un sello de tiempo avalando el momento exacto de la firma electrónica.
Acceso
- endpoint: https://ws.firmar.online/ef30/ecoSignatureWS.asmx
- wsdl: https://ws.firmar.online/ef30/ecoSignatureWS.asmx?wsdl
Autenticación y acceso a los servicios de firma
En la cabecera de las peticiones se debe informar el token de acceso a los servicios de firma.
<AuthToken xmlns="http://www.edatalia.com/"> <Token>token de acceso</Token></AuthToken>
Método 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>
Método 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í.
Método 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. Si es un número fuera de España, debe añadirse el prefijo internacional junto con el signo +. Por ejemplo +33nnnnnnnnnn para enviar a un número móvil francés.</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>
Método SignBioOTC
<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> <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 si 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>
Método SignOTC
El método SignOTC permite la firma con certificado de un solo uso OTC (One-Time Certificate). Previamente a este método, se ha tenido que enviar un SMS al firmante mediante el método GenerateOTC. El valor del OTC recibido por el firmante se informará en el nodo otp.
- Se genera un certificado OTC, a nombre del firmante, con el que se firma electrónicamente para proteger la integridad del documento.
- 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. Debe ser el mismo valor con el que se generó el código OTP con el método generateOTP</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 inicio 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:
<SignOTCResponse> <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>
Método 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>