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

Con las subidas manuales de archivos, 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, lee sus esquemas y trae transacciones a Matcher bajo demanda.

Cómo funciona Discovery

Discovery se ejecuta dentro de Matcher. El motor integrado administra las conexiones a bases de datos externas y ejecuta las extracciones de forma local. Discovery expone esas conexiones, coordina el proceso de extracción y entrega los resultados directamente a Ingestion. El workflow tiene ocho pasos:

Crear una conexión: registra una base de datos con su dirección y su usuario, o una conexión REST con la API de un proveedor.
Verificar el estado: ve cuántas conexiones tiene el tenant y cuándo se sincronizaron por última vez.
Explorar las conexiones: ve las conexiones de base de datos del tenant.
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 sincronizar las conexiones desde el motor integrado.

Workflow de Discovery

Crear una conexión

Registra una conexión de base de datos para el tenant.

curl -X POST "https://api.matcher.example.com/v1/discovery/connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "prod-ledger-db",
    "databaseType": "POSTGRESQL",
    "host": "db.internal.example.com",
    "port": 5432,
    "databaseName": "ledger",
    "userName": "matcher_ro",
    "password": "..."
  }'

configName, databaseType, host, port, databaseName y userName son obligatorios. schema y password son opcionales, y Matcher nunca devuelve password. Una creación exitosa devuelve 201. Actualiza una conexión con PATCH y elimínala con DELETE en /v1/discovery/connections/{connectionId}.

Crear una conexión REST

Crea una conexión REST para extraer datos de la API de un proveedor en lugar de una base de datos.

curl -X POST "https://api.matcher.example.com/v1/discovery/rest-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "stripe-main",
    "connectorType": "STRIPE",
    "apiKey": "..."
  }'

configName y connectorType son obligatorios. connectorType es PAGBANK, STRIPE o PIX_BCB. baseURL es opcional y define la dirección de la API del proveedor para esta conexión. Cada tipo de conector también exige sus propios campos de credencial:

`connectorType`	Campos de credencial obligatorios
`PAGBANK`	`establishmentID`, `ediToken`
`STRIPE`	`apiKey`
`PIX_BCB`	`clientID`, `clientSecret`, `clientCert`, `clientKey`

Matcher almacena las credenciales cifradas. Listar los tipos de conector devuelve los mismos nombres de campo en requiredFields. Una creación exitosa devuelve 201, y la conexión aparece en la lista de conexiones como cualquier otra conexión. En una conexión REST, PATCH acepta solo configName. Para cambiar cualquier otra cosa, elimina la conexión y créala de nuevo.

Verificar el estado de Discovery

Lee el conteo de conexiones del tenant y la hora de la última sincronización.

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 de base de datos con su configName, databaseType, host, base de datos, status y si se descubrió su esquema.

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 los mismos campos 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

Obtener el historial del esquema

Lee las generaciones anteriores del esquema de una conexión, de la más antigua a la más reciente.

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

La respuesta lleva connectionId y una lista generations. Cada generación lleva archivedAt, el momento en que dejó de ser el esquema vigente, y sus tables. Cuando todas las tablas de una generación comparten una causa, la generación también lleva retirementCause:

`retirementCause`	Significado
`ABSENT_FROM_CATALOG`	El catálogo de la fuente dejó de listar la tabla.
`COLUMN_SET_SUPERSEDED`	El catálogo todavía listaba la tabla, pero con un conjunto distinto de columnas.
`CONNECTION_RETIRED`	Alguien retiró la conexión.
`UNKNOWN_LEGACY`	Una versión anterior archivó la generación y no registró ninguna causa.

Una conexión desconocida devuelve 404.

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"

La prueba se conecta a la base de datos y le hace ping. No verifica el acceso de lectura a las tablas. Una prueba fallida devuelve 200 con "healthy": false y un errorMessage. 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 una conexión. La solicitud no indica ningún contexto. Matcher ingiere el resultado en la fuente FETCHER vinculada a la conexión.

curl -X POST "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/extractions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": {
      "public.transactions": {}
    }
  }'

Cada clave de tables debe ser un nombre de tabla exactamente como lo lista el esquema de la conexión. 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). Una extracción falla cuando su resultado supera 2 GiB. 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

La actualización vuelve a sincronizar las conexiones del tenant desde el motor integrado. Una conexión que el motor ya no informa pasa a UNREACHABLE.

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 tu entorno. 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 (el id de item de Pluggy o el id de link de Belvo) es opcional. Sin él, Matcher crea una conexión que espera el consentimiento. Consulta Conectar una cuenta mediante consentimiento alojado. 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",
  "awaitingConsent": false
}

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"

Usa este flujo cuando todavía no tienes el id de item o de link del proveedor. El cliente final autoriza el acceso en el propio widget de consentimiento del proveedor.

Crea la conexión sin accountRef. La respuesta lleva "awaitingConsent": true.
Obtén el id de la conexión en la respuesta del listado.
Solicita un token de consentimiento para la conexión. La solicitud no tiene cuerpo.
Abre el widget de consentimiento del proveedor con el token de la respuesta.
Envía el id de item o de link que devuelve el widget como accountRef en PUT /v1/discovery/aggregator-connections/{id}. No necesitas enviar otros campos.

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}/connect-token" \
  -H "Authorization: Bearer $TOKEN"

La respuesta 201 lleva vendor, configName, token, expiresAt, reconsent y accountRef. Para una conexión que ya tiene un accountRef, el token renueva el consentimiento para ese mismo item o link. En ese caso, reconsent es true, y accountRef lleva el id vinculado. Pasa ese accountRef al modo de actualización del widget. La respuesta muestra el token de consentimiento una sola vez, y Matcher no lo almacena. Úsalo antes de expiresAt. Después de ese momento, el proveedor lo rechaza. Un id de conexión que no es una conexión con un agregador devuelve 404. Si el proveedor no emite un token, la llamada devuelve 422 (MTCH-0212). Si Matcher no tiene un flujo de consentimiento para el proveedor, la llamada devuelve 422 (MTCH-0213).

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. Envía solo el 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 devuelve 404. Matcher no puede probar conexiones de Belvo, así que una conexión de Belvo devuelve 422 (MTCH-0210). Una conexión que espera el consentimiento devuelve 422 (MTCH-0211). En estos casos, no se ejecuta ninguna prueba. Cada fila de la respuesta del listado lleva testable, que indica si una prueba puede ejecutarse.

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. Cuando el proveedor tiene un secreto HMAC, esa verificación es un HMAC-SHA256 válido, en hexadecimal, del cuerpo en crudo en el header X-Webhook-Signature. En los demás casos, es 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. Una nueva entrega de un evento que Matcher ya recibió 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 luego revisa el trabajo de ingesta vinculado antes de empezar una ejecución de coincidencia. Empezar una ejecución sobre datos incompletos genera excepciones incorrectas.

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

Console

Operaciones

Qué resuelve Discovery

Cómo funciona Discovery

Workflow de Discovery

Crear una conexión

Crear una conexión REST

Verificar el estado de Discovery

Explorar las conexiones

Obtener una conexión

Inspeccionar una conexión

Obtener el historial del esquema

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

​Crear una conexión

​Crear una conexión REST

​Verificar el estado de Discovery

​Explorar las conexiones

​Obtener una conexión

​Inspeccionar una conexión

​Obtener el historial del esquema

​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

​Conectar una cuenta mediante consentimiento alojado

​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

Crear una conexión

Crear una conexión REST

Verificar el estado de Discovery

Explorar las conexiones

Obtener una conexión

Inspeccionar una conexión

Obtener el historial del esquema

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

Conectar una cuenta mediante consentimiento alojado

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