Manual de Usuario de la API

El Portal de Contrataciones Abiertas de Honduras es una potente herramienta web que utiliza como fuente los datos en el Estándar de Datos para las Contrataciones Abiertas (EDCA) publicados por la Oficina Normativa de Contratación y Adquisiciones del Estado (ONCAE) y la Secretaría de finanzas (SEFIN) y proporciona a los usuarios finales una interface de programación de aplicaciones API REST (por sus siglas en inglés, application programming interface) que permite un mecanismo útil para la interoperabilidad entre diferentes sistemas de información.

Los servicios web (GET) disponibles para usuarios finales proporcionan datos en formato JSON de procesos de contratación en las fases de Planificación, Licitación, Adjudicación, Contrato e Implementación en forma de Releses y Records lo que permite exploración y reutilización de los datos EDCA.

Este manual tiene como objetivo principal apoyar a los usuarios finales a conocer la forma de consumir datos de la API EDCA por lo que a continuación se describe cada uno de los servicios provistos:

1. Listado de Releases (Lanzamientos):

Proporciona un listado de los releases almacenados en la base de datos dentro de un paquete paginados de 10 en 10, disponible a través de una petición HTTP GET a la url http://contratacionesabiertas.gob.hn/api/v1/release/ que retornará un objeto en formato JSON con las siguientes variables:

  • "releases": Cantidad total de releases existentes en la base de datos.
  • "pages": Cantidad total de páginas que contienen resultados.
  • "page": Número de página que contiene los 10 resultados solicitados.
  • "next": Enlace url a la página que contiene los 10 resultados siguientes, se muestra el valor de null en caso de no existir.
  • "previous": Enlace url a la página que contiene los 10 resultados anteriores, se muestra el valor de null en caso de no existir.
  • "releasePackage": Paquete de releases que contiene los datos de procesos de contratación incluyendo sus metadatos.

Las primeras 5 variables proporcionan datos de paginación y son útiles para navegar y obtener los resultados, la última variable “releasePackage” es la que provee como máximo 10 procesos de contratación incluidos en un paquete de lanzamientos en el formato del estándar EDCA.

Los parámetros permitidos son:

"page": Debe ser un número entero que identifica la página de la que se requiere obtener los resultados, en caso de que el parámetro no sea provisto en la url se devolverán los resultados de la página 1, a continuación, algunos ejemplos:

"publisher": Este parámetro permite obtener los releases filtrados por un publicador en específico y puede tener como valor uno de las siguientes 2 cadenas de texto: “oncae” o “sefin” a continuación, algunos ejemplos:

También se pueden utilizar ambos parámetros en una misma petición HTTP GET, por ejemplo:

  • http://contratacionesabiertas.gob.hn/api/v1/release/?page=2&publisher=oncae

    • 2. Obtener un Release (Lanzamiento):

    Proporciona los datos de un release dentro de su paquete a través de una petición HTTP GET a la url http://contratacionesabiertas.gob.hn/api/v1/releas/{release.id}/ enviando como parámetro el identificador del release (release.id) y retornará un objeto JSON en el formato del estándar EDCA.

    Los parámetros permitidos son:

    "release.id": Debe ser una cadena de texto que identifica un release, a continuación, algunos ejemplos:


    3. Listado de Records (Registros):

    Proporciona un listado de los records almacenados en la base de datos dentro de un paquete paginados de 10 en 10, disponible a través de una petición HTTP GET a la url http://contratacionesabiertas.gob.hn/api/v1/record/ que retornará un objeto en formato JSON con las siguientes variables:

    • "records": Cantidad total de records existentes en la base de datos.
    • "pages": Cantidad total de páginas que contienen resultados.
    • "page": Número de página que contiene los 10 resultados solicitados.
    • "next": Enlace url a la página que contiene los 10 resultados siguientes, se muestra el valor de null en caso de no existir.
    • "previous": Enlace url a la página que contiene los 10 resultados anteriores, se muestra el valor de null en caso de no existir.
    • "recordPackage": Paquete de records que contiene los datos de procesos de contratación incluyendo sus metadatos.

    Las primeras 5 variables proporcionan datos de paginación y son útiles para navegar y obtener los resultados, la última variable “recordPackage” es la que provee como máximo 10 procesos de contratación incluidos en un paquete de lanzamientos en el formato del estándar EDCA.

    Los parámetros permitidos son:

    "page": Debe ser un número entero que identifica la página de la que se requiere obtener los resultados, en caso de que el parámetro no sea enviado en la url se devolverán los resultados de la página 1, a continuación, algunos ejemplos:


    4. Obtener un Record (Registro):

    Proporciona los datos de un record dentro de su paquete a través de una petición HTTP GET a la url http://contratacionesabiertas.gob.hn/api/v1/record/{ocid}/ enviando como parámetro el identificador único del proceso de contratación (OCID) y retornará un objeto JSON en el formato del estándar EDCA.

    "OCID": Debe ser una cadena de texto que identifica de manera única el proceso de contratación, por ejemplo:


    5. Descarga masiva de archivos:

    Proporciona un listado con las urls para descarga de los archivos que contienen procesos de contratación en formatos JSON, CSV y XLSX a través de una petición HTTP GET a la url http://contratacionesabiertas.gob.hn/api/v1/descargas/ que retornará una lista con en formato JSON con objetos que contienen siguientes variables:

    • "urls"."csv": Enlace url para descargar el archivo de releases en formato .csv
    • "urls"."json": Enlace url para descargar el archivo de releases en formato .json
    • "urls"."xlsx": Enlace url para descargar el archivo de releases en formato .xlsx
    • "urls"."md5": Archivo .md5 del archivo. json de releases, útil para identificar si el paquete de raleases ha sufrido algún cambio.
    • "year": Año de publicación del paquete de releases, extraído de “release.date”.
    • "month": Mes de publicación del paquete de releases, extraído de “release.date”.
    • "sistema": Nombre del sistema de información del cual se obtienen los datos, extraído de “release.sources.id”.
    • "publicador": Nombre del publicador de los datos, extraído de “releasePackage.publisher.name”.
    Los parámetros permitidos son:

    Este servicio no tiene parámetros.


    Ejemplos de llamadas a Métodos de la API

    Utilizar la API EDCA para usuarios finales es muy sencillo, únicamente basta abrir el navegador de internet de tu preferencia e ingresar la url del método que queremos utilizar esto permite familiarizarse con la respuesta retornada a través de una interface gráfica. También es posible realizar peticiones utilizando códigos en diferentes lenguajes de programación o utilizar una herramienta de testeo, por ejemplo: Postman.

    A continuación, se muestran algunos ejemplos de llamadas a la API utilizando la herramienta Postman:

    Ejemplo 1: Realizar una llamada a la API para obtener un listado de records:

    Ejemplo 1

    Imagen 1: Llamada a la API utilizando el método listado de records utilizando Postman.
    Explicación de los resultados en la imagen 1

    1. El método que se utiliza para realizar la petición es: GET
    2. El nombre de la url es: http://contratacionesabiertas.gob.hn/api/v1/record/?page=2
    3. La respuesta de la API son en formato JSON.
    4. Se envía el parámetro page=2 para obtener los resultados de la segunda página.
    5. Otras variables a tomar en cuenta es que se retorna un código 200 cuando la API logró procesar la solicitud de manera correcta, el tiempo estimado de respuesta fue de 2.05 segundos y el tamaño de los datos retornados es de 176.11 KB.

    Ejemplo 2: Realizar una llamada a la API para obtener un record

    Ejemplo 2

    Imagen 2: Llamada a la API con el método obtener record utilizando Postman.
    Explicación de los resultados en la imagen 2:

    1. El método que se utiliza para la petición es: GET
    2. El nombre de la url es: http://contratacionesabiertas.gob.hn/api/v1/record/ocds-lcuori-P2013-70-1-949/
    3. La respuesta de la API son en formato JSON.
    4. No se envía un parámetro, ya que el identificador OCID este contenido en la url.
    5. Otras variables a tomar en cuenta es que se retorna un código 200 cuando la API logró procesar la solicitud de manera correcta, el tiempo estimado de respuesta fue de 779 mili segundos y el tamaño de los datos retornados es de 23.6 KB.