API efirma go

Introducción a la API

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.

API efirma

WS Envío de documentos (https://api.efirma.es/enviar_documento)

Parámetros de entrada
Nombre del campo Tipo de dato Obligatorio
archivo Archivo
json Estructura JSON formada por los campos mostrados a continuación
private_key Varchar(255)
cif_desarrollador Varchar(255)
origen Varchar(255) No
nombre_cliente Varchar(255)
cif_cliente Varchar(255)
email_cliente Varchar(255)
direccion_cliente Varchar(255) No
provincia_cliente Varchar(255) No
poblacion_cliente Varchar(255) No
tarifa_cliente Varchar(255) No
nombre_documento Varchar(255) No
codigo_email Varchar(255) No
codigo_sms Varchar(255) No
validacion_clave Varchar(255) No
tipo_documento Varchar(255) No
coordenada_x Entero No
coordenada_y Entero No
bloques Array con el número de bloques, de los que se solicitarán los datos
Nombre del campo Tipo de dato Obligatorio
nombre_bloque Varchar(255) No
minimo Entero
orden Entero
firmantes Array con los firmantes, de estos se solicitarán los datos
Nombre del campo Tipo de datos Obligatorio
nombre_firmante Varchar(255)
apellido1_firmante Varchar(255) No
apellido2_firmante Varchar(255) No
email_firmante Varchar(255)
dni_firmante Varchar(9)
telefono_firmante Varchar(12) No
direccion_firmante Varchar(255) No
numero_firmante Varchar(255) No
provincia_firmante Varchar(255) No
municipio_firmante Varchar(255) No
codigo_postal_firmante Varchar(255) No
coordenada_x Entero No
coordenada_y Entero No
enviar_notificacion Varchar(255) No
enviar_resumen Varchar(255) No
terminal_corporativo Int(1) No
nombre_gestor Varchar(255) No
email_gestor Varchar(255) No
firma_multiple Array[TipoFirmaMultiple] No
CC Array con los emails de los usuarios que deseamos que reciban copia NO
Nombre del campo Tipo de dato Obligatorio
email Varchar(255)


TipoFirmaMultiple


Nombre del campo Tipo de dato Obligatorio
pagina Entero Si
coordenada_x Entero
coordenada_y Entero
Parámetros de salida
Nombre del campo Tipo de dato Obligatorio
json Estructura JSON formada por los campos mostrados a continuación
id_operacion Varchar(255) No
estado_operacion Varchar(255)
mensaje_operacion Varchar(255)
Códigos de operación
Estado de operación Mensaje de la operación
0000 El proceso de creación del documento se ha realizado con éxito.
0001 No se ha podido establecer conexión con efirma.
0002 La private key no es válida.
0003 El cliente no existe.
0004 El archivo no es accesible.
0005 El formato del archivo no es válido o no es legible. Compruebe que no está protegido por contraseña y que sea un archivo PDF.
0006 No se ha podido descargar el documento.
0007 No se ha aportado información de bloques de firmantes.
0008 El valor “mínimo” de un bloque no es válido.
0009 El valor “orden” de un bloque no es válido.
0010 No se ha aportado información de firmantes.
0011 El valor “nombre_firmante” no es válido.
0012 El valor "apellido1_firmante" no es válido.
0013 El valor "apellido2_firmante" no es válido.
0014 El valor “email_firmante” no es válido.
0015 El valor “dni_firmante” no es válido.
0016 El valor “telefono_firmante” no es válido.
0017 El valor “direccion_firmante” no es válido.
0018 El valor “numero_firmante” no es válido.
0019 El valor “provincia_firmante” no es válido.
0020 El valor “municipio_firmante” no es válido.
0021 El valor “codigo_postal_firmante” no es válido.
0022 No se ha podido descargar el JSON enviado.
0023 El cliente indicado no corresponde con la private key insertada.
0024 Las coordenadas indicadas superan los límites del documento. (Coordenada X: valor, Coordenada Y: valor)
0025 La información del cliente, el gestor o la firma múltiple no es correcta.
0026 El valor email_gestor no es válido.
0027 La tarifa introducida no existe
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
Probar mediante petición JSON
Datos del documento
Archivo firmado
Respuesta

API efirma

WS Recepción de documentos (URL proporcionada por la empresa integradora a efirma)

Parámetros de entrada
Nombre del campo Tipo de dato Obligatorio
archivo Archivo
json Estructura JSON formada por los campos mostrados a continuación
id_operacion Varchar(255)
Parámetros de salida
Nombre del campo Tipo de dato Obligatorio
json Estructura JSON formada por los campos mostrados a continuación
id_operacion Varchar(255)
estado_operacion Varchar(255)
Códigos de operación
Estado de operación Mensaje de la operación
OK El proceso de recepción del documento firmado se ha realizado correctamente.
KO No se ha podido realizar la descarga del documento
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"
}

API efirma

WS Consulta de documentos (https://api.efirma.es/consultar_documento)

Parámetros de entrada
Nombre del campo Tipo de dato Obligatorio
json Estructura JSON formada por los campos mostrados a continuación
id_operacion Varchar(255)
private_key Varchar(255)
cif_cliente Varchar(255)
Parámetros de salida
Nombre del campo Tipo de dato Obligatorio
json Estructura JSON formada por los campos mostrados a continuación
id_operacion Varchar(255)
estado_operacion Varchar(255)
firmantes Array
Códigos de operación
Estado de operación Mensaje de la operación
OK El documento se encuentra firmado y se procederá a enviarlo de nuevo.
0001 El id_operacion no es correcto.
0002 El private_key no es correcto.
0003 El cif_cliente no es correcto.
KO El documento aún no se encuentra firmado.
Anulado El documento fue anulado por el cliente.
Rechazado El documento fue rechazado por algún firmante.

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
Probar mediante formulario
Datos del documento
Probar mediante petición JSON
Datos del documento
Respuesta

API efirma

WS Consultar datos del firmante

Parámetros de entrada
Nombre del campo Tipo de dato Obligatorio
json Estructura JSON formada por los campos mostrados a continuación
private_key Varchar(255)
cif_desarrollador Varchar(255)
cif_cliente Varchar(255)
nif_firmante Varchar(255)
Parámetros de salida
Nombre del campo Tipo de dato
json Estructura JSON formada por los campos mostrados a continuación
estado_operacion Varchar(255)
mensaje_operacion Varchar(255)
usuario Estructura JSON formada por los campos mostrados a continuación
Nombre del campo Tipo de dato
nombre Varchar(255)
apellido1 Varchar(255)
apellido2 Varchar(255)
email Varchar(255)
nif Varchar(255)
telefono Varchar(255)
direccion Varchar(255)
numero Varchar(255)
provincia Varchar(255)
localidad Varchar(255)
codigo_postal Varchar(255)
terminal_corporativo Boolean
Códigos de operación
Estado de operación Mensaje de la operación
0000 El proceso se ha realizado con éxito.
0001 No se ha podido descargar el JSON enviado.
0002 La private key no es válida
0003 Debe de indicar un CIF y email correcto para identificar al cliente
0004 El cliente no es válido.
0005 Debe de indicar un NIF correcto para identificar al firmante.
0006 Debes de indicar un correo electrónico para el usuario.
0007 El formato del email es incorrecto.
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
Probar mediante petición JSON
Datos de entrada
Respuesta

API efirma

WS Actualizar datos del firmante

Parámetros de entrada
Nombre del campo Tipo de dato Obligatorio
json Estructura JSON formada por los campos mostrados a continuación
private_key Varchar(255)
cif_desarrollador Varchar(255)
cif_cliente Varchar(255)
nif_firmante Varchar(255)
usuario Estructura JSON formada por los campos mostrados a continuación
Nombre del campo Tipo de dato Obligatorio
nombre Varchar(255) Si
apellido1 Varchar(255) No
apellido2 Varchar(255) No
email Varchar(255) Si
nif Varchar(255) Si
telefono Varchar(255) No
direccion Varchar(255) No
numero Varchar(255) No
provincia Varchar(255) No
localidad Varchar(255) No
codigo_postal Varchar(255) No
terminal_corporativo Boolean No
Parámetros de salida
Nombre del campo Tipo de dato
json Estructura JSON formada por los campos mostrados a continuación
estado_operacion Varchar(255)
mensaje_operacion Varchar(255)
usuario Estructura JSON formada por los campos mostrados a continuación
Nombre del campo Tipo de dato
nombre Varchar(255)
apellido1 Varchar(255)
apellido2 Varchar(255)
email Varchar(255)
nif Varchar(255)
telefono Varchar(255)
direccion Varchar(255)
numero Varchar(255)
provincia Varchar(255)
localidad Varchar(255)
codigo_postal Varchar(255)
terminal_corporativo Boolean
Códigos de operación
Estado de operación Mensaje de la operación
0000 El proceso se ha realizado con éxito.
0001 No se ha podido descargar el JSON enviado.
0002 La private key no es válida
0003 Debe de indicar un CIF y email correcto para identificar al cliente
0004 El cliente no es válido.
0005 Debe de indicar un NIF correcto para identificar al firmante.
0006 Debes de indicar un correo electrónico para el usuario.
0007 El formato del email es incorrecto.
0008 Debes de indicar un nombre al usuario.
0009 Ya existe un usuario con dicho email.
0010 La provincia introducida no se encuentra en la base de datos.
0011 La localidad introducida no se encuentra en la base de datos.
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
Probar mediante petición JSON
Datos de entrada
Respuesta