Consumo desde la app (solvento-api ↔ Metabase)

Qué de Metabase usa realmente la aplicación Solvento y cómo lo pide. La app consume Metabase a través de solvento-api; el "cómo" (cliente, endpoints, autenticación, inyección de RFC) es lo que te lleva al lugar correcto cuando un número del front sale mal o falla.

Fuente de verdad — son DOS repos, y el que manda es el segundo:

solvento-api (gitlab.com/solventomx/solvento-api) define el mecanismo y los defaults: src/data-access/ (questions), src/integrations/ (dashboards embebidos), IDs default en src/data-access/config/questions/* (agregados en question.registry.ts) y en src/integrations/enums/metabase.enum.ts.

flux/app-config (gitlab.com/solventomx/devops/flux/app-config) define el ID que realmente se usa en cada ambiente: apps/<env>/solvento-api-values.yaml → envVariables.DATA_ACCESS_QUESTION_ID_*.

⚠️ Los defaults del repo mienten sobre lo que sirve un ambiente. En la práctica casi todos los IDs están overrideados por env. Para responder "¿qué question está viendo este usuario?" hay que mirar app-config del ambiente, no question.registry.ts.

0 · Cómo se comunica (mecanismo)

El cliente es MetabaseClient (src/data-access/client/metabase.client.ts). Config por env: METABASE_BASE_URL, METABASE_API_KEY (header X-API-Key), timeout METABASE_TIMEOUT_SECONDS (15s def), tope de respuesta METABASE_MAX_RESPONSE_SIZE_MB (1MB def). Hay dos formas de pedir datos de una question:

Tipo de llamada	Endpoint Metabase	Cuándo se usa
CARD	`POST {base}/api/card/{questionId}/query/json` (`/query/csv` para descarga)	La mayoría de questions. Params como template-tags (`{{variable}}`)
DASHBOARD (vía dashcard)	`POST {base}/api/dashboard/{dashboardId}/dashcard/{dashcardId}/card/{cardId}/query`	Cuando la question necesita filtros de dimensión que el endpoint de card no soporta (usa `param id` + `field id`)

Cada question se define como QuestionDefinition (question.definition.ts) con: schema (validación de params), call (CARD o DASHBOARD), prepareParams, processResult (singleValue/singleRow para tarjetas de un valor/una fila), y flags allowDownload, paginated, requiresBusinessEntity.

Multi-tenant por RFC (clave de seguridad): las questions con requiresBusinessEntity: true aplican extractTaxId('rfc'), que inyecta el RFC del usuario autenticado como parámetro rfc. Así cada carrier ve solo lo suyo. En los dashboards embebidos, el filtro por RFC viaja firmado dentro del JWT (ver §2).

Endpoints que expone solvento-api al front:

GET /data-access/question?alias=<alias> — ejecuta la question del alias y devuelve JSON.
GET /data-access/download?alias=<alias> — devuelve CSV (solo aliases con allowDownload).
GET /integrations/dashboards/:dashboardId — devuelve el JWT para embeber un dashboard (§2).

Dónde mirar cuando algo falla:

Logs del servicio: [Metabase] Question <id> queried successfully o [Metabase] API error for question <id>. Los errores cargan {entity:'Metabase', questionId, parameters} (y dashboardId/dashcardId en llamadas dashboard).
Causas típicas: response too large (>1MB → refinar params), timeout (15s), o el SQL de la question en Metabase.
El alias → questionId está en question.registry.ts; el id real en prod puede estar overrideado por una env DATA_ACCESS_QUESTION_ID_*.

1 · Registro de questions (por dominio)

Resuelto desde el repo (defaults; prod puede override por env). Tipo = CARD salvo que diga DASHBOARD.

✅ Validado contra Metabase (2026-06-26): las 31 questions existen, son accesibles y ninguna está archivada. Viven en colecciones por dominio (terminal / [Prod] Terminal v3 / homepage, Queries Resumen de crédito vf, Queries Pagos hechos a Solvento, Queries Pagos hechos a Proveedores, Queries Dashboard Adela).

Terminal / quoting / lanes — `questions/common.ts` (todas CARD; colecciones `terminal`, `[Prod] Terminal v3`, `homepage`)

Defaults del repo solvento-api — ⚠️ ninguno de estos se usa hoy en los ambientes de top-lanes; están todos overrideados (ver tabla siguiente):

Alias	Question ID (default)
ORIGINS	5494
DESTINATIONS	5495
QUOTING	5496
TOP_LANES_ORIGINS	5692
TOP_LANES_DESTINATIONS	5693
TOP_LANES_DATA	5694
TOP_LANES_ROUTES	5904
TOP_LANES_BORDER_DOMESTIC_SUMMARY	5909
DIESEL_COST	5848

IDs REALES por ambiente (`flux/app-config`) — esto es lo que sirve la app

Verificado contra apps/<env>/solvento-api-values.yaml el 2026-07-25:

Alias	demo	prod	staging	development
`TOP_LANES_ORIGINS`	6266	6266	6266	6006
`TOP_LANES_DESTINATIONS`	6265	6265	6265	6007
`TOP_LANES_DATA`	6264	6264	6264	6008
`TOP_LANES_BORDER_DOMESTIC_SUMMARY`	6267	6267	6267	6009
`TOP_LANES_ROUTES`	6268	6268	6268	6010
`ORIGINS` / `DESTINATIONS` / `QUOTING`	5494-96	5494-96	5494-96	5494-96

6264-6268 = modelo 7 → terminal_v3.datarelease_20260624. Alineados desde el commit 716fe11e (2026-06-24).
6006-6010 = modelo 6 → terminal_v3.datarelease_20260515. development quedó atrás (sirve datos ~2 meses más viejos).
Editar el SQL de una card NO requiere re-deploy (el ID se resuelve en cada request). Cambiar el ID sí: es un cambio en app-config → rollout de pods. Si editás una card, no toques nombres de columnas de salida ni template-tags: el processResult y el schema de solvento-api dependen de ellos y rompen el front sin que nadie haya deployado.

⚠️ Quoting (origins/destinations/quoting) corre sobre Terminal v2 (model_analytics_terminal_v2.v_quoting_*) en los cuatro ambientes; top-lanes sobre Terminal v3. Los defaults de top-lanes del repo (5694 → card #5696 → tabla tmp, 5904/5909 → #5901 → release 20260421) apuntan a releases viejos: un ambiente nuevo sin override serviría datos de marzo. Ver Riesgos y Terminal v3.

Resumen de crédito — `questions/credit-summary.ts` (dashboard 594; colección `Queries Resumen de crédito vf`)

Alias	Question ID	Llamada
CREDIT_SUMMARY_LIMIT	5345	CARD
CREDIT_SUMMARY_AVAILABLE	5346	CARD
CREDIT_SUMMARY_BALANCE	5347	CARD
CREDIT_SUMMARY_CREDIT_DETAIL	5894	CARD (paginado)
CREDIT_SUMMARY_CREDIT_DETAIL_FULL	5355	CARD (download) — la que apareció en Slack con timeout/alias `f0_`
CREDIT_SUMMARY_BY_PRODUCT	5549	DASHBOARD 594 / dashcard 3551 (download)
CREDIT_SUMMARY_PAYMENT_CALENDAR	5548	DASHBOARD 594 / dashcard 3550 (download)

Pagos a Solvento — `questions/payments-to-solvento.ts` (dashboard 596, todas DASHBOARD)

Alias	Question ID	Dashcard
PAYMENTS_TO_SOLVENTO_TOTAL	5356	3563
PAYMENTS_TO_SOLVENTO_CAPITAL	5357	3554
PAYMENTS_TO_SOLVENTO_INTEREST	5358	3555
PAYMENTS_TO_SOLVENTO_LATE_FEE	5359	3556
PAYMENTS_TO_SOLVENTO_SUMMARY	5360	3553 (download)
PAYMENTS_TO_SOLVENTO_DETAIL	5361	3560 (download)

Pagos a Proveedores — `questions/payments-to-providers.ts` (dashboard 598, todas DASHBOARD)

Alias	Question ID	Dashcard
PAYMENTS_TO_PROVIDERS_BY_SUPPLIER	5378	3586
PAYMENTS_TO_PROVIDERS_BY_PERIOD	5379	3587
PAYMENTS_TO_PROVIDERS_DETAIL	5381	3588 (download)

Adela — `questions/adela.ts` (dashboard 614 "Dashboard Pixel Perfect Adela", todas CARD)

Alias	Question ID
ADELA_APPROVED_CREDIT	5497
ADELA_AVAILABLE_CREDIT	5498
ADELA_USED_CREDIT	5499
ADELA_NEXT_PAYMENT	5500
ADELA_PAYMENT_HISTORY	5501 (download)
ADELA_ACCOUNT_STATEMENT	5502

2 · Dashboards embebidos — `GET /integrations/dashboards/:dashboardId`

IntegrationsService firma un JWT (jsonwebtoken, METABASE_SECRET_KEY) con payload {resource:{dashboard:<id>}, params:{<filtro RFC>}, exp: now + METABASE_TOKEN_EXPIRATION_SECONDS (def 7200)}, y el front lo usa para embeber el dashboard filtrado por RFC. Solo se permiten los IDs de la whitelist (MetabaseDashboardIdEnum):

Concepto (enum)	Dashboard ID
CREDIT_SUMMARY	594
SOLVENTO_PAYMENTS	596
SUPPLIER_PAYMENTS	598
OPERATIONAL_SUMMARY	599
SUPPLIER_OPERATIONS	603
ADELA_ACCOUNT_SUMMARY	614

Los dashboards 594/596/598/614 son a la vez embebidos (esta sección) y origen de las questions que la app consulta por dato (§1). 599 y 603 (operacionales) hoy solo se usan embebidos. Los modelos base de esos dashboards (Saldos V7, Pagos V11 Colab, Límites Colab) vienen de dataform_metabase_luzmo; los operacionales, del modelo "Audita BQ".

Diagrama

graph LR
    FRONT["🖥️ App Solvento / carrier front"]
    subgraph api["solvento-api"]
        DA["data-access<br/>GET /question · /download"]
        IN["integrations<br/>GET /dashboards/:id (JWT)"]
        REG["question.registry<br/>(alias → questionId DEFAULT)"]
        CL["MetabaseClient<br/>X-API-Key"]
    end
    CFG["flux/app-config<br/>apps/&lt;env&gt;/solvento-api-values.yaml<br/>DATA_ACCESS_QUESTION_ID_*"]
    MB["Metabase<br/>/api/card/.. · /api/dashboard/../dashcard/.."]

    FRONT --> DA --> REG --> CL --> MB
    FRONT --> IN -->|JWT firmado por RFC| MB
    CFG -.->|override: ID efectivo por ambiente| REG

    classDef logic fill:#dcfce7,stroke:#15803d,color:#000;
    classDef cfg fill:#fef9c3,stroke:#a16207,color:#000;
    class DA,IN,REG,CL logic;
    class CFG cfg;

3 · Otras questions usadas (señal de Slack) — fuera del registro de la app

Questions que no están en el registro de solvento-api pero aparecen en Slack con uso/problemas → analytics, credit-risk u operación. (Las del front como 5355, 5346, 5498, 5548 ya están arriba en §1.) Útiles para saber a dónde ir; resueltas contra Metabase. DB: 44 = solvento-adv-analytics-prod · 45 = solvento-risk-analytics-prod · 10 = Postgres del producto (directo).

ID	Question	Para qué	Fuente	Señal Slack
5124 / 5731	Estado de registros (por RFC)	Estatus de onboarding por carrier	`svc_master_public.stages`, `.carriers`	Jean/Tomas/Oscar (#data)
270	KYC_Persona física y partes relacionadas	KYC	`svc_master_public.business_info`, `.shareholders`, `.entities_kyc`…	Credit-risk, migración psql (Diego/Felipe)
3423	Last Years of Sales Revenue	Ingresos por ventas por cliente	card #3422 (Syntage Metrics)	QA sales revenue (Diego)
5673	Differences sales_revenue_..._daily vs _v	QA duplicados	MBQL/modelo	Diego
6135	Cambios en Saldos Diarios	Cambios de saldos	`analytics_engineering_core_models.historical_loanpro`	Diego
6203	Recuperación por CIEC — Precandidatos	Precandidatos recuperación CIEC	`public.*` (Postgres directo)	Leandro (#engineering)
919	SettingsClientes	Identificar clientes "paga"	`public.settings`, `business_info`	Astrid
5544	[PROD] qp_movements_mxn	Movimientos QP en MXN	`analytics_engineering.qp_movements_mxn`	Piera
287	MACs Daily	MACs diarios	`loanpro.`, `svc_master_public.`	Alejandro
5165	Accrued QP Revenue Monthly	Revenue devengado	MBQL/modelo	Jaime
6084	Syntage Insight Members - Layout Vendors V4	Layout de vendors	`svc_master_public.*`, `consistency_jobs.invoices_360`	Martin

Riesgos / deuda

⚠️ Quoting sobre Terminal v2 en los cuatro ambientes (5494-5496 → model_analytics_terminal_v2.v_quoting_*). Nunca migró a v3.
⚠️ Los defaults de top-lanes del repo apuntan a releases muertos: 5694 → card #5696 → solvento-risk-analytics-prod.tmp.chr_20260302 (sandbox de marzo) y 5904/5909 → #5901 → release 20260421. Hoy todos los ambientes los sobreescriben, pero un ambiente nuevo sin override serviría datos de marzo sin avisar. Registrado en Deprecados y Terminal v3.
⚠️ development desalineado en top-lanes (modelo 6 / release 20260515) mientras demo/prod/staging están en modelo 7.
✅ Resuelto: la 5498 (crédito disponible Adela), que en Slack figuraba "no configurada en backend", ya está wireada (ADELA_AVAILABLE_CREDIT). La versión nueva de solvento-api cableó toda la familia Adela (5497–5502).
Varias questions de operación (6203, 919) leen directo del Postgres del producto (DB 10), no del warehouse.

Cómo mantener este mapeo

ID efectivo de un ambiente (empezá siempre por acá): flux/app-config → apps/<env>/solvento-api-values.yaml → envVariables.DATA_ACCESS_QUESTION_ID_*.

grep -n "QUESTION_ID" apps/<env>/solvento-api-values.yaml
# comparar todos los ambientes de una:
for f in apps/*/solvento-api-values.yaml; do echo "--- $f"; grep "QUESTION_ID_TOP_LANES" "$f"; done

Defaults y mecanismo: solvento-api → src/data-access/config/questions/*.ts (agregados en question.registry.ts). Overridables por DATA_ACCESS_QUESTION_ID_* / DATA_ACCESS_DASHBOARD_ID_* / DATA_ACCESS_DASHCARD_ID_*.
Dashboards embebidos permitidos: src/integrations/enums/metabase.enum.ts.
Resolver qué hace una question/dashboard: conector de Metabase (retrieve por id) o metabase_metadata.* (Metabase Extractor).
Diagnóstico "el front muestra un dato viejo": ejecutá la card del ID del ambiente. Si la card devuelve el dato correcto, el problema es caché (navegador/CDN/Metabase), no el backend ni el warehouse.

Última actualización: 2026-07-25 · Se agregó la fuente de verdad que faltaba: los question IDs efectivos viven en flux/app-config por ambiente, no en los defaults de solvento-api. Tabla demo/prod/staging/development verificada contra el repo. Si el backend cambia un id/alias, o si se agrega un ambiente, actualizar.

Consumo desde la app (solvento-api ↔ Metabase)

0 · Cómo se comunica (mecanismo)

1 · Registro de questions (por dominio)

Terminal / quoting / lanes — questions/common.ts (todas CARD; colecciones terminal, [Prod] Terminal v3, homepage)

IDs REALES por ambiente (flux/app-config) — esto es lo que sirve la app

Resumen de crédito — questions/credit-summary.ts (dashboard 594; colección Queries Resumen de crédito vf)

Pagos a Solvento — questions/payments-to-solvento.ts (dashboard 596, todas DASHBOARD)

Pagos a Proveedores — questions/payments-to-providers.ts (dashboard 598, todas DASHBOARD)

Adela — questions/adela.ts (dashboard 614 "Dashboard Pixel Perfect Adela", todas CARD)

2 · Dashboards embebidos — GET /integrations/dashboards/:dashboardId