{
 "openapi": "3.0.3",
 "info": {
  "title": "ZitaKita API",
  "version": "1.0",
  "description": "Mitmachstunden einer Kita lesen und Familien anlegen. Authentifizierung über den Kita-Schlüssel im Header X-Api-Key. Alle Zeiten Europe/Berlin, Datum als YYYY-MM-DD, Stunden als Dezimalzahl."
 },
 "servers": [
  {
   "url": "https://zitakita.com/api/v1"
  }
 ],
 "components": {
  "securitySchemes": {
   "ApiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-Api-Key"
   }
  }
 },
 "security": [
  {
   "ApiKey": []
  }
 ],
 "paths": {
  "/kita": {
   "get": {
    "summary": "Stammdaten und Regeln der Kita",
    "responses": {
     "200": {
      "description": "name, year_start, goal_hours, rate_eur, carry_max"
     }
    }
   }
  },
  "/jobs": {
   "get": {
    "summary": "Dienste (Ausschreibungen) mit freien Plätzen",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Ab Datum, Standard heute"
     }
    ],
    "responses": {
     "200": {
      "description": "Liste: id, title, date, time, hours, slots, taken, note"
     }
    }
   },
   "post": {
    "summary": "Dienst ausschreiben",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "title",
         "date",
         "hours"
        ],
        "properties": {
         "title": {
          "type": "string"
         },
         "date": {
          "type": "string"
         },
         "time": {
          "type": "string"
         },
         "hours": {
          "type": "number"
         },
         "slots": {
          "type": "integer"
         },
         "note": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "id"
     }
    }
   }
  },
  "/families": {
   "get": {
    "summary": "Familien mit Stundenstand (ohne Zugangscodes)",
    "responses": {
     "200": {
      "description": "Liste: id, name, grp, email, goal, done, pending"
     }
    }
   },
   "post": {
    "summary": "Familie anlegen (Import). Liefert den Einladungslink; optional direkt per Mail versenden.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name"
        ],
        "properties": {
         "name": {
          "type": "string"
         },
         "grp": {
          "type": "string"
         },
         "email": {
          "type": "string"
         },
         "persons": {
          "type": "array",
          "items": {
           "type": "string"
          }
         },
         "external_id": {
          "type": "string",
          "description": "ID im Fremdsystem, verhindert Doppelimport"
         },
         "send_invite": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "id, invite"
     }
    }
   }
  },
  "/families/{id}/entries": {
   "get": {
    "summary": "Stundeneinträge einer Familie",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Liste"
     }
    }
   }
  },
  "/calendar.ics": {
   "get": {
    "summary": "Alle Dienste als iCalendar-Feed (für Kalender-Abos in anderen Apps)",
    "responses": {
     "200": {
      "description": "text/calendar"
     }
    }
   }
  },
  "/aushang": {
   "get": {
    "summary": "Offene Dienste als Text für Pinnwand, Newsletter, Kita-App",
    "parameters": [
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "text",
        "json"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Text oder JSON"
     }
    }
   }
  }
 }
}