Descripción general del API de efirma GO

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 GO 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 GO 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 GO 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 asociada al cliente (tarifa_cliente). Por defecto Tarifa Personal (hasta 5 documentos). Para más información sobre las tarifas, consultar Planes eFirma GO

• Envíar email de bienvenida (enviar_bienvenida)

Configurar la cuenta del cliente para que permmita enviar las notificaciones de creación de cuenta para un destinatario en caso de que no exista al realizar el proceso

• Nombre del documento (nombre_documento)

Nombre del documento que se muestra a los destinatarios.

• Tipo de seguridad (tipo_seguridad). Por defecto "basica"

Basica: No requiere validación por OTP

Avanzada: Require validación por OTP al firmar el documento po parte del destinatario

• Revisa plan (revisa_plan). Por defecto 0

Incrementa el contador de documentos consumidos en la tarifa del cliente

El Código Seguro de Verificación (CSV) permite a cualquier persona acceder al documento. Se imprime en el lateral de cada página.

• Tipo de documento (tipo_documento)

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

• Campos clave del documento (campos_clave)

Introduce parámetros de forma clave/valor que puedan identificar al documento.

• Mensaje privado (mensaje_privado)

Escribe un mensaje privado que le llegará a todos los destinatarios que participan en el documento

• Enviar documento firmado a la URL de respuesta(enviar_url_respuesta)

Configurar si se desea recibir el documento firmado cuando se haya completado el proceso a la URL de respuesta proporcionad por el desarrollador (por defecto se enviará siempre)

• 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 destinatarios que actúan como una entidad:

• Nombre del bloque (nombre_bloque): Nombre para darle sentido al conjunto de destinatarios. Por ejemplo: Bloque empresa, bloque empleado...
• Tipo del bloque (tipo_bloque): Define el tipo de destinatarios que contiene el bloque. Puede ser 'firma' para definir los firmantes, 'revision' para los revisores o 'copia' para los usuarios que vayan en copia en el documento
• Mínimo (minimo): Mínimo número de destinatarios 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 destinatarios que componen el bloque.
• Orden (orden): Determina la posición que tendrá dicho bloque con respecto al resto de destinatarios 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.
• Destinatarios (destinatarios). Listado de destinatarios (firmantes, revisores, copia) que pertenecen al bloque. De cada destinatario se solicitará:
• Nombre (nombre_destinatario): Nombre del destinatario.
• Apellido 1 (apellido1_destinatario): Primer apellido del destinatario.
• Apellido 2 (apellido2_destinatario): Segundo apellido del destinatario.
• Email (email_destinatario): Correo electrónico del destinatario. Este campo es único, por lo que no puede estar repetido en otros destinatarios dentro de la misma empresa cliente.
• Identificador (identificador_destinatario): Identificador único para facilitar su búsqueda desde API o Web.
• Teléfono (telefono_destinatario): Teléfono móvil del destinatario. Este teléfono es el que usa para verificar la cuenta del destinatario. Sin la verificación no se puede tener acceso a los documentos.
• Mensaje privado (mensaje_privado): Escribe un mensaje privado visible solamente para el destinatario asignado
• Enviar notificación (enviar_notificacion)

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

• Enviar resumen (enviar_resumen)

Indica si se enviará una sola notificación al destinatario 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.

• Firma Web (terminal_web)

Indica si este destinatario puede acceder y firmar desde la plataforma web de efirma GO.

• Dispositivo personal (terminal_personal)

Indica si este destinatario puede acceder y firmar desde la aplicación de efirma GO.

• Terminal corporativo (terminal_corporativo)

Indica si este destinatario va a tener que firmar desde el dispositivo de un usuario.

• Medio de comunicación (medio_comunicacion)

Medio por donde se enviará el documento a firmar. Puede optar los valores 'email' o 'sms' (por defecto 'email')

• Firma múltiple (firma_multiple)

Indica las posiciones que de las firmas: (solamente para los bloques de tipo "firma")

• 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 destinatarios no esté dado de alta en efirma GO, éste se dará de alta de forma automática y transparente.

• Id Operación (id_operacion)

Código generado por efirma GO 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 destinatarios.

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",
   "nombre_documento": "Nómina empleado 300",
   "tarifa_cliente": "Tarifa Personal",
   "tipo_documento": "Nómina mes de enero",
   "campos_clave": {
   		"clave1": "valor1",
   		"clave2:" "valor",
   },
   "notificar_cada":"-1",
   "origen": "API Cliente",
   "mensaje_privado": "Mensaje privado",
   "bloques": [
      {
         "nombre_bloque": "Firmantes grupo A",
         "minimo": "1",
         "orden": "1",
		 "tipo_bloque": "firma",
         "destinatarios": [
            {
               "nombre_destinatario": "Jesús Sánchez Alonso",
			   "apellido1_destinatario": "Sánchez",
			   "apellido2_destinatario": "Jesús Sánchez Alonso",
               "email_destinatario": "jesus@e-firma.com",
               "telefono_destinatario": "+32677777777",
			   "enviar_notificacion":"si",
			   "enviar_resumen":"no",
			   "terminal_web": 1,
			   "terminal_personal": 1,
			   "terminal_corporativo":1,
				"firma_multiple": [
					{
						"pagina": "1",
						"coordenada_x": "149",
						"coordenada_y": "950"
					}
				]
            }
         ]
      },
      {
         "nombre_bloque": "Revisores grupo B",
         "minimo": "1",
		 "tipo_bloque": "revision",
         "orden": "1",
         "destinatarios": [
            {
               "nombre_destinatario": "Máximo",
			   "apellido1_destinatario": "López",
			   "apellido2_destinatario": "Bonillo",
               "email_destinatario": "maximo@e-firma.com",
               "telefono_destinatario": "+32677777777",
			   "enviar_notificacion":"si",
			   "enviar_resumen":"no",
            }
         ]
      }
   ]
}

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

El servicio de efirma GO enviará una petición POST a la URL de la empresa integradora con los parámetros de entrada descritos en este apartado. Además, la URL configurada por el desarrollador deberá de devolver una respuesta con los parámetros de salida. En caso de que la URL proporcionada no devuelva los parámetros de salida correctos, se le avisará al desarrollador vía email del error.

Parámetros de entrada

Parámetros de salida

Códigos de operación

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: la private key del desarrollador (private_key), el cif del cliente (cif_cliente), el cif del desarrollador (cif_desarrollador) y mínimo uno de los tres campos de búsqueda (campos_clave, id_operacion o CSV) tal y como se muestra a continuación:

{
	"private_key":"Zj9xyAidNJAz3d9",
	"cif_desarrollador": "815947823F",
	"cif_cliente":"S1169730G",
	"CSV": "243246634711319",
	"id_operacion": "243246634711319",
	"campos_clave": {
		"clave1" : "value1",
		"clave2" : "value2"
	}
}

Respuesta recibida

{
"estado_operacion":"0000",
"mensaje_operacion":"El proceso se ha realizado con éxito",
"listado_documentos":[
	{
        "url_documento": "https://app.efirma.es/viewer?...",
        "url_certificado": "http://app.efirma.es/viewer?...",
        "campos_clave": [
        	{
        		"clave1": "value1"
        	}
        ],
        "CSV": "AAAA-BBBB-CCCC-DDDD-EEEE",
        "id_operacion": "11111"
	},
	{
        "url_documento": "https://app.efirma.es/viewer?...",
        "url_certificado": "http://app.efirma.es/viewer?...",
        "campos_clave": [
        	{
        		"clave1": "value1"
        	}
        ],
        "CSV": "AAAA-BBBB-CCCC-DDDD-EEEE",
        "id_operacion": "11111"
	},
	{
        "url_documento": "https://app.efirma.es/viewer?...",
        "url_certificado": "http://app.efirma.es/viewer?...",
        "campos_clave": [
        	{
        		"clave1": "value1"
        	}
        ],
        "CSV": "AAAA-BBBB-CCCC-DDDD-EEEE",
        "id_operacion": "11111"
	}
],
"siguiente_pagina": "https://api.efirma.es/descargar_documentos_firmados/2",
"total_busqueda": "10"
}

Zona de pruebas

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", el servicio de efirma GO realizará una petición POST 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) que puede ser un array de id de operaciones o un único id_operacion en un string, la Private Key (private_key) y el CIF del cliente (cif_cliente), tal y como se muestra a continuación:

{
"id_operacion":"123456789999999", //Alternativamente también valdría "id_operacion": ["123456789999999", "1122334455"]
"private_key": "123456789123456",
"cif_cliente": "A77445566"
}

Respuesta recibida

[
	{
		"id_operacion":"123456789999999",
		"estado_operacion":"OK",
		"url_documento_firmado": "https://app.efirma.es/..."
		"destinatarios": [
		    {
	      	"nombre_apellidos": "Jesus Demonila",
	      	"email": "jesus@e-firma.com",
	      	"telefono": "+32677777777",
	      	"bloqueado": "0",
	      	"activo": "1",
	      	"firmado": "1",
	      	"tipo": "firmante"
	    	},
	    	{
	      	"nombre_apellidos": "Pedro López J",
	      	"email": "pedro@e-firma.com",
	      	"telefono": "+32667677677",
	      	"bloqueado": "0",
	      	"activo": "1",
	      	"revisado": "1",
	      	"tipo": "revisor"
	    	}
	  	]
	},
	{
		"id_operacion":"1122334455",
		"estado_operacion":"KO",
		"url_documento_firmado": ""
		"destinatarios": [
		    {
	      	"nombre_apellidos": "Jesus Demonila",
	      	"email": "jesus@e-firma.com",
	      	"telefono": "+32677777777",
	      	"bloqueado": "0",
	      	"activo": "1",
	      	"firmado": "1",
	      	"tipo": "firmante"
	    	},
	    	{
	      	"nombre_apellidos": "Pedro López J",
	      	"email": "pedro@e-firma.com",
	      	"telefono": "+32667677677",
	      	"bloqueado": "0",
	      	"activo": "1",
	      	"revisado": "1",
	      	"tipo": "revisor"
	    	}
	  	]
	}
]

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 email (email_firmante) o identificador (identificador_firmante) del firmante a consultar tal y como se muestra a continuación:

{
"private_key":"Zj9xyAidNJAz3d9",
"cif_desarrollador": "815947823F",
"cif_cliente": "S1169730G",
"email_firmante": "firmante@gmail.com"
}

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",
	"telefono":"+12345667",
	"terminal_corporativo":"Si",
	"terminal_web": "Si",
	"terminal_personal": "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 email 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",
"email_firmante": "test@firmante.com",
"cif_cliente": "S1169730G",
"usuario": {
    "email": "pepelopez@gmail.com",
    "nombre": "Pepe",
    "apellido1": "Lopez",
    "apellido2": "Lopez",
    "telefono": "+341456789",
    "terminal_corporativo": "No"
    "terminal_personal": "Si",
    "terminal_web": "No"
}
}

Respuesta recibida

{
"estado_operacion":"0000",
"mensaje_operacion":"El proceso 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 a la URL (https://api.efirma.es/api_get_cliente), donde el parámetro es una variable del tipo JSON (json) con la Private Key (private_key), el CIF del cliente (cif_cliente) a consultar tal y como se muestra a continuación:

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

Respuesta recibida

{
"estado_operacion":"0000",
"mensaje_operacion":"El proceso se ha realizado con éxito.",
"cliente":{
	"cif":"S1169730G",
	"nombre":"Cliente S.L",
	"email":"cliente@test.es",
	"direccion":"Calle Altamira nº1",
	"provincia": "Almería",
	"poblacion": "Almería"
}
}

Zona de pruebas