{
  "openapi": "3.0.3",
  "info": {
    "title": "CRM Pro GECOERP API",
    "description": "API REST oficial y versionada de integración para CRM Pro GECOERP. Permite la sincronización bidireccional de clientes, inventarios, cotizaciones, pedidos, facturación electrónica CFDI 4.0 con el SAT y pipeline de ventas.",
    "version": "1.0.0",
    "contact": {
      "name": "Soporte Técnico e Integraciones GECOERP",
      "url": "https://geco-crm.gecoerp.com/api-externa",
      "email": "soporte@gecoerp.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://geco-crm.gecoerp.com/terms"
    }
  },
  "x-api-versioning": {
    "strategy": "URL Path (/api/v1/) and Header Parameter (X-API-Version)",
    "current_version": "v1",
    "supported_versions": ["v1"],
    "version_header": "X-API-Version",
    "deprecation_policy": {
      "policy_description": "GECOERP implements a strict Semantic Versioning policy. Deprecated endpoints are announced at least 6 months before retirement and signal deprecation via standard HTTP Deprecation and Sunset (RFC 8594) response headers.",
      "deprecation_header": "Deprecation",
      "sunset_header": "Sunset",
      "documentation_url": "https://geco-crm.gecoerp.com/docs/"
    }
  },
  "servers": [
    {
      "url": "https://geco-crm.gecoerp.com",
      "description": "Servidor de Producción (v1)"
    }
  ],
  "tags": [
    { "name": "Clientes", "description": "Gestión de clientes, datos fiscales y saldos" },
    { "name": "Productos", "description": "Catálogo de productos, servicios, precios y existencias" },
    { "name": "Cotizaciones", "description": "Generación y seguimiento de cotizaciones comerciales" },
    { "name": "Pedidos", "description": "Órdenes de venta y estatus de surtido" },
    { "name": "Facturas", "description": "Emisión y timbrado de facturación CFDI 4.0 con SAT" },
    { "name": "Pipeline", "description": "Embudo de ventas y oportunidades comerciales" },
    { "name": "Marketplace", "description": "Feeds y aplets del ecosistema GECOERP" },
    { "name": "Autenticación", "description": "Inicio de sesión y verificación de credenciales" }
  ],
  "paths": {
    "/api/v1/clients": {
      "get": {
        "tags": ["Clientes"],
        "summary": "Listar clientes (v1)",
        "description": "Obtiene la lista paginada de clientes activos de la empresa.",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" },
          { "name": "search", "in": "query", "description": "Filtro por nombre, RFC, email o teléfono", "schema": { "type": "string" } },
          { "name": "page", "in": "query", "description": "Número de página", "schema": { "type": "integer", "default": 1 } },
          { "name": "limit", "in": "query", "description": "Registros por página (máx 100)", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Lista de clientes obtenida exitosamente",
            "headers": {
              "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
              "Vary": { "$ref": "#/components/headers/VaryHeader" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ClientListResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "post": {
        "tags": ["Clientes"],
        "summary": "Crear cliente (v1)",
        "description": "Registra un nuevo cliente con información comercial y fiscal SAT.",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ClientInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cliente creado exitosamente",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ClientDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/clients/{id}": {
      "get": {
        "tags": ["Clientes"],
        "summary": "Obtener cliente por ID (v1)",
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Detalle del cliente",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ClientDetailResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "patch": {
        "tags": ["Clientes"],
        "summary": "Actualizar cliente (v1)",
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ClientInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cliente actualizado",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ClientDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "tags": ["Productos"],
        "summary": "Listar productos (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" },
          { "name": "search", "in": "query", "schema": { "type": "string" } },
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Catálogo de productos",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "post": {
        "tags": ["Productos"],
        "summary": "Crear producto (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProductInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Producto creado",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/products/{id}": {
      "get": {
        "tags": ["Productos"],
        "summary": "Obtener producto por ID (v1)",
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Detalle del producto",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "patch": {
        "tags": ["Productos"],
        "summary": "Actualizar producto (v1)",
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProductInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Producto actualizado",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/quotations": {
      "get": {
        "tags": ["Cotizaciones"],
        "summary": "Listar cotizaciones (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "200": {
            "description": "Lista de cotizaciones",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuotationListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "post": {
        "tags": ["Cotizaciones"],
        "summary": "Crear cotización (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QuotationInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cotización creada",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuotationDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/orders": {
      "get": {
        "tags": ["Pedidos"],
        "summary": "Listar pedidos (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "200": {
            "description": "Lista de pedidos",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "post": {
        "tags": ["Pedidos"],
        "summary": "Crear pedido (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "201": {
            "description": "Pedido creado",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/invoices": {
      "get": {
        "tags": ["Facturas"],
        "summary": "Listar facturas CFDI 4.0 (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "200": {
            "description": "Lista de facturas emitidas",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InvoiceListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "post": {
        "tags": ["Facturas"],
        "summary": "Timbrar factura CFDI 4.0 con el SAT (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "201": {
            "description": "Factura timbrada exitosamente",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InvoiceDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/pipeline": {
      "get": {
        "tags": ["Pipeline"],
        "summary": "Listar oportunidades comerciales (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "200": {
            "description": "Oportunidades en el embudo",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PipelineListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      },
      "post": {
        "tags": ["Pipeline"],
        "summary": "Crear oportunidad en el pipeline (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "201": {
            "description": "Oportunidad creada",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PipelineDetailResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/pipeline/stages": {
      "get": {
        "tags": ["Pipeline"],
        "summary": "Listar etapas del pipeline (v1)",
        "security": [{ "ApiKeyAuth": [], "Timestamp": [], "Nonce": [], "Signature": [] }, { "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "responses": {
          "200": {
            "description": "Etapas del pipeline",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StageListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "tags": ["Autenticación"],
        "summary": "Iniciar sesión (v1)",
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersionHeader" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "format": "password" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Autenticación exitosa",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuthLoginResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ApiVersionHeader": {
        "name": "X-API-Version",
        "in": "header",
        "required": false,
        "description": "Versión de la API solicitada. Por defecto: v1.",
        "schema": {
          "type": "string",
          "default": "v1",
          "enum": ["v1"]
        }
      }
    },
    "headers": {
      "ApiVersionResponse": {
        "description": "Versión activa de la API que procesó la solicitud.",
        "schema": { "type": "string", "example": "v1" }
      },
      "DeprecationHeader": {
        "description": "Fecha o booleano que indica si el endpoint está obsoleto (RFC 8594).",
        "schema": { "type": "string", "example": "@1735689600" }
      },
      "SunsetHeader": {
        "description": "Fecha límite tras la cual el endpoint dejará de responder (RFC 8594).",
        "schema": { "type": "string", "example": "Wed, 31 Dec 2026 23:59:59 GMT" }
      },
      "VaryHeader": {
        "description": "Cabecera de negociación de caché HTTP.",
        "schema": { "type": "string", "example": "Accept, Accept-Encoding" }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Clave pública de API emitida en el portal de desarrolladores."
      },
      "Timestamp": {
        "type": "apiKey",
        "in": "header",
        "name": "x-timestamp",
        "description": "Timestamp Unix en milisegundos."
      },
      "Nonce": {
        "type": "apiKey",
        "in": "header",
        "name": "x-nonce",
        "description": "Cadena única y aleatoria por solicitud."
      },
      "Signature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-signature",
        "description": "Firma HMAC-SHA256 del cuerpo y encabezados con el API Secret."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Token JWT de sesión interactiva."
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "Modelo formal de error tipado conforme a RFC 9457.",
        "required": ["type", "title", "status", "detail", "code"],
        "properties": {
          "type": { "type": "string", "format": "uri", "example": "https://geco-crm.gecoerp.com/docs/errors/bad-request" },
          "title": { "type": "string", "example": "Petición Inválida" },
          "status": { "type": "integer", "example": 400 },
          "detail": { "type": "string", "example": "El campo 'name' es requerido." },
          "instance": { "type": "string", "example": "/api/v1/clients" },
          "code": { "type": "string", "example": "MISSING_REQUIRED_FIELD" },
          "invalid_params": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "reason"],
              "properties": {
                "name": { "type": "string", "example": "rfc" },
                "reason": { "type": "string", "example": "RFC inválido ante el SAT" }
              }
            }
          }
        }
      },
      "Client": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "example": "Comercializadora del Norte S.A. de C.V." },
          "rfc": { "type": "string", "example": "CNO180425ABC" },
          "email": { "type": "string", "format": "email", "example": "contacto@comercializadora.mx" },
          "phone": { "type": "string", "example": "+52 55 1234 5678" },
          "creditLimit": { "type": "number", "example": 50000.00 },
          "balance": { "type": "number", "example": 12450.00 },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "ClientInput": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "rfc": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string" },
          "address": { "type": "string" },
          "postal_code": { "type": "string" },
          "regimen_fiscal": { "type": "string", "example": "601" },
          "uso_cfdi": { "type": "string", "example": "G03" }
        }
      },
      "ClientListResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "ClientDetailResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/Client" }
        }
      },
      "Product": {
        "type": "object",
        "required": ["id", "name", "price"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "example": "Laptop Dell 15 pulgadas" },
          "sku": { "type": "string", "example": "DELL-LAP-001" },
          "barcode": { "type": "string", "example": "7501234567890" },
          "price": { "type": "number", "example": 15999.00 },
          "cost": { "type": "number", "example": 12000.00 },
          "stock": { "type": "number", "example": 10 },
          "sat_code": { "type": "string", "example": "43211503" }
        }
      },
      "ProductInput": {
        "type": "object",
        "required": ["name", "price"],
        "properties": {
          "name": { "type": "string" },
          "sku": { "type": "string" },
          "barcode": { "type": "string" },
          "price": { "type": "number" },
          "cost": { "type": "number" },
          "description": { "type": "string" },
          "category": { "type": "string" },
          "sat_code": { "type": "string" }
        }
      },
      "ProductListResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "ProductDetailResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/Product" }
        }
      },
      "Quotation": {
        "type": "object",
        "required": ["id", "client_id", "total", "status"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "folio": { "type": "string", "example": "COT-2026-001" },
          "client_id": { "type": "string", "format": "uuid" },
          "client_name": { "type": "string", "example": "Comercializadora del Norte" },
          "total": { "type": "number", "example": 25000.00 },
          "currency": { "type": "string", "example": "MXN" },
          "status": { "type": "string", "enum": ["draft", "sent", "approved", "rejected", "converted"] },
          "items_count": { "type": "integer", "example": 3 },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "QuotationInput": {
        "type": "object",
        "required": ["client_id", "items"],
        "properties": {
          "client_id": { "type": "string", "format": "uuid" },
          "currency": { "type": "string", "default": "MXN" },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["product_id", "quantity", "unit_price"],
              "properties": {
                "product_id": { "type": "string" },
                "quantity": { "type": "number" },
                "unit_price": { "type": "number" },
                "discount_percent": { "type": "number", "default": 0 }
              }
            }
          }
        }
      },
      "QuotationListResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quotation" } },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "QuotationDetailResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/Quotation" }
        }
      },
      "Order": {
        "type": "object",
        "required": ["id", "folio", "total", "status"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "folio": { "type": "string", "example": "PED-2026-089" },
          "client_id": { "type": "string", "format": "uuid" },
          "total": { "type": "number", "example": 25000.00 },
          "status": { "type": "string", "enum": ["pending", "in_process", "shipped", "delivered", "invoiced"] },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "OrderListResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "OrderDetailResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/Order" }
        }
      },
      "Invoice": {
        "type": "object",
        "required": ["id", "uuid_sat", "total", "status"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "uuid_sat": { "type": "string", "example": "4a5c89d2-3e21-4f12-9c34-7a1b89c0d123" },
          "serie": { "type": "string", "example": "F" },
          "folio": { "type": "integer", "example": 1042 },
          "rfc_emisor": { "type": "string", "example": "GEC150320XYZ" },
          "rfc_receptor": { "type": "string", "example": "CNO180425ABC" },
          "total": { "type": "number", "example": 29000.00 },
          "currency": { "type": "string", "example": "MXN" },
          "status": { "type": "string", "enum": ["stamped", "cancelled"] },
          "xml_url": { "type": "string", "format": "uri" },
          "pdf_url": { "type": "string", "format": "uri" },
          "stampedAt": { "type": "string", "format": "date-time" }
        }
      },
      "InvoiceListResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "InvoiceDetailResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/Invoice" }
        }
      },
      "Opportunity": {
        "type": "object",
        "required": ["id", "title", "value", "stage"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string", "example": "Implementación ERP 50 usuarios" },
          "value": { "type": "number", "example": 120000.00 },
          "currency": { "type": "string", "example": "MXN" },
          "stage": { "type": "string", "example": "negotiation" },
          "probability": { "type": "integer", "example": 75 },
          "client_id": { "type": "string", "format": "uuid" },
          "expected_close": { "type": "string", "format": "date" }
        }
      },
      "PipelineListResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "PipelineDetailResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/Opportunity" }
        }
      },
      "Stage": {
        "type": "object",
        "required": ["id", "name", "probability", "order"],
        "properties": {
          "id": { "type": "string", "example": "prospecting" },
          "name": { "type": "string", "example": "Prospección Inicial" },
          "probability": { "type": "integer", "example": 20 },
          "order": { "type": "integer", "example": 1 }
        }
      },
      "StageListResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Stage" } }
        }
      },
      "AuthLoginResponse": {
        "type": "object",
        "required": ["token", "user"],
        "properties": {
          "token": { "type": "string", "description": "JWT Bearer Token" },
          "user": {
            "type": "object",
            "required": ["id", "email", "name", "role"],
            "properties": {
              "id": { "type": "string" },
              "email": { "type": "string", "format": "email" },
              "name": { "type": "string" },
              "role": { "type": "string", "example": "admin" }
            }
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "required": ["total", "page", "limit", "pages"],
        "properties": {
          "total": { "type": "integer", "example": 120 },
          "page": { "type": "integer", "example": 1 },
          "limit": { "type": "integer", "example": 50 },
          "pages": { "type": "integer", "example": 3 }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Petición inválida o parámetros faltantes (RFC 9457 Problem Details)",
        "headers": {
          "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
          "Vary": { "$ref": "#/components/headers/VaryHeader" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "Unauthorized": {
        "description": "Firma inválida o credenciales no proporcionadas (RFC 9457 Problem Details)",
        "headers": {
          "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
          "Vary": { "$ref": "#/components/headers/VaryHeader" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "Forbidden": {
        "description": "Acceso denegado al endpoint para el plan contratado (RFC 9457 Problem Details)",
        "headers": {
          "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
          "Vary": { "$ref": "#/components/headers/VaryHeader" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "NotFound": {
        "description": "Recurso no encontrado (RFC 9457 Problem Details)",
        "headers": {
          "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
          "Vary": { "$ref": "#/components/headers/VaryHeader" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "UnprocessableEntity": {
        "description": "Error semántico de validación en la entidad enviada (RFC 9457 Problem Details)",
        "headers": {
          "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
          "Vary": { "$ref": "#/components/headers/VaryHeader" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "TooManyRequests": {
        "description": "Límite de tasa de peticiones excedido (RFC 9457 Problem Details)",
        "headers": {
          "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
          "Vary": { "$ref": "#/components/headers/VaryHeader" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      },
      "InternalServerError": {
        "description": "Error interno del servidor (RFC 9457 Problem Details)",
        "headers": {
          "X-API-Version": { "$ref": "#/components/headers/ApiVersionResponse" },
          "Vary": { "$ref": "#/components/headers/VaryHeader" }
        },
        "content": {
          "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } },
          "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }
        }
      }
    }
  }
}