Testumgebungen (Sandbox)

Isolieren Sie Ihre Entwicklung, experimentieren Sie ohne Risiko und bereinigen Sie Ihre Daten mit einem Klick.

Warum Testumgebungen?

Bei der Integration von Finanz-APIs ist es entscheidend, die Logik Ihrer Anwendung zu testen, ohne echte Transaktionen auszulösen oder E-Mails an echte Kunden zu senden. Cord löst das mit einer vollständig isolierten Testumgebung (Sandbox).

Im Testmodus erstellte Daten (Angebote, Kunden, Webhooks) kommen nie mit Ihren Live-Daten in Berührung.

Den Testmodus erkennen

Im Dashboard: Wenn der Testmodus aktiv ist, sehen Sie in der Oberfläche eine orangefarbene Markierung. Alle manuellen Aktionen, die Sie ausführen, finden in der isolierten Umgebung statt.
In der API: Ihre geheimen API-Schlüssel bestimmen automatisch, welche Umgebung Sie aufrufen. Ein Testschlüssel arbeitet mit der Testumgebung, ein Live-Schlüssel mit Ihren echten Daten.

Wichtig: Verwenden Sie in Ihren Unit- oder Integrationstests niemals echte Schlüssel.

Schnelles Zurücksetzen (Sandbox-Reset)

Bei der Entwicklung von Integrationen entstehen oft Tausende unbrauchbarer Datensätze. Cord bietet ein konsequentes Werkzeug, um Ihre Umgebung wieder in einen sauberen Zustand zu versetzen: den Reset-Endpoint.

Daten der Testumgebung leeren

Sie können eine destruktive Bereinigung auslösen (die Kunden, Angebote, Produkte und Ereignisse der Testumgebung kaskadierend löscht), indem Sie einen POST an den folgenden internen Endpoint senden (erfordert eine aktive Browsersitzung im Testmodus):

POST /api/test-mode/reset

Warnung: Dieser Endpoint enthält strikte Schutzmechanismen in der Datenbank (sandbox_of is not null). Selbst wenn Sie ihn versehentlich in Ihrer Live-Umgebung aufrufen, bricht die Datenbank die Transaktion ab, um Ihre echten Daten zu schützen. Er funktioniert nur innerhalb von Testumgebungen.

Simulatoren (Test-Helpers)

Mit einem sk_test_-Schlüssel können Sie auslösen, was in der Produktion ein Dritter tut: die Antwort des SAT, das Verstreichen von Zeit oder das Öffnen des Links durch den Kunden. Jeder Simulator durchläuft denselben Code wie die Produktion, sodass Webhooks, Verlauf und E-Mails genauso entstehen wie im Live-Betrieb. Mit einem Live-Schlüssel antworten sie mit test_mode_only, und die Datenbank lehnt jede Simulation für eine echte Organisation ab.

Das Ergebnis der nächsten Stempelung erzwingen

curl -X POST https://cordhq.app/api/v1/test_helpers/fiscal \
  -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
  -d '{ "siguiente_resultado": "pac_caido" }'

Ergebnisse: exito, pac_caido (die Rechnung bleibt als Entwurf und kann erneut versucht werden), receptor_invalido, certificado_vencido und timbre_duplicado. Das Ergebnis wird bei der nächsten Ausstellung verbraucht; ist keines vorgemerkt, ist die simulierte Ausstellung erfolgreich.

Den Kunden und die Zeit simulieren

curl -X POST https://cordhq.app/api/v1/test_helpers/cotizaciones/8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 \
  -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
  -d '{ "accion": "vista" }'

vista erfasst, dass der Kunde das Angebot geöffnet hat (quote.viewed), und vencer lässt es ablaufen (quote.expired). Bestätigen, Ablehnen und Als bezahlt markieren gibt es bereits in POST /api/v1/cotizaciones/{id}.

Einen Webhook auslösen

curl -X POST https://cordhq.app/api/v1/test_helpers/webhooks \
  -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \
  -d '{ "evento": "quote.approved", "objeto_id": "8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10" }'

Akzeptiert jedes Ereignis des Katalogs. Mit der objeto_id eines Testangebots oder einer Testrechnung verwendet er deren echte Daten; ohne sie Beispieldaten mit test_…-IDs. Die objeto_id muss zum Typ des Ereignisses passen: ein Angebot für quote.*, payment.*, invoice.stamped und invoice.issued, eine Rechnung für die übrigen invoice.*-Ereignisse. Ereignisse zu Kunden, Produkten, Aufgaben, Zahlungszusagen, Rückbuchungen, Rückerstattungen, Auszahlungen und Konto verwenden immer Beispieldaten. Die Zustellung läuft über die echte Outbox: Signatur, Wiederholungsversuche und Verlauf in den Zustellungen des Endpoints, im Tab Webhooks der Cord Workbench. Mit objeto_id landet das Ereignis zusätzlich im Ereignisverlauf und im Tab Ereignisse; mit Beispieldaten nicht, denn es ist kein Ereignis Ihres Unternehmens.