Discovery

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:

Verificar el estado: confirma que Discovery y su motor integrado están disponibles.
Explorar las conexiones: ve todas las fuentes de datos a las que el motor integrado tiene acceso.
Inspeccionar una conexión: revisa el esquema para entender qué campos están disponibles.
Probar una conexión: valida la conexión antes de comprometerte con una extracción.
Crear una extracción: pide que Matcher traiga datos de una fuente específica.
Monitorear el progreso: sigue el estado de la extracción mientras los datos llegan.
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.

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

Referencia de API: Obtener el estado de Discovery

Explorar las conexiones

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

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 de API: Listar conexiones

Obtener una conexión

Recupera una única conexión 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} 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.

Referencia de API: Obtener una conexión de Discovery

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.

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.

Referencia de API: Obtener el esquema de la conexión

Probar una conexión

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

Referencia de API: Probar la conexión

Crear una extracción

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

Referencia de API: Crear una extracción

Monitorear el progreso de la extracción

Sigue el estado de una extracción activa consultándolo de forma periódica con GET.

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.

Referencia de API: Obtener la extracción

Actualizar las conexiones disponibles

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

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

Referencia de API: Actualizar las conexiones

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.

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

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

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

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

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

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

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

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.

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.

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.

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.

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.

Próximos pasos

Fuentes externas

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

Mapeo de campos

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

Referencia de API de Discovery

Referencia de API completa de los endpoints de Discovery.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Qué resuelve Discovery

Cómo funciona Discovery

Workflow de Discovery

Verificar el estado de Discovery

Explorar las conexiones

Obtener una conexión

Inspeccionar una conexión

Probar una conexión

Crear una extracción

Monitorear el progreso de la extracción

Actualizar las conexiones disponibles

Listar los tipos de conector

Respuesta

Conexiones con agregadores (Open Finance)

Crear una conexión con un agregador

Respuesta

Listar, obtener, actualizar y eliminar

Probar una conexión con un agregador

Respuesta

Tokens de webhook de agregadores

Generar un token de webhook

Respuesta

Recibir webhooks

Mejores prácticas

Próximos pasos

Fuentes externas

Mapeo de campos

Referencia de API de Discovery

​Qué resuelve Discovery

​Cómo funciona Discovery

​Workflow de Discovery

​Verificar el estado de Discovery

​Explorar las conexiones

​Obtener una conexión

​Inspeccionar una conexión

​Probar una conexión

​Crear una extracción

​Monitorear el progreso de la extracción

​Actualizar las conexiones disponibles

​Listar los tipos de conector

​Respuesta

​Conexiones con agregadores (Open Finance)

​Crear una conexión con un agregador

​Respuesta

​Listar, obtener, actualizar y eliminar

​Probar una conexión con un agregador

​Respuesta

​Tokens de webhook de agregadores

​Generar un token de webhook

​Respuesta

​Recibir webhooks

​Mejores prácticas

​Próximos pasos

Fuentes externas

Mapeo de campos

Referencia de API de Discovery

Qué resuelve Discovery

Cómo funciona Discovery

Workflow de Discovery

Verificar el estado de Discovery

Explorar las conexiones

Obtener una conexión

Inspeccionar una conexión

Probar una conexión

Crear una extracción

Monitorear el progreso de la extracción

Actualizar las conexiones disponibles

Listar los tipos de conector

Respuesta

Conexiones con agregadores (Open Finance)

Crear una conexión con un agregador

Respuesta

Listar, obtener, actualizar y eliminar

Probar una conexión con un agregador

Respuesta

Tokens de webhook de agregadores

Generar un token de webhook

Respuesta

Recibir webhooks

Mejores prácticas

Próximos pasos