Está en la página 1de 27

ZOFRI - SVE

Especificación Técnica de Servicios Web

Versión 1.1
14/07/2010
Índice

1. Objetivo del Documento 3


1.1 Definiciones, Acrónimos y Abreviaciones 3
1.2 Referencias 3

2. Introducción 4

3. Especificación Técnica de Invocación de Servicios Web 4


3.1 Estándares de Comunicación 4
3.2 Seguridad 4
3.3 Definición Técnica 6
3.3.1 Estructura de Entrada SOAP Servicio Web 6
3.3.2 Estructura Salida SOAP del Servicio Web 6

4. Invocación de Servicios Web 10


4.1 Autenticación e Inicio de Sesión 10
4.2 Servicio con estructura simple de entrada / salida 12
4.3 Servicio con estructura compleja de entrada / salida 13
4.4 Valores opcionales en los Servicios Web 14

5. Ejemplos de Invocación de Servicios Web 19


5.1 Ejemplo de llamada a WS desde cliente Java con Axis modalidad ‘One-Way’ 19

6. Anexo 22
6.1 Estándares 22
6.2 Productos 27

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 2 de 27
1. Objetivo del Documento
El objetivo del presente documento es describir la Especificación Técnica de los
Servicios Web del Servicio de Visación Electrónica - ZOFRI, necesaria para las
integraciones con los usuarios externos.

1.1 Definiciones, Acrónimos y Abreviaciones


Definición Significado
WebService Servicio Web que contiene WebMethods para poder brindar funcionalidad e
información de otros sistemas.
WebMethod Método Web que implementa una determinada funcionalidad dentro de un
Servicio Web.
Token Cadena de caracteres alfanuméricos utilizado para identificar unívocamente
una sesión de usuario en el sistema SVE.

Acrónimo Significado
HTTPS Hypertext Transfer Protocol Secure (Protocolo seguro de transferencia de
hipertexto)
SOAP Simple Object Access Protocol (Protocolo Simple de Acceso a Objetos)
SVE Servicio de Visación Electrónica
UDDI Universal Description, Discovery and Integration
http://www.uddi.org/pubs/ProgrammersAPI-V2.04-Published-20020719.htm
UTF-8 Unicode Transformation Format-8 (formato de codificación de caracteres
Unicode) http://www.utf8.com/
XML Extensible Markup Language (Lenguaje de Etiquetado Extensible)
W3C World Wide Web Consortium (Consorcio de la Red mundial de Redes)
http://www.w3.org/
WS-I Web Services Interoperability Organization http://www.ws-i.org/
WSDL Web Services Description Language (Descriptor de Lenguaje de Servicios
Web)

Abreviación Significado
No Aplica

1.2 Referencias
Título Fecha Autor
No Aplica

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 3 de 27
2. Introducción
El siguiente documento contiene las definiciones técnicas respecto a los Servicios
Web que Zofri S.A. pondrá a disposición para que las Empresas Usuarias como los
Organismos Externos puedan integrarse con el Servicio de Visación Electrónica
(SVE).

En estas definiciones se tomaron como base las especificaciones Basic Profile v1.0
del organismo WS-I para cubrir de esta manera los aspectos de interoperabilidad
como de seguridad.

3. Especificación Técnica de Invocación de Servicios Web

3.1 Estándares de Comunicación


Los Servicios Web del Servicio de Visación Electrónica – ZOFRI se implementarán de
acuerdo con las especificaciones WSDL v1.1, SOAP v1.1, UDDI v2.0 y XML v1.0, esto
con el objetivo de incorporar las recomendaciones de la WS-I definidas en la
especificación Basic Profile v1.0 y de esta manera asegurar la interoperabilidad entre
los sistemas.

SOAP (Simple Object Access Protocol) es un protocolo ligero destinado al intercambio


de información estructurada en un entorno descentralizado, distribuido y define cómo
dos objetos en diferentes procesos pueden comunicarse por medio de intercambio de
datos XML.

Los mensajes se intercambian entre el cliente y el servidor a través de los Servicios


Web, estos poseen una estructura XML y están descritos por el XML Schema
contenido en el WSDL, siguiendo los estándares de la W3C y la especificación de WS-
I antes mencionada. El estándar de codificación que utilizan en los mensajes XML es
UTF-8.

3.2 Seguridad
Ciertos servicios se acceden a través de una conexión segura HTTPS, el cual se
encuentra implementado a través del protocolo Secure Sockets Layer v3.0. HTTPS es
un protocolo de red basado en el protocolo HTTP, destinado a la transferencia segura
de datos de hipertexto, es decir, es la versión segura de HTTP.

Para los Servicios Web de integración con las Empresas Usuarias y con Organismos
Externos (Ej: Aduana) que se encuentren en la modalidad HTTPS, el mecanismos de
seguridad será One-Way, es decir, el cliente debe asegurarse que el servidor es el
que corresponde y no otro, esto previo a realizar la invocación de los Servicios Web.
Una vez realizada la verificación, se establecerá una conexión segura de tipo HTTPS
donde la información transmitida se trasmite por un canal encriptado.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 4 de 27
Por ejemplo, para el servicio requiere de autenticación a través de “usuario” y
“clave”, se utiliza el Servicio Web HTTPS de Login, el cual recibe además el Rut de la
empresa usuaria y Rut de la Agencia de Aduana en los casos que se desee iniciar una
sesión representando los mismo.

Una vez que se validan correctamente los datos ingresados, el sistema inicia una
sesión y retorna un Token (Llave de seguridad) con el cual se ejecutan los siguiente
Servicios Web. El Token obtenido debe ser enviado en el Header del mensaje SOAP.

En cada ejecución de un Servicio Web se entrega un nuevo Token de Sesión el cual


debe ser utilizado en la próxima invocación a un Servicio Web. El Token de Sesión
entonces, es un valor de ingreso/salida que se va renovando con cada llamada a una
operación, siempre y cuando la validación del último Token enviado sea exitosa.

En la invocación de lo servicios se valida además que el usuario posea el perfil


necesario para poder ejecutar la operación.

En caso de que la sesión expire, se debe invocar nuevamente el Servicio Web de


Login, el cual se detalla en el apartado “Autenticación e Inicio de Sesión” de este
documento.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 5 de 27
3.3 Definición Técnica

3.3.1 Estructura de Entrada SOAP Servicio Web


La estructura de entrada a un Servicio Web está representada en el siguiente
ejemplo.

En el mismo se puede observar la estructura estándar del protocolo SOAP: Envelope,


Header y Body (ver SOAP, sección Anexo).
En el Header o cabecera se encuentra el token de sesión.
En el Body o cuerpo del mensaje SOAP, se encuentra la llamada a la operación
conjuntamente con los parámetros.

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<token xmlns="cl.zofri.sve">token_sesion</token>
</env:Header>
<env:Body>
<nombreOperacion xmlns="http://cl/zofri/sve/prd/wsn">
<parametro_1>valor_parametro_1</parametro_1>

<parametro_i>valor_parametro_i</parametro_i>
</nombreOperacion >
</env:Body>
</env:Envelope>

Donde:

token_sesion Es un valor alfanumérico de 144 caracteres. Por ejemplo:


3721dd0d9a04ce9c4-.14506bd9-34.b-729b-481e_2e31-976f-
4.f4c026b4108.0085f-7618d2d8a042e0c4-91-5.67d0-349bd7.9b-28be42d3_-
271fe46f8c.2db014840d8.f

<parametro_i> Iésimo parámetro de la operación.

valor_parametro_i Iésimo valor para el iésimo parámetro de la operación.

nombreOperacion Es el nombre del webmethod, es decir la operación ejecutada.

3.3.2 Estructura Salida SOAP del Servicio Web


La estructura de salida del Servicio Web está ordenada de la siguiente manera: en el
Header o cabecera se puede observar datos de sesión como así también datos de
respuesta. Los datos que se retornan aquí son: el Token de sesión y el código,
severidad y mensaje de respuesta.
En el Body se encuentra el retorno de la operación. Más adelante se muestra que
esta información puede ser un tipo de dato simple o complejo.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 6 de 27
La siguiente es una estructura de salida cuando el Método Web se ejecuta
correctamente sin ninguna excepción.

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<cl:token xmlns:cl="cl.zofri.sve">token_sesion</cl:token>
<cl:respuesta xmlns:cl="cl.zofri.sve">
<java:resCodigo
xmlns:java="java:cl.zofri.sve.utl.bo">Código_Respuesta</java:resCodigo>
<java:resMensaje
xmlns:java="java:cl.zofri.sve.utl.bo">Mensaje_Respuesta</java:resMensaje>
<java:resSeveridad
xmlns:java="java:cl.zofri.sve.utl.bo">Severidad_Respuesta</java:resSeveridad>
</cl:respuesta>
</env:Header>
<env:Body>
<m:nombreOperacion xmlns:m="http://cl/zofri/sve/prd/wsn">
<m:return>

<m:respuesta></m:respuesta>

</m:return>
</m:nombreOperacion>
</env:Body>
</env:Envelope>

Donde:

token_sesion Es un valor alfanumérico de 144 caracteres. Por ejemplo:


3721dd0d9a04ce9c4-.14506bd9-34.b-729b-481e_2e31-976f-
4.f4c026b4108.0085f-7618d2d8a042e0c4-91-5.67d0-349bd7.9b-28be42d3_-
271fe46f8c.2db014840d8.f

Código_Respuesta Es el código de la respuesta en formato numérico. Ej. 105

Mensaje_Respuesta Es el mensaje de respuesta. Ej. Estructura XML del documento no válida

Severidad_Respuesta Es el nivel de severidad de la respuesta. Los niveles de severidad pueden ser:

O (Ok), I(Info), W (Warning), E (Error).

nombreOperacion Es el nombre del webmethod, es decir la operación ejecutada.

respuesta Es la respuesta del servicio Web contenida en el tag <m:return></m:return>


la cual puede corresponder a un tipo simple (String, Long, Boolean) o
complejo (DocumentoEO, SesionEO, etc). En el caso de los tipos complejos, la
definición del objeto se incluye dentro del WSDL del servicio.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 7 de 27
La siguiente es una estructura de salida cuando el Método Web se ejecuta con una
excepción controlada en el mismo.

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<cl:token xmlns:cl="cl.zofri.sve">token_sesion</cl:token>
<cl:respuesta xmlns:cl="cl.zofri.sve">
<java:resCodigo xmlns:java="java:cl.zofri.sve.utl.bo"> Código_Respuesta
</java:resCodigo>
<java:resMensaje xmlns:java="java:cl.zofri.sve.utl.bo"> Mensaje_Respuesta
</java:resMensaje>
<java:resSeveridad xmlns:java="java:cl.zofri.sve.utl.bo"> Severidad_Respuesta
</java:resSeveridad>
</cl:respuesta>
</env:Header>
<env:Body>
<m:nombreOperacion xmlns:m="http://cl/zofri/sve/prd/wsn">
<m:return xsi:nil="true"/>
</m:nombreOperacion>
</env:Body>
</env:Envelope>

Donde:
token_sesion Es un valor alfanumérico de 144 caracteres. Por ejemplo:
3721dd0d9a04ce9c4-.14506bd9-34.b-729b-481e_2e31-976f-
4.f4c026b4108.0085f-7618d2d8a042e0c4-91-5.67d0-349bd7.9b-28be42d3_-
271fe46f8c.2db014840d8.f
Código_Respuesta Es el código de la respuesta del error en formato numérico. Para este caso
siempre es -1
Mensaje_Respuesta Es el mensaje de la respuesta del error producido.

Severidad_Respuesta Es el nivel de severidad de la respuesta. Para este caso siempre es E (Error)

nombreOperacion Es el nombre del webmethod, es decir la operación ejecutada.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 8 de 27
La siguiente es una estructura de salida cuando el Método Web se ejecuta con una
excepción No controlada en el mismo.

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<env:Fault>
<faultcode>env:Server</faultcode>
<faultstring>Fallo_Descripcion</faultstring>
<detail>
<bea_fault:stacktrace
xmlns:bea_fault="http://www.bea.com/servers/wls70/webservice/fault/1.0.0">
Fallo_Error
</bea_fault:stacktrace>
</detail>
</env:Fault>
</env:Body>
</env:Envelope>

Donde:

Fallo_Descripcion Es una descripción acerca del error producido.

Fallo_Error Es el error completo con traza del error producido.

En este caso se debe utilizar el último token recuperado si se desea realizar una
nueva invocación de un Servicio Web.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 9 de 27
4. Invocación de Servicios Web

4.1 Autenticación e Inicio de Sesión


Como se explicó en la sección anterior, previa a la invocación de cualquier Servicio
Web del sistema, es preciso realizar la autenticación contra el servidor del SVE.

La autenticación de usuario e inicio de sesión se realizan a través de la invocación del


Servicio Web de Sesión donde el cliente debe invocar en primera instancia el Servicio
Web “login”, mediante el cual se ingresan los datos usuario / clave (obligatorios), Rut
de Empresa y Rut de Agencia de Aduana, los cuales son opcionales.

En caso de éxito, se inicia una sesión en el servidor a través de un Token generado.


El token en la invocación del Servicio Web de login debe ser vacío.

El WSDL del servicio para Iniciar Sesión es:

http://<hostSVE>/svePerfilacionWSN/Sesion?WSDL

Un ejemplo de invocación al servicio para realizar el Login se muestra en el


siguiente XML:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:cl="cl.zofri.sve" xmlns:wsn="http://cl/zofri/sve/prf/wsn"
xmlns:java="java:cl.zofri.sve.app.eo">
<soapenv:Header>
<cl:token></cl:token>
</soapenv:Header>
<soapenv:Body>
<wsn:login>
<wsn:usuario>juan.rojas</wsn:usuario>
<wsn:clave>ro83ja</wsn:clave>
<wsn:rutEmpresa>
<java:Dv>4650516</java:Dv>
<java:Nro>6</java:Nro>
</wsn:rutEmpresa>
<wsn:rutAgencia>
<java:Dv>23940242</java:Dv>
<java:Nro>9</java:Nro>
</wsn:rutAgencia>
</wsn:login>
</soapenv:Body>
</soapenv:Envelope>

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 10 de 27
Cuando la respuesta es exitosa, en el Header del mensaje SOAP se retorna el Token
de sesión con el cual se podrá realizar la posterior llamada a los servicios del sistema
SVE. En el cuerpo del mensaje SOAP se retorna el objeto Usuario con los datos
principales del mismo. Por ejemplo:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Header>
<cl:token xmlns:cl="cl.zofri.sve">67221803520f5c9b4-.e830c7c9-a4.5-b2c5-4ae7_cce1-
8c38-b.c4305451be6.d4a10-712b823c20f7c0b0-9e-3.cfc0-34950b.c4-2a774c7e_-
1c188b3c83.5e50b861d9a.0</cl:token>
<cl:respuesta xmlns:cl="cl.zofri.sve">
<java:resCodigo xmlns:java="java:cl.zofri.sve.utl.bo">0</java:resCodigo>
<java:resMensaje xmlns:java="java:cl.zofri.sve.utl.bo">Se ejecutó correctamente el
servicio.</java:resMensaje>
<java:resSeveridad xmlns:java="java:cl.zofri.sve.utl.bo">O</java:resSeveridad>
</cl:respuesta>
</env:Header>
<env:Body>
<m:loginResponse xmlns:m="http://cl/zofri/sve/prf/wsn">
<m:return>
<java:IdUsuario xmlns:java="java:cl.zofri.sve.prf.eo">juan.rojas</java:IdUsuario>
<java:Apellidos xmlns:java="java:cl.zofri.sve.prf.eo">Rojas Pérez</java:Apellidos>
<java:Nombre xmlns:java="java:cl.zofri.sve.prf.eo">Juan Manuel</java:Nombre>
<java:Profesion xmlns:java="java:cl.zofri.sve.prf.eo">Auditor</java:Profesion>
<java:Rut xmlns:java="java:cl.zofri.sve.prf.eo">23769254</java:Rut>
<java:DigitoVerificador xmlns:java="java:cl.zofri.sve.prf.eo">3</java:DigitoVerificador>
<java:DireccionEmpresa xmlns:java="java:cl.zofri.sve.prf.eo"/>
<java:Mail xmlns:java="java:cl.zofri.sve.prf.eo">jperez@induropa.com</java:Mail>
<java:DescripcionEmpresa xmlns:java="java:cl.zofri.sve.prf.eo">Importadora
INDUROPA LTDA.</java:DescripcionEmpresa>
<java:RazonSocialEmpresa xmlns:java="java:cl.zofri.sve.prf.eo">INDUROPA
LTDA</java:RazonSocialEmpresa>
</m:return>
</m:loginResponse>
</env:Body>
</env:Envelope>

Cuando la respuesta es fallida, es decir, cuando el usuario no pueda autenticarse por


alguna razón, ya sea porque no existe, su cuenta no se encuentra activa ó su clave
es incorrecta, el Token es siempre un valor negativo igual a -1, lo cual significa que
es un Token inválido para realizar operaciones. El valor -1 también se retorna
cuando la sesión ha expirado por tiempo de inactividad, en cuyo caso se debe
invocar nuevamente al servicio de login. Por ejemplo:

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 11 de 27
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Header>
<cl:token xmlns:cl="cl.zofri.sve">-1</cl:token>
<cl:respuesta xmlns:cl="cl.zofri.sve">
<java:resCodigo xmlns:java="java:cl.zofri.sve.utl.bo">MELG08</java:resCodigo>
<java:resMensaje xmlns:java="java:cl.zofri.sve.utl.bo">No fue posible autenticar el
usuario. Verifique sus datos e intente nuevamente.</java:resMensaje>
<java:resSeveridad xmlns:java="java:cl.zofri.sve.utl.bo">W</java:resSeveridad>
</cl:respuesta>
</env:Header>
<env:Body>
<m:loginResponse xmlns:m="http://cl/zofri/sve/prf/wsn">
<m:return xsi:nil="true"/>
</m:loginResponse>
</env:Body>
</env:Envelope>

4.2 Servicio con estructura simple de entrada / salida


Luego de haber realizado el Login, el usuario podrá realizar la invocación de un
servicio del sistema SVE utilizando para ellos el Token generado por éste último.

El siguiente ejemplo es la llamada a un Servicio Web que recibe un parámetro simple


y retorna un tipo simple. Para el ejemplo se utilizó el tipo de dato String como tipo
de entrada y un tipo de dato entero como salida.

Entrada al servicio:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<token xmlns="cl.zofri.sve">67221803520f5c9b4-.e830c7c9-a4.5-b2c5-4ae7_cce1-8c38-
b.c4305451be6.d4a10-712b823c20f7c0b0-9e-3.cfc0-34950b.c4-2a774c7e_-
1c188b3c83.5e50b861d9a.0</token>
</env:Header>
<env:Body>
<obtenerIdPais xmlns="http://cl/zofri/sve/prd/wsn">
<codigoPais>ARG</codigoPais>
</obtenerIdPais>
</env:Body>
</env:Envelope>

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 12 de 27
Salida del servicio:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Header>
<cl:token xmlns:cl="cl.zofri.sve">3125dd0a970dc09b4-.14e0bbc9-34.f-42eb-4a11_8e51-
9966-f.3410b603a05.90d43-1058d2a870d200b4-91-e.b7c0-349fd4.eb-2ab148d5_-
2916ef6381.bd00a4539dd.3</cl:token>
<cl:respuesta xmlns:cl="cl.zofri.sve">
<java:resCodigo xmlns:java="java:cl.zofri.sve.utl.bo">0</java:resCodigo>
<java:resMensaje xmlns:java="java:cl.zofri.sve.utl.bo">Se ejecutó correctamente el
servicio.</java:resMensaje>
<java:resSeveridad xmlns:java="java:cl.zofri.sve.utl.bo">O</java:resSeveridad>
</cl:respuesta>
</env:Header>
<env:Body>
<m:obtenerIdPaisResponse xmlns:m="http://cl/zofri/sve/prd/wsn">
<m:return>1</m:return>
</m:obtenerIdPaisResponse>
</env:Body>
</env:Envelope>

4.3 Servicio con estructura compleja de entrada / salida


El siguiente es un ejemplo de la llamada a un Servicio Web que recibe un parámetro
complejo (En este ejemplo se utiliza el objeto Filtros) y retorna un array de objetos
del tipo Persona. Las clases y los paquetes del ejemplo son sólo a modo ilustrativo, lo
que significa que los mismos pueden no existir en el Sistema SVE.

Entrada al servicio:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<cl:token xmlns:cl="cl.zofri.sve">3125dd0a970dc09b4-.14e0bbc9-34.f-42eb-4a11_8e51-
9966-f.3410b603a05.90d43-1058d2a870d200b4-91-e.b7c0-349fd4.eb-2ab148d5_-
2916ef6381.bd00a4539dd.3</cl:token>
</env:Header>
<env:Body>
<obtenerPersonas xmlns="http://cl/zofri/sve/prd/wsn"
xmlns:java="java:cl.zofri.sve.prd.wsn">
<objFiltros>
<java:Apellido>Alvar</java:Apellido>
<java:Nombre>Ma</java:Nombre>
</objFiltros>
</obtenerPersonas>
</env:Body>
</env:Envelope>

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 13 de 27
Salida del servicio:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<cl:token xmlns:cl="cl.zofri.sve">3125dd0a159dc09b4-.14e0bbc9-34.f-42eb-4a11_8e51-
9966-f.3410b603a05.90d43-1058d2a870d200b4-91-e.b7c0-349fd4.eb-2ab148d5_-
2916ef6381.bd00a4539dd.4</cl:token>
<cl:respuesta xmlns:cl="cl.zofri.sve">
<java:resCodigo xmlns:java="java:cl.zofri.sve.utl.bo">0</java:resCodigo>
<java:resMensaje xmlns:java="java:cl.zofri.sve.utl.bo">Se ejecutó correctamente el
servicio.</java:resMensaje>
<java:resSeveridad xmlns:java="java:cl.zofri.sve.utl.bo">O</java:resSeveridad>
</cl:respuesta>
</env:Header>
<env:Body>
<m:obtenerPersonasResponse xmlns:m="http://cl/zofri/sve/prd/wsn">
<m:return xmlns:java="java:cl.zofri.sve.prd.wsn">
<java:PersonaEO>
<java:Apellido>Alvarado</java:Apellido>
<java:IdPersona>2345</java:IdPersona>
<java:Nombre>Mauro</java:Nombre>
</java:PersonaEO>
<java:PersonaEO>
<java:Apellido>Alvarez</java:Apellido>
<java:IdPersona>7632</java:IdPersona>
<java:Nombre>Maria</java:Nombre>
</java:PersonaEO>
</m:return>
</m:obtenerPersonasResponse>
</env:Body>
</env:Envelope>

4.4 Valores opcionales en los Servicios Web


Para el ingreso de valores opcionales o el no ingreso de un valor, para Servicios
Web en los cuales se envía un documento XML como parámetro (Ej: Visación de
Documentos) o se invoca un Servicio Web con parámetros Tipados (Ej: Long, Date,
Double, etc), se debe tener en cuenta las siguientes consideraciones:

1 – No incluir el nodo “opcional” en la estructura XML.

2 – Incluir el nodo opcional pero acompañado con el atributo xsi:nil="true" y la


definición xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" en el nodo principal
de la estructura XML. En el caso de Servicios Web tipados, la definición
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" se debe incluir en el tag
“soapenv:Envelope” del mensaje SOAP.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 14 de 27
Por ejemplo, supongamos que tenemos la siguiente estructura XML como parámetro
de un Servicio Web:

<documento>
<monto>10</monto>
<texto>Texto de Prueba</texto>
</documento>

Ahora deseamos que el valor de <monto> no sea ingresado al sistema debido a que
el mismo es opcional. Para ello deberemos enviar el XML según las opciones antes
mencionadas:

1–
<documento>
<texto>Texto de Prueba</texto>
</documento>

2–
<documento xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<monto xsi:nil="true"></monto>
<texto>Texto de Prueba</texto>
</documento>

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 15 de 27
Según lo indicado, para el caso de un Servicio Web con datos Tipados, la invocación
del dato opción para este caso se podrá realizar como se muestra en la siguiente
figura:

Nota: La definición de los elementos opcionales en la estructura XML, se indica en el


esquema XSD asociado a la operación. En el caso de los Servicios Web Tipados, esta
definición se encuentra en el XSD incluido dentro del WSDL que los define.

Las definiciones antes mencionadas se encuentra de acuerdo a lo definido por la W3C


respecto XML Schema, para revisar la documentación de la norma respecto a estos
puntos se puede consultar en:

http://www.w3.org/TR/xmlschema-0/

Secciones “2.2.1 Occurrence Constraints” y “2.9 Nil Values” respectivamente.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 16 de 27
En el caso de que un parámetro (nodo) del servicio se informe, el mismo deberá
incluir al menos un valor, por ejemplo, para el caso de un parámetro tipo entero se
deberá informa al menos:

<documento>
<monto>0</monto>
</documento>

Siendo incorrecto que se informe de la siguiente manera:

<documento>
<monto></monto>
</documento>

Lo mismo sucede con el resto de los tipos de datos (Date, Long, Double, etc), siendo
la excepción el tipo de dato String, para el cual será posible informarlo de la
siguiente manera:

<documento>
<texto></texto>
</documento>

En este caso, el valor de <texto></texto> corresponde a texto=“”, lo cual, desde el


punto de vista de los sistemas, es distinto a informar texto=null.

Respecto a los Servicios Web Tipados que poseen parámetros donde se puede recibir
un arreglo de valores (por ejemplo, una lista de Rut), si no se desean enviar valores
se deberá mantener la estructura base del parámetro. Por ejemplo, en la siguiente
definición existe un parámetro tipado (Long) denominado numeroProvisorio, el cual
puede recibir una lista de valores numéricos:

<soapenv:Body>
<wsn:obtenerCausalesRechazo>
<wsn:numeroProvisorio>
<java:JavaLanglong>20102553</java:JavaLanglong>
<java:JavaLanglong>20109278</java:JavaLanglong>
<java:JavaLanglong>20108392</java:JavaLanglong>
</wsn:numeroProvisorio>
</wsn:obtenerCausalesRechazo>
</soapenv:Body>

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 17 de 27
Si no se desea enviar valores para este parámetro, la estructura correcta a utilizar es
la siguiente:

<soapenv:Body>
<wsn:obtenerCausalesRechazo>
<wsn:numeroProvisorio></wsn:numeroProvisorio>
</wsn:obtenerCausalesRechazo>
</soapenv:Body>

Como se mencionó anteriormente, esta definición se debe respetar para cualquier


otro tipo de parámetro que permita el ingreso de un arreglo de valores.

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 18 de 27
5. Ejemplos de Invocación de Servicios Web

5.1 Ejemplo de llamada a WS desde cliente Java con Axis modalidad ‘One-Way’
A continuación se presenta un ejemplo completo de invocación y consumo de un
Servicio Web, desde una estación cliente, utilizando para el Framework Axis.

package tst.ws;

import javax.xml.rpc.holders.StringHolder;

import bo.utl.sve.zofri.cl.holders.RespuestaHolder;
import cl.zofri.sve.prf.wsn.Login;
import cl.zofri.sve.prf.wsn.LoginResponse;
import cl.zofri.sve.prf.wsn.Sesion;
import cl.zofri.sve.prf.wsn.SesionServiceLocator;
import cl.zofri.sve.prm.wsn.Exec;
import cl.zofri.sve.prm.wsn.ExecResponse;
import cl.zofri.sve.prm.wsn.Servicios;
import cl.zofri.sve.prm.wsn.ServiciosServiceLocator;
import eo.prf.sve.zofri.cl.UsuarioEO;

public class wsTestOneWay {

public void invokeWSOneWay() throws Exception


{
// Definicion de variables y objetos de contexto
String xmlPrm = "";
String resultado = "";
Exec parametersExec = new Exec();
Login parametersLogin = new Login();
UsuarioEO usuarioEO = new UsuarioEO();
LoginResponse loginResponse;
ExecResponse execResponse;
StringHolder token = new StringHolder();
RespuestaHolder respuesta = new RespuestaHolder();

try
{ System.setProperty("javax.net.debug","all");

// Especificar la ubicación del archivo de Almacén de


Confianza
// (truststore) con los certificados digitales validos del
Servidor
System.setProperty("javax.net.ssl.trustStore",
"C:\\bea103\\wlserver_10.3\\server\\lib\\DemoTrust.jks");
System.setProperty("javax.net.ssl.trustStorePassword",
"DemoTrustKeyStorePassPhrase");

// Creación del Objeto locator del Servicio Web de 'Sesion'


SesionServiceLocator locatorSes = new SesionServiceLocator();
// Seteo del EndPoint del Servicio Web de 'Sesion',
// (esto puede ser un parámetro configurable para la
aplicación)
locatorSes.setEndpointAddress("SesionSoapPort",
"https://localhost:7002/svePerfilacionWSN/Sesion");

// Obtención del objeto de Servicio para la invocación al


Servicio Web

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 19 de 27
Sesion ses = locatorSes.getSesionSoapPort();

// Definición de usuario y clave para el Metodo Web 'login'


// (estos pueden ser un parámetro del método actual o
configurable para la aplicación cliente)
String usuario = "jperez";
String clave = "clave123";

// Seteo de los parámetros de entrada para el Metodo Web


'login'
parametersLogin.setUsuario(usuario);
parametersLogin.setClave(clave);

// Invocación al Método Web 'login'


loginResponse = ses.login(parametersLogin, token, respuesta);

// Obtención de la respuesta, la cual corresponde a un objeto


de tipo UsuarioEO
usuarioEO = loginResponse.get_return();

// Visualización de la respuesta en la consola


System.out.print("Ejecución 'login' OK : " +
usuarioEO.getNombre() + " " + usuarioEO.getApellidos() + "\n\n");

// Creación del Objeto locator del Servicio Web de 'Servicios'


ServiciosServiceLocator locatorSrv = new
ServiciosServiceLocator();
// Seteo del EndPoint del Servicio Web de 'Servicios',
// (esto puede ser un parámetro configurable para la
aplicación)
locatorSrv.setEndpointAddress("ServiciosSoapPort",
"http://localhost:7001/sveParametrosWSN/Servicios");

// Obtención del objeto de Servicio para la invocación al


Servicio Web
Servicios srv = locatorSrv.getServiciosSoapPort();

// Seteo de los parámetros de ingreso para el Metodo Web


'exec'
xmlPrm = "<srvs><srv typeQuery='queryForList'
idQuery='obtenerPais' alias='obtenerPais1' pageNumber='1' pageSize='5' pais_id=''
pais_codi='' pais_nomb='' pais_desc='' pais_vige='N'/> <srv
typeQuery='queryForList' idQuery='obtenerPais' idSqlContext='sve'
alias='obtenerPais2' pageNumber='1' pageSize='5' pais_id='' pais_codi='' pais_nomb=''
pais_desc='' pais_vige=''/></srvs>";

// Seteo de los parámetros de entrada para el Metodo Web


'exec'
parametersExec.setXmlPrm(xmlPrm);

// Invocación al Método Web 'exec'


execResponse = srv.exec(parametersExec, token, respuesta);

// Obtención de la respuesta
resultado = execResponse.get_return();

// Visualización de la respuesta en la consola


System.out.print("Ejecución 'exec' OK: " + resultado +
"\n\n");
}
catch (Exception e)
{
System.out.print("Ejecución ERROR: " + e.getMessage()+
"\n\n");

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 20 de 27
throw e;
}
}
}

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 21 de 27
6. Anexo
A continuación se detallan los estándares y productos en orden alfabético.

6.1 Estándares

Estándar Servicios Web

Los Servicios Web son un conjunto de aplicaciones o de tecnologías con


capacidad para interoperar en la Web. Estas aplicaciones o tecnologías
intercambian datos entre sí con el objetivo de ofrecer unos servicios. Los
Definición
proveedores ofrecen sus servicios como procedimientos remotos y los
usuarios solicitan un servicio llamando a estos procedimientos a través de la
Web.

Los Servicios Web proporcionan mecanismos de comunicación estándares


entre diferentes aplicaciones, que interactúan entre sí para presentar
información dinámica al usuario. Para proporcionar interoperabilidad y
extensibilidad entre estas aplicaciones, y que al mismo tiempo sea posible
su combinación para realizar operaciones complejas, es necesaria una
Descripción arquitectura de referencia estándar.

Para esto es que la definición de un Servicio Web se realiza a través de su


WSDL (ver Anexo) el cual contiene la descripción del Servicio Web que se
podría traducir en el contrato que se establece entre el usuario y el que
brinda el servicio.

Página Principal http://www.w3.org/2002/ws/

http://www.w3.org/2002/ws/Activity

Documentación http://www.w3c.es/Divulgacion/GuiasBreves/ServiciosWeb

http://www.w3schools.com/webservices/default.asp

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 22 de 27
Estándar SOAP v1.1 (Simple Object Access Protocol)

SOAP es un protocolo ligero destinado al intercambio de información


estructurada en un entorno descentralizado y distribuido. SOAP define cómo
Definición
dos objetos en diferentes procesos pueden comunicarse por medio de
intercambio de datos XML.

Estructura de un mensaje SOAP


<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>...</soap:Header>

<soap:Body>...

<soap:Fault>...</soap:Fault>

</soap:Body>

</soap:Envelope>
El elemento raíz de todo mensaje SOAP es el nodo Envelope. El mismo
contiene todo el mensaje XML correspondiente al estándar.

Luego se encuentra el nodo de cabecera (Header) el cual es un nodo


opcional. El mismo contiene información específica de la aplicación (como
por ejemplo autenticación, mensajes adicionales, etc).
Descripción
Luego de la cabecera se encuentra el nodo Body, el cual es requerido y
corresponde con el cuerpo que contiene la información del mensaje SOAP.

Por último aparece el nodo Fault, el mismo solo está presente en caso de
que se produzca una excepción en el sistema, por lo cual representa un
error en la ejecución del método.

Si hay un elemento de error, debe aparecer como un elemento secundario


del elemento Body y solo un elemento de error (Fault) puede aparecer en un
mensaje SOAP.

El elemento de error SOAP tiene los siguientes sub elementos:

Sub Elemento Descripción


<faultcode> Código de identificación del error.
<faultstring> Resumen del error
<faultactor> Información acerca del causal del error
<detail> Información específica del error

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 23 de 27
Página Principal http://www.w3.org/TR/soap/

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
Documentación
http://www.w3schools.com/soap/soap_intro.asp

Estándar WSDL v1.1 (Web Services Description Language)

WSDL es un lenguaje basado en XML para describir Servicios Web y cómo


Definición
acceder a ellos.

Las principales características de los WSDL son:


• WSDL es un Lenguaje de Descripción de Servicios Web estándar
• WSDL está escrito en XML
Descripción • WSDL es un documento XML
• WSDL se utiliza para describir los Servicios Web
• WSDL también se utilizo para ubicar los Servicios Web
• WSDL es una recomendación del la W3C

Página Principal http://www.w3.org/TR/wsdl

Documentación http://www.w3schools.com/WSDL/default.asp

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 24 de 27
Estándar XML v1.0 (Extensible Markup Language)

XML es un Lenguaje de Etiquetado Extensible muy simple, pero estricto que


Definición juega un papel fundamental en el intercambio de una gran variedad de
datos.

XML es un lenguaje muy similar a HTML pero su función principal es


describir datos y no mostrarlos como es el caso de HTML. XML es un
formato que permite la lectura de datos a través de diferentes aplicaciones.

Las tecnologías XML son un conjunto de módulos que ofrecen servicios


útiles a las demandas más frecuentes por parte de los usuarios. XML sirve
para estructurar, almacenar e intercambiar información.

A continuación se presenta un ejemplo de un documento XML:


Descripción
<?xml version="1.0" encoding="UTF-8"?>
<libro>
<titulo></titulo>
<capitulo>
<titulo></titulo>
<seccion>
<titulo></titulo>
</seccion>
</capitulo>
</libro>

Página Principal http://www.w3.org/TR/REC-xml/

http://www.w3c.es/divulgacion/guiasbreves/tecnologiasXML
Documentación
http://www.w3.org/XML/1999/XML-in-10-points.es.html

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 25 de 27
Estándar XML Schema v1.1 (o XML Schema Definition (XSD))

XML Schema o XSD es un Lenguaje de Esquemas escrito en XML, utilizado


Definición
para validar estructuras XML.

Un XML Schema define la estructura de debe tener un documento XML y se


utiliza tanto para validar la forma como el contenido.

Un Esquema XML:
• define los elementos que pueden aparecer en un documento
• define los atributos que pueden aparecer en un documento
• define qué elementos son los elementos secundarios
• define el orden de los elementos secundarios
• define el número de elementos secundarios
• define si un elemento está vacío o puede incluir texto
• define los tipos de datos para elementos y atributos

Descripción • define por defecto y valores fijos para elementos y atributos

A continuación se presenta un ejemplo de un Esquema XML:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="note">
<xs:complexType>
<xs:sequence>
<xs:element name="to" type="xs:string"/>
<xs:element name="from" type="xs:string"/>
<xs:element name="heading" type="xs:string"/>
<xs:element name="body" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

Página Principal http://www.w3.org/XML/Schema

http://www.w3.org/TR/xmlschema-0/
Documentación
http://www.w3schools.com/Schema/

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 26 de 27
6.2 Productos

Producto Axis

Axis es un Framework OpenSource desarrollado por Apache Software


Foundation, utilizado en el SVE para el consumo de Servicios Web externos
a la aplicación (Client-Side), esto con el fin de lograr la integración con
Descripción
otros sistemas. Axis es una implementación de SOAP y posee varias
utilidades y APIs para la generación y despliegue de Servicios y Clientes
Web.

Axis Server y Cliente requieren de Java 1.3 o superior.

Para poder utilizar este framework el servidor debe ser de tipo J2EE y debe
contar con las siguientes librerías instaladas en el mismo.

/lib/axis.jar

lib/commons-discovery.jar
Requerimientos
/lib/commons-logging.jar

/lib/jaxrpc.jar

/lib/saaj.jar

/lib/wsdl4j.jar

Página Principal http://ws.apache.org/axis/

http://ws.apache.org/axis/java/index.html
Documentación
http://ws.apache.org/axis/java/client-side-axis.html

Arquitectura y Diseño de la solución. Versión Template: 1.0 Fecha:14/07/10


ZOFRI - SVE

Confidencial Página 27 de 27