{
  "openapi": "3.1.0",
  "info": {
    "title": "Motum OS — API pública",
    "version": "1.0.0",
    "description": "Endpoints públicos de Motum OS, el sistema operativo de flotas (Argentina). Incluye el motor de liquidación de choferes (cálculo puro, sin datos), captura de leads, estado de vinculación, posiciones de demo y el copiloto de IA. Guía para agentes: https://motumfleet.com/llms.txt",
    "contact": { "name": "Motum Fleet", "email": "hola@motumfleet.com", "url": "https://motumfleet.com/" }
  },
  "servers": [{ "url": "https://motumfleet.com" }],
  "paths": {
    "/api/calc": {
      "post": {
        "summary": "Calcular una liquidación de chofer (motor §4)",
        "description": "Cálculo puro del reparto dueño↔chofer. No toca la base ni lee datos de nadie; sin PII. Es el mismo motor que usa el producto.",
        "operationId": "calcLiquidacion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bruto": { "type": "number", "description": "Bruto generado por el chofer en el período." },
                  "cobrado_efectivo": { "type": "number", "description": "Parte cobrada en efectivo (la tiene el chofer)." },
                  "cobrado_tarjeta": { "type": "number", "description": "Parte cobrada por tarjeta (la tiene el dueño)." },
                  "gnc": { "type": "number", "description": "Gasto de GNC/combustible del período." },
                  "rule": {
                    "type": "object",
                    "properties": {
                      "type": { "type": "string", "enum": ["porcentaje", "alquiler"] },
                      "pct_owner": { "type": "number", "description": "Porcentaje del dueño. Acepta fracción (0.4) o porcentaje (40)." },
                      "monto_alquiler": { "type": "number", "description": "Alquiler fijo que paga el chofer (modelo alquiler)." },
                      "descuenta_gnc": { "type": "boolean", "default": true },
                      "absorbe_efectivo": { "type": "boolean", "default": true }
                    },
                    "required": ["type"]
                  }
                },
                "required": ["rule"]
              },
              "examples": {
                "porcentaje": { "value": { "bruto": 800000, "cobrado_efectivo": 300000, "gnc": 60000, "rule": { "type": "porcentaje", "pct_owner": 40 } } },
                "alquiler": { "value": { "cobrado_tarjeta": 500000, "gnc": 60000, "rule": { "type": "alquiler", "monto_alquiler": 250000 } } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado del cálculo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "modelo": { "type": "string" },
                    "neto": { "type": "number" },
                    "a_favor_de": { "type": "string", "enum": ["chofer", "dueño"] },
                    "detalle": { "type": "object" },
                    "resumen": { "type": "string" }
                  }
                },
                "example": { "ok": true, "modelo": "porcentaje", "neto": 120000, "a_favor_de": "chofer", "resumen": "El dueño le paga al chofer $120.000." }
              }
            }
          },
          "400": { "description": "Datos inválidos (p.ej. rule.type desconocido)." },
          "429": { "description": "Demasiadas solicitudes (rate limit 60/min por IP)." }
        }
      }
    },
    "/api/lead": {
      "post": {
        "summary": "Registrar un lead / interés",
        "description": "Registra un interés comercial. Con soft=true (o source='calculadora') no crea cuenta ni manda email de bienvenida.",
        "operationId": "createLead",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string" },
                  "vehicles": { "type": "integer" },
                  "kind": { "type": "string", "description": "'dueño' o 'chofer'." },
                  "plan": { "type": "string" },
                  "source": { "type": "string" },
                  "soft": { "type": "boolean", "description": "Lead de baja intención: no crea cuenta ni manda bienvenida." }
                },
                "required": ["email"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Registrado.", "content": { "application/json": { "example": { "ok": true } } } },
          "400": { "description": "Email inválido." }
        }
      }
    },
    "/api/pair": {
      "get": {
        "summary": "Estado de vinculación de un dispositivo",
        "operationId": "pairStatus",
        "parameters": [
          { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": ["status"] } },
          { "name": "device", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Identificador del dispositivo del chofer." }
        ],
        "responses": {
          "200": {
            "description": "Estado de vinculación.",
            "content": { "application/json": { "example": { "linked": true, "fleet": "Flota Uber — Neuquén", "driverName": "Martín Gutiérrez" } } }
          }
        }
      }
    },
    "/api/positions": {
      "get": {
        "summary": "Posiciones de demostración en vivo",
        "description": "Devuelve solo posiciones de demostración (device_id like demo-%) cuando se llama sin owner. Las posiciones reales de clientes requieren el email del dueño.",
        "operationId": "positions",
        "parameters": [
          { "name": "owner", "in": "query", "required": false, "schema": { "type": "string", "format": "email" } }
        ],
        "responses": {
          "200": { "description": "Lista de posiciones.", "content": { "application/json": { "example": { "positions": [] } } } }
        }
      }
    },
    "/api/copilot": {
      "post": {
        "summary": "Copiloto de IA de la flota (lado dueño)",
        "description": "Chat con el copiloto. Con una cuenta real (owner) puede usar herramientas y ejecutar acciones acotadas. Degrada a {fallback:true} si la IA está apagada.",
        "operationId": "copilot",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": { "type": "string" },
                  "owner": { "type": "string", "format": "email", "description": "Email del dueño (habilita datos y herramientas reales)." },
                  "history": { "type": "array", "items": { "type": "object" } }
                },
                "required": ["message"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Respuesta del copiloto o fallback.",
            "content": { "application/json": { "example": { "reply": "Tenés 27 unidades transmitiendo ahora." } } }
          }
        }
      }
    }
  }
}