amap-portafirmas
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:
Key | Descripción | Ejemplo |
---|---|---|
sistemas.global.amap.portafirmas.url | Endpoint del portafirmas | http://*****/pfirma |
sistemas.app.amap.portafirmas.usuario | Usuario necesario para autenticarse en la aplicación | * |
sistemas.app.amap.portafirmas.password | Password necesaria para autenticarse en la aplicación | * |
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.
Nombre | amap-portafirmas |
Identificador | amap-portafirmas |
Grupo | es.gobcantabria.amap.integracion |
Versión | 1.4.0 |
Licencia | |
Desarrollador | Gobierno de Cantabria |
Descripción |
Documentación | amap-portafirmas (JavaDoc) |
Binario | amap-portafirmas (Jar) |
Sin particularidades. Seguir las recomendaciones del fabricante.
- Cambios en la interfaz a partir de la versión 1.3.0
- Envío de una petición de firma a un único firmante con acción asociada
- Envío de una petición de firma a un usuario y un puesto de trabajo
- Envío de una petición de firma a un usuario y visto bueno a un cargo con documento anexo
- Eliminación de una petición
- Creación de una petición con metadatos
- Eliminar y añadir firmantes a una petición existente
- Añadir y eliminar documentos a una petición existente
- Obtener documentos, firmas e informe de firmas
- Obtener una petición, el histórico, si está finalizada y los comentarios
- Bloquear una petición para Portafirmas V3
- Obtener tipos CSV disponible por aplicación para Portafirmas V3
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");