Syntage · Cartas Porte (complemento CCP)

Del webhook de Syntage a las tablas de carta porte (cuerpo, mercancías, tipos de figura, ubicaciones). Pasa por un handler API que pide el detalle antes de escribir en BigQuery.

¿Llegaste hasta acá desde…?

Usa esta tabla para entrar en sentido inverso (lo que ves → de dónde sale):

El camino de carta porte por terminal_client (dbt-etls) fue ELIMINADO el 2026-09-11

El uso vivo de carta porte para pricing es Terminal v3, que lee analytics_engineering_intermediate.int_carta_porte (dbt-analytics, en solvento-risk-analytics-prod). Los modelos terminal_client de dbt-etls (cartaporte_data.sql) ya no existen: se borraron el 2026-09-11 junto con el export a Supabase (ver Apagado Terminal → Supabase).

Si ves…	Eso sale de…	La lógica está en…
Carta porte en el pricing de lanes (Terminal)	`solvento-risk-analytics-prod.terminal_v3.datarelease_*`	Terminal v3 ← `dbt-analytics` `int_carta_porte`
Datos de lanes / segmentación por carta porte	`solvento-data-prod.syntage.cp_*` (staging analytics)	`dbt-analytics` → `models/staging/carta_porte/`
❌ Carta porte en `terminal_client` (dbt-etls) — eliminado 2026-09-11	`solvento-adv-analytics-prod.terminal` (se dropea)	Ya no existe — ver Apagado Terminal → Supabase
Una carta porte "cruda" / sin transformar	`solvento-data-prod.syntage.cp_body` (RAW)	Ingesta (sin lógica de negocio); ver "Paso a paso"

Resumen

Campo	Valor
Origen	Webhook de Syntage (evento carta porte / CFDI con complemento CCP)
Patrón	Event-driven (Cloud Run → Pub/Sub → Cloud Run handler → Pub/Sub → Dataflow)
Tabla RAW	`solvento-data-prod.syntage.cp_body` (+ `cp_mercancias`, `cp_tiposfigura`, `cp_ubicaciones`)
Frecuencia	Streaming
Criticidad	🟡 Media
Dueño	Martin (data eng)
Repos	`webhook_syntage` · `api_syntage_handler` · `template-cp`

Diagrama de linaje

graph LR
    SYN[["📨 Syntage<br/>webhook carta porte"]]

    subgraph ing["Ingesta (sin lógica de negocio)"]
        CR["Cloud Run<br/>webhook-syntage-inline-prod"]
        T1(["Pub/Sub<br/>cp-api-prod"])
        H["Cloud Run handler<br/>cp-api-syntage-requests-handler-prod"]
        T2(["Pub/Sub<br/>cp-api-syntage-success"])
        DF["Dataflow<br/>cp-api-multischema-prod-20251205-191037"]
        RAW[("solvento-data-prod.syntage<br/>cp_body · cp_mercancias<br/>cp_tiposfigura · cp_ubicaciones")]
    end

    subgraph cons["Consumo (dbt)"]
        TC["❌ Terminal cliente<br/>dbt-etls models/terminal_client<br/>ELIMINADO 2026-09-11"]
        AN["Lanes / segmentación<br/>dbt-analytics carta_porte"]
    end

    SYN -->|HTTP| CR --> T1 --> H --> T2 --> DF --> RAW
    RAW --> TC
    RAW --> AN

    classDef src fill:#fde68a,stroke:#b45309,color:#000;
    classDef store fill:#bfdbfe,stroke:#1e40af,color:#000;
    classDef logic fill:#dcfce7,stroke:#15803d,color:#000;
    class SYN src;
    class RAW store;
    class TC,AN logic;

Paso a paso

Syntage emite un webhook cuando hay un CFDI con complemento de carta porte (CCP).
Cloud Run webhook-syntage-inline-prod (webhook_syntage) recibe todos los eventos de Syntage y hace fan-out; para carta porte publica al topic cp-api-prod (env INVOICE_CFDI_CP_TOPIC). Es el componente más crítico del ecosistema.
Cloud Run handler cp-api-syntage-requests-handler-prod (api_syntage_handler, CONTEXT=cartaporte, cola cp-api-syntage-queue) consume el evento, pide el detalle a la API de Syntage y publica el resultado al topic cp-api-syntage-success (errores a cp-api-syntage-errors).
Dataflow cp-api-multischema-prod-20251205-191037 (template-cp) consume cp-api-syntage-success y escribe en streaming a las 4 tablas RAW de solvento-data-prod.syntage. DLQ: cp-dlq.

Tablas que alimenta

Tabla	Contenido	Job que la carga
`syntage.cp_body`	Cuerpo / cabecera de la carta porte	`cp-api-multischema-prod-20251205-191037`
`syntage.cp_mercancias`	Mercancías transportadas	`cp-api-multischema-prod-20251205-191037`
`syntage.cp_tiposfigura`	Tipos de figura (operador, propietario, etc.)	`cp-api-multischema-prod-20251205-191037`
`syntage.cp_ubicaciones`	Ubicaciones origen / destino	`cp-api-multischema-prod-20251205-191037`

Consumo aguas abajo

Terminal de cliente — ❌ eliminado el 2026-09-11 (models/terminal_client/silver/cartaporte_data.sql). Lo que queda vivo de carta porte en dbt-etls es models/advanced_analytics/cp_data.sql, que une invoices_360.
Analytics / lanes / segmentación — staging e intermedios en dbt-analytics: models/staging/carta_porte/ e models/intermediate/carta_porte/.

Si falla 🛠️

Impacto: si cae webhook-syntage-inline-prod se afecta todo Syntage (no solo carta porte). Mitigante: Syntage reintenta los webhooks; recuperar el servicio suele bastar.

Síntoma	Dónde mirar	Acción
No llegan cartas porte nuevas	Logs Cloud Run `webhook-syntage-inline-prod` y `cp-api-syntage-requests-handler-prod`	Si fue un deploy → rollback; si es saturación → subir instancias/memoria. Syntage reintenta
Llega al handler pero no a RAW	Dataflow `cp-api-multischema-prod-…`: watermark y backlog de la suscripción; topic `cp-dlq`	Transitorios se recuperan solos; relanzar consumiendo la misma suscripción. Revisar DLQ
Carta porte no aparece en el pricing de lanes	Modelos de dbt-analytics (`int_carta_porte`) + el release del repo `terminal`	Ver Terminal v3; el camino por `terminal_client` ya no existe
Datos "raros" de mercancías / lanes	Lógica en `dbt-etls` / `dbt-analytics`	Revisar la transformación en el repo, no la ingesta

Escalación: lógica SQL / Metabase → Diego · Airbyte → Gero · resto (webhook, handler, Dataflow) → Martin.

Enlaces

📊 Estado en vivo: dashboard "Data Processes" (Cloud Monitoring)
📦 Ingesta: webhook_syntage · api_syntage_handler · template-cp
🧮 Lógica: dbt-etls (models/advanced_analytics/cp_data.sql) · dbt-analytics (models/staging/carta_porte)

Última actualización: 2026-06-21 · Si cambia el flujo o un modelo dbt, actualizar esta ficha en el mismo MR.