APIs, webhooks y MCP

Inicio rápido

1) Elige el riel (webhook, MCP o Passport). 2) Crea la llave correcta en el dashboard. 3) Llama api.karvia.mx con JSON. 4) Verifica el estado real en Integraciones.

export KARVIA_API=https://api.karvia.mx
export KARVIA_KEY=kmcp_prod_YOUR_KEY

Estado de integraciones

Live = productizado. Path = contrato vía webhook/API existente (sin SDK nativo). Stub = se pueden guardar credenciales; sync aún no.

Autenticación

Hay tres familias de llaves. No las mezcles: cada endpoint espera un prefijo distinto.

Authorization: Bearer kmcp_prod_YOUR_KEY
# DMS workshop:
X-API-Key: YOUR_WORKSHOP_KEY
# Passport B2B:
Authorization: Bearer pk_live_YOUR_KEY

Webhooks entrantes (telemetría)

Envía eventos desde Samsara, Geotab, Airbag u orígenes genéricos. Usa una llave Agent API (Bearer kmcp_prod_…) con permiso de telemetría y el secreto de webhook configurado en Integraciones.

Endpoints

Secreto: header X-Samsara-Signature (HMAC). Respuesta 200 { received, eventId }.

Secreto: ?token= o X-Geotab-Token / X-Webhook-Secret.

Secreto: X-Airbag-Signature / X-Webhook-Secret / ?token=.

Contrato genérico. Campos mínimos: external_vehicle_id (o vehicle_id). Opcional type: diagnostics | fault | trip | alert | behavior | gps.

curl -X POST https://api.karvia.mx/api/webhooks/generic \
  -H "Authorization: Bearer kmcp_prod_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_vehicle_id": "CAR-1234",
    "latitude": 19.4326,
    "longitude": -99.1332,
    "speed": 65,
    "odometer": 42000
  }'

DMS / GetCarSignal / CarSignal

CarSignal (trycarsignal.com / getcarsignal.com) y DMS genéricos (Zapier, Make, n8n, CDK vía JSON) usan webhooks de taller. No hay conector nativo por marca. Hay dos endpoints con contratos distintos.

A) Webhook público DMS

Auth obligatoria con X-API-Key (llave de taller). Evento procesado: service_completion. Respuesta 200.

curl -X POST https://api.karvia.mx/api/webhooks/dms/WORKSHOP_ID \
  -H "X-API-Key: YOUR_WORKSHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "service_completion",
    "dms_reference": "RO-99881",
    "vehicle": {
      "vin": "3VW…",
      "plate": "ABC123A",
      "make": "Volkswagen",
      "model": "Virtus",
      "year": 2022,
      "mileage": 48200
    },
    "service": {
      "type": "maintenance",
      "description": "Servicio 40k + aceite",
      "total_cost": 2490.0
    },
    "invoice": { "currency": "MXN", "total": 2490.0 }
  }'

Si VIN/placa no matchea un vehículo Karvia: 200 con warning (queda en log para revisión manual). Éxito: work_order_id + service_record_id.

B) Webhook taller premium

Requiere cuenta Taller Premium. Auth obligatoria: X-API-Key o Authorization Bearer. Body: arreglo services obligatorio.

curl -X POST https://api.karvia.mx/api/workshops/webhooks/dms/WORKSHOP_ID \
  -H "Authorization: Bearer YOUR_WORKSHOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dms_reference": "cs-wo-12345",
    "vehicle": { "vin": "3VW…", "plate": "ABC123A", "make": "VW", "model": "Virtus", "year": 2022 },
    "services": [
      { "type": "oil_change", "description": "Cambio de aceite", "total_cost": 890 }
    ]
  }'

Respuesta 200: { success, created_orders, count }. Mint de llaves: Taller → Webhooks (POST /api/workshops/mine/api-keys).

MCP (Agentic Hub)

Model Context Protocol sobre datos de flota (salud, alertas, viajes, copiloto). Crea la llave en Integraciones → API / MCP. Son los mismos datos del dashboard web y WhatsApp operativo.

Transportes

SSE legacy (Cursor / mcp-remote).

Streamable HTTP (Claude Cloud / clientes modernos).

Cursor mcp.json

{
  "mcpServers": {
    "karvia_hub": {
      "url": "https://api.karvia.mx/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer kmcp_prod_YOUR_KEY"
      }
    }
  }
}

mcp-remote

npx -y mcp-remote https://api.karvia.mx/api/mcp/sse \
  --header "Authorization:Bearer kmcp_prod_YOUR_KEY"

Passport B2B (/api/v1)

Identidad vehicular verificable para partners. Llaves pk_live_* emitidas por Karvia (habla con ventas). Mint y attest se encolan y se procesan; la emisión NFT on-chain puede requerir ops si aún no existe passport.

Público — métricas de plataforma.

curl -X POST https://api.karvia.mx/api/v1/passport/mint \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vin": "3VW…",
    "make": "Volkswagen",
    "model": "Virtus",
    "year": 2022,
    "ownerWallet": "0x…"
  }'

201 { requestId, status: "pending" }. 409 si el VIN ya tiene passport. Requiere vin, make, model.

masterScore requerido (0–10000 basis points). Opcional: legal, mechanical, driving, maintenance, eventType.

Lectura pública del passport.

Body: vin, eventType, payload.

Máx. 100 eventos por request.

docType + referencia IPFS/URL.

Key en path. Requiere event + vin.

Integraciones solo en el dashboard

La conexión pull de telemetría (Geotab/Samsara/VisionQube) y HRIS (Buk) se configura iniciando sesión en Integraciones — no son APIs públicas de partner.

Telemetría (conexión)

Geotab / Samsara / VisionQube: guardar credenciales → Probar → Sincronizar → mapear cada unidad. Si solo empujas datos, usa Webhooks.

HRIS

Buk: disponible (envío de scores). Workday / Runa: próximamente.

OpenAPI

Especificación machine-readable de los mismos contratos. Úsala en Postman, Insomnia o generadores de cliente.

https://karvia.mx/developers/openapi.yaml