> ## Documentation Index > Fetch the complete documentation index at: https://help.impactu.colav.co/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```text theme={null} 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. > [tab] 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`). > > ```json theme={null} > { > "data": { "...": "..." }, > "meta": { > "count": 1, > "page": 1, > "size": 1, > "db_response_time_ms": 25, > "cursor": { "next": null, "previous": null } > } > } > ``` > [tab] Un listado > > Los endpoints de búsqueda devuelven una lista en `data` y los datos de paginación en `meta`. > > ```json theme={null} > { > "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. **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` **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` (default: 10) Resultados por página, de 1 a 250. **page** `integer` (default: 1) Número de página. **sort** `string` (default: 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` (default: 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. > [!NOTE] > > 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 > [accordion] Fechas > > Las fechas se expresan en segundos Unix. En las fechas de fin, un valor `-1` indica que la relación sigue vigente. > [accordion] 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` | > [accordion] 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](https://help.impactu.colav.co/api-reference/auth/login.md) 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](https://help.impactu.colav.co/api-reference/submit/project.md), con un máximo de 10 MB. | | `415` | El tipo de archivo no está permitido. Solo en [Enviar archivo SCIENTI](https://help.impactu.colav.co/api-reference/submit/scienti.md). | | `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. | ```json theme={null} { "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](https://help.impactu.colav.co/api-reference/submit/project.md) 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 > [card] [Search](https://help.impactu.colav.co/api-reference/search/persons.md) > > Búsqueda de personas, productos, afiliaciones, fuentes, patentes, proyectos > y geografía, con sus endpoints de filtros disponibles. > [card] [Affiliation](https://help.impactu.colav.co/api-reference/affiliation/get-affiliation.md) > > 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. > [card] [Person](https://help.impactu.colav.co/api-reference/person/get-person.md) > > El perfil de un autor y sus productos, con filtros, exportación y 16 > indicadores, patentes, proyectos y noticias. > [card] [Source](https://help.impactu.colav.co/api-reference/source/get-source.md) > > Una fuente (revista, conferencia u otra publicación) y sus productos, con > filtros, exportación y 1 indicador. > [card] [Work](https://help.impactu.colav.co/api-reference/work/get-work.md) > > Un producto bibliográfico por su identificador o por DOI, y la lista > completa de sus autores. > [card] [Patent](https://help.impactu.colav.co/api-reference/patent/get-patent.md) > > Una patente y sus autores. > [card] [Project](https://help.impactu.colav.co/api-reference/project/get-project.md) > > Un proyecto de investigación y sus autores. > [card] [Geo](https://help.impactu.colav.co/api-reference/geo/get-geo.md) > > Un departamento o una ciudad, con sus afiliaciones y sus productos. > [card] [APC](https://help.impactu.colav.co/api-reference/apc/search.md) > > Exportación a CSV de los datos de APC de una búsqueda, de un autor o de una > afiliación. > [card] [Completer](https://help.impactu.colav.co/api-reference/completer/get-person.md) > > Sugerencias de autocompletado de autores, afiliaciones y fuentes. > [card] [Autenticación](https://help.impactu.colav.co/api-reference/auth/login.md) > > Inicio y cierre de sesión, y estado de la sesión. > [card] [Usuarios](https://help.impactu.colav.co/api-reference/users/list-users.md) > > Administración de usuarios, con rol admin, y gestión del API Key propio. > [card] [Submit](https://help.impactu.colav.co/api-reference/submit/staff.md) > > Carga y validación de los archivos de las instituciones: Staff, CIARP, > SCIENTI y proyectos. > [card] [Sistema](https://help.impactu.colav.co/api-reference/system/get-info.md) > > Conteos generales, métricas de calidad de los datos y ping. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.