> ## 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 para detectar fuentes de datos externas, inspeccionar sus esquemas y traer transacciones a Matcher de forma automática.

Discovery automatiza la detección de fuentes de datos y la extracción mediante el motor de extracción integrado de Matcher. En lugar de subir archivos a mano, Discovery se conecta a sistemas externos, identifica los datos disponibles y extrae transacciones directamente hacia Matcher.

## Qué resuelve Discovery

***

Las subidas manuales de archivos crean fricción en cada paso. Los equipos exportan archivos, los transfieren, vigilan las fallas y vuelven a subirlos cuando algo sale mal. Este proceso toma mucho tiempo, es propenso a errores y se rompe cuando el volumen de datos crece.

Discovery reemplaza el pipeline manual. Se conecta a sistemas externos mediante el motor de extracción, detecta las fuentes de datos disponibles de forma automática y trae transacciones a Matcher bajo demanda. Cuando aparece una nueva fuente de datos (una nueva conexión bancaria, un nuevo procesador de pago), Discovery la encuentra sin reconfiguración.

## Cómo funciona Discovery

***

Discovery se ejecuta dentro de Matcher. No hay un servicio de extracción aparte que desplegar. El motor integrado administra las conexiones a bases de datos externas y ejecuta las extracciones de forma local. Discovery expone esas conexiones y coordina el proceso de extracción, y entrega los resultados directamente a Ingestion.

El workflow tiene siete pasos:

1. **Verificar el estado**: confirma que Discovery y su motor integrado están disponibles.
2. **Explorar las conexiones**: ve todas las fuentes de datos a las que el motor integrado tiene acceso.
3. **Inspeccionar una conexión**: revisa el esquema para entender qué campos están disponibles.
4. **Probar una conexión**: valida la conexión antes de comprometerte con una extracción.
5. **Crear una extracción**: pide que Matcher traiga datos de una fuente específica.
6. **Monitorear el progreso**: sigue el estado de la extracción mientras los datos llegan.
7. **Actualizar las conexiones**: vuelve a escanear cuando aparecen nuevas fuentes de datos.

## Workflow de Discovery

***

### Verificar el estado de Discovery

Antes de empezar, verifica que Discovery y el motor de extracción integrado están operativos.

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

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

### Explorar las conexiones

Lista todas las fuentes de datos disponibles mediante el motor de extracción integrado.

```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 de API: [Listar conexiones](/es/reference/products/matcher/list-discovery-connections)
</Tip>

### Obtener una conexión

Recupera una única conexión 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}` devuelve el `ConnectionResponse` completo (nombre, tipo, estado y metadatos) de una conexión. Úsalo cuando ya tienes un `connectionId`, por ejemplo del canal de consulta de una vinculación de fuente. Da los detalles actuales sin una lista de todas las conexiones.

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

### Inspeccionar una conexión

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

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

Usa la inspección del esquema para confirmar que los campos obligatorios (IDs de transacción, montos, fechas, referencias) existen antes de construir los mapeos de campos.

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

### Probar una conexión

Valida que Matcher puede alcanzar una conexión y leer de ella 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 la conectividad y el acceso de lectura. Prueba siempre antes de crear una extracción, sobre todo con conexiones nuevas o modificadas hace poco.

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

### Crear una extracción

Pide que Matcher traiga datos de transacciones desde una conexión específica al 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 devuelve un ID de extracción. Úsalo para monitorear el progreso.

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

### Monitorear el progreso de la extracción

Sigue el estado de una extracción activa consultándolo de forma periódica 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 pasa 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 enlaza con la ingesta.

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

### Actualizar las conexiones disponibles

Cuando registras una nueva fuente de datos en el motor integrado, dispara una actualización para que Discovery la detecte.

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

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

### Listar los tipos de conector

Lista los tipos de conector (datasource) que el registro del motor tiene registrados para este despliegue. Cada entrada lleva una `category` derivada del backend (`database` o `rest`). El registro es en vivo. Solo aparecen los conectores registrados en el arranque. Esta lista excluye los proveedores de agregadores (Pluggy/Belvo). Aprovisiona esos mediante la superficie de conexiones con agregadores de 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 con agregadores (Open Finance)

***

Las conexiones con agregadores de datos de Open Finance (Pluggy o Belvo) permiten que Matcher traiga transacciones desde agregadores bancarios. El material de credenciales (`clientId`/`secret`) se **sella al escribir y nunca se devuelve**. Cada lectura está libre de secretos por construcción.

### Crear una conexión con un 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": "..."
  }'
```

Envía cinco campos obligatorios: `vendor`, `configName`, `baseUrl`, `clientId` y `secret`. El campo `accountRef` es opcional. Omítelo para crear una conexión a la espera del consentimiento del cliente final en el flujo alojado por el proveedor. Después vincula con `PUT` el id de item o de link devuelto.

El campo `vendor` es `pluggy` o `belvo`. El campo `configName` es el nombre con alcance de tenant al que se vincula el endpoint que genera tokens de webhook. Una creación exitosa devuelve **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 con un agregador

Ejecuta una verificación de conectividad en vivo contra la credencial ya sellada de una conexión existente y vinculada, identificada por `configName`. Matcher lee el proveedor de la conexión almacenada. Esta llamada no toma ninguna credencial ni devuelve ninguna.

Las credenciales almacenadas inválidas dan un resultado de prueba esperado: `200` con `"healthy": false`, no un error. Una conexión ausente, una conexión sin vincular o un proveedor existente sin ruta de prueba de conectividad (hoy Belvo) se expone mediante la respuesta de error estándar. No se ejecuta ninguna prueba. Usa el campo `testable` de la respuesta de la lista antes de ofrecer la acción.

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

#### Respuesta

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

## Tokens de webhook de agregadores

***

Los agregadores envían señales de cambio de datos a Matcher mediante webhooks. Genera un token opaco vinculado a una conexión de agregador y después configura la URL devuelta en el dashboard del proveedor.

### Generar un token de webhook

Matcher devuelve el token en crudo y su URL expuesta al proveedor **exactamente una vez**. Matcher almacena solo 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>"
}
```

### Recibir webhooks

El proveedor llama a `POST /v1/discovery/webhooks/{provider}/{webhookToken}` (sin JWT de operador). Dos capas lo autentican: el token opaco de la ruta **más** una verificación de origen por proveedor. Esa verificación es un HMAC-SHA256 válido del cuerpo en crudo en el header `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 devuelve **202 Accepted**. Después Matcher trae los datos señalados de forma asíncrona al pipeline de ingesta. La repetición de un evento ya procesado devuelve **200 OK**.

## Mejores prácticas

***

<AccordionGroup>
  <Accordion title="Prueba siempre las conexiones antes de extraer">
    Recuperarse de una extracción que falla a mitad de ejecución es más difícil que de una prueba fallida. Prueba cada conexión antes de crear una extracción, sobre todo al conectarte a una fuente nueva o después de rotar una credencial.
  </Accordion>

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

  <Accordion title="Monitorea activamente las extracciones de grandes conjuntos de datos">
    Las extracciones grandes toman tiempo. No supongas que terminaron. Consulta el estado de la extracción de forma periódica y confirma el conteo de registros antes de empezar una ejecución de coincidencia. Empezar una ejecución sobre datos incompletos genera excepciones incorrectas.
  </Accordion>

  <Accordion title="Actualiza las conexiones cuando cambian las fuentes">
    Discovery no busca conexiones nuevas de forma automática. Cuando agregas un nuevo procesador de pago, o registras una nueva base de datos en el motor integrado, dispara una actualización. Si no, Discovery no mostrará la fuente nueva.
  </Accordion>

  <Accordion title="Acota las extracciones al período de conciliación">
    Usa los parámetros de rango de fechas para extraer solo los datos relevantes del período de conciliación actual. Extraer datos sin límite 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/products/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/products/matcher/configuration/matcher-field-mapping" horizontal>
  Mapea los campos de los datos extraídos al modelo de transacciones de Matcher.
</Card>

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