Sandbox (Testmodus)

Mit der Sandbox probieren Sie die API aus, ohne Ihre echten Daten zu berühren. Sie ist eine eigene Test-Organisation mit erfundenen Musterdaten; Test-Tokens sehen ausschließlich diese Daten — nie Ihre echten, und echte Tokens sehen nie die Sandbox. Die Trennung sichert die Datenbank, nicht nur die Anwendung.

In vier Schritten zur ersten Antwort

So starten Sie

Unter Administration → API-Zugänge → Sandbox die Sandbox anlegen (Recht „API-Zugänge: Vollzugriff“, höchstens eine je Organisation) und ein Test-Token erzeugen. Sie gehört zum Zusatzmodul „API-Zugänge“ und ist nur nutzbar, solange der API-Zugang aktiv ist (kostenlose Testzeit oder Buchung); die Nutzung in der Testzeit ist keine Buchung und ändert keine Preise. Ohne aktiven Zugang lässt sich keine Sandbox anlegen, und eine bestehende ist gesperrt: Ein gültiges Test-Token erhält dann `403 sandbox_unavailable` mit Hinweis auf das Zusatzmodul (ein ungültiges Token weiter `401`); mit aktivem Zugang funktioniert dasselbe Token wieder.

curl -H "Authorization: Bearer m2h_test_…" https://api.manage2hero.com/v1/locations

Die Adresse ist dieselbe wie für echte Tokens. Die Sandbox erkennen Sie am Präfix m2h_test_ des Tokens und am Antwortkopf X-M2H-Sandbox: true, den jede Antwort auf ein Test-Token trägt. Test-Tokens gelten in jeder Umgebung (Produktion, Staging, Entwicklung); die Sandbox liegt jeweils in der Datenbank der Umgebung.

Was die Sandbox enthält

Eine Firma, zwei Standorte, drei Garagentypen, 20 Einheiten (zwölf vermietet, zwei reserviert, eine gesperrt, fünf frei), zwölf Mieter und zwölf laufende Verträge. Alle Namen und Adressen sind erfunden; E-Mail-Adressen enden auf @sandbox.invalid (nie zustellbar), Telefonnummern gibt es nicht (bei Interessenten steht eine Platzhalternummer).

Dazu kommen die Daten, die die Lese-Endpunkte zeigen: je Vertrag drei Monatsmieten (Konditionen, Buchungen, offene Posten; drei Mieter sind im Rückstand), 27 Zahlungseingänge mit Zuordnung zu den Mieten, drei Rechnungen (offen, bezahlt, teilbezahlt), drei Mahnungen (Stufe 1 und 2), sechs Stromzähler mit je drei Zählerständen, zwei Schadensfälle und zwei Mietermeldungen, zwei allgemeine Termine und zwei Übergaben, drei Interessenten, vier Dokumente (nur Metadaten, ohne Datei) und sechs Einträge im E-Mail-Verlauf (nur Protokollzeilen, es wird nichts gesendet). Die Bankverbindung ist eine Beispiel-IBAN aus der öffentlichen Dokumentation, keine Anbindung. Das Zurücksetzen stellt diese Daten wieder her; eine schon bestehende Sandbox zeigt sie nach dem nächsten Zurücksetzen.

Was die Sandbox nicht tut

Aus der Sandbox gehen keine E-Mails hinaus — auch nicht über das Systempostfach. Es gibt keine echten Zahlungen (die Zahlungseingänge sind erfundene Beispiele), keine Bankanbindung und keine echten Dokumente.

Webhooks in der Sandbox

Ein Test-Token darf den Scope webhooks:manage tragen. Sandbox-Webhooks laufen über denselben Zustelldienst wie echte: signierter POST, Wiederholungen, Selbstabschaltung nach sechs Fehlversuchen, Replay und Pausieren, nur https auf Port 443 an öffentliche Adressen (derselbe Schutz gegen Zugriffe auf interne Adressen). Jede Nachricht trägt "livemode": false im Körper und den Kopf X-M2H-Livemode: false (echte Ereignisse: true), damit Test- und echte Ereignisse nie verwechselt werden. Zugestellt wird nur bei aktivem API-Zugang der Organisation. Gesendet wird, wie bei echten Webhooks, nur von der Produktion; in Entwicklung und Staging bleiben die Zustellungen wartend.

Ein Ereignis lösen Sie ohne echte Buchung mit POST /v1/sandbox/events aus (Body { "type": "payment.received" }, Idempotency-Key Pflicht): Es wird für ein Musterobjekt der Sandbox eingestellt und an Ihre aktiven, den Typ abonnierenden Webhooks gesendet. Der Verlauf steht in GET /v1/webhooks/{id}/deliveries. Mit einem echten Token gibt es diesen Aufruf nicht (404).

Die Antwort nennt die Ereignis-Kennung, das gewählte Musterobjekt, an wie viele Webhooks das Ereignis ging (recipients, queued) und ob dieser Server sendet (delivery: enabled in der Produktion, not_in_this_environment in Entwicklung und Staging). Wiederholen Sie den Aufruf mit demselben Idempotency-Key, kommt dieselbe Antwort, und es wird nichts doppelt eingestellt.

{
  "data": {
    "event_id": "6f1d3c52-8b0e-4a67-9c21-3d5e7a90b4f8",
    "event_type": "payment.received",
    "object_id": "b2a4c6e8-1f3d-4b5a-8c7e-9d0f1a2b3c4d",
    "recipients": 2,
    "queued": 2,
    "delivery": "enabled"
  }
}

curl -X POST https://api.manage2hero.com/v1/sandbox/events \
  -H "Authorization: Bearer m2h_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type":"payment.received"}'

Unterschiede zu echten Daten

Typische Fehlerbilder

Grenzen und Aufbewahrung

„Zurücksetzen“ in der Verwaltung ersetzt die Sandbox durch eine frische mit neuen Musterdaten (selbst angelegte Daten gehen verloren); Ihre aktiven Test-Tokens bleiben gültig und arbeiten danach in der neuen Sandbox. Ist die Sandbox abgelaufen, legt „Neue Sandbox anlegen“ in der Verwaltung eine frische an; die Test-Tokens der alten gelten dann nicht mehr. Der Betreiber-Not-Aus Ihrer Organisation sperrt auch die Sandbox. Anlegen und Widerrufen von Test-Tokens stehen im Aktivitätsprotokoll Ihrer Organisation.