Berechtigungen, Fehler und Limits

Berechtigungen (Scopes)

Ein Client fordert Berechtigungen an, wenn er registriert wird; das Mitglied sieht sie auf der Einwilligungsseite.

Scope	Wer	Was
profile:read	Mitglied	GET /v1/me — Name, E-Mail, Kontaktdaten, Geburtsdaten, die Steuernummer, falls vorhanden, und wie die Person identifiziert ist (codicefiscale_check)
profile:write	Mitglied	PATCH /v1/me — Telefon, Geschlecht und die Identifizierung: Geburtsdatum, Geburtsort und Geburtsland, Steuernummer (optional, kann später ergänzt werden; wird erneut geprüft)
membership:read	Mitglied	GET /v1/me/membership, /events, /statuto, /card
membership:request	Mitglied	POST /v1/me/membership — Beitrittsantrag
statuto:accept	Mitglied	POST /v1/me/membership/statuto/accept
network:manage	Mitglied	die Einwilligung des Mitglieds in Verbünde (demnächst)
memberships:read	Client	GET /v1/memberships/{id}/status
verify:read	Client	Ausweisprüfung über das anonyme Kontingent hinaus
identity:signup	Client	POST /v1/signup — Konten im Namen von Mitgliedern anlegen (Server-Integrationen)
enroll:write	Client	POST /v1/enroll — Beitrittsanträge stellen, mit oder ohne Steuernummer (Anleitung)
events:read	Mitglied	GET /v1/events, /v1/events/{slug}, /eligibility — einschließlich Veranstaltungen nur für Mitglieder (Anleitung)
registrations:read	Mitglied, Client	GET /v1/me/registrations (Mitglied); GET /v1/events/{slug}/registrations (Client, ohne personenbezogene Daten)
registrations:write	Mitglied, Client	POST /v1/events/{slug}/registrations und DELETE /v1/me/registrations/{id} (Mitglied); POST …/registrations/guest (Client)
checkins:write	Client	POST /v1/checkins — Check-ins am Einlass, von einem Ausweis oder einer Anmeldung
webhooks:manage	Client	demnächst

Ein öffentlicher oder nativer Client darf nur Mitglieder-Berechtigungen anfordern; „Client“-Berechtigungen erfordern einen vertraulichen Client. Wer noch nicht Mitglied ist, darf nur die Beitrittsberechtigungen erteilen (profile:*, membership:read, membership:request, statuto:accept).

Fehler

Fehlerantworten sind application/problem+json (RFC 9457):

{
  "type": "https://developers.vimine.network/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Missing scope: profile:write",
  "request_id": "…"
}

code ist stabil: Verzweigen Sie danach. errors[] begleitet validation_failed und identification_required ({ field, code }). Ein Eintrag codicefiscale_mismatch — eine Steuernummer, die nicht zu den Geburtsdaten der Person passt — enthält außerdem mismatches, hints und confirmable: Ist confirmable gleich true, darf die Person die Steuernummer bestätigen, und der Antrag wird mit codicefiscale_confirmed: true wiederholt (siehe Mitglieder ohne Steuernummer). Die OAuth-Endpunkte (/v1/oauth/token, /revoke) antworten im OAuth-Format ({ error, error_description }).

code	Bedeutung
missing_token, invalid_token, token_expired	401 — neu anmelden (das SDK erneuert und wiederholt selbst)
insufficient_scope	403 — dem Token fehlt diese Berechtigung
api_disabled	403 — der Verein hat die API nicht aktiviert oder nimmt keine Anträge an
plan_limit	403 — der Tarif des Vereins hat keinen Platz für ein weiteres Mitglied (prüfen Sie aps.accepting_requests, bevor Sie das Formular zeigen)
not_available	403 — der Verein nimmt gerade keine Anträge an: Er hat die Verträge der Plattform noch nicht akzeptiert oder sein Statuto noch nicht hinterlegt, er ist nicht bereit, oder er nimmt nur Personen auf, die er eingeladen hat (die private Beta); detail sagt, was zutrifft. Bei POST /v1/signup: Während der Beta werden Konten auf Einladung angelegt
not_found	404 — auch für Ressourcen anderer Vereine
validation_failed	422 — siehe errors[] (required, invalid, invalid_codicefiscale, codicefiscale_mismatch mit confirmable…)
identification_required	422 bei POST /v1/me/membership, 409 bei POST /v1/enroll/confirm — die Person ist nicht identifiziert: Eine Steuernummer oder Geburtsdatum, Geburtsort und Geburtsland sind nötig; errors[] nennt, was fehlt
statuto_outdated, statuto_required	422 — nennt die geltende Version des Statuto (detail)
rate_limited	429 — Retry-After abwarten
unavailable	503 — in Kürze erneut versuchen

OAuth: invalid_grant (Code oder Refresh-Token ungültig, abgelaufen oder wiederverwendet), invalid_client, invalid_scope, unauthorized_client (Client wartet auf Aktivierung), access_denied (das Mitglied hat abgebrochen).

Im SDK ist all das ein VimineError mit demselben code.

Die private Beta

Vimine ist in einer privaten Beta: Personen und Vereine kommen auf Einladung herein. Für einen Client bedeutet das:

• POST /v1/signup antwortet 403 not_available und legt nichts an, es sei denn, Vimine hat den öffentlichen Beitritt Ihres Vereins geöffnet;
• ein Verein, der nur Personen aufnimmt, die er eingeladen hat, hat aps.invitation_only: true und aps.accepting_requests: false in seinem öffentlichen Profil (association(slug)); POST /v1/enroll und POST /v1/me/membership antworten 403 not_available. Wer eine Einladung hat, tritt über den Link bei, den er per E-Mail erhält;
• die Sandboxes bleiben offen: Test-Clients funktionieren wie immer.

Prüfen Sie aps.accepting_requests, bevor Sie ein Beitrittsformular zeigen — für die Beta wie für alles andere; <vimine-events> und <vimine-enroll> tun das bereits.

Limits

• Pro IP-Adresse: 60 Anfragen/Minute auf den sensiblen Endpunkten (Ausweisprüfung, Steuernummer, Token), 120/Minute auf den übrigen; RateLimit-* und Retry-After in den Antworten.
• POST /v1/me/membership akzeptiert Idempotency-Key: Derselbe Schlüssel innerhalb von 24 Stunden liefert dieselbe Antwort (das SDK erzeugt einen pro Aufruf).
• Authentifizierte Antworten sind Cache-Control: no-store.
• Jede Antwort trägt eine request_id: Nennen Sie sie, wenn Sie ein Problem melden.