WEBSERVICE DE LA PLATAFORMA DE PROVEEDORES GE-FACTURA Descripción Técnica

Versión 4.2 Fecha: Junio 2015

Definición Servicio Web, Ge-Factura

ÍNDICE

Nº Pág.

1 URL de Interfaz WSDL ............................................................................................. 3 2 Servicio de grabación y envío de facturas............................................................. 3 2.1 Resultado de la ejecución ................................................................................................ 3

3 Servicio de consulta de facturas ............................................................................ 5 3.1 Resultado de la ejecución ................................................................................................ 5 3.1.1 Datos proporcionados por la consulta de Información Extendida................................ 7

4 Servicio de consulta de Departamentos Destinatarios ......................................... 9 4.1 Resultado de la ejecución .............................................................................................. 10

5 ANEXO I: Filtros para el servicio de consulta...................................................... 11 6 ANEXO II: Errores .................................................................................................. 13 6.1 Errores Generales ......................................................................................................... 15 6.2 Errores en la Publicación de facturas ............................................................................. 15 6.3 Errores en la Consulta de facturas ................................................................................. 16 6.4 Errores en la Consulta de departamentos destinatarios.................................................. 16

Página 2 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

1

URL de Interfaz WSDL

La URL del interfaz WSDL es la siguiente: http://web.sedeb2b.com/EdiwinWS/services/geFact?wsdl También existe un entorno de preproducción para poder hacer pruebas sobre el servicio web. La URL de acceso a PRUEBAS es la siguiente:

http://web.sedeb2b.com/EdiwinWSPre/services/geFact?wsdl 2

Servicio de grabación y envío de facturas

Se utilizará para grabar o publicar y enviar facturas. function PublishDocument( aUser : Usuario que va realizar la publicación aPassword : Contraseña del usuario que va realizar la publicación aMessage : Fichero ZIP en B64 que contendrá los ficheros, en formato gefactura a publicar. ) String : Devolveremos el estado de la publicación

2.1

Resultado de la ejecución

En caso de que se haya publicado correctamente la factura, devolverá un mensaje de texto con el identificador del documento que se ha publicado en la plataforma. En caso de que haya algún error en el proceso de publicación, devolverá un mensaje de texto con el error producido. Un ejemplo sería un error en la validación del usuario, o en caso de no enviar ningún fichero. Sólo se podrán publicar facturas que ya hayan sido previamente firmadas. En caso de enviar una factura no firmada, el servicio web generará un error indicando esta situación y no la publicará. Ejemplo: protected String PublicarFactura(String user, String pass, File file){ String retorno = ""; try { FileInputStream fis = new FileInputStream(file); byte[] data = new byte[fis.available()]; fis.read(data); String proccess = null; retorno = service.publishDocument(user, pass, data, proccess); } catch (EdiwinWSException EWSe) { // EWSe.printStackTrace(); System.out.println("EdiwinWSExcepcion: " + EWSe.getText());

Página 3 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

} catch (RemoteException Re) { // Re.printStackTrace(); System.out.println("RemoteExcepcion: " + Re.toString()); } catch (Exception e) { // e.printStackTrace(); System.out.println("Exception: " + e.toString()); } System.out.println(retorno); return retorno; }

Página 4 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

3

Servicio de consulta de facturas

Se utilizará para consultar los datos de una o más facturas. Opciones de consulta permitidas por este servicio:     

Consulta de la información extendida de la factura Consulta de la e-factura original en formato geFactura (contenido del XML) Consulta de la e-factura original incluyendo firma. (Fuente). Consulta del informe o copia impresa en formato PDF. Consulta de información auxiliar de motivos de devolución, errores, auditoría, etc…

function getDocuments ( aUser : Usuario aPassword : Contraseña aDomain : Domain aFilter : Filtro SQL para identificar la/las eFacturas aType : Info/Doc/Int/Informe/aux ) byte[ ] : Resultado de la consulta.

Donde, aType es el tipo de respuesta/consulta que se solicita. Los 4 tipos de consultas indicadas anteriormente, se pueden solicitar según el valor de este parámetro: Info/Doc/Int/Informe 1. Info  Información extendida 2. Doc  Documento o contenido de la factura 3. Int  Intercambio o factura firmada 4. Informe  Informe 5. Aux  Información auxiliar aFilter, especifica un filtro, para la consulta SQL, que permita acotar qué factura o facturas se quieren recuperar. Ver anexo I.

3.1

Resultado de la ejecución

En caso de que se haya obtenido correctamente la o las facturas, devolverá un fichero ZIP en Base64 con la información solicitada. En caso de que haya algún error en el proceso de recuperación, devolverá un mensaje de texto con el error producido. Un ejemplo sería error en la validación del usuario, o en caso de que ninguna factura cumpla el filtro de búsqueda.

En base a lo solicitado, esto es, a lo indicado en la llamada en el parámetro aType, el formato del fichero ZIP variará: Info (solicitamos información extendida)  obtendremos un fichero de texto “export.txt” con el contenido de la Información extendida y asociada a la factura, (o sea, datos adicionales que no constan en el XML origen de la factura), por ejemplo, datos del registro. Ver apartado 3.1.1.

Página 5 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

Doc (solicitamos la factura original)  obtendremos el XML de la factura original sin la firma. Int (solicitamos la factura intercambiada)  obtendremos el XML de la factura original con la firma. El nombre del fichero de respuesta está estructurado. Dicho nombre está compuesto por los siguientes datos separadas por "_". 1. Identificador. 2. Fecha de la factura 3. Emisor 4. Receptor 5. Número de factura.

Informe (solicitamos al copia impresa de la factura) obtendremos un pdf con la imagen de la factura (el formato de su copia impresa). Información auxiliar (solicitamos información auxiliar a la factura)  obtendremos un fichero de texto, “infoAuxiliar.txt” con información que incluye:    

Errores de validación. Errores de puntos operacionales. Errores de mapeo. Información de auditoría.

Los registros están separados por el carácter "|", y los campos por el carácter "~". Cada registro contiene, por orden, los siguientes campos: ID: Identificador de la factura. REFERENCIA: Número de la factura. TIPO: Tipo de información auxiliar. INFORMACION: Texto con la información.

   

Ejemplo: protected byte[] ObtenerFactura(String user, String pass, String domain,String filter, int type) { byte[] dato = null; try { dato = service.getGeFact().getDocuments(user, pass, domain, filter, type); } catch (EdiwinWSException EWSe) { } catch (RemoteException rE) { System.out.println("RemoteExcepcion: " + rE.toString()); } return dato; }

Página 6 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

Datos proporcionados por la consulta de Información Extendida

3.1.1

Se explicaba anteriormente que, en el caso de una consulta del tipo Info, el servicio devuelve un fichero de texto “export.txt”, con información “extendida” de la factura, esto es, información adicional a la factura. Los registros están separados por el carácter "|", y los campos por el carácter "~". La siguiente tabla, describe la lista de campos que devuelve este fichero y su significado: CAMPO

VALOR

DESCRIPCION

ID

6265

Identificador asignado a la factura publicada. Este número es único en la plataforma.

ENV_DESTINO

ESS4611001A

NIF en formato europeo de la entidad destino de la factura

ESTADO

COR

Estado de la factura en cuanto a errores de validación o sintácticos. Puede estar correcta (COR) o errónea (ERR)

FECHACAMBIOESTADO

07/12/09 13:56

Fecha en la que se ha actualizado el estado de la factura.

ORIGEN

NIFPROV1

Emisor de la factura. El NIF en formato europeo (p.e, precedido de ES)

DESTINO

G06CSI000

Código de departamento destino de la factura.

FORMATO

XML

De momento el único formato admitido es XML.

FECHA

07/12/09

Fecha de la factura.

INTERFAZ

XML_FACTURAE_3_1

Guía de la factura. Formato de la misma.

REFERENCIA

NUMFACT_001

Número de referencia de la factura.

CRIPTO

SXADES

Factura firmada con XSADES.

LONGITUD

28797

Longitud del fichero de factura.

MARCA

09120713440901044381 Código de autenticación/validación asociada a la copia impresa

ESTADOEXT

REG

Estado actual de la factura en cuanto a su procesamiento. Los posibles valores son: REG: Registrada DEV: Devuelta CNF: Aceptada

Página 7 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

PPA: Propuesta de pago PAG: Pagada LEI: Leido RCF: Registrada en registro contable ERR: Erróneas

GE_NUMREG

02GRF/2009-155478

Número de registro de entrada asignado al documento al recibir la factura la plataforma destino

GE_FECHAREG

07/12/09 13:56

Fecha de registro de entrada.

FECHACAMBIOESTADOEXT 07/12/09 13:56

Fecha y hora en la que la factura ha cambiado de estado en la plataforma destino. (Registrada, anulada, etc.)

GE_TOTALEJECUTAR

Importe de la factura

GE_NUMREGS

Número de registro de salida de la factura en caso de ser devuelta.

GE_FECHAREGS

Fecha de registro de salida.

GE_IDRUF

Identificador de registro único de facturas.

Página 8 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

4

Servicio de consulta de Departamentos Destinatarios

Se utiliza para obtener información de los puntos operacionales definidos en la administración: puntos destinatarios de facturas y puntos receptores de mercancías y/o servicios. Devolverá un fichero con el resultado de la información de estos departamentos, o una excepción en caso de producirse un error.

Function getRecipientDepartment ( aUser : Usuario aPassword : Contraseña aDomain : Dominio aDepartmentType : Tipo de departamento aHierarchicalCode : Código jerárquico del departamento aDepartmentCode : Código del departamento ) var byte[] : Resultado de la consulta

El filtro de búsqueda de departamentos se hará según los parámetros:  tipo de departamento  código jerárquico del departamento y,  código de departamento. Estos parámetros son opcionales, por lo que se podrá obtener toda la estructura de departamentos si no se especifica ninguno de ellos. Tipo de departamento: Es el código del tipo de departamento que se está buscando. Existen 4 tipos de departamentos: • NR: No receptores • RF: Receptores de facturas • RM: Receptores de mercancías • RFM: Receptores de facturas y mercancías. Se podrán especificar los tipos que se quieran separados por comas. De esta forma se podrán obtener los departamentos que correspondan a los tipos especificados. Ejemplos: aDepartmentType=RF,RFM aDepartmentType=NR Código jerárquico: El código jerárquico indica el departamento padre de los departamentos buscados. La asignación en la búsqueda se hará mediante la operación igualdad, de forma que si se especifica un departamento padre, se obtendrán todos aquellos departamentos que dependan de ese departamento. En el caso de que no se especifique ningún código jerárquico en la llamada, la búsqueda se aplicará a toda la libreta de direcciones.

Sólo se puede especificar un único código jerárquico. En caso de introducir varios, la aplicación dará error.

Página 9 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

Código de departamento: El código de departamento indica el departamento en sí que se está buscando. Se podrán especificar los códigos de departamento que se quieran separados por comas. De esta forma, se obtendrán aquellos departamentos especificados en este parámetro.

4.1

Resultado de la ejecución

En caso de que se haya obtenido correctamente el o los departamentos, devolverá un fichero ZIP en Base64 con los datos de los departamentos que genera la búsqueda. En caso de que haya algún error en el proceso de recuperación, saltará una excepción que contendrá un mensaje de texto con el error producido. Ejemplos de este tipo de excepciones serían error en la validación del usuario, o en caso de no existir ningún departamento destinatario del que obtener los datos. Ejemplo:

protected String ObtenerDepartamento(String aUser, String aPass, String aDomain, String aDepartmentType, String aHierarchicalCode, String aDepartmentCode) { byte[] dato = null; try { dato = service.getRecipientDepartment(aUser, aPass, aDomain, aDepartmentType, aHierarchicalCode, aDepartmentCode); } catch (RemoteException rE) { String text = "RemoteExcepcion: " + rE.toString(); logger.error(text); System.out.println(text); } return dato; }

Página 10 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

5

ANEXO I: Filtros para el servicio de consulta

Los datos que se pueden utilizar para construir el filtro de la consulta que se puede especificar en el parámetro aFilter,, son los siguientes: Campo que se puede utilizar para construir el filtro ID ESTADO FECHACAMBIOESTADO

Tipo

Descripción

Int Varchar DateTime

ORIGEN DESTINO FORMATO FECHA INTERFAZ REFERENCIA ENV_DESTINO CRIPTO LONGITUD MARCA

Varchar Varchar Varchar DateTime Varchar Varchar Varchar Varchar Int Varchar

ESTADOEXT GE_TOTALEJECUTAR GE_NUMREG GE_FECHAREG FECHACAMBIOESTADOEXT GE_FECHAREGS GE_NUMREGS GE_IDRUF

Varchar Varchar Varchar DateTime DateTime DateTime Varchar Varchar

Identificador de la factura. Estado de la factura dentro del sistema. Fecha del último cambio de estado de la factura. Origen de la factura. Departamento destinatario de la factura. Formato de la factura. Fecha de la factura. Interfaz que utiliza la factura. Número de la factura. Empresa a la que va destinada la factura. Tipo de firma utilizada en la factura. Tamaño de la factura en bytes. Identificador único de la factura dentro de la plataforma. Estado de la factura. Importe de la factura. Número de registro de entrada. Fecha del registro de entrada. Fecha del cambio de estado de la factura. Fecha del registro de salida. Número del registro de salida. Número de identificación de registro único de facturas.

A continuación se muestran algunos ejemplos de consultas más usuales, se permite cualquier combinación de búsqueda sobre los campos permitidos. Un dato importante para el tema de las fechas es que hay que utilizar el formato de fechas de la base de datos. Puesto que en este caso se utiliza SQLServer, el formato a utilizar de las fechas será el siguiente: MM/dd/yyyy HH:mm:ss (Mes/Dia/Año Hora:Minuto:Segundo) Ejemplos: - Consulta por Referencia de factura: REFERENCIA='NUMFACT_001' - Por identificador ID=6265 - Varios identificadores simultáneamente: ID IN (6265,6248,6219) - Rango de Identificadores

Página 11 de 17

Fecha Modificación: 16/06/2015

Definición Servicio Web, Ge-Factura

ID>6000 AND ID='11/01/2009 00:00:00' AND FECHACAMBIOESTADO