{
  "openapi": "3.1.0",
  "info": {
    "title": "Calcola Impresa — Calculator API",
    "version": "v1 (engine 2026.09.10-rc11)",
    "description": "Deterministic estimate of the mandatory setup and recurring structural costs of Italian business and professional structures at zero revenue. Same engine as the website.",
    "license": {
      "name": "Public, free to use",
      "url": "https://calcolaimpresa.com/api"
    }
  },
  "servers": [
    {
      "url": "https://calcolaimpresa.com"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "summary": "Calculate structural costs for one legal form",
        "operationId": "calculateCosts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalculatorInput"
              },
              "example": {
                "form": "srl",
                "shareholders": [
                  {
                    "worksOperationally": true,
                    "inps": "merchant"
                  }
                ],
                "isAdmin": true,
                "adminCompensation": 20000,
                "adminOtherCompulsoryCoverage": "unknown",
                "capital": 10000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "Request body too large"
          },
          "415": {
            "description": "Unsupported content type"
          }
        }
      },
      "options": {
        "summary": "CORS preflight",
        "operationId": "calculateCostsPreflight",
        "responses": {
          "204": {
            "description": "Preflight accepted"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "InpsClass": {
        "type": "string",
        "enum": [
          "merchant",
          "artisan",
          "uncertain"
        ]
      },
      "Person": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "worksOperationally"
        ],
        "properties": {
          "worksOperationally": {
            "type": "boolean"
          },
          "inps": {
            "$ref": "#/components/schemas/InpsClass"
          }
        }
      },
      "CalculatorInput": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "form",
              "professionalCassa"
            ],
            "properties": {
              "form": {
                "type": "string",
                "enum": [
                  "professionista_piva_gestione_separata"
                ]
              },
              "professionalCassa": {
                "type": "boolean"
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "form"
            ],
            "properties": {
              "form": {
                "type": "string",
                "enum": [
                  "ditta_individuale_commerciante"
                ]
              },
              "inpsReduction35Active": {
                "type": "boolean"
              },
              "cciaaSection": {
                "type": "string",
                "enum": [
                  "special",
                  "ordinary",
                  "unknown"
                ]
              },
              "specialCase": {
                "type": "string",
                "enum": [
                  "affittacamere",
                  "produttore_assicurazione"
                ]
              },
              "seatInSicily": {
                "oneOf": [
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "string",
                    "enum": [
                      "unknown"
                    ]
                  }
                ]
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "form"
            ],
            "properties": {
              "form": {
                "type": "string",
                "enum": [
                  "ditta_individuale_artigiana"
                ]
              },
              "inpsReduction35Active": {
                "type": "boolean"
              },
              "seatInSicily": {
                "oneOf": [
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "string",
                    "enum": [
                      "unknown"
                    ]
                  }
                ]
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "form",
              "workingPartners"
            ],
            "properties": {
              "form": {
                "type": "string",
                "enum": [
                  "snc"
                ]
              },
              "workingPartners": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "inps"
                  ],
                  "properties": {
                    "inps": {
                      "$ref": "#/components/schemas/InpsClass"
                    }
                  }
                }
              },
              "nonWorkingPartners": {
                "type": "integer",
                "minimum": 0
              },
              "seatInSicily": {
                "oneOf": [
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "string",
                    "enum": [
                      "unknown"
                    ]
                  }
                ]
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "form",
              "accomandatari",
              "accomandanti"
            ],
            "properties": {
              "form": {
                "type": "string",
                "enum": [
                  "sas"
                ]
              },
              "accomandatari": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/Person"
                }
              },
              "accomandanti": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/Person"
                }
              },
              "seatInSicily": {
                "oneOf": [
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "string",
                    "enum": [
                      "unknown"
                    ]
                  }
                ]
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "form",
              "shareholders",
              "isAdmin"
            ],
            "properties": {
              "form": {
                "type": "string",
                "enum": [
                  "srl"
                ]
              },
              "shareholders": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/Person"
                }
              },
              "isAdmin": {
                "type": "boolean"
              },
              "adminCompensation": {
                "type": "number",
                "minimum": 0
              },
              "adminOtherCompulsoryCoverage": {
                "type": "string",
                "enum": [
                  "si",
                  "no",
                  "unknown"
                ]
              },
              "capital": {
                "type": "number",
                "exclusiveMinimum": 0
              },
              "activity": {
                "type": "string",
                "enum": [
                  "software_saas"
                ]
              },
              "startupInnovativaBenefitsActive": {
                "type": "boolean"
              },
              "seatInSicily": {
                "oneOf": [
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "string",
                    "enum": [
                      "unknown"
                    ]
                  }
                ]
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "form",
              "shareholders",
              "isAdmin"
            ],
            "properties": {
              "form": {
                "type": "string",
                "enum": [
                  "srls"
                ]
              },
              "shareholders": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/Person"
                }
              },
              "isAdmin": {
                "type": "boolean"
              },
              "adminCompensation": {
                "type": "number",
                "minimum": 0
              },
              "adminOtherCompulsoryCoverage": {
                "type": "string",
                "enum": [
                  "si",
                  "no",
                  "unknown"
                ]
              },
              "activity": {
                "type": "string",
                "enum": [
                  "software_saas"
                ]
              },
              "startupInnovativaBenefitsActive": {
                "type": "boolean"
              },
              "seatInSicily": {
                "oneOf": [
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "string",
                    "enum": [
                      "unknown"
                    ]
                  }
                ]
              }
            }
          }
        ]
      },
      "CalculationResponse": {
        "type": "object",
        "required": [
          "calculator",
          "engine_version",
          "rules_year",
          "methodology_url",
          "inputs",
          "results"
        ],
        "properties": {
          "calculator": {
            "type": "string"
          },
          "engine_version": {
            "type": "string"
          },
          "rules_year": {
            "type": "integer"
          },
          "methodology_url": {
            "type": "string",
            "format": "uri"
          },
          "sources_url": {
            "type": "string",
            "format": "uri"
          },
          "inputs": {
            "$ref": "#/components/schemas/CalculatorInput"
          },
          "results": {
            "type": "object",
            "description": "Complete, unrounded engine result: opening, annual fixed, INPS, INAIL status, annual totals, first 12 months, cost lines, INPS detail, excluded mandatory items, possible additional costs, warnings and assumptions.",
            "additionalProperties": true
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "level": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "date": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}