Server-Integrationen

Für die Systeme des Vereins selbst — eine Verwaltungssoftware, ein Drehkreuz, ein CMS-Plugin — ein vertraulicher Client mit client_id + client_secret. Das Secret wird einmal angezeigt und darf nie in einen Browser gelangen.

Authentifizieren

Node

import { VimineServer } from '@vimine/sdk/server';

const vimineServer = new VimineServer({
    clientId: 'vmc_…',
    clientSecret: process.env.VIMINE_SECRET,
    scopes: ['memberships:read']
});
const token = await vimineServer.token();      // client_credentials — Token für 1 Stunde, erneuert sich selbst

Ohne das SDK: POST /v1/oauth/token mit grant_type=client_credentials und HTTP Basic client_id:client_secret (oder client_id/client_secret im Body):

curl -u "vmc_…:vms_…" -d "grant_type=client_credentials&scope=memberships:read" \
     https://api.vimine.network/v1/oauth/token

Bei den lesenden Endpunkten (/v1/memberships/{id}/status, /v1/memberships) wird HTTP Basic auch direkt akzeptiert, ohne den Umweg über ein Token, für Hardware und Low-Code-Plattformen — nie aus einem Browser.

Status eines Ausweises

const s = await vimineServer.memberships.status('membership-uuid');
// { id, status: 'active', verdict: 'valid', valid_until: '2027-…', membership_type: { cod: 'ORD' } }

Keine personenbezogenen Daten: nur Status und Gültigkeit. Die id ist die, die das Mitglied auf seinem eigenen Ausweis sieht (membership.id über Mit Vimine anmelden), oder die, die Ihr System bei der Erfassung erhalten hat.

Um einen am Einlass gezeigten Ausweis zu prüfen, verwenden Sie stattdessen das QR-Token mit /v1/verify/{card_token}: Es braucht überhaupt keine Authentifizierung.

Beitritte aus Ihrem System

Mit identity:signup und enroll:write kann Ihr Backoffice Konten anlegen und Beitrittsanträge stellen, ohne dass die Person über Vimine geht: Sie erhält per E-Mail den Link, um die Adresse zu bestätigen und ein Passwort zu wählen.

// Nur das Konto (die Person ist noch nicht Mitglied)
await vimineServer.signup({ email: 'mario.rossi@example.org', first_name: 'Mario', last_name: 'Rossi' });

// Konto + ausstehender Beitrittsantrag, den das Sekretariat in der Vimine-Verwaltung genehmigt
const { statuto, membership_types } = await vimineServer.public.association('your-slug');
await vimineServer.enroll({
    email: 'mario.rossi@example.org',
    first_name: 'Mario',
    last_name: 'Rossi',
    codicefiscale: 'RSSMRA80A01H501U',      // optional: ohne sie sind dob + birthplace + birth_country nötig
    dob: '1980-01-01', birthplace: 'Roma', birth_country: 'IT',
    gender: 'M',                              // nur statistisch: wird nicht mit der Steuernummer abgeglichen
    membership_type: membership_types[0].uid, // optional, wenn es genau eine Art gibt
    accept_statuto: { version: statuto.version, sha256: statuto.sha256 },
    privacy_notice: privacy_notice && { version: privacy_notice.version, sha256: privacy_notice.sha256 } // Pflicht, wenn der Verein Datenschutzhinweise veröffentlicht
});

Die Antwort ist immer 202 { status: 'accepted' }, was auch immer hinter der Adresse steht: Sie können nicht erfahren, ob eine E-Mail-Adresse schon ein Vimine-Konto hat (nur ihr Inhaber erfährt es, per E-Mail). Im Einzelnen:

• neue Adresse → Konto angelegt und, mit enroll, ein ausstehender Beitrittsantrag; Willkommens-E-Mail mit der Bestätigung der Adresse;
• bereits registrierte Adresse → mit enroll wird nichts geschrieben: Der Inhaber erhält einen Link „Bestätigen Sie Ihren Antrag an “, 24 Stunden gültig, und der Antrag entsteht erst, wenn er ihn verwendet. Ist er bereits Mitglied, geschieht nichts;
• 422-Fehler betreffen nur Ihre Nutzdaten (validation_failed mit errors[].field, statuto_outdated, invalid_type); 403 api_disabled, wenn der Verein keine Anträge annimmt; 403 not_available während der privaten Beta, solange Konten nur auf Einladung angelegt werden.

Eine Person wird über eine Steuernummer oder über Geburtsdatum, Geburtsort und Geburtsland (dob, birthplace, birth_country) identifiziert — nie über keins von beidem: Ohne Steuernummer ist jede fehlende Geburtsangabe ein Eintrag required in errors[]. Für eine im Ausland geborene Person senden Sie immer birth_country: Ihre Steuernummer enthält nur den Staat. Eine Steuernummer, die nicht zu den Geburtsdaten passt, ergibt 422 mit einem Eintrag codicefiscale_mismatch, der mismatches, hints und confirmable enthält: Ist confirmable gleich true, darf die Person sie bestätigen, und Sie wiederholen den Aufruf mit codicefiscale_confirmed: true. Wenn der Verein die Adresse seiner Mitglieder erfasst (aps.member_address im öffentlichen Profil), fügen Sie address hinzu. Wenn er die Daten der sorgeberechtigten Person erfasst (aps.collects_guardian_data) und die Person laut dob minderjährig ist, ist guardian Pflicht — first_name, last_name, relation, optional codicefiscale, email, phone — sonst 422 mit guardian: required. Der ganze Weg steht in Mitglieder ohne Steuernummer.

accept_statuto muss das geltende Statuto nennen: Zeigen Sie es der Person auf Ihrer Website (es steht in association(slug); Text und Dokument unter GET /v1/aps/{slug}/statuto) und übergeben Sie die Version, die sie akzeptiert hat. Ein Verein, der kein lesbares Statuto hinterlegt hat, antwortet mit accepting_requests: false, und der Antrag mit 403 not_available. Dasselbe gilt für die Datenschutzhinweise des Vereins für seine Mitglieder (privacy_notice in association(slug), der Text unter GET /v1/aps/{slug}/privacy-notice): Wenn der Verein welche veröffentlicht, muss der Antrag die Version nennen, die die Person gelesen hat, sonst 422 (privacy_notice fehlt oder privacy_notice_outdated); die Kenntnisnahme wird im Namen der Person erfasst, unter Nennung Ihres Clients. Optional, nach derselben Regel: accept_terms und acknowledge_privacy (die Nutzungsbedingungen des Kontos und die Datenschutzerklärung der Plattform, GET /v1/legal/{kind}), wenn die Person sie auf Ihrer Website akzeptiert hat. Die Aufrufe sind idempotent: Das SDK erzeugt pro Aufruf einen Idempotency-Key, oder Sie übergeben Ihren eigenen ({ idempotencyKey: 'order-42' }), um nach einem Timeout gefahrlos zu wiederholen. E-Mails sind kontingentiert (3 pro Adresse und Tag) und werden aus der Sandbox nie versendet.

Check-ins am Einlass

Mit checkins:write erfasst ein Gerät am Eingang den Durchgang eines Mitglieds, indem es das aus dem QR-Code des Ausweises gelesene Token sendet (keine Kennung): Die Antwort ist allein das Ergebnis, keine personenbezogenen Daten. HTTP Basic wird direkt akzeptiert, für Hardware und Low-Code-Plattformen.

const r = await vimineServer.checkins.create('vmt_…');   // { verdict: 'valid' | 'expired' | 'not_yet_valid' | 'statuto_required' | 'inactive', status, membership_id, valid_until, identity_check, checked_in_at }

curl -u "vmc_…:vms_…" -H "Content-Type: application/json" -d '{"token":"vmt_…"}' https://api.vimine.network/v1/checkins

Der Body ist { "token": "vmt_…" } — das aus dem QR-Code gelesene Token, eines Ausweises oder einer Veranstaltungsanmeldung; nur bei Ausweisen wird card als Alias akzeptiert.

Ein fehlerhaftes oder gefälschtes Token ergibt 422 invalid_card; der Ausweis eines anderen Vereins ist „nicht gefunden“.

identity_check: 'pending' ist ein Hinweis für die Person am Einlass: Das Mitglied hat keine prüfbare Steuernummer, und noch niemand aus dem Verein hat ein Ausweisdokument angesehen. Zeigen Sie ihn an; er ist nicht Teil von verdict und schränkt nichts ein (siehe die Identitätsprüfung).

Mitgliedschaften auflisten (Tarife Pro und Network)

vimineServer.memberships.list({ status?, updated_since?, limit?, cursor? }) liefert IDs, Status und Daten — nie personenbezogene Daten — seitenweise (next_cursor). Mit updated_since synchronisieren Sie nur, was sich geändert hat. In Tarifen, die das nicht enthalten, lautet die Antwort 403 plan_limit.

Rotation des Secrets

In der Konsole (Secret erneuern): Das neue Secret wird einmal angezeigt, das bisherige funktioniert noch 24 Stunden, sodass Sie Ihre Systeme ohne Ausfall umstellen können. Wenn Sie eine Kompromittierung vermuten, widerrufen Sie den Client: Alle seine Sitzungen enden sofort.

Sicherheit

• Ein wiederholt falsches Secret sperrt den Client für 15 Minuten aus.
• Jedes Token ist an den Verein des Clients gebunden: Ein Ausweis eines anderen Vereins ist schlicht „nicht gefunden“.
• Ein 401 mit gerade rotierten Zugangsdaten wiederholt das SDK einmal mit einem frischen Token.
• Antworten verwenden application/problem+json (siehe Berechtigungen, Fehler und Limits).