Seleccionar página

API Web Services 1.7

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 

FechaCambiosVersión
30/07/2020Se 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/2020Se 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/2020Se 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/2021Se 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/2022Se 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/2022Se 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/2022Se 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/2022Se añade la opción de poder crear un envío con tipo de firma OTP.1.7

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ámetroDescripciónTipo de dato
NomPlantillaNombre 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á. Máx. 40 caracteresString
OrientacionOrientación de las páginas en el documento a enviar. Valores posibles: V – Vertical, H – HorizontalString
CodFormatoFormato de las páginas en el documento a enviar. Valores posibles: A4, A3, A2, A1, A5String
SelloImagen 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 selloString
AltoFirmaAlto de las firmas de los destinatarios en cm.Single
AnchoFirmaAncho de las firmas de los destinatarios en cm.Single
AltoSelloAlto del sello de la empresa en cm. Indicar 0 si no hay selloSingle
AnchoSelloAncho del sello de la empresa en cm. Indicar 0 si no hay selloSingle
MultifirmaTrue 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
NumeroDestinatariosIndica el número de personas que tendrán que firmar el documento cuando se trate de un envío multifirma. Máx. 255Byte
PlantillaPorDefectoEs 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
UbicacionFirmasEsta 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.IdDestinatarioSi 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.NumPaginaNú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.TipoFirmaIndica 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 – SelloString
UF.XCoordenada X en cm. La esquina inferior izquierda es la coordenada (0,0)Single
UF.YCoordenada Y en cm. La esquina inferior izquierda es la coordenada (0,0)Single
UF.TextoEs 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. Máx. 100 caracteresString
UsuarioIndica 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ámetroDescripciónTipo de dato
AsuntoAsunto del envíoString
EmisorTexto que identifique fácilmente a la organización o persona que envía el documentoString
IdValor 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.String
Esta propiedad es opcional, en caso de no querer rellenarla basta con dejarla vacía o simplemente no incluirla.
ReceptoresTexto 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.
TipoEnvioIndica 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 EnlaceString
TipoFirmaIndica si los destinatarios podrán firmar mediante firma digital manuscrita, mediante un certificado digital o indistintamente.String
Valores posibles: M – Firma digital manuscrita, C – Certificado digital, A – Ambas opciones indistintamente
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.
DiasCaducidadCuando 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
MultifirmaIndica 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:Boolean
- 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.
ConPrioridadEsta 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.Boolean
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.
PaisNombre 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.String
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á.
PlantillaNombre 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
DocumentoCodificación en un string en formato Base64 del documento pdf que se va a firmar.String
AdjuntosSe 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
UsuarioIndica 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

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ámetroDescripciónTipo de dato
IdEnvioIdentificador numérico interno en Firma Documentos de cada envío generado Entero 32 bits
CodEnvioCó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
UrlEnvioCuando 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ámetroDescripciónTipo de dato
OsNameSistema operativo del dispositivo desde el que se accede al envío o si se hace desde un navegador, el nombre del mismo.String
OsVersionEstá 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
ModelCuando 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
UsernameEn algunos dispositivos es posible obtener el username del mismo, por ejemplo: “iPhone de Sandra”String
DeviceIDAl 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ámetroDescripciónTipo de dato
IdEnvioIdentificador numérico interno en Firma Documentos del envíoEntero 32 bits
CodEnvioCódigo público identificativo de cada envío.String
IdCadena 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.
CodHashCó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
AsuntoAsunto del envíoString
EmisorTexto que identifique fácilmente a la organización o persona que envía el documentoString
EmisorTexto que identifique fácilmente a la organización o persona que envía el documentoString
ReceptoresTexto que contiene los diferentes destinatarios a los que se solicita la firma del documento.String
FechaEnvioFecha y hora en la que se generó el envio.String
TipoEnvioIndica si los destinatarios recibirán una notificación mediante un SMS o mediante un correo electrónico. Valores posibles: S – SMS, E – EmailString
TipoFirmaIndica 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 indistintamenteString
EstadoEstado 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.
DiasCaducidadCuando 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
FechaFirmaFecha y hora en la que el envío pasa al estado firmadoString
FechaRechazoFecha y hora en la que el envío pasa al estado rechazadoString
MotivoRechazoTexto descriptivo que indicó el destinatario al rechazar el envíoString
MultifirmaIndica si el envío es multifirmaBoolean
ConPrioridadEsta 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
PaisNombre del país a donde se hizo el envío.String
PlantillaNombre de la plantilla utilizada.String
DocumentoAl usar este servicio web esta propiedad estará vacía. Para obtener el documento en sí se debe utilizar el servicio web Document.String
AdjuntosAl 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
DocsEnvioDocumentos asociados al envío. Cada uno de ellos tiene las propiedades que se referencian a continuación con el prefijo DocE.
DocE.IdDocEnvioIdentificador numérico necesario si se quiere utilizar el servicio web AttachmentEntero 32 bits
DocE.IdEnvioIdentificador numérico del envío al que está asociadoEntero 32 bits
DocE.TipoAdjuntoNombre descriptivo del tipo de adjunto del que se trata. Por ejemplo: DNIString
DocE.IdDestinatarioIdentificador 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 adjuntosByte
DestinatariosLista 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.IdDestinatarioIdentificador 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.IdEnvioIdentificador numérico del envío al que está asociado.Entero 32 bits
D.DatoDestinatarioDato 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.EstadoEstado actual del destinatario respecto a lo que haya hecho o no. Valores posibles: P – Pendiente (es el estado inicial), F – Firmado, R – RechazadoString
D.FechaFecha y hora en la que el destinatario ha realizado la acción reflejada en el estado, es decir, firmar el documento o rechazarloString
D.MotivoRechazoTexto descriptivo que indicó el destinatario al rechazar el envíoString

Propiedades query

ParámetroDescripciónTipo de dato
codCó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ámetroDescripciónTipo de dato
OsNameSistema operativo del dispositivo desde el que se obtiene el documento o si se hace desde un navegador, el nombre del mismo.String
OsVersionEstá 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
ModelCuando 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
UsernameEn algunos dispositivos es posible obtener el username del mismo, por ejemplo: “iPhone de Sandra”String
DeviceIDAl 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ámetroDescripción
codCó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ámetroDescripciónTipo de dato
OrdenOrden de la imagen dentro del documento final que se construirá para el documento adjunto.Byte
IdDocAdjuntoIdentificador numérico del documento adjunto cuyo valor se habrá obtenido al recuperar la información mediante el servicio web Sending/codEntero 32 bits
NumFotosNú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
ImagenCodificación en un string en formato Base64 de la imagen.String
ArchivoNombre del archivo de la imagenString

Parámetros query

ParámetroDescripciónTipo de dato
codCó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ámetroDescripciónTipo de dato
OperaciónIndica la operación seleccionada por el destinatario. Valores posibles: F – Firmar, R - RechazarString
DatoAuxiliarDependiendo del tipo de operación, esta propiedad contendrá una información u otra:String
-          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
OsNameSistema operativo del dispositivo desde el que se firma o rechaza el documento o si se hace desde un navegador, el nombre del mismo.String
OsVersionEstá 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
ModelCuando 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
UsernameEn algunos dispositivos es posible obtener el username del mismo, por ejemplo: “iPhone de Sandra”String
DeviceIDAl 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ámetroDescripciónTipo de dato
codCó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
200 Operación correcta
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ámetros query

 

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

 

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/…

 

/Subscribe

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ámetroDescripciónTipo de dato
UrlIndica la url del WebHook donde se enviarán los datos de los eventos generadosString
EventosEs 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ámetroDescripciónTipo de dato
eventoIndica 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

 

 

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:

var accessor = {

consumerSecret : secret_key

};

var parameters = {

};

var message = {

method : ‘GET‘,

action : url,

parameters : [[‘oauth_consumer_key’, consumer_key], [‘oauth_nonce’, OAuth.nonce(6)], [‘oauth_signature_method’, ‘HMAC-SHA1’], [‘oauth_timestamp’, OAuth.timestamp()], [‘oauth_version’, ‘1.0’]]

};

 

//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)