Web Service Delivery 2.0

Introducción

Las aplicaciones web actuales ya no son suficientes. El modelo actual de negocio electrónico no facilita la integración de las aplicaciones de Internet con el resto de software de las empresas. Si las compañías quieren extraer el máximo beneficio de Internet, los sitios web deben evolucionar. Este es el contexto en el que surgen los web services.

Por eso es que en los últimos tiempos ha surgido con mucha fuerza el concepto de web services, incluso afirmándose que el mismo cambiaría la forma de programar las aplicaciones orientadas a Internet hacia una arquitectura orientada a servicios. Podemos decir que un web service es una aplicación que puede ser descripta, publicada, localizada e invocada a través de una red, generalmente Internet. Combinan los mejores aspectos del desarrollo basado en componentes y la Web. Al igual que los componentes, los web services son funcionalidades que se encuentran dentro de una caja negra, que pueden ser reutilizados sin preocuparse de cómo fueron implementados. A diferencia de la actual tecnología de componentes, no son accedidos por medio de protocolos específicos del modelo de objetos como ser RMI, DCOM o IIOP; sino que son accedidos utilizando protocolos web como ser HTTP y XML. La interface de los web services está definida en términos de los mensajes que el mismo acepta y retorna, por lo cual los consumidores de los web services pueden ser implementados en cualquier plataforma y en cualquier lenguaje de programación, solo tiene que poder crear y consumir los mensajes definidos por la interface de los web services

El Modelo Web Services

La arquitectura básica del modelo de web services describe a un consumidor, un proveedor (Implementador) y ocasionalmente un corredor (bróker UDDI). Relacionados con estos agentes están las operaciones de publicar, encontrar y enlazar. La idea básica consiste en que un proveedor publica su servicios en un corredor, luego un consumidor se conecta el corredor para buscar los servicios deseados y una vez que lo hace se realiza un lazo entre el consumidor y el proveedor ó implementador. Cada entidad puede jugar alguno o todos los roles.

Por todo lo anterior hay ciertos requerimientos a la hora de desarrollar o consumir un web services:

Una forma estándar de representar los datos.

XML es la opción obvia para este requerimiento.

Un formato común y extensible de mensajes

SOAP es el elegido en este caso; SOAP es un protocolo liviano para el intercambio de información. Más adelante en este documento lo veremos con más detalle.

Un lenguaje común y extensible para describir los servicios.

La opción en este caso es WSDL. Es un lenguaje basado en XML desarrollado en forma conjunta por IBM y Microsoft. Lo veremos con más detalle más adelante en este documento.

Una forma de descubrir los servicios en Internet.

UDDI se utiliza en este caso; el mismo especifica un mecanismo para publicar y localizar los servicios por parte de los proveedores y consumidores respectivamente. Se verá con más detalle más adelante en este documento.

Descripción del Servicio Web Oca Delivery 2.0

La descripción del Servicio de Oca está disponible a través de los métodos del WebServices SigmaService y están publicados en la URL

http://www1.oca.com.ar/SigmaWebService/SigmaService.asmx.

Los Métodos Públicos de este Web Services son :

EstadoMotivoActualXML

Este método se utiliza para poder consultar el estado y motivo de tramitación actual de una pieza.

Tiene 9 parametros: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa, mostrarDatosAdicionales

“CCC,CCC25501,XXXXXX,CCC,,1080661,,,”

ClienteLogueo = Es la sigla del cliente registrada en la operativa comercial de OCA, en el ej. CCC (Después se los informaremos cuál les corresponde).
Usuario = código de usuario del cliente, en el ej. CCC25501 (Después se los informaremos).
Password = contraseña del usuario del cliente (Después se los informaremos).
Clienteconsulta = Nuevamente deben poner la sigla cliente, en el ej. CCC (Después se los informaremos).
Producto = Es el código del producto definido, por ej. “108410” (Opcional)
NumeroPieza = Es el nro. De pieza de seguimiento que se quiere consultar.
IdPiezaOca = Es el Identificador único de Oca para las piezas a distribuir. (Opcional)
Operativa = Es el código de Operativa comercial del servicio, por ej. “108410” para Pasaportes. (Opcional)
MostrarDatosAdicionales = Vacio

Devuelve lo siguiente :

NumeroPieza = Número de Pieza de Seguimiento.
EstadoMotivo = Estado/Motivo de Tramitación actual de la pieza.
FechaEstado = Fecha/Hora del Estado/Motivo actual de la pieza.
Operativa = Descripción de la Operativa del servicio.
Recibo = Nro. De Recibo de Imposición con que se retiraron las piezas físicas.
Carta = Nro. De Carta de Rendición
Cliente = Descripción del Cliente.
Subservicio = Código de Subservicio OCA.
SucursalOCA = Sigla y Descripción de la sucursal Oca actual de la pieza.
SucursalCliente = Código de Sucursal del Cliente.
IdpiezaOca = Identificador único de Pieza de Oca.
Destinatario = Apellido y Nombre del Destinatario de la pieza.
TipoPieza = Tipo de Pieza, por ej. Pieza Normal, Adicional, Paquetes, etc.
FechaInclusion = Fecha/Hora de la inclusión del lógico de la Pieza si vino con un archivo lógico sino se informa vacio.
FechaEnvio = Fecha/Hora del Envio del cliente del archivo a Oca (Fecha-Hora del Header) si vino con un archivo lógico sino se informa vacio.
PlanillaEnvio = Nro. De Planilla de envio actual de la pieza.
FechaPlanillaEnvio = Fecha/Hora de la Planilla de Envio a las sucursales Oca.
FechaRendicion = Fecha/Hora de Rendición de la Pieza.

En formato XML, informando como cabecera del Dataset la Palabra “ID” + el IdPieza de Oca. Se adjunta un ejemplo de cómo se generaría dicho XML, el cual se puede mostrar dinámicamente en cualquier grilla de Java o .NET por ej. ver figura 1 donde se muestra el XML tal como se genera y como quedaría en una grilla de una página de Explorer.

        
          
        < OCAServiciosDLV2_0 >
            < ID11211446 >
              < NumeroPieza > 1080661 < /NumeroPieza >
              < EstadoMotivo >Rendida al Cliente: Entregada < /EstadoMotivo >
              < FechaEstado >30/08/2010 12:00:00 a.m. < /FechaEstado >
              < Operativa > 108410-Distribucion de Sobres – CCC < /Operativa >
              < Recibo >4843685 < /Recibo >
              < Carta >181121 < /Carta >
              < Cliente > CCC – Cliente de OCA < /Cliente >
              < Subservicio >SS < /Subservicio >
              < SucursalOCA >FLS (FLORES) < /SucursalOCA >
              < SucursalCliente >0000000002 < /SucursalCliente >
              < IdPieza >11211446 < /IdPieza >
              < Destinatario />
              < TipoPieza > Pieza Normal < /TipoPieza >
              < FechaInclusion />
              < FechaEnvio />
              < FechaPlanillaEnvio >11/08/2010 - 03:54:57 p.m. < /FechaPlanillaEnvio >
              < FechaRendicion >19/08/2010 12:26:42 a.m. < /FechaRendicion >
            < /ID11211446 >
          < /OCAServiciosDLV2_0 >

HistoricoSeguimientoXML

Este método devuelve el historial de todos los estados/motivos de una pieza en formato XML.

Tiene 8 parametros de Input: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa

Los mismos se pasan utilizando una coma como delimitador de parámetros (por ej. “CCC,CCC25501,XXXXXX,CCC,,1080661,,” y Donde :

ClienteLogueo = Es la sigla del cliente, en el ej. CCC (Después se los informaremos cuál les corresponde).
Usuario = código de usuario del cliente en el ej. CCC25501 (Después se los informaremos).
Password = contraseña del usuario del cliente (Después se los informaremos).
Clienteconsulta = Nuevamente deben poner la sigla cliente, en el ej. CCC (Después se los informaremos cuál les corresponde).
Producto = Es el código del producto por ej. “VISA”. (Opcional)
NumeroPieza = Es el nro. De pieza de seguimiento.
IdPiezaOca = Es el Identificador único de Oca para las piezas a distribuir. (Opcional)
Operativa = Es el código de Operativa del servicio (Opcional)

Devuelve lo siguiente :

FechaEstadoSolicitud = Fecha/Hora del Estado de la Pieza.
EstadoDescripción = Descripción del Estado ó de la Acción de la Pieza.
MotivoDescripción = Descripción del Motivo de la Pieza.
Usuario = Descripción del Usuario que intervino en ese estado/motivo.
FechaEjecución = Fecha/Hora de Ejecución de la Acción, solo tiene valor cuando el estado de la acción es Ejecutada, Anulada ó Descartada.
Respuesta= Es la descripción del resultado de la acción puede ser ejecutada con éxito, Descartada, Anulada, Ingresada.
Motivo = en el caso de que la acción sea descartada tiene valor e indica el motivo del porque se Descartó la acción.

          
            
  < OCAServiciosDLV2_0 >
    < ID11211446 >
      < FechaEstadoSolicitud>11/08/2010 11:44:28 a.m.< /FechaEstadoSolicitud >
      < EstadoDescripcion>Lógico Recibido< /EstadoDescripcion >
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion >
      < Usuario>Usuario para inclusión. 9W1, SISTEMAS(SISTEMAS)< /Usuario >
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < /ID11211446>
      < FechaEstadoSolicitud>11/08/2010 11:56:16 a.m.< /FechaEstadoSolicitud >
      < EstadoDescripcion>Fisico Recibido< /EstadoDescripcion >
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion >
      < Usuario>Gimenez, Pablo(101606)< /Usuario >
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
      < ID11211446>
      < FechaEstadoSolicitud>11/08/2010 11:57:03 a.m.< /FechaEstadoSolicitud >
      < EstadoDescripcion>A Enviar a Sucursal Oca< /EstadoDescripcion >
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion >
      < Usuario>Gimenez, Pablo(101606)< /Usuario >
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446 >
    < ID11211446 >
      < FechaEstadoSolicitud>11/08/2010 03:54:54 p.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Despachada a Sucursal Oca< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Alonso, Javier(103083)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>12/08/2010 06:13:01 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Recepcionada en Sucursal< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>12/08/2010 03:39:01 p.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>En Distribución< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>14/08/2010 08:11:01 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>En Calle< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>14/08/2010 04:55:02 p.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Despachada a Planta Impositora< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>10/09/2010 11:47:26 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Reenviar< /EstadoDescripcion>
      < MotivoDescripcion />
      < Usuario>romar, lorena(23)< /Usuario>
      < FechaEjecucion>15/09/2010 01:13:33 p.m.< /FechaEjecucion>
      < Respuesta>Ejecutada con éxito< /Respuesta>
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>18/08/2010 10:01:18 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>A Generar Carta de Rendición< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>RAMIREZ OCSA REMBERTO, ANDRES(101612)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>19/08/2010 12:31:03 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Pendiente de Habilitar Carta Para Envio< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>Cabrera, Natalia(79225)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
      < ID11211446>
      < FechaEstadoSolicitud>25/08/2010 07:50:22 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Rendición enviada al Cliente< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>RODRIGUEZ , JUAN DIEGO(78611)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
      < ID11211446>
      < FechaEstadoSolicitud>30/08/2010 12:00:01 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Rendida al Cliente< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
  < / OCAServiciosDLV2_0>

EjecutarAccionXML

Este método se utiliza para poder ingresar acciones a una pieza que está en el sistema, para lo cual el usuario debe tener un perfil habilitado para esa acción y el estado/motivo de la pieza debe permitir ingresar la acción correspondiente.

Tiene 11 parametros de Input: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa, idAccion, delimitador, filler

Donde :

ClienteLogueo = Es la sigla del cliente, en el ej. CCC(Después se los informaremos cuál les corresponde).
Usuario = código de usuario del cliente en el ej. CCC25501 (Después se los informaremos).
Password = contraseña del usuario del cliente (Después se los informaremos).
Clienteconsulta = Nuevamente deben poner la sigla cliente, en el ej. CCC (Después se los informaremos cuál les corresponde).
Producto = Es el código del producto por ej. “VISA”. (Opcional)
NumeroPieza = Es el nro. De pieza de seguimiento que se quiere tomar acciones
IdPiezaOca = Es el Identificador único de Oca para las piezas a distribuir. (Opcional)
Operativa = Es el código de Operativa del servicio. (Opcional)
IdAccion = Es el código de Acción que se quiere ingresar
Delimitador = Indicar el delimitador que utilizaran para parsear los datos que vienen especificados en el filler donde se indican los datos adicionales propios de cada acción; por ej ; (punto y coma)
Filler = se indican separados por el delimitador del parámetro anterior, los datos propios de cada acción, por ej. para una acción de Rescate a Sucursal, se debería especificar algo así si utilizaran el punto y coma como delimitador por ej. 18;Devolver Urgente donde sería una acción de rescate de código 18.

Por ejemplo para una pieza que se le ingresa una acción de rescate a Casa Central (Accion 19) pasando los siguiente parámetros:

CCC, CCC25501,Clavex,CCC,,2008060400303380,,,19,;,Devolver Urgente

Nos estaría devolviendo lo siguiente:

                  
                  < OCAServiciosDLV2_0 > 
                    < ID27007 >
                      < ResultadoIngresoAccion >Acción Ingresada exitosamente – 21/09/2010 18:02:09
                      < /ResultadoIngresoAccion >
                    < /ID27007 >
                  < /OCAServiciosDLV2_0 >

En el caso de generarse algún error por error en los parámetros o errores funcionales de que por ej la pieza no está en condiciones de ingresarse una acción, el Web Services reportará informando el mismo a través de una excepción del tipo SoapException con lo cual si atrapan dicha excepción podrán recibir el mensaje de error correspondiente, por ej. No se puede ingresar la acción, la Pieza tiene acciones pendientes.

AccionPendienteXML

Este método devuelve la acción pendiente de una pieza en formato XML.

Tiene 8 parametros de Input: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa.

Donde:

ClienteLogueo = Es la sigla del cliente, en el ej. CCC (Después se los informaremos cuál les corresponde).
Usuario = código de usuario del cliente en el ej. CCC25501 (Después se los informaremos).
Password = contraseña del usuario del cliente (Después se los informaremos).
Clienteconsulta = Nuevamente deben poner la sigla cliente, en el ej. CCC (Después se los informaremos cuál les corresponde).
Producto = Es el código del producto por ej. “VISA”. (Opcional)
NumeroPieza = Es el nro. De pieza de seguimiento.
IdPiezaOca = Es el Identificador único de Oca para las piezas a distribuir. (Opcional)
Operativa = Es el código de Operativa del servicio. (Opcional)

Devuelve lo siguiente :

IdpiezaOca = Identificador único de Pieza de Oca.
DescripcionAccion = Descripción de la Acción por ej. Repactar
FechaSolicitud = Fecha de Solicitud de la Acción.
UsuarioSolicitud = Usuario que solicitó la acción.
Estado = Estado de la Acción, pueden ser :
- Ingresada: Primer estado de la Acción cuando la ingresa el cliente.
- Pendiente:
  - Si la pieza está en la Sucursal oca, y la misma ejecuta esta acción la cual debe devolver a planta Central para que la ejecute definitivamente, la pieza queda en estado “Pendiente”
- Ejecutada: Es el estado que indica que la acción se ejecutó con éxito.
- Anulada: Si el cliente ingresa una acción de Cancelar, la acción toma este estado
- Descartada: Si al momento de ejecutarse la acción, el estado/motivo de la pieza no permite ejecutar la acción porque por ej. fue entregada la pieza y la acción se descarta.

Por Ejemplo :

                  < OCAServiciosDLV2_0 >
                    < ID6166816 >
                    < DescripcionAccion>Reenviar< /DescripcionAccion >
                    < FechaSolicitud>02/09/2010 11:48:20 a.m.< /FechaSolicitud >
                    < UsuarioSolicitud>romar, lorena< /UsuarioSolicitud >
                    < Estado>Ingresada< /Estado>
                    < /ID6166816>
                  < /OCAServiciosDLV2_0>

AccionesIngresadasXML

Este método devuelve el historial de todas las acciones ingresadas de una pieza en formato XML.

Tiene 8 parametros de Input: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa

Donde:

ClienteLogueo = Es la sigla del cliente, en el ej. CCC (Después se los informaremos cuál les corresponde).
Usuario = código de usuario del cliente en el ej. CCC25501 (Después se los informaremos).
Password = contraseña del usuario del cliente (Después se los informaremos).
Clienteconsulta = Nuevamente deben poner la sigla cliente, en el ej. CCC (Después se los informaremos cuál les corresponde)
Producto = Es el código del producto por ej. “VISA”. (Opcional)
NumeroPieza = Es el nro. De pieza de seguimiento.
IdPiezaOca = Es el Identificador único de Oca para las piezas a distribuir. (Opcional)
Operativa = Es el código de Operativa del servicio. (Opcional)

Devuelve lo siguiente:

IdpiezaOca
DescripcionAccion = Descripción de la Acción por ej. Repactar
FechaSolicitud = Fecha de Solicitud de la Acción.
UsuarioSolicitud = Usuario que solicitó la acción.
Estado = Estado de la Acción, pueden ser :
- Ingresada: Primer estado de la Acción cuando la ingresa el cliente.
- Pendiente:
  - Si la pieza está en la Sucursal oca, y la misma ejecuta esta acción la cual debe devolver a planta Central para que la ejecute definitivamente, la pieza queda en estado “Pendiente”
- Ejecutada: Es el estado que indica que la acción se ejecutó con éxito.
- Anulada: Si el cliente ingresa una acción de Cancelar, la acción toma este estado
- Descartada: Si al momento de ejecutarse la acción, el estado/motivo de la pieza no permite ejecutar la acción porque por ej. fue entregada la pieza y la acción se descarta.
FechaEjecución = Fecha de Ejecución de la Acción, solo tiene valor cuando el estado de la acción es Ejecutada, Anulada ó Descartada.
UsuarioEjecución = Usuario que solicitó la acción, olo tiene valor cuando el estado de la acción es Ejecutada, Anulada ó Descartada.

Por ejemplo para una pieza con 2 acciones ingresadas, muestra el IDpieza en 2 oportunidades, una por cada ocurrencia.
Se adjunta :

                  < OCAServiciosDLV2_0>
                    < ID11142128>
                    < DescripcionAccion>Reenviar< /DescripcionAccion>
                    < FechaSolicitud>27/08/2010 03:42:57 p.m.< /FechaSolicitud>
                    < UsuarioSolicitud>Giambeluca, Leonardo< /UsuarioSolicitud>
                    < Estado>Ejecutada< /Estado>
                    < FechaEjecucion>31/08/2010 09:37:27 a.m.< /FechaEjecucion>
                    < UsuarioEjecucion>gajardo, javier< /UsuarioEjecucion>
                    < /ID11142128>
                    < ID11142128>
                    < DescripcionAccion>Reenviar< /DescripcionAccion>
                    < FechaSolicitud>08/09/2010 10:25:05 a.m.< /FechaSolicitud>
                    < UsuarioSolicitud>Giambeluca, Leonardo< /UsuarioSolicitud>
                    < Estado>Ingresada< /Estado>
                    < /ID11142128>
                  < /OCAServiciosDLV2_0>

Credenciales

Para obtener las credenciales y acceder a los webservices debes ponerte en contacto con nuestra area de sistemas. Lo podes solicitar en la siguiente casilla de correo: integraciones@oca.com.ar