> ## 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.

# Discovery

> Usa Discovery y Fetcher para detectar fuentes de datos externas, inspeccionar sus esquemas e ingresar transacciones a Matcher de forma automática.

Discovery automatiza la detección y extracción de fuentes de datos a través de Fetcher. En lugar de cargar archivos manualmente, Discovery se conecta a sistemas externos, identifica los datos disponibles y extrae transacciones directamente en Matcher.

## Qué resuelve Discovery

***

Las cargas manuales de archivos generan fricción en cada paso. Los equipos exportan archivos, los transfieren, monitorean fallos y vuelven a cargar cuando algo sale mal. Este proceso es lento, propenso a errores y se quiebra cuando el volumen de datos crece.

Discovery reemplaza el pipeline manual. Se conecta a sistemas externos a través de Fetcher, detecta fuentes de datos disponibles automáticamente y trae transacciones a Matcher bajo demanda. Cuando aparece una nueva fuente de datos — una nueva conexión bancaria, un nuevo procesador de pagos — Discovery la encuentra sin reconfiguración.

## Cómo funciona Discovery

***

Discovery opera sobre el motor de extracción de Fetcher, que Matcher aloja en el mismo proceso; Fetcher no es un servicio remoto. El motor embebido gestiona las conexiones a bases de datos externas y ejecuta las extracciones localmente. Discovery expone esas conexiones, coordina el proceso de extracción y entrega los resultados directamente a Ingestion.

El flujo de trabajo tiene siete pasos:

1. **Verificar estado** — Confirmar que Discovery y su motor embebido están disponibles.
2. **Explorar conexiones** — Ver todas las fuentes de datos a las que el motor embebido tiene acceso.
3. **Inspeccionar una conexión** — Revisar el esquema para entender qué campos están disponibles.
4. **Probar una conexión** — Validar la conexión antes de comprometerte con una extracción.
5. **Crear una extracción** — Solicitar que Matcher obtenga datos de una fuente específica.
6. **Monitorear progreso** — Rastrear el estado de la extracción mientras los datos fluyen.
7. **Actualizar conexiones** — Reescanear cuando se agregan nuevas fuentes de datos.

## Flujo de trabajo de Discovery

***

### Verificar estado de Discovery

Verifica que Discovery y el motor embebido de Fetcher están operativos antes de comenzar.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/status" \
  -H "Authorization: Bearer $TOKEN"
```

<Tip>Referencia API: [Obtener estado de Discovery](/es/reference/matcher/discovery-status)</Tip>

### Explorar conexiones

Lista todas las fuentes de datos disponibles a través del motor embebido de Fetcher.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connections" \
  -H "Authorization: Bearer $TOKEN"
```

La respuesta lista cada conexión con su nombre, tipo (base de datos, API, almacén de archivos) y estado actual.

<Tip>Referencia API: [Listar conexiones](/es/reference/matcher/list-discovery-connections)</Tip>

### Obtener una conexión

Recupera una única conexión de Fetcher descubierta por su identificador interno:

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connections/{connectionId}" \
  -H "Authorization: Bearer $TOKEN"
```

`GET /v1/discovery/connections/{connectionId}` retorna el `ConnectionResponse` completo (nombre, tipo, estado y metadatos) de una conexión — útil cuando ya tienes un `connectionId` (por ejemplo, del rail de consulta de un binding de fuente) y quieres sus detalles actuales sin listar cada conexión.

<Tip>Referencia API: [Obtener conexión de discovery](/es/reference/matcher/retrieve-discovery-connection)</Tip>

### Inspeccionar una conexión

Revisa el esquema de una conexión específica para entender qué campos de datos están disponibles antes de extraer.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/schema" \
  -H "Authorization: Bearer $TOKEN"
```

Usa la inspección de esquema para confirmar que los campos requeridos — IDs de transacción, montos, fechas, referencias — existen antes de configurar los mapeos de campos.

<Tip>Referencia API: [Obtener esquema de conexión](/es/reference/matcher/get-connection-schema)</Tip>

### Probar una conexión

Valida que Matcher puede alcanzar y leer de una conexión antes de crear una extracción.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/test" \
  -H "Authorization: Bearer $TOKEN"
```

Una prueba exitosa confirma conectividad y acceso de lectura. Prueba siempre antes de crear una extracción — especialmente para conexiones nuevas o modificadas recientemente.

<Tip>Referencia API: [Probar conexión](/es/reference/matcher/test-discovery-connection)</Tip>

### Crear una extracción

Solicita que Matcher obtenga datos de transacciones de una conexión específica en el contexto actual.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/extractions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": {
      "transactions": {}
    },
    "startDate": "2026-06-01",
    "endDate": "2026-06-30"
  }'
```

La respuesta retorna un ID de extracción. Úsalo para monitorear el progreso.

<Tip>Referencia API: [Crear extracción](/es/reference/matcher/create-extraction)</Tip>

### Monitorear progreso de extracción

Rastrea el estado de una extracción activa consultando su estado con `GET`.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/extractions/{extractionId}" \
  -H "Authorization: Bearer $TOKEN"
```

El estado de la extracción transiciona de `PENDING` → `SUBMITTED` → `EXTRACTING` → `COMPLETE` (o `FAILED`/`CANCELLED`). La respuesta lleva el `status` de la extracción, un `errorMessage` cuando falló y el `ingestionJobId` vinculado una vez que la extracción pasa a la ingestión.

<Tip>Referencia API: [Obtener extracción](/es/reference/matcher/retrieve-extraction)</Tip>

### Actualizar conexiones disponibles

Cuando se registran nuevas fuentes de datos en el motor embebido, activa una actualización para que Discovery las detecte.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/refresh" \
  -H "Authorization: Bearer $TOKEN"
```

<Tip>Referencia API: [Actualizar conexiones](/es/reference/matcher/refresh-discovery)</Tip>

### Listar tipos de conectores

Lista los tipos de conector (fuente de datos) que el registro del motor ha registrado para este despliegue. Cada entrada lleva una `category` derivada del backend (`database` o `rest`). El registro es en vivo—solo aparecen los conectores registrados al arranque. Los proveedores agregadores (Pluggy/Belvo) se excluyen; provisiónalos a través de la superficie de aggregator-connections descrita más abajo.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"
```

#### Respuesta

```json theme={null}
{
  "types": [
    { "type": "POSTGRESQL", "category": "database" },
    { "type": "MYSQL", "category": "database" }
  ]
}
```

## Conexiones de agregador (Open Finance)

***

Las conexiones de agregador de datos de Open Finance (Pluggy o Belvo) permiten que Matcher obtenga transacciones desde agregadores bancarios. El material de credenciales (`clientId`/`secret`) se **sella al escribir y nunca se retorna**—toda lectura es libre de secretos por construcción.

### Crear una conexión de agregador

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "clientId": "...",
    "secret": "..."
  }'
```

Los seis campos son requeridos. `vendor` es uno de `pluggy` o `belvo`. `configName` es el nombre con alcance de tenant al que se vincula el endpoint de emisión de tokens del webhook. Retorna **201** con una conexión libre de secretos.

#### Respuesta

```json theme={null}
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
```

### Listar, obtener, actualizar y eliminar

```bash theme={null}
# List (cursor-paginated, secret-free)
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN"

# Get one by id
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Update (PUT). vendor is immutable. Supply clientId+secret together to rotate
# the sealed credential, or omit both to keep the stored secret intact.
curl -X PUT "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'

# Delete (soft-delete; frees the config name for reuse). Returns 204.
curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

### Probar una conexión de agregador

Ejecuta una verificación de conectividad en vivo contra la credencial ya sellada de una conexión existente, direccionada por `(vendor, configName)`. No se suministra ni se retorna ninguna credencial—el resultado es un estado de salud booleano libre de secretos.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "configName": "pluggy-main"
  }'
```

#### Respuesta

```json theme={null}
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "healthy": true
}
```

## Tokens de webhook de agregador

***

Los agregadores envían señales de cambio de datos a Matcher mediante webhooks. Emite un token opaco vinculado a una conexión de agregador y luego configura la URL retornada en el panel del proveedor.

### Emitir un token de webhook

El token en bruto y su URL orientada al proveedor se retornan **exactamente una vez**—solo se almacena el hash SHA-256 del token.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/webhooks/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "connection_config_name": "pluggy-main"
  }'
```

#### Respuesta

```json theme={null}
{
  "vendor": "pluggy",
  "token": "<raw-token-shown-once>",
  "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>"
}
```

### Recepción de webhooks

El proveedor llama a `POST /v1/discovery/webhooks/{provider}/{webhookToken}` (sin JWT de operador). Se autentica mediante el token opaco de la ruta **más** una verificación de origen por proveedor: un HMAC-SHA256 válido del cuerpo en bruto en el encabezado `X-Webhook-Signature`, **o** la pertenencia a la lista de IP de origen permitidas del proveedor. Ambas capas fallan de forma cerrada. Una primera entrega válida retorna **202 Accepted** y los datos señalados se obtienen de forma asíncrona hacia el pipeline de ingesta; una repetición de un evento ya procesado retorna **200 OK**.

## Mejores prácticas

***

<AccordionGroup>
  <Accordion title="Prueba siempre las conexiones antes de extraer">
    Una extracción fallida a mitad de ejecución es más difícil de recuperar que una prueba fallida. Prueba cada conexión antes de crear una extracción — especialmente al conectar a una fuente nueva o después de una rotación de credenciales.
  </Accordion>

  <Accordion title="Inspecciona esquemas antes de mapear campos">
    Los nombres de campos varían entre sistemas. Un banco puede llamar a la fecha de transacción `value_date` mientras tu ledger usa `posting_date`. Verifica el esquema antes de configurar mapeos de campos para evitar discrepancias silenciosas.
  </Accordion>

  <Accordion title="Monitorea extracciones activamente para conjuntos de datos grandes">
    Las extracciones grandes toman tiempo. No asumas que se completaron — consulta el estado de la extracción y confirma el conteo de registros antes de iniciar una ejecución de conciliación. Iniciar una ejecución con datos incompletos genera excepciones incorrectas.
  </Accordion>

  <Accordion title="Actualiza conexiones cuando las fuentes cambien">
    Discovery no escanea nuevas conexiones automáticamente. Cuando se agrega un nuevo procesador de pagos o se registra una nueva base de datos en el motor embebido, activa una actualización. De lo contrario, Discovery no mostrará la nueva fuente.
  </Accordion>

  <Accordion title="Delimita las extracciones al período de conciliación">
    Usa parámetros de rango de fechas para extraer solo los datos relevantes para el período de conciliación actual. Extraer datos sin acotar aumenta el tiempo de procesamiento y puede traer registros que pertenecen a contextos ya cerrados.
  </Accordion>
</AccordionGroup>

## Próximos pasos

***

<Card title="Fuentes externas" icon="building-columns" href="/es/matcher/integrations/matcher-external-sources" horizontal>
  Configura las fuentes de datos externas a las que Discovery se conecta.
</Card>

<Card title="Mapeo de campos" icon="arrows-left-right" href="/es/matcher/configuration/matcher-field-mapping" horizontal>
  Mapea campos de los datos extraídos al modelo de transacciones de Matcher.
</Card>

<Card title="Referencia API de Discovery" icon="code" href="/es/reference/matcher/discovery-status" horizontal>
  Referencia completa de la API para los endpoints de Discovery.
</Card>