AMAPPortafirmas-1.4.0 2021/01/21

Nuevos métodos para Portafirmas V3

• Método para bloquear una petición.
• Método para obtener los tipos CSV disponible por aplicación.

AMAPPortafirmas-1.3.4 2020/04/16

• Comprobación de avisos vacíos en la creación de peticiones.

AMAPPortafirmas-1.3.3 2020/02/07

• Corrige bug en el  servicio de modificación con seguridad.

AMAPPortafirmas-1.3.2 2020/02/04

• Permite obtener peticiones que tengan estados de acciones no contemplados.

AMAPPortafirmas-1.3.1 2019/12/23

• Corrección del método getFirmaDetalle

AMAPPortafirmas-1.3.0 2019/07/09

•  Elimina los estados EstadoPeticion y EstadoGlobal.
•  Nuevos estados EstadoLineaFirma y EstadoAccion.
•  Elimina el método getEstadoPeticion, el estado de la petición ahora será finalizado o no.
•  Nuevo método isFinalizado, devuelve true si todas las líneas de firma de la petición están en estado final.
•  Nuevo campo en la clase Peticion: lista de parámetros
•  Nuevo servicio de modificación con seguridad en la implementación HTTPCLIENT: permite crear y modificar peticiones con el campo lista de parámetros.
•  Alineación de componentes bouncy castle a la versión jdk15on
•  Actualización de las excepciones de la implementación httpclient

AMAPPortafirmas-1.2.4 2019/02/27

•  Cliente con implementacion MOCK

AMAPPortafirmas-1.2.3 2019/01/25

•  Corrección en el parseo de documentos

AMAPPortafirmas-1.2.2 2019/01/16

•  Actualización de las trazas

AMAPPortafirmas-1.2.1 2018/11/21

•  Soluciona el mapeo de los mensajes de error en las excepciones

AMAPPortafirmas-1.2.0 2018/7/19

•  Soporte de http en httpclient para servicio de modificación 

AMAPPortafirmas-1.1.4 2018/6/26

•  Corrección en el método getInformeFirma

AMAPPortafirmas-1.1.3 2018/6/22

•  Corrección en el log

AMAPPortafirmas-1.1.2 2018/6/19

•  Implementación "httpclient"

AMAPPortafirmas-1.1.1 2017/8/10

•  Se modifica el algoritmo de los estados de la petición

AMAPPortafirmas-1.1.0 2017/3/28

• Se quitan los parámetros.
• Se añade un estado global a la petición.
• Se renombran las propiedades del amap-portafirmas-interno
• Si el documento no existe retorna un error.
• Se cambia la versión del amap-parent a 2.0.5

AMAPPortafirmas-1.0.7-2016/1/14

• Corrección en la devolución del identificador del tipo de documento.

AMAPPortafirmas-1.0.6-2015/12/15

• Corrección para el trazado.

AMAPPortafirmas-1.0.5-2015/05/04

• Nuevos métodos getFirmaDetalle, getDocumentoDetalle y getCSV.
• Cambios en la gestión de las excepciones, sin efectos en el API.

AMAPPortafirmas-1.0.4-2015/01/28

• Nuevo método de consulta para la obtención del estado de una petición.

AMAPPortafirmas-1.0.3-2014/12/02

• Cambio en la configuración. Se incluye indica la url base (común para ambos servicios).

AMAPPortafirmas-1.0.2-2014/10/13

• Corrección de bugs menores.

AMAPPortafirmas-1.0.1-2014/10/13

• Actualización y completado del interface .

AMAPPortafirmas-0.0.1-SNAPSHOT 2012/05/23

• Primera versión componente.

<dependency>
<groupId>es.gobcantabria.amap.integracion</groupId>
<artifactId>amap-portafirmas</artifactId>
<version>1.4.0</version>
</dependency>

La aplicación que va a consumir los servicios debe estar dada de alta en la aplicación Portafirmas y tener acceso a su "endpoint".

Sin recursos disponibles.

Configuración

Obtención de un servicio de la factoría

Para la utilización del componente amap-portafirmas basta con añadir el jar y sus correspondientes dependencias al classpath de la aplicación y crear un servicio del siguiente modo:

amap-portafirmas provee de dos servicios, uno de consulta y otro de modificación (con o sin seguridad):

• Para obtener el servicio de consulta (PortafirmasConsultaService):

PortafirmasConsultaService portafirmasConsultaService = PortafirmasConsultaService.getServicio(urlServicioBase, implementacion);

• Para obtener el servicio de modificación (PortafirmasModificacionService) con seguridad:

Aplicacion aplicacion = new Aplicacion(nombreAplicacion, password);
PortafirmasModificacionService portafirmasModificacionService = 
                         PortafirmasModificacionService.getServicio(urlServicioBase, aplicacion, implementacion);

• Para obtener el servicio de modificación (PortafirmasModificacionService) sin seguridad:

PortafirmasModificacionService portafirmasModificacionService = PortafirmasModificacionService.getServicio(urlServicioBase, implementacion);

El servicio concreto a usar se definirá a partir de un fichero de properties junto con el resto de los parámetros:

Actualmente los valores de implementacion soportados son:
 - httpclient (recomendado y por defecto si se deja el campo a null)
 - guadaltel (deprecado)
 - mock: cliente de prueba para la integración con el servicio sin necesidad de conectarse a ningún servidor (los parámetros serán ignorados)

Ejemplo de contenido del fichero de propiedades:

sistemas.global.amap.portafirmas.url=http://*****/pfirma
sistemas.app.amap.portafirmas.usuario=*****
sistemas.app.amap.portafirmas.password=*****

No disponible.

Sin particularidades. Seguir las recomendaciones del fabricante.

Tratamiento de las excepciones

Tanto en los métodos de consulta como en los métodos de modificación de la implementacion httpclient, el detalle de los errores controlados que se devuelven al realizar la petición son accesibles a través de la clase ErrorInfo que se encuetra dentro de la clase excepción AMAPPortaFirmasGenericException.

Ejemplos de uso

Envío de una petición de firma a un único firmante con acción asociada

El primer paso será obtener el usuario que actuará a su vez como remitente y como destinatario de la petición. Para ello se hará una consulta de usuarios a través del método getUsuarios pasando como filtro el dni del usuario que se pretende recuperar (si no se le pasan parámetros devuelve la lista completa).

List<Usuario> listaUsuarios = miServicioQuery.getUsuarios("12345678Z");
Usuario usuario = listaUsuarios.get(0);

Una vez obtenido, se asignará el mismo como remitente:

List<Usuario> listaRemitentes = new ArrayList<Usuario>();
listaRemitentes.add(usuario);

y como firmante de la petición:

Firmante firmante = new Firmante();
firmante.setUsuarioCargo(usuario);
  
List<Firmante> listaFirmantes = new ArrayList<Firmante>();
listaFirmantes.add(firmante);

El siguiente paso en la creación de la petición es añadirle una línea de firma que contenga al firmante que se definió anteriormente. Los firmantes han de añadirse a las líneas de firma a través de listas por lo que se instanciará una lista de firmantes para añadirlas a la linea de firma y esta será añadida también a una lista de líneas de firma. Si no se especifica el tipo de línea de firma (firma o visto bueno), ésta toma por defecto el valor de firma.

LineaFirma lineaFirma = new LineaFirma();
lineaFirma.setFirmantes(listaFirmantes);
  
List<LineaFirma> listaLineasFirma = new ArrayList<LineaFirma>();
listaLineasFirma.add(lineaFirma);

Tras crear la línea de firma se procederá a obtener el tipo de documento que se añadirá a la petición (con identificador para obtener uno concreto o sin el para la lista completa)

TipoDocumento tipoDocumento = miServicioQuery.getTiposDocumento("GENERICO").get(0);

y se adjuntará el documento a la petición.

Documento doc = new Documento();
doc.setFirmable(true);
doc.setTipoDocumento(tipoDocumento);
doc.setMime("application/pdf");
doc.setNombre("Fichero_a_firmar_PRUEBAWS");
  
File file = new File("/tmp/midocumento.pdf");
doc.setContenido(FileUtils.readFileToByteArray(file));

List<Documento> listaDocumentos = new ArrayList<Documento>();
listaDocumentos.add(doc);

Tras crear la lista de documentos se procederá a crear la lista de acciones a ejecutar añadiendo la opción tipo WEB que invocará la url indicada en el parámetro action cuando la petición haya pasado al estado indicado.

Accion accion = new Accion();
accion.setTipo(TipoAccion.WEB.toString());
accion.setAccion("http://www.google.es");

EstadoAccion estadoLeido= EstadoAccion.LEIDO;
accion.setEstado(estadoLeido);
  
List<Accion> listaAcciones = new ArrayList<Accion>();
listaAcciones.add(accion);

Para utilizar esta funcionalidad se debe tener acceso desde el servidor de portafirmas a la url invocada, por lo que si no está habilitado ese acceso se deberá solicitar. En caso de que no sea posible no se podrá utilizar esta funcionalidad y se deberá consultar periódicamente el cambio de estado por parte del llamante al portafirmas.

Se recomienda hacer peticiones http (puerto 80), funciona a modo de trigger para que la aplicación cliente recupere el resto de información consultando a los servicios web de portafirmas.

Es posible realizar una petición https (puerto 443), aunque es necesario cargar el certificado público del servidor al que se desea conectar en el almacén de certificados de confianza del servidor de portafirmas, por lo que deberá solicitarse su inclusión en el mismo.

Los estados soportados pueden ser obtenidos mediante el método getEstados (con el identificador del estado o sin ningún parámetro para obtener todos).

Tambien se puede añadir información adicional a una petición mediante el uso de metadatos: 

Parametro parametro = new Parametro()
parametro.setIdentificador("MIPARAMETRO");
parametro.setValor("Valor de mi parametro");

List<Parametro> listaParametros = new ArrayList<Parametro>();
listaParametros.add(parametro);

Una vez creada la lista de acciones de la petición, el siguiente paso es instanciar un objeto Peticion y fijar sus propiedades con los datos obtenidos anteriormente además de indicar la aplicación a la que irá asociada dicha petición, el asunto, texto, referencia y tipo de firma de la misma. Si el servicio de modificación se ha instanciado con seguridad, el campo aplicación del objeto Peticion es obligatorio y debe coincidir con nombre de la aplicación fijada en la instancia del servicio.

Peticion peticion = new Peticion();
peticion.setAplicacion("MIAPP");
peticion.setDocumentos(listaDocumentos);
peticion.setReferencia("referencia_ws");
peticion.setRemitentes(listaRemitentes);
peticion.setLineasFirma(listaLineasFirma);
peticion.setTipoFirma(TipoFirma.PRIMER_FIRMANTE.toString());
peticion.setAsunto("UNICO FIRMANTE");
peticion.setTexto("mi texto");
peticion.setAcciones(listaAcciones);
peticion.setParametros(listaParametros);

Una vez creado el objeto, se creará la petición a través del método crearPeticion del servicio de modificación pasándole como parámetro la petición. El resultado de la operación es el identificador de la petición creada.

String identificador = miServicioModify.crearPeticion(peticion);

Finalmente la petición se envía invocando al método enviarPeticion pasándole el identificador como parámetro.

miServicioModify.enviarPeticion(requestHash);

Envío de una petición de firma a un usuario y un puesto de trabajo

El procedimiento sería idéntico al anterior, sólo que se añadiría como firmante en lugar de a un usuario concreto a un puesto cargo determinado.

Para ello se ha de obtener el cargo (puesto de trabado) deseado de la lista cargos (con identificador para obtener uno o sin el para obtener la lista completa)

List<Cargo> listaCargos = miServicioQuery.getCargos("JEFE");
Cargo cargo = listaCargos.get(0);

y añadirlo a la lista de firmantes como si de un usuario se tratara

Firmante cargoFirmante = new Firmante();
cargoFirmante.setUsuarioCargo(cargo);

listaFirmantes.add(cargoFirmante);

El tipo firma en este caso sería de tipo CASCADA en lugar de PRIMER_FIRMANTE

peticion.setTipoFirma(TipoFirma.CASCADA.toString());

Envío de una petición de firma a un usuario y visto bueno a un cargo con documento anexo

El algoritmo sería idéntico al anterior salvo que se crearía una nueva línea de firma de tipo VISTOBUENO:

LineaFirma2 lineaFirma = new LineaFirma();
lineaFirma2.setFirmantes(listaFirmantes);
lineaFirma2.setTipo(TipoLineaFirma.VISTOBUENO.toString());
  
List<LineaFirma> listaLineasFirma = new ArrayList<LineaFirma>();
listaLineasFirma.add(lineaFirma2);

Para adjuntar un anexo basta con añadir a la lista de documentos un documento con el flag firmable=false:

Documento anexo = new Documento();  
anexo.setFirmable(false);
anexo.setTipoDocumento(tipoDocumento);
anexo.setMime("application/pdf");
anexo.setNombre("Fichero_a_firmar_PRUEBAWS_anexo");
anexo.setContenido(FileUtils.readFileToByteArray(file));

List<Documento> listaDocumentos = new ArrayList<Documento>();
listaDocumentos.add(doc);
listaDocumentos.add(anexo);

Eliminación de una petición

Para eliminar una petición basta con invocar al método borrarPeticion del servicio de modificación pasándole como parámetro el identificador de la petición. El siguiente snippet eliminará la petición cuyo identificador es el 9kMYJ7Xu6c

miServicioModify.borrarPeticion("9kMYJ7Xu6c");

Creación de una petición con metadatos

Es posible añadir información adicional a una petición enviada.

Parametro parametro = new Parametro()
parametro.setIdentificador("MIPARAMETRO");
parametro.setValor("Valor de mi parametro");

List<Parametro> listaParametros = new ArrayList<Parametro>();
listaParametros.add(parametro);

peticion.setParametros(listaParametros);

miServicioModify.enviarPeticion(identificadorPeticion);

Eliminar y añadir firmantes a una petición existente

A continuación se eliminará el único firmante que tiene la petición a través del método borrarFirmantes pasándole el identificador de petición y la lista de firmantes a eliminar (en este caso la que contiene la única línea de firma de la petición).

miServicioModify.borrarFirmantes(identificadorPeticion, peticion.getLineasFirma().get(0).getFirmantes());

Tras haber dejado la petición sin líneas de firma ni firmantes, se procederá a insertar una nueva línea de firma con un firmante. Para ello basta con llamar al método insertarFirmantes  pasándole el identificador de la petición, el número de la línea de firma (contando desde 0) y la lista de firmantes a insertar.

miServicioModify.insertarFirmantes(identificadorPeticion, 0, listaFirmantes)

Añadir y eliminar documentos a una petición existente

A continuación se añadirá un documento a la petición a través del método insertarDocumento pasándole el identificador de la petición y el nuevo documento a incluir en la petición.

Documento anexoAdicional = new Documento();  
anexoAdicional.setFirmable(false);
anexoAdicional.setTipoDocumento(tipoDocumento);
anexoAdicional.setMime("application/pdf");
anexoAdicional.setNombre("Fichero_a_firmar_PRUEBAWS_anexo_adicional");
anexoAdicional.setContenido(FileUtils.readFileToByteArray(file));

miServicioModify.insertarDocumento(identificadorPeticion, anexoAdicional);

Después se eliminará este documento anexado utilizando el método borrarDocumento  pasándole el identificador del documento a eliminar.

miServicioModify.borrarDocumento("8kMYJ7Xu2c");

Obtener documentos, firmas e informe de firmas

Para obtener un documento o firma se utilizará el método getDocumento o getFirma respectivamente pasándole como parámetro el identificador del documento o firma a obtener.

Alternativamente se puede invocar a los métodos getInformeFirma o getInformeFirmaURL para obtener el contenido o la url del informe de firma (CSV).

Peticion peticion = miServicioQuery.getPeticion("03C18k80SJ");
String idPeticion = peticion.getIdentificador();
String idDocumento = peticion.getDocumentos().get(0).getIdentificador();

byte[] documento = miServicioQuery.getDocumento(idDocumento);
byte[] firma = miServicioQuery.getFirma(idDocumento);
byte[] informeFirma = getService().getInformeFirma(idPeticion, idDocumento);
URL informeFirmaUrl = getService().getInformeFirmaURL(idPeticion, idDocumento);

También se puede obtener información más detallada de los documentos o firmas con el método getDocumentoDetalle o getFirmaDetalle respectivamente pasándole como parámetro el identificador del documento o firma a obtener.

Peticion peticion = miServicioQuery.getPeticion("03C18k80SJ");
String idPeticion = peticion.getIdentificador();
String idDocumento = peticion.getDocumentos().get(0).getIdentificador();

Documento documento = miServicioQuery.getDocumentoDetalle(idDocumento);
Firma firma = miServicioQuery.getFirmaDetalle(idDocumento);

Por otro lado se puede acceder al código CSV de un documento con el método getCSV pasándole como parámetro el identificador del documento.

Peticion peticion = miServicioQuery.getPeticion("03C18k80SJ");
String idPeticion = peticion.getIdentificador();
String idDocumento = peticion.getDocumentos().get(0).getIdentificador();

String csv = miServicioQuery.getCSV(idDocumento);

Obtener una petición, el histórico, si está finalizada y los comentarios

Para obtener la información general de la petición el histórico y los comentarios de una petición se disponen de los métodos getPeticion, getComentarios, getHistorico, isFinalizado y isFinalizadoFirmado para todos ellos se necesitará indicar el identificador de la petición.

Peticion peticion = miServicioQuery.getPeticion(identificadorPeticion);
List<Historico> historicos = miServicioQuery.getHistorico(identificadorPeticion);
List<Comentario> comentarios = miServicioQuery.getComentarios(identificadorPeticion);
boolean finalizado= miServicioQuery.isFinalizado(identificadorPeticion);
boolean finalizadoFirmado= miServicioQuery.isFinalizadoFirmado(identificadorPeticion);

Bloquear una petición para Portafirmas V3

Para bloquear una petición basta con invocar al método bloquearPeticion del servicio de modificación pasándole como parámetros el identificador y una fecha de inicio de la petición.
El siguiente snippet bloqueará la petición cuyo identificador es el HjsoV9dIc4 hasta la fecha 2020-09-17.

miServicioModify.bloquearPeticion("HjsoV9dIc4","2020-09-17");

Obtener tipos CSV disponible por aplicación para Portafirmas V3

El método getTiposFirmaNoCriptográficos permite recuperar el listado de mecanismos de autenticación CSV disponibles para una aplicación,
es necesario indicar el identificador de la aplicación.

miServicioConsulta.getTiposFirmaNoCriptográficos("PFIRMA");