Descripción general del API de efirma

Efirma proporciona una API mediante un servicio web de tipo REST/JSON, que permite a cualquier aplicación poder gestionar la firma de documentos.

La comunicación se realiza mediante el protocolo cURL en el que siempre se envía un campo con el nombre json, que en ciertas llamadas debe ir acompañado de un campo archivo. El json contiene un parámetro especial llamado private_key, que es proporcionado por efirma y permite identificar al desarrollador que hace la llamada.

La empresa integradora debe disponer de un servicio web en una URL fija con el que efirma pueda comunicarse (recepción de documentos).

Con cada alta de documento se genera un código de operación que identifica al documento en las diferentes llamadas. Una vez que esté firmado completamente el documento, efirma lo devolverá al servicio web de la empresa integradora.

Terminología

JSON: acrónimo de JavaScript Object Notation, es un formato de texto ligero para el intercambio de datos.

• Archivo (archivo)

Documento PDF que se quiere firmar

• JSON (json)
• Private Key (private_key)

Clave que identifica a la empresa integradora y que le permite hacer peticiones a la API. Esta clave es de uso exclusivo y privado.

• Desarrollador (cif_desarrollador)

CIF de la empresa integradora.

• CIF Cliente (cif_cliente)

CIF/NIF del cliente.

• Nombre cliente (nombre_cliente)

Nombre del cliente.

• Email cliente (email_cliente)

Email del cliente.

• Dirección cliente (direccion_cliente)

Dirección del cliente.

• Provincia cliente (provincia_cliente)

Provincia del cliente.

• Población cliente (poblacion_cliente)

Población del cliente.

• Tarifa del cliente (tarifa_cliente)

Tarifa asociada al cliente. Por defecto Tarifa personal (hasta 5 documentos). Para más información sobre las tarifas, consultar Planes eFirma

• Nombre del documento (nombre_documento)

Nombre del documento que se muestra a los firmantes.

• Validación de código por email (codigo_email)

Indica si se desea disponer de un extra de seguridad, consistente en el envío de un código al email de cada firmante con una clave que es solicitada en el momento de la firma.

• Validación de código por SMS (codigo_sms)

Indica si se desea disponer de un extra de seguridad, consistente en el envío de un código al móvil de cada firmante con una clave que es solicitada en el momento de la firma.

• Validación de contraseña (validacion_clave)

Indica si se desea disponer de un extra de seguridad, consistente en la validación de la contraseña del firmante en el momento de la firma.

• Tipo de documento (tipo_documento)

Especifica el tipo de documento. Algunos ejemplos podrían ser: nóminas, LOPD, prevención...

• Período de notificacion (notificar_cada)

Establece el período de notificación en días para enviar una notificación resumen. Si es -1, no se envían notificaciones. Si es 0, se envía en el momento.

• Bloques (bloques)

Un bloque está definido como un conjunto de firmantes que actúan como una entidad:

• Nombre del bloque (nombre_bloque): Nombre para darle sentido al conjunto de firmantes. Por ejemplo: Bloque empresa, bloque empleado...
• Mínimo (minimo): Mínimo número de firmantes que son necesarios para dar por completa la firma de este bloque. Este número deberá ser mayor que 0 y menor o igual al número de firmantes que componen el bloque.
• Orden (orden): Determina la posición que tendrá dicho bloque con respecto al resto de firmantes a la hora de firmar. Este número deberá ser mayor que 0 y menor o igual al número de bloques que se definen para el documento.
• Firmantes (firmantes). Listado de firmantes que pertenecen al bloque. De cada firmante se solicitará:
• Nombre (nombre_firmante): Nombre del firmante.
• Apellido 1 (apellido1_firmante): Primer apellido del firmante.
• Apellido 2 (apellido2_firmante): Segundo apellido del firmante.
• Email (email_firmante): Correo electrónico del firmante. Este campo es único, por lo que no puede estar repetido en otros firmantes dentro de la misma empresa cliente.
• DNI (dni_firmante): Es necesario aportar el documento de identificación de las personas físicas.
• Teléfono (telefono_firmante): Teléfono móvil del firmante. Este teléfono es el que usa para verificar la cuenta del firmante. Sin la verificación no se puede tener acceso a los documentos.
• Dirección (direccion_firmante): Dirección del firmante.
• Número de la dirección (numero_firmante): Número de la dirección del firmante.
• Provincia (provincia_firmante): Provincia del firmante.
• Localidad (municipio_firmante): Localidad del firmante.
• Código postal (codigo_postal_firmante): Código postal del firmante.
• Enviar notificación (enviar_notificacion)

Indica si se enviará una notificación al firmante para hacerle saber que tiene documentos nuevos por firmar.

• Enviar resumen (enviar_resumen)

Indica si se enviará una sola notificación al firmante informándole de que tiene documentos por firmar, de modo contrario se le enviará una notificación informándole de que el presente documento está disponible para su firma.

• Terminal corporativo (terminal_corporativo)

Indica si este firmante va a tener que firmar en el gestor de documentos (nombre_gestor y email_gestor).

• Nombre gestor (nombre_gestor)

Nombre del gestor de documentos.

• Email gestor (email_gestor)

Email del gestor de documentos.

• Firma múltiple (firma_multiple)

Indica las posiciones que de las firmas:

• Página (pagina): Número de la página
• Coordenada X de firma (coordenada_x): El valor debe ir en píxeles.
• Coordenada Y de firma (coordenada_y): El valor debe ir en píxeles.

En el caso en el que alguno de los firmantes no esté dado de alta en efirma, éste se dará de alta de forma automática y transparente.

• Id Operación (id_operacion)

Código generado por efirma que identifica cada una de las peticiones recibidas. Este código es devuelto como parámetro de salida de una operación realizada con éxito.

• Estado operación (estado_operacion)

Identifica mediante el listado de códigos de operación el resultado de la misma, es decir, si se ha realizado con éxito o si ha ocurrido algún error.

• Mensaje operación (mensaje_operacion)

Descripción correspondiente el estado de la operación.

• Archivo firmado (archivo)

Es el archivo físico ya firmado por todos los firmantes.

Parámetros de entrada

TipoFirmaMultiple

Parámetros de salida

Códigos de operación

Ejemplos

Petición de envío

Se envía una petición POST donde los parámetros son: el archivo a firmar (archivo) y una variable del tipo JSON (json) con los datos asociados al documento. Como información complementaria, las coordenadas de firma (campo coordenada_x o coordenada_y) indican dónde irá situada la firma dentro del documento. Las coordenadas deben de ir en formato pixel, acorde con las dimensiones de un documento en formato A4 (210 mm x 297 mm ó 794 px x 1123 px), teniendo en cuenta que la densidad de un documento procesado es de 96 PPI. Ejemplo del JSON a enviar:

{
   "private_key": "123456789123456",
   "cif_desarrollador": "A23433211",
   "nombre_cliente": "Cliente A",
   "cif_cliente": "A77445566",
   "email_cliente": "cliente@cliente.com",
   "direccion_cliente": "Calle de la Victoria nº5",
   "provincia_cliente": "Sevilla",
   "poblacion_cliente": "La Lantejuela",
   "tarifa_cliente": "Tarifa Personal",
   "nombre_documento": "Nómina empleado 300",
   "codigo_email": "si",
   "codigo_sms": "si",
   "validacion_clave": "no",
   "tipo_documento": "Nómina mes de enero",
   "notificar_cada":"-1"
   "coordenada_x":"2",
   "coordenada_y":"3",
   "bloques": [
      {
         "nombre_bloque": "Firmantes grupo A",
         "minimo": "1",
         "orden": "1",
         "firmantes": [
            {
               "nombre_firmante": "Jesús Sánchez Alonso",
			   "apellido1_firmante": "Sánchez",
			   "apellido2_firmante": "Jesús Sánchez Alonso",
               "email_firmante": "jesus@e-firma.com",
               "dni_firmante": "77777777A",
               "telefono_firmante": "+32677777777",
			   "direccion_firmante":"Plaza de la Victoria",
			   "numero_firmante":"5",
			   "provincia_firmante":"Almería",
			   "municipio_firmante":"Almería",
			   "codigo_postal_firmante":"04006",
			   "enviar_notificacion":"si",
			   "enviar_resumen":"no",
			   "terminal_corporativo":1
            }
         ]
      },
      {
         "nombre_bloque": "Firmantes grupo B",
         "minimo": "1",
         "orden": "1",
         "firmantes": [
            {
               "nombre_firmante": "Máximo",
			   "apellido1_firmante": "López",
			   "apellido2_firmante": "Bonillo",
               "email_firmante": "maximo@e-firma.com",
               "dni_firmante": "44444444A",
               "telefono_firmante": "+32667677677",
			   "coordenada_x":"2",
			   "coordenada_y":"3",
               "telefono_firmante": "+32677777777",
			   "direccion_firmante":"Plaza de la Derrota",
			   "numero_firmante":"2",
			   "provincia_firmante":"Granada",
			   "municipio_firmante":"Granada",
			   "codigo_postal_firmante":"18070",
			   "enviar_notificacion":"si",
			   "enviar_resumen":"no",
			   "firma_multiple":[
			   		{
			   			"pagina":"1",
			   			"coordenada_x":"100",
			   			"coordenada_y":"100"
					},
					{
			   			"pagina":"2",
			   			"coordenada_x":"300",
			   			"coordenada_y":"300"
					}
				]
            }
         ]
      }
   ]
}

Respuesta recibida

{
"id_operacion":"123456789999999",
"estado_operacion":"0000",
"mensaje_operacion":"El proceso de creación del documento se ha realizado con éxito."
}

Zona de pruebas

Parámetros de entrada

Parámetros de salida

Códigos de operación

Ejemplos

Petición de envío

Se envía una petición POST, donde los parámetros son: el archivo firmado (archivo) y una variable del tipo JSON (json) con los datos asociados al documento, tal y como se muestra a continuación:

{
"id_operacion":"123456789999999"
}

Respuesta recibida

{
"id_operacion":"123456789999999",
"estado_operacion":"OK"
}

Parámetros de entrada

Parámetros de salida

Códigos de operación

En caso de que el estado de la operación sea "OK", se realiza una petición a la URL configurada sobre dicho cliente, devolviendo el id_operacion y el archivo firmado.

Ejemplos

Petición de envío

Se envía una petición POST, donde el parámetro es una variable del tipo JSON (json) con el ID de operación (id_operacion), la Private Key (private_key) y el CIF del cliente (cif_cliente), tal y como se muestra a continuación:

{
"id_operacion":"123456789999999",
"private_key": "123456789123456",
"cif_cliente": "A77445566"
}

Respuesta recibida

{
"id_operacion":"123456789999999",
"estado_operacion":"OK",
"firmantes": [
    {
      "dni": "10929181H",
      "nombre_apellidos": "Jesús Sánchez Alonso",
      "email": "jesus@e-firma.com",
      "telefono": "+32677777777",
      "bloqueado": "0",
      "activo": "1",
      "firmado": "1"
    },
    {
      "dni": "X2430285J",
      "nombre_apellidos": "Máximo López Bonillo",
      "email": "maximo@e-firma.com",
      "telefono": "+32667677677",
      "bloqueado": "0",
      "activo": "1",
      "firmado": "1"
    }
  ]
}

Zona de pruebas

Parámetros de entrada

Parámetros de salida

Códigos de operación

Ejemplos

Petición de envío

Se envía una petición POST a la URL (https://api.efirma.es/api_get_firmante), donde el parámetro es una variable del tipo JSON (json) con la Private Key (private_key), el CIF del cliente (cif_cliente) y el NIF del firmante a consultar (nif_firmante) tal y como se muestra a continuación:

{
"private_key":"Zj9xyAidNJAz3d9",
"cif_desarrollador": "815947823F",
"cif_cliente": "S1169730G",
"nif_firmante": "D52743382"
}

Respuesta recibida

{
"estado_operacion":"0000",
"mensaje_operacion":"El proceso se ha realizado con éxito.",
"usuario":{
	"nombre":"Pedro",
	"apellido1":"José",
	"apellido2":"Ramón",
	"email":"usuario@test.com",
	"nif":"D52743382",
	"telefono":"+12345667",
	"direccion":"C/ Gran Vía",
	"numero":"1",
	"provincia":"Madrid",
	"localidad":"Madrid",
	"codigo_postal":"1234",
	"terminal_corporativo":"Si",
}
}

Zona de pruebas

Parámetros de entrada

Parámetros de salida

Códigos de operación

Ejemplos

Petición de envío

Se envía una petición POST a la URL (https://api.efirma.es/api_actualizar_firmante), donde el parámetro es una variable del tipo JSON (json) con la Private Key (private_key), el CIF del cliente (cif_cliente), el NIF del firmante a editar (en caso e que no exista el firmante se creará uno nuevo con los datos especificados) y otra variable del tipo JSON (json) con los datos princiaples del usuario donde el nombre y el email son obligatorios:

{
"private_key":"Zj9xyAidNJAz3d9",
"cif_desarrollador": "815947823F",
"cif_cliente": "S1169730G",
"nif_firmante": "17702970P",
"usuario": {
    "email": "pepelopez@gmail.com",
    "provincia": "Madrid",
    "localidad": "Madrid",
    "codigo_postal": "123456",
    "nombre": "Pepe",
    "apellido1": "Lopez",
    "apellido2": "Lopez",
    "telefono": "+341456789",
    "direccion": "Gran Via",
    "numero": "1",
    "terminal_corporativo": "No"
}
}

Respuesta recibida

{
"estado_operacion":"0000",
"mensaje_operacion":"El proceso se ha realizado con éxito.",
"usuario": {
    "nombre": "Pepe",
    "apellido1": "Lopez",
    "apellido2": "Lopez",
    "email": "pepelopez@gmail.com",
    "nif": "17702970P",
    "telefono": "+341456789",
    "direccion": "Gran Via",
    "numero": "1",
    "codigo_postal": "123456",
    "terminal_corporativo": "No"
    "provincia": "Madrid",
    "localidad": "Madrid"
}
}

Zona de pruebas