{
  "openapi": "3.1.0",
  "info": {
    "title": "Farola Public API",
    "version": "1.0.0",
    "summary": "Registrierung eines Pflegedienstes vorbereiten — der Mensch bestätigt.",
    "description": "Die einzige öffentliche Schreib-Schnittstelle von Farola. Sie legt KEIN Konto an: sie speichert eine Registrierung als ausstehend und sendet der Ansprechperson einen Bestätigungslink (7 Tage gültig). Erst wenn die Person bestätigt und ein Passwort festlegt, entsteht der Pflegedienst. Zustimmungen (Nutzungsbedingungen, Datenschutz) gibt ausschließlich der Mensch auf der Bestätigungsseite. Übermitteln Sie keine Gesundheitsdaten von Klient:innen.",
    "contact": {
      "name": "997 Ventures UG (haftungsbeschränkt)",
      "url": "https://farolacare.com/support"
    }
  },
  "servers": [
    {
      "url": "https://app.farolacare.com"
    }
  ],
  "paths": {
    "/api/public/v1/registrations": {
      "post": {
        "operationId": "prepareProviderRegistration",
        "summary": "Registrierung eines Pflegedienstes vorbereiten",
        "description": "Antwortet immer mit 202 und `pending_confirmation`, wenn die Angaben gültig sind — auch wenn es zu dieser E-Mail-Adresse bereits ein Konto gibt oder zu viele Anfragen eingegangen sind. Die Antwort verrät bewusst nichts über bestehende Konten. Sagen Sie der Person, dass eine E-Mail kommt und dass nichts angelegt ist, bis sie bestätigt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "organisationName",
                  "contactName",
                  "email"
                ],
                "properties": {
                  "organisationName": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 120,
                    "description": "Name des Pflegedienstes."
                  },
                  "contactName": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 120,
                    "description": "Name der Ansprechperson, die später bestätigt."
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 200,
                    "description": "E-Mail der Ansprechperson. Hierhin geht der Bestätigungslink."
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 160,
                    "description": "Straße und Hausnummer des Pflegedienstes."
                  },
                  "postalCode": {
                    "type": "string",
                    "maxLength": 10
                  },
                  "city": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "staffCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5000,
                    "description": "Ungefähre Zahl der Pflegekräfte."
                  },
                  "clientCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50000,
                    "description": "Ungefähre Zahl der Klient:innen."
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "agent",
                      "web"
                    ],
                    "default": "agent",
                    "description": "`agent`, wenn ein KI-Assistent die Anfrage stellt."
                  },
                  "agentName": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Name des Assistenten, z. B. „ChatGPT“. Wird der Person auf der Bestätigungsseite angezeigt."
                  }
                }
              },
              "examples": {
                "agent": {
                  "summary": "Von einem KI-Assistenten vorbereitet",
                  "value": {
                    "organisationName": "Pflegedienst Sonnenschein",
                    "contactName": "Maria Beispiel",
                    "email": "maria@example.org",
                    "city": "Mainz",
                    "staffCount": 12,
                    "clientCount": 40,
                    "source": "agent",
                    "agentName": "Claude"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Angenommen. Eine Bestätigungs-E-Mail ist unterwegs (sofern die Adresse zustellbar ist). Es wurde nichts angelegt.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "const": "pending_confirmation"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Ungültige Angaben.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "const": "INVALID_BODY"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}