> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ardoiseeduc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Öffentliche API

> Den Ardoise-Marketplace (Schulen, Tutoren, Stellenangebote) in Ihre eigene Website oder Ihr eigenes System integrieren.

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.

<Info>
  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.
</Info>

## Einen Schlüssel erhalten

<Steps>
  <Step title="Erstellen Sie ein Entwicklerkonto">
    Registrieren Sie sich auf [saas.ardoiseeduc.com](https://saas.ardoiseeduc.com/register) mit der Rolle **Entwickler**.
  </Step>

  <Step title="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_...`).
  </Step>

  <Step title="Authentifizieren Sie Ihre Anfragen">
    Senden Sie den Schlüssel im `Authorization`-Header jeder Anfrage:

    ```bash theme={null}
    curl -H "Authorization: Bearer sk_live_..." https://api.ardoiseeduc.com/api/public/schools
    ```
  </Step>
</Steps>

<Note>
  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](#schul-api-schlüssel-scope-schoolprofile) weiter unten.
</Note>

## 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](/de/plateforme/partenaires-certifies#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](#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](/de/plateforme/partenaires-certifies) - 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 |

<Tip>
  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.
</Tip>

## Endpoints

<Note>
  Base URL: `https://api.ardoiseeduc.com`
</Note>

### `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](#verfügbare-länder) - optional, sonst das erlaubte Land |
| `limit` | Maximale Anzahl der Ergebnisse (Standard 50, max. 200) |

```json theme={null}
{
  "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`.

<Note>
  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.
</Note>

### `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](/de/plateforme/partenaires-certifies) auf, filterbar nach `country`.

**Erforderliche Berechtigung:** `marketplace:read`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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](/de/plateforme/partenaires-certifies), 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`

```json theme={null}
{ "status": "ok" }
```

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

```json theme={null}
{
  "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": "..." }`.

<Warning>
  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).
</Warning>

## 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.

<Warning>
  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.
</Warning>

## 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

<CardGroup cols={2}>
  <Card title="MCP-Server" icon="plug" href="/de/plateforme/mcp">
    Dieselben öffentlichen Funktionen mit einem Model-Context-Protocol-Client verwenden.
  </Card>

  <Card title="Zertifizierte Partner" icon="user-check" href="/de/plateforme/partenaires-certifies">
    Zertifizierter Partner werden oder einem Partner von Ihrer Schule aus Support-Zugriff gewähren.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.