Firma documentos - La excelencia de la firma digital a tu alcance

API Web Services 1.9

Introducción

FirmaDocumentos puede utilizarse como middleware y se puede integrar con otros sistemas mediante el uso de servicios web integrados. Los servicios web responden al estándar REST y la seguridad está garantizada ya que se utilizan siempre sobre protocolo HTTPS y la llamada a los mismos requiere autenticación OAuth 1.0.

Una vez contratado el servicio por parte del cliente, éste recibirá una clave y una contraseña (Consumer Key y Consumer Secret respectivamente en la terminología de la autenticación OAuth 1.0) que le permitirán autenticarse y empezar a utilizar la API.

El cliente dispondrá de un entorno de pruebas en el cual podrá llevar a cabo los trabajos de desarrollo y testing necesarios para la integración de sus sistemas con FirmaDocumentos. Cuando el cliente lo crea oportuno, podrá utilizar el entorno real de la API que ya estará conectado con sus datos reales de FirmaDocumentos. El cliente puede trabajar con ambos entornos con total libertad sin necesidad de solicitar el paso de un entorno a otro.

URL entorno de pruebas: https://apitest.firmadocumentos.es/….

URL entorno real: https://api.firmadocumentos.es/….

Algunos ejemplos de llamadas generadas desde la herramienta Postman:

curl –location –request POST ‘https://apitest.firmadocumentos.es/send/Template?oauth_consumer_key=XXXXXXXXXXXXXXXXXXXXX&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1588868100&oauth_nonce=s8xbzILkavi&oauth _version=1.0&oauth_signature=+NwET4pY2AE+raoBlhHXj9xCDm0%3D’ \
–header ‘Content-Type: text/plain’ \
–data-raw ‘{“NomPlantilla”:”Multifirma”,”Orientacion”:”V”,”CodFormato”:”A4″,”Sello”:””,”AltoFirma”:2.0,”AnchoFirma”:5.0,”AltoSello”:0,”AnchoSello”:0,”Multifirma”:true,”NumeroDestinatarios”:3,”PlantillaPorDefecto”:false,”UbicacionFirmas”:[{“IdDestinatario”:1,”NumPagina”:1,”TipoFirma”:”F”,”X”:0.0,”Y”:0.0,”Texto”:””},{“IdDestinatario”:2,”NumPagina”:1,”TipoFirma”:”F”,”X”:2.0,”Y”:2.0,”Texto”:””},{“IdDestinatario”:3,”NumPagina”:1,”TipoFirma”:”F”,”X”:3.0,”Y”:4.0,”Texto”:””}]}’

curl –location –request POST ‘https://apitest.firmadocumentos.es/send/Sending/95SX602?oauth_consumer_key=XXXXXXXXXXXXXX &oauth_signature_method=HMAC-SHA1&oauth_timestamp=1588788849&oauth_nonce=IQTRf8kOZNo&oauth _version=1.0&oauth_signature=nyy7Q8VKD3oy8qnvUECahOr2ZuQ%3D’ \
–header ‘Content-Type: text/plain’ \
–data-raw ‘{“Operacion”: “L”,”DatoAuxiliar”: “”,”OsName”: “android”,”OSVersion”: “7.0”,”Model”: “samsung SM-JF342″,”Username”: “string”,”DeviceID”: “0.0.0.0”}’

curl –location –request GET ‘https://apitest.firmadocumentos.es/admin/Budget?oauth_consumer_key=XXXXXXXXXXXXXXXXXXXXXX &oauth_signature_method=HMAC-SHA1&oauth_timestamp=1588868844&oauth_nonce=wwrOvS5Q011&oauth _version=1.0&oauth_signature=fz6/m4X77ra0hwSomUeTyPJdrYk%3D’ \
–header ‘Content-Type: text/plain’ \

La Api Web Services de Firma Documentos permite realizar operaciones para un ciclo completo de la generación de los envíos, su firma o rechazo y el seguimiento de los mismos consultado la información completa de cada envío; y también el seguimiento y control del uso de Firma Documentos pudiendo obtener en todo momento los envíos disponibles según el paquete contratado o un desglose de los envíos realizados según su estado.

Nota

Los servicios web indicados en esta documentación se corresponden al conjunto básico que ofrece la API Web Services de Firma Documentos. Esta API, sin embargo, puede ampliarse en implantaciones específicas según los requerimientos del cliente y adaptarse a sus necesidades concretas.

El equipo de soporte y desarrollo de Firma Documentos está a disposición de los clientes para analizar sus necesidades y ayudar a sus propios equipos técnicos en la mejor manera de integrar sus sistemas con la API Web Services de FirmaDocumentos.

* Firma Documentos es una plataforma de software en constante evolución y mejora por lo que la API Web Services de Firma Documentos también puede evolucionar implementando cambios que es posible que no estén reflejados en este documento en un momento determinado.

Historial de Cambios

Fecha	Cambios	Versión
30/07/2020	Se añade el tipo de envío por enlace o link (valor “L” del parámetro TipoEnvio) en el servicio web Sending para la creación de un nuevo envío. Cuando se indica este tipo de envío, la notificación no se envía al o a los destinatarios en ese momento como ocurre con los tipos de envío por SMS o por Email sino que el servicio web devuelve en los datos de identificación del envío una url y el cliente será el encargado de hacer llegar dicha url a los destinatarios con el sistema que mejor se adapte a sus procesos (por ejemplo, usando su propio servidor de correo de manera que el destinatario identifique mejor el origen del envío). El tipo de envío por enlace no se puede utilizar con los envíos multifirma.	1.1
23/09/2020	Se implementa el uso de WebHooks. Los WebHooks permiten a los clientes recibir notificaciones en tiempo real de los eventos que soporta un envío, es decir, firma, rechazo o caducidad. Un WebHook es un endpoint, es decir, una URL, que el cliente habilita en su sistema y que acepta los datos del evento generado. Además, los clientes disponen de nuevas llamadas a la API para configurar los WebHooks y también probarlos.	1.2
08/10/2020	Se añade un nuevo evento para los WebHooks que se genera cuando el destinatario abre el envío, de forma que el cliente puede a través de su WebHook dejar acreditado al 100% que sus destinatarios han recibido el envío.	1.2
25/03/2021	Se añade la propiedad Id en los envíos que permite a los clientes identificar los envíos generados con un valor propio que use internamente en sus sistemas.	1.3
24/02/2022	Se añade la propiedad TipoFirma para que los clientes puedan indicar si el envío puede firmarse con firma digital manuscrita, utilizando un certificado digital o indistintamente.	1.4
20/04/2022	Se añade la propiedad Usuario para indicar que el envío que se realiza lo hace un usuario y no el administrador de la cuenta, o bien, que la plantilla que se actualiza pertenece a un usuario.	1.5
29/04/2022	Se añade la opción de poder crear un envío con tipo de firma simple y la posibilidad de firmar envíos con certificado y con firma simple a través de la API.	1.6
10/05/2022	Se añade la opción de poder crear un envío con tipo de firma OTP.	1.7
21/09/2022	Se añade la opción de poder crear usuarios.	1.8
15/03/2023	Se añade la opción para obtener el documento de trazabilidad de un envío.	1.9

Servicios para el proceso de firma

Son el conjunto de servicios web que se utilizan durante el ciclo de la generación de envíos, la visualización del documento a firmar y finalmente la firma o rechazo del mismo; además de la obtención completa de los datos de un envío, así como la creación de plantillas que son la entidad que permite preconfigurar donde se ubicarán las firmas, si el envío es multifirma, etc.

URL entorno de pruebas: https://apitest.firmadocumentos.es/send/ …

URL entorno real: https://api.firmadocumentos.es/send/ …

/Template

Descripción	Crea o modifica una plantilla a partir de la configuración indicada en el request body.

Tipo	POST

Request Body

{

“NomPlantilla”: “string”,

“Orientacion”: “string”,

“CodFormato”: “string”,

“Sello”: “string”,

“AltoFirma”: 0.0,

“AnchoFirma”: 0.0,

“AltoSello”: 0.0,

“AnchoSello”: 0.0,

“Multifirma”: Boolean,

“NumeroDestinatarios”: 0,

“PlantillaPorDefecto”: Boolean,

“UbicacionFirmas”: [

{

“IdDestinatario”: 0,

“NumPagina”: 0,

“TipoFirma”: “string”,

“X”: 0.0,

“Y”: 0.0,

“Texto”: “string”

}

“Usuario”:”string”

}

Propiedades Request Body

Parámetro	Descripción	Tipo de dato
NomPlantilla	Nombre de la plantilla. Si se indica un nombre de una plantilla que no existe, se creará una nueva. Si se indica un nombre de una plantilla que ya existe, se modificará. La longitud máxima del parámetro es de 40 caracteres. Si se indica un texto más largo quedará recortado a 40 caracteres.	String
Orientacion	Orientación de las páginas en el documento a enviar. Valores posibles: V – Vertical, H – Horizontal	String
CodFormato	Formato de las páginas en el documento a enviar. Valores posibles: A4, A3, A2, A1, A5	String
Sello	Imagen del sello de la empresa si quiere añadirse a los documentos. La imagen se codificará en un string en formato Base64. Se indica una cadena vacía si no se quiere añadir un sello.	String
AltoFirma	Alto de las firmas de los destinatarios en cm.	Single
AnchoFirma	Ancho del sello de la empresa en cm. Indicar 0 si no hay sello.	Single
AltoSello	Alto del sello de la empresa en cm. Indicar 0 si no hay sello.	Single
AnchoSello	Ancho del sello de la empresa en cm. Indicar 0 si no hay sello	Single
Multifirma	True si la plantilla es para envíos multifirma y false si no lo es. Una plantilla multifirma implica que un envío lo tienen que firmar varias personas para que quede completamente firmado el documento.	Boolean
NumeroDestinatarios	Indica el número de personas que tendrán que firmar el documento cuando se trate de un envío multifirma. Máx. 255	Byte
PlantillaPorDefecto	Es una propiedad que sirve más para el uso de FirmaDocumentos desde el entorno web, haciendo que aquella plantilla que sea la plantilla por defecto sea la elegida en primer lugar al hacer un nuevo envío.	Boolean
UbicacionFirmas	Esta propiedad es una lista de entidades cada una de las cuales configura una ubicación de una firma o del sello de la empresa, por lo tanto, puede haber de 1 a N elementos. A continuación, se indica cada una de sus propiedades señalándolas con el prefijo UF.
UF.IdDestinatario	Si la plantilla es multifirma indicaremos el nº de destinatario a quien corresponde la ubicación, si es un envío no multifirma o es una ubicación para el sello de la empresa, el valor será cero.	Byte
UF.NumPagina	Número de página donde se sitúa la firma o sello. Si se indica un cero, la ubicación se refiere a todas las páginas del documento.	Entero 16 bits
UF.TipoFirma	Indica a qué se refiere la ubicación, si a una firma de una persona o al sello de la empresa. Valores posibles: F – Firma, S – Sello	String
UF.X	Coordenada X en cm. La esquina inferior izquierda es la coordenada (0,0)	Single
UF.Y	Coordenada Y en cm. La esquina inferior izquierda es la coordenada (0,0)	Single
UF.Texto	Es posible colocar la firma de manera automática debajo de un determinado texto sin tener que indicar la coordenada concreta. FirmaDocumentos busca el texto en todo el documento (p.ej. “Fdo. Por el Cliente” y coloca la firma debajo del mismo, cuando se indica una ubicación por texto NumPagina, X e Y deben valer cero. La búsqueda tiene en cuenta mayúsculas y minúsculas. La longitud máxima del parámetro es de 100 caracteres. Si se indica un texto más largo quedará recortado a 100 caracteres.	String
Usuario	Indica si la plantilla que se está modificando pertenece a un usuario, para lo que se rellenará con el correo electrónico del usuario. Si no se incluye la propiedad o se deja vacía, la plantilla se asigna al administrador de la cuenta.	String

Ejemplos de Request Body:

Plantilla no multifirma:

{“NomPlantilla”: “Plantilla 1”, “Orientacion”: “V”, “CodFormato”: “A4”, “Sello”: “”, “AltoFirma”: 2.0, “AnchoFirma”: 2.0, “AltoSello”: 0, “AnchoSello” :0, “Multifirma”: false, “NumeroDestinatarios”: 0, “PlantillaPorDefecto”: false, “UbicacionFirmas”: [ { “IdDestinatario”: 0, “NumPagina”: 1, “TipoFirma”: “F”, “X”: 0.0, “Y”: 0.0, “Texto”:””}, {“IdDestinatario”: 0, “NumPagina”: 3, “TipoFirma”: “F”, “X”: 0.0, “Y”: 0.0, “Texto”:””}],”Usuario”:”ejemplo@mail.com”}

Plantilla multifirma:

{“NomPlantilla”:”Multifirma”,”Orientacion”:”V”,”CodFormato”:”A4″,”Sello”:””,”AltoFirma”:2.0,”AnchoFirma”:5.0,”AltoSello”:0,”AnchoSello”:0,”Multifirma”:true,”NumeroDestinatarios”:3,”PlantillaPorDefecto”:false,”UbicacionFirmas”:[{“IdDestinatario”:1,”NumPagina”:1,”TipoFirma”:”F”,”X”:0.0,”Y”:0.0,”Texto”:””},{“IdDestinatario”:2,”NumPagina”:1,”TipoFirma”:”F”,”X”:2.0,”Y”:2.0,”Texto”:””},{“IdDestinatario”:3,”NumPagina”:1,”TipoFirma”:”F”,”X”:3.0,”Y”:4.0,”Texto”:””}],”Usuario”:”ejemplo@mail.com”}

Mensajes de Respuesta

HTTP Status Code	Mensaje
200	Operación correcta
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Sending

Descripción	Inicia el proceso de envío para la firma de un documento creando un nuevo envío (o varios, según se detalla más adelante).

Tipo	POST

Request Body

{

“Asunto”: “string”,

“Emisor”: “string”,

“Id”: “string”,

“Receptores”: “string”,

“TipoEnvio”: “string”,

“TipoFirma”: “string”,

“DiasCaducidad”: 0,

“Multifirma”: boolean,

“ConPrioridad”: boolean,

“Pais”: “string”,

“Plantilla”: “string”,

“Documento”: “string”,

“Adjuntos”: “string”,

“Usuario”: “string”

}

Propiedades Request Body

Parámetro	Descripción	Tipo de dato
Asunto	Asunto del envío. La longitud máxima del parámetro es de 40 caracteres. Si se indica un texto más largo quedará recortado a 40 caracteres.	String
Emisor	Texto que identifique fácilmente a la organización o persona que envía el documento. La longitud máxima del parámetro es de 50 caracteres. Si se indica un texto más largo quedará recortado a 50 caracteres.	String
Id	Valor alfanumérico mediante el cual el cliente puede identificar el envío a generar con un valor propio de sus sistemas de forma que le resulte más fácil identificarlo posteriormente; por ejemplo, en un sistema que enviase facturas para firmarlas en esta propiedad el cliente podría indicar el número de factura. Esta propiedad es opcional, en caso de no querer rellenarla basta con dejarla vacía o simplemente no incluirla.	String
Receptores	Texto que contiene los diferentes destinatarios a los que se solicita la firma del documento.	String
	Esta propiedad está relacionada con la propiedad TipoEnvio:
	- Si la propiedad TipoEnvio tiene el valor S (SMS), el contenido de este texto serán números de móviles válidos separados por una coma ya que los destinatarios recibirán notificación a través de un SMS en sus móviles.
	- Si la propiedad TipoEnvio tiene el valor E (Email), el contenido de este texto serán direcciones de correo electrónico válidas separadas por una coma.
	- Si la propiedad TipoEnvio tiene el valor L (Link o Enlace), el contenido de este texto es indiferente que sean emails, teléfonos o por ejemplo nombres, dado que no se van a usar para enviar un SMS o un email, pero sí para al menos identificar de alguna manera a los destinatarios. De la misma forma que en las otras dos opciones, los destinatarios deben separarse por comas. El envío por enlace no es compatible con envíos multifirma.
	La longitud máxima del parámetro es de 500 caracteres. Si se indica un texto más largo quedará recortado a 500 caracteres.
TipoEnvio	Indica si los destinatarios recibirán una notificación mediante un SMS o un correo electrónico, o no recibirán ninguna notificación ya que será el cliente el que le hará llegar la url que le devolverá el servicio web en los datos identificativos del envío. Valores posibles: S – SMS, E – Email, L – Link o Enlace.	String
TipoFirma	Indica si los destinatarios podrán firmar mediante firma digital manuscrita, mediante un certificado digital,ambas opciones, bien mediante firma simple o bien mediante firma OTP recibiendo un código de verificación. Valores posibles: M – Firma digital manuscrita, C – Certificado digital, A – Ambas opciones indistintamente, S – Firma simple, O – Firma OTP. La firma mediante certificado digital no es compatible con los envíos multifirma. Esta propiedad es opcional, en caso de no querer rellenarla basta con dejarla vacía o simplemente no incluirla. En estos casos, el valor que toma es el que el cliente tiene indicado por defecto en sus opciones de configuración. La firma mediante código de verificación OTP no es compatible con los envíos mediante Link o enlace.	String
DiasCaducidad	Cuando transcurran los días indicados en esta propiedad sin que el envío haya sido completamente firmado (si es multifirma, firmado por todos los destinatarios), su estado pasará a ser caducado y ya no podrá firmarse o rechazarse. Su valor debe estar entre 1 y 255 días.	Byte
Multifirma	Indica si el envío es multifirma. Es una propiedad importante que marca como se va a comportar el proceso de generación de envíos: - Si el envío no es multifirma y se indican varios destinatarios en la propiedad Receptores, se generarán tantos envíos independientes como destinatarios se encuentren en dicha propiedad; cada envío con su propia identificación única y destinado a que sea firmado individualmente por cada uno de ellos. - Si el envío es multifirma, únicamente se generará un envío que deberá ser firmado por todos los destinatarios indicados en la propiedad Receptores.	Boolean
ConPrioridad	Esta propiedad sólo se tiene en cuenta en los envíos multifirma, y si se indica “true”, significa que los destinatarios deben firmar en el orden establecido; de modo que no puede firmar el 2º destinatario hasta que no haya firmado el 1º, y así sucesivamente. El orden queda establecido en la propiedad Receptores, de manera que el primer destinatario será el 1, el segundo será el 2, etc. Esta numeración es muy importante también porque estará relacionada con la plantilla utilizada, que en el caso de una plantilla multifirma, las ubicaciones para cada destinatario se indican por el nº de destinatario correspondiente, por tanto, el destinatario nº X según se haya puesto en la propiedad Receptores estará asociado a las ubicaciones de firmas con el mismo número de destinatario en la plantilla utilizada.	Boolean
Pais	Nombre del país a donde se enviará el documento. Es importante porque sirve para validar los números de teléfono móviles en el caso de que el tipo de envío sea por SMS. También los destinatarios recibirán los mensajes SMS o correos electrónicos en el idioma del país del envío. Actualmente en FirmaDocumentos es posible realizar envíos a los siguientes países: España, Alemania, Colombia, Argentina, Brasil, México, Perú, EEUU y Canadá.	String
Plantilla	Nombre de la plantilla que se va a utilizar para el envío generado y por tanto la que indica donde se ubicarán las firmas de las personas que firmen el documento. Se debe tener en cuenta que debe haber una correspondencia en las propiedades Multifirma y Plantilla, de forma que no se puede indicar una plantilla que no sea multifirma si indicamos que la propiedad multifirma es true.	String
Documento	Codificación en un string en formato Base64 del documento pdf que se va a firmar.	String
Adjuntos	Se puede solicitar a los firmantes documentación adjunta necesaria. En esta propiedad y separada por una coma podremos indicar los documentos adjuntos que necesitemos y que deberemos tener configurados previamente en FirmaDocumentos.	String
Usuario	Indica si el envío que se está realizando pertenece a un usuario, para lo que se rellenará con el correo electrónico del usuario. Si no se incluye la propiedad o se deja vacía, la el envío se asigna al administrador de la cuenta.	String

Ejemplos de Request Body:

Envío normal que generará dos envíos independientes y en los que se solicitará además como documentación adjunta el DNI. Cada envío se notificará por email y será necesario firmarlo con un certificado digital:

{“Asunto”: “Envio Prueba 1”, “Emisor”: “ENVIOS ACME”, “Id”: “env.1234”, “Receptores”: “destinatario1@gmail.com,destinatario2@gmail.com”, “TipoEnvio”: “E”, “TipoFirma”: “C”, “DiasCaducidad”: 25, “Multifirma”: false, “ConPrioridad”: false, “Pais”: “España”, “Plantilla”: “Plantilla 1”, “Documento”: “JVBERi0xLjcNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlcy1FUykgL1N0cnVjdFRyZWVSb290IDEwIDAgUi9NYXJrSW5mbzw8L01hcmtlZCB0cnVlPj4vTWV0YWRhdGEgMjAgMCBSL1ZpZXdGb250vRjEgNSAwIFI+Pi9FeHRH …(continúa)”, “Adjuntos”:”DNI”,”Usuario”:”ejemplo@mail.com”}

Envío multifirma que generará un envío que deberá ser firmado por tres destinatarios que serán notificados por SMS:

{“Asunto”: “Envio Multifirma”, “Emisor”:”ENVIOS ACME”, “Id”: “env.1234”, “Receptores”: “666666666,666777888,666111222”, “TipoEnvio”: “S”, “TipoFirma”: “M”, “DiasCaducidad”: 5, “Multifirma”: true, “ConPrioridad”: false, “Pais”: “España”, “Plantilla”: “Multifirma”, “Documento”: ” JVBERi0xLjcNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlcy1FUykgL1N0cnVjdFRyZWVSb290IDEwIDAgUi9NYXJrSW5mbzw8L01hcmtlZCB0cnVlPj4vTWV0YWRhdGEgMjAgMCBSL1ZpZXdGb250vRjEgNSAwIFI+Pi9FeHRH … (continúa)”, “Adjuntos”: “”,”Usuario”:”ejemplo@mail.com”}

Response Body (status 200). Operación correcta

[

{

“IdEnvio”: 0,

“CodEnvio”: “string”

“UrlEnvio”: “string”

}

]

Response Content-Type: application/json

Este servicio web devuelve información que identifica los envíos generados para que pueda almacenarla en el sistema con el que está integrando nuestra API y poder realizar operaciones posteriores utilizando dicha información. En el caso de envíos multifirma siempre devolverá una única identificación (IdEnvio, CodEnvio, UrlEnvio), puesto que sólo se genera un envío; pero en los envíos que no son multifirma se generarán tantos envíos como receptores se hayan indicado en la propiedad correspondiente y por tanto se devolverán tantas identificaciones como envíos se hayan generado.

Parámetro	Descripción	Tipo de dato
IdEnvio	Identificador numérico interno en Firma Documentos de cada envío generado	Entero 32 bits
CodEnvio	Código público identificativo de cada envío y que puede ser utilizado posteriormente como parámetro en otras operaciones sobre el envío.	String
UrlEnvio	Cuando el tipo de envío sea por enlace (“L”), esta propiedad contendrá la url de acceso a la aplicación de firma que se le enviará al destinatario. El cliente será el encargado de hacerle llegar dicha url con el sistema que mejor se adapte a sus procesos.	String

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Sending/cod

Descripción	Obtiene los datos de un envío determinado

Tipo	POST

Request Body

{

“OsName”: “string”,

“OSVersion”: “string”,

“Model”: “string”,

“Username”: “string”,

“DeviceID”: “string”

}

La información indicada en el request body es importante para la trazabilidad cuando se obtiene la información del envío durante el ciclo de firma; es decir, cuando desde un sistema que integremos con la API se quiera guardar en el documento de trazabilidad la información referida al dispositivo o navegador desde el que el destinatario ha consultado el envío es importante rellenar correctamente las propiedades. Esta información se guarda en el registro de trazabilidad cuando se llama a este servicio web estando el envío en estado Pendiente. Cuando el envío ya no esté pendiente y se consulte la información del mismo a través de este servicio web, el valor que se dé a estas propiedades será irrelevante.

Propiedades Request Body

Parámetro	Descripción	Tipo de dato
OsName	Sistema operativo del dispositivo desde el que se accede al envío o si se hace desde un navegador, el nombre del mismo.	String
OsVersion	Está relacionada con la propiedad anterior y en ésta se indica la versión, bien sea del SO del dispositivo o del navegador, etc. De este modo entre ambas propiedades se registrarán por ejemplo valores como “iphone 13.4.1” o “Chrome 72.0”	String
Model	Cuando se acceda desde un navegador no tiene sentido rellenar este dato, si se hace desde un dispositivo podemos obtener el modelo del mismo, por ejemplo, “samsung SM-G935F”	String
Username	En algunos dispositivos es posible obtener el username del mismo, por ejemplo: “iPhone de Sandra”	String
DeviceID	Al acceder a la información desde un navegador podremos indicar la IP desde la que se accede; en el caso de dispositivos podríamos indicar un identificador que es posible recuperar y que depende del SO que utilice. Algunos ejemplos: “B47D69F9-59BB-489A-87E5-C2BC3D41D252”, “63d28e0c801b0485”, etc.	String

Response Body (status 200). Operación correcta

{

“IdEnvio”: 0,

“CodEnvio”: “string”,

“Id”: “string”,

“CodHash”: “string”,

“Asunto”: “string”,

“Emisor”: “string”,

“Usuario”: “string”,

“Receptores”: “string”,

“FechaEnvio”: “string”,

“TipoEnvio”: “string”,

“TipoFirma”: “string”,

“Estado”: “string”,

“DiasCaducidad”: 0,

“FechaFirma”: “string”,

“FechaRechazo”: “string”,

“Multifirma”: boolean,

“ConPrioridad”: boolean,

“Pais”: “string”,

“Plantilla”: “string”,

“Documento”: “string”,

“Adjuntos”: “string”,

“DocsEnvio”: [

{

“IdDocEnvio”: 0,

“IdEnvio”: 0,

“TipoAdjunto”: “string”,

“IdDestinatario”: 0

}

]

“Destinatarios”: [

{

“IdDestinatario”: 0,

“IdEnvio”: 0,

“DatoDestinatario”: “string”,

“Estado”: “string”,

“Fecha”: “string”,

“MotivoRechazo”: “string”

}

]

}

Response Content-Type: application/json

Propiedades Response Body

Parámetro	Descripción	Tipo de dato
IdEnvio	Identificador numérico interno en Firma Documentos del envío	Entero 32 bits
CodEnvio	Código público identificativo de cada envío.	String
Id	Cadena identificadora del envío en el caso de que haya sido informado en el momento de realizar el envío, contendrá el valor que se indicó, en caso contrario, la propiedad estará vacía.
CodHash	Código hash MD5 generado a partir del contenido del archivo pdf y que sirve en todo momento para verificar la integridad del documento, sobretodo al completarse su firma y de esa forma comprobar si dicho documento ha sido alterado o no tras su firma.	String
Asunto	Asunto del envío	String
Emisor	Texto que identifique fácilmente a la organización o persona que envía el documento	String
Usuario	Contiene el correo electrónico del usuario que realizó el envío o null en el caso de que el envío lo realizara el administrador de la cuenta	String
Receptores	Texto que contiene los diferentes destinatarios a los que se solicita la firma del documento.	String
FechaEnvio	Fecha y hora en la que se generó el envio.	String
TipoEnvio	Indica si los destinatarios recibirán una notificación mediante un SMS o mediante un correo electrónico. Valores posibles: S – SMS, E – Email	String
TipoFirma	Indica si los destinatarios podrán firmar mediante firma digital manuscrita, certificado digital o ambas indistintamente. Valores posibles: M – firma digital manuscrita, C – certificado digital, A – ambas opciones indistintamente	String
Estado	Estado actual del envío. Valores posibles: P – Pendiente (es el estado inicial), F – Firmado, R – Rechazado, C – Caducado En el caso de un envío multifirma, el envío no cambiará a firmado hasta que todos los destinatarios hayan firmado el documento; por el contrario, cuando uno de ellos lo rechace, el envío pasará al estado rechazado.
DiasCaducidad	Cuando transcurran los días indicados en esta propiedad sin que el envío haya sido completamente firmado (si es mutifirma, firmado por todos los destinatarios), su estado pasará a ser caducado y ya no podrá firmarse o rechazarse. Su valor debe estar entre 1 y 255 días.	Byte
FechaFirma	Fecha y hora en la que el envío pasa al estado firmado	String
FechaRechazo	Fecha y hora en la que el envío pasa al estado rechazado	String
MotivoRechazo	Texto descriptivo que indicó el destinatario al rechazar el envío	String
Multifirma	Indica si el envío es multifirma	Boolean
ConPrioridad	Esta propiedad sólo se tiene en cuenta en los envíos multifirma, y si se indica “true”, significa que los destintarios deben firmar en el orden establecido; de modo que no puede firmar el 2º destinatario hasta que no haya firmado el 1º, y así sucesivamente.	Boolean
Pais	Nombre del país a donde se hizo el envío.	String
Plantilla	Nombre de la plantilla utilizada.	String
Documento	Al usar este servicio web esta propiedad estará vacía. Para obtener el documento en sí se debe utilizar el servicio web Document.	String
Adjuntos	Al usar este servicio web esta propiedad esta vacía, en su lugar se obtiene una lista de los adjuntos asociados que contiene más información como a continuación veremos en la propiedad DocsEnvio.	String
DocsEnvio	Documentos asociados al envío. Cada uno de ellos tiene las propiedades que se referencian a continuación con el prefijo DocE.
DocE.IdDocEnvio	Identificador numérico necesario si se quiere utilizar el servicio web Attachment	Entero 32 bits
DocE.IdEnvio	Identificador numérico del envío al que está asociado	Entero 32 bits
DocE.TipoAdjunto	Nombre descriptivo del tipo de adjunto del que se trata. Por ejemplo: DNI	String
DocE.IdDestinatario	Identificador en el envío del destinatario al que corresponde el adjunto. En el caso de envíos que no son multifirma este valor será siempre 0; en los envíos multifirma tendrá un valor referido a alguno de los destinatarios que deben firmar el documento, y en el que si se han solicitado adjuntos, cada uno de ellos tendrá que aportar dichos adjuntos	Byte
Destinatarios	Lista de información referida a cada uno de los destinatarios que tenga asociado el envío si este es multifirma. Cada uno de ellos tiene las propiedades que se referencian a continuación con el prefijo D.
D.IdDestinatario	Identificador en el envío del destinatario. Este dato es importante si se requieren hacer algunas operaciones por lo que luego explicaremos del parámetro de entrada cod.	Byte
D.IdEnvio	Identificador numérico del envío al que está asociado.	Entero 32 bits
D.DatoDestinatario	Dato que se indicó al crear el envío en la propiedad Receptores y que se refiere al número de móvil o dirección de correo electrónico del destinatario.	String
D.Estado	Estado actual del destinatario respecto a lo que haya hecho o no. Valores posibles: P – Pendiente (es el estado inicial), F – Firmado, R – Rechazado	String
D.Fecha	Fecha y hora en la que el destinatario ha realizado la acción reflejada en el estado, es decir, firmar el documento o rechazarlo	String
D.MotivoRechazo	Texto descriptivo que indicó el destinatario al rechazar el envío	String

Propiedades query

Parámetro	Descripción	Tipo de dato
cod	Código público identificativo de cada envío. Cuando se requiera obtener la información del envío, pero referida a un solo destinatario en el caso de un envío multifirma, el código debe formarse por los 5 caracteres del propio código del envío más dos caracteres que representarán el identificador del destinatario en el envío en hexadecimal. Por ejemplo, si se requiere obtener la información acotada del destinatario 12 del envío XJH29, el parámetro cod será “XJH290C” ya que 12 = 0C en hexadecimal.	String

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Document/cod

Descripción	Obtiene el documento en formato string base 64

Tipo	POST

Request Body

{

“OsName”: “string”,

“OSVersion”: “string”,

“Model”: “string”,

“Username”: “string”,

“DeviceID”: “string”

}

La información indicada en el request body es importante para la trazabilidad cuando se obtiene el documento durante el ciclo de firma; es decir, cuando desde un sistema que integremos con la API se quiera guardar en el documento de trazabilidad la información referida al dispositivo o navegador desde el que el destinatario ha obtenido el documento es importante rellenar correctamente las propiedades. Esta información se guarda en el registro de trazabilidad cuando se llama a este servicio web estando el envío en estado Pendiente. Cuando el envío ya no esté pendiente y se obtenga el documento través de este servicio web, el valor que se dé a estas propiedades será irrelevante.

Propiedades Request Body

Parámetro	Descripción	Tipo de dato
OsName	Sistema operativo del dispositivo desde el que se obtiene el documento o si se hace desde un navegador, el nombre del mismo.	String
OsVersion	Está relacionada con la propiedad anterior y en ésta se indica la versión, bien sea del SO del dispositivo o del navegador, etc. De este modo entre ambas propiedades se registrarán por ejemplo valores como “iphone 13.4.1” o “Chrome 72.0”	String
Model	Cuando se acceda desde un navegador no tiene sentido rellenar este dato, si se hace desde un dispositivo podemos obtener el modelo del mismo, por ejemplo, “samsung SM-G935F”	String
Username	En algunos dispositivos es posible obtener el username del mismo, por ejemplo: “iPhone de Sandra”	String
DeviceID	Al acceder al documento desde un navegador podremos indicar la IP desde la que se accede; en el caso de dispositivos podríamos indicar un identificador que es posible recuperar y que depende del SO que utilice. Algunos ejemplos: “B47D69F9-59BB-489A-87E5-C2BC3D41D252”, “63d28e0c801b0485”, etc.	String

Response Body (status 200). Operación correcta

Response Content-Type: string

Parámetros query

Parámetro	Descripción
cod	Código público identificativo del envío.
	Cuando se requiera obtener el documento para uno de los destinatarios en el caso de un envío multifirma, el código debe formarse por los 5 caracteres del propio código del envío más dos caracteres que representarán el identificador del destinatario en el envío en hexadecimal. Por ejemplo, si se requiere obtener la información acotada del destinatario 12 del envío XJH29, el parámetro cod será “XJH290C” ya que 12 = 0C en hexadecimal. Esta casuística es importante conocerla si queremos guardar en el documento de trazabilidad la información de cuando obtiene el documento cada uno de los destinatarios de un envío multifirma, durante el ciclo de firma del envío.

Parámetro

Descripción

cod

Código público identificativo del envío.

Cuando se requiera obtener el documento para uno de los destinatarios en el caso de un envío multifirma, el código debe formarse por los 5 caracteres del propio código del envío más dos caracteres que representarán el identificador del destinatario en el envío en hexadecimal. Por ejemplo, si se requiere obtener la información acotada del destinatario 12 del envío XJH29, el parámetro cod será “XJH290C” ya que 12 = 0C en hexadecimal. Esta casuística es importante conocerla si queremos guardar en el documento de trazabilidad la información de cuando obtiene el documento cada uno de los destinatarios de un envío multifirma, durante el ciclo de firma del envío.

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Attachment/cod

Descripción	Sube al servidor cada una de las imágenes que forman los adjuntos solicitados en el envío. El ámbito de uso de este servicio web está exclusivamente centrado en el proceso de firma del documento; cuando, en el caso de haberse solicitado adjuntos adicionales, el destinatario debe aportar dicha documentación. El servicio web se encarga de procesar cada imagen subida, unirlas (en el caso de que un mismo adjunto necesite estar formado por varias imágenes, por ejemplo, para un DNI puede subirse la imagen del anverso y la imagen del reverso)

Tipo	POST

Request Body

{

“Orden”: 0,

“IdDocAdjunto”: 0,

“NumFotos”: 0,

“Imagen”: “string”,

“Archivo”: “string”

}

Propiedades Request Body

Parámetro	Descripción	Tipo de dato
Orden	Orden de la imagen dentro del documento final que se construirá para el documento adjunto.	Byte
IdDocAdjunto	Identificador numérico del documento adjunto cuyo valor se habrá obtenido al recuperar la información mediante el servicio web Sending/cod	Entero 32 bits
NumFotos	Número de imágenes que constituyen el documento adjunto. De esta forma, el sistema puede comprobar si ya ha recibido todas las imágenes para el adjunto y así poder generar el archivo con todas ellas.	Byte
Imagen	Codificación en un string en formato Base64 de la imagen.	String
Archivo	Nombre del archivo de la imagen	String

Parámetros query

Parámetro	Descripción	Tipo de dato
cod	Código público identificativo del envío.	string
	En un envío multifirma, el código siempre deberá formarse por los 5 caracteres del propio código del envío más dos caracteres que representarán el identificador del destinatario en el envío en hexadecimal. Por ejemplo, si se requiere obtener la información acotada del destinatario 12 del envío XJH29, el parámetro cod será “XJH290C” ya que 12 = 0C en hexadecimal.

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/AddresseeResponse/cod

Descripción

Realiza la operación de firma o de rechazo según la respuesta del destinatario y se indique en una de las propiedades del request body.

No se pueden realizar operaciones de firma en envíos que se han generado para firmarse mediante un certificado digital.

Tipo

POST

Request Body

{

“Operacion”: “string”,

“DatoAuxiliar”: “string”,

“OsName”: “string”,

“OSVersion”: “string”,

“Model”: “string”,

“Username”: “string”,

“DeviceID”: “string”

}

En este servicio web la información indicada en el request body es siempre relevante para la trazabilidad ya que guardará la información relativa al momento en que los destinatarios firmen o rechacen el documento enviado.

Propiedades Request Body

Parámetro	Descripción	Tipo de dato
Operación	Indica la operación seleccionada por el destinatario. Valores posibles: F – Firmar con firma manuscrita, R – Rechazar, FC – Firmar con certificado, FS – Firmar con firma simple	String
DatoAuxiliar	Dependiendo del tipo de operación, esta propiedad contendrá una información u otra: - En el caso de firma, debe contener la codificación en un string en base64 de la imagen de la firma del destinatario. - En el caso de rechazo, debe contener un texto indicando el motivo de rechazar la firma del documento - En el caso de firma con certificado debe contener un JSON serializado con la siguiente estructura: {“Password certificado”:”string en base64 de los Bytes del certificado exportado”} - En el caso de firma simple puede contener el nombre de la persona firmante o bien quedarse en blanco, en cuyo caso se utilizará el destinatario del envío como dato.	String
OsName	Sistema operativo del dispositivo desde el que se firma o rechaza el documento o si se hace desde un navegador, el nombre del mismo.	String
OsVersion	Está relacionada con la propiedad anterior y en ésta se indica la versión, bien sea del SO del dispositivo o del navegador, etc. De este modo entre ambas propiedades se registrarán por ejemplo valores como “iphone 13.4.1” o “Chrome 72.0”	String
Model	Cuando se acceda desde un navegador no tiene sentido rellenar este dato, si se hace desde un dispositivo podemos obtener el modelo del mismo, por ejemplo, “samsung SM-G935F”	String
Username	En algunos dispositivos es posible obtener el username del mismo, por ejemplo: “iPhone de Sandra”	String
DeviceID	Al firmar o rechazar el documento desde un navegador podremos indicar la IP desde la que se accede; en el caso de dispositivos podríamos indicar un identificador que es posible recuperar y que depende del SO que utilice. Algunos ejemplos: “B47D69F9-59BB-489A-87E5-C2BC3D41D252”, “63d28e0c801b0485”, etc.	String

Parámetros query

Parámetro	Descripción	Tipo de dato
cod	Código público identificativo del envío. En un envío multifirma, el código siempre deberá formarse por los 5 caracteres del propio código del envío más dos caracteres que representarán el identificador del destinatario en el envío en hexadecimal. Por ejemplo, si se requiere obtener la información acotada del destinatario 12 del envío XJH29, el parámetro cod será “XJH290C” ya que 12 = 0C en hexadecimal.	string

Mensajes de Respuesta

HTTP Status Code	Mensaje
200	Operación correcta
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Trace/Cod

Descripción	Obtiene el documento de trazabilidad en formato string base 64

Tipo	GET

Response Body (status 200). Operación correcta

Response Content-Type: string

Parámetros query

Parápetro	Descripción	Tipo de dato

Cod	Código público identificativo del envío	String

Mensajes de respuesta

http Status Code	Mensaje

401	Error de autenticación
418	Ver el texto del mensaje de respuesta

Servicios para control del uso de Firma Documentos

Son servicios web que ofrecen datos sobre el uso de Firma Documentos por parte del cliente que pueden utilizarse para tener un control y seguimiento.

URL entorno de pruebas: https://apitest.firmadocumentos.es/admin/…

URL entorno real: https://api.firmadocumentos.es/admin/…

/Summary/fromdate/todate

Descripción	Obtiene un resumen de los datos de los envíos generados por el cliente según el filtro de fechas indicadas en los parámetros fromdate y todate

Tipo	GET

Response Body (status 200). Operación correcta

{

“Enviados”: 0,

“Pendientes”: 0,

“Firmados”: 0,

“Rechazados”: 0,

“Caducados”: 0

}

Response Content-Type: application/json

Propiedades Response Body

Parámetro	Descripción	Tipo de dato
Enviados	Número de envíos generados en el periodo de tiempo consultado	Entero 32 bits
Pendientes	Número de envíos generados en el periodo de tiempo consultado en estado pendiente	Entero 32 bits
Firmados	Número de envíos generados en el período de tiempo consultado en estado firmado	Entero 32 bits
Rechazados	Número de envíos generados en el período de tiempo consultado en estado rechazado	Entero 32 bits
Caducados	Número de envíos generados en el período de tiempo consultado en estado caducado	Entero 32 bits

Parámetros query

Parámetro	Descripción	Tipo de dato
fromdate	Fecha a partir de la cual se consultan los envíos. El formato debe ser DDMMAAAA.	String
	Si no se quiere indicar una fecha inicial el valor del parámetro debe ser un guión “-“.
todate	Fecha hasta la cual se consultarán los envíos. El formato debe ser DDMMAAAA.	String
	Si no se quiere indicar una fecha final el valor del parámetro debe ser un guión “-“.

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Budget

Descripción	Obtiene el número de envíos disponibles según el plan contratado por el cliente

Tipo	GET

Response Body (status 200). Operación correcta

Response Content-Type: integer

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Users

Descripción	Crea usuarios administradores en un cliente

Tipo	GET

Request Body

{

“Nombre”: “string”,

“Email”: “string”,

}

Parámetro	Descripción	Tipo de dato
Nombre	Nombre del nuevo usuario que se desea crear. La longitud máxima del parámetro es de 50 caracteres. Si se indica un texto más largo quedará recortado a 50 caracteres.	String
Email	Correo electrónico del nuevo usuario que se desea crear. La longitud máxima del parámetro es de 50 caracteres. Si se indica un texto más largo quedará recortado a 50 caracteres.	String

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

Response Body (status 200). Operación correcta

{

“Nombre”: “string”,

“Email”: “string”,

“Contraseña”: “string”,

}

Parámetro	Descripción	Tipo de dato
Nombre	Nombre del nuevo usuario creado.	String
Email	Correo electrónico del nuevo usuario creado.	String
UrlEnvio	Contraseña del nuevo usuario creado.	String

Mensajes de Respuesta

HTTP Status Code	Mensaje
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

Servicios para el uso de WebHooks

Son servicios web que permiten configurar los WebHook de los clientes donde se enviarán los eventos generados, tanto la URL como los eventos concretos que quiere recibir, es decir, a los eventos a los que quiere subscribirse; también podrá eliminar su configuración del WebHook para no recibir los eventos; así como poder provocar la generación de dichos eventos para probar sus propios procesos.

URL entorno de pruebas: https://apitest.firmadocumentos.es/webhooks/…

URL entorno real: https://api.firmadocumentos.es/webhooks/…

Descripción	Indica a FirmaDocumentos la url del cliente donde se enviarán los eventos, así como a qué eventos quiere subscribirse, es decir, qué eventos quiere recibir en la url indicada. El servicio web sirve tanto para subscribirse la primera vez como para modificar la configuración de los WebHook, es decir, si el cliente desea modificar la url o cambiar los eventos a los que quiere subscribirse, puede utilizar este servicio cada vez que requiera hacer un cambio de este tipo. Siempre se deben indicar las dos propiedades. Por otro lado y como es obvio, al poder utilizarse este servicio web tanto en el entorno de pruebas como en el real, el cliente puede configurar WebHooks con distintas urls para un entorno y para el otro, y así poder trabajar con un WebHook en su propio entorno de pruebas.

Tipo	POST

Request Body

{

“Url”: “string”,

“Eventos”: “string”

}

Propiedades Request Body

Parámetro	Descripción	Tipo de dato
Url	Indica la url del WebHook donde se enviarán los datos de los eventos generados	String
Eventos	Es un valor de tipo cadena que indicará cuáles son los eventos que el cliente quiere recibir. Se pueden indicar tres eventos posibles:	String
	- A: el envío ha sido abierto
	- F: el envío ha sido firmado
	- R: el envío ha sido rechazado
	- C: el envío ha pasado al estado caducado tras superar el periodo de caducidad
	Simplemente hay que indicar los eventos que quieren recibirse separados por una coma. Ejemplos válidos:
	- F: el cliente sólo quiere recibir el evento de que se ha firmado el envío
	- F,R: el cliente quiere recibir los eventos generados al firmarse o rechazarse un envío
	- A,F,R,C: el cliente quiere recibir todos los eventos
	El orden en que se indiquen no importa.

Mensajes de Respuesta

HTTP Status Code	Mensaje
200	Operación correcta
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

/Unsubscribe

Descripción	Indica a FirmaDocumentos que el cliente no desea utilizar los WebHook, de forma que se eliminará la información relativa a su uso.

Tipo	POST

Mensajes de Respuesta

HTTP Status Code	Mensaje
200	Operación correcta
401	Error de autenticación

/Test/evento

Descripción	Provoca que se genere el evento indicado como parámetro y se envíe al WebHook configurado por el cliente. De esta forma, el cliente podrá hacer pruebas con su WebHook sin utilizar envíos de forma innecesaria.

Tipo	POST

Parámetros query

Parámetro	Descripción	Tipo de dato
evento	Indica el evento que se quiere generar utilizando los mismos códigos que en la configuración del WebHook. Así el valor posible para este parámetro es uno de los 3 siguientes:	string
	- A: generar evento de envío abierto
	- F: generar evento de envío firmado
	- R: generar evento de envío rechazado
	- C: generar evento de envío caducado

Mensajes de Respuesta

HTTP Status Code	Mensaje
200	Operación correcta
401	Error de autenticación
418	Ver el texto del mensaje de respuesta

Recepción de los WebHook

Como hemos dicho en el apartado anterior, FirmaDocumentos genera varios eventos que son enviados al WebHook configurado por el cliente. La información que se envía es la siguiente:

{

“Id”: “string”,

“Attempt”: 0,

“Properties”: {},

“Notifications”: [

{

“Action”: “string”,

“id”: “string”,

“id2”: 0,

“date”: “string”,

“comment”: “string”

}

]

}

Propiedades

Editar
Parámetro	Descripción	Tipo de dato
ID	Identificador de la notificación	String
Attempt	Número de intento del envío. Se realizan hasta 3 intentos.	Numérico
Properties	Información del evento. FirmaDocumentos sólo indica un evento en cada caso por lo que este array sólo contendrá un elemento siempre. Las propiedades contenidas se referencian a continuación con el prefijo Notif.
Notif.Action	Es la acción que genera el evento. Los valores posibles son: – open. Envío abierto – signed. Envío firmado – refused. Envío rechazado – timed-out. Envío caducado	String
Notif.id	Código del envío	String
Notif.id2	Identificador en el envío del destinatario al que corresponde la acción de firma o rechazo si es un envío multifirma.	Byte
Notif.date	Fecha y hora en que se produce el evento.	String
Notif.comment	En caso de que sea el evento de rechazo, se indica en ese parámetro el texto con el motivo del rechazo.	String

Cuando se trata de un envío multifirma y se da la situación de que firma el último destinatario que estaba pendiente de firmar, se generarán dos eventos seguidos, uno indicando la firma del destinatario y otro también de firma sin indicar destinatario que significará que el envío ha quedado firmado por todos los destinatarios.

A continuación, se muestra un ejemplo de evento de firma generado por el servicio web /webhooks/Test capturado en Fiddler.

Implementación del WebHook

Facilitamos un ejemplo de una implementación de WebHook desarrollado en C# y utilizando las librerías de Microsoft ASP.NET WebHook que facilitan mucho la labor.

Naturalmente el cliente es libre de desarrollar la implementación de los WebHook de FirmaDocumentos utilizando los lenguajes, tecnologías y frameworks que prefiera según sus necesidades y requerimientos. Este proyecto es sólo un ejemplo que esperamos que pueda aprovechar.

Puede descargarse tanto el código fuente del proyecto, como el proyecto ya compilado listo para su despliegue en los siguientes enlaces.

Un breve vistazo a los fuentes del proyecto le permitirá comprobar que es en el archivo CustomWebHookHandler.cs donde se centra la recepción de los eventos y su proceso. En el método ExecuteAsync se pueden ver varias líneas de código donde se ejemplifican varios posibles usos de los datos recibidos: dar valor a una variable de cadena con los datos en formato JSON, convertir los datos en una clase más entendible, a través de una clase EventoFirmaDocumentos, realizar luego un proceso distinto según el evento recibido, etc. Al final se ha añadido una línea de código que guarda en un archivo plano los datos recibidos en una subcarpeta logs como ejemplo rápido de procesamiento de los eventos.
Como hemos dicho anteriormente, este proyecto pretende ser un punto de partida para ayudarle a implementar su WebHook.
Para el despliegue del proyecto, simplemente necesitará crear en sus sistemas un sitio web donde alojarlo. Una vez que tenga dicho sitio web creado deberá tener en cuenta unas pocas indicaciones:

– Copiar los archivos contenidos en Despliegue Ejemplo FDWebHookReceiver.rar en la carpeta correspondiente del servidor
– Dar permisos de lectura y escritura al usuario de IIS, normalmente IIS_IUSRS, en la carpeta logs.
– Poner en la clave “MS_WebHookReceiverSecret_Custom” del Web.config el valor de su “Consumer Secret” que utiliza para las llamadas a la API de FirmaDocumentos. Esta clave en el Web.config es necesaria cuando se utilizan las librerías de Microsoft ASP. Net WebHooks. Si va a implementar su WebHook sin estas librerías, no sería necesario.

Una vez desplegado el webhook mediante este proyecto de ejemplo, la url del mismo que debería configurar a través de la API con el servicio web /webhooks/Subscribe sería http (o https)://sudominio/api/webhooks/incoming/custom

Documentación sobre OAuth 1.0

Como se indicó al principio de este documento los servicios web requieren de autenticación OAuth 1.0. A continuación se anexa diversa información que le será útil para desarrollar las integraciones que necesite utilizando este tipo de autenticación.

https://oauth.net/1 Especificaciones de OAuth 1.0 y colección de librerías en diversos lenguajes

http://lti.tools/oauth/ Página web que funciona como una SandBox para generar los parámetros necesarios para acceder a una determinada url y que además explica paso a paso cómo se genera cada uno de ellos, resultando muy útil para la comprensión de este tipo de autenticación. Se recomienda probarlo seleccionando la opción “Create Your Own” ya que permite la generación completa de una llamada a cualquier servicio web que el usuario necesite, pudiendo configurar todos los elementos de la llamada al servicio.

https://github.com/onmyway133/oauth/tree/master/code Código fuente en los lenguajes más populares de la implementación de la autenticación OAuth 1.0. Por comentar algún ejemplo, destacamos las implementaciones en .Net, tanto C# en el archivo OAuthBase.cs como en VB.Net en el archivo oAuth.vb; o la implementación en JavaScript en los archivos oauth.js y sha1.js, este último contiene la implementación del algoritmo de hash.

Un ejemplo de generación de parámetros en JavaScript:

//load up additional parameters for the request
var moreParams = parameters || {};
for (var key in moreParams) {
if (moreParams.hasOwnProperty(key)) {
message.parameters.push([key, moreParams[key]]);
}
}

OAuth.SignatureMethod.sign(message, accessor);
var finalUrl = OAuth.addToURL(message.action, message.parameters);
finalUrl = finalUrl.replace(“%253D”, “%3D”);

Otro ejemplo, esta vez en .Net, de preparación de llamada:

Dim normalUrl As String = “”
Dim normalParametros As String = “”
Dim Uri As Uri = New Uri(“https://apitest.firmadocumentos.es/Admin/Budget”)

Dim oAuth As New OAuth.OAuthBase
Dim nonce As String = oAuth.GenerateNonce ‘Cadena de contenido aleatorio
Dim timestamp As String = oAuth.GenerateTimeStamp ‘Timestamp
Dim signature As String = oAuth.GenerateSignature(Uri, ConsumerKey, ConsumerSecret,
String.Empty, String.Empty, “GET”,
timestamp, nonce, normalUrl, normalParametros)

Dim RequestURL As String = String.Format(“{0}?{1}&oauth_signature={2}”, normalUrl, normalParametros, signature)

Descargar documentación PDF

1. Introducción/API Web Services 1.1

2. Algunos Ejemplos

3. Servicios para el proceso de firma

3.1.- /Template

3.2.- /Sending

3.3.- /Sending/cod

3.4.- /Document/cod

3.5.- /Attachment/cod

3.6.- /AddresseeResponse/cod

4.- Servicios para control del uso de Firma Documentos