Öffentliche API

Die öffentliche API ermöglicht einer Integration freigegebene öffentliche Profile und zulässige Kontaktübermittlung mit einem autorisierten Kontoschlüssel. Der Client benötigt weder Firebase-SDK noch eine Nutzersitzung pro Aufruf; der Schlüsselinhaber braucht weiterhin ein Konto und muss Berechtigungen/Land beachten.

Veröffentlichte Profilfelder unterliegen den Länder- und Berechtigungsprüfungen des Schlüssels. Private Daten und nicht veröffentlichte Kontaktdaten bleiben ausgeschlossen. Verwenden Sie diesen Serverzugang mit widerrufbaren Schlüsseln und Nutzungsverfolgung; gehen Sie nicht von anonymem oder direktem Firestore-Zugriff aus.

Einen Schlüssel erhalten

Erstellen Sie ein Entwicklerkonto

Registrieren Sie sich auf saas.ardoiseeduc.com mit der Rolle Entwickler.

Generieren Sie einen Schlüssel

Im Entwicklerbereich, Abschnitt API-Schlüssel: Wählen Sie die benötigten Berechtigungen (Scopes) aus und generieren Sie dann einen Test-Schlüssel (sk_test_...) oder einen Produktions-Schlüssel (sk_live_...).

Authentifizieren Sie Ihre Anfragen

Senden Sie den Schlüssel im Authorization-Header jeder Anfrage:

curl -H "Authorization: Bearer sk_live_..." https://api.ardoiseeduc.com/api/public/schools

Eine Schule, die ihr eigenes Profil oder ihre eigenen Stellenangebote auf ihrer Website anzeigen möchte, braucht kein Entwicklerkonto: Der Gründer generiert einen dedizierten Schlüssel über API-Integrationen in seinem Dashboard - siehe Schul-API-Schlüssel weiter unten.

Berechtigungen (Scopes)

Ein Produktionsschlüssel setzt Identitätsprüfung, technische Zertifizierung und Partnerfreigabe im Entwicklerablauf voraus. Ein Testschlüssel für die Sandbox berechtigt nicht zum Produktionszugriff. Siehe Developer Academy und Zertifizierung.

Scope	Gewährt Zugriff auf
`marketplace:read`	Lesen der veröffentlichten Schulen, Tutoren, Stellenangebote und zertifizierten Partner, filterbar nach Land (siehe Verfügbare Länder)
`leads:write`	Übermittlung eines Leads (Schule oder Kandidat) an das Ardoise-CRM
`school:profile`	Lesen des Profils einer einzigen Schule (von dieser Schule selbst generierter Schlüssel)
`support:access`	Vorbehalten für zertifizierte Partner - Zugriff auf den Server-/Backup-Status einer Schule, die diesen Zugriff ausdrücklich gewährt hat

Ein ungültiger, widerrufener oder nicht mit der erforderlichen Berechtigung ausgestatteter Schlüssel erhält 401/403 mit einer Meldung, die erläutert, welcher Fall vorliegt.

Verfügbare Länder

Der Parameter country akzeptiert Code oder exakten französischen Namen. Entwicklerschlüssel sind serverseitig an das erlaubte Land gebunden. Ohne Parameter bleibt dieser Umfang bestehen; andere Länder oder fremde Profilkennungen werden abgelehnt. Die Liste ist eine technische Referenz, kein Beleg für sämtliche Angebote/Zahlungen. Ardoise School wird in Österreich nicht angeboten.

Code	Land
`BEN`	Benin
`BFA`	Burkina Faso
`CMR`	Kamerun
`CAF`	Zentralafrikanische Republik
`COM`	Komoren
`COG`	Kongo
`COD`	DR Kongo
`CIV`	Côte d’Ivoire
`GAB`	Gabun
`GIN`	Guinea
`GNB`	Guinea-Bissau
`GNQ`	Äquatorialguinea
`MLI`	Mali
`NER`	Niger
`SEN`	Senegal
`TCD`	Tschad
`TGO`	Togo
`AUT`	Österreich

Diese Liste ist auch per API verfügbar (siehe GET /api/public/countries weiter unten) - praktisch, um eine Länderauswahl zu bauen, ohne sie von Hand abzuschreiben.

Endpoints

Base URL: https://api.ardoiseeduc.com

`GET /api/public/countries`

Gibt die Liste der 18 oben genannten Länder zurück ({ "data": [{ "code": "BEN", "name": "Bénin" }, ...] }). Kein Schlüssel erforderlich - dies sind statische Referenzdaten, keine Marketplace-Daten.

`GET /api/public/schools`

Listet die auf dem Marketplace registrierten Schulen auf. Erforderliche Berechtigung: marketplace:read

Parameter	Beschreibung
`country`	Code oder französischer Name - siehe Verfügbare Länder - optional, sonst das erlaubte Land
`limit`	Maximale Anzahl der Ergebnisse (Standard 50, max. 200)

{
  "data": [
    { "id": "abc123", "name": "École Les Palmiers", "city": "Cotonou", "country": "Bénin", "description": "...", "image": "https://..." }
  ]
}

`GET /api/public/schools/:schoolId`

Öffentliches Einrichtungsprofil im erlaubten Land eines marketplace:read-Schlüssels oder der bestimmten Einrichtung eines school:profile-Schlüssels. Auch die angefragte Kennung wird auf das Land geprüft; Institute verwenden öffentliche Profile, ohne School-Mandanten zu werden.

`GET /api/public/teachers`

Listet die unabhängigen Tutoren des Marketplace auf. Gleiche Parameter country/limit wie /schools.

Diese Route liefert freigegebene öffentliche Felder, keine privaten Kontaktdaten, Verträge oder Finanzakten. Kontakt und Buchung verwenden erlaubte Abläufe; Marketplace-Gebühren und Zahlungen lassen sich nicht aus diesem öffentlichen Ergebnis ableiten.

`GET /api/public/jobs`

Listet die offenen Stellenangebote auf, filterbar nach country und/oder schoolId. Erforderliche Berechtigung: marketplace:read

`GET /api/public/partners`

Listet die genehmigten zertifizierten Partner auf, filterbar nach country. Erforderliche Berechtigung: marketplace:read

{
  "data": [
    { "id": "uid123", "publicName": "Jean Dupont", "bio": "...", "specialties": ["Installation", "Maintenance serveur"], "country": "Bénin" }
  ]
}

`POST /api/public/leads`

Übermittelt einen Lead (interessierte Schule oder Lehrerkandidat) in die Vertriebspipeline von Ardoise, damit ein Teammitglied Kontakt aufnimmt. Erforderliche Berechtigung: leads:write

{
  "type": "school_prospect",
  "name": "Jean Dupont",
  "contactEmail": "jean@example.com",
  "contactPhone": "+229 90 00 00 00",
  "country": "Bénin",
  "message": "Intéressé par une démo pour notre établissement."
}

type ist entweder school_prospect oder candidate. name ist erforderlich, ebenso contactEmail oder contactPhone (mindestens eines von beiden).

Support-Zugriff (Scope `support:access`)

Vorbehalten für zertifizierte Partner, denen ein Gründer ausdrücklich Zugriff gewährt hat - siehe diese Seite dazu, wie ein Gründer diesen Zugriff über sein Dashboard gewährt bzw. widerruft. Diese Routen leiten als Proxy zur Django-Installation der Schule selbst weiter (niemals zu auf der Plattform gespeicherten Daten) und antworten mit 403, wenn kein aktiver Zugriff die Schule oder die angeforderte Berechtigung abdeckt. Erforderliche Berechtigung: support:access

`GET /api/support/schools/:schoolId/health`

{ "status": "ok" }

`GET /api/support/schools/:schoolId/backupStatus`

{
  "isConfigured": true,
  "isEnabled": true,
  "lastBackup": { "status": "success", "date": "2026-07-28T02:00:00Z", "error": null }
}

`POST /api/support/schools/:schoolId/backupTrigger`

Löst eine sofortige Sicherung aus. Antwort { "success": true, "message": "..." } oder { "success": false, "error": "..." }.

Diese drei Routen sind strikt auf den Server- und Backup-Status beschränkt - niemals auf Noten, Buchhaltung oder Schülerakten - und öffnen keinerlei Systemzugriff auf die Maschine (weder SSH noch Konsole).

Schul-API-Schlüssel (Scope `school:profile`)

Über API-Integrationen im Gründer-Dashboard kann eine Schule ihren eigenen Schlüssel generieren, beschränkt auf ihr eigenes Profil (GET /api/public/schools/:sonPropreId) und ihre eigenen Stellenangebote. Dieser Schlüssel kann nichts von einer anderen Schule lesen und gewährt keinen Zugriff auf Noten-, Finanz- oder Schülerdaten - ausschließlich auf dieselben Informationen, die auf dem Marketplace bereits öffentlich sind.

Die öffentliche API stellt keine Noten, Buchhaltung oder Schülerakten einer Schule bereit und wird dies ohne einen deutlich umfassenderen Einwilligungsrahmen als diese Schlüssel auch nicht tun - das ist keine vorübergehende Auslassung, sondern eine bewusste Grenze.

Aktuelle Einschränkungen

Keine strikte Ratenbegrenzung (noch keine dedizierte Infrastruktur) - missbräuchliche Nutzung wird über den im Entwicklerbereich angezeigten Anfragenzähler überwacht, und ein Schlüssel kann jederzeit widerrufen werden.
Webhooks (Echtzeit-Benachrichtigungen) können im Entwicklerbereich konfiguriert werden, werden aber noch nicht automatisch bei realen Ereignissen ausgelöst - derzeit funktioniert nur der manuelle Test.

Siehe auch

MCP-Server

Dieselben öffentlichen Funktionen mit einem Model-Context-Protocol-Client verwenden.

Zertifizierte Partner

Zertifizierter Partner werden oder einem Partner von Ihrer Schule aus Support-Zugriff gewähren.

Konto und Aktivierung

Integrationen & API

Partner

Einen Schlüssel erhalten

Berechtigungen (Scopes)

Verfügbare Länder

Endpoints

`GET /api/public/countries`

`GET /api/public/schools`

`GET /api/public/schools/:schoolId`

`GET /api/public/teachers`

`GET /api/public/jobs`

`GET /api/public/partners`

`POST /api/public/leads`

Support-Zugriff (Scope `support:access`)

`GET /api/support/schools/:schoolId/health`

`GET /api/support/schools/:schoolId/backupStatus`

`POST /api/support/schools/:schoolId/backupTrigger`

Schul-API-Schlüssel (Scope `school:profile`)

Aktuelle Einschränkungen

Siehe auch

MCP-Server

Zertifizierte Partner

​Einen Schlüssel erhalten

​Berechtigungen (Scopes)

​Verfügbare Länder

​Endpoints

​GET /api/public/countries

​GET /api/public/schools

​GET /api/public/schools/:schoolId

​GET /api/public/teachers

​GET /api/public/jobs

​GET /api/public/partners

​POST /api/public/leads

​Support-Zugriff (Scope support:access)

​GET /api/support/schools/:schoolId/health

​GET /api/support/schools/:schoolId/backupStatus

​POST /api/support/schools/:schoolId/backupTrigger

​Schul-API-Schlüssel (Scope school:profile)

​Aktuelle Einschränkungen

​Siehe auch

MCP-Server

Zertifizierte Partner

Einen Schlüssel erhalten

Berechtigungen (Scopes)

Verfügbare Länder

Endpoints

`GET /api/public/countries`

`GET /api/public/schools`

`GET /api/public/schools/:schoolId`

`GET /api/public/teachers`

`GET /api/public/jobs`

`GET /api/public/partners`

`POST /api/public/leads`

Support-Zugriff (Scope `support:access`)

`GET /api/support/schools/:schoolId/health`

`GET /api/support/schools/:schoolId/backupStatus`

`POST /api/support/schools/:schoolId/backupTrigger`

Schul-API-Schlüssel (Scope `school:profile`)

Aktuelle Einschränkungen

Siehe auch