Canigó - Connector PICA-TRIBUTS

CONNECTOR PICA-TRIBUTS










Introducció

L'objectiu d'aquest connector ,es el de proporcionar accés als 3 grans serveis de consulta de dades fiscals que actualment ofereix la PICA. Aquests tres serveis són:

  • AEAT: Agència Estatal de l'Administració Tributària
  • ATC: Agència Tributària de Catalunya
  • TGSS: Tresoreria General de la Seguretat Social

a més també es troba integrat el servei AEAT_ATC_TGSS que sintetitza una petita suite de les modalitats de servei dels 3 productes anteriors.

Propòsit

El propòsit del connector és proporcionar una interfície funcional reduïda al connector de la Pica que simplifica l'utilització del servei de consulta de dades fiscals ofert per la generalitat.

Context i Escenaris d'ús

El connector PICA-TRIBUTS es troba dins els connectors de serveis funcionals de la Generalitat.

Versions i Dependències

En el present apartat es mostren quines són les versions i dependències necessàries per fer ús del Connector.

Les dependències descrites a la següent url són requerides per tal de fer funcionar el servei:
Dependències del Connector TRIBUTS

A qui va dirigit

Aquest document va dirigit als següents perfils:

  1. Programador. Per conèixer l'ús del connector.
  2. Arquitecte. Per conèixer quins són els components i la configuració del connector.

Documents i Fonts de Referència

[1] Guia d'ús de l'API del Connector PICA-TRIBUTS.
[2] Documentació funcional i tècnica del Connector PICA-TRIBUTS.

Descripció Detallada

Introducció

Com ja s'ha comentat aquest connector sintetitza peticions als tres grans serveis oferts per la PICA relatius a la consulta de dades fiscals.

Serveis

Servei AEAT (Agència Estatal de l'Administració Tributària)

La seva finalitat és l'obtenció de dades tributàries de l'AEAT per consultar, per part dels gestors públics, les dades relatives als contribuents que ofereix l'Agència Estatal de l'Administració Tributària
Per una descripció detallada del servei i de les seves modalitats es pot consultar el document "Guia d'us del servei AEAT_PICA v1.7.pdf" disponible en l'àrea privada de http://cttiprojectes.gencat.cat/web/otpica en la secció "productes Oferts -> Interoperabilitat -> AEAT"

Modalitats:

  • AEAT_PICA_C1: Està al corrent de pagament/ No està al corrent de pagament.
  • AEAT_PICA_C2: Les dades del certificat individual de renda.
  • AEAT_PICA_C3: Les dades identificatives del CIF o DNI/NIE corresponent.
  • AEAT_PICA_C4: Les dades del certificat de renda per a prestacions socials.
  • AEAT_PICA_C5: Les dades del certificat de renda d'agricultors.
  • AEAT_PICA_C6: Les dades del certificat de renda per a beques.
  • AEAT_PICA_C7: Les dades del certificat de renda per a beques anticipades.
  • AEAT_PICA_C8: Les dades del certificat de l'impost d'activitats econòmiques.

Totes les modalitats anteriors són síncrones.

Servei ATC (Agència Tributària de Catalunya)

El servei d'obtenció del certificat de deutes amb la Generalitat de Catalunya té com a objectiu poder consultar per part dels gestors públics les dades que ofereix l'Agència Tributària de Catalunya respecte a deutes amb la Generalitat.
Per una descripció detallada del servei i de les seves modalitats es pot consultar el document "Guia d'us del servei de l'ATCv1.4.3.pdf" disponible en l'àrea privada de http://cttiprojectes.gencat.cat/web/otpica en la secció "productes Oferts -> Interoperabilitat -> ATC"

Modalitats:

  • ATC_INF_DEUTES_TMP: Modalitat de servei asíncrona que retorna les dades d'un certificat de deutes amb la Generalitat de Catalunya.

Servei TGSS (Tresoreria General de la Seguretat Social)

El servei d'obtenció de dades de la seguretat social de la TGSS té com a objectiu poder consultar, per part dels gestors públics, les dades que ofereix la Tresoreria General de la Seguretat Social.
Per una descripció detallada del servei i de les seves modalitats es pot consultar el document "Guia d'us del servei de TGSS v1.6.pdf" disponible en l'àrea privada de http://cttiprojectes.gencat.cat/web/otpica en la secció "productes Oferts -> Interoperabilitat -> TGSS"

Modalitats:

  • TGSS_AL_CORRENT_PAGAMENT: Especifica si una persona o una organització té algun deute amb la seguretat social en el moment de fer la consulta.
  • TGSS_INFORME_SITUACIO: Aquest informe especifica si una persona cotitzava a una data determinada, per tant és un possible sinònim de si la persona treballava o no.
  • TGSS_ACREDITACIO_AGRARIA_PROPI: Aquest informe especifica les situacions de les acreditacions de jornades agràries en un període de temps determinat pels valors del filtre.

Servei AEAT_ATC_TGSS

L'objectiu del Servei de consulta de la situació de deute d'un contribuent respecte de AEAT, ATC i TGSS és l'agrupació dels productes AEAT (Agència Estatal de l'Administració Tributària), ATC(Agència Tributària de Catalunya) i TGSS (Tresoreria General de la Seguretat Social) en una sola consulta per a la obtenció de la situació de deute d'un contribuent a AEAT, ATC i TGSS. En concret, és l'agrupació de les modalitats següents:
-AEAT: Certificat d'obligacions tributàries (AEAT_PICA_C1)
-ATC: Informe de situació de deutes amb la Generalitat de Catalunya (ATC_INF_DEUTES_TMP)
-TGSS: Informe de situació de deutes de la TGSS (TGSS_AL_CORRENT_PAGAMENT)

Per una descripció detallada del servei i de les seves modalitats es pot consultar el document "Guia d'us del servei deutes del contribuent AEAT-ATC-TGSS v1.1.pdf" disponible en l'àrea privada de http://cttiprojectes.gencat.cat/web/otpica en la secció "productes Oferts -> Interoperabilitat -> AEAT_ATC_TGSS"

Modalitats:

  • AEAT_ATC_TGSS_CONSULTA_DEUTES: Modalitats de servei asíncrona que llença una petició de consulta sobre les modalitats anteriorment anomenades dels tres serveis de consulta de dades fiscals AEAT, ATC i TGSS.

Totes les modalitats anteriors són síncrones.

Arquitectura i Components

Interfícies i Components Genèrics

Es pot trobar tota la documentació JavaDoc i el codi font referent aquests components a les següents url's:

JavaDoc: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_3_15/canigo-connectors-root/canigo-connectors-pica-tributs/apidocs/index.html
Codi Font:  http://repos.canigo.ctti.gencat.cat/repository/maven2/canigo/connectors/canigo-connectors-pica-tributs/1.0.2/

Requeriments

El connector TRIBUTS és compatible amb les versions 1.5 o superior de Java. Per versions inferiors no és garantit el seu correcte funcionament.

Per tal de que el connector TRIBUTS funcioni correctament sobre l'aplicació que l'utilitzi, es s'ha de tenir configurat el servei connector genèric de la PICA 1.0.

Instal.lació i Configuració

Instal.lació

La instal.lació del connector requereix de la utilització de la llibreria 'canigo-connectors-pica-tributs' i les dependències indicades a l'apartat 'Introducció-Versions i Dependències'.

Per poder disposar del Connector PICA-TRIBUTS en una aplicació Canigó s'ha de modificar el pom.xml de l'aplicació per incloure la llibreria del Connector com a dependència.

<dependency>
        <groupId>canigo.connectors</groupId>
        <artifactId>canigo-connectors-pica-tributs</artifactId>
        <version>1.0.2</version>
</dependency>

També és necessari afegir una exclusió sobre la dependència de la PICA;

<dependency>
    <groupId>canigo.connectors</groupId>
	<artifactId>canigo-connectors-pica</artifactId>
	<version>1.0</version>
	<exclusions>
	        <exclusion>
				<groupId>xmlbeans</groupId>
	            <artifactId>xbean</artifactId>
	        </exclusion>
	</exclusions>
</dependency>

Configuració


Per poder configurar el connector TRIBUTS és necessari tenir configurat el connector genèric a la PICA.

<bean id="requeridor" class="cat.gencat.pica.peticio.core.beans.Requeridor" singleton="true">
<property name="fitxerSignatura" value="signatura.properties"> </property>
	<property name="idSolicitante" value="1DPGO049"></property>
	<property name="idTransmision" value="213421"></property>
	<property name="nombreSolicitante" value="CTTI"></property>
	<property name="password" value="password"></property>
	<property name="user" value="usuari"></property>
</bean>

<bean name="ProducteModalitatBase" abstract="true" class="cat.gencat.pica.peticio.core.beans.ProducteModalitat">
	<property name="passwordType" value="PasswordText"></property>
</bean>

<bean id="picaService" class="net.gencat.ctti.canigo.connectors.pica.impl.PicaServiceWrapper" singleton="false">
	<property name="axisDefinition" value="classpath:axis2client/"></property>

	<property name="loggingService" ref="loggingService"></property>
	<property name="requeridor" ref="requeridor"></property>
	<property name="modalitats">
		<map>
			...
		</map>
	</property>
</bean>


Com al final el connector PICA-TRIBUTS dona servei sobre quatre productes diferents es precisarà de la inicialització de quatre beans, un per cada servei. 

<bean id="aeatService" class="net.gencat.ctti.canigo.connectors.pica.tributs.aeat.impl.AeatConnectorImpl" singleton="false">
		<property name="picaService" ref="picaService"/>
		<property name="nifEmisor" value="[nifEmisor]" />
		<property name="nomEmisor_PCI" value="CONSORCI AOC" />
		<property name="nomEmisor_CAT635" value="CAT365" />
		<property name="finalitat" value="PROVES"/>
		<property name="urlPica" value="http://preproduccio.pica.intranet.gencat.cat/pica_cataleg/AppJava/services/" />
			<property name="funcionari" ref="funcionari" />

	</bean>
	
	<bean id="atcService" class="net.gencat.ctti.canigo.connectors.pica.tributs.atc.impl.AtcConnectorImpl" singleton="false">
		<property name="picaService" ref="picaService"/>
		<property name="nifEmisor" value="[nifEmisor]" />
		<property name="nomEmisor" value="CONSORCI AOC" />
		<property name="finalitat" value="PROVES"/>
		<property name="urlPica" value="http://preproduccio.pica.intranet.gencat.cat/pica_cataleg/AppJava/services/"/>
		<	<property name="funcionari" ref="funcionari" />
	</bean>
	
	<bean id="tgssService" class="net.gencat.ctti.canigo.connectors.pica.tributs.tgss.impl.TgssConnectorImpl" singleton="false">
		<property name="picaService" ref="picaService"/>
		<property name="nifEmisor" value="[nifEmisor]" />
		<property name="nomEmisor" value="CONSORCI AOC" />
		<property name="finalitat" value="PROVES"/>
		<property name="urlPica" value="http://preproduccio.pica.intranet.gencat.cat/pica_cataleg/AppJava/services/"/>
			<property name="funcionari" ref="funcionari" />
	</bean>
	
	<bean id="aeatAtcTgssService" class="net.gencat.ctti.canigo.connectors.pica.tributs.aeat_atc_tgss.impl.AeatAtcTgssConnectorImpl" singleton="false">
		<property name="picaService" ref="picaService"/>
		<property name="nifEmisor" value="[nifEmisor]" />
		<property name="nomEmisor" value="ODAE" />
		<property name="finalitat" value="PROVES"/>
		<property name="urlPica" value="http://preproduccio.pica.intranet.gencat.cat/pica_cataleg/AppJava/services/"/>
			<property name="funcionari" ref="funcionari" />
	</bean>

<bean id="funcionari" class="cat.gencat.pica.peticio.core.beans.Funcionari">
	<property name="nifFuncionario" value="nifFuncionari"/>
	<property name="nombreFuncionario" value="nombreFuncionari"/>
	<property name="emailFuncionario" value="emailFuncionario"/>
</bean>

NOTA: Es molt important que l'ordre de les propietats del bean en tots quatre beans, sigui l'especificat anteriorment.

Utilització del Connector


Exemple d'utilització d'una modalitat de Servei de AEAT

Referenciar al servei AEAT des de l'acció que es vulgui utilitzar (action-servlet-aaa.xml):

<property name="aeatConnector" ref="aeatService"></property>

En l'acció, s'hauran de crear els getters i setters corresponents per al connector de AEAT:

private AeatConnectorImpl aeatConnector;
public AeatConnectorImpl getAeatConnector() {
	return aeatConnector;
}

public void setAeatConnector(AeatConnectorImpl aeatConnector) {
	this.aeatConnector = aeatConnector;
}

En aquest cas d'exemple es consumirà la modalitat de servei AEAT_PICA_C1 que es correspon amb la consulta de les Obligacions Tributàries.
NOTA: Les dades de nom, cognom1 i 2, nom complet i el valor del document sobre l'exemple son inventades. 

DadesPeticioAEAT peticio = new DadesPeticioAEAT();
    peticio.setNom("Nom");
    peticio.setCognom1("cognom1");
    peticio.setCognom2("cognom2");
    peticio.setNomComplet("Nom Cognom1 Cognom2");
    peticio.setTipusDocument("NIF");
    peticio.setDocument("12345678B");
	
   	C1PICAResponse resposta = aeatConnector.ObligacionsTributaries(peticio);

Per més informació sobre les dades d'entrada i sortida d'aquesta modalitat es pot consultar el document "Guia d'us del servei AEAT_PICA v1.7.pdf"

Exemple d'utilització del servei ATC

Referenciar al servei ATC des de l'acció que es vulgui utilitzar (action-servlet-aaa.xml):

<property name="atcConnector" ref="atcService"></property>

En l'acció, s'hauran de crear els getters i setters corresponents per al connector de ATC:

private AtcConnectorImpl atcConnector;
public AtcConnectorImpl getAtcConnector() {
	return atcConnector;
}

public void setAtcConnector(AtcConnectorImpl atcConnector) {
	this.atcConnector = atcConnector;
}

En aquest cas d'exemple es consumirà la modalitat de servei ATC_INF_DEUTES_TMP que retorna les dades d'un certificat de deutes amb la Generalitat de Catalunya.

Donat que el servei ATC es consumeix de forma asíncrona la forma correcta per poder consumir-ho es realitza en 3 fases:
1.- Fer petició al Servei
2.- Testar l'estat de resolució de la petició
3.- Recuperar les dades de la petició

NOTA: Les dades de nom, cognom1 i 2, nom complet i el valor del document sobre l'exemple son inventades. 

DadesPeticioATC peticio = new DadesPeticioATC();
    	
    peticio.setIdioma("Català");
    peticio.setNom("Nom");
    peticio.setCognom1("Cognom1");
    peticio.setCognom2("Cognom2");
	peticio.setNomComplet("Nom Cognom1 Cognom2");
    peticio.setDocument("12341234D");
    peticio.setTipusDocument("NIF");
    DataResponse resposta = atcConnector.informeSituacioDeute(peticio); //<-- Petició al servei
    
    EstatAsincron estatResposta = atcConnector.getEstatInformeSituacioDeute(resposta.getResponse()); //<-- Comprovació estat petició
    int tempsEstimat = estatResposta.getTempsEstimatResposta();
  
	...
    	
    Informacio inf = atcConnector.getDadesInformeSituacioDeute(resposta.getServei()); //<-- Recuperació resposta a la petició

Per més informació sobre les dades d'entrada i sortida d'aquesta modalitat es pot consultar el document "Guia d'us del servei de l'ATCv1.4.3.pdf"

Exemple d'utilització d'una modalitat de Servei TGSS

Referenciar al servei TGSS des de l'acció que es vulgui utilitzar (action-servlet-aaa.xml):

<property name="tgssConnector" ref="tgssService"></property>

En l'acció, s'hauran de crear els getters i setters corresponents per al connector de TGSS:

private TgssConnectorImpl tgssConnector;
public TgssConnectorImpl getTgssConnector() {
	return tgssConnector;
}

public void setTgssConnector(TgssConnectorImpl tgssConnector) {
	this.tgssConnector = tgssConnector;
}

En aquest cas d'exemple es consumirà la modalitat de servei TGSS_AL_CORRENT_PAGAMENT que especifica si una persona o una organització té algun deute amb la seguretat social en el moment de fer la consulta.
NOTA: Les dades de nom, cognom1 i 2, nom complet i el valor del document sobre l'exemple son inventades. 

DadesPeticioTGSS peticio = new DadesPeticioTGSS();
    peticio.setNom("Nom");
    peticio.setCognom1("Cognom1");
    peticio.setCognom2("Cognom2");
    peticio.setNomComplet(null);
    peticio.setTipusDocumentacioInt(Constants.TGSS_NIF);
    peticio.setDocument("12345678B");

    RespostaAlCorrentDePagament resposta = tgssConnector.alCorrentPagament(peticio);

Per més informació sobre les dades d'entrada i sortida d'aquesta modalitat es pot consultar el document "Guia d'us del servei de TGSS v1.6.pdf"

Exemple d'utilització del servei AEAT_ATC_TGSS

Referenciar al servei AEAT_ATC_TGSS des de l'acció que es vulgui utilitzar (action-servlet-aaa.xml):

<property name="aatConnector" ref="aeatAtcTgssService"></property>

En l'acció, s'hauran de crear els getters i setters corresponents per al connector de AEAT_ATC_TGSS:

private AeatAtcTgssConnectorImpl aatConnector;
public AeatAtcTgssConnectorImpl getAtcConnector() {
	return aatConnector;
}

public void setAeatAtcTgssConnector(AeatAtcTgssConnectorImpl aeatAtcTgssConnector) {
	this.aeatAtcTgssConnector = aeatAtcTgssConnector;
}

En aquest cas d'exemple es consumirà la modalitat de servei AEAT_ATC_TGSS_CONSULTA_DEUTES que retorna les dades conjuntes de les modalitats següents:
-AEAT: Certificat d'obligacions tributàries (AEAT_PICA_C1)
-ATC: Informe de situació de deutes amb la Generalitat de Catalunya (ATC_INF_DEUTES_TMP)
-TGSS: Informe de situació de deutes de la TGSS (TGSS_AL_CORRENT_PAGAMENT)

Donat que el servei AEAT_ATC_TGSS es consumeix de forma asíncrona la forma correcta per poder consumir-ho es realitza en 3 fases:
1.- Fer petició al Servei
2.- Testar l'estat de resolució de la petició
3.- Recuperar les dades de la petició

NOTA: Les dades de nom, cognom1 i 2, nom complet i el valor del document sobre l'exemple son inventades. 

DadesPeticioAEAT_ATC_TGSS peticio = new DadesPeticioAEAT_ATC_TGSS();
			
	peticio.setIdioma("Català");
	peticio.setTipusDocumentacio(Constants.AAT_NIF);
	peticio.setDocument("12345678B");
	peticio.setNom("Nom");
	peticio.setNomComplet("Nom Cognom1 Cognom2");
	peticio.setCognom1("Cognom1");
	peticio.setCognom2("Cognom2");
			
	resposta = aeatAtcTgssConnector.consultaDeutes(peticio); //<-- Petició al servei
			
	EstatAsincron estatResposta = aeatAtcTgssConnector.getEstatConsultaDeutes(resposta.getResponse()); //<-- Consulta de l'estat de la petició
	int tempsEstimat = estatResposta.getTempsEstimatResposta();
	
	...

	RespostaConsultaDeutes dadesResposta = aeatAtcTgssConnector.getDadesConsultaDeutes(resposta.getServei()); //<-- recuperació de les dades de la petició

Per més informació sobre les dades d'entrada i sortida d'aquesta modalitat es pot consultar el document "Guia d'us del servei deutes del contribuent AEAT-ATC-TGSS v1.1.pdf"