Integraciones

El YMS se integra con sistemas externos por tres canales bien definidos: Samsara entrante (webhooks de GPS), webhooks salientes firmados hacia los sistemas del cliente, y API REST de consulta para que sistemas internos lean el estado del patio.

flowchart LR
  SAMSARA[Samsara GPS<br/>flota del cliente] -- 1. Webhook entrante<br/>firmado --> YMS[YMS API]
  YMS -- 2. Webhooks salientes<br/>firmados HMAC --> TMS[TMS / WMS / ERP<br/>del cliente]
  TMS_R[Sistemas internos<br/>del cliente] -.-> | 3. API REST<br/>consulta read-only| YMS

  style YMS fill:#0a2540,color:#fff
  style SAMSARA fill:#ffc107,color:#212529
  style TMS fill:#79b8ff,color:#0a2540
  style TMS_R fill:#79b8ff,color:#0a2540

Tres canales de integración del YMS

🔍 Click para ampliar

---

1. Samsara — webhook entrante (GPS de flotas)

El YMS se suscribe a los eventos relevantes del API de Samsara. Cuando un trailer cruza un geofence configurado, Samsara envía un webhook firmado al backend.

Resumen ejecutivo

Qué hace: confirma — no genera — los eventos que el personal de patio ya capturó.

• Confirma que un trailer cruzó el geofence de entrada.
• Confirma que un trailer cruzó el geofence de salida.
• Sugiere la zona en la que está el trailer (señal débil, ±15-30m).

Si Samsara reporta un cruce sin que el personal haya capturado nada, el sistema genera anomalía UnexpectedManualGap para que el Yard Manager investigue.

Para trailers visitantes sin Samsara (~5%), no hay confirmación GPS — la zona se confirma exclusivamente en el rondín.

Detalle técnico

Pipeline (ADR-039):

1. Webhook firmado HMAC entra a POST /api/integrations/samsara/events.
2. Verificación de firma + idempotencia (EventId único por evento Samsara).
3. Persistencia raw en SamsaraEventRaw (audit completo, sin transformación).
4. Worker async consume eventos pendientes:
   • Busca match con MovementEvent manual reciente del mismo trailer.
   • Si encuentra: actualiza MovementEvent.GpsConfirmedAt.
   • Si no encuentra: genera Anomaly.UnexpectedManualGap (Medium).
5. Actualiza Trailer.LastGpsAt y, si aplica, Trailer.CurrentZoneId (señal débil).

Anomalías relacionadas: UnexpectedManualGap, NoGpsSignal, OperatorCorrectedGpsZone.

Sprints: 14 (webhook), 14.5 (sync), 15 (worker reescrito), 16 (polling defensivo).

Configuración requerida del cliente

• API key de Samsara con permisos de lectura sobre la flota.
• Definición de geofences por yard (perímetros) en Samsara, alineados con los polígonos de Yard.Perimeter del YMS.
• Webhook URL apuntando al backend del YMS.

---

2. Webhooks salientes — TMS / WMS / ERP del cliente

El YMS publica eventos relevantes a los sistemas internos del cliente para que reaccionen automáticamente (facturación, alerta a clientes finales, despacho, etc.).

Resumen ejecutivo

Cuándo se disparan:

• Entrada registrada (MovementEvent.EntryRegistered).
• Salida registrada (MovementEvent.ExitRegistered).
• Confirmación GPS de entrada/salida.
• Anomalía abierta (severidad High/Medium).
• Trailer cambia de zona (OperatorZoneCorrected).

Cómo: el cliente registra una URL → el YMS envía un POST JSON firmado HMAC cuando ocurre un evento de los suscritos. Reintentos con backoff exponencial si falla.

Detalle técnico

Envío:

• JSON con event_type, event_id (idempotencia), occurred_at, payload.
• Header X-YMS-Signature: sha256=... (HMAC con secret compartido).
• Header X-YMS-Event-Id para deduplicación lado cliente.

Reintentos:

• Backoff exponencial (1s, 5s, 30s, 5m, 30m, 2h) hasta 24h.
• Después de 24h sin éxito, anomalía interna WebhookDeliveryFailed + alerta al Admin.

Endpoints administrativos:

• POST /api/admin/webhook-subscriptions — registrar URL + eventos + secret.
• GET /api/admin/webhook-deliveries/{id} — auditar entregas.
• POST /api/admin/webhook-deliveries/{id}/replay — reintentar manualmente.

---

3. API REST de consulta (read-only)

Los sistemas internos del cliente pueden consultar el estado del patio vía API REST autenticada.

Resumen ejecutivo

Para qué sirve:

• Saber qué trailers están actualmente en un yard o zona.
• Consultar el histórico de movimientos de un trailer específico.
• Listar anomalías abiertas para un dashboard interno.
• Obtener fotos de inspección para reclamaciones.

Acceso: JWT con scope Viewer o superior. Cliente IT del cliente gestiona sus propios tokens.

Detalle técnico

Endpoints principales:

Endpoint	Para qué
GET /api/yards/{yardId}/state	Snapshot actual: trailers por zona, KPIs
GET /api/trailers/{trailerId}/timeline	Histórico completo del trailer
GET /api/anomalies?status=Open&yardId=...	Anomalías abiertas
GET /api/movements?from=...&to=...	Eventos en un rango
GET /api/trailers/{trailerId}/photos?type=inspection	Fotos de inspección

Convenciones: paginación con cursor, filtros por query string, respuestas JSON con data + meta.

Documentación OpenAPI/Swagger auto-generada disponible en /api/docs.

---

Integraciones futuras (out-of-scope MVP, contempladas)

• SAT / Aduanas — exportación de pedimentos y sellos para auditoría.
• TMS específico del cliente — si emite QR en la hoja de salida, integración directa con la generación del documento.
• Sistema de cámaras del patio — captura automática de fotos en cruces de geofence.

Estas no están en el alcance del MVP pero la arquitectura las soporta sin retrabajos.

---

Continúa

• Seguridad y compliance →
• Decisiones técnicas clave →