Manual de Usuario

Portal de datos abiertos

La estructura del Portal se detalla a continuación:

1. Inicio: página principal donde se presenta una breve introducción al portal y las opciones de navegación disponibles.
2. Visualizaciones: sección que lista las diferentes visualizaciones desarrolladas y provee el enlace para acceder a ellas.
3. Explorar los Datos: se presentan los conjuntos de datos publicados por la DNCP y una breve explicación para desarrolladores/programadores.
4. Diccionario: presenta el diccionario de datos de la DNCP en formato tabular. Además permite descargar el archivo “.owl” correspondiente al mismo.
5. Mis aplicaciones: sección que permite al usuario gestionar sus aplicaciones. Requiere inicio de sesión.
6. Ayuda: activa la ayuda interactiva. Disponible para las secciones: “Inicio” y “Mis aplicaciones”.
7. Acerca de: información básica sobre el Portal de Datos Abiertos.
8. Aviso legal: descripción de los términos y/o condiciones legales referentes al Portal de Datos Abiertos.

Figura 1: Página principal del Portal de Datos Abiertos de la DNCP

CONJUNTOS DE DATOS

Se eligieron para ser publicados en el Portal de Datos Abiertos de la Dirección Nacional de Contrataciones del Paraguay (DNCP) los siguientes conjuntos de datos:

• Planificaciones: Contienen información básica acerca de las necesidades presentadas por las Unidades Operativas de Contratación (UOCs), que se buscan satisfacer por medio de una convocatoria.
• Convocatorias: Avisos o llamados a licitación pública que contienen información básica para que los oferentes puedan determinar su interés de participar.
• Adjudicaciones: Resultados de las licitaciones en las cuales se determinan los proveedores adjudicados y el monto adjudicado. Contratos: Información básica acerca de los contratos firmados con los proveedores adjudicados.
• Modificaciones de contratos: Información básica acerca de las modificaciones realizadas a los contratos firmados con los proveedores adjudicados.

Los datos publicados por la DNCP siguen el estándar propuesto por Tim Berners-Lee que sugiere agrupar el tipo de publicación de los datos en niveles según determinadas características, los niveles se representan por medio de estrellas.

Los conjuntos de datos publicados en CSV corresponden al nivel de 3 estrellas, mientras que los servicios, cuya respuesta retorna los datos en formato JSON-LD corresponden al nivel de 5 estrellas. Para cada uno de los conjuntos de datos publicados son posibles las siguientes acciones:

Figura 2: Acciones disponibles para cada conjunto de datos

1. Explorar: enlace a la vista tabular del conjunto de datos.
2. Documentación: enlace a la documentación de los servicios web disponibles.
3. Diccionario: enlace al diccionario de datos.
4. Descargas: enlace a la página de descarga de los archivos CSV.
5. JSON-LD: enlace a un ejemplo de respuesta JSON-LD de la API Rest.
6. @Context en JSON-LD: enlace al contexto del JSON-LD.

Conjuntos de Datos: CSV

Todos los conjuntos de datos publicados pueden descargarse en formato CSV, desde el año 2010 en adelante. Para acceder a la página de descargas de un determinado conjunto de dato se debe hacer click en la acción “Descargas” como se muestra en la Figura 3, lo cual redirecciona la página de descargas de la Figura 4 (se utiliza el conjunto de planificaciones como ejemplo).

Figura 3: Enlace a la página de descarga de los conjuntos de datos en formato CSV.

Figura 4: Página de descarga de los conjuntos de datos en formato CSV (años 2010 a 2015).

Por cada archivo CSV se disponibiliza además el código de comprobación, para lo cual se utiliza el algoritmo de reducción criptográfica “MD5”1. Este código de comprobación cambia siempre que el contenido del archivo CSV al que corresponde se modifique.

La generación de los archivos CSV y sus códigos de comprobación se realizan como un proceso de sistema de manera diaria, por tal motivo se provee también la fecha de la última actualización.

Diccionario de Datos: HTML

Un diccionario de datos es un conjunto de metadatos que ofrece información o características de los datos. Sirve para que el usuario final pueda conocer las propiedades de los datos que están publicados como el nombre, la descripción, el tipo de dato, su cardinalidad, ejemplos, restricciones, etc.

Todos los conjuntos de datos publicados cuentan con una sección dentro del diccionario de datos de la DNCP. Para acceder a la página del diccionario de un determinado conjunto de dato se debe hacer click en la acción “Diccionario” como se muestra en la Figura 5, lo cual redirecciona a la página del diccionario de la Figura 6 (se utiliza el conjunto de planificaciones como ejemplo).

Figura 5: Enlace a la página del diccionario de datos

Figura 6: Diccionario de datos de la clase Planificación

En esta página se presentan las propiedades del conjunto de datos de manera tabular. Las filas indican las propiedades y las columnas representan las características o descripciones de cada propiedad.

Se detallan a continuación las columnas del diccionario:

1. Propiedad en json-ld: Estable el nombre de la propiedad exactamente como se devuelve en el servicio.
2. Nombre de la propiedad: nombre completo de la propiedad.
3. Label: establece el nombre de la propiedad en español.
4. Labels alternativos: establece los nombres alternativos de la propiedad en español.
5. Ejemplos: los valores de ejemplo.
6. Tipo de datos: el tipo de dato esperado de los valores del atributo. Por ejemplo: String, Float, etc. Idealmente se deben utilizar los tipos de datos definidos en el Estándar XMl Schema Datatypes de la W3C http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes, por ejemplo: xsd:string, xsd:boolean, xsd:dateTime.
7. Cardinalidad: establece la relación que existe entre la clase padre e hija.
8. Restricciones: en caso que existan, se especifican las restricciones de los datos.
9. Descripción: describe con más detalle los datos que se encuentran en el atributo en el idioma español.
10. Propiedad equivalente: de existir, se especifica la correspondencia con una propiedad del estándar de datos de Open Contracting.

Estas columnas junto con su descripción se presentan en el Portal al pie del diccionario mediante una tabla de referencia como se muestra en la Figura 7.

Figura 7: Tabla de referencia para las columnas del diccionario de datos

Vista tabular de los conjuntos de datos

Para cada uno de los conjuntos de datos se presenta una vista en formato tabular. Para acceder a la vista tabular de un determinado conjunto de datos se debe hacer click en la acción “Explorar” como se muestra en la Figura 8, lo cual redireccionará a la página con la tabla de la Figura 9 (se utiliza el conjunto de planificaciones como ejemplo).

Figura 8: Enlace a la vista tabular del conjunto de datos

La tabla de la Figura 9 permite realizar dos tipos de filtros: uno global y otro particular. El filtro global busca coincidencias en todas las columnas, mientras que los filtros particulares buscan coincidencia en la columna sobre la cual se especifican.

La tabla cuenta además con paginado y permite seleccionar la cantidad de elementos que se desean ver por página.

Adicionalmente, existe la opción de descargar los datos filtrados en formato CSV, para ello se debe aplicar filtros sobre la tabla y luego hacer click en el botón “CSV” que se encuentra al pie de la tabla.

Figura 9: Vista tabular para el conjunto de datos “Planificaciones”

Servicios Web JSON-LD

Se realizó la puesta en producción de seis grupos de servicios web, basados en los servicios internos de la DNCP. Estos servicios, los cuales retornan recursos en forma JSON-LD, corresponden al nivel de datos a cinco estrellas según el modelo de Tim Berners-Lee.

Los servicios web permiten a los desarrolladores acceder a información relacionada a las distintas etapas de las licitaciones públicas en tiempo real, es decir, siempre la respuesta devuelve la última versión de los datos. Están dirigidos principalmente a programadores/desarrolladores de aplicaciones.

Un archivo JSON-LD permite, además de incluir todas las propiedades publicadas por la DNCP, hacer referencia a:

1. Descripción de las propiedades del archivo JSON original mediante referencias al modelo formal definido. Esto permite acceder a metadatos de la propiedad como su formato, cardinalidad, restricciones y propiedades equivalentes a la misma.
2. Otros recursos relacionados al recurso JSON original. Esto se logra mediante la utilización de las URIs que identifican a los recursos relacionados. Los recursos JSON-LD publicados se representan utilizando una sintaxis válida para archivo JSON, lo cual representa una ventaja importante debido al alto grado de adopción de este formato en aplicaciones web y la diversidad de herramientas disponibles para su procesamiento.

A continuación se expone la respuesta JSON-LD de una petición al servicio de planificaciones por id:

{
"@context": "/datos/contexts/planificacion.json",
  "@graph": [
    {
      "categoria": {
        "id": 40,
        "codigo": 24,
        "nombre": "Equipos, accesorios y programas computacionales, de oficina, educativos, de imprenta, de comunicación y señalamiento"
      },
      "tipo_procedimiento": {
        "id": 3,
        "codigo": "CO",
        "nombre": "Concurso de Ofertas"
      },
      "moneda": {
        "codigo": "PYG",
        "nombre": "Guaraníes"
      },
      "estado": {
        "codigo": "ADJ",
        "nombre": "Adjudicado (Ejecutado)"
      },
      "id": "193399-adquisicion-scanner",
      "anio": 2010,
      "id_llamado": 193399,
      "nombre_licitacion": "Adquisición de Scanner",
      "convocante": "Dirección Nacional de Contrataciones Públicas (Dncp)",
      "fecha_estimada": "2010-02-22",
      "fecha_publicacion": null,
      "etiquetas": [
        "_subasta"
      ],
      "@id": "/datos/id/planificaciones/193399-adquisicion-scanner",
      "@type": "planificacion",
      "formato": "application/ld+json",
      "license": "http://creativecommons.org/licenses/by/4.0/",
      "convocatorias": "/datos/doc/planificaciones/193399-adquisicion-scanner/convocatorias",
      "adjudicaciones": "/datos/doc/planificaciones/193399-adquisicion-scanner/adjudicaciones"
    }
  ]
}

Documentación Online: Swagger

Para la documentación online se utilizó la librería Swagger1. Esta librería genera una interfaz interactiva que permite producir, visualizar y consumir servicios expuestos mediante una API Rest. Para acceder a la documentación hacer click en “Documentación” del menú desplegable en la tabla de conjuntos de datos y se redireccionará a la página de la Figura 8.

La documentación generada presenta la siguiente estructura:

Figura 10 Documentación online: Lista de servicios disponibles

Los servicios se muestran separados según el módulo al que corresponden. Dentro de cada módulo se listan los servicios disponibles, a la izquierda se especifica el método HTTP, a continuación la URL y luego una breve descripción.

El primer paso para la utilización de los servicios es autenticarse en el sistema, para ello se utiliza el modelo de autenticación OAuth. Para más detalles acerca del método de autenticación ir a la Sección Guía para desarolladores.

El detalle de pasos a seguir para realizar la autenticación OAuth se encuentra en la Sección Tutorial: Creando una Aplicación de Datos Abiertos.

Una vez que la aplicación se ha autenticado, tendrá a su disposición el access_token requerido para realizar las peticiones a los servicios web.

Para visualizar y consumir un servicio específico se debe hacer click sobre el ítem de la lista como se muestra en la Figura 9.

Figura 11: Documentación online: Módulo planificaciones

Se desplegará formulario de la Figura 10 que detalla los diferentes parámetros del servicio, valores de ejemplo, el tipo de parámetro y el tipo de dato.

Figura 12: Documentación online: Servicio planificaciones por id

Haciendo click en “Try it out!” se realizará una petición al servicio y se podrá ver la respuesta del mismo más abajo en formato JSON-LD como se muestra en la Figura 11.

Figura 13: Documentación online: Respuesta del servicio de planificaciones por id

Diccionario de datos: OWL

OWL (Web Ontology Language) es un lenguaje de marcado cuya finalidad es describir de manera formal la estructura de un dominio de conocimiento. Sirve para cuando la información necesita ser procesada por programas o aplicaciones, en contraste a situaciones donde el contenido necesita sólo ser presentado a los seres humanos. Se utiliza para representar términos y sus relaciones, tal representación es la que se conoce como ontología.

El diccionario de datos OWL de la DNCP se encuentra disponible en /datos/def/dncp.owl , igualmente se puede acceder desde el portal por medio del enlace de “Descarga” en la página del “Diccionario de Datos” como se muestra en la Figura 12.

Figura 14: Enlace de descarga del archivo OWL

El diccionario OWL tiene la siguiente información y estructura:

• Nombre de la ontología y una breve descripción. (Figura 13)

Figura 15 OWL : Nombre y descripción de la ontología

• Para cada clase (se toma como ejemplo la clase Planificación) se especifica la descripción y etiqueta en los diferentes idiomas soportados. (Figura 14)

Figura 16 OWL: Clase Planificación

• Para cada atributo de la clase u objeto (se toma como ejemplo la clase Planificación) se especifica el dominio al que pertenece, el tipo de dato, la descripción y etiquetas en los diferentes idiomas soportados. “Domain” hace referencia a la clase padre del atributo. “Range” hace referencia al tipo de dato del atributo. (Figura 15)

Figura 17 OWL: Atributo id del llamado de la clase planificación

• Si el atributo fuera otra clase, entonces el tipo de dato especificado en “range” sería el nombre de la clase. (Figura 16)

Figura 18 OWL: Atributo estado de la clase planificación

Para más información acerca de OWL, su definición, estructura y contenido ir a http://www.w3.org/TR/2012/REC-owl2-quick-reference-20121211/#Class_Expressions.

Guía para Desarrolladores

Autenticación: OAuth

El esquema de autenticación propuesto se basa en el protocolo OAuth en su versión 2, en particular en el flujo de concesión de credenciales de cliente, el cual define una secuencia de pasos a seguir para la autenticación entre cliente y servidor HTTP.

El acceso a los servicios de datos abiertos se lleva a cabo utilizando credenciales de acceso previamente generadas por el sistema de autenticación, las cuales reciben el nombre de CONSUMER KEY y CONSUMER SECRET.

Estas credenciales se generan bajo demanda, y permiten identificar unívocamente a una aplicación registrada. Para solicitar la generación de credenciales para su aplicación, un desarrollador deberá registrarse como consumidor de los servicios de la DNCP, utilizando una aplicación web disponible para tal efecto en el Portal de la DNCP. El registro del usuario podrá realizarse utilizando su correo electrónico, o cuentas de servicios externos como Google o Github.

Secuencia de Autenticación

Precondiciones

1. El desarrollador de la aplicación cliente debe tener en su poder las credenciales de acceso: CONSUMER KEY y CONSUMER SECRET previamente generadas.
2. Las solicitudes (como mínimo la del intercambio inicial de credenciales) deberán hacerse por HTTPS.

Postcondiciones

1. Solicitudes autorizadas se responden con el código HTTP 200.
2. Cualquier solicitud previa a la autenticación se responde con HTTP 401.
3. Pasando el límite de solicitudes, se responde con HTTP 429.

Figura 19: Secuencia de autenticación OAuth

Secuencia de Petición a Servicios de Datos Abiertos

Precondiciones

1. La aplicación deberá conocer el token proveído por la API al final de la fase de autenticación.
2. Las solicitudes deberán hacerse por HTTPS.

Postcondiciones

1. Solicitudes autorizadas se responden con el código HTTP 200.
2. Cualquier solicitud previa a la autenticación se responde con HTTP 401.
3. Pasando el límite de solicitudes, se responde con HTTP 429.

Figura 20: Secuencia de petición a un servicio de datos abiertos

Tutorial: Creando una Aplicación de Datos Abiertos

La utilización de servicios de Datos Abiertos requiere que el usuario tenga registrada una aplicación. Para ingresar a la sección de gestión de aplicaciones hacer click en “Mis aplicaciones” del menú principal.

Figura 21 Mis aplicaciones: Inicio de sesión

Para gestionar aplicaciones el usuario debe estar registrado en el Portal. El registro de usuario puede realizarse proporcionando nombre de usuario y contraseña, o bien utilizando la autenticación vía Google o Github. Una vez que el usuario está registrado puede iniciar sesión e ingresar a la lista de aplicaciones (Figura 20). En caso de que sea un usuario nuevo, la lista se muestra vacía porque todavía no cuenta con aplicaciones creadas.

Figura 22 Mis aplicaciones: Lista de aplicaciones

Para crear una nueva aplicación hacer click en el botón “Crear Nueva Aplicación”, lo cual mostrará el formulario de creación de aplicaciones como se muestra en la Figura 21.

Figura 23 Mis aplicaciones: Formulario de creación de una aplicación

Para confirmar los datos y crear la aplicación hacer click en “Guardar”. Para descartar los cambios ir atrás con el botón del navegador o hacer click en cualquier elemento del menú.

Figura 24 Mis aplicaciones: Lista de aplicaciones

Para consultar una aplicación existente hacer click sobre el nombre de la aplicación en la lista, lo cual mostrará el formulario con los datos de dicha aplicación y tres posibles acciones: “Modificar”, “Eliminar” y “Regenerar Keys” como se muestra en la Figura 23.

Figura 25 Mis aplicaciones: Vista de consulta de una aplicación

Modificar: Para modificar la aplicación hacer click en “Modificar Aplicación”, lo cual mostrará el formulario de modificación de aplicaciones como se muestra en la Figura 24.

Figura 26 Mis aplicaciones: Formulario de modificación de una aplicación

Para confirmar los cambios y modificar la aplicación hacer click en “Guardar”- Para descartar los cambios ir atrás con el botón del navegador o hacer click en cualquier elemento del menú.

Eliminar: Para eliminar la aplicación hacer click en el botón “Eliminar”, se mostrará una ventana emergente para confirmar la eliminación (Figura 25).

Figura 27 Mis aplicaciones: Mensaje de confirmación para eliminar de la aplicación

Para confirmar hacer click en “Eliminar”, para descartar hacer click en “Cancelar” o salir con la cruz de la esquina superior derecha.

Regenerar keys: Para regenerar las claves de la aplicación hacer click en el botón “Regenerar Keys”, se mostrará una ventana emergente para confirmar la regeneración de las claves (Figura 26).

Figura 28 Mis aplicaciones: Mensaje de confirmación para regenerar keys de la aplicación

Para confirmar hacer click en “Regenerar”, para descartar hacer click en “Cancelar” o salir con la cruz de la esquina superior derecha.

Una vez que el usuario haya creado su aplicación o aplicaciones podrá utilizar las claves generadas para realizar peticiones a los Servicios de Datos Abiertos.

En el formulario de consulta de la aplicación se muestran el Consumer Key y el Consumer Secret generados para la aplicación, además se muestra el request token (Figura 27) correspondiente a la concatenación de ambas claves mediante “:” (dos puntos) y convertido a Base64. Este request token es el que deberá utilizar el usuario para realizar la autenticación OAuth.

Figura 29 Request token de una aplicación

Autenticación de la aplicación con la API Rest

Una vez que el usuario ha registrado su aplicación puede autenticarla con la API realizando una petición POST a la URL /datos/oauth/token. Se debe pasar el request token como parámetro de la cabecera “Authorization” con el formato Basic [request_token] como se muestra en la Figura 28.

Si el request token no es válido se verá el resultado de la Figura 29.

Figura 31 Servicio de autenticación: Request token incorrecto

Si por algún motivo se quiere invalidar el access token de una aplicación, se puede realizar una petición POST a la URL /datos/oauth/invalidate_token. Se debe pasar el request token como parámetro de la cabecera “Authorization” con el formato Basic [request_token] y el access token en el cuerpo de la petición como se muestra en la Figura 30.

Figura 32 Servicio de invalidación: Invalidar access token

Si el request token o el access token no son válidos se verá la respuesta de la Figura 31.

Figura 33 Servicio de invalidación: Request o access tokens incorrectos

Una vez que la aplicación se ha autenticado con la API y dispone de un access token puede realizar peticiones a cualquiera de los servicios web pasando como parámetro de autenticación dicho access token. Se debe pasar el access token como parámetro de la cabecera “Authorization” con el formato Bearer [access_token] como se muestra en la Figura 32.

Figura 34 Petición a un servicio de datos abiertos con el access token obtenido

Si el access token no es válido o ha expirado, así como si la aplicación ha alcanzado su límite de peticiones, se verá la respuesta de la Figura 33.

Figura 35 Respuesta del servicio de datos abiertos cuando el access token no es válido o expiró