Zielgruppe: IT-Dienstleister, CRM-Anbieter und Vereins-Webmaster, die Fairgate-Kontaktdaten automatisiert lesen oder schreiben möchten.

Inhaltsverzeichnis

1. Service buchen

2. API-Zugang einrichten

3. Kontakte abrufen & bearbeiten

4. Zusatzfelder nutzen

5. Änderungen abonnieren

6. Fehlermeldungen & LimitsAnhang – OpenAPI & Ressourcen

1 Service buchen

1.1 Voraussetzungen

• Administrator-Rolle im Fairgate-Backend

1.2 Buchungs-Workflow

1. Melden Sie sich in der Fairgate-Weboberfläche an.

2. Öffnen Sie das Menü Verwaltung › Module & Services.
   

3. Klicken Sie in der Kachel Contacts REST-API (v2.0) auf Jetzt buchen.

4. Bestätigen Sie den Dialog mit OK.

5. Nach wenigen Sekunden erscheint eine Erfolgsmeldung – das Modul ist nun einsatzbereit.

   
   

2 API-Zugang einrichten

2.1 Access-Key & Token-Flow

Nach erfolgreicher Buchung erscheint der Reiter FSA Service › Contacts API unter Einstellungen.

1. API aktivieren – setzen Sie den Schalter auf Aktivier
   

2. API-Token generieren – klicken Sie auf FSA-Zugriffstoken erstellen/bearbeiten.

3. Kopieren Sie

   • (A) OID (Organisation-ID)

   • (B) Access-Key
     
     
     

4. Access-Token abrufen

   curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"access_key":"{{access_key}}"}' \
     https://fsa.fairgate.ch/fsa/v1.1/auth/create/{{oid}}/token

   → Antwort: access_token, refresh_token, expires_in.

5. Token verwenden – senden Sie jeden API-Call mit
   Authorization: Bearer {{access_token}}.

6. Token erneuern –
   POST /fsa/v1.1/auth/refresh/{{oid}}/token.

Hinweis: Wählen Sie beim Zugangstoken Write, falls Sie Kontakte anlegen oder ändern möchten.

3  Kontakte abrufen & bearbeiten

3.1  Überblick Endpunkte (v2)

Hinweis: Bei allen Listen-Abfragen (v1.1 und v2.0) sind die Query-Parameter pageNo und pageLimi obligatorisch. Ohne diese Angaben beantwortet der Server die Anfrage mit 400 Bad Request.

3.2  Beispiel – Liste abrufen

curl -H "Authorization: Bearer {{access_token}}" \
  "https://fsa.fairgate.ch/fsa/v1.1/contact/{{oid}}/contacts?pageNo=1&pageLimit=100"

Antwort enthält totalPages, pageNo, contacts […].

3.3  Beispiel – Kontakt anlegen

curl -X POST -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{
        "contactType":"single_person",
        "first_name":"Max",
        "last_name":"Muster",
        "correspondence_lang":"de"
      }' \
  "https://fsa.fairgate.ch/fsa/v2.0/contact/{{oid}}/data"

4  Zusatzfelder nutzen

4.1  Zusatzfelder aktivieren

1. Öffnen Sie in Fairgate Einstellungen › FSA › Zusatzfelder.

2. Aktivieren Sie die gewünschten Felder für die API.

4.2  Beispiel – Zusatzfelder lesen & schreiben

"configured_fields": {
  "Lizenznummer": "CH‑12345",
  "Hobby": "Klettern"
}

Fügen Sie den Block beim POST/PUT ein – im GET …/extended sind die Werte im gleichen Objekt enthalten.

5  Änderungen abonnieren

5.1  Subscription‑Flow

1. Verfügbare Events abrufen
   GET /fsa/v2.0/subscription/{{oid}}

2. Callback registrieren

   curl -X POST -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
    -d '{"events":["contact.data.updated"],"endpoint":"https://example.com/webhook"}' \
    "https://fsa.fairgate.ch/fsa/v2.0/subscription/{{oid}}/events"

3. Callback muss innerhalb 5 s mit 2xx antworten – sonst Retry.

4. Optional: Job‑API bei Bulk‑Events: /job/{{oid}}/info/{jobId}.

Best Practice: HTTPS, Timeout ≤ 30 s, idempotente Verarbeitung.

6  Fehlermeldungen & Standardcodes

Die OpenAPI‑Spezifikation der Contacts API nennt explizit folgende HTTP‑Antworten:

Hinweis: Allfällige Rate‑Limiting‑Antworten (z. B. 429 Too Many Requests) sind Server‑seitig möglich, aber nicht Teil der offiziellen Spezifikation. Bitte beobachten Sie die Response‑Header Ihres Clients, falls Ihr Integrations‑Szenario sehr viele Aufrufe pro Minute generiert.

Weiterführende Ressourcen

• Technische Dokumenation: https://fsa.fairgate.ch/docs/fsa_openapi3