Consulta-Nif

La AEAT (Agencia Tributaria Española) cuenta con un API SOAP donde poder consultar la calidad de la identificación de personas por NIF+Nombre.

El origen de este proyecto se encuentra en un artículo publicado en http://groovy-lang.gitlab.io/101-scripts/ws/consulta_nif.html

Básicamente el SOAP definido por la AEAT tiene este aspecto:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:vnif="http://www2.agenciatributaria.gob.es/static_files/common/internet/dep/aplicaciones/es/aeat/burt/jdit
/ws/VNifV2Ent.xsd">
<soapenv:Header/>
<soapenv:Body>
<vnif:VNifV2Ent>
<vnif:Contribuyente>
<vnif:Nif>99999999R</vnif:Nif>
<vnif:Nombre>ESPAÑOL ESPAÑOL JUAN</vnif:Nombre>
</vnif:Contribuyente>
</vnif:VNifV2Ent>
</soapenv:Body>
</soapenv:Envelope>

Y esta sería la respuesta:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <env:Body>
 <VNifV2Sal:VNifV2Sal
xmlns:VNifV2Sal="http://www2.agenciatributaria.gob.es/static_files/common/internet/dep/aplicaciones/es/aeat/burt/jdit/ws/VNifV2Sal.xsd">
 <VNifV2Sal:Contribuyente>
 <VNifV2Sal:Nif>99999999R</VNifV2Sal:Nif>
 <VNifV2Sal:Nombre>ESPAÑOL ESPAÑOL JUAN</VNifV2Sal:Nombre>
 <VNifV2Sal:Resultado>Identificado</VNifV2Sal:Resultado>
 </VNifV2Sal:Contribuyente>
 </VNifV2Sal:VNifV2Sal>
 </env:Body>
</env:Envelope>

Donde el elemento vnif:Contribuyente puede ser repetido hasta 10.000 veces para consultas masivas

El objetivo de este proyecto es proporcionar unas herramientas para que el consumo de este servicio SOAP sea más fácil.

Estas herramientas son:

Script groovy, documentado en la página de referencia anterior
Plugin Grails, para ser incluido en la aplicación
Servicio Docker, para ser ejecutado como microservicio

GroovyScript

Como ya se ha explicado el script se encuentra documentado en el artículo http://groovy-lang.gitlab.io/101-scripts/ws/consulta_nif.html

Básicamente el script quedaría de la siguiente forma:

@Grab('com.github.groovy-wslite:groovy-wslite:1.1.2')
def client = new SOAPClient('https://www1.agenciatributaria.gob.es/wlpl/BURT-JDIT/ws/VNifV2SOAP')
def response = client.send() {
     envelopeAttributes([
            "xmlns:vnif": "http://www2.agenciatributaria.gob.es/static_files/common/internet/dep/aplicaciones/es/aeat/burt/jdit/ws/VNifV2Ent.xsd"
     ])
    body {
        'vnif:VNifV2Ent' {
            'vnif:Contribuyente'{
                'vnif:Nif'(args[0])
                'vnif:Nombre'(args[1])
            }
        }
    }
}
println "${response.VNifV2Sal.Contribuyente.Resultado}"

y para ejecutarlo pasaríamos por argumento un NIF y un Nombre:

groovy consulta_nif.groovy 9999999X "Espanol Espanol Juan"

Plugin Grails

Para integrar el servicio de validación como un plugin en una aplicacion Grails hay que incluir la dependencia:

build.gradle

compile 'com.puravida:consulta-nif:0.1'

lo cual proporcionará un Service nuevo ConsultaNifService y un POJO ConsultaNif

POJO ConsultaNif

Mediante este POJO encapsulamos la petición de un NIF y un Nombre con la respuesta de la AEAT

package consulta.nif

import groovy.transform.Canonical

@Canonical
class ConsultaNif {

    String nif
    String nombre
    String resultado
    String nombreAeat

}

Consulta de un NIF

    ConsultaNif validaNif( ConsultaNif consultaNif) {

Consulta de una lista de NIF

    List<ConsultaNif> validaNif( List<ConsultaNif> consultaNifList ) {

Servicio Docker

En el caso de que no quieras/puedas usar el plugin integrado en tu aplicación Grails también puedes usar la imagen Docker.

Mediante esta imagen dispondrás de un servicio web al que poder realizar las consultas vía REST y él se encarga de hacer la transformación y llamada a la AEAT. Simplemente necesitas proporcionar tu certificado y la password para poder acceder al mismo.

En primer lugar tendrás que hacer login en el repositorio de Gitlab:

docker login -u TU_USUARIO -p TU_PASSWORD registry.gitlab.com (1)en un futuro tal vez se publique la imagen en Docker Hub

en un futuro tal vez se publique la imagen en Docker Hub

Ejecución

Desde una consola ejecuta

docker run --rm -p 8080:8080 -v "$pwd/certs":/app/certs \
    -e "javax.net.ssl.keyStore=/app/certs/certificado.p12" \
    -e "javax.net.ssl.keyStorePassword=CHANGEME" \
    -e "javax.net.ssl.keyStoreTYpe=PKCS12" \
    registry.gitlab.com/puravida-software/consulta-nif:0.1

--rm borrar el contenedor cuando termine la ejecución
-p 8080:8080 conecta el puerto 8080 de la máquina anfitriona con el del contenedor
-v "$pwd/certs":/app/certs monta el subdirectorio "certs" como /app/certs del contenedor
-e (3) para configurar la ubicación del certificado, su password y formato

Certificados

Para acceder al servicio SOAP de la AEAT tienes que proporcionar un certificado (de empresa, personal, de empleado público, etc) para evitar abusos de consulta. Este servicio NO incluye ningún certificado como es obvio, sin embargo lo que te permite es que proporciones el tuyo de una forma cómoda.

Crea un directorio en la máquina donde vas a ejecutar el servicio y copia el certificado en el mismo. Cuando ejecutes el contenedor debes "mapear" esta carpeta a /app/certs y mediante la variable de entorno javax.net.ssl.keyStore indicarle el nombre precedido de /app/certs/

Así mismo debes proporcionar la password y tipo usando las otras dos variables de entorno.

REST

El servicio consulta-nif una vez iniciado atiende peticiones HTTP en la ruta /aeat y admite los parametros nif y nombre para su validación.

Por ejemplo, con el contenedor corriendo en la máquina, ejecutamos desde otra consola:

curl http://localhost:8080/aeat?nif=123456789Q&nombre=ApellidoNombre