Aplicacin de Factura Electrnica:

Gua de Usuario para el API de Facturae 2.0

Control de Cambios
VERSIN 1.0 1.1 1.2 FECHA 11/07/2008 28/07/2008 01/08/2008 AUTOR Fernando Manzano Pablo Lorente Pablo Lorente Fernando Manzano DESCRIPCIN Versin inicial Nueva funcionalidad: extensin del recubrimiento de los componentes de firma aadiendo la validacin de firma Se incluye informacin acerca del uso y configuracin de las Extensions Nueva versin en la que se incluye: Soporte para la versin 3.2 de Facturae, nueva estructura del API y nuevos mtodos de firma.

2.0

04/06/2010

Fernando Manzano

ndice

Control de Cambios ______________________________________________________ 2 ndice _________________________________________________________________ 3 Introduccin____________________________________________________________ 4

Objetivo y alcance ___________________________________________________________ 4 Audiencia __________________________________________________________________ 4 Descripcin general __________________________________________________________ 4

Instalacin _____________________________________________________________ 5
Contenido __________________________________________________________________ 5 Instalacin__________________________________________________________________ 5

Componentes ___________________________________________________________ 6
Arquitectura ________________________________________________________________ 6 Componentes de la API _______________________________________________________ 7
MarshallerUtil ____________________________________________________________________ 7 UnmarshallerUtil __________________________________________________________________ 9 ValidatorUtil ____________________________________________________________________ 10 Validadores contables _____________________________________________________________ 11 SignatureUtil ____________________________________________________________________ 11

Componentes de soporte _____________________________________________________ 12

GenericFacturae __________________________________________________________________ 12 Otros componentes _______________________________________________________________ 13

Configuracin _________________________________________________________ 15
Configuracin del componente de firma ________________________________________ 15 Configuracin de las propiedades del API ______________________________________ 15 Configuracin de la imagen de cabecera de la ventana de seleccin de certificado______ 16 Configuracin del sistema de logs _____________________________________________ 17 Configuracin del lenguaje ___________________________________________________ 17 Advertencias _______________________________________________________________ 18

ANEXO A: USO DE EXTENSIONS _______________________________________ 19

Introduccin _______________________________________________________________ 19 Configuracin______________________________________________________________ 19 Creacin del elemento Extensions ___________________________________________ 20

Introduccin Objetivo y alcance

El Ministerio de Industria, Turismo y Comercio (MITyC), como parte del Plan Avanza, pretende impulsar la facturacin electrnica entre pequeas empresas (PYMES y microPYMES) y trabajadores autnomos. Para conseguir su objetivo, ha desarrollado herramientas capaces de gestionar, de forma sencilla e intuitiva, facturas electrnicas que cumplan el formato de facturacin electrnica desarrollado por la propia Administracin en colaboracin con otras entidades. As mismo, como complemento a este objetivo principal, el MITyC se ha propuesto facilitar a las empresas de mayor envergadura (tanto por nmero de empleados como por volumen de negocio) la integracin de la factura electrnica en sus ERPs (Enterprise Resource Planning1) particulares. Para tal cometido, se facilita un API (Application Programming Interface2) que contenga la funcionalidad necesaria para gestionar facturas con formato Facturae, dejando en manos de dichas empresas la labor de integracin final en sus aplicaciones propietarias. El presente documento tiene como finalidad detallar las diversas funcionalidades ofrecidas por el API. Para ello se contemplar un abanico de procesos y operaciones lo ms amplio posible a fin de conseguir proporcionar una API fiable y completa, que se ajuste verdaderamente a las necesidades de las empresas.

Audiencia
Esta gua est dirigida al grupo de desarrollo de la aplicacin propietaria que desee hacer uso del formato Facturae.

Descripcin general
Desarrollo de un API Java con la funcionalidad necesaria para manejar facturas que cumplan con el formato Facturae (en la fecha de redaccin de este documento, versiones 3.0, 3.1 y 3.2). El objetivo es facilitar a las empresas, que as lo deseen, la integracin de un paquete de funcionalidad Facturae en sus respectivas aplicaciones.

Los sistemas de planificacin de recursos empresariales (ERP) son sistemas de informacin gerenciales que integran y manejan muchos de los negocios asociados con las operaciones de produccin y de los aspectos de distribucin de una compaa comprometida en la produccin de bienes o servicios. 2 Una API representa una interfaz de comunicacin entre componentes software. Se trata del conjunto de llamadas a ciertas bibliotecas que ofrecen acceso a ciertos servicios desde los procesos y representa un mtodo para conseguir abstraccin en la programacin, generalmente (aunque no necesariamente) entre los niveles o capas inferiores y los superiores del software. Uno de los principales propsitos de una API consiste en proporcionar un conjunto de funciones de uso general.

Instalacin Contenido
El API est constituido por un nico fichero comprimido que incluye las libreras y la documentacin al respecto. En ms detalle, el contenido del fichero comprimido que constituye el API completo es el siguiente: Facurae-API-2.0.jar Lib Libreras de soporte (ya especificadas en este documento) META-INF Informacin adicional del API o o disclaimer.txt y exencion_responsabilidades.txt /licencias/ ficheros de licencia en distintos idiomas (castellano, ingls, euskera, cataln y gallego) README.txt y LEEME.txt

Gua de usuario (este documento) Javadoc (en formato JAR)

Instalacin
Extraer las libreras JAR contenidas en el directorio <lib>, junto con el JAR del API llamado Facturae-API-2.0.jar y situado en el raz. Despus aadirlas al classpath de la aplicacin con la que se quiera integrar.

Componentes Arquitectura
Este API se divide en dos partes bien diferenciadas: Por un lado estn los componentes de marshal, unmarshal y validacin. Ayudan a la gestin de datos XML, permitiendo la conversin recproca de datos XML y objetos Java. Por otro lado se encuentra el componente de firma, encargado de realizar la firma digital de una factura electrnica.

El API est compuesto por las siguientes libreras (cada grupo de libreras corresponde, respectivamente, a las partes diferenciadas comentadas anteriormente): Facturae-API-2.0.jar Es el ncleo del API y contiene los componentes bsicos. Libreras JAXB Contiene la lgica necesaria para realizar la transformacin entre datos XML y objetos Java. Permite realizar los procesos de marshal (java xml) y unmarshal (xml java) o o o o o jaxb-api-2.1.jar stax-api-1.0-2.jar jaxb-impl-2.1.12.jar activation-1.1.jar jsr173_1.0_api.jar

swing-layout-1.0.3.jar Contiene extensiones de los layout de swing. Son empleados por la interfaz de usuario de seleccin de certificado. Componentes de logs Se utiliza la librera commons-logging.jar para flexibilizar el sistema de logs empleado por el desarrollador. Se incluye log4j por defecto. o o commons-logging.jar log4j-1.2.14.jar

FacturaEBridge.jar Bridge de firma. Contiene la interfaz fachada de los servicios de firma. Componentes de firma Componentes de firma empleados por el API. Se conecta al bridge anterior mediante configuracin. El desarrollador puede conectar otro componente de firma si as lo deseara.

Facturae API

Bridge

- FEBComp10-1.0.4.jar

sign.properties: Contiene una propiedad que conecta el "bridge" con el componente de firma.

- jaxb-api-2.1.jar - stax-api-1.0-2.jar - jaxb-impl-2.1.12.jar - activation-1.1.jar - jsr173_1.0_api.jar - swing-layout-1.0.3.jar - commons-loggin-1.1.jar - log4j-1.2.14.jar

Componentes de firma

(*) No necesarias para la compilacin.

- MITyCLibAPI-1.0.5.jar - MITyCLibCert-1.0.4-mscapi5.jar - MITyCLibCert-1.0.5.jar - MITyCLibOCSP-1.0.5.jar - MITyCLibPolicy-1.0.5.jar - MITyCLibTrustInternal-1.1.0.jar - MITyCLibTSA-1.0.5.jar - MITyCLibXADES-1.0.5.jar - bcprov-jdk15-1.43.jar - bctsp-jdk15-1.43.jar - commons-logging-1.1.jar - commons-codec-1.3.jar - commons-httpclient-3.0.1.jar - commons-lang-2.4.jar - log4j-1.2.14.jar - jss-4.2.5.jar - bcmail-jdk15-1.43.jar (*) - serializer-2.7.1.jar (*) - xml-apis-1.3.04.jar (*) - xalan-2.7.1.jar (*) - xmlsec-1.4.2-ADSI-1.0.jar

Ilustracin 1 Arquitectura general del API

Componentes de la API
Los componentes de es.mityc.facturae.utils. funcionalidad bsica del API se localizan en el paquete

MarshallerUtil
Descripcin
Tiene por cometido la serializacin de un objeto Java Facturae en un fichero de datos XML que representa una factura con formato Facturae.

Funciones
Consta de varios mtodos marshal, adems del mtodo encargado de devolver una instancia de la clase (que a su vez utiliza otros mtodos de creacin de instancias y constructores privados). Cada uno de los mtodos marshal tiene un formato distinto de salida: fichero, nodo

Caso de uso
1) Crear un objeto Java Facturae de la versin 3.0, 3.1 3.2: Para ello, incluidos en el API, se ofrecen todos los objetos necesarios para representar una factura electrnica en clases Java, bajo los paquetes es.mityc.facturae30, es.mityc.facturae31 y es.mityc.facturae32 respectivamente. El objeto raz se denomina Facturae. Para este ejemplo, se utilizar una factura 3.2. El proceso de marshal para una factura 3.0 y 3.1 es idntico teniendo en cuenta las particularidades de la versin del formato a la hora de construir el objeto Facturae en cuestin. Cdigo
// Construir el objeto facturae32Object. es.mityc.facturae32.Facturae facturae32Object = new es.mityc.facturae32.Facturae(); // Utilizar los mtodos set de Facturae, para establecer el contenido de la factura. es.mityc.facturae32.FileHeaderType cabecera32Object = new es.mityc.facturae32.FileHeaderType(); String schemaVersion = "3.2"; cabecera32Object.setSchemaVersion(schemaVersion); invoice32.setFileHeader(cabecera32Object);

2) Crear una instancia de MarshallerUtil: Cdigo

// Obtener un MarshallerUtil para la versin 3.2 de Facturae. MarshallerUtil marshallerUtil32 = MarshallerUtil.getInstance(FacturaeVersion.FACTURAE_32); // El objeto creado cargar el contexto y extensin adecuados.

3) Realizar el marshal: Cdigo

// Utilizar el objeto creado MarshallerUtil, invocando el mtodo marshal. marshallerUtil32.marshal(facturae32Object, "nombreFicheroFactura"); File ficheroFactura = new File("nombreFicheroFactura.xsig"); // Durante el proceso podra lanzarse una MarshalExceptioin.

UnmarshallerUtil
Descripcin
Su finalidad es dirigir la deserializacin de un XML que represente una factura con formato Facturae en un objeto Java Facturae.

Funciones
Consta de varios mtodos unmarshal, adems del mtodo encargado de devolver una instancia de la clase (que a su vez utiliza otros mtodos de creacin de instancias y constructores privados). Cada uno de los mtodos unmarshal tiene un formato distinto de salida: fichero, nodo

Caso de uso
1) Partimos de un fichero XML o XSIG en funcin de si el fichero representa una factura 3.0, 3.1 3.2 respectivamente: Para este ejemplo, se utilizar una factura 3.2. El proceso de unmarshal para una factura 3.0 y 3.1 es idntico teniendo en cuenta la versin del objeto Java Facturae que se produce en cada caso. Cdigo
// Construir el objeto facturae32Object que recibir el resultado del unmarshal. java.io.File factura32 = new java.io.File( factura32.xsig ));

2) Crear una instancia de UnmarshallerUtil: Cdigo

// Obtener un UnmarshallerUtil para la versin 3.2 de Facturae.
UnmarshallerUtil unmarshallerUtil32=UnmarshallerUtil.getInstance(FacturaeVersion.FACTURAE_32);

// El objeto creado cargar el contexto adecuado.

3) Utilizar el componente UnmarshallerUtil: Cdigo

// Utilizar el objeto creado UnmarshallerUtil, invocando el mtodo unmarshal. Se obtiene un objeto Facturae de la versin 3.2 es.mityc.facturae32.Facturae invoice32 = (es.mityc.facturae32.Facturae)unmarshallerUtil32.unmarshal(factura32);

// Durante el proceso podra lanzarse una UnmarshalExceptioin.

ValidatorUtil
Descripcin
Su propsito es verificar la validez de un fichero XML o XSIG (en funcin de si la versin del formato Facturae es 3.0, 3.1 3.2) que representa una factura con formato Facturae.

Funciones
Implementa un mtodo denominado validate que recibe como parmetros el fichero XML o XSIG que representa una factura con formato Facturae y una cadena con la versin del formato Facturae correspondiente a dicho fichero. Devuelve verdadero o falso en funcin de si pasa la validacin o no. El mtodo est sobrecargado para aceptar, tambin, un objeto de tipo source. Un fichero XML/XSIG ser declarado vlido si presenta una estructura adecuada de acuerdo al esquema XSD asociado (esquema de Facturae 3.0, esquema de Facturae 3.1 esquema de Facturae 3.2, junto con el esquema de firma digital).

Caso de uso
1) Partimos de un fichero XML o XSIG en funcin de si el fichero representa una factura 3.0 3.1 / 3.2 respectivamente: Para este ejemplo, se utilizar una factura 3.2. El proceso de validate para una factura 3.0 3.1 es idntico teniendo en cuenta el segundo parmetro de la funcin, que indica la versin que se est validando. Cdigo
// Construir el fichero factura32. java.io.File factura32 = new java.io.File( factura32.xsig ));

2) Utilizar el componente ValidatorUtil:

Cdigo // Crear un objeto de tipo ValidatorUtil. ValidatorUtil vu = new ValidatorUtil(); // Invocar el mtodo validate. Parmetros: el fichero a validar y la versin correspondiente. vu.validate(factura32, "3.2"); // Durante el proceso podra lanzarse una ValidationExceptioin.

10

Validadores contables
En esta versin del API no existen validadores contables. Puede utilizar los validadores contables aportados por la AEAT desde su pgina Web: www.aeat.es

SignatureUtil
Descripcin
Este componente permite firmar digitalmente la factura electrnica empleando un certificado de usuario.

Funciones
Esta clase implementa un mtodo esttico sign sobrecargado de diversas formas. Tambin implementa varias versiones de un mtodo validateSignature. En esta versin del API se permite la especificacin de un almacn de certificados. En el caso de no especificarlos se utilizan los que existan por defecto en un fichero de propiedades. Se han mantenido los mtodos antiguos, sin indicar almacn, para mantener la compatibilidad. Tambin se incluye la posibilidad de paso por parmetro del certificado a utilizar como alternativa a la interfaz grfica de seleccin de certificados. Adems de lo indicado se permite el uso de distintos formatos de entrada: Documento, Fichero para las distintas modalidades del mtodo de firma.

Caso de uso
1) Partir de un fichero XML / XSIG, dependiendo de si se trata de un borrador (de cualquier versin) o de una factura con formato 3.1 3.2 firmada, respectivamente: Para este ejemplo, se utilizar una factura 3.2. Cdigo
// Construir el fichero factura32. java.io.File factura32 = new java.io.File( factura32.xsig ));

2) Invocar al mtodo sign, pasando como parmetros la factura (o borrador) a firmar y la ruta donde se quiera ubicar la factura firmada: Cdigo
// Invocar al mtodo esttico sign. Document docSigned = es.mityc.facturae.utils.SignatureUtil.sign(factura32,almacen ,parametro); * * Ejemplo: almacn = Explorer, parmetro = .

11

En cuanto a la validacin de la firma:

Caso de uso
1) Partir de un fichero XML / XSIG, dependiendo de si se trata de un borrador (de cualquiera de las dos versiones) o de una factura con formato 3.1 3.2 firmada, respectivamente: Para este ejemplo, se utilizar una factura 3.2. Cdigo
// Construir el fichero factura32. java.io.File factura32 = new java.io.File( factura32.xsig ));

2) Invocar al mtodo validateSignature, pasando como parmetros la factura (o borrador) a firmar y la ruta donde se quiera ubicar la factura firmada: Cdigo
// Invocar al mtodo esttico sign. java.util.Map<String, Object> b = es.mityc.facturae.utils.SignatureUtil.validateSignature(factura32); // Si la validacin ha sido correcta se devuelven caractersticas de la firma: / ******************************************************************************************************* * certificado (X509Certificate): certificado con el que se ha firmado. * sign.date (Date): fecha de la firma (no es sello de tiempo). * sign.roles (List<String>): roles aplicados a la firma. * sign.xades.schema (String): esquema XAdES de la firma. Valores posibles: 1.2.2 y 1.3.2. * sign.policy (String): poltica asociada a la firma. Valores posibles: facturae30 y facturae31. ******************************************************************************************************* / // En caso contrario, se lanza una excepcin InvalidSignatureException.

Componentes de soporte
Los componentes de soporte son utilizados por los componentes bsicos, siendo transparentes para el usuario final del API.

GenericFacturae
Descripcin
Se ha creado una clase genrica para agrupar a todas las facturas Facturae independientemente de la versin a la que pertenecen. Las clases Facturae de las distintas versiones heredan de esta clase genrica GenericFacturae.

12

Otros componentes
Estos componentes se agrupan en los siguientes paquetes: Paquete es.mityc.facturae.utils.adapters

Algunas clases JAVA no se mapean de forma natural a una respresentacin XML (por ejemplo HashMap). Se requieren clases adaptadoras para establecer como deben realizar los procesos de marshal y unmarshal. Estas clases heredan de la clase abstracta XmlAdapter. Esta clase abstracta define mtodos para adaptar un tipo dado a un tipo determinado o viceversa. Los mtodos se corresponden con los procesos de marshal y unmarshal.

Paquete es.mityc.facturae.utils.mappers

Se crea una clase personalizada que hereda de NamespacePrefixMapper para determinar el prefijo a utilizar en funcin de la URI que identifica un determinado espacio de nombres (namespace).

Paquete es.mityc.facturae.utils.auth

Contiene una clase personalizada que hereda de java.net.Authenticator. Simplemente almacena el nombre de usuario y contrasea para autenticarse en el proxy durante las validaciones de certificado OCSP (si existiera proxy). Paquete es.mityc.facturae.utils.constants Constantes del API.

Paquete es.mityc.facturae.ui

En este paquete se incluye la interfaz de usuario. Se permite la seleccin de certificado para firmar una factura digitalmente cuando no ste no se pasa como parmetro. Esta interfaz permite la visualizacin de certificados disponibles, la consulta de los atributos de estos certificados, la seleccin de uno de ellos y la validacin de los mismos va OCSP. Los certificados listados dependen del almacn indicado / configurado. Esta interfaz se lanza directamente desde el proceso de firma de factura, es decir, desde el componente SignatureUtil.

13

Ilustracin 2Ventana de seleccin / consulta de certificados

14

Configuracin Configuracin del componente de firma

Para configurar el componente de firma a utilizar habr que incluir un recurso con nombre sign.properties anterior al bridge (FacturaEBridge.jar) en el classpath de la aplicacin. Habr que definir la propiedad facade.sign.class indicando la clase que implementa la interfaz del bridge. Por defecto, se utilizan los componentes de firma desarrollados por MITyC (versin 1.0). El fichero sign.properties contiene:

facade.sign.class=es.mityc.javasign.bridge.comp104.SignMITyCComp10Facade

Configuracin de las propiedades del API

El API permite definir una serie de propiedades para adaptarlo a las necesidades del desarrollador que quiera integrarlo en su aplicacin. Para sobreescribir las propiedades por defecto del API, ser necesario establecer un recurso con nombre /config/sign.properties anterior al API (Facturae-API.jar) en el classpath de la aplicacin. Se encuentran disponibles las siguientes propiedades: store almacen al que se va acceder (por ejemplo Explorer = Internet Explorer) store.param parmetro auxiliar necesario para algunos almacenes (por ejemplo el perfil para el almacn de Mozilla) sign.policy poltica de firma (por ejemplo facturae31) sign.xades.schema esquema XADES (por ejemplo 1.3.2) locale.language lenguaje (por ejemplo, para espaol, es) locale.country pas (por ejemplo, para Espaa, ES) lookAndFeel apariencia de la ventana de seleccin de certificados (por ejemplo so para indicar la apariencia utilizada por el sistema operativo) lookAndFeelTheme tema para el look&feel, cuando el valor del mismo es metal. Contiene un valor numrico (por ejemplo 1) ocsp.server servidor OCSP

15

ocsp.proxyused true o false en funcin de si se usa proxy o no ocsp.proxyauthenticated true o false en funcin de si el proxy es autenticado ocsp.proxyserver direccin de proxy ocsp.proxyport puerto del proxy ocsp.proxyuser usuario de proxy autenticado ocsp.proxypassword password de proxy autenticado truster.id identificador de la clase encargada de administrar la confianza (por defecto mityc).

Las propiedades configuradas por defecto son las siguientes:

store=Explorer store.param= sign.policy=facturae31 sign.xades.schema=1.3.2 locale.language=es locale.country=ES lookAndFeel=so #It will be considered only if lookAndFeel contains "metal" lookAndFeelTheme=1 #OCSP validation ocsp.server= ocsp.proxyused= ocsp.proxyauthenticated= ocsp.proxyserver= ocsp.proxyport= ocsp.proxyuser= ocsp.proxypassword= #truster truster.id=mityc

Configuracin de la imagen de cabecera de la ventana de seleccin de certificado

El API incluye una interfaz, compuesta por una sola ventana, para la seleccin de certificado. Esta ventana incorpora una imagen superior como cabecera, que se establece en funcin de que el look&feel configurado sea facturae o cualquier otro.

16

No se recomienda modificar la imagen correspondiente al look&feel facturae ya que se ha realizado a medida para esta presentacin. Sin embargo, si el look&feel es otro (por ejemplo so, sistema operativo) podra interesar cargar una imagen distinta. Para ello, simplemente habra que establecer un nuevo recurso con nombre /images/topbar3.jpg anterior al API (Facturae-API.jar) en el classpath de la aplicacin. Esta nueva imagen, debera respetar las dimensiones de la imagen por defecto para no interferir en la correcta presentacin de la ventana.

Configuracin del sistema de logs

El API permite definir el sistema de logs a utilizar. De esta forma el desarrollador puede conectar el API con el sistema de logs utilizado en su aplicacin. Para conseguirlo se hace uso de la librera de Apache commons-logging. Para conectar el API con un sistema de logs es necesario configurar el fichero commonslogging.properties. Para sobreescribir el existente por defecto, ser necesario crear un recurso con nombre conmmons-logging.properties que se encuentre por delante del fichero del mismo nombre contenido en el API (Facturae-API.jar) en el classpath de la aplicacin. Por defecto, el API hace uso de log4j. El contenido del fichero commons-logging.properties incluido en el API es el siguiente:

org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4Jlogger

En el caso de querer continuar utilizando este sistema, tambin es posible definir las propiedades concretas de log4j. Para ello habr que crear un recurso con nombre log4j.properties anterior al API (Facturae-API.jar) en el classpath de la aplicacin Para sobreescribir las propiedades de logs por defecto, ser necesario establecer un recurso con nombre commons-logging.properties anterior al incluido en el API (Facturae-API.jar) en el classpath de la aplicacin. Por defecto, el contenido del fichero log4j.properties incluido en el API es el siguiente:

log4j.rootLogger=ERROR, Consola log4j.appender.Consola=org.apache.log4j.ConsoleAppender log4j.appender.Consola.layout=org.apache.log4j.PatternLayout log4j.appender.Consola.layout.ConversionPattern=[%-5p] %c{1} --> %m%n

Configuracin del lenguaje

Como ya se ha mencionado con anterioridad, el API es multilenguaje. Por defecto incluye los idiomas espaol e ingls. Sera posible incluir nuevos idiomas con relativa comodidad. Para ello habra que aadir los siguientes recursos:

17

Un recurso con nombre language/lang_xx_XX.properties, dnde xx son dos caracteres en minsculas que indican el lenguaje utilizado, y XX dos caracteres en maysculas que indican el pas. Este fichero contiene toda la traduccin de las interfaces del API. Un recurso html con nombre html/help_certificat e_xxXX.html, dnde xx son dos caracteres en minsculas que indican el lenguaje utilizado, y XX dos caracteres en maysculas que indican el pas (opcionales). Este recurso constituye una pgina html con la ayuda de la ventana de seleccin de certificados. o Recursos de idioma de los componentes de firma. Al igual que en los casos anteriores, habra que aadir ficheros personalizados para el idioma y pas deseados.

Advertencias
No es posible realizar un unmarshal de una factura firmada para despus realizar un marshal. La factura que se obtiene no es equivalente a la de partida y la firma resulta no ser vlida debido al cambio en la estructura del fichero. El problema reside en que los procesos de marshal y unmarshal no guardan informacin de la estructura del XML. No existe mayor problema, ya que en realidad, nunca debera realizarse un unmarshal para despus realizar un marshal. Una factura firmada no se podr modificar nunca, por lo que si se realizara un unmarshal de la misma, slo sera con propsitos de lectura y nunca de alteracin. Problema JRE La API es compatible con las mquinas virtuales JRE1.5 y JRE1.6. No obstante se ha detectado un problema con la actualizacin 03 de la JRE1.6. Las libreras de JAXB en su versin 2.1 (utilizadas para el desarrollo de la API) tienen un conflicto con las libreras de JRE. Se recomienda encarecidamente no usar la versin JRE1.6.0_03. Con la versin JRE1.6.0_07 (la ms reciente durante la redaccin de este documento) se soluciona el problema. En cualquier caso, si se reprodujera el problema puede solucionarse a travs del mecanismo de directorio endorsed. Para saber ms acerca de este problema y como solucionarlo, acceda al siguiente enlace: http://java.sun.com/j2se/1.5.0/docs/guide/standards/

18

ANEXO A: USO DE EXTENSIONS Introduccin

En ocasiones, el formato Facturae no consigue paliar las necesidades concretas de todos los sectores de negocio a los que va dirigido. Por tal motivo, se opt por definir un elemento incluido en el formato y con nombre Extensions que permitiese la introduccin flexible de datos estructurados. Estas extensiones pueden introducirse a tres niveles: Lote de facturas Datos adicionales Lnea de factura

Existe una gran diferencia entre el elemento Extensions definido en el formato 3.0 con respecto al definido en el formato 3.1/ 3.2. En el primer caso, no se realiza validacin contra esquema, tan slo se comprueba que es un elemento XML bien formado y que el espacio de nombres (atributo xmlns) es distinto al de Facturae. En el segundo caso, s que se realiza una validacin contra esquema obligatoria. En el siguiente apartado, se detallar como introducir un nuevo esquema.

Configuracin
En el caso de facturas con formato Facturae 3.1 / 3.2 se realiza una validacin obligatoria contra esquema del contenido del elemento Extensions. Por este motivo, es necesario especificarle al componente de validacin de facturas, dnde se encuentra el esquema que sigue dicha extensin del formato. Es necesario definir un fichero de propiedades que contenga los datos de los esquemas utilizados en las extensiones. El nombre del fichero es schemaLocationExtensions.properties y se encuentra en la ruta externa a la API /config/. Este fichero de propiedades estar formado por: Una propiedad fija, que contiene una lista de los esquemas introducidos separados por ;. EXTENSION_SCHEMAS Dos nuevas propiedades por cada uno de los esquemas. La primera indica la localizacin interna del esquema y la segunda el espacio de nombres. EXTENSION_SCHEMA_<NOMBRE_ESQUEMA> <NOMBRE_ESQUEMA>_EXTENSION_NAMESPACE

19

Ejemplo de fichero de propiedades schemaLocationExtensions.properties que incluye dos esquemas de extensiones: SHIPORDER y TRAVEL.

EXTENSION_SCHEMA_SHIPORDER=externalResources/schemas/shiporder.xsd SHIPORDER_EXTENSION_NAMESPACE=http://www.extensions.es/shiporder EXTENSION_SCHEMA_TRAVEL=externalResources/schemas/travel.xsd TRAVEL_EXTENSION_NAMESPACE=http://www.extensions.es/travel EXTENSION_SCHEMAS=SHIPORDER;TRAVEL

Por otro lado, hay que introducir los esquemas XSD correspondientes en las rutas especificadas en el fichero de propiedades. En este caso, en la ruta externa a la API /externalResources/schemas/.

Creacin del elemento Extensions

Existen dos posibilidades para crear un elemento Extensions (a cualquiera de los niveles que permite el formato). La primera opcin es manipular directamente el fichero XML para escribir el contenido adecuado. La segunda opcin, es ms recomendable y pasa por crear la extensin desde el objeto JAVA, antes de construir el fichero XML. A continuacin se detallar sta ltima opcin. Para introducir las extensiones desde el objeto JAVA que representa una factura: 1. Partimos de un fichero XML que representa una factura (versin 3.0, 3.1 3.2)
File f = new File (factura.xml");

2. Se crea una cadena de texto que contenga los datos en XML de la extensin String s="<jarl:shiporder xmlns:jarl=\"http://www.extensions.es/shiporder\" orderid=\"33\">"+ "<orderperson>" + "Juana Batata" + "</orderperson>" + "<shipto>" + "<name>Hugo Sanchez</name>" + "<address>C/Mayor</address>" + "<city>Mexico D.F.</city>" + "<country>Mexico</country>" + "</shipto>" + "<item>" + "<title>Mister T</title>" + "<note>Enviado de Argentina</note>" + "<quantity>5</quantity>" + "<price>7.88</price>" + "</item>" + "</jarl:shiporder>";

20

3. Se obtiene un objeto Document a partir del fichero que representa la factura.

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); Document doc = null; try { doc = dbf.newDocumentBuilder().parse(f); catch (ParserConfigurationException ex) {} catch (SAXException ex) {} catch (IOException ex) {} catch (IllegalArgumentException ex) {}

4. Se obtiene un objeto Document a partir de la cadena que representa la extensin. DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); Document doc2 = null; try { doc2 = dbf.newDocumentBuilder().parse(new InputSource(new StringReader(s))); catch (ParserConfigurationException ex) {} catch (SAXException ex) {} catch (IOException ex) {} catch (IllegalArgumentException ex) {} 5. Se importa el nodo desde el documento que contiene la factura. Node nVal = doc.importNode(doc2.getChildNodes().item(0),true); // true = deep copy 6. Se declara e inicializa el nodo Extensions que se desee modificar.
* Una forma sencilla de hacerlo sera la que se muestra a continuacin. Existen otros procedimientos ms adecuados y fiables basados en la lectura del rbol. Queda a eleccin del desarrollador elegir un mtodo u otro.

Node nExt = doc.getElementsByTagName("Extensions").item(3); 7. Se aade el nodo que contiene las extensiones. nExt.appendChild(nVal); 8. Por ltimo habra que construir el fichero XML a partir del documento modificado doc. try { Source source = new DOMSource(doc); File file = new File(filename); Result result = new StreamResult(file); Transformer xformer = TransformerFactory.newInstance().newTransformer(); xformer.transform(source, result); } catch (TransformerConfigurationException tce) { } catch (TransformerException te) { }

21