> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# API REST de Fetcher
> Ubícate en la API del Manager de Fetcher: autenticación bearer, alcance de producto, paginación, filtrado y la forma de error RFC 9457 que comparten las 12 operaciones.
El **Manager** sirve la API HTTP de Fetcher. Lleva 12 operaciones en dos áreas:
* **Jobs de extracción** bajo `/v1/fetcher` — crear un job, leer un job.
* **Conexiones** bajo `/v1/management/connections` — el ciclo de vida de la conexión, las lecturas de esquema, las pruebas de conexión y las dos operaciones de asignación de producto.
Las 12 operaciones se renderizan bajo el anclaje **Fetcher** en la [Referencia de API](/es/reference/introduction). Esta página cubre lo que esas operaciones comparten. No repite sus formas de solicitud y respuesta.
Los documentos OpenAPI de este portal son fuentes de renderizado para las páginas de referencia. No son contratos de cliente, ni una base para generar SDKs.
## Autenticación
***
Fetcher acepta un token bearer JWT:
```http theme={null}
Authorization: Bearer
```
La autenticación es una decisión de despliegue. `PLUGIN_AUTH_ENABLED` activa el middleware de autenticación, y `PLUGIN_AUTH_ADDRESS` lo apunta al servicio de identidad. El Manager se niega a arrancar cuando activas la autenticación y dejas la dirección vacía. El modo multi-tenant también requiere autenticación efectiva — el router se niega a construir un middleware de tenant sin ella. Consulta [Configuración](/es/fetcher/fetcher-configuration).
Cada una de las 12 operaciones declara `401` y `403`. Fetcher autoriza cada solicitud contra la aplicación `fetcher`, un recurso (`connections` o `fetcher`) y una acción que corresponde al método HTTP.
Cinco rutas quedan fuera de la autenticación para que las sondas sigan funcionando: `/health`, `/readyz`, `/readyz/tenant/{id}`, `/metrics` y `/version`.
## Alcance de producto
***
Las operaciones de conexión llevan un header `X-Product-Name`. Nombra el producto dueño de la conexión.
* **Crear una conexión lo exige.** Fetcher rechaza un valor ausente, vacío o compuesto solo de espacios.
* **Listar conexiones lo trata como opcional.** Con el header, ves las conexiones de un solo producto. Sin él, ves todas las conexiones dentro del alcance.
* Fetcher pasa el valor a minúsculas. Acepta letras, dígitos, guiones bajos y guiones, hasta 100 caracteres.
Los jobs de extracción no usan este header. Un job nombra a su producto dueño en `metadata.source`, que el payload de creación exige.
## Jobs asíncronos
***
`POST /v1/fetcher` responde `202 Accepted` y devuelve un identificador de job con estado `pending`. El Worker ejecuta la extracción después de la respuesta.
Fetcher deduplica las solicitudes de job por un hash de solicitud dentro de una **ventana de 5 minutos**. Una solicitud duplicada dentro de esa ventana responde `200 OK` y devuelve el job existente en lugar de encolar un segundo. Un job que ya falló no impide un reintento — puedes reenviarlo.
Para seguir un job, consulta `GET /v1/fetcher/{id}` de forma periódica, o suscríbete a los eventos terminales que describe [Eventos de job](/es/fetcher/fetcher-job-events).
## Paginación
***
Ambas operaciones de listado — conexiones y conexiones sin asignar — usan paginación por offset con los mismos parámetros de consulta.
| Parámetro | Valor por defecto | Reglas |
| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `page` | `1` | Número de página. Debe ser 1 o mayor. |
| `limit` | `10` | Elementos por página. Debe ser 1 o mayor, y como máximo `MAX_PAGINATION_LIMIT` (100 tal como se distribuye). |
| `sortOrder` | `desc` | `asc` o `desc`. Fetcher siempre ordena por fecha de creación. |
| `startDate` | — | Límite inferior inclusivo sobre la fecha de creación, como `YYYY-MM-DD`. |
| `endDate` | — | Límite superior inclusivo sobre la fecha de creación, como `YYYY-MM-DD`. |
Una respuesta de página lleva `items`, `page`, `limit` y `total`.
```json theme={null}
{
"items": [],
"page": 1,
"limit": 10,
"total": 42
}
```
Una solicitud de listado siempre aplica una ventana de fecha de creación. Si no envías `startDate` ni `endDate`, Fetcher aplica el último mes hasta mañana. Las conexiones más antiguas quedan fuera de esa ventana. Define ambas fechas cuando quieras una vista más amplia.
`MAX_PAGINATION_MONTH_DATE_RANGE` limita el ancho de esa ventana a un mes tal como se distribuye. Si pides un rango más amplio, Fetcher adelanta `startDate` para ajustarse al límite. No responde con un error.
Los datasources internos — los que un operador configura con las variables de entorno `DATASOURCE_{NAME}_*` — aparecen solo en la página 1, delante de las conexiones almacenadas, y cuentan para `total`.
## Filtrado
***
El listado de conexiones acepta dos filtros más allá de la ventana de fechas.
* **`type`** — uno de `POSTGRESQL`, `MYSQL`, `ORACLE`, `SQL_SERVER` o `MONGODB`. Fetcher pasa el valor a mayúsculas.
* **`metadata.=`** — una coincidencia exacta sobre una entrada de metadata que guardaste con la conexión. Por ejemplo, `metadata.region=br`.
El listado de conexiones sin asignar se acota solo por la ventana de fechas. Responde una sola pregunta — qué conexiones siguen sin producto — así que no toma filtro de tipo ni de metadata.
Fetcher ignora un parámetro de consulta desconocido en lugar de fallar la solicitud. Tres casos aún fallan con `FET-0405`:
* Una clave que empieza con `$`, lo que bloquea la inyección de operadores de consulta.
* Una clave que empieza con `_`, lo que bloquea los campos internos.
* Una clave de más de 64 caracteres, o un valor de más de 256 caracteres.
## Errores
***
Cada error responde `application/problem+json` y sigue [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).
```json theme={null}
{
"type": "about:blank",
"title": "Invalid payload",
"status": 400,
"detail": "empty request body",
"code": "FET-0001",
"errors": [
{ "location": "body.configName", "message": "is required" }
]
}
```
| Campo | Qué lleva |
| ---------- | ----------------------------------------------------------------------------------------------------------- |
| `type` | Referencia URI a la documentación del problema. Por defecto `about:blank`. |
| `title` | Resumen corto del tipo de problema. Estable entre ocurrencias. |
| `status` | El código de estado HTTP. |
| `detail` | Explicación específica de esta ocurrencia. |
| `instance` | Referencia URI para esta ocurrencia específica. |
| `code` | Código de error de dominio estable, con la forma `FET-NNNN`. |
| `errors` | Detalles opcionales por campo, cada uno con un `location`, un `message` y el `value` que causó el problema. |
Haz coincidir sobre `code`, no sobre `title` ni `detail`. Los códigos se agrupan por rango:
| Rango | Significado | Ejemplos |
| ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `FET-000x` | Resultados generales | `FET-0001` solicitud inválida, `FET-0002` error interno, `FET-0004` conflicto, `FET-0005` no encontrado |
| `FET-04xx` | Problemas de solicitud | `FET-0403` header inválido, `FET-0405` parámetro de consulta inválido, `FET-0406` límite de paginación excedido, `FET-0414` host prohibido |
| `FET-10xx` | Reglas de negocio | `FET-1002` conflicto de entidad, `FET-1021` job en curso, `FET-1040` conexión caída |
| `FET-106x` | Validación de esquema | `FET-1060` validación fallida, `FET-1062` objeto no encontrado |
Fetcher redacta los fallos a nivel de driver en su frontera. Descarta el error crudo de la base de datos, así que una cadena de conexión, una credencial o un detalle interno del driver nunca llega a un llamador.
## Leer la especificación desde un Manager en ejecución
***
`SWAGGER_ENABLED=true` monta una referencia Scalar en `/swagger/docs` y el documento OpenAPI 3.1 en `/swagger/openapi.json` y `/swagger/openapi.yaml`. Mantenlo apagado en producción.
## Próximos pasos
***
Las 12 operaciones, con las formas completas de solicitud y respuesta.
Reacciona a `job.completed` y `job.failed` en lugar de consultar de forma periódica.
Conexiones, descubrimiento de esquemas, jobs de extracción, filtros y resultados.
Las variables de entorno detrás de la autenticación, los límites de paginación y la superficie de API.