API efirma GO
Introducción a la API
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)
- JSON (json)
- Private Key (private_key)
- Desarrollador (cif_desarrollador)
- CIF Cliente (cif_cliente)
- Nombre cliente (nombre_cliente)
- Email cliente (email_cliente)
- Dirección cliente (direccion_cliente)
- Provincia cliente (provincia_cliente)
- Población cliente (poblacion_cliente)
- Tarifa del cliente
- Envíar email de bienvenida (enviar_bienvenida)
- Nombre del remitente (nombre_remitente)
- Email del remitente (email_remitente)
- Nombre del documento (nombre_documento)
- Tipo de seguridad (tipo_seguridad). Por defecto "basica"
- Revisa plan (revisa_plan). Por defecto 0
- Tipo de documento (tipo_documento)
- Campos clave del documento (campos_clave)
- Mensaje general (mensaje_general)
- Enviar documento firmado a la URL de respuesta(enviar_url_respuesta)
- Período de notificacion (notificar_cada)
- Bloques (bloques)
- 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)
- Enviar resumen (enviar_resumen)
- Firma Web (terminal_web)
- Dispositivo personal (terminal_personal)
- Terminal corporativo (terminal_corporativo)
- Medio de comunicación (medio_comunicacion)
- Verificación de identidad por sms (verificacion_identidad_sms_activo)
- Teléfono de verificación de identidad (telefono_verificacion_identidad)
- Verificación de identidad por código (verificacion_identidad_codigo_activo)
- Código de verificación de identidad (codigo_verificacion_identidad)
- Firma múltiple (firma_multiple)
- 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.
- Id Operación (id_operacion)
- Estado operación (estado_operacion)
- Mensaje operación (mensaje_operacion)
- Archivo firmado (archivo)
Documento PDF que se quiere firmar
Clave que identifica a la empresa integradora y que le permite hacer peticiones a la API. Esta clave es de uso exclusivo y privado.
CIF de la empresa integradora.
CIF/NIF del cliente.
Nombre del cliente.
Email del cliente.
Dirección del cliente.
Provincia del cliente.
Población 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
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 remitente que estará ligado al documento
Email del remitente que estará ligado al documento
Nombre del documento que se muestra a los destinatarios.
Basica: No requiere validación por OTP
Avanzada: Require validación por OTP al firmar el documento po parte del destinatario
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.
Especifica el tipo de documento. Algunos ejemplos podrían ser: nóminas, LOPD, prevención...
Introduce parámetros de forma clave/valor que puedan identificar al documento.
Escribe un mensaje privado que le llegará a todos los destinatarios que participan en el documento
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)
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.
Un bloque está definido como un conjunto de destinatarios que actúan como una entidad:
Indica si se enviará una notificación al destinatario para hacerle saber que tiene documentos nuevos por firmar.
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.
Indica si este destinatario puede acceder y firmar desde la plataforma web de efirma GO.
Indica si este destinatario puede acceder y firmar desde la aplicación de efirma GO.
Indica si este destinatario va a tener que firmar desde el dispositivo de un usuario.
Medio por donde se enviará el documento a firmar. Puede optar los valores 'email' o 'sms' (por defecto 'email')
Para asegurarse de que accede al documento la persona correcta, se enviará por SMS un código al móvil especificado
Teléfono del destinatario al que le llegará el SMS con el código de verificación de identidad
Introduzca un código que debe de proporcionar al destinatario para que acceda al documento
Código de verificación de identidad para que el destinatario acceda al documento
Indica las posiciones que de las firmas: (solamente para los bloques de tipo "firma")
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.
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.
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.
Descripción correspondiente el estado de la operación.
Es el archivo físico ya firmado por todos los destinatarios.
API efirma GO
WS Envío de documentos (https://api.efirma.es/enviar_documento)
Parámetros de entrada
Nombre del campo | Tipo de dato | Obligatorio | ||||
---|---|---|---|---|---|---|
archivo | Archivo | Sí | ||||
json | Estructura JSON formada por los campos mostrados a continuación | Sí | ||||
private_key | Varchar(255) | Sí | ||||
cif_desarrollador | Varchar(255) | Sí | ||||
origen | Varchar(255) | No | ||||
nombre_cliente | Varchar(255) | Sí | ||||
cif_cliente | Varchar(255) | Sí | ||||
email_cliente | Varchar(255) | Sí | ||||
direccion_cliente | Varchar(255) | No | ||||
provincia_cliente | Varchar(255) | No | ||||
poblacion_cliente | Varchar(255) | No | ||||
tarifa_cliente | Varchar(255) | No | ||||
enviar_bienvenida | Boolean | No | ||||
nombre_remitente | Boolean | No | ||||
email_remitente | Boolean | No | ||||
nombre_documento | Varchar(255) | No | ||||
tipo_seguridad | Varchar(255) | No | ||||
revisa_plan | Boolean | No | ||||
tipo_documento | Varchar(255) | No | ||||
campos_clave | Objeto con clave => valor | No | ||||
mensaje_general | Varchar(255) | No | ||||
enviar_url_respuesta | Boolean | No | ||||
bloques | Array con el número de bloques, de los que se solicitarán los datos | Sí | ||||
Nombre del campo | Tipo de dato | Obligatorio | ||||
nombre_bloque | Varchar(255) | No | ||||
tipo_bloque | Varchar(255) | Si | ||||
minimo | Entero | Sí | ||||
orden | Entero | Sí | ||||
destinatarios | Array con los destinatarios, de estos se solicitarán los datos | Sí |
||||
Nombre del campo | Tipo de datos | Obligatorio | ||||
nombre_destinatario | Varchar(255) | Sí | ||||
apellido1_destinatario | Varchar(255) | No | ||||
apellido2_destinatario | Varchar(255) | No | ||||
email_destinatario | Varchar(255) | Sí | ||||
identificador_destinatario | Varchar(255) | No | ||||
mensaje_privado | Varchar(255) | Sí | ||||
telefono_destinatario | Varchar(12) | No | ||||
medio_comunicacion | Varchar(255) | No | ||||
verificacion_identidad_sms_activo | Int(1) | No | ||||
telefono_verificacion_identidad | Varchar(255) | No | ||||
verificacion_identidad_codigo_activo | Int(1) | No | ||||
codigo_verificacion_identidad | Varchar(255) | No | ||||
enviar_notificacion | Varchar(255) | No | ||||
enviar_resumen | Varchar(255) | No | ||||
terminal_web | Int(1) | No | ||||
terminal_personal | Int(1) | No | ||||
terminal_corporativo | Int(1) | No | ||||
firma_multiple | Array[TipoFirmaMultiple] | No |
||||
email_gestor | Varchar(255) | No |
||||
nombre_gestor | Varchar(255) | No |
TipoFirmaMultiple
Nombre del campo | Tipo de dato | Obligatorio |
---|---|---|
pagina | Entero | Si |
coordenada_x | Entero | Sí |
coordenada_y | Entero | Sí |
Parámetros de salida
Nombre del campo | Tipo de dato | Obligatorio |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | Sí |
id_operacion | Varchar(255) | No |
estado_operacion | Varchar(255) | Sí |
mensaje_operacion | Varchar(255) | Sí |
Códigos de operación
Estado de operación | Mensaje de la operación |
---|---|
0000 | La operación fue registrada con éxito. |
0001 | No se ha podido establecer conexión con efirma GO. |
0002 | La private key no es válida. |
0003 | Debe de indicar un CIF y email correcto para identificar al cliente. |
0004 | El formato pdf que está subiendo no cumple con el estándar. |
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 destinatarios. |
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 destinatarios. |
0011 | El valor “nombre_destinatario” no es válido. |
0014 | El valor “email_destinatario” no es válido. |
0016 | El valor “telefono_destinatario” 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 o la firma múltiple no es correcta. |
0026 | El valor identificador que ha introducido pertenece a otro usuario y podría dar conflictos. |
0027 | El valor telefono_destinatario es obligatorio para firmas avanzadas. |
0028 | El valor email introducido pertenece a otro usuario y podría causar conflictos. |
0029 | El valor email que ha introducido ya está registrado en la plataforma. |
0030 | La tarifa introducida no existe. |
0031 | Uno de los campos introducido no es correcto. Revise la documentación. |
0032 | El valor tipo_bloque que ha introducido no es válido. Revise la documentación. |
0033 | El cliente se encuentra dado de baja. |
0034 | El cliente se encuentra no se encuentra activo. |
0035 | Debe de indicar los campos email_gestor y nombre_gestor. |
0500 | El servicio de efirma GO se encuentra temporalmente inactivo. |
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
API efirma GO
WS Recepción de documentos (URL proporcionada por la empresa integradora a efirma GO)
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
Nombre del campo | Tipo de dato | Obligatorio |
---|---|---|
archivo | Archivo | Sí |
json | Estructura JSON formada por los campos mostrados a continuación | Sí |
id_operacion | Varchar(255) | Sí |
estado | Varchar(255) | Sí |
Parámetros de salida
Nombre del campo | Tipo de dato | Obligatorio |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | Sí |
id_operacion | Varchar(255) | Sí |
estado_operacion | Varchar(255) | Sí |
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 |
API efirma
WS Descarga de documentos (https://api.efirma.es/descargar_documentos/{n_pagina})
Parámetros de entrada
Nombre del campo | Tipo de dato | Obligatorio | ||
---|---|---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | Sí | ||
private_key | Varchar(255) | Sí | ||
cif_desarrollador | Varchar(255) | Sí | ||
cif_cliente | Varchar(255) | Sí | ||
campos_clave | Objeto con clave => valor | No | ||
id_operacion | Array / Varchar(255) | No | ||
CSV | Varchar(255) | No | ||
descargado | Boolean | No | ||
estados_documento | Estructura JSON formada por los campos mostrados a continuación | No | ||
firmado | Boolean | No | ||
anulado | Boolean | No | ||
rechazado | Boolean | No |
Parámetros de salida
Nombre del campo | Tipo de dato | |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | |
mensaje_operacion | Varchar(255) | |
estado_operacion | Varchar(255) | |
listado_documentos | Estructura Array formada por los campos mostrados a continuación | |
Nombre del campo | Tipo de dato | |
estado | Varchar(255) | |
destinatarios | Array | |
nombre_documento | Varchar(255) | |
url_documento | Varchar(255) | |
url_certificado | Varchar(255) | |
id_operacion | Varchar(255) | |
campos_clave | Objeto con clave => valor | |
CSV | Varchar(255) | |
siguiente_pagina | Varchar(255) | |
total_busqueda | Entero |
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 | El cliente no es válido. |
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). Se podrá especificar los siguientes filtros: (id_operacion) que puede ser un array de id de operaciones o un único id_operacion en un string, (campos_clave) una serie de claves/valor que puedan identificar al documento, (csv) un código de verificación, (descargado) aquellos documentos que hayan sido descargado o no por el desarrollador. Además se podrá filtrar el estado del documento (estados_documento) queriendo obtener aquellos documentos firmados, anulados y/o rechazados. Si no se especifica ningún filtro en (estados_documento) obtendrá todos los estados (FIRMADO, RECHAZADO, ANULADO y EN PROCESO)
{ { "private_key":"Zj9xyAidNJAz3d9", "cif_desarrollador":"815947823F", "cif_cliente":"S1169730G", "descargado":0, "estados_documento": { "firmado":1, "anulado":1, "rechazado":1 } } //Recoge tanto firmados, anulados y rechazados { "private_key":"Zj9xyAidNJAz3d9", "cif_desarrollador":"815947823F", "cif_cliente":"S1169730G", "descargado":0, "estados_documento": { "firmado":1 } } //Recoge solamente firmados { "private_key":"Zj9xyAidNJAz3d9", "cif_desarrollador":"815947823F", "cif_cliente":"S1169730G", "descargado":0, "estados_documento": { } //Recoge todos los estados } { "private_key":"Zj9xyAidNJAz3d9", "cif_desarrollador": "815947823F", "cif_cliente":"S1169730G", "descargado": "0", "csv": "123456", "id_operacion": "123456", //Alternativamente también valdría "id_operacion": ["123456789999999", "1122334455"] "campos_clave": { "clave1" : "value1", "clave2" : "value2", } "estados_documento": { "firmado":1 } //Recoge los firmados que cumplan las condiciones de campos_clave, csv e id_opracion } }
Respuesta recibida
{ "estado_operacion":"0000", "mensaje_operacion":"El proceso se ha realizado con éxito", "listado_documentos":[ { "estado": "FIRMADO", "destinatarios": [ { "nombre_apellidos": "DESTINATARIO 1", "email": "destinatario@email.com", "telefono": "+123456789", "bloqueado": 0, "activo": 1, "tipo": "Firmante", "firmado": 0 } ], "nombre_documento": "pedido.pdf", "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" }, { "estado": "RECHAZADO", "destinatarios": [ { "nombre_apellidos": "DESTINATARIO 1", "email": "destinatario@email.com", "telefono": "+123456789", "bloqueado": 0, "activo": 1, "tipo": "Firmante", "firmado": 0 } ], "nombre_documento": "descarga.pdf", "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" }, { "estado": "ANULADO", "destinatarios": [ { "nombre_apellidos": "DESTINATARIO 1", "email": "destinatario@email.com", "telefono": "+123456789", "bloqueado": 0, "activo": 1, "tipo": "Firmante", "firmado": 0 } ], "nombre_documento": "efirma.pdf", "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" }, { "estado": "EN PROCESO", "destinatarios": [ { "nombre_apellidos": "DESTINATARIO 1", "email": "destinatario@email.com", "telefono": "+123456789", "bloqueado": 0, "activo": 1, "tipo": "Firmante", "firmado": 0 } ], "nombre_documento": "api.pdf", "url_documento": "https://app.efirma.es/viewer?...", "url_certificado": "http://app.efirma.es/viewer?...", "campos_clave": [ { "clave1": "value1" } ], "CSV": "AAAA-BBBB-CCCC-DDDD-KKKK", "id_operacion": "115111" } ], "siguiente_pagina": "https://api.efirma.es/descargar_documento/2", "total_busqueda": "10" }
Zona de pruebas
API efirma
WS Marcar documento como descargado (https://api.efirma.es/marcar_documento_descargado)
Parámetros de entrada
Nombre del campo | Tipo de dato | Obligatorio | ||
---|---|---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | Sí | ||
private_key | Varchar(255) | Sí | ||
cif_desarrollador | Varchar(255) | Sí | ||
cif_cliente | Varchar(255) | Sí | ||
id_operacion | Array / Varchar(255) | Sí |
Parámetros de salida
Nombre del campo | Tipo de dato | |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | |
mensaje_operacion | Varchar(255) | |
estado_operacion | Varchar(255) |
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 | El cliente no es válido. |
Ejemplos
Petición de envío
Si desea marcar el documento como 'descargado' deberá de realizar una segunda a https://api.efirma.es/marcar_documento_descargado con los parámetros indicando además en la petición el campo (id_operacion) con un array de id de operaciones o un único id_operacion en un string
{ "private_key":"Zj9xyAidNJAz3d9", "cif_desarrollador": "815947823F", "cif_cliente":"S1169730G", "id_operacion": "123456", //Alternativamente también valdría "id_operacion": ["123456789999999", "1122334455"] }
Respuesta recibida
{ "estado_operacion":"0000", "mensaje_operacion":"El proceso se ha realizado con éxito" }
Zona de pruebas
API efirma
WS Descarga de documentos firmados (https://api.efirma.es/descargar_documentos_firmados/{n_pagina})
Parámetros de entrada
Nombre del campo | Tipo de dato | Obligatorio |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | Sí |
private_key | Varchar(255) | Sí |
cif_desarrollador | Varchar(255) | Sí |
cif_cliente | Varchar(255) | Sí |
campos_clave | Objeto con clave => valor | No |
id_operacion | Varchar(255) | No |
CSV | Varchar(255) | No |
Parámetros de salida
Nombre del campo | Tipo de dato | |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | |
mensaje_operacion | Varchar(255) | |
estado_operacion | Varchar(255) | |
listado_documentos | Estructura Array formada por los campos mostrados a continuación | |
Nombre del campo | Tipo de dato | |
url_documento | Varchar(255) | |
url_certificado | Varchar(255) | |
id_operacion | Varchar(255) | |
campos_clave | Objeto con clave => valor | |
CSV | Varchar(255) | |
siguiente_pagina | Varchar(255) | |
total_busqueda | Entero |
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 | El cliente no es válido. |
0004 | Debes de especificar al menos un campo para la búsqueda. |
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
API efirma GO
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 | Sí |
id_operacion | Array / Varchar(255) | Sí |
enviar_url_respuesta | Boolean | No |
private_key | Varchar(255) | Sí |
cif_cliente | Varchar(255) | Sí |
Parámetros de salida
Nombre del campo | Tipo de dato | Obligatorio |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | Sí |
id_operacion | Varchar(255) | Sí |
estado_operacion | Varchar(255) | Sí |
destinatarios | Array | Sí |
url_documento_firmado | Varchar(255) | No |
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 destinatario. |
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
Probar mediante formulario
Datos del documento
Probar mediante petición JSON
Datos del documento
Respuesta
API efirma GO
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 | Sí |
private_key | Varchar(255) | Sí |
cif_desarrollador | Varchar(255) | Sí |
cif_cliente | Varchar(255) | Sí |
identificador_firmante | Varchar(255) | Sí |
email_firmante | Varchar(255) | Sí |
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) | ||||
Varchar(255) | |||||
telefono | Varchar(255) | ||||
terminal_web | Boolean | ||||
terminal_personal | Boolean | ||||
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 correcto para identificar al cliente |
0004 | El cliente no es válido. |
0006 | Debe de indicar un email o identificador del firmante. |
0007 | El formato del email es incorrecto. |
0008 | El usuario no existe. |
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
API efirma GO
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 | Sí | |
private_key | Varchar(255) | Sí | |
cif_desarrollador | Varchar(255) | Sí | |
cif_cliente | Varchar(255) | Sí | |
email_firmante | Varchar(255) | Sí | |
usuario | Estructura JSON formada por los campos mostrados a continuación | Sí | |
Nombre del campo | Tipo de dato | Obligatorio | |
nombre | Varchar(255) | Si | |
apellido1 | Varchar(255) | No | |
apellido2 | Varchar(255) | No | |
Varchar(255) | Si | ||
telefono | Varchar(255) | No | |
terminal_web | Boolean | No | |
terminal_personal | Boolean | 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) | ||||
Varchar(255) | |||||
telefono | Varchar(255) | ||||
terminal_web | Boolean | ||||
terminal_personal | Boolean | ||||
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 correcto para identificar al cliente |
0004 | El cliente no es válido. |
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. |
0012 | El email introducido ha sido clasificado como inválido. |
0013 | La cuenta del cliente se encuentra dada de baja. |
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
API efirma GO
WS Consultar datos del cliente
Parámetros de entrada
Nombre del campo | Tipo de dato | Obligatorio |
---|---|---|
json | Estructura JSON formada por los campos mostrados a continuación | Sí |
private_key | Varchar(255) | Sí |
cif_desarrollador | Varchar(255) | Sí |
cif_cliente | Varchar(255) | Sí |
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) | ||||
cliente | Estructura JSON formada por los campos mostrados a continuación | ||||
Nombre del campo | Tipo de dato | ||||
cif | Varchar(255) | ||||
nombre | Varchar(255) | ||||
Varchar(255) | |||||
direccion | Varchar(255) | ||||
provincia | Varchar(255) | ||||
poblacion | Varchar(255) |
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 identificar al cliente |
0004 | El cliente no es válido. |
0005 | El cliente no existe. |
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" } }