Skip to content

Shinkansen

Shinkansen es la integración de datos de payouts y órdenes de payout hacia el data warehouse de Solvento. Combina eventos en casi tiempo real (NRT) vía webhooks, una carga diaria desde Treasury como fuente de verdad operativa y, según el diseño del producto, histórico por exportación CSV. Una vista en BigQuery expone un modelo unificado con expectativas claras de frescura de datos.

Dataset y objetos en BigQuery

Proyecto y dataset: solvento-data-prod.shinkansen

Objeto Tipo Rol
shinkansen_metadata Tabla NRT: metadata inmediata de eventos de webhook (p. ej. tracking_key, receipt_url).
shinkansen_payout_results Tabla NRT: estado técnico final del payout order (notificaciones de éxito o falla en tiempo real).
shinkansen_treasury Tabla Carga diaria: información oficial desde Treasury; fuente de verdad para conciliación y campos operativos.
shinkansen_transactions_history Tabla Carga manual (según despliegue): histórico desde exportación CSV en Shinkansen WEB.
shinkansen_unificado Vista Une información de payouts y payout orders con semántica temporal (ver siguiente sección).

La vista puede construirse solo sobre metadata, resultados y Treasury, o incorporar también el histórico CSV, según cómo esté definida en BigQuery.

Vista shinkansen_unificado

La vista consolida las fuentes anteriores para consumo analítico y operativo:

  • Al instante (NRT): quedan disponibles de inmediato campos como tracking_key y cep_receipt_url (y el resto de columnas que provienen de los flujos webhook).
  • Día siguiente: tras ejecutarse la carga diaria de Treasury, se completan el resto de los campos operativos que dependen de esa fuente de verdad.

Nombres en BigQuery

Si el nombre físico de la vista o de alguna tabla difiere en la consola (p. ej. variantes con sufijos), este documento describe el contrato funcional; conviene validar los identificadores exactos en el dataset shinkansen.

Arquitectura de flujo de datos

flowchart TB
    subgraph fuentes["Fuentes"]
        WH_M[Webhook Payout Metadata]
        WH_R[Webhook Payout Order Results]
        TAPI[API Treasury]
        CSV[Shinkansen WEB<br/>Export CSV]
    end

    subgraph nrt["Ingesta NRT"]
        CR_W[Cloud Run<br/>webhook-shinkansen-inline-prod]
        T_META[Pub/Sub<br/>shinkansen-payout-metadata-prod]
        T_RES[Pub/Sub<br/>shinkansen-payout-results-prod]
        DF_M[Dataflow<br/>shinkansen-metadata-webhook]
        DF_R[Dataflow<br/>shinkansen-payout-results-webhook]
    end

    subgraph diaria["Ingesta diaria"]
        SCH[Cloud Scheduler<br/>shinkansen-treasury-api-daily]
        CR_T[Cloud Run<br/>treasury-api-shinkansen-requests-handler]
        T_OK[Pub/Sub<br/>treasury-api-shinkansen-success]
        DF_T[Dataflow<br/>treasury-shinkansen-api]
    end

    subgraph bq["BigQuery solvento-data-prod.shinkansen"]
        TBL_M[shinkansen_metadata]
        TBL_R[shinkansen_payout_results]
        TBL_T[shinkansen_treasury]
        TBL_H[shinkansen_transactions_history]
        V_UNI[shinkansen_unificado]
    end

    WH_M --> CR_W
    WH_R --> CR_W
    CR_W --> T_META
    CR_W --> T_RES
    T_META --> DF_M
    T_RES --> DF_R
    DF_M --> TBL_M
    DF_R --> TBL_R

    SCH --> CR_T
    CR_T --> TAPI
    TAPI --> CR_T
    CR_T --> T_OK
    T_OK --> DF_T
    DF_T --> TBL_T

    CSV --> TBL_H

    TBL_M --> V_UNI
    TBL_R --> V_UNI
    TBL_T --> V_UNI
    TBL_H --> V_UNI

1. Webhooks NRT (metadata y resultados)

  1. Shinkansen envía eventos HTTP a Cloud Run webhook-shinkansen-inline-prod.
  2. El servicio enruta mensajes a dos topics de Pub/Sub:
  3. shinkansen-payout-metadata-prod
  4. shinkansen-payout-results-prod
  5. Cada topic alimenta un job de Dataflow:
  6. shinkansen-metadata-webhook → escribe en shinkansen_metadata
  7. shinkansen-payout-results-webhook → escribe en shinkansen_payout_results

2. API Treasury (carga diaria)

  1. Cloud Scheduler dispara el job shinkansen-treasury-api-daily.
  2. Se invoca Cloud Run treasury-api-shinkansen-requests-handler, que consulta la API Treasury.
  3. Las respuestas exitosas se publican en treasury-api-shinkansen-success.
  4. Dataflow treasury-shinkansen-api consume el topic y persiste en shinkansen_treasury.

3. CSV manual (histórico)

Exportaciones desde la plataforma Shinkansen WEB se cargan en shinkansen_transactions_history (flujo batch / manual según operación).

Relación con otros componentes

Esta integración usa el mismo patrón general descrito en la documentación de plataforma:

  • Cloud Run — puntos de entrada HTTP y orquestación hacia Pub/Sub.
  • Pub/Sub — desacoplamiento entre ingesta y procesamiento.
  • Dataflow — persistencia estructurada hacia BigQuery.
  • Cloud Scheduler — disparo de la ruta diaria Treasury.
  • BigQuery — dataset raw en solvento-data-prod.

Los datos raw en solvento-data-prod son el punto de partida para transformaciones posteriores hacia capas depuradas en otros proyectos GCP, según la filosofía de proyectos.

Despliegue y operación

Los procedimientos de despliegue (templates, buckets, CI) no se documentan en esta página. Cuando exista un runbook específico, deberá enlazarse desde Despliegue.

Referencias