{"openapi":"3.1.0","info":{"title":"Telegram Group Access Gateway","description":"\nMandantenfaehiges Gateway, mit dem externe Systeme (Make.com, CRM, Shopify, ...)\nZugriff auf eine **Telegram-Gruppe** gewaehren und entziehen.\n\n### Kernaussage zur Telegram-Realitaet\n\nDie Telegram Bot API kann Nutzer **nicht** per `user_id` in eine Gruppe zwingen.\nZugriff wird deshalb ueber **Einladungslinks** gewaehrt (`POST /api/v1/group/add`),\noptional mit sofortiger Zustellung per Bot-DM oder mit Admin-Freigabe\n(Beitrittsanfrage). Entfernen/Sperren laeuft ueber `POST /api/v1/group/remove`.\n\n### Authentifizierung\n\nJeder `/api/v1/*`-Aufruf braucht einen API-Key:\n\n* `X-API-Key: <key>` **oder**\n* `Authorization: Bearer <key>`\n\n### Beispiel (Make.com HTTP-Modul)\n\n```\nPOST https://<deine-domain>/api/v1/group/add\nX-API-Key: <key>\nContent-Type: application/json\n\n{\"telegram_user_id\": 123456789, \"external_user_id\": \"booking-4712\", \"delivery\": \"dm\"}\n```\n","contact":{"name":"Quievreux Consulting"},"license":{"name":"Proprietary - Prototype"},"version":"0.1.0"},"paths":{"/health":{"get":{"tags":["System"],"summary":"Liveness/Readiness-Check","description":"Prueft Anwendung + Datenbank. Fuer Uptime-Monitoring und Load Balancer.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/info":{"get":{"tags":["System"],"summary":"Maschinenlesbare Uebersicht der Endpunkte","description":"Frueher die Antwort auf ``/`` - jetzt getrennt, damit ``/`` eine Seite sein kann.","operationId":"info_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Info Info Get"}}}}}}},"/api/v1/me":{"get":{"tags":["Mandant"],"summary":"Eigenen Mandanten anzeigen","description":"Zeigt, zu welchem Mandanten und welcher Gruppe der verwendete API-Key gehoert.\n\nNützlich beim Debuggen von Make.com-Verbindungen.","operationId":"whoami_api_v1_me_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/add":{"post":{"tags":["Gruppen-Zugriff"],"summary":"Zugriff gewaehren (Einladungslink erzeugen)","description":"Gewaehrt einer Person Zugriff auf die Gruppe.\n\n**Wichtig:** Telegram erlaubt Bots kein direktes Hinzufuegen per ``user_id``.\nDer Endpunkt erzeugt deshalb einen (per Default einmaligen, befristeten)\nEinladungslink und sendet ihn optional per Bot-DM.\n\nTypische Antworten:\n\n* ``invited`` - Link erzeugt, ggf. per DM zugestellt\n* ``already_member`` - Person ist schon drin (idempotent, kein Fehler)\n* ``pending_join_request`` - Link mit Admin-Freigabe erzeugt","operationId":"add_member_api_v1_group_add_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMemberRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMemberResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/remove":{"post":{"tags":["Gruppen-Zugriff"],"summary":"Zugriff entziehen (entfernen oder sperren)","description":"Entfernt eine Person aus der Gruppe.\n\n``mode=kick`` (Default): ban + unban -> Person ist raus, kann aber ueber\neinen neuen Einladungslink wieder beitreten.\n``mode=ban``: dauerhafte (oder befristete) Sperre.","operationId":"remove_member_api_v1_group_remove_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveMemberRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveMemberResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/status":{"get":{"tags":["Gruppen-Zugriff"],"summary":"Bot-Rechte und Gruppen-Status pruefen","description":"Diagnose: Ist die Gruppe erreichbar und hat der Bot die noetigen Adminrechte?\n\nGeeignet als Vorab-Check in Make.com-Szenarien oder fuer Monitoring.","operationId":"group_status_api_v1_group_status_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupStatusResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/members/{telegram_user_id}":{"get":{"tags":["Gruppen-Zugriff"],"summary":"Mitgliedschaft einer Person pruefen","description":"Liefert den Telegram-Mitgliedsstatus (``member``, ``left``, ``kicked``, ...).","operationId":"member_status_api_v1_group_members__telegram_user_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"telegram_user_id","in":"path","required":true,"schema":{"type":"integer","title":"Telegram User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberStatusResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/join-requests/{telegram_user_id}/approve":{"post":{"tags":["Gruppen-Zugriff"],"summary":"Beitrittsanfrage annehmen","description":"Nimmt eine Beitrittsanfrage an (nur bei ``delivery='join_request'`` relevant).","operationId":"approve_join_request_api_v1_group_join_requests__telegram_user_id__approve_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"telegram_user_id","in":"path","required":true,"schema":{"type":"integer","title":"Telegram User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Approve Join Request Api V1 Group Join Requests  Telegram User Id  Approve Post"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/join-requests/{telegram_user_id}/decline":{"post":{"tags":["Gruppen-Zugriff"],"summary":"Beitrittsanfrage ablehnen","description":"Lehnt eine Beitrittsanfrage ab.","operationId":"decline_join_request_api_v1_group_join_requests__telegram_user_id__decline_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"telegram_user_id","in":"path","required":true,"schema":{"type":"integer","title":"Telegram User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Decline Join Request Api V1 Group Join Requests  Telegram User Id  Decline Post"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/invite-links":{"get":{"tags":["Gruppen-Zugriff"],"summary":"Erzeugte Einladungslinks auflisten","description":"Zeigt alle Links, die dieses Gateway erzeugt hat — mit Status.\n\nDamit erkennst du sofort, ob irgendwo noch ein offener Link herumliegt.","operationId":"list_invite_links_api_v1_group_invite_links_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"only_active","in":"query","required":false,"schema":{"type":"boolean","description":"Nur noch nutzbare Links zeigen","default":false,"title":"Only Active"},"description":"Nur noch nutzbare Links zeigen"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteLinkListResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/invite-links/revoke":{"post":{"tags":["Gruppen-Zugriff"],"summary":"Einladungslink(s) sperren","description":"Sperrt einen Link bei Telegram und markiert ihn als ungültig.\n\nAnwendungsfall: Ein Link ist versehentlich an die falsche Person oder in\neine öffentliche Gruppe geraten. Dann sofort `revoke_all_active: true`\nsenden — damit ist kein offener Link mehr gültig.","operationId":"revoke_invite_link_api_v1_group_invite_links_revoke_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeInviteLinkRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeInviteLinkResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/stats":{"get":{"tags":["Gruppen-Zugriff"],"summary":"Statistik: Einladungen, Austritte, Zustellquote","description":"Auswertung aus der eigenen Datenbank plus Live-Mitgliederzahl von Telegram.","operationId":"group_stats_api_v1_group_stats_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Zeitraum für die Auswertung","default":30,"title":"Days"},"description":"Zeitraum für die Auswertung"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupStatsResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/group/title":{"post":{"tags":["Gruppen-Zugriff"],"summary":"Gruppennamen ändern","description":"Ändert den Gruppennamen.\n\nDer Bot braucht dafür das Recht **Gruppe bearbeiten** (`can_change_info`) –\nin der Gruppeneinstellung unter *Administratoren* aktivierbar. Fehlt es,\nantwortet Telegram mit 403.","operationId":"set_group_title_api_v1_group_title_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetGroupTitleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetGroupTitleResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler (z. B. Bot ist nicht Admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Server nicht vollstaendig konfiguriert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/memberships":{"get":{"tags":["Mitgliedschaften"],"summary":"Mitgliedschaften auflisten","description":"Alle Mitgliedschaften des Mandanten mit Status und Laufzeit.","operationId":"list_memberships_api_v1_memberships_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipListResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Mitgliedschaften"],"summary":"Mitgliedschaft anlegen (manuell oder aus Make.com)","description":"Legt eine Mitgliedschaft an und stellt optional sofort den Zugang her.\n\nFuer Make.com ohne Stripe: einfach aufrufen, wenn eine Zahlung eingeht -\nmit ``valid_until`` fuer befristete Zugaenge.","operationId":"create_membership_api_v1_memberships_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipCreateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipCreateResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/memberships/{telegram_user_id}":{"delete":{"tags":["Mitgliedschaften"],"summary":"Mitgliedschaft beenden und Zugang entziehen","description":"Beendet die Mitgliedschaft sofort (ohne Kulanzfrist) und entfernt die Person.","operationId":"delete_membership_api_v1_memberships__telegram_user_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"telegram_user_id","in":"path","required":true,"schema":{"type":"integer","title":"Telegram User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Membership Api V1 Memberships  Telegram User Id  Delete"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Telegram-Fehler","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/payments/stripe":{"post":{"tags":["Mitgliedschaften"],"summary":"Stripe-Webhook (Zahlung -> Mitgliedschaft)","description":"Nimmt Stripe-Ereignisse entgegen.\n\n**Zuordnung:** Die Zahlung muss ``metadata[tenant_id]`` und\n``metadata[telegram_user_id]`` tragen (oder ``client_reference_id`` im Format\n``tenant:1|user:123456789``).\n\n**Signatur:** In Produktion ist ``STRIPE_WEBHOOK_SECRET`` Pflicht; ohne Secret\nwird nur in der Entwicklung ungeprueft gelesen.","operationId":"stripe_webhook_api_v1_payments_stripe_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeWebhookResponse"}}}},"400":{"description":"Signatur ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/documents":{"get":{"tags":["Dokumentation"],"summary":"Hinterlegte Dokumentation auflisten","description":"Alle Dokumente, die fuer diesen Mandanten (oder global) hinterlegt sind.","operationId":"list_documents_api_v1_documents_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListResponse"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Dokument nicht vorhanden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/documents/{identifier}":{"get":{"tags":["Dokumentation"],"summary":"Dokument lesen (per key oder ID)","description":"Liefert Titel, Kategorie und Inhalt eines Dokuments.","operationId":"get_document_api_v1_documents__identifier__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDetail"}}}},"401":{"description":"API-Key fehlt oder ist ungueltig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Dokument nicht vorhanden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/telegram/webhook-info":{"get":{"tags":["Telegram Webhook","System"],"summary":"Aktuellen Webhook-Status bei Telegram abfragen","description":"Zeigt, ob und wohin Telegram Updates schickt (Debugging-Hilfe).","operationId":"webhook_info_telegram_webhook_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Webhook Info Telegram Webhook Info Get"}}}}}}}},"components":{"schemas":{"AddMemberRequest":{"properties":{"telegram_user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Telegram User Id","description":"Telegram-Nutzer-ID. Noetig fuer die DM-Zustellung.","examples":[123456789]},"external_user_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"External User Id","description":"ID aus dem Quellsystem (CRM/Buchung) - nur fuer Tracking.","examples":["booking-4711"]},"delivery":{"type":"string","enum":["dm","link_only","join_request"],"title":"Delivery","description":"dm = Einladungslink per Bot-DM senden (Nutzer muss den Bot gestartet haben); link_only = Link nur in der API-Antwort zurueckgeben; join_request = Link mit Admin-Freigabe (Beitrittsanfrage).","default":"dm"},"ttl_minutes":{"anyOf":[{"type":"integer","maximum":10080.0,"minimum":1.0},{"type":"null"}],"title":"Ttl Minutes","description":"Gueltigkeit des Links; Default aus .env."},"single_use":{"type":"boolean","title":"Single Use","description":"Link nur fuer eine Person gueltig.","default":true},"label":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Label","description":"Name des Links (Tracking)."}},"additionalProperties":false,"type":"object","title":"AddMemberRequest","description":"Zugriff gewaehren.\n\nHinweis: Die Telegram Bot API kann Nutzer nicht direkt hinzufuegen.\nEs wird ein (standardmaessig einmaliger) Einladungslink erzeugt und -\nwenn moeglich - per DM an den Nutzer gesendet."},"AddMemberResponse":{"properties":{"status":{"type":"string","enum":["invited","already_member","link_created","pending_join_request"],"title":"Status","default":"invited"},"chat_id":{"type":"string","title":"Chat Id"},"invite_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invite Link","description":"Einmal-/Zeitlink zum Beitritt."},"deep_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deep Link","description":"t.me-Link zum Weiterleiten."},"delivered":{"type":"boolean","title":"Delivered","description":"True, wenn die DM an den Nutzer rausging.","default":false},"delivery_detail":{"type":"string","title":"Delivery Detail","description":"Klartext-Hinweis / Telegram-Fehler.","default":""},"telegram_user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Telegram User Id"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External User Id"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"single_use":{"type":"boolean","title":"Single Use","default":true}},"additionalProperties":false,"type":"object","required":["chat_id"],"title":"AddMemberResponse"},"BotRightsStatus":{"properties":{"can_invite_users":{"type":"boolean","title":"Can Invite Users"},"can_restrict_members":{"type":"boolean","title":"Can Restrict Members"},"can_delete_messages":{"type":"boolean","title":"Can Delete Messages"},"is_administrator":{"type":"boolean","title":"Is Administrator"}},"additionalProperties":false,"type":"object","required":["can_invite_users","can_restrict_members","can_delete_messages","is_administrator"],"title":"BotRightsStatus"},"DocumentDetail":{"properties":{"id":{"type":"integer","title":"Id"},"key":{"type":"string","title":"Key"},"title":{"type":"string","title":"Title"},"category":{"type":"string","title":"Category"},"url":{"type":"string","title":"Url","default":""},"has_body":{"type":"boolean","title":"Has Body","default":false},"sort_order":{"type":"integer","title":"Sort Order","default":100},"body":{"type":"string","title":"Body","default":""}},"additionalProperties":false,"type":"object","required":["id","key","title","category"],"title":"DocumentDetail"},"DocumentInfo":{"properties":{"id":{"type":"integer","title":"Id"},"key":{"type":"string","title":"Key"},"title":{"type":"string","title":"Title"},"category":{"type":"string","title":"Category"},"url":{"type":"string","title":"Url","default":""},"has_body":{"type":"boolean","title":"Has Body","default":false},"sort_order":{"type":"integer","title":"Sort Order","default":100}},"additionalProperties":false,"type":"object","required":["id","key","title","category"],"title":"DocumentInfo","description":"Hinterlegte Dokumentation."},"DocumentListResponse":{"properties":{"total":{"type":"integer","title":"Total"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"documents":{"items":{"$ref":"#/components/schemas/DocumentInfo"},"type":"array","title":"Documents"}},"additionalProperties":false,"type":"object","required":["total"],"title":"DocumentListResponse"},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error"},"detail":{"type":"string","title":"Detail"},"telegram_error_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Telegram Error Code"},"correlation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correlation Id"}},"additionalProperties":false,"type":"object","required":["error","detail"],"title":"ErrorResponse"},"GroupStatsResponse":{"properties":{"chat_id":{"type":"string","title":"Chat Id"},"member_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Member Count","description":"Live von Telegram"},"period_days":{"type":"integer","title":"Period Days","default":30},"invites_total":{"type":"integer","title":"Invites Total","default":0},"invites_in_period":{"type":"integer","title":"Invites In Period","default":0},"invites_today":{"type":"integer","title":"Invites Today","default":0},"links_active":{"type":"integer","title":"Links Active","default":0},"links_expired":{"type":"integer","title":"Links Expired","default":0},"links_revoked":{"type":"integer","title":"Links Revoked","default":0},"removals":{"type":"integer","title":"Removals","default":0},"bans":{"type":"integer","title":"Bans","default":0},"join_requests_approved":{"type":"integer","title":"Join Requests Approved","default":0},"join_requests_declined":{"type":"integer","title":"Join Requests Declined","default":0},"dm_delivered":{"type":"integer","title":"Dm Delivered","default":0},"dm_not_possible":{"type":"integer","title":"Dm Not Possible","default":0},"dm_success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dm Success Rate","description":"Anteil erfolgreicher DM-Zustellungen (0..1)"},"errors":{"type":"integer","title":"Errors","default":0},"first_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Event At"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"}},"additionalProperties":false,"type":"object","required":["chat_id","generated_at"],"title":"GroupStatsResponse","description":"Auswertung des Zugangsverkehrs (Prototyp: aus der eigenen Datenbank)."},"GroupStatusResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"bot_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bot Username"},"chat_id":{"type":"string","title":"Chat Id"},"chat_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chat Title"},"chat_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chat Type"},"is_administrator":{"type":"boolean","title":"Is Administrator","default":false},"rights":{"anyOf":[{"$ref":"#/components/schemas/BotRightsStatus"},{"type":"null"}]},"member_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Member Count"},"problems":{"items":{"type":"string"},"type":"array","title":"Problems"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Hinweise, die nicht als Fehler gewertet werden (z. B. Gruppenlimit)."},"checked_at":{"type":"string","format":"date-time","title":"Checked At"}},"additionalProperties":false,"type":"object","required":["ok","chat_id","checked_at"],"title":"GroupStatusResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded"],"title":"Status"},"version":{"type":"string","title":"Version"},"environment":{"type":"string","title":"Environment"},"telegram_token_configured":{"type":"boolean","title":"Telegram Token Configured"},"checks":{"additionalProperties":{"type":"string"},"type":"object","title":"Checks"}},"additionalProperties":false,"type":"object","required":["status","version","environment","telegram_token_configured"],"title":"HealthResponse"},"InviteLinkInfo":{"properties":{"id":{"type":"integer","title":"Id"},"invite_link":{"type":"string","title":"Invite Link"},"name":{"type":"string","title":"Name","default":""},"status":{"type":"string","enum":["active","expired","revoked"],"title":"Status","description":"active = noch nutzbar; expired = abgelaufen; revoked = gesperrt"},"telegram_user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Telegram User Id"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External User Id"},"join_request_mode":{"type":"boolean","title":"Join Request Mode","default":false},"member_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Member Limit"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"}},"additionalProperties":false,"type":"object","required":["id","invite_link","status","created_at"],"title":"InviteLinkInfo","description":"Ein vom Gateway erzeugter Einladungslink."},"InviteLinkListResponse":{"properties":{"chat_id":{"type":"string","title":"Chat Id"},"total":{"type":"integer","title":"Total"},"active":{"type":"integer","title":"Active"},"links":{"items":{"$ref":"#/components/schemas/InviteLinkInfo"},"type":"array","title":"Links"}},"additionalProperties":false,"type":"object","required":["chat_id","total","active"],"title":"InviteLinkListResponse"},"MemberStatusResponse":{"properties":{"chat_id":{"type":"string","title":"Chat Id"},"telegram_user_id":{"type":"integer","title":"Telegram User Id"},"is_member":{"type":"boolean","title":"Is Member"},"telegram_status":{"type":"string","title":"Telegram Status","description":"creator|administrator|member|restricted|left|kicked"}},"additionalProperties":false,"type":"object","required":["chat_id","telegram_user_id","is_member","telegram_status"],"title":"MemberStatusResponse"},"MembershipCreateRequest":{"properties":{"telegram_user_id":{"type":"integer","title":"Telegram User Id","description":"Telegram-ID des Mitglieds"},"valid_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Valid Until","description":"Ablaufdatum; leer = unbefristet"},"email":{"type":"string","maxLength":254,"title":"Email","default":""},"external_ref":{"type":"string","maxLength":128,"title":"External Ref","description":"Bestell-/Abo-Nummer","default":""},"source":{"type":"string","enum":["manual","make","stripe"],"title":"Source","default":"manual"},"grant_access_now":{"type":"boolean","title":"Grant Access Now","description":"Sofort Einladungslink erzeugen/zustellen","default":true}},"additionalProperties":false,"type":"object","required":["telegram_user_id"],"title":"MembershipCreateRequest","description":"Mitgliedschaft manuell anlegen (auch fuer Make.com ohne Stripe)."},"MembershipCreateResponse":{"properties":{"membership":{"$ref":"#/components/schemas/MembershipInfo"},"access_status":{"type":"string","title":"Access Status","default":""},"detail":{"type":"string","title":"Detail","default":""}},"additionalProperties":false,"type":"object","required":["membership"],"title":"MembershipCreateResponse"},"MembershipInfo":{"properties":{"id":{"type":"integer","title":"Id"},"tenant_id":{"type":"integer","title":"Tenant Id"},"telegram_user_id":{"type":"integer","title":"Telegram User Id"},"email":{"type":"string","title":"Email","default":""},"source":{"type":"string","title":"Source","default":"manual"},"external_ref":{"type":"string","title":"External Ref","default":""},"status":{"type":"string","title":"Status","default":"active"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"valid_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Valid Until"},"grace_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Grace Until"}},"additionalProperties":false,"type":"object","required":["id","tenant_id","telegram_user_id","started_at"],"title":"MembershipInfo","description":"Mitgliedschaft eines Telegram-Nutzers."},"MembershipListResponse":{"properties":{"total":{"type":"integer","title":"Total"},"active":{"type":"integer","title":"Active"},"grace":{"type":"integer","title":"Grace"},"expired":{"type":"integer","title":"Expired"},"memberships":{"items":{"$ref":"#/components/schemas/MembershipInfo"},"type":"array","title":"Memberships"}},"additionalProperties":false,"type":"object","required":["total","active","grace","expired"],"title":"MembershipListResponse"},"RemoveMemberRequest":{"properties":{"telegram_user_id":{"type":"integer","title":"Telegram User Id","description":"Telegram-Nutzer-ID","examples":[123456789]},"mode":{"type":"string","enum":["kick","ban"],"title":"Mode","description":"kick = entfernen, Wiederbeitritt moeglich (ban+unban); ban = dauerhaft sperren.","default":"kick"},"revoke_messages":{"type":"boolean","title":"Revoke Messages","description":"Nachrichten des Nutzers in der Gruppe loeschen (Supergruppen: immer true).","default":false},"ban_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ban Until","description":"Nur bei mode=ban: Sperre laeuft zu diesem Zeitpunkt aus."},"reason":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Reason"}},"additionalProperties":false,"type":"object","required":["telegram_user_id"],"title":"RemoveMemberRequest","description":"Zugriff entziehen."},"RemoveMemberResponse":{"properties":{"status":{"type":"string","enum":["removed","banned","not_a_member"],"title":"Status"},"chat_id":{"type":"string","title":"Chat Id"},"telegram_user_id":{"type":"integer","title":"Telegram User Id"},"detail":{"type":"string","title":"Detail","default":""},"banned_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Banned Until"}},"additionalProperties":false,"type":"object","required":["status","chat_id","telegram_user_id"],"title":"RemoveMemberResponse"},"RevokeInviteLinkRequest":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id","description":"ID aus GET /api/v1/group/invite-links"},"invite_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invite Link","description":"Alternativ die URL selbst"},"revoke_all_active":{"type":"boolean","title":"Revoke All Active","description":"ALLE noch nutzbaren Links sperren (Notfall: Link ist oeffentlich geworden)","default":false}},"additionalProperties":false,"type":"object","title":"RevokeInviteLinkRequest","description":"Sperrt einen Einladungslink. Entweder id oder invite_link angeben."},"RevokeInviteLinkResponse":{"properties":{"revoked":{"type":"integer","title":"Revoked"},"links":{"items":{"type":"string"},"type":"array","title":"Links"},"detail":{"type":"string","title":"Detail","default":""}},"additionalProperties":false,"type":"object","required":["revoked"],"title":"RevokeInviteLinkResponse"},"SetGroupTitleRequest":{"properties":{"title":{"type":"string","maxLength":128,"minLength":1,"title":"Title","description":"Neuer Gruppenname"}},"additionalProperties":false,"type":"object","required":["title"],"title":"SetGroupTitleRequest","description":"Aendert den Gruppennamen (Bot braucht das Recht 'Gruppe bearbeiten')."},"SetGroupTitleResponse":{"properties":{"chat_id":{"type":"string","title":"Chat Id"},"title":{"type":"string","title":"Title"},"detail":{"type":"string","title":"Detail"}},"additionalProperties":false,"type":"object","required":["chat_id","title","detail"],"title":"SetGroupTitleResponse"},"StripeWebhookResponse":{"properties":{"received":{"type":"boolean","title":"Received"},"event_id":{"type":"string","title":"Event Id","default":""},"event_type":{"type":"string","title":"Event Type","default":""},"handled":{"type":"boolean","title":"Handled","default":false},"detail":{"type":"string","title":"Detail","default":""}},"additionalProperties":false,"type":"object","required":["received"],"title":"StripeWebhookResponse"},"TenantInfo":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"chat_id":{"type":"string","title":"Chat Id"},"api_key_prefix":{"type":"string","title":"Api Key Prefix"},"is_active":{"type":"boolean","title":"Is Active"}},"additionalProperties":false,"type":"object","required":["id","name","chat_id","api_key_prefix","is_active"],"title":"TenantInfo"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"API-Key des Mandanten. Alternativ: 'Authorization: Bearer <key>'","in":"header","name":"X-API-Key"}}},"tags":[{"name":"System","description":"Health-Check und Diagnose (ohne API-Key)."},{"name":"Mandant","description":"Informationen zum verwendeten API-Key."},{"name":"Gruppen-Zugriff","description":"Zugriff gewaehren/entziehen, Mitgliedschaft, Statistik und Bot-Rechte pruefen."},{"name":"Dokumentation","description":"Hinterlegte Anleitungen (auch im Bot per /doku abrufbar)."},{"name":"Telegram Webhook","description":"Endpunkt fuer Telegram-Updates."}]}