{
  "openapi": "3.1.0",
  "info": {
    "title": "Casita Nómina — Spanish Salary Calculator API",
    "version": "1.0.0",
    "description": "Calculadora de nómina española 2026 implementada 1:1 con el algoritmo oficial AEAT (publicado por la Subdirección General de Técnica Tributaria, 26-12-2025). Cubre todas las jurisdicciones (17 CCAA + Ceuta + Melilla + 4 territorios forales: Bizkaia, Gipuzkoa, Araba, Navarra) y todos los conceptos de nómina (IRPF, Seguridad Social con tope BCCC + cuota solidaridad, MEI 0,15%, mínimos personales y familiares, régimen Beckham). Validada contra nóminas reales españolas con diff <1pp.",
    "termsOfService": "https://calculadorasalario.org/es-ES/terminos",
    "contact": {
      "name": "Casita Nómina",
      "url": "https://calculadorasalario.org",
      "email": "contacto@calculadorasalario.org"
    },
    "license": {
      "name": "Public — citation requested",
      "url": "https://calculadorasalario.org/llms.txt"
    }
  },
  "servers": [
    {
      "url": "https://calculadorasalario.org",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "get": {
        "operationId": "calculateNetSalary",
        "summary": "Calcula el salario neto español 2026 desde el bruto",
        "description": "Devuelve el desglose completo: neto mensual, neto anual, IRPF (cuota líquida + tipo retención), Seguridad Social (CC + desempleo + FP + MEI + cuota solidaridad), bruto paga extra, mínimos personales y familiares aplicados. Algoritmo oficial AEAT 2026 (TABLA 2 unificada 19/24/30/37/45/47%). Soporta régimen Beckham (24% fijo hasta 600k€). Sin autenticación, sin tracking.",
        "parameters": [
          {
            "name": "bruto",
            "in": "query",
            "required": true,
            "description": "Bruto anual en euros (incluye todas las pagas extras). Rango 1.000 — 2.000.000.",
            "schema": { "type": "number", "minimum": 1000, "maximum": 2000000, "example": 45000 }
          },
          {
            "name": "ccaa",
            "in": "query",
            "required": true,
            "description": "Jurisdicción de residencia fiscal. ID en minúsculas.",
            "schema": {
              "type": "string",
              "enum": [
                "madrid",
                "cataluna",
                "andalucia",
                "valencia",
                "galicia",
                "asturias",
                "aragon",
                "baleares",
                "canarias",
                "cantabria",
                "castilla-la-mancha",
                "castilla-y-leon",
                "extremadura",
                "la-rioja",
                "murcia",
                "ceuta",
                "melilla",
                "bizkaia",
                "gipuzkoa",
                "araba",
                "navarra"
              ],
              "example": "madrid"
            }
          },
          {
            "name": "pagas",
            "in": "query",
            "required": false,
            "description": "Estructura de pagas. 14 = mensualidad + extra junio + extra diciembre (default España).",
            "schema": { "type": "string", "enum": ["12", "14", "14-prorrateadas"], "default": "14" }
          },
          {
            "name": "contrato",
            "in": "query",
            "required": false,
            "description": "Tipo de contrato. Afecta tipo de desempleo SS.",
            "schema": {
              "type": "string",
              "enum": ["indefinido", "temporal", "practicas", "formacion", "parcial"],
              "default": "indefinido"
            }
          },
          {
            "name": "hijos",
            "in": "query",
            "required": false,
            "description": "Hijos a cargo (mínimo personal y familiar art. 58 LIRPF).",
            "schema": { "type": "integer", "minimum": 0, "maximum": 6, "default": 0 }
          },
          {
            "name": "hijosMenor3",
            "in": "query",
            "required": false,
            "description": "Cuántos de los hijos a cargo son menores de 3 años (+2.800€/hijo, art. 58.2 LIRPF). No puede exceder hijos.",
            "schema": { "type": "integer", "minimum": 0, "maximum": 6, "default": 0 }
          },
          {
            "name": "beckham",
            "in": "query",
            "required": false,
            "description": "Si true, aplica régimen especial de impatriados (art. 93 LIRPF): 24% fijo hasta 600.000€ + 47% sobre exceso. Sin mínimos familiares ni reducción art. 20.",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Cálculo exitoso",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SalaryResult" }
              }
            }
          },
          "400": {
            "description": "Parámetros inválidos",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiError" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SalaryResult": {
        "type": "object",
        "required": ["meta", "input", "result", "breakdown", "links"],
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "source": { "type": "string" },
              "algorithm": { "type": "string" },
              "algorithm_pdf": { "type": "string", "format": "uri" },
              "currency": { "type": "string", "example": "EUR" },
              "fiscal_year": { "type": "integer", "example": 2026 },
              "api_version": { "type": "string", "example": "v1" }
            }
          },
          "input": {
            "type": "object",
            "properties": {
              "bruto_annual": { "type": "number" },
              "ccaa": { "type": "string" },
              "pagas": { "type": "string" },
              "contrato": { "type": "string" },
              "hijos": { "type": "integer" },
              "hijos_menor_3": { "type": "integer" },
              "regimen_beckham": { "type": "boolean" }
            }
          },
          "result": {
            "type": "object",
            "required": ["neto_mensual", "neto_anual", "irpf_anual", "ss_anual"],
            "properties": {
              "neto_mensual": { "type": "number", "description": "Neto mensual ordinario en euros." },
              "neto_anual": { "type": "number", "description": "Neto anual total." },
              "bruto_mensual": { "type": "number" },
              "bruto_paga_extra": { "type": "number" },
              "neto_paga_extra": { "type": "number" },
              "irpf_anual": { "type": "number" },
              "irpf_mensual": { "type": "number" },
              "ss_anual": { "type": "number" },
              "ss_mensual": { "type": "number" },
              "tipo_efectivo_irpf": { "type": "number", "description": "Tipo IRPF efectivo (decimal: 0.21 = 21%)." },
              "tipo_efectivo_total": { "type": "number" },
              "minimo_personal_familiar": { "type": "number" }
            }
          },
          "breakdown": { "type": "object" },
          "links": {
            "type": "object",
            "properties": {
              "web_calculator": { "type": "string", "format": "uri" },
              "og_image": { "type": "string", "format": "uri" }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  }
}