Introducción

Conoce la estructura general de la API de ImpactU: URL base, formato de las respuestas, paginación, filtros y errores.

La API de ImpactU es una API REST que devuelve información científica y académica en formato JSON: personas, productos, afiliaciones, fuentes, patentes, proyectos y entidades geográficas. La consulta es pública y de solo lectura. Con sesión, la API también permite administrar usuarios y cargar los archivos de las instituciones.

​

URL base

https://api.dev.impactu.colav.co

Todas las rutas de esta documentación se agregan a esa URL. Por ejemplo, GET /search/works se consulta en https://api.dev.impactu.colav.co/search/works.

​

Formato de las respuestas

Las respuestas son JSON y tienen dos formas, según el tipo de endpoint.

Un recurso

Los endpoints que devuelven una sola entidad envuelven el resultado en data y agregan meta, con la misma forma que en los listados (count vale 1).

{
  "data": { "...": "..." },
  "meta": {
    "count": 1,
    "page": 1,
    "size": 1,
    "db_response_time_ms": 25,
    "cursor": { "next": null, "previous": null }
  }
}

Un listado

Los endpoints de búsqueda devuelven una lista en data y los datos de paginación en meta.

{
  "data": [ { "...": "..." } ],
  "meta": {
    "count": 1542618,
    "page": 1,
    "size": 10,
    "db_response_time_ms": 348,
    "cursor": { "next": "https://...", "previous": null }
  }
}

Algunos endpoints devuelven el objeto sin envolver en data: los filtros disponibles, las afiliaciones relacionadas (de una afiliación o de una entidad geográfica), /info y /info/quality. Las exportaciones devuelven un archivo CSV o Excel.

​

Campo meta de los listados

meta · object

Metadatos de la respuesta.

Mostrar propiedades

count · integer

Total de resultados que cumplen la consulta.

page · integer

Página actual.

size · integer

Cantidad de resultados devueltos en esta página.

db_response_time_ms · integer

Tiempo de respuesta de la base de datos en milisegundos.

cursor · object

Mostrar propiedades

next · string | null

URL de la página siguiente.

previous · string | null

URL de la página anterior.

​

Convenciones de los listados

Los endpoints de búsqueda comparten estos parámetros de consulta.

keywords · string

Texto de búsqueda. Se usa en las búsquedas desde caja de texto.

max · integer · predeterminado: "10"

Resultados por página, de 1 a 250.

page · integer · predeterminado: "1"

Número de página.

sort · string · predeterminado: "citations_desc"

Ordenamiento con el formato campo_direccion, donde la dirección es asc o desc. Los campos válidos dependen de la entidad y se describen en cada endpoint.

view · string · predeterminado: "full"

Nivel de detalle de la respuesta: full (todos los campos) o summary (solo los campos principales). Lo aceptan los listados y los detalles de las entidades, salvo la búsqueda y el detalle de entidades geográficas y las noticias.

Además, cada listado tiene sus propios filtros. Todos aceptan varios valores separados por coma (por ejemplo, years=2020,2026), y las opciones válidas se consultan en el endpoint de filtros disponibles de cada entidad.

Si no envías max, page ni sort, se aplican max=10, page=1 y sort=citations_desc. Si envías max y page sin sort, se aplica sort=citations_desc.

​

Datos y formatos

Fechas

Las fechas se expresan en segundos Unix. En las fechas de fin, un valor -1 indica que la relación sigue vigente.

Identificadores

Cada entidad tiene su propio formato de identificador:

Entidad	Ejemplo
Institución	03bp5hc83 (identificador ROR)
Facultad	03bp5hc83_20
Departamento	03bp5hc83_2_21620003_3154
Grupo de investigación	COL0001262
Persona	0000000001
Producto, fuente	6ab555045418a51e325f5303

Información por fuente

Muchos campos (nombres, citas, tipos, rankings) devuelven un elemento por cada fuente de información, con los campos source y provenance.

​

Autenticación y límites

Los endpoints de consulta son públicos: no requieren autenticación y por ahora no tienen límite de solicitudes.

Requieren sesión la administración de usuarios (/admin/users), la gestión del API Key (/users/{email}/apikey), el estado de sesión (/me) y todas las cargas de archivos (/submit/staff, /submit/ciarp, /submit/scienti y /submit/project). La sesión es el JWT que Iniciar sesión guarda en la cookie HttpOnly access_token_cookie.

• Token CSRF. Las solicitudes con sesión que no son GET (POST, PUT, PATCH y DELETE) deben enviar el encabezado X-CSRF-TOKEN con el valor de la cookie csrf_access_token, que también crea el inicio de sesión. Sin ese encabezado responden 401.
• Cuentas desactivadas. Cada solicitud con sesión comprueba que la cuenta siga activa. Si un administrador la desactiva, o la cuenta ya no existe, el token deja de servir de inmediato y la solicitud responde 403, aunque el token no haya vencido.

​

Errores

Cuando una solicitud falla, la API responde con el código HTTP del caso y un mensaje en error:

Código	Cuándo
400	Un parámetro es inválido: por ejemplo max=0, un sort mal formado, un campo de fields que no está permitido o un cuerpo JSON que no es un objeto.
401	Falta la sesión, el token no es válido o falta el encabezado X-CSRF-TOKEN.
403	La sesión no tiene permiso para la operación o la cuenta está desactivada.
404	La entidad no existe.
409	La operación choca con un registro existente, por ejemplo al crear un usuario.
413	El archivo supera el tamaño máximo. Solo en Validar archivo de proyectos, con un máximo de 10 MB.
415	El tipo de archivo no está permitido. Solo en Enviar archivo SCIENTI.
422	Al Excel de Staff o CIARP le faltan columnas o tiene columnas sin nombre.
500	Error inesperado del servidor.
502	No se pudo enviar el correo con las credenciales al crear un usuario, cambiar su correo o restablecer su contraseña. No se guarda ningún cambio, así que se puede reintentar.

{ "error": "The person with id 9999999999 does not exist." }

Los endpoints de autenticación, usuarios y carga de archivos responden con { "success": false, "msg": "..." } en lugar de error. Validar archivo de proyectos usa error para los problemas del archivo (400 y 413) y msg para los de sesión (401 y 403).

Los listados de una entidad que no existe (por ejemplo, los productos de un autor inexistente) responden 200 con la lista vacía.

​

Endpoints disponibles

Search

Búsqueda de personas, productos, afiliaciones, fuentes, patentes, proyectos y geografía, con sus endpoints de filtros disponibles.

Affiliation

Una afiliación (institución, facultad, departamento o grupo), sus afiliaciones relacionadas y sus productos, con filtros, exportación y 30 indicadores, patentes, proyectos y noticias.

Person

El perfil de un autor y sus productos, con filtros, exportación y 16 indicadores, patentes, proyectos y noticias.

Source

Una fuente (revista, conferencia u otra publicación) y sus productos, con filtros, exportación y 1 indicador.

Work

Un producto bibliográfico por su identificador o por DOI, y la lista completa de sus autores.

Patent

Una patente y sus autores.

Project

Un proyecto de investigación y sus autores.

Geo

Un departamento o una ciudad, con sus afiliaciones y sus productos.

APC

Exportación a CSV de los datos de APC de una búsqueda, de un autor o de una afiliación.

Completer

Sugerencias de autocompletado de autores, afiliaciones y fuentes.

Autenticación

Inicio y cierre de sesión, y estado de la sesión.

Usuarios

Administración de usuarios, con rol admin, y gestión del API Key propio.

Submit

Carga y validación de los archivos de las instituciones: Staff, CIARP, SCIENTI y proyectos.

Sistema

Conteos generales, métricas de calidad de los datos y ping.