Servicio de facturación electrónica del Sector Público de la CAE. Definición del API de Web Services. Interfaz ERP

Transcripción

1 Servici de facturación electrónica del Sectr Públic de la CAE Definición del API de Web Services Interfaz ERP

2 Índice 1 INTRODUCCIÓN ALCANCE CONSIDERACIONES GENERALES SERVICIOS WEB DEFINICIÓN DE SERVICIO WEB WSDL INTERACCIÓN CON LOS WEB SERVICES AUTENTICACIÓN Y CONTROL DE ACCESO IDENTIFICACIÓN DE LAS FACTURAS OBJETOS RETORNADOS POR LOS WEB SERVICES Objets retrnads pr el servici efacturaws - java Objets retrnads pr el servici efacturawsnet - <XML> SERVICIO WEB EFACTURAWS - JAVA Descripción Métds definids LOGIN Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación Expecificación de la librería LOGOUT Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación Expecificación de la librería SENDINVOICES Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETINVOICESDATA Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación ADDATTACHMENT Servici de facturación electrónica de la CAE Página 2 de 89

3 5.6.1 Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación LISTATTACHMENTS Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación DOWNLOADATTACHMENT Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SETCOMMENTS Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SETMETADATA Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETMETADATA Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETRECEIVEDINVOICES Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETSENTINVOICES Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETINVOICESDATASTATUS Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SETINVOICESDATASTATUS Descripción Servici de facturación electrónica de la CAE Página 3 de 89

4 Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación Estads permitids en el servici setinvicesstatus REJECTINVOICES Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETINVOICES Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SENDINVOICESSIGN Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SERVICIO WEB EFACTURAWSNET - <XML> LOGIN Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación LOGOUT Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SENDINVOICESBASE Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETINVOICESDATABASE Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación ADDATTACHMENTBASE Descripción Parámetrs de entrada Parámetrs de salida Servici de facturación electrónica de la CAE Página 4 de 89

5 6.5.4 Psibles códigs de terminación LISTATTACHMENTS Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación DOWNLOADATTACHMENTBASE Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SETCOMMENTS Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SETMETADATA Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETMETADATA Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación REJECTINVOICES Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETINVOICESDATASTATUS Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación SETINVOICESDATASTATUS Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETINVOICESBASE Descripción Parámetrs de entrada Parámetrs de salida Servici de facturación electrónica de la CAE Página 5 de 89

6 Psibles códigs de terminación GETSENTINVOICESBASE Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación GETRECEIVEDINVOICESBASE Descripción Parámetrs de entrada Parámetrs de salida Psibles códigs de terminación ANEXO A CONSTANTE TYPEID URL 87 Servici de facturación electrónica de la CAE Página 6 de 89

7 1 Intrducción Este dcument va dirigid especialmente al persnal técnic encargad del desarrll y/ mantenimient de ls sistemas externs que expltan y hacen us de la platafrma, puest que cntiene infrmación detallada y técnica del Sistema. La arquitectura del Sistema efactura, de frma resumida, cntiene ds móduls principales: Módul Web: Aplicación Web que da acces a las funcinalidades de la platafrma tant para ls clientes de la misma cm para ls clientes externs. Módul Central: Encargad de realizar tda la lógica de negci, tant de validación de ls dcuments recibids, cm de emisión de facturas custdia de dcuments. Cntiene a su vez ds móduls: Núcle: Este módul, denminad anterirmente frntend, prprcina la mayr parte de las funcinalidades del sistema efactura. Ls servicis Web definids en este módul pdrán ser invcads desde frntales dispnibles en las entidades prmtras. MOA (Módul de Operacines Asíncrnas): Este módul, denminad anterirmente backend, cntiene el cnjunt de prcess asíncrns que ejecutarán una serie de tareas necesarias para el crrect funcinamient del sistema. Estas tareas sn fundamentalmente la emisión de facturas y la ntificación de events a ls usuaris del sistema. Las Entidades Prmtras frecen este servici de facturación electrónica a sus clientes, llamadas Entidades Adscritas, mediante aplicacines Web aplicacines ERP, cnectadas al sistema central vía Web Services. Para ell Sistema efactura prprcina un API que cntienen ls web services destinads a ser expltads pr cada aplicación: WS-API ERP: API diseñad para ser expltad pr aplicacines ERP (web de escritri) para cnectar, la funcinalidad que prprcinan cm ERP a la entidad adscrita, cn la facturación electrónica frecida pr la platafrma. En este dcument se presentan en detalle cada un de ls métds frecids pr el WS-API ERP. 2 Alcance El bjetiv de este dcument es presentar en detalle cada un de ls métds frecids pr ls Web services destinad a ls ERP, describiend las peracines que frecen, ls parámetrs de entrada y salida y la frma de utilizarls. En primer lugar, se frece una pequeña intrducción sbre ls cncepts más imprtantes sbre Servicis Web, para pasar después a detallar ls Servicis Web de efactura que se emplean para la interrelación cn ls ERP y sus peracines. De cada una de estas peracines se indicarán ls parámetrs de entrada y salida, Servici de facturación electrónica de la CAE Página 5 de 89

8 y se describe brevemente su funcinamient. Ls parámetrs de salida hacen referencia a bjets Java que están recgids en el Javadc crrespndiente. Este dcument cntiene la descripción del interfaz ERP, y cubre la descripción de ls métds para la librería Java. 3 Cnsideracines generales Servicis Web Este capítul describe en detalle ls Web Services del Interfaz ERP que frman el cmpnente central del sistema efactura. 3.1 Definición de Servici Web Un Servici Web es un cmpnente sftware cn las siguientes características: Es accesible a través del interface SOAP (Simple Object Access Prtcl). Su interface se describe en un dcument WSDL (Web Service Descriptin Language). SOAP es un prtcl de mensajería XML que frma la base de ls Servicis Web. SOAP prprcina un mecanism simple y cnsistente que permite a una aplicación enviar mensajes XML a tra aplicación. Un mensaje SOAP es una transmisión desde un emisr SOAP a un receptr SOAP, y cualquier aplicación puede participar en este intercambi cm emisr receptr. SOAP es un prtcl cmpletamente independiente del prtcl de transprte subyacente, pr es ls mensajes SOAP se pueden intercambiar sbre HTTP, JMS prtcls de transprte de . Actualmente el prtcl HTTP es el únic sprtad pr el Sistema efactura. WSDL es un dcument XML que cntiene un cnjunt de definicines que describen un Servici Web. Prprcina tda la infrmación necesaria para acceder y utilizar un Servici Web. Un dcument WSDL describe qué hace el Servici Web, cóm se cmunica, y dónde reside. Usams el dcument WSDL en el mment del despliegue para crear nuestrs interfaces de servici WSDL El WSDL (Web Services Descriptin Language, Lenguaje de Descripción de Servicis Web) describe el cmprtamient de ls servicis Web e instruye en la frma de interactuar cn ells. Se muestra cm un archiv cn frmat XML para cada servici Web. 4 Interacción cn ls Web services A cntinuación pasams a detallar cóm se realiza la interacción cn ls Web services de efactura. Existe una librería cliente (Java) que sirve de unión entre el ERP que es rigen de la invcación y ls Web services prpiamente dichs. Esta librería psee un métd pr cada un de ls servicis que se frecen: lgin, Servici de facturación electrónica de la CAE Página 6 de 89

9 lgut,... Cada un de ests métds del cliente realiza una invcación a la peración crrespndiente del servici Web a través de una petición SOAP cn ls parámetrs prprcinads, y btiene la respuesta que devuelve en frma de bjet. En el siguiente gráfic se la interacción entre ls nuevs servicis Web y ls cmpnentes clientes que será facilitada para la integración cn ls misms. Junt cn las librerías cliente se suministra un bjet que cntiene tds ls códigs de errr catalgads, así cm ls valres admisibles para determinads parámetrs de ls Web Services. Para el cas de las aplicacines que invquen directamente al servici mediante SOAP sin utilizar las librerías clientes se suministrará la dcumentación prtuna. 4.1 Autenticación y cntrl de acces Para la autenticación en ls servicis frecids, se emplea un ticket de sesión que se btiene mediante un servici de lgin y que deberá emplearse en ls subsiguientes peticines al rest de métds que se frecen a través del servici efacturaws efacturaxmlws. Mediante el ticket el servici es capaz en td mment de identificar al usuari que realiza la petición. El usuari puede utilizar el ticket tdas las veces que sea precis dentr del períd de timeut establecid pr el servidr. Cuand se cnsidere que la sesión ha terminad, es precis realizar un lgut cn el fin de asegurarse que el ticket será invalidad. En tds ls demás servicis prprcinads se incluye un parámetr de tip cadena de text cn el ticket btenid mediante el métd lgin, el cual permite autenticar al usuari y mantener la sesión para el mism. Según se ha indicad anterirmente, dich ticket de sesión debe ser invalidad al terminar de trabajar Servici de facturación electrónica de la CAE Página 7 de 89

10 cn el mism mediante la invcación al servici lgut. N se servirá ninguna petición que n incluya un ticket de sesión válid. Se presenta a cntinuación un diagrama de secuencia que describe el prces de autenticación y psterir manej del ticket de sesión prprcinad pr el mism: Librería cliente efacturaws lgin(llave) ticket, siguientellave peticin1(ticket, dats) respuesta1 peticinn(ticket, dats) respuestan lgut(ticket) lgutok El métd lgin invalida la llave que se prprcina al mism y devuelve la que deberá emplearse en la próxima invcación al mism (mecanism One-timepasswrd), td est si el usuari tiene cnfigurad la pción OTP cm true (Opción pr defect), de l cntrari n se invalida. Para btener la primera llave es precis realizar el alta del servici a través del prtal de la Entidad Prmtra crrespndiente. Esta llave n estará en ningún cas relacinada cn el lgin y usuari de la entidad para prevenir psibles cass de phising. Además de este lgin hay dispnible tr tip de lgin que recibe cm parámetrs el cif, códig de la entidad prmtra y un passwrd, a cntinuación se presenta un diagrama de secuencia que describe el prces de autenticación y psterir manej del ticket de sesión prprcinad pr el mism: Servici de facturación electrónica de la CAE Página 8 de 89

11 Librería Cliente efacturaws Lgin(idUser, cdprmentity, passwrd) ticket peticin1(ticket,dats) respuesta1 peticinn(ticket,dats) respuestan lgut(ticket) lgutok 4.2 Identificación de las facturas Es necesari destacar que en tds ls servicis que desean cnsultar, actualizar el estad descargar facturas, la frma de identificar unívcamente una factura es indicand: guiddefinitiv ( númer definitiv de factura) y CIFPrveedr Id y TypeId Est es debid a que en efactura se utiliza una numeración para las facturas basada en un númer de serie (dependiente del tip de factura) y númer de factura crrelativ para cada prveedr. Para un mism prveedr, n pdrán existir ds facturas cn el mism númer de serie y númer de factura. La segunda pción es válida para enviar slicitar infrmación enviand un Id y su respectiva tiplgía, teniend en cuenta que typeid especifica qué tip de identificadr se está utilizand: ID_FISCAL, ID_INTERNO, ID_EXTERNO. De acuerd cn l anterir, para identificar una factura deberems indicar ls ds dats referids al principi de un apartad (guiddefinitiv - númer de serie- y CIFPrveedr). Respect a ls códigs que identificarán las facturas (guiddefinitiv), cnsiderams imprtante realizar las siguientes puntualizacines: A la hra de imprtar una factura mediante el servici sendfile, habrá que indicar en el camp Invice/GUID del XML en frmat UBL1.0 el códig de dicha factura en el ERP (idfacturaerp). Servici de facturación electrónica de la CAE Página 9 de 89

12 Una vez imprtada una factura (servici sendfile) será precis invcar al servici getdefinitiveguids para btener el identificadr que se ha asignad a la factura tras su emisión, guiddefinitiv, frmad pr un númer de serie y códig. Un mism prveedr n puede tener ds facturas cn la misma serie y códig de factura, pr l que ests dats (númer de serie y códig de factura más el CIF del prveedr) serán ls utilizads en el rest de servicis para acceder a las facturas. Ests guiddefinitivs serán ls que habrá que prprcinar a ls servicis en el parámetr guiddefinitiv. En el siguiente diagrama se muestra el prces de enví de una factura, la recuperación de su GUIDdefinitiv y la realización de una peración referente a dicha factura: <Invice>... <GUID>FP-12345</GUID>... </Invice> Librería cliente efacturaws sendfile(ticket, XML_factura) sendfileok FP getdefinitiveguids(ticket, idfacturaerp, cifusuari) GUIDdefinitiv peticinn(ticket, GUIDdefinitiv, cifprveedr) respuestan 2038F lgut(ticket) lgutok 4.3 Objets retrnads pr ls Web Services En las versines anterires a la v2.1 de la platafrma, tds ls bjets retrnads pr ls servicis web de efactura eran bjets Bean, es decir, bjets que cntienen dats y métds de acces a ls misms, de md que la infrmación retrnada esté claramente tipada y definida. Desde dicha versión, se ha cread un nuev servici efacturaxmlws que permite acceder a las funcinalidades para ERP de la platafrma utilizand XML en lugar de bjets Bean. La lógica de negci que atiende dichas peticines es la misma que Servici de facturación electrónica de la CAE Página 10 de 89

13 para el servici efacturaws, cambiand únicamente la frma de realizar las cnsultas y de tratar las respuestas del servici Objets retrnads pr el servici efacturaws - java El bjet devuelt pr el Web service tiene siempre tres métds, geterrr, getsubcde y getmessage que devuelve el resultad de la invcación al servici, así cm infrmación adicinal sbre ls errres que se hayan pdid prducir en la misma. Mediante el métd geterrr se puede saber si la peración slicitada ha terminad crrectamente n. En cas de haber currid un errr, mediante getsubcde es psible btener un códig asciad al tip de errr y mediante getmessage se btiene una explicación textual de la causa del errr. Adicinalmente, el bjet devuelt pr el servici puede cntener infrmación adicinal sbre el resultad de la peración slicitada. Ls códigs devuelts pr ls Web Services están establecids de anteman para que las aplicacines invcantes sean capaces de decidir qué cmprtamient deben seguir a partir de ls misms. Ls bjets de resultad pueden ser Bean simples (cn ls tres métds de acces al resultad de la invcación del servici más ls métds de acces a ls dats), bien bjets BeanSet, cmpuests pr ls tres métds de acces al resultad de la invcación del servici más un métd que devlverá un vectr de bjets Bean cn la infrmación slicitada. Nótese que únicamente el bjet devuelt directamente pr el Web service cntará cn la infrmación del resultad de la invcación, en cas de que éste cntenga un vectr de bjets Bean, ésts cntendrán slamente la infrmación prprcinada pr el servici Objets retrnads pr el servici efacturawsnet - <XML> Este servici puede retrnar bjets de ds tips: 1. Un java.lang.string cn frmat XML que entre trs cntendrá una rama bean que infrmará sbre la terminación de la invcación: errr: ns dirá si se ha prducid un errr en la invcación n, pudiend tmar cm valres false true. subcde: puede tmar valres numérics y en cas de errr cntendrá un códig asciad al tip de errr message: tmará valres de cadena y en cas de errr cntendrá una explicación cntextual de la causa del errr. 2. javax.activatin.datahandler: que cntendrá un archiv en cas de errr saltará una excepción cn un mensaje descriptiv del errr si se cnce. Servici de facturación electrónica de la CAE Página 11 de 89

14 5 Servici Web efacturaws - java Descripción A cntinuación, se muestra una descripción detallada de ls métds que frece el Web service efacturaws. Para cada un de ls métds se indica: 1. Una breve descripción funcinal del mism 2. Sus parámetrs de entrada (clase y nmbre del parámetr), descrits en el mism rden que tienen en la declaración del métd, cn una descripción funcinal de ls misms. En el cas de que sus valres estén actads, un listad de dichs valres. 3. Su parámetr de salida, indicand la clase a la que pertenecen y describiend su funcinalidad. La infrmación de ests bjets se cmpleta cn la Javadc crrespndiente. Psibles códigs de terminación, indicand ls valres que pueden tmar ls camps descrits en el apartad 4.3 para dich métd Métds definids A cntinuación se describen en detalle tds ls métds que frman parte del Servici Web. Para más infrmación cnsultar el javadc. 5.2 Lgin Descripción Este métd identifica y autentica ante Sistema efactura a la entidad adscrita que desea utilizar ls servicis de la platafrma mediante el WS-API ERP. Permite a una entidad adscrita btener un ticket de sesión válid para ser utilizad durante un tiemp limitad en las siguientes llamadas. Para ell debe prprcinarse una cntraseña que fue prprcinada pr el usuari a la entidad prmtra mediante el módul web. Para infrmación más detallada sbre el mecanism de autenticación y cntrl de acces del Web service efacturaws, cnsultar el apartad 4.1 Autenticación y Cntrl de Acces. Si el usuari ya está lgad, pr ejempl mediante tra petición de lgin anterir, el nuev lgin n inhabilita el ticket previ, pr l que la sesión anterir se puede seguir utilizand. Servici de facturación electrónica de la CAE Página 12 de 89

15 5.2.2 Parámetrs de entrada Parámetr Obligat ri (S/N) Descripción usercif S java.lang.string que cntiene una cadena de text que representa el identificadr de la entidad adscrita (CIF, NIE, NIF ). cdprmentity S java.lang.string que cntiene una cadena de text que representa el códig de la entidad prmtra a la que se le prprcin la cntraseña. passwrd S java.lang.string que cntiene una cadena de text cn la cntraseña que se prprcinó a la entidad prmtra Parámetrs de salida Parámetr LginBean Descripción Entre sus atributs cntiene un ticket válid para las siguientes peticines, en esta casión la llave cifrada tiene el valr null. Así cm infrmación sbre el resultad de la invcación al Web service que cntendrá la infrmación de si la peración se ha cmpletad cn éxit si pr el cntrari ha currid algún errr, en cuy cas se indicará el errr en un mensaje Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde WS_ERROR_002 Errr intern realizand la peracin slicitada WS_ERROR_006 El lgin prprcinad es errne Expecificación de la librería Al igual que para el rest de metóds la librería JAVA prprcina algunas ventajas para el usuari sbre el us direct de la peración del web services. Servici de facturación electrónica de la CAE Página 13 de 89

16 Este métd además de identifica y autentica ante Sistema efactura a la entidad adscrita almacena internamente el ticket de frma que las demás funcines l utilizan sin necesidad de que el usuari tenga que estar manejand el ticket en las siguientes peticines. Pr ell, esta función también requiere que se le pase cm parámetr de entrada la url de cnexión cn ls web services del WS-API ERP. 5.3 Lgut Descripción Mediante este métd se descnecta del Sistema efactura Parámetrs de entrada Parámetr Obligatri (S/N) Descripción ticket S java.lang.string cntiene una cadena cn frmat XML Parámetrs de salida Parámetr LgutBean Descripción Objet LgutBean que envía la respuesta al cliente Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde WS_ERROR_002 Errr intern realizand la peracin slicitada Expecificación de la librería Al igual que para el rest de métds la librería JAVA prprcinadas también prprcina esta, aprtand algunas ventajas para el usuari sbre el us direct de la peración del web services. Servici de facturación electrónica de la CAE Página 14 de 89

17 Este métd además de identifica y autentica ante Sistema efactura a la entidad adscrita almacena internamente el ticket de frma que las demás funcines l utilizan sin necesidad de que el usuari tenga que estar manejand el ticket en las siguientes peticines. Pr ell, esta función también requiere que se le pase cm parámetr de entrada la url de cnexión cn ls web services del WS-API ERP. 5.4 sendinvices Descripción Este servici permite la imprtación de un ficher XML cn una factura en frmat FACTURAE32, bien un archiv zip cn varias facturas en dichs frmats. Devuelve un bjet SendFileBeanSet que aprta infrmación sbre las facturas imprtadas y el estad de la imprtación. Ls estads en ls que puede quedar la factura tras la imprtación están definids de anteman de tal frma que a partir de esta infrmación la aplicación pueda decidir cm cmprtarse al respect. El sistema emitirá autmáticamente las facturas incrpradas mediante este métd, asignándles númer de serie y factura (salv errr de frmat de las mismas del prces de emisión) Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. javax.activatin.datahandler ficherentrada : DataHandler cn el ficher de facturas a imprtar. java.lang.string tipfactura: Tip de factura que se desea imprtar a efactura. Pdrá tmar ls valres 380 para facturas, 389 para autfacturas, bien 384 para rectificativas, valres tds ells catalgads en archiv de cnstantes (cnstantes WS_INVOICE_TYPE_FACTURA, WS_INVOICE_TYPE_AUTOFACTURA, WS_INVOICE_TYPE_FACTURA_RECTIFICATIVA, WS_INVOICE_TYPE_AUTOFACTURA_RECTIFICATIVA). Para el cas de las facturas rectificativas, se indica siempre el tip 384 siend el sistema internamente quien detecta si se trata de una factura de una autfactura a partir del códig de la factura que se pretende rectificar. Ls valres de este camp n se chequean (se cge el tip de factura directamente de la factura), únicamente se tiene en cuenta si se pasa 1 y la factura n es factura 4 y n es autfactura. De tds mds, se recmienda mantener la especificación cm está y estudiar el validar ests valres. Servici de facturación electrónica de la CAE Página 15 de 89

18 java.lang.string frmat: Frmat en que sean incrprar al sistema las facturas. Únicamente se permiten ls siguientes valres FACTURAE32 valres catalgads en archiv de cnstantes. IDENTIFICADOR LITERAL CM10 CM10 FACTURAE30 FACTURAE 3.0 FACTURAE31 FACTURAE 3.1 FACTURAE32 FACTURAE 3.2 PROPIETARIO Frmat prpietari UBL10 UBL 1.0 Ests frmats se encuentran cnfigurads en la tabla frmat Parámetrs de salida Devuelve un bjet SendFileBeanSet cn infrmación sbre el resultad de la invcación al Web service y un vectr de bjets SendFileBean cn la infrmación particular del resultad de la imprtación de cada una de las facturas imprtadas. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs. En este cas cncret, es necesari distinguir entre el resultad de la invcación al servici (btenida a partir de ls métds heredads de la clase Bean y que puede tmar ls valres descrits en el siguiente punt) y de la imprtación de cada una de las facturas del zip enviad (descrit en cada un de ls bjets SendFileBean devuelts pr el servici) Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 WS_ERROR_003 WS_ERROR_007 WS_ERROR_012 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración slicitada El ticket n es crrect Ls parámetrs de la llamada n sn crrects Ya existen facturas cn las series númer de factura slicitadas Servici de facturación electrónica de la CAE Página 16 de 89

19 WS_ERROR_014 WS_ERROR_017 WS_ERROR_018 WS_ERROR_019 Debe cnfigurar el separadr entre la serie y el númer de la factura Errr cn el prefij serie. Tiene que tener entre 1 y 4 caracteres alfanumerics Errr, el prefij serie n está asciad a la delegación crrespndiente Errr cn el prefij serie 5.5 getinvicesdata Descripción Este servici puede ser invcad para descargar facturas que han sid emitidas en el sistema. Permite btener un archiv zip cn las facturas slicitadas a través de su GUIDdefinitiv Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. java.lang.string [ ] guidsdefinitivs: Identificadr universal de la facturas que se quieren descargar (btenid mediante getdefinitiveguids).. java.lang.string [ ] CIFsPrveedr: CIF del prveedr de la facturas que se quieren descargar. Es necesari crear una entrada en este vectr pr cada un de ls guiddefinitivs indicads en el anterir parámetr. java.lang.string frmat: Frmat en que sean descargar las facturas indicadas. Se permiten ls siguientes valres catalgads en archiv de cnstantes: IDENTIFICADOR LITERAL CM10 CM10 COPIA Cpia del riginal firmada digitalmente PDF Un SOLO ficher PDF PROPIETARIO Frmat prpietari UBL10 UBL 1.0 FACTURAE30 FACTURAE 3.0 FACTURAE31 FACTURAE 3.1 FACTURAE32 FACTURAE 3.2 Ests frmats prvienen de la tabla frmat Parámetrs de salida Devuelve un bjet DataHandlerBean cn infrmación del resultad de la invcación al servici y un DataHandler cn un zip que cntiene ls XMLs en el frmat seleccinad de las facturas que se están slicitand mediante su Servici de facturación electrónica de la CAE Página 17 de 89

20 GUIDdefinitiv. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 WS_ERROR_003 WS_ERROR_004 WS_ERROR_007 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración slicitada El ticket n es crrect Acces n permitid para ls GUID slicitads GUID inexistentes Ls parámetrs de la llamada n sn crrects 5.6 addattachment Descripción Servici que permite adjuntar un ficher a una factura existente en el sistema. Puede usarse para asciar a una factura fichers que permitan aclarar su cntenid que pr cualquier causa se desea que permanezcan asciads a la misma y accesibles desde su detalle. N hay límite en el númer de fichers que se pueden adjuntar a una factura, si bien hay un límite en tamañ ttal de adjunts a una factura (en la actualidad, 512k) Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. java.lang.string guiddefinitiv: Identificadr universal de la factura a la que se quiere adjuntar el archiv (btenid mediante el métd getdefinitiveguids). javax.activatin.datahandler ficherentrada: Objet DataHandler cn el ficher que se desea adjuntar. java.lang.string descripcin: Descripción del adjunt. java.lang.string nmbreficher: Nmbre del ficher que se adjunta. Servici de facturación electrónica de la CAE Página 18 de 89

21 java.lang.string CIFPrveedr: CIF del prveedr de la facturas que se quieren cnsultar Parámetrs de salida Un bjet AddAttachmentBean cn infrmación sbre el resultad de la invcación al Web service y sbre el resultad de la inclusión del ficher adjunt. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 WS_ERROR_003 WS_ERROR_004 WS_ERROR_007 WS_ERROR_010 WS_ERROR_025 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración slicitada El ticket n es crrect Acces n permitid para ls GUID slicitads GUID inexistentes Ls parámetrs de la llamada n sn crrects N se ha pdid btener el identificadr de la factura Errr. Se ha ha intentad adjuntar un ficher a una factura en custdia El bjet retrnad pr este métd, además de la infrmación genérica sbre el resultad de la invcación al Servici web, psee ds camps para devlver infrmación específica sbre el resultad de la peración (errroperativa, messageoperativa). Si errroperativa es true, significa que el ficher n se ha adjuntad debid al errr indicad en messageoperativa. 5.7 listattachments Descripción Métd de cnsulta que devuelve una lista cn la infrmación de ls fichers adjunts de una factura determinada. Servici de facturación electrónica de la CAE Página 19 de 89

22 5.7.2 Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. java.lang.string guiddefinitiv: Identificadr universal de la factura a la que se quiere adjuntar el archiv (btenid mediante el métd getdefinitiveguids). java.lang.string CIFPrveedr: CIF del prveedr de la facturas que se quieren cnsultar Parámetrs de salida Un bjet AttachmentFileBeanSet cn infrmación del resultad de la invcación al servici y un vectr de bjets AttachmentFileBean que cntendrán infrmación acerca de s fichers adjunts de la factura cnsultada. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 WS_ERROR_003 WS_ERROR_004 WS_ERROR_007 WS_ERROR_010 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración slicitada El ticket n es crrect Acces n permitid para ls GUID slicitads GUID inexistentes Ls parámetrs de la llamada n sn crrects N se ha pdid btener el identificadr de la factura Servici de facturación electrónica de la CAE Página 20 de 89

23 5.8 dwnladattachment Descripción Métd que permite descargar un ficher adjunt, indicand la factura a la que pertenece y el númer de adjunt Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. java.lang.string guiddefinitiv: Identificadr universal de la factura de la que se quiere descargar el archiv (btenid mediante el métd getdefinitiveguids). java.lang.lng idadjunt: Númer de adjunt de dicha factura que se desea descargar. java.lang.string CIFPrveedr: CIF del prveedr de la facturas que se quieren cnsultar Parámetrs de salida Un bjet DataHandlerBean cn infrmación del resultad de la invcación al servici y el ficher adjunt slicitad. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 WS_ERROR_003 WS_ERROR_004 WS_ERROR_007 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración slicitada El ticket n es crrect Acces n permitid para ls GUID slicitads GUID inexistentes Ls parámetrs de la llamada n sn crrects Servici de facturación electrónica de la CAE Página 21 de 89

24 WS_ERROR_010 WS_ERROR_011 N se ha pdid btener el identificadr de la factura N se ha pdid btener el cntenid del ficher adjunt 5.9 setcmments Descripción Servici que permite insertar una bservacin a una factura indicand el guiddefinitiv, el cifprveedr de esta, el tip de bservación y el text de la bservación Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. java.lang.string guiddefinitiv: Identificadr universal de la factura a la que se quiere establecer la bservación (btenid mediante el métd getdefinitiveguids). java.lang.string cifprveedr: CIF del prveedr de la factura a la que se quiere establecer la bservación. java.lang.string cmmenttype: Identificadr del tip de bservación. Ha de ser un de ls siguientes valres: 1 bservación de rechaz 2 bservación de e 3 bservación de recepció receptr). 4 ). bservación de cncept java.lang.string cmment: Text de la bservación Parámetrs de salida Un bjet CmmentsBeanSet cn infrmación sbre el resultad de la invcación al Web service así cm un vectr de bjets CmmentsBean cn infrmación de la bservación insertada. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del Servici de facturación electrónica de la CAE Página 22 de 89

25 mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 WS_ERROR_003 WS_ERROR_004 WS_ERROR_007 WS_ERROR_015 WS_ERROR_010 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración slicitada El ticket n es crrect Acces n permitid para ls GUID slicitads GUID inexistentes Ls parámetrs de la llamada n sn crrects Tip de bservación n permitida N se ha pdid btener el identificadr de la factura 5.10 setmetadata Descripción Esta peración permite asciar infrmación adicinal (metadat) a un dcument, de frma que sea almacenada pr la platafrma para su psterir cnsulta mdificación. La infrmación almacenada se cmpne de una pareja: clave, valr. Utilizándse la clave cm identificadr del tip de infrmación adicinal, pr ejempl: Fecha Registr, actuand valr cm la infrmación adicinal, pr ejempl: Si en el mment de asciar a un dcument un metadat que ya tiene asciad, existe un metadat cn la misma clave, es decir, dich dcument ya tiene infrmación asciada a la misma clave, el valr será remplazad Las limitacines de la infrmación almacenada sn las siguientes: 20 byte (alfanumérics) para la clave infrmada. 100 byte (alfanumérics) para el valr infrmad. En ambs cass se prhiben ls caracteres rars:?! [ ]... y n se recmienda el us de tildes Parámetrs de entrada Parámetr Obligatri (S/N) Descripción Servici de facturación electrónica de la CAE Página 23 de 89

26 ticket S java.lang.string ticket de sesión válid que autriza la peración. keydata S java.lang.string Nmbre de la infrmación adicinal, que se utilizará cm clave para recuperar el valr psteriremente. valuedata S java.lang.string Valr de la infrmación adicinal asciad a keydata. typeid S java.lang.string Categrización del tip de identificadr usad para ubicar la las facturas, psibles valres ver anex A. ids S java.util.list Lista de identificadres de dcuments, cuy valr será asciad al typeid. sellercif N java.lang.string Valr del CIF del prveedr, necesari para identifica unívcamente una factura si cm typeid se ha especificad ID_FISCAL Parámetrs de salida Parámetr IdInviceBea nset Descripción Un bjet cn infrmación sbre el resultad de la invcación al Web service así cm un vectr de bjets IdInviceBean cn infrmación de las facturas relacinadas a la inserción. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde WS_ERROR_002 Errr intern realizand la peración slicitada WS_ERROR_003 WS_ERROR_023 El ticket n es crrect Intent de acces ilegal desde un usuari cn cif:.. WS_ERROR_028 Errr. Tip de identificadr slicitad inexistente. Servici de facturación electrónica de la CAE Página 24 de 89

27 5.11 getmetadata Descripción Esta peración permite btener el valr de la infrmación adicinal (metadat) asciada a un dcument. Si el dcument n cntiene ninguna infrmación adicinal cn la clave especificada la peración n devlverá nada Parámetrs de entrada Parámetr Obligatri (S/N) Descripción ticket S java.lang.string ticket de sesión válid que autriza la peración. keydata S java.lang.string Nmbre de la infrmación adicinal, que se utilizará cm clave para recuperar el valr psteriremente. typeid S java.lang.string Categrización del tip de identificadr usad para ubicar la las facturas, psibles valres ver anex A. Ids S java.util.list Lista de identificadres de dcuments, cuy valr será asciad al typeid. sellercif N java.lang.string Valr del CIF del prveedr, necesari para identifica unívcamente una factura si cm typeid se ha especificad ID_FISCAL Parámetrs de salida Un bjet IdInviceBeanSet cn infrmación sbre el resultad de la invcación al Web service así cm un vectr de bjets IdInviceBean cn infrmación de las facturas relacinadas a la inserción. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración Servici de facturación electrónica de la CAE Página 25 de 89

28 WS_ERROR_003 slicitada El ticket n es crrect WS_ERROR_023 Intent de acces ilegal desde un usuari cn cif:.. WS_ERROR_028 Errr. Tip de identificadr slicitad inexistente getreceivedinvices Descripción Este servici devuelve la relación de facturas recibidas entre ds fechas indicadas y que están en un estad determinad. Las facturas se devuelven en el frmat especificad códificadas en frmat binari DataHandler (más eficiente que Base64) en un ficher ZIP, en cas de n especificar ningún frmat se devuelve una clección de beans que resumen el cntenid de la factura. Tdas las facturas devueltas quedan marcadas en el servidr cm descargadas autmáticamente pr ERP. El parámetr de tip blean nlynew permite filtrar de la relación de facturas recibidas que cumplen el filtr aquéllas que n han sid descargadas anterirmente desde ERP Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. java.util.date initdate: Fecha inicial de interval de búsqueda de facturas recibidas. java.util.date enddate: Fecha final de interval de búsqueda de facturas recibidas. int statuscde: Estad de la factura. java.lang.string dwnladfrmat: Frmat en que sean descargar las facturas indicadas. Se permiten ls siguientes valres catalgads en archiv de cnstantes: IDENTIFICADOR LITERAL CM10 CM10 COPIA Cpia del riginal firmada digitalmente PDF Un SOLO ficher PDF UBL10 UBL 1.0 FACTURAE30 FACTURAE 3.0 FACTURAE31 FACTURAE 3.1 FACTURAE32 FACTURAE 3.2 Ests frmats prvienen de la tabla frmat. blean nlynew: Valr blean que indica si se desean descargar tdas las facturas recibidas entre initdate y enddate y que aún n han sid descargadas pr el ERP (valr true) bien si se desean descargar tdas las Servici de facturación electrónica de la CAE Página 26 de 89

29 facturas cmprendidas entre dichas fechas independientemente de si han sid descargadas cn anteriridad (valr false) Parámetrs de salida Un bjet InviceDataBeanSet cn infrmación sbre el resultad de la invcación al Web service así cm un vectr de bjets InviceDataBean cn infrmación de las facturas recibidas, un bjet DataHandler que cntendrá un archiv ZIP cn las facturas recibidas, un blean que indicara si existen mas facturas pendientes pr descargar. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 WS_ERROR_002 WS_ERROR_003 WS_ERROR_024 WS_ERROR_027 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde Errr intern realizand la peración slicitada El ticket n es crrect Errr al intentar descargar facturas en frmat:.. Warning. N existen dats para ls parámetrs slicitads 5.13 getsentinvices Este servici devuelve la relación de facturas enviadas entre ds fechas indicadas y que están en un estad determinad. Las facturas se devuelven en el frmat especificad códificadas en frmat binari DataHandler (más eficiente que Base64) en un ficher ZIP, en cas de n especificar ningún frmat se devuelve una clección de beans que resumen el cntenid de la factura. Tdas las facturas devueltas quedan marcadas en el servidr cm descargadas autmáticamente pr ERP. El parámetr de tip blean nlynew permite filtrar de la relación de facturas enviadas que cumplen el filtr aquéllas que n han sid descargadas anterirmente desde ERP Parámetrs de entrada Servici de facturación electrónica de la CAE Página 27 de 89

30 Parámetr Obligatri (S/N) Descripción initdate S java.util.date Fecha inicial de interval de búsqueda de facturas enviadas. enddate S java.util.date Fecha final de interval de búsqueda de facturas enviadas. statuscde S int Estad en el que deben estar las facturas enviadas. dwnladfr mat S java.lang.string Frmat en que sean descargar las facturas indicadas. Se permiten ls siguientes valres catalgads en archiv de cnstantes. nlynew S blean Indica si se desean descargar tdas las facturas enviadas entre initdate y enddate y que aún n han sid descargadas pr el ERP (valr true) bien si se desean descargar tdas las facturas cmprendidas entre dichas fechas independientemente de si han sid descargadas cn anteriridad (valr false). IDENTIFICADOR LITERAL CM10 CM10 COPIA Cpia del riginal firmada digitalmente PDF Un SOLO ficher PDF UBL10 UBL 1.0 FACTURAE30 FACTURAE 3.0 FACTURAE31 FACTURAE 3.1 FACTURAE32 FACTURAE Parámetrs de salida Parámetr InviceDataBea nset Descripción infrmación sbre el resultad de la invcación al Web service así cm un vectr de bjets InviceDataBean cn infrmación de las facturas recibidas, un bjet DataHandler que cntendrá un archiv ZIP cn las facturas recibidas, un blean que indicara si existen mas facturas pendientes pr descargar. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: Servici de facturación electrónica de la CAE Página 28 de 89

31 CÓDIGO DE TERMINACIÓN WS_ERROR_001 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici el servici n respnde WS_ERROR_002 Errr intern realizand la peración slicitada WS_ERROR_003 El ticket n es crrect WS_ERROR_024 Errr al intentar descargar facturas en frmat: getinvicesdatastatus Descripción Servici que permite btener el estad de un grup de facturas Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. java.lang.string typeid: Categrización del tip de identificadr usad para ubicar la las facturas, psibles valres ver anex A. java.util.list ids: Lista de ids de facturas, cuy valr será asciad al typeid. java.lang.string sellercif: Valr del CIF del prveedr, necesari para identifica unívcamente una factura si cm typeid se ha especificad ID_FISCAL Parámetrs de salida Un bjet InviceStatusDataBeanSet cn infrmación sbre el resultad de la invcación al Web service así cm un vectr de bjets InviceStatusDataBean cn infrmación de las factutras cnsultadas. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici Servici de facturación electrónica de la CAE Página 29 de 89

32 el servici n respnde WS_ERROR_002 WS_ERROR_003 Errr intern realizand la peración slicitada El ticket n es crrect WS_ERROR_023 Intent de acces ilegal desde un usuari cn cif:.. WS_ERROR_028 Errr. Tip de identificadr slicitad inexistente setinvicesdatastatus Descripción Servici que permite cambiar el estad de una factura varias facturas, indicand el id, y su tip de Identificadr de ID Parámetrs de entrada java.lang.string ticket: ticket de sesión válid. int statuscde: Estad de la factura. java.lang.string typeid: Categrización del tip de identificadr usad para ubicar la las facturas, psibles valres ver anex A. java.util.list ids: Lista de ids de facturas, cuy valr será asciad al typeid. java.lang.string sellercif: Valr del CIF del prveedr, necesari para identifica unívcamente una factura si cm typeid se ha especificad ID_FISCAL Parámetrs de salida Un bjet InviceStatusDataBeanSet cn infrmación sbre el resultad de la invcación al Web service así cm un vectr de bjets InviceStatusDataBean cn infrmación de las factutras cnsultadas. Cnsultar la Javadc al respect para más infrmación sbre este bjet y sus miembrs Psibles códigs de terminación En el cas de que la peración se haya realizad crrectamente, el camp errr del bjet devuelt pr el servici (se puede cnsultar cn el métd geterrr del mism) será false. En cas cntrari, para esta peración se cntemplan ls siguientes mensajes de errr: CÓDIGO DE TERMINACIÓN WS_ERROR_001 LITERAL DESCRIPTIVO Falta de cmunicación cn el servici Servici de facturación electrónica de la CAE Página 30 de 89