REVELCYL

 

Recursos del Servicio Web


El Servicio Web de RevelCYL permite incorporar la información de todas las recetas emitidas desde cualquier plataforma de receta veterinaria existente que se haya adaptado a los requisitos de importación del mismo.

En esta sección se pueden visualizar y/o descargar todos los documentos necesarios para poder utilizar el servicio web.

Requisitos del Servicio Web Mostrar/Ocultar

Los envíos de datos deben cumplir los siguientes requisitos para ser aceptados por el sistema:

a) Todas las peticiones al servicio web deben estar firmadas.

b) Todos los agentes que intervienen en la receta, veterinarios, equipos veterinarios, dispensadores, titulares de animales, representantes de veterinarios y dispensadores, deben estar dados de alta y autorizados en la plataforma RevelCYL.

En el caso de veterinarios que no estén dados de alta en el sistema, pertenezcan o no a la Comunidad de Castilla y León, deben solicitar el alta, desde la sección de Alta para el Servicio Web de este portal, o bien a través de cualquier Colegio Veterinario de Castilla y León.

En el caso de dispensadores que no estén dados de alta en el sistema, deben solicitar igualmente el alta de la misma manera que los veterinarios.

En el caso de titulares que no estén dados de alta en el sistema, puede solicitar el alta como en los casos anteriores.

En el caso de representantes de veterinarios y dispensadores, deben solicitar el alta en alguno de los Colegios Veterinarios de Castilla y León..

c) Los datos enviados deberán cumplir con los requisitos indicados para la transmisión de la receta original en XML, cumplirán con el protocolo de comunicación SOAP del servicio web especificado, y deberán cumpir como mínimo con el formato "AFIRMA (XAdES-BES)" que firma y envuelve el XML de los datos transmitidos.

El formato XAdES-BES contendrá una firma electrónica realizada por un certificado digital válido en el momento de la firma, aceptado por el sistema RevelCYL y que identifique inequívocamente al autorizado en la transmisión, bien sea veterinario, dispensador o representante de cualquiera de ellos.

Requisitos de la Receta Veterinaria Mostrar/Ocultar

Las recetas que el sistema admitirá deberán cumplir con las siguientes características:

a) Las recetas enviadas deben contener los datos mínimos requeridos en cada tipo de receta.

Los tipos de receta se citan más adelante en el apartado Tipos de Recetas admitidas.

b) Las recetas deben estar firmadas electrónicamente.

La firma electrónica en la receta veterinaria implica que el veterinario disponga de certificado digital válido en el momento de firma y aceptado por el sistema RevelCYL.

Los envíos de recetas realizados serán documentos XML de tipo XML_RecetaVeterinaria conteniendo los datos de prescripción, opcionalmente los de dispensación, y firmadas o no por parte del veterinario.

Si la receta viene firmada usando este formato, el documento XML que se envía será de tipo XML_AFIRMA conteniendo el XML_RecetaVeterinaria indicado y la parte de la firma del veterinario en, como mínimo, el formato XAdES-BES.

Si la receta no viene firmada usando este formato, el documento XML_RecetaVeterinaria que se envía deberá incluir entre sus datos un "Documento Firmado" adjunto el cual será a su vez un XML de tipo XML_AFIRMA válido que contendrá el documento de la receta en un formato "propietario" del sistema informático que lo confeccionó y la parte de la firma del veterinario en, como mínimo, el formato XAdES-BES.

c) Las recetas enviadas pueden estar dispensadas o no dispensadas:

Recetas dispensadas: Son las recetas en las que se indican los datos de dispensación, es decir, que se informa que están dispensadas, quién las ha dispensado y los datos relativos a la dispensación.

Recetas no dispensadas: Son las recetas en las que no se indican los datos de dispensación, es decir, que no están dispensadas o no se conoce esa información.

En este último caso, para permitir cerrar el ciclo de vida de una receta, los dispensadores y representantes de dispensadores tendrán la posibilidad de transmitir la dispensación de recetas utilizando exclusivamente el apartado de datos de "Dispensación" del formato XML_RecetaVeterinaria.

Tipos de Recetas admitidas Mostrar/Ocultar

Las recetas que son obligatorias enviar al sistema son aquellas realizadas principalmente a animales destinados a consumo humano y/o produzcan alimentos que se destinen al consumo humano. Además se incluyen también las de animales de compañia o pequeñas mascotas.

Estas serán del tipo:

a) Receta de medicamentos.

b) Receta de piensos medicamentosos.

c) Receta de autovacuna.

d) Receta de fórmula magistral.

e) Receta no válida para dispensar.

f) Receta de pequeñas mascotas.

Certificados admitidos Mostrar/Ocultar

Un certificado digital es un documento electrónico con funciones equivalentes a un documento oficial de identidad y que sirve para dar validez legal a las transacciones electrónicas que pueda realizar cualquier interesado.

Para garantizar la validez jurídica de los datos enviados es necesario identificarse mediante alguno de los certificados digitales admitidos en el servicio web, los cuales son:

- DNIe: Certificados de DNI Electrónico.(Dirección General de Policía - Ministerio del Interior)

- FNMT: Certificados de Identificación de Persona Física o Jurídica de la FNMT.(Fábrica Nacional de Moneda y Timbre)

- FNMT-RCM: Certificados de Identificación Personal de la FNMT-RCM.(Fábrica Nacional de Moneda y Timbre - Real Casa de la Moneda)

- CAMERFIRMA: Certificados de Identificación Personal o de Colegiado Veterinario.(Autoridad de Certificación de las Cámaras de Comercio Españolas)

Dirección de acceso, protocolo, punto de entrada y seguridad Mostrar/Ocultar

La dirección de acceso al portal web de información y ayuda del sistema RevelCYL es:https://revelcyl.es

La dirección de acceso al portal web de gestión del propio sistema RevelCYL se hace mediante protocolo HTTP seguro (dirección que empieza por "https://") proporcionado por un certificado digital que certifica la autenticidad del servidor que lo aloja.

El intercambio de información con el servicio web será mediante el protocolo SOAP, accediendo a través del punto de entrada del servicio correspondiente.

La URL de acceso para obtener la descripción WSDL del servicio web es:https://revelcyl.es/wsdl

La URL para realizar una petición específica al servicio es:https://revelcyl.es/wsvc

SEGURIDAD

Dado que el servicio web es de tipo seguro, para poder utilizarlo es necesario que la petición SOAP que se realiza contenga la información firmada, con lo que será necesario un certificado digital de entre los admitidos por el sistema RevelCYL. Así mismo, la identificación de la entidad, extraida de los datos del certificado, deberá estar autorizada como usuario dentro del servicio web, tal y como se indica en las Condiciones de Acceso.

MODO DE PRUEBAS

La admisión en el sistema RevelCYL de transmisiones de datos reales está supeditada a la realización previa de comunicaciones de datos en modo de prueba. Ésto es para comprobar y confirmar que el sistema externo utilizado genera los datos correctamente, cumple con los formatos especificados para cada tipo de envío, es decir, crea bien los XML con los datos de la receta e incluye la firma adecuadamente, que el formato del elemento de firma cumple, como mínimo, con el formato XAdES-BES y realiza la petición SOAP correctamente.

Las direcciones para acceder al servicio web en "MODO PRUEBA" son:

Para obtener la descripción WSDL del servicio web en pruebas, la URL es:https://revelcyl.es/wsdl_prueba

Para realizar una petición específica al servicio en pruebas, la URL es:https://revelcyl.es/wsvc_prueba

Condiciones de Acceso Mostrar/Ocultar

Como ya se ha indicado, para poder realizar peticiones al servicio web, los certificados digitales utilizados en la tranmisión deben identificar inequívocamente a alguno de los usuarios autorizados en el sistema RevelCYL, por el NIF/CIF extraído del mismo, en concreto:

a) Como usuario de tipo Veterinario si actúa en nombre propio con un certificado personal o de colegiado veterinario.

b) Como usuario de tipo Equipo Veterinario si actúa en nombre de los veterinarios que tenga asociados y usa un certificado personal o de entidad.

c) Como usuario Dispensador si actúa en nombre propio con un certificado personal o de entidad.

d) Como usuario especial Representante Veterinario si actúa en nombre de uno o varios veterinarios que le hayan dado autorización y permiso para actuar en su nombre en el sistema. En ese caso el NIF/CIF extraído del certificado deberá coincidir con la entidad a la que el veterinario le ha asignado el permiso de representación.

e) Como usuario especial Representante Dispensador si actúa en nombre de uno o varios dispensadores que le hayan dado permiso para actuar en su nombre en el sistema. En ese caso el NIF/CIF extraído del certificado deberá coincidir con la entidad a la que el dispensador le ha asignado el permiso de representación.

Peticiones al Servicio Web: Datos Generales SOAP y XML-AFIRMA Mostrar/Ocultar

Las peticiones al servicio web se deben realizar mediante el protocolo SOAP, el cual se implementa a través de peticiones HTTP-POST usando un envoltorio SOAP en el cuerpo de la petición HTTP.

Todas las peticiones realizadas al servicio deberán ir encapsuladas en un XML con los datos correspondientes, firmado con el certificado del usuario autorizado para la transmisión, y envuelto en un XML de tipo AFIRMA (XAdES-BES) el cual se incluirá en la petición SOAP como contenido XML no procesable para evitar posibles fallos de interpretación del contenido.

SOLICITUD SOAP

El formato de una petición SOAP será como:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:rec="RecetaWS"> <soapenv:Header/> <soapenv:Body> <rec:[[funcion_a_invocar]] soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <xml xsi:type="xsd:string"> <!-- ...en esta zona va el XML_AFIRMA con la peticion firmada... --> <![CDATA[XML_AFIRMA]]> </xml> </rec:[[funcion_a_invocar]]> </soapenv:Body> </soapenv:Envelope>

En este formato, se debe sustituir el contenido indicado como [[funcion_a_invocar]], por el nombre de la función que se desea invocar en la llamada, y el contenido XML_AFIRMA por el resultado de encapsular la petición XML como un documento firmado.

FORMATO XML-AFIRMA PARA PETICIONES SOAP

El formado de los documentos firmados que se acepta es el siguiente:

<?xml version="1.0" encoding="UTF-8"?> <AFIRMA> <CONTENT Encoding="UTF-8" Id="[[ID_Contenido_Firmado]]" MimeType="application/octet-stream" Algorithm= "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"> [[HASH_SHA512(XML_Compacto_con_Solicitud)]] </CONTENT> <NOMBRE_ORIGINAL> [[Nombre_Documento_con_Solicitud]] </NOMBRE_ORIGINAL> <DOCUMENTO> [[BASE64(XML_Compacto_con_Solicitud)]] </DOCUMENTO> [[Firma_del_HASH_en_Formato_XADES-BES]] <!— aqui va el resultado de la firma propiamente dicho, un nodo de tipo... <ds:Signature> ... </ds:Signature> --> </AFIRMA>

Este formato es una firma tipo "XAdES Enveloped", donde la información que se firma se identifica por el ID [[ID_Contenido_Firmado]] que se puede generar de forma diferente en las distintas peticiones, o establecer un identificador único y mantenerlo para facilitar la codificación de la firma.

El ID está contenido en la etiqueta <CONTENT>, siendo en este caso un hash de tipo "SHA-512" calculado en función del XML con los datos de la solicitud XML_Compacto_con_Solicitud, compactado de forma que no tenga saltos de línea, retornos de carro, ni espacios o tabuladores entre etiquetas.

Por otra parte, el mismo documento XML compactado se codifica en "Base64" para incluirlo dentro de la etiqueta <DOCUMENTO>, y así poder recuperarlo a la hora de validar la firma, o al comparar con los datos originales en la base de datos, contrastarlos con el PDF generado, etc.

El elemento <NOMBRE_ORIGINAL> será o simulará el nombre del archivo que representa el documento XML original, y sustituirá al contenido [[Nombre_Documento_con_Solicitud]].

La firma que irá dentro del elemento <ds:Signature>, y que sustituirá al contenido <[[Firma_del_HASH_en_Formato_XAdES-BES]]>, contendrá toda la información relativa a la misma (hash de firma, certificado de usuario utilizado, información del certificado del emisor, momento de la firma, ...).

Se recomienda que el algoritmo de firma sea un hash de tipo SHA-512 para que la firma sea lo suficientemente robusta como para perdurar durante varios años.

El certificado que se debe utilizar para realizar esta firma, será la de un usuario autorizado para la transmisión.

Formato para la Receta Veterinaria firmada Mostrar/Ocultar

En el caso de que el documento que se va a transmitir en la petición SOAP sea el de una receta firmada por un veterinario, se sustituirá el documento indicado en la petición como XML_Compacto_con_Solicitud por el que se denomina XML-AFIRMA-VET, el cual es similar al XML-AFIRMA, y donde el contenido que se firma es el hash de un documento de tipo XML RecetaVeterinaria preparado de forma compacta.

El formado de los documentos firmados propuesto es el siguiente:

<?xml version="1.0" encoding="UTF-8"?> <AFIRMA> <CONTENT Encoding="UTF-8" Id="[[ID_Contenido_Firmado]]" MimeType="application/octet-stream" Algorithm= "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"> [[HASH_SHA512(XML_Compacto_con_RecetaVeterinaria)]] </CONTENT> <NOMBRE_ORIGINAL> [[Receta_EJER_DIST_PROV_COLEG_NUM.xml]] </NOMBRE_ORIGINAL> <DOCUMENTO> [[BASE64(XML_Compacto_con_RecetaVeterinaria)]] </DOCUMENTO> [[Firma_del_HASH_en_Formato_XADES-BES]] <!— aqui va el resultado de la firma propiamente dicho, un nodo de tipo... <ds:Signature> ... </ds:Signature> --> </AFIRMA>

Como ya se ha explicado anteriormente, este formato contiene una firma tipo "XAdES Enveloped", donde la información que se firma se identifica por el ID [[ID_Contenido_Firmado]] que se puede generar de forma diferente en las distintas peticiones, o establecer un identificador único y mantenerlo para facilitar la codificación de la firma.

El ID está contenido en la etiqueta <CONTENT>, siendo en este caso un hash de tipo "SHA-512" calculado en función del XML con los datos de la receta XML_Compacto_con_RecetaVeterinaria, compactado de forma que no tenga saltos de línea, retornos de carro, ni espacios o tabuladores entre etiquetas.

Por otra parte, el mismo documento XML compactado se codifica en "Base64" para incluirlo dentro de la etiqueta <DOCUMENTO>, y así poder recuperarlo a la hora de validar la firma, o al comparar con los datos originales en la base de datos, contrastarlos con el PDF generado, etc.

El elemento <NOMBRE_ORIGINAL> será o simulará el nombre del archivo que representa el documento XML original, y en este caso, identificará la receta por su código único (Ejercicio, Distintivo, CódigoProvincia, NumColegiado, NumReceta) unidos por el separador "_". Con este nombre se sustituirá el contenido [[Receta_EJER_DIST_PROV_COLEG_NUM.xml]].

La firma que irá dentro del elemento <ds:Signature>, y que sustituirá al contenido <[[Firma_del_HASH_en_Formato_XAdES-BES]]>, contendrá toda la información relativa a la misma (hash de firma, certificado de usuario utilizado, información del certificado del emisor, momento de la firma, ...).

Se recomienda que el algoritmo de firma sea un hash de tipo SHA-512 para que la firma sea lo suficientemente robusta como para perdurar durante varios años.

El certificado que se debe utilizar para realizar esta firma, será la de un veterinario autorizado para la emisión de recetas por el colegio al que pertenece, y que esté activo como usuario del sistema.

SELLO DE TIEMPO Y EXTENSIÓN DE FORMATO

Dado que en este caso la firma de la receta no se realiza desde la plataforma SicylVET, la cual asegura que el momento temporal de la firma es el actual (salvo algunos segundos de variación por las comunicaciones y márgenes de tiempo entre equipo servidor y cliente), y asegura que el certificado usado por el veterinario es válido en ese momento, rechazando todo el proceso si éste no lo es o está revocado; se deben asegurar de forma externa estas condiciones.

Para poder asegurar que la firma se ha realizado con un certificado válido en el momento en el que se hizo, el elemento <ds:Signature>, deberá incluir los nodos XAdES necesarios para que el formato de la misma pase de ser de tipo XAdES-BES a tipo XAdES-T incluyendo un sello de tiempo de una entidad externa válida, y de éste a tipo XAdES-C para que se incluyan las referencias completas de comprobación/revocación del certificado del veterinario utilizado en la firma.

Estas condiciones necesarias para transmitir recetas firmadas hace un poco más complejo el sistema externo, pero asegura que la información es fiable y verificable en todo momento.

Respuestas generales: SOAP y estructura DTD Mostrar/Ocultar

RESPUESTA SOAP

Una respuesta válida a cualquier petición, una vez extraída del elemento return de la respuesta SOAP recibida, será una cadena de texto con el resultado de la petición.

El resultado estará codificado en formato XML de forma predeterminada.

El esquema de la respuesta SOAP es:

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns= "importarRecetaVeterinaria" xmlns:xsd= "http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC= "http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <tns:[[funcion_invocada]]Response> <return xsi:type="xsd:string"> [[RESULTADO]] <!-- ...en esta zona va el resultado codificado en XML... --> </return> </tns:[[funcion_invocada]]Response> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

La codificación de resultados podrá estar envuelta en una sección XML de contenido no procesable, es decir, envuelto en <![CDATA[RESULTADO]]>, en caso de que el contenido lo requiera.

FORMATO DEL XML CON RESULTADO GENÉRICO: ESTRUCTURA DTD

El resultado de la llamada al Ws viene en el elemento ResultadoWS. El esquema DTD del XML con el resultado genérico es el siguiente:

<!DOCTYPE ResultadoWS [ <!-- Resultado del Servicio Web --> <!ELEMENT ResultadoWS (Resultado, Mensaje, FechaHora, RefTransmision, Saldo?, CodSegVerificacion?, Errores?)> <!-- Lista de errores si hay más de uno en total. --> <!ELEMENT Errores (Error+)> <!ELEMENT Error (Codigo, Texto)> <!-- El "Codigo" es el codgo de resultado del error, y el "Texto" es el mensaje descriptivo del error. --> <!ELEMENT Resultado (#PCDATA)> <!ELEMENT Mensaje (#PCDATA)> <!ELEMENT FechaHora (#PCDATA)> <!ELEMENT RefTransmision (#PCDATA)> <!ELEMENT Saldo (#PCDATA)> <!ELEMENT CodSegVerificacion (#PCDATA)> <!ELEMENT Codigo (#PCDATA)> <!ELEMENT Texto (#PCDATA)> ]>

Los parámetros contenidos en el documento XML de respuesta son fácilmente reconocibles, aunque hay que hacer algunas aclaraciones:

Resultado: Valor numérico que si es 0 (CERO), el resultado es correcto (no hay error). Cualquier otro valor indicará un resultado erróneo y ese mismo valor será el código de error producido.

Mensaje: Texto descriptivo del resultado, o cadena vacía si el resultado es correcto (0).

FechaHora: La fecha y hora del sistema en el momento de dar la respuesta a la petición. Puede servir para calcular la duración de una solicitud en tiempo, o para sincronizar la hora del sistema externo con la del servidor.

RefTransmision: Identificador de referencia de la transmisión realizada, generada por el sistema de forma única y que sirve para el control de las mismas a la hora de comprobar su validez; o como referencia para el sistema externo en caso de que se detecten incidencias.

CodSegVerificacion: código seguro de verificación de la receta una vez que se haya importado correctamente.

Errores: Lista ampliada de errores producidos en el proceso del tratamiento de la transmisión. Sólo aparece este elemento si hay más de un error en el proceso ya que si sólo hay uno, se tendrá en los elementos "Resultado" y "Mensaje".

Error: Detalle de cada error con su código de resultado y mensaje de texto en los elementos "Código" y "Texto" respectivamente.

Función "ImportarRecetaVeterinaria()" Mostrar/Ocultar

Esta función es la que permite realizar la importación de datos de recetas veterinarias. Su prototipo es:

string importarRecetaVeterinaria( string xml)

La llamada admite un argumento de tipo cadena que será el XML-AFIRMA descrito anteriormente y, dentro de éste se tendrá el XML con los datos de la receta que se desea enviar al sistema RevelCYL para que la importe.

Una respuesta válida a esta petición indicará que la receta ha sido importada por el sistema y almacenada. Una respuesta errónea indica que la receta en ningún caso ha sido almacenada.

Ejemplos XML RecetaVeterinaria Mostrar/Ocultar

Los siguientes ejemplos muestran cómo deberían enviarse diferentes tipos de recetas y en función de si están o no dispensadas.

En la creación de los XML es importante tener en cuenta que los campos de texto libres que puedan contener caracteres no válidos para el contenido de un elemento XML, y que provocaría la invalidación del mismo, se deben envolver obligatoriamente en el elemento <![CDATA[campotextolibre]]>, tal y como se muestra en algunos ejemplos.

Descarga de Ficheros Mostrar/Ocultar

En esta sección se pueden descargar los documentos necesarios para entender y porder utilizar el servicio web de Receta Veterinaria Electrónica.

Aviso Legal Mostrar/Ocultar