REST-API: Testmodus
Ein Test-Key arbeitet in einem Testbüro mit erfundenen Daten. Nichts verlässt Athaus außer Webhooks an deine eigenen Adressen.
Zuletzt aktualisiert:
Mit einem Test-Key baust du gegen /v1, ohne ein echtes Büro, einen Anfragenden oder ein Portal zu berühren. Er sieht aus wie ein Live-Key und heißt ath_test_....
Authorization: Bearer ath_test_...Das Testbüro
Jedes Büro hat höchstens ein Testbüro: eine eigene Organisation mit eigenen Daten, die auf das echte Büro zeigt. Es entsteht mit dem ersten Test-Key. Ein Test-Key führt immer ins Testbüro, nie ins echte, und das echte Büro sieht nichts davon.
Ein neues Testbüro beginnt mit erfundenen Daten:
| Was | Wie viele |
|---|---|
| Inserate (Wohnung zum Kauf, Wohnung zur Miete, Haus) | 3 |
| Kontakte | 5 |
| Anfragen | 2 |
| Besichtigung | 1 |
| Datei (ein kleines erzeugtes Bild) | 1 |
Die Straßen heißen Musterstraße, die Adressen enden auf example.com. GET /v1/me liefert key.mode als test und die Id des Testbüros.
Einen Test-Key anlegen
Wähle unter Einstellungen, API-Keys beim Key-Typ Test. Scopes und die Einschränkung je Ressource funktionieren wie bei einem Live-Key, ebenso die Regel, wer Keys anlegen darf. Der Tarif des echten Büros entscheidet: Pro und Scale gehen, in Basic antwortet die API plan_required.
Ein Test-Key arbeitet nur bei /v1, nicht am MCP-Server und nicht in der App. Er zählt nicht gegen die Anbindungen deines Tarifs, aber ein Büro hat höchstens 10 gültige Test-Keys gleichzeitig: Der elfte wird beim Anlegen in der App mit test_key_limit_erreicht beantwortet. Das Testbüro ist in der App nicht sichtbar.
Nichts verlässt Athaus
Im Testbüro geht keine E-Mail, keine SMS und keine andere Nachricht hinaus. Kein Portal bekommt etwas, kein angebundenes CRM wird beschrieben, kein Inserat wird öffentlich. Auch läuft kein KI-Modell.
Eine Nachricht, die du an eine Anfrage schickst, steht dann im Verlauf als gesendet, mit dem Vermerk, dass sie im Testmodus nicht zugestellt wurde. Der Vorschlag endet als executed.
Webhooks laufen weiter: Die Endpunkte eines Test-Keys gehören zum Testbüro, bekommen seine Ereignisse und werden genauso signiert, du kannst also deinen Empfänger testen. Fällt ein Endpunkt dauerhaft aus, wird er wie jeder andere abgeschaltet (disabledReason, disabledAt); dazu geht keine E-Mail hinaus.
Ereignisse unterscheiden
Jedes Ereignis trägt livemode: true für das echte Büro, false für das Testbüro. Ein Vorschlag trägt dasselbe Mitglied.
{ "object": "event", "type": "proposal.pending", "livemode": false }Vorschläge über die API entscheiden
In einem echten Büro sagt eine Person in der App Ja oder Nein, oder ein Key mit dem Scope decide. Im Testbüro ist niemand, darum gibt es zwei Pfade, die ein Test-Key ohne diesen Scope nutzt:
| Pfad | Wirkung |
|---|---|
POST /v1/proposals/{id}/approve | Ja: Die Nachricht steht im Verlauf als gesendet, der Vorschlag ist executed |
POST /v1/proposals/{id}/reject | Nein: Nichts wird gesendet, der Vorschlag ist rejected |
So spielst du "202 mit einem Vorschlag, dann Ja" ohne die App durch (Was das Büro verlässt). Ein Live-Key braucht dafür den Scope decide, sonst 403 (Ohne Person entscheiden). Auch hier siehst du nur die Vorschläge deines eigenen Keys.
Zurücksetzen
POST /v1/test/reset stellt die Beispieldaten wieder her. Alles andere im Testbüro verschwindet, auch die alten Ereignisse. Die Beispieldaten selbst melden keine Ereignisse: Dein Empfänger bekommt keine Flut von created-Ereignissen, nur was du danach anlegst oder änderst. Webhook-Endpunkte und Keys bleiben, und das Testbüro behält seine Id. Der Key braucht Schreibzugriff auf alle Ressourcen. Mit einem Live-Key: 404.
Grenzen
Es gelten dieselben Grenzen wie bei Live-Keys. Das Testbüro ist zusätzlich gedeckelt, damit es kein Speicher wird: 200 Inserate, 1.000 Kontakte und 100 MB Dateien. Darüber antwortet die API mit 403 und test_office_full. Zurücksetzen schafft wieder Platz.
Was schiefgehen kann
| Status | Code | Ursache |
|---|---|---|
403 | test_office_full | das Testbüro hat seine Grenze erreicht |
409 | test_office_busy | das Testbüro wird gerade aufgebaut oder zurückgesetzt |
403 | plan_required | der Tarif des echten Büros hat keinen API-Zugang |
404 | not_found | Zurücksetzen oder Entscheiden mit einem Live-Key |
Weiter lesen
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
API-Key anlegen und Scopes wählen
Ein API-Key für die REST-API, eigene Agenten und Dienste, mit genau den Scopes, die du ihm gibst.
REST-API: was das Büro verlässt
Anfragenden antworten und nachfassen. Wann eine Nachricht sofort hinausgeht, wann ein Vorschlag auf ein Ja wartet (202) und wie du das Ergebnis liest.
REST-API: Webhooks
Ereignisse an eine Adresse deines Systems: einrichten, die Signatur prüfen, Wiederholungen verstehen, das Secret wechseln.
REST-API: Ereignisse
Was im Büro geschah, 30 Tage lang abrufbar. Dieselben Ereignisse, die an Webhooks gehen, gefiltert nach Typ und Zeit.
Ausgehende Nachrichten
Anfragenden antworten und nachfassen. Wann eine Nachricht sofort hinausgeht, wann ein Vorschlag auf ein Ja wartet (202) und wie du das Ergebnis liest.
Webhooks
Ereignisse an eine Adresse deines Systems: einrichten, die Signatur prüfen, Wiederholungen verstehen, das Secret wechseln.