{
  "openapi": "3.1.0",
  "info": {
    "title": "BlueNext · invio dichiarazione redditi",
    "version": "1.0",
    "description": "Contratto HTTP della POST di invio. I casi di accettazione multi-passo, l’idempotenza tra invii e la validazione incrociata restano nella sandbox e in scenarios.json; questo file documenta forma di richiesta e risposta."
  },
  "servers": [
    {
      "url": "https://example.invalid",
      "description": "Sostituire con la base URL dell’endpoint di sviluppo. Il percorso esatto va concordato con Fiscomed."
    }
  ],
  "paths": {
    "/": {
      "post": {
        "operationId": "submitDeclaration",
        "summary": "Invio o aggiornamento payload dichiarazione",
        "description": "Bearer token, Content-Type application/json, header Idempotency-Key obbligatorio. `tax_year` è l’anno dei redditi (di solito anno di dichiarazione − 1).",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID v4; stessa chiave e stesso body → stessa risposta (escluso request_id)."
          },
          {
            "name": "Accept",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "application/json"
              ]
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclarationPayload"
              },
              "example": {
                "declaration_year": 2027,
                "tax_year": 2026,
                "tipo_dichiarazione": "ordinaria",
                "fiscal_code": "RSSMRA80A01H501U",
                "quadri": {
                  "lm": {
                    "lm21_col_3_nuova_attivita": true,
                    "lm22": {
                      "col_1_codice_attivita": "86.21.00",
                      "col_3_componenti_positivi": "6333.00",
                      "col_6_impresa_lavoro_autonomo": "2",
                      "col_7_casi_particolari": null
                    },
                    "lm23": {
                      "col_1_codice_attivita": "86.21.00",
                      "col_3_componenti_positivi": "5000.00",
                      "col_6_impresa_lavoro_autonomo": "2",
                      "col_7_casi_particolari": "1"
                    },
                    "lm24": null,
                    "lm25": null,
                    "lm26": null,
                    "lm27": null,
                    "lm35_contributi_contabilita": "1700.00",
                    "lm44_eccedenza_compensata_f24": "50.00",
                    "lm45_versato_f24": "1200.00"
                  },
                  "rs": {
                    "rs40_ritenute": null,
                    "rs140_conservazione_documenti": "1",
                    "rs381_assenza_dati": true
                  },
                  "rr": {
                    "aliquota": "0.2607",
                    "sede_inps": "ROMA",
                    "importo": "12000.00",
                    "mese_inizio": 1,
                    "mese_fine": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payload accettato.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessBody"
                },
                "example": {
                  "request_id": "00000000-0000-4000-8000-000000000001",
                  "declaration_year": 2027,
                  "tax_year": 2026,
                  "message": "Dichiarazione ricevuta."
                }
              }
            }
          },
          "400": {
            "description": "Body non JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000001",
                      "error": {
                        "code": "INVALID_JSON",
                        "message": "Messaggio leggibile per l’operatore.",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token assente o non valido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000001",
                      "error": {
                        "code": "AUTHENTICATION_FAILED",
                        "message": "Messaggio leggibile per l’operatore.",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Contribuente o dichiarazione non presenti nell’ambiente di test.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "taxpayer": {
                    "summary": "TAXPAYER_NOT_FOUND",
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000001",
                      "error": {
                        "code": "TAXPAYER_NOT_FOUND",
                        "message": "Contribuente non censito.",
                        "details": []
                      }
                    }
                  },
                  "declaration": {
                    "summary": "DECLARATION_NOT_FOUND",
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000002",
                      "error": {
                        "code": "DECLARATION_NOT_FOUND",
                        "message": "Dichiarazione non presente per l’anno indicato.",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Stessa Idempotency-Key con payload diverso dal primo invio.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000001",
                      "error": {
                        "code": "IDEMPOTENCY_CONFLICT",
                        "message": "Messaggio leggibile per l’operatore.",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Content-Type diverso da application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000001",
                      "error": {
                        "code": "UNSUPPORTED_MEDIA_TYPE",
                        "message": "Messaggio leggibile per l’operatore.",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validazione fallita o campo sconosciuto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "validation": {
                    "summary": "VALIDATION_ERROR",
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000001",
                      "error": {
                        "code": "VALIDATION_ERROR",
                        "message": "Uno o più campi non sono validi.",
                        "details": [
                          {
                            "field": "/fiscal_code",
                            "code": "INVALID_FORMAT",
                            "message": "Codice fiscale non valido."
                          }
                        ]
                      }
                    }
                  },
                  "unknownField": {
                    "summary": "UNKNOWN_FIELD",
                    "value": {
                      "request_id": "00000000-0000-4000-8000-000000000002",
                      "error": {
                        "code": "UNKNOWN_FIELD",
                        "message": "Campo non previsto dalla specifica.",
                        "details": [
                          {
                            "field": "/quadri/lm/extra",
                            "code": "UNKNOWN_FIELD",
                            "message": "Proprietà non ammessa."
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token fornito da Fiscomed per l’ambiente di integrazione."
      }
    },
    "schemas": {
      "DeclarationPayload": {
        "title": "DeclarationPayload",
        "description": "Payload della POST di invio dichiarazione. La regola «mese_fine non precedente a mese_inizio» non è esprimibile in JSON Schema.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "declaration_year",
          "tax_year",
          "tipo_dichiarazione",
          "fiscal_code",
          "quadri"
        ],
        "properties": {
          "declaration_year": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 9999
          },
          "tax_year": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 9999
          },
          "tipo_dichiarazione": {
            "type": "string",
            "enum": [
              "ordinaria",
              "correttiva"
            ]
          },
          "fiscal_code": {
            "type": "string",
            "minLength": 1
          },
          "quadri": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "lm",
              "rs",
              "rr"
            ],
            "properties": {
              "lm": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "lm21_col_3_nuova_attivita",
                  "lm22",
                  "lm23",
                  "lm24",
                  "lm25",
                  "lm26",
                  "lm27",
                  "lm35_contributi_contabilita",
                  "lm44_eccedenza_compensata_f24",
                  "lm45_versato_f24"
                ],
                "properties": {
                  "lm21_col_3_nuova_attivita": {
                    "type": "boolean"
                  },
                  "lm22": {
                    "anyOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "col_1_codice_attivita",
                          "col_3_componenti_positivi",
                          "col_6_impresa_lavoro_autonomo",
                          "col_7_casi_particolari"
                        ],
                        "properties": {
                          "col_1_codice_attivita": {
                            "type": "string",
                            "minLength": 1
                          },
                          "col_3_componenti_positivi": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^\\d+\\.\\d{2}$"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "col_6_impresa_lavoro_autonomo": {
                            "type": "string",
                            "enum": [
                              "2"
                            ]
                          },
                          "col_7_casi_particolari": {
                            "type": "null"
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm23": {
                    "anyOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "col_1_codice_attivita",
                          "col_3_componenti_positivi",
                          "col_6_impresa_lavoro_autonomo",
                          "col_7_casi_particolari"
                        ],
                        "properties": {
                          "col_1_codice_attivita": {
                            "type": "string",
                            "minLength": 1
                          },
                          "col_3_componenti_positivi": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^\\d+\\.\\d{2}$"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "col_6_impresa_lavoro_autonomo": {
                            "type": "string",
                            "enum": [
                              "2"
                            ]
                          },
                          "col_7_casi_particolari": {
                            "anyOf": [
                              {
                                "type": "string",
                                "enum": [
                                  "1",
                                  "2"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm24": {
                    "anyOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "col_1_codice_attivita",
                          "col_3_componenti_positivi",
                          "col_6_impresa_lavoro_autonomo",
                          "col_7_casi_particolari"
                        ],
                        "properties": {
                          "col_1_codice_attivita": {
                            "type": "string",
                            "minLength": 1
                          },
                          "col_3_componenti_positivi": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^\\d+\\.\\d{2}$"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "col_6_impresa_lavoro_autonomo": {
                            "type": "string",
                            "enum": [
                              "2"
                            ]
                          },
                          "col_7_casi_particolari": {
                            "anyOf": [
                              {
                                "type": "string",
                                "enum": [
                                  "1",
                                  "2"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm25": {
                    "anyOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "col_1_codice_attivita",
                          "col_3_componenti_positivi",
                          "col_6_impresa_lavoro_autonomo",
                          "col_7_casi_particolari"
                        ],
                        "properties": {
                          "col_1_codice_attivita": {
                            "type": "string",
                            "minLength": 1
                          },
                          "col_3_componenti_positivi": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^\\d+\\.\\d{2}$"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "col_6_impresa_lavoro_autonomo": {
                            "type": "string",
                            "enum": [
                              "2"
                            ]
                          },
                          "col_7_casi_particolari": {
                            "anyOf": [
                              {
                                "type": "string",
                                "enum": [
                                  "1",
                                  "2"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm26": {
                    "anyOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "col_1_codice_attivita",
                          "col_3_componenti_positivi",
                          "col_6_impresa_lavoro_autonomo",
                          "col_7_casi_particolari"
                        ],
                        "properties": {
                          "col_1_codice_attivita": {
                            "type": "string",
                            "minLength": 1
                          },
                          "col_3_componenti_positivi": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^\\d+\\.\\d{2}$"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "col_6_impresa_lavoro_autonomo": {
                            "type": "string",
                            "enum": [
                              "2"
                            ]
                          },
                          "col_7_casi_particolari": {
                            "anyOf": [
                              {
                                "type": "string",
                                "enum": [
                                  "1",
                                  "2"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm27": {
                    "anyOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "col_1_codice_attivita",
                          "col_3_componenti_positivi",
                          "col_6_impresa_lavoro_autonomo",
                          "col_7_casi_particolari"
                        ],
                        "properties": {
                          "col_1_codice_attivita": {
                            "type": "string",
                            "minLength": 1
                          },
                          "col_3_componenti_positivi": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^\\d+\\.\\d{2}$"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "col_6_impresa_lavoro_autonomo": {
                            "type": "string",
                            "enum": [
                              "2"
                            ]
                          },
                          "col_7_casi_particolari": {
                            "anyOf": [
                              {
                                "type": "string",
                                "enum": [
                                  "1",
                                  "2"
                                ]
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm35_contributi_contabilita": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^\\d+\\.\\d{2}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm44_eccedenza_compensata_f24": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^\\d+\\.\\d{2}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "lm45_versato_f24": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^\\d+\\.\\d{2}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              },
              "rs": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "rs40_ritenute",
                  "rs140_conservazione_documenti",
                  "rs381_assenza_dati"
                ],
                "properties": {
                  "rs40_ritenute": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^\\d+\\.\\d{2}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "rs140_conservazione_documenti": {
                    "type": "string",
                    "enum": [
                      "1",
                      "2"
                    ]
                  },
                  "rs381_assenza_dati": {
                    "type": "boolean"
                  }
                }
              },
              "rr": {
                "anyOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "aliquota",
                      "sede_inps",
                      "importo",
                      "mese_inizio",
                      "mese_fine"
                    ],
                    "properties": {
                      "aliquota": {
                        "type": "string",
                        "pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$"
                      },
                      "sede_inps": {
                        "type": "string",
                        "minLength": 1
                      },
                      "importo": {
                        "type": "string",
                        "pattern": "^\\d+\\.\\d{2}$"
                      },
                      "mese_inizio": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12
                      },
                      "mese_fine": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 12
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "field",
          "code",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "JSON Pointer del campo.",
            "pattern": "^/"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SuccessBody": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "declaration_year",
          "tax_year",
          "message"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "declaration_year": {
            "type": "integer"
          },
          "tax_year": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ErrorBody": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "error"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message",
              "details"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            }
          }
        }
      }
    }
  }
}
