Delivery Adapter — última milla

Cómo encaja con el CSB

1. El CSB encola una tarea de Cloud Tasks hacia POST /delivery/create-order firmada con la SA csb-dlv-adapter-<env>-tasks-sa (única con run.invoker).
2. El adapter selecciona el proveedor activo (DELIVERY_PROVIDER) y responde con el DeliveryResult en la misma llamada.
3. Cuando el proveedor cambia el estado de la entrega, llama a POST /webhooks/bringoz; el adapter publica el resultado en delivery.completed.v1.
4. El CSB consume la suscripción y continúa el flujo de negocio.

Bootstrap (main.ts): ValidationPipe global (transform, whitelist), GlobalExceptionFilter, CORS restringido a CORS_ORIGINS con métodos GET/POST y headers Content-Type, X-Correlation-ID, Authorization.

A · Crear orden (Cloud Tasks → proveedor)

1. Cloud Tasks → POST /delivery/create-orderCuerpo DeliveryPayloadDto. El middleware fija X-Correlation-ID (del header o UUID nuevo) y lo devuelve en la respuesta.
2. Validaciónenvelope.id y envelope.data obligatorios; el resto opcional. Campos desconocidos se descartan.
3. Provider activoDeliveryService resolvió el proveedor al arrancar (provider_selected). createOrder(envelope.data).
4. Respuesta 200{ status: "ok", provider, result }. Con Bringoz: result.status es accepted (2xx de Bringoz) o rejected (4xx, con el body de Bringoz en raw); 5xx agotados tras los reintentos → 500. No se publica en Pub/Sub en este flujo.

B · Crear orden desde un push de Pub/Sub

1. Pub/Sub → POST /delivery/eventsPush subscription con OIDC de sa-csb-api-<env> (tiene run.invoker sobre el servicio). El envelope CloudEvents v1.0 viaja en message.data (base64).
2. Decodificación y validacióndecodeEventEnvelope(): base64 → JSON → EventEnvelopeDto (id, type, source, specversion y data obligatorios). Cualquier defecto → 400.
3. Filtro por tipoSolo delivery.order.requested.v1 y order.placed.v1 (ORDER_EVENT_TYPES). Otro tipo → 400: Pub/Sub no reintenta un 4xx, así que un mensaje irrecuperable no se queda en bucle.
4. Mismo camino que create-ordertaskMetadata sintético — taskName = message.messageId, retryCount 0, queueName = subscription. Respuesta 204 sin cuerpo (ack); un 500 sí se reintenta hasta el ack deadline.

C · Webhook de Bringoz → Pub/Sub

1. Bringoz → POST /webhooks/bringozWebhookEventDto: eventType y orderId obligatorios.
2. Mapeo de estadoorder_accepted → accepted, order_rejected → rejected, order_delivered → delivered, order_cancelled → cancelled, order_in_transit → pending, cualquier otro → pending.
3. PublicaciónPubSubService.publishResult(orderId, result, { webhookEvent }) en PUBSUB_RESULT_TOPIC. Si falla → 500 y Bringoz debe reintentar.
4. Respuesta 200 { status: "ok", acknowledged: true }

Referencia interactiva en Swagger UI (carga /docs/openapi.json, mantenido a mano porque este adapter no usa @nestjs/swagger).

{
  "message": {
    // EventEnvelope (CloudEvents v1.0) serializado como JSON y en base64
    "data": "eyJpZCI6ImExYjJjM2Q0LWU1ZjYtNzg5MC1hYmNkLWVmMTIzNDU2Nzg5MCIsIC4uLn0=",
    "messageId": "11209384756102",
    "publishTime": "2026-09-11T18:20:00Z"
  },
  "subscription": "projects/rtp-transversal-dev/subscriptions/csb-delivery-orders-sub"
}

// message.data decodificado — EventEnvelopeDto:
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "delivery.order.requested.v1",
  "source": "//bebbia/order-service",
  "specversion": "1.0",
  "time": "2026-09-11T18:19:58Z",
  "entityid": "FC-1001",
  "data": { … mismo body Bringoz que envelope.data de create-order … }
}

{
  "envelope": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "entityId": "ORD-000123",
    "correlationId": "corr-7f3a",
    // data = body de Bringoz ya mapeado por el CSB (doc "Conexión Bringoz QAS")
    "data": {
      "externalId": "FC-1001-Installation",
      "fulfillmentLines": [
        {
          "id": "FC-1001",
          "type": "Delivery",
          "programName": "INSTALACION",
          "destinationTask": {
            "purpose": "Dropoff",
            "contact": { "name": "Ana López", "phoneNo": "5512345678" },
            "location": { "address": { … street, city, zipCode, country, location … } }
          },
          "lineItems": [ { "id": "300432" } ]
        }
      ],
      "itemLines": [ { "id": "300432", "sku": "300432", "count": 1, "type": "BasePack" } ],
      "metaData": [ { "key": "ServiceType", "value": "Instalacion-NuevoActivo" } ],
      "tags": [ "Entrega" ]
    }
  },
  "taskMetadata": {
    "queueName": "csb-delivery-adapter-queue",
    "retryCount": 0
  }
}
// envelope.id y envelope.data son obligatorios; entityId, correlationId y taskMetadata son opcionales

{
  "status": "ok",
  "provider": "bringoz",
  "result": {
    "orderId": "FC-1001-Installation",
    "status": "accepted",
    "providerRef": "FC-1001-Installation",
    "raw": { … respuesta de Bringoz … }
  }
// 4xx de Bringoz → status "rejected", providerRef "" y su body en raw (sigue siendo HTTP 200)
}

{
  "eventType": "order_delivered",
  "orderId": "ORD-000123",
  "status": "DELIVERED",
  "trackingUrl": "https://track.bringoz.com/ORD-000123",
  "timestamp": "2026-09-09T18:20:00Z",
  "details": {
    "driver": "…",
    "signature": "…"
  }
}

{ "status": "ok", "acknowledged": true }

{ "status": "ok", "timestamp": "…", "service": "csb-delivery-adapter", "version": "1.0.0", "provider": "bringoz" }

DeliveryPayloadDto

DeliveryResult

Mensaje publicado en Pub/Sub (webhooks)

// topic: PUBSUB_RESULT_TOPIC (default delivery.completed.v1)
{
  "eventId": "ORD-000123",
  "result": {
    "orderId": "ORD-000123",
    "status": "delivered",
    "providerRef": "ORD-000123",
    "trackingUrl": "https://track.bringoz.com/ORD-000123",
    "raw": { … details del webhook … }
  },
  "publishedAt": "2026-09-09T18:20:01.000Z",
  "source": "csb-delivery-adapter"
}
// atributos: eventId, provider ("bringoz" si providerRef no esta vacio, si no "unknown"), status, webhookEvent

No es un envelope CloudEvents como en CRM/ERP: el consumidor del CSB debe tratarlo como JSON plano.

{
  "success": false,
  "statusCode": 400,
  "error": "Bad Request Exception",
  "timestamp": "2026-09-09T15:04:05.000Z"
}

• 400DTO inválido. El detalle de campos no viaja en la respuesta (solo error: "Bad Request Exception"); está en el log unhandled_exception.
• 500Excepción del proveedor o de Pub/Sub. Con los stubs actuales solo puede ocurrir en /webhooks/bringoz (publicación).
• 200Operación aceptada; el estado de negocio va en result.status.

La política de reintentos la define la cola de Cloud Tasks del CSB (pendiente de crear). Los webhooks dependen de la política de reintento de Bringoz. El adapter no deduplica: un webhook repetido publica dos mensajes.

De extremo a extremo: qué sistema dispara, por qué puerta entra al Core Service Bus, cómo llega hoy el bus a Bringoz (directo, sin este adapter), qué ya está cableado hacia el adapter, qué falta para que los flujos pasen por él y cómo la tienda o Data Mesh usan el resultado. Fuente: rtp-csb en dev (seed, seed-data/*, infra/envs/dev) al 10 sep 2026.

Situación real: Bringoz es hoy un nodo external-api de los pipelines Bebbia. Este adapter está desplegado, publicado en el balanceador y cableado por remote state en el CSB, pero ningún flujo lo llama y sus providers son stubs. Esta página documenta ambos estados para que la migración sea un cambio de flujo, no un rediseño.

Ejemplo · cierre de orden reportado por Bringoz (CSB-01, contrato inputTemplate)

{
  "eventId": "EVT-ASSET-0001",
  "origin": "BRINGOZ",
  "occurredAt": "2026-09-02T15:00:00.000Z",
  "assetSerialNumber": "ACT-000123",
  "assetSku": "SKU-DEMO-01",
  "status": "EN_CASA_CLIENTE",
  "custodianId": "",
  "custodianName": "",
  "locationId": "",
  "orderRef": "ORD-DEMO-001",
  "bringozOrderId": "FC-ORDER-1001-Installation",
  "customerRef": "CLIENT-KEY-1",
  "config": {
    "sapPlant": "MX01",
    "bringozTenantId": "rotoplas",
    "sapMovementTypes": { … },
    "sapStorageLocations": { … },
    "custodianTypes": { … },
    "locationTypes": { … }
  }
}

SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOKS_SIGNING_KEY" | awk '{print $2}')
curl -s -X POST "https://csb-dev.rotoplas.com/api/flows/$FLOW_ID/webhook" \
  -H "Content-Type: application/json" -H "X-CSB-Signature: $SIG" -d "$BODY"

1. Outputs del adapterrtp-delivery-adapter/infra/terraform/environments/dev expone service_url, service_account_email, cloud_tasks_invoker_email (csb-dlv-adapter-dev-tasks-sa), cloud_tasks_queue y result_topic (commit 63e28d4). Estado en gs://rtp-delivery-adapter-dev-tf-state/terraform/state.
2. Remote state en el CSBdata "terraform_remote_state" "delivery_adapter" → local.adapters.delivery = { url, queue = null, tasks_sa, result_topic = null } (commit 40352ce). Esos null ya son corregibles: el adapter expone cloud_tasks_queue y result_topic; falta que el CSB los lea del remote state.
3. Variable de entornoDELIVERY_ADAPTER_URL llega a csb-api y al job de seed, pero el seed no la lee todavía.
4. Identidadsa-csb-api-dev@… tiene iam.serviceAccountUser sobre csb-dlv-adapter-dev-tasks-sa, que a su vez tiene run.invoker en el adapter. csb-api ya puede encolar tareas con OIDC hacia /delivery/*.
5. RegistryEl seed registra la ApiDefinition Bringoz Logistics v2 (proveedor externo, no el adapter): POST /auth/token, POST /v2/oms/depots, PUT /v2/oms/orders-v2, GET /v2/oms/orders/{orderId}, GET …/options, POST …/dispatch/{slotId}; API key x-api-key desde el secreto csb-dev-bringoz-credential. No hay Adapter ni Connector de delivery.
6. ResultadoEl adapter publica en PUBSUB_RESULT_TOPIC solo desde /webhooks/bringoz. El topic ya lo declara este repo (Terraform) y se expone como output result_topic; falta la suscripción del lado del CSB.

Ejemplo del paso actual (nodo try del editor, credencial del catálogo):

{
  "url": "{{BRINGOZ}}/v2/oms/orders-v2",
  "method": "PUT",
  "headers": [ { "name": "Authorization", "value": "${\"Bearer \" + brzToken.body.token}" } ],
  "args": {
    "externalId": "${string(fluentWO.body.data.createOrder.id) + \"-Installation\"}",
    "siteId": "${args.payload.config.SiteIDBringoz}",
    "accountId": "${args.payload.config.BringozAccountId}",
    "programName": "…",
    "fulfillmentLines": [ { "purpose": "Dropoff", "itemLines": [ … ] } ],
    "address": { … calle, número, ciudad, estado, cp, lat, lon … },
    "contact": { … nombre, apellidos, email, teléfonos … },
    "metaData": [ { "key": "OrderNumber_CT_FC", "value": "${args.payload.orderNumber}" }, … ]
  },
  "result": "bringozOrder",
  "retryPolicy": { "maxAttempts": 3, "initialDelaySeconds": 1, "maxDelaySeconds": 10, "multiplier": 2 }
}

1. Leer los outputs del adaptercloud_tasks_queue y result_topic ya salen de infra/terraform/environments/<env>/outputs.tf (hecho del lado del adapter). Falta en el CSB mapear el remote state a local.adapters.delivery.queue/result_topic en vez de null.
2. Proveedor realHecho: BringozProvider cableado contra QAS con Basic estático (sin /auth/token) — PUT /v2/oms/orders-v2, cancelación, depots, cotización, polling y dispatch. Falta publicar DeliveryResult en Pub/Sub también tras create-order y confirmar el endpoint de consulta (track).
3. Sembrar el registryEn seed.ts: DELIVERY: process.env.DELIVERY_ADAPTER_URL en pipelineBases, ApiDefinition Delivery Adapter (Cloud Run) con /delivery/create-order, /delivery/events, /delivery/cancel/{orderId} y las rutas de agendado /delivery/{orderId}/lines/{lineId}/…, Connector bringoz-delivery-connector y Adapter csb-delivery-adapter (cloudRunUrl = DELIVERY_ADAPTER_URL, probe /health).
4. Identidad de los workflowscsb-api ya puede firmar como csb-dlv-adapter-dev-tasks-sa; las SAs de Cloud Workflows necesitan run.invoker en csb-delivery-adapter-dev-api.
5. Cambiar el paso del flujoEn crear-orden-trabajo-bebbia reemplazar el try Bringoz por {{DELIVERY}}/delivery/create-order con auth: OIDC, compensación {{DELIVERY}}/delivery/cancel/{orderId}; ajustar condiciones a body.result.status.
6. Cerrar el ciclo con los webhooksPublicar /webhooks/bringoz por el balanceador (ruta solo para ese prefijo, firma de Bringoz), crear en el CSB la suscripción a delivery.completed.v1 y disparar CSB-01 desde ahí.
7. Deploy, ejecución y observaciónPreview GCP → Deploy → POST /api/provisioning/flows/{id}/execute con el inputTemplate; ver /monitoring y en el adapter create_order_received → create_order_completed con el X-Correlation-ID.

• deudaEl CSB modela Bringoz distinto a como es. El seed y mock-bringoz-api asumen x-api-key → POST /auth/token → Bearer y rutas /v2/oms/depots, /v2/oms/times. La doc "Conexión Bringoz QAS" (Bebbia, 10 sep 2026) fija Basic estático, x-bringoz-tenant-id, siteId en query y las rutas orders-v2/…/options/locations|summary. Este adapter ya sigue la doc; el CSB debe migrar sus flujos a él o corregir su ApiDefinition y mock.
• bloqueanteSin registro en el CSB. No hay Adapter, Connector ni ApiDefinition del adapter en el seed; DELIVERY_ADAPTER_URL llega a csb-api pero nadie la usa.
• resueltoOutputs de cola y topic. Terraform ya declara la cola csb-delivery-adapter-<env>-queue y el topic de resultados, y los expone como cloud_tasks_queue / result_topic (63e28d4). Pendiente del lado del CSB: consumirlos por remote state en vez de dejarlos en null.
• deudaContrato de envelope distinto por Cloud Tasks. DeliveryPayloadDto (id, data, taskMetadata opcional) no coincide con el SyncPayloadDto CloudEvents de CRM/ERP ni con @rtp-csb/contracts. Por Pub/Sub ya no aplica: POST /delivery/events acepta el envelope CloudEvents v1.0 tal cual (EventEnvelopeDto).
• deudaWebhooks. /webhooks/bringoz no valida firma y el servicio tiene ingress interno: Bringoz no puede llegar. Mientras tanto Bringoz usa el WebHook HMAC del flujo CSB-01.
• deudaPush a /events: falta el prefijo. El adapter ya expone POST /delivery/events (envelope CloudEvents, 204/400), pero un edge topic→adapter en el editor sigue provisionando la suscripción push a <cloudRunUrl>/events. Alinear el editor a /delivery/events (o montar un alias) y usar OIDC con sa-csb-api-<env>, que ya tiene run.invoker.
• hechoCloud Run desplegado con VPC y monitoring, documentación pública, remote state en el CSB con URL y SA de tasks, actAs de csb-api sobre la SA de tasks, pipelines Bebbia funcionando contra Bringoz directo con compensaciones.

loadDeliveryConfig() lee todo de variables de entorno con USE_SECRET_MANAGER=false; con true lee los secretos csb-<env>-* por API (los de Nexus con tolerancia a fallo). Terraform además monta seis de esos secretos (los cinco de Bringoz y delivery-provider) como variables de entorno vía secret_key_ref, así que en Cloud Run los valores llegan por dos caminos; gana la lectura por API.

Módulos networking, secrets, compute y monitoring en infra/terraform/modules, con ambientes dev, qa y prd. Es el único adapter con VPC propia y alertas declaradas.

Trigger: push a dev (y main). Sustituciones _REGION, _ENV, _SERVICE. Tags de imagen $SHORT_SHA y latest.

1. audit → install → lint + testnpm audit --audit-level=high, luego lint y jest --coverage en paralelo (sin umbral obligatorio).
2. docker build · pushMulti-stage non-root; .dockerignore excluye infra, tests y markdown.
3. terraformImporta los secretos existentes al state si faltan, luego plan + apply con image_tag=$SHORT_SHA. Aquí Terraform sí actualiza la imagen del servicio (no hay paso --no-traffic: la revisión nueva recibe tráfico directamente).
4. health-checkComprueba que latestCreatedRevisionName == latestReadyRevisionName vía Admin API.

resource.type="cloud_run_revision" resource.labels.service_name="csb-delivery-adapter-dev-api"
jsonPayload.correlationId="<X-Correlation-ID>"

Las alertas de 5xx, latencia p95 e instancias y el uptime check están en el módulo monitoring.

• hechoBringoz QAS cableado (10 sep 2026) a partir de la doc "Conexión Bringoz QAS" de Bebbia: crear, cancelar, depots, cotización, polling y dispatch contra sandbox.bringoz.com, con los mismos reintentos por endpoint que Bebbia.
• pendienteConsulta de orden en Bringoz (track): la doc de Bebbia no la incluye; confirmar endpoint con Bringoz (el CSB-01 asume GET /v2/oms/orders/{orderId}). Spec de Nexus sigue pendiente.
• pendientePublicar resultado tras create/cancel: hoy solo los webhooks publican en Pub/Sub; el CSB no recibe evento por una orden creada.
• hechoCola de Cloud Tasks y topic de resultados declarados en este repo (63e28d4): csb-delivery-adapter-<env>-queue, topic result_topic_name, run.invoker y cloudtasks.enqueuer para sa-csb-api-<env>, más los outputs para el remote state del CSB.
• hechoEntrada por Pub/Sub: POST /delivery/events acepta el envelope CloudEvents v1.0 de los topics del CSB (204 / 400 sin reintento). Queda alinear también el DeliveryPayloadDto de Cloud Tasks con @rtp-csb/contracts.
• pendienteSeguridad del webhook: firma/secreto compartido y exposición controlada por balanceador externo.
• pendienteConvención de naming (revisión de Hugo, 26 ago 2026): secretos delivery-<env>-bringoz-* y Artifact Registry propio delivery-adapter; las rutas ya cumplen (/delivery/* en inglés).
• deudaAtributo provider del mensaje Pub/Sub se infiere de providerRef (siempre bringoz/unknown), no del proveedor real.
• deudaPipeline sin canary (--no-traffic) ni umbral de cobertura; e2e no se ejecutan en CI.
• hechoScaffold completo: strategy de proveedores, webhooks → Pub/Sub, middlewares de correlación y logging, Terraform con VPC/secrets/monitoring por ambiente, pipeline, portal de documentación.