efact - WebServices Realizado por: Consorci AOC Versión: 1.1 Fecha: 23/07/2013

Transcripción

1 efact - WebServices Realizado por: Consorci AOC Versión: 1.1 Fecha: 23/07/2013

2 e.fact-webservices pàg 2/14 Historia del Documento Versión: 1.0 Versión: 1.1 Descripción: versión inicial. Descripción: actualización esquema estados, corrección URL.

3 e.fact-webservices pàg 3/14 Índice 1 Introducción Objetivos Características del proceso de comunicación WSDL Ubicación Funcionamiento Esquema Consulta de estados (wsefhubinvoicequerystatus) Funcionalidad Esquema de mensajes Consulta de códigos de direccionamiento (wshubdirectioncodesquery) Funcionalidad Esquema dels missatges... 11

4 e.fact-webservices pàg 4/14 1 Introducción 1.1 Objetivos El objetivo de este documento es describir el servicio que ofrece el hub e.fact para la consulta externa de estados, y la consulta de códigos de direccionamiento de receptores e.fact. Esta descripción debe servir como referencia para que las aplicaciones cliente puedan desarrollar la infraestructura necesaria para su integración con el hub e.fact. 2 Características del proceso de comunicación El proceso de comunicación entre el HUB e.fact y las aplicaciones cliente tiene lugar mediante una interfaz de tipo WebService. En los siguientes apartados se muestra el WSDL que define esta interfaz, los esquemas que utiliza, así como detalles tanto de petición como de respuesta. 2.1 WSDL Éste es el documento WSDL que cumple el WebService del HUB e.fact que da servicio a las aplicaciones cliente. Como se puede ver se definen dos operaciones (wsefhubinvoicequerystatus y wshubdirectioncodesquery). Los mensajes de entrada y de salida se describen en los apartados correspondientes Ubicación La URL donde encontramos dicho WebService (WS) es la siguiente: Funcionamiento El WS recibe un XML con la petición que se quiere hacer efectiva. Internamiento evalúa este XML de entrada y en función de una serie de reglas se realiza la consulta en la BB.DD. del Hub, creando el XML de respuesta del WS Esquema <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions xmlns:apachesoap=" xmlns:impl=" xmlns:intf=" xmlns:wsdl="

5 e.fact-webservices pàg 5/14 xmlns:wsdlsoap=" xmlns:xsd=" targetnamespace=" <wsdl:types> <schema elementformdefault="qualified" targetnamespace=" xmlns=" <element name="wsefhubinvoicequerystatus"> <complextype> <sequence> <element name="hubusersenderid" type="xsd:string"/> <element name="hubinfoadd" type="xsd:string"/> <element name="invoicenumber" type="xsd:string"/> <element name="invoicedate" type="xsd:string"/> <element name="invoicesupplier" type="xsd:string"/> <element name="invoicebuyer" type="xsd:string"/> <element name="invoicetotal" type="xsd:string"/> </sequence> </complextype> </element> <element name="wsefhubinvoicequerystatusresponse"> <complextype> <sequence> <element name="wsefhubinvoicequerystatusreturn" type="xsd:string"/> </sequence> </complextype> </element> <element name="wshubdirectioncodesquery"> <complextype> <sequence> <element name="xml" type="xsd:string"/> </sequence> </complextype> </element> <element name="wshubdirectioncodesqueryresponse"> <complextype> <sequence> <element name="wshubdirectioncodesqueryreturn" type="xsd:string"/> </sequence> </complextype> </element> </schema> </wsdl:types> <wsdl:message name="wshubdirectioncodesqueryresponse"> <wsdl:part name="parameters" element="impl:wshubdirectioncodesqueryresponse"/> </wsdl:message> <wsdl:message name="wsefhubinvoicequerystatusresponse"> <wsdl:part name="parameters" element="impl:wsefhubinvoicequerystatusresponse"/> </wsdl:message> <wsdl:message name="wsefhubinvoicequerystatusrequest"> <wsdl:part name="parameters" element="impl:wsefhubinvoicequerystatus"/> </wsdl:message> <wsdl:message name="wshubdirectioncodesqueryrequest"> <wsdl:part name="parameters" element="impl:wshubdirectioncodesquery"/> </wsdl:message> <wsdl:porttype name="hubconnectorws"> <wsdl:operation name="wsefhubinvoicequerystatus"> <wsdl:input name="wsefhubinvoicequerystatusrequest" message="impl:wsefhubinvoicequerystatusrequest"/> <wsdl:output name="wsefhubinvoicequerystatusresponse" message="impl:wsefhubinvoicequerystatusresponse"/> </wsdl:operation> <wsdl:operation name="wshubdirectioncodesquery"> <wsdl:input name="wshubdirectioncodesqueryrequest" message="impl:wshubdirectioncodesqueryrequest"/> <wsdl:output name="wshubdirectioncodesqueryresponse" message="impl:wshubdirectioncodesqueryresponse"/> </wsdl:operation> </wsdl:porttype> <wsdl:binding name="hubconnectorwssoapbinding" type="impl:hubconnectorws"> <wsdlsoap:binding style="document" transport=" <wsdl:operation name="wsefhubinvoicequerystatus"> <wsdlsoap:operation/>

6 e.fact-webservices pàg 6/14 <wsdl:input> <wsdlsoap:body use="literal"/> </wsdl:input> <wsdl:output> <wsdlsoap:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="wshubdirectioncodesquery"> <wsdlsoap:operation/> <wsdl:input> <wsdlsoap:body use="literal"/> </wsdl:input> <wsdl:output> <wsdlsoap:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="hubconnectorwsservice"> <wsdl:port name="hubconnectorws" binding="impl:hubconnectorwssoapbinding"> <wsdlsoap:address location=" </wsdl:port> </wsdl:service> </wsdl:definitions> 2.2 Consulta de estados (wsefhubinvoicequerystatus) Funcionalidad Esta función permite la consulta de estados de una determinada factura registrada en e.fact. A pesar de que los estados de las facturas son realimentados hacia los emisores de las mismas, dependiendo del medio de emisión de éstos, puede ser que no dispongan de uno histórico de envío con los correspondientes estados. En este caso, podrán realizar la consulta del histórico de estados de una determinada factura, a través de este servicio. Un ejemplo de uso de este servicio se la consulta ciega de estados desde el buzón de entrega (ver Manual de Usuario Buzón de Entrega). Pero también se pone a disposición de otras plataformas emisoras, con el fin de permitir consultas puntuales a sus usuarios. Debido a que la consulta podrá devolver más de una factura que cumpla la condición, al no poder garantizarse que el emisor de la factura a través del Buzón del emisor haya enviado la misma factura una sola vez, el documento Xml devuelto podrá contener más de un nodo SatusFeedback, uno por cada factura que cumpla la condición. A su vez cada factura podrá contener uno o varios nodos Feedback, en función del número de estados recibidos en el Hub para una factura, por tanto, se devuelve dicho histórico de estados. Los nodos Feedback deberán aparecer ordenados descendentemente (estado más moderno primero). El mensaje XML devuelto podrá contener información de trazabilidad sobre el fichero en el que viajo la factura solicitada en el nodo HubFeedback. La generación de este nodo solo se llevará a cabo si así se solicita en el documento XML que reciba como petición el Hub.

7 e.fact-webservices pàg 7/ Esquema de mensajes En este apartado se muestra el esquema que tienen que cumplir los mensajes XML entre el hub e.fact y las aplicaciones cliente Petición Para la búsqueda del estado de una factura es imprescindible suministrar todos los datos contemplados en los parámetros de petición descritos a continuación, e incluidos en el wsdl de arriba. String HUBusersenderid: Código direccionamiento completo del emisor de las facturas. Como se indica en la Guía de integración para plataforma privadas al hub e.fact, dichos códigos son asignados por las plataformas emisoras a sus usuarios. String HubInfoAdd: Si se recibe este elemento con el valor TRUE, se añadirá a la respuesta la información de trazabilidad sobre el intercambio que contenía la factura buscada (nodo HubFeedback ). String INVOICEnumber: Número de la factura a buscar. String INVOICEdate: Año fiscal de factura a buscar (Formato YYYY). String INVOICEsupplier: NIF del vendedor. String INVOICEbuyer: NIF del comprador. String INVOICEtotal: Importe total de la factura Respuesta El WebService devolverá un documento Xml que contendrá la información reflejada en el esquema que se describe a continuación. Dicho documento Xml coincide con el establecido para el envío de información de estados al Hub por parte de las plataformas adheridas al mismo (mensaje DeliveryFeedback ). El esquema del mensaje que contiene los datos de la respuesta del WS, es el siguiente: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema xmlns:xs=" elementformdefault="qualified"> <xs:element name="cif"> <xs:element name="deliveryfeedback"> <xs:documentation>remesa de Estados</xs:documentation> <xs:element name="statusfeedback" maxoccurs="unbounded"> <xs:documentation>estado</xs:documentation> <xs:element name="hubfeedback" minoccurs="0"> <xs:documentation>identificador del mensaje dentro del Hub</xs:documentation>

8 e.fact-webservices pàg 8/14 <xs:element name="hubid"> <xs:element name="hubtype" minoccurs="0"> <xs:element name="hubdate" minoccurs="0"> <xs:restriction base="xs:datetime"/> <xs:element name="hubstatus" minoccurs="0"> <xs:restriction base="xs:string"> <xs:enumeration value="rejected"/> <xs:enumeration value="delivered"/> </xs:restriction> <xs:element name="hubstatusdate" minoccurs="0"> <xs:restriction base="xs:datetime"/> <xs:element name="huberrorcode" minoccurs="0"> <xs:element name="hubfilename" minoccurs="0"> <xs:element name="hubsenderref" minoccurs="0"> <xs:element name="hubsenderid" minoccurs="0"> <xs:element name="hubrecipientid" minoccurs="0"> <xs:element name="invoicefeedback" minoccurs="0"> <xs:documentation>identificador de la factura</xs:documentation> <xs:element name="invoiceid"> <xs:element name="supplier">

9 e.fact-webservices pàg 9/14 <xs:documentation>vendedor</xs:documentation> <xs:element ref="cif"/> <xs:element ref="dept" minoccurs="0"/> <xs:element name="buyer"> <xs:documentation>comprador</xs:documentation> <xs:element ref="cif"/> <xs:element ref="dept" minoccurs="0"/> <xs:element name="invoicedate"> <xs:restriction base="xs:date"/> <xs:element name="feedback" maxoccurs="unbounded"> <xs:element name="status"> <xs:restriction base="xs:string"> <xs:enumeration value="accepted"/> <xs:enumeration value="rejected"/> <xs:enumeration value="paid"/> <xs:enumeration value="delivered"/> <xs:enumeration value="sent"/> <xs:enumeration value="registered"/> <xs:enumeration value="error"/> <xs:enumeration value="validated"/> </xs:restriction> <xs:element name="statusdate"> <xs:restriction base="xs:datetime"/> <xs:element name="reason"> <xs:element name="code"> <xs:element name="description" type="xs:string" minoccurs="0"/> <xs:element name="registernumber" type="xs:string" minoccurs="0"/> <xs:element name="paymentdate" type="xs:string" minoccurs="0"/> <xs:element name="validationresponse" type="validationresponsetype" minoccurs="0"/>

10 e.fact-webservices pàg 10/14 <xs:element name="dept" type="xs:string"/> <xs:complextype name="validationresponsetype"> <xs:any namespace="##other" processcontents="strict" minoccurs="0" maxoccurs="unbounded"/> </xs:schema> A continuación se muestra la representación gráfica del mensaje de respuesta:

11 e.fact-webservices pàg 11/ Consulta de códigos de direccionamiento (wshubdirectioncodesquery) Funcionalidad Mediante esta función, se pueden consultar los códigos de direccionamiento de las diversas administraciones públicas receptoras inscritas en e.fact. La consulta se puede realizar tanto por CIF, como por nombre de la entidad pública. En el caso de que haya más de un código para una misma búsqueda, el mensaje de respuesta contendrá todos los códigos localizados Esquema dels missatges En este apartado se muestra el esquema que tienen que cumplir los mensajes XML entre el hub e.fact y las aplicaciones cliente Petición Para invocar este WebService será necesario proporcionarle un mensaje XML que podrá contener uno de los siguientes criterios de selección: - Una lista de códigos de direccionamiento, par los cuales queremos conocer el resto de datos publicados (nombre, información adicional, NIF, etc.) - Una lista de códigos de plataforma, para los cuales queremos conocer sus códigos de direccionamiento. - Una lista de NIF para los cuales queremos conocer los diferentes códigos de direccionamiento asociados. - Si no se especifica ningún criterio, se devolverá el listado completo de códigos de direccionamiento. El esquema del mensaje que contiene los datos de la petición que se envía al WS, es el siguiente: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema xmlns:xs=" elementformdefault="qualified"> <xs:element name="hubcode"> <xs:element name="hubpartnerlistquery"> <xs:choice> <xs:element name="hubcodelist"> <xs:element ref="hubcode" maxoccurs="unbounded"/> <xs:element name="hubpartcodelist">

12 e.fact-webservices pàg 12/14 <xs:element ref="partcode" maxoccurs="unbounded"/> <xs:element name="hubpartaliaslist"> <xs:element ref="partalias" maxoccurs="unbounded"/> </xs:choice> <xs:element name="partalias"> <xs:element name="partcode"> </xs:schema> A continuación se muestra la representación gráfica del mensaje de petición: Respuesta El WebService devolverá los datos obtenidos dentro de un documento XML que seguirá el siguiente formato. Dentro del XML se incluyen dos campos para indicar la fecha de publicación del código en el Hub ( PartCreated ), y la fecha de última modificación del código dentro del Hub ( PartModified ). El esquema del mensaje que contiene los datos de la respuesta del WS, es el siguiente: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema xmlns:xs=" elementformdefault="qualified"> <xs:element name="hubpartner"> <xs:element ref="partner" maxoccurs="unbounded"/> <xs:element name="partaction">

13 e.fact-webservices pàg 13/14 <xs:documentation>acción a realizar (INSERT o DELETE)</xs:documentation> <xs:restriction base="xs:string"> <xs:enumeration value="delete"/> <xs:enumeration value="insert"/> </xs:restriction> <xs:element name="partalias"> <xs:documentation>nif o alias asociado al código</xs:documentation> <xs:element name="partid"> <xs:documentation>código direccionamiento completo</xs:documentation> <xs:element name="partinfo"> <xs:documentation>información adicional sobre el código</xs:documentation> <xs:element name="partname"> <xs:documentation>nombre asignado al código de direccionamiento</xs:documentation> <xs:element name="partner"> <xs:element name="hubcode"> <xs:documentation>código plataforma asignada por el Hub</xs:documentation> <xs:element ref="partid"/> <xs:element ref="partname"/> <xs:element ref="partinfo" minoccurs="0"/> <xs:element ref="partalias" minoccurs="0"/> <xs:element ref="partaction" minoccurs="0"/> <xs:element name="partcreated" minoccurs="0"> <xs:documentation>fecha publicaciónen ell Hub</xs:documentation> <xs:restriction base="xs:datetime"/> <xs:element name="partmodified" minoccurs="0"> <xs:documentation>fecha modificación en el Hub</xs:documentation>

14 e.fact-webservices pàg 14/14 <xs:restriction base="xs:datetime"/> </xs:schema> A continuación se muestra la representación gráfica del mensaje de respuesta ():