{
  "openapi": "3.1.0",
  "info": {
    "title": "CargaCompartida — Calculadora de importación de China a Perú",
    "summary": "Cotiza online tu flete, aduana e impuestos: calculadora de importación con costo estimado de traer productos de China a Perú por carga compartida (LCL) puerta a puerta en Lima.",
    "description": "API pública de solo lectura para obtener un precio referencial real, sin registro ni datos personales. Los importes salen del tarifario vigente de CargaCompartida, no de una tabla fija. Hay además un POST que crea una cotización formal y devuelve el PDF, pensado para el formulario del sitio, no para asistentes.",
    "version": "1.0.0",
    "contact": {
      "name": "CargaCompartida — CHINASKU PERU SAC",
      "email": "ventas@cargacompartida.pe",
      "url": "https://www.cargacompartida.pe"
    },
    "termsOfService": "https://www.cargacompartida.pe/",
    "x-llms-txt": "https://www.cargacompartida.pe/llms.txt"
  },
  "servers": [
    { "url": "https://www.cargacompartida.pe", "description": "Producción" }
  ],
  "paths": {
    "/api/cotizador/estimar": {
      "get": {
        "operationId": "estimarImportacion",
        "summary": "Calculadora: costo estimado de importar un volumen desde China a Perú",
        "description": "Devuelve el total en dólares y su desglose (flete, seguro, CIF, aranceles, IGV, IPM, percepción, nacionalización y entrega en Lima). No crea lead ni cotización. Usar este endpoint cuando alguien pregunte cuánto cuesta importar.",
        "tags": ["cotizador"],
        "parameters": [
          {
            "name": "cbm",
            "in": "query",
            "required": true,
            "description": "Volumen de la carga en metros cúbicos. Mínimo 0,1 y máximo 25.",
            "schema": { "type": "number", "minimum": 0.1, "maximum": 25, "examples": [2] }
          },
          {
            "name": "peso",
            "in": "query",
            "required": false,
            "description": "Peso en kilogramos. Si se omite se asumen 300 kg por CBM. Máximo 15000.",
            "schema": { "type": "number", "minimum": 0, "maximum": 15000, "examples": [120] }
          },
          {
            "name": "valorFob",
            "in": "query",
            "required": false,
            "description": "Valor de la mercadería en dólares, sin flete. Si se omite se asumen US$ 1000.",
            "schema": { "type": "number", "minimum": 0, "examples": [700] }
          },
          {
            "name": "producto",
            "in": "query",
            "required": false,
            "description": "Texto libre del producto. Define el arancel: ropa y calzado 11%, insumos 6%, resto 6%.",
            "schema": { "type": "string", "examples": ["ropa"] }
          },
          {
            "name": "categoria",
            "in": "query",
            "required": false,
            "description": "Rubro, cuando no se conoce el producto exacto. Se usa como respaldo de 'producto'.",
            "schema": { "type": "string", "examples": ["Ropa y Textil"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Estimado calculado con el tarifario vigente.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Estimado" },
                "example": {
                  "ok": true,
                  "mensaje": null,
                  "moneda": "USD",
                  "cbm": 2,
                  "pesoKg": 120,
                  "valorFob": 1000,
                  "total": 2112.00,
                  "servicio": 690.00,
                  "tributos": 422.00,
                  "delivery": 30.00,
                  "flete": 162.00,
                  "zonaReferencia": "ZONA V",
                  "desglose": {
                    "valorProducto": 1000,
                    "gastoOrigen": 70.00,
                    "flete": 162.00,
                    "seguro": 15.00,
                    "cif": 1247.00,
                    "arancel": 130.00,
                    "arancelPorcentaje": 11,
                    "isc": 0,
                    "iscPorcentaje": 0,
                    "ipm": 27.00,
                    "igv": 210.00,
                    "pigv": 55.00,
                    "totalTributos": 422.00,
                    "nacionalizacion": 413.00,
                    "delivery": 30.00,
                    "total": 2112.00
                  },
                  "aviso": "Precio referencial en dólares: puede variar según las medidas y el peso reales, el valor de la factura comercial, la partida arancelaria y el tipo de cambio. El precio final lo confirma un asesor de CargaCompartida.",
                  "fuente": "https://www.cargacompartida.pe/cotizador"
                }
              }
            }
          },
          "400": {
            "description": "Parámetro fuera de rango o dato inválido.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "ok": false, "error": "El cotizador en línea calcula hasta 25 CBM. Sobre eso se cotiza a medida con un asesor." }
              }
            }
          },
          "429": { "description": "Demasiadas consultas desde la misma IP." }
        }
      }
    },
    "/api/cotizador/referencias": {
      "get": {
        "operationId": "listarReferenciasCarga",
        "summary": "Categorías y tamaños reales de carga ya importada",
        "description": "Sirve para elegir un volumen cuando la persona no sabe cuánto ocupa su compra. Cada referencia trae CBM y peso de una carga real, sin datos del cliente.",
        "tags": ["cotizador"],
        "responses": {
          "200": {
            "description": "Categorías con sus tamaños de referencia.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "categorias": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "integer" },
                          "nombre": { "type": "string" },
                          "descripcion": { "type": ["string", "null"] },
                          "ordenes": { "type": "integer" },
                          "referencias": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "codigo": { "type": "string", "description": "Formato categoriaId:tamano" },
                                "etiqueta": { "type": "string" },
                                "cbm": { "type": "number" },
                                "pesoKg": { "type": "number" },
                                "detalle": { "type": "string" }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cotizador": {
      "post": {
        "operationId": "crearCotizacion",
        "summary": "Cotización formal con PDF y asesor asignado",
        "description": "Crea el lead y la cotización en el CRM y devuelve los totales con el PDF en base64. Requiere datos de contacto: reservado al formulario del sitio. Un asistente no debe llamarlo sin consentimiento explícito de la persona.",
        "tags": ["cotizador"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["Nombre", "Telefono", "Producto"],
                "properties": {
                  "Nombre": { "type": "string", "description": "Nombre y apellido, mínimo 3 caracteres." },
                  "Telefono": { "type": "string", "description": "Celular de 9 a 15 dígitos. Si son 9 se antepone 51." },
                  "Producto": { "type": "string", "description": "Producto a importar, mínimo 3 caracteres." },
                  "ValorFob": { "type": "number", "description": "Valor de compra en USD. Opcional si se envía Proforma." },
                  "Cbm": { "type": "number", "description": "Volumen en CBM. Obligatorio salvo que se envíe CategoriaReferencia o Proforma." },
                  "PesoKg": { "type": "number" },
                  "TamanoCodigo": { "type": "string", "description": "Tamaño aproximado cuando no hay medidas." },
                  "CategoriaReferencia": { "type": "string", "description": "Código 'categoriaId:tamano' de /referencias." },
                  "CategoriaNombre": { "type": "string", "description": "Nombre de la categoría elegida; el CRM lo usa para el arancel." },
                  "LinkProducto": { "type": "string", "description": "Link de Alibaba o 1688." },
                  "Proforma": { "type": "string", "format": "binary", "description": "PDF, JPG o PNG hasta 10 MB." },
                  "Confirmar": { "type": "boolean", "description": "true = además de estimar, guarda la cotización formal." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cotización calculada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "mensaje": { "type": "string" },
                    "numeroCotizacion": { "type": "string", "example": "CCK123" },
                    "validoHasta": { "type": "string", "format": "date-time" },
                    "totalPagar": { "type": "number" },
                    "totalServicio": { "type": "number" },
                    "totalTributos": { "type": "number" },
                    "delivery": { "type": "number" },
                    "flete": { "type": "number" },
                    "cbm": { "type": "number" },
                    "pesoKg": { "type": "number" },
                    "asesorNombre": { "type": ["string", "null"] },
                    "whatsapp": { "type": ["string", "null"] },
                    "esEstimado": { "type": "boolean" },
                    "desglose": { "$ref": "#/components/schemas/Desglose" },
                    "pdfBase64": { "type": ["string", "null"] }
                  }
                }
              }
            }
          },
          "400": { "description": "Faltan datos o están fuera de rango.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "422": { "description": "El CRM no pudo calcular con el tarifario vigente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Límite de envíos por IP: 5 cada 10 minutos." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": { "type": "string" }
        }
      },
      "Desglose": {
        "type": "object",
        "properties": {
          "valorProducto": { "type": "number", "description": "Valor FOB de la mercadería." },
          "gastoOrigen": { "type": "number" },
          "flete": { "type": "number" },
          "seguro": { "type": "number" },
          "cif": { "type": "number", "description": "Valor en aduana: mercadería + flete + seguro." },
          "arancel": { "type": "number", "description": "Ad/Valorem." },
          "arancelPorcentaje": { "type": "number" },
          "isc": { "type": "number" },
          "iscPorcentaje": { "type": "number" },
          "ipm": { "type": "number" },
          "igv": { "type": "number" },
          "pigv": { "type": "number", "description": "Percepción de IGV." },
          "totalTributos": { "type": "number" },
          "nacionalizacion": { "type": "number" },
          "delivery": { "type": "number" },
          "total": { "type": "number" }
        }
      },
      "Estimado": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "mensaje": { "type": ["string", "null"] },
          "moneda": { "type": "string", "const": "USD" },
          "cbm": { "type": "number" },
          "pesoKg": { "type": "number" },
          "valorFob": { "type": "number" },
          "total": { "type": "number" },
          "servicio": { "type": "number" },
          "tributos": { "type": "number" },
          "delivery": { "type": "number" },
          "flete": { "type": "number" },
          "zonaReferencia": { "type": "string", "description": "Zona usada para tarifar el delivery en Lima." },
          "desglose": { "$ref": "#/components/schemas/Desglose" },
          "aviso": { "type": "string" },
          "fuente": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}
