DOCUMENTACIÓN API efirma Versión 1.0.

Transcripción

1 DOCUMENTACIÓN API efirma Versión 1.0.

2 Cntenid Descripción general del API de efirma... 3 Terminlgía... 3 WS Enví de dcuments... 6 Parámetrs de entrada... 6 Parámetrs de salida... 7 Códigs de peración... 8 Ejempls... 9 Petición de enví... 9 WS Recepción de dcuments Parámetrs de entrada Parámetrs de salida Códigs de peración Ejempls Petición de enví WS Cnsulta de dcuments Parámetrs de entrada Parámetrs de salida Códigs de peración Ejempls Petición de enví WS Eliminar dcument Parámetrs de entrada Parámetrs de salida Códigs de peración Ejempls Petición de enví

3 Descripción general del API de efirma efirma dispne de una API a la que se accede mediante un servici web. Dicha API permite a cualquier aplicación pder gestinar la firma de dcuments. Entre las características de la API, se permite añadir dcuments que han de ser firmads, especificand ls usuaris que han de realizar dicha firma. Entre tras pcines, se pueden elegir el rden en que se firma el dcument pr ls usuaris si es necesari que se envíe un códig de validación pr crre para dcuments de mayr seguridad. Cada alta de dcument dispne de un códig de peración identificativ que puede ser almacenad pr la empresa integradra. Este códig permitirá identificar el dcument en las diferentes llamadas. Una vez que esté firmad cmpletamente el dcument, efirma l envía al servici web de la empresa integradra. Para dar de alta a la empresa integradra es necesari cmunicar a efirma una URL dnde se encntrará el servici web de la empresa integradra. Una vez verificada la URL, se le facilitará a la empresa integradra su privatekey. La cmunicación se realiza mediante prtcl curl, en el que se envían ds camps, archiv y jsn. Terminlgía Archiv (archiv). Dcument PDF que se quiere firmar JSON (jsn). JSON, acrónim de JavaScript Object Ntatin, es un frmat de text liger para el intercambi de dats. Private Key (private_key). Clave que identifica a la empresa integradra cm desarrlladr y que le permite hacer peticines a la API. Esta clave es de us privad y exclusiv Cliente (cif_cliente). CIF de la empresa integradra. Nmbre del dcument (nmbre_dcument). Nmbre que se muestra a ls usuaris firmantes. Terminal prpi(terminal_prpi). Indica si el dcument sól se pdrá firmar en el terminal del usuari. Pr defect esta pción se marca cm 'si'. Terminal empresa (terminal_empresa). Indica si el dcument sól se pdrá firmar en el terminal de la empresa. Pr defect esa pción se marca cm 'n'. Validación de códig pr (cdig_ ). Indica si se desea dispner de un extra de seguridad, cnsistente en el enví de un códig al de cada usuari cn una clave que es slicitada en el mment de la firma. 3

4 Validación de cntraseña (validacin_clave). Indica si se desea dispner de un extra de seguridad, cnsistente en la validación de la cntraseña del usuari en el mment de la firma. Tip de dcument (tip_dcument). Denminación de carácter pcinal que se puede utilizar cm categrización del dcument para pder ser cnsultads desde la platafrma de efirma. Alguns ejempls pdrían ser: nóminas, LOPD, prevención... Crdenada X de firma (crdenada_x). Indica la psición hrizntal de la firma en el dcument. Este valr va junt al tip de dcument indicad, y tiene efect si sl hay un firmante. El valr debe ir en píxeles. Crdenada Y de firma (crdenada_y). Indica la psición vertical de la firma en el dcument. Este valr va junt al tip de dcument indicad, y tendrá efect si sl hay un firmante. El valr debe ir en píxeles. Blques (blques). Un blque está definid cm un cnjunt de firmantes que actúan cm una entidad: Nmbre del blque (nmbre_blque). Denminación de carácter pcinal para darle sentid al cnjunt de firmantes. Pr ejempl: Blque empresa, blque emplead... Mínim (minim): Mínim númer de firmantes que sn necesaris para dar pr cmpleta la firma de este blque. Dich númer deberá ser mayr que 0 y menr igual al númer de firmantes que cmpnen dich blque. Orden (rden): Determina la psición que tendrá dich blque cn respect al rest a la hra de firmar. Dich númer deberá ser mayr que 0 y menr igual al númer de blques que se definen para dich dcument. Firmantes (firmantes). Listad de usuaris que pertenecen a dich blque. De cada firmante se slicitará: Nmbre (nmbre_firmante). Nmbre del firmante Apellid 1 (apellid1_firmante). Primer apellid del firmante Apellid 2 (apellid2_firmante). Segund apellid del firmante ( _firmante). Crre electrónic que es necesari para que efirma pueda acceder a la aplicación móvil. Este camp es únic, pr l que n puede estar repetid en trs usuaris. DNI (dni_firmante). Es necesari aprtar el dcument de identificación de las persnas físicas. Teléfn (telefn_firmante). Teléfn móvil de la persna que va a firmar. Dich teléfn es el que usa para verificar la cuenta del usuari. Sin la verificación n se puede tener acces a ls dcuments. Dirección (direccin_firmante). Dirección del firmante Númer de la dirección (numer_firmante). Númer de la dirección del firmante Prvincia (prvincia_firmante). Prvincia del firmante Lcalidad (lcalidad_firmante). Lcalidad del firmante 4

5 Códig pstal (cdig_pstal_firmante). Códig pstal del firmante Crdenada X de firma (crdenada_x). Indica la psición hrizntal de la firma en el dcument. El valr debe ir en píxeles. Crdenada Y de firma (crdenada_y). Indica la psición vertical de la firma en el dcument. El valr debe ir en píxeles. En el cas en el que algun de ls firmantes n esté dad de alta en efirma, éste se dará de alta de frma autmática y transparente a la empresa integradra. Id Operación (id_peracin). Códig generad pr efirma que identifica cada una de las peticines recibidas desde la empresa integradra. Este códig es devuelt cm parámetr de salida de una peración realizada cn éxit. Estad peración (estad_peracin). Identifica mediante el listad de códigs de peración el resultad de la misma, es decir, si se ha realizad cn éxit si ha currid algún errr. Mensaje peración (mensaje_peracin). Descripción crrespndiente el estad de la peración. Archiv firmad (archiv_firmad). Es el archiv físic ya firmad pr tds ls firmantes. 5

6 WS Enví de dcuments Parámetrs de entrada Nmbre del camp Tip de dat Obligatri archiv Archiv jsn Estructura JSON frmada pr ls camps mstrads a cntinuación private_key Varchar(255) cif_cliente Varchar(255) nmbre_dcument Varchar(255) N terminal_prpi Varchar(255) N terminal_empresa Varchar(255) N cdig_ Varchar(255) N validacin_clave Varchar(255) N tip_dcument Varchar(255) N crdenada_x Enter N crdenada_y Enter N blques Array cn el númer de blques, de ls que se slicitarán ls dats Nmbre del camp Tip de dat Obligatri nmbre_bl que Varchar(255) N minim Enter rden Enter firmantes Array cn ls usuaris que han de firmar, de ests se slicitarán ls dats 6

7 Nmbre del camp Tip de dats Obli gat ri nmbre_firmante Varchar(255) apellid1_firmante apellid2_firmante Varchar(255) N Varchar(255) N _firmante Varchar(255) dni_firmante Varchar(9) telefn_firmante Varchar(12) direccin_firmante numer_firmante prvincia_firmante municipi_firmante Varchar(255) N Varchar(255) N Varchar(255) N Varchar(255) N cdig_pstal_firmante Varchar(255) N crdenada_x Enter N crdenada_y Enter N Parámetrs de salida Nmbre del camp Tip de dat Obligatri jsn Estructura JSON frmada pr ls camps mstrads a cntinuación id_peracin Varchar(255) N estad_peracin Varchar(255) mensaje_peracin Varchar(255) 7

8 Códigs de peración Estad de peración Mensaje de la peración 0000 El prces de creación del dcument se ha realizad cn éxit N se ha pdid establecer cnexión cn e-firmas La private key n es válida El cliente n existe El archiv n es accesible El frmat del archiv n es válid n es legible. Cmpruebe que n está prtegid pr cntraseña y que sea un archiv PDF N se ha pdid descargar el dcument N se ha aprtad infrmación de blques de firmantes El valr mínim de un blque n es válid El valr rden de un blque n es válid N se ha aprtad infrmación de firmantes El valr nmbre_firmante n es válid El valr "apellid1_firmante" n es válid El valr "apellid2_firmante" n es válid El valr _firmante n es válid El valr dni_firmante n es válid El valr telefn_firmante n es válid El valr direccin_firmante n es válid El valr numer_firmante n es válid El valr prvincia_firmante n es válid El valr municipi_firmante n es válid. 8

9 0021 El valr cdig_pstal_firmante n es válid N se ha pdid descargar el JSON enviad El cliente indicad n crrespnde cn la private key insertada Las crdenadas indicadas superan ls límites del dcument. (Crdenada X: valr, Crdenada Y: valr) Ejempls Petición de enví Se envía una petición POST a la URL ( dnde ls parámetrs sn, pr una parte el archiv a firmar (archiv) y pr tra parte una variable del tip JSON (jsn) cn ls dats asciads al dcument. Cm infrmación cmplementaria, cabe destacar que las crdenadas de firma (camp crdenada_x crdenada_y) indican dónde irá situada la firma dentr del dcument. Dichas crdenadas deben de ir en frmat pixel, acrde cn las dimensines de un dcument en frmat A4 (210 mm x 297 mm ó 794 px x 1123 px), teniend en cuenta que la densidad de un dcument prcesad es de 96 PPI. A cntinuación, se muestra un ejempl del JSON a enviar: 9

10 10

11 WS Recepción de dcuments Parámetrs de entrada Nmbre del camp Tip de dat Obligatri archiv_firmad Archiv jsn Estructura JSON frmada pr ls camps mstrads a cntinuación id_peracin Varchar(255) Parámetrs de salida Nmbre del camp Tip de dat Obligatri jsn Estructura JSON frmada pr ls camps mstrads a cntinuación id_peracin Varchar(255) estad_peracin Varchar(255) Códigs de peración Estad de peración Mensaje de la peración OK El prces de recepción del dcument firmad se ha realizad crrectamente. KO N se ha pdid realizar la descarga del dcument 11

12 Ejempls Petición de enví Se envia una petición POST, dnde ls parámetrs sn pr una parte el archiv firmad (archiv_firmad) y pr tra una variable del tip JSON (jsn) cn ls dats asciads al dcument, tal y cm se muestra a cntinuación: 12

13 WS Cnsulta de dcuments Parámetrs de entrada Nmbre del camp Tip de dat Obligatri jsn Estructura JSON frmada pr ls camps mstrads a cntinuación id_peracin Varchar(255) private_key Varchar(255) cif_cliente Varchar(255) Parámetrs de salida Nmbre del camp Tip de dat Obligatri jsn Estructura JSON frmada pr ls camps mstrads a cntinuación id_peracin Varchar(255) estad_peracin Varchar(255) firmantes Array Códigs de peración Estad de peración Mensaje de la peración OK El dcument se encuentra firmad y se prcederá a enviarl de nuev. 13

14 0001 El id_peracin n es crrect El private_key n es crrect El cif_cliente n es crrect. KO El dcument aún n se encuentra firmad. Anulad El dcument fue anulad pr el cliente. Rechazad El dcument fue rechazad pr algún firmante. En cas de que el estad de la peración sea "OK", se realiza una petición sbre la URL cnfigurada sbre dich cliente, devlviend el id_peracin y el archiv firmad. Ejempls Petición de enví Se envía una petición POST a la URL ( dnde el parámetr es una variable del tip JSON (jsn) cn el ID de peración (id_peracin), la Private Key (private_key) y el CIF del cliente (cif_cliente), tal y cm se muestra a cntinuación: 14

15 15

16 WS Eliminar dcument Parámetrs de entrada Nmbre del camp Tip de dat Obligatri jsn Estructura JSON frmada pr ls camps mstrads a cntinuación id_peracin Varchar(255) private_key Varchar(255) cif_cliente Varchar(255) Parámetrs de salida Nmbre del camp Tip de dat Obligatri jsn Estructura JSON frmada pr ls camps mstrads a cntinuación id_peracin Varchar(255) N estad_peracin Varchar(255) mensaje_peracin Varchar(255) Códigs de peración Estad de peración Mensaje de la peración OK El dcument ha sid brrad existsamente. 16

17 0001 El id_peracin n es crrect El private_key n es crrect El cif_cliente n es crrect. KO El dcument ya fue firmad, anulad rechazad. Ejempls Petición de enví Se envía una petición POST a la URL ( dnde el parámetr es una variable del tip JSON (jsn) cn el ID de peración (id_peracin), la Private Key (private_key) y el CIF del cliente (cif_cliente), tal y cm se muestra a cntinuación: 17