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.

curl -X GET "https://api.matcher.example.com/v1/discovery/status" \
  -H "Authorization: Bearer $TOKEN"

Referencia API: Obtener estado de Discovery

​

Explorar conexiones

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

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.

Referencia API: Listar conexiones

​

Obtener una conexión

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

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.

Referencia API: Obtener conexión de discovery

​

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.

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.

Referencia API: Obtener esquema de conexión

​

Probar una conexión

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

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.

Referencia API: Probar conexión

​

Crear una extracción

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

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.

Referencia API: Crear extracción

​

Monitorear progreso de extracción

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

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.

Referencia API: Obtener extracción

​

Actualizar conexiones disponibles

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

curl -X POST "https://api.matcher.example.com/v1/discovery/refresh" \
  -H "Authorization: Bearer $TOKEN"

Referencia API: Actualizar conexiones

​

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.

curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"

​

Respuesta

{
  "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

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

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

​

Listar, obtener, actualizar y eliminar

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

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

{
  "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.

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

{
  "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

---

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.

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.

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.

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.

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.

​

Próximos pasos

---

Fuentes externas

Configura las fuentes de datos externas a las que Discovery se conecta.

Mapeo de campos

Mapea campos de los datos extraídos al modelo de transacciones de Matcher.

Referencia API de Discovery

Referencia completa de la API para los endpoints de Discovery.