{
  "openapi": "3.1.0",
  "info": {
    "title": "ImportRD — API de estimación de costos de importación (RD)",
    "description": "Calcula el costo total de importar un producto a República Dominicana: arancel, ITBIS, impuesto selectivo, flete y gastos. Gratis, sin registro, CORS abierto. Una marca de Grupo Altus SRL.",
    "version": "1.0.0",
    "contact": { "name": "ImportRD", "url": "https://importrd.do/desarrolladores" }
  },
  "servers": [{ "url": "https://importrd.do" }],
  "paths": {
    "/api/estimate": {
      "get": {
        "operationId": "estimateImportCost",
        "summary": "Estima el costo total de importar un producto a República Dominicana",
        "description": "Devuelve el desglose (FOB, flete, seguro, CIF, arancel, ITBIS, selectivo, gastos) y el total en USD y DOP. Sin parámetros, devuelve la documentación de uso; con solo 'category', lista las subcategorías válidas.",
        "parameters": [
          { "name": "category", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Categoría del producto. Valores: vehicles, electronics, solar, general, construction, clothing." },
          { "name": "sub", "in": "query", "required": true, "schema": { "type": "string" }, "description": "ID de subcategoría/producto (ej. phones, laptops, tvs, appliances)." },
          { "name": "fob", "in": "query", "required": true, "schema": { "type": "number", "minimum": 0 }, "description": "Valor de la mercancía (FOB) en USD." },
          { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "enum": ["courier", "air", "maritime"], "default": "courier" }, "description": "Vía de envío." },
          { "name": "origin", "in": "query", "required": false, "schema": { "type": "string" }, "description": "País de origen (ej. China, Estados Unidos) para estimar el flete si no se envía 'freight'." },
          { "name": "freight", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Flete en USD. Si se envía, se usa tal cual en vez de estimarlo." },
          { "name": "rate", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Tasa de cambio RD$/US$ (default 59)." }
        ],
        "responses": {
          "200": {
            "description": "Estimación calculada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "input": { "type": "object" },
                    "breakdown": {
                      "type": "object",
                      "properties": {
                        "fob": { "type": "number" },
                        "insurance": { "type": "number" },
                        "freight": { "type": "number" },
                        "cif": { "type": "number" },
                        "arancel": { "type": "number" },
                        "arancelRate": { "type": "number" },
                        "selectivo": { "type": "number" },
                        "itbis": { "type": "number" },
                        "portFees": { "type": "number" },
                        "brokerFee": { "type": "number" },
                        "totalUSD": { "type": "number" },
                        "totalDOP": { "type": "number" },
                        "exchangeRate": { "type": "number" }
                      }
                    },
                    "disclaimer": { "type": "string" },
                    "source": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Parámetros inválidos (devuelve las categorías/subcategorías válidas)" },
          "429": { "description": "Límite de peticiones excedido" }
        }
      }
    }
  }
}