Erste Schritte mit der API

Vorschau

Die öffentliche API wird noch gebaut. Schlüssel, Testmodus und Webhooks sind noch nicht verfügbar: Diese Seite beschreibt den angestrebten Vertrag, nicht einen Dienst, den Sie heute aufrufen können.

Schreiben Sie uns aus der App, wenn Sie an der Vorschau teilnehmen möchten.

Die TAYO.pro-API gibt Ihrer eigenen Software Zugriff auf Ihre Projekte, Angebote, Rechnungen und Erinnerungen. Sie ist dafür gedacht, von einem Server aufgerufen zu werden, niemals aus einem Browser: Ein API-Schlüssel in einem JavaScript-Bundle ist ein veröffentlichter Schlüssel.

Was Sie vorher brauchen

Die API ist ein kostenpflichtiges Zusatzmodul zusätzlich zu einem PLUS-Abonnement. Ohne dieses antwortet jeder Aufruf mit 403 addon_required.

Schlüssel werden unter Einstellungen → API erstellt, und nur eine Administratorin oder ein Administrator darf das tun.

Ihre zwei Schlüssel

Jedes Unternehmen erhält zwei Schlüssel, und das Präfix entscheidet über alles:

Schlüssel	Wirkung
tay_live_…	Wirkt auf Ihre echten Daten.
tay_test_…	Durchläuft die gesamte Kette und gibt dann eine Beispielantwort zurück, ohne etwas zu verändern.

Der Modus steht also weder in der URL noch im Rumpf noch in einem Header — ausschliesslich im Schlüssel, den Sie vorlegen.

Der Schlüssel wird nur einmal angezeigt

Bei der Erstellung erscheint der vollständige Schlüssel genau einmal. Wir speichern nur eine Prüfsumme davon und können ihn Ihnen nicht erneut anzeigen. Geht er verloren, bleibt nur: widerrufen und einen neuen erstellen.

Einen Aufruf authentifizieren

Der Schlüssel gehört in den Authorization-Header und sonst nirgendwohin — ein als Query-Parameter übergebener Schlüssel wird mit 401 abgewiesen, auch wenn er gültig ist.

curl https://staging.tayo.pro/api/v1/ping \
  -H "Authorization: Bearer tay_live_ihr_schluessel"

Die Basis-URL lautet https://staging.tayo.pro/api/v1.

Der Testmodus

Eine Anfrage mit einem tay_test_…-Schlüssel durchläuft genau dieselbe Kette wie eine echte: Authentifizierung, Kontingentzählung und dieselbe Validierung von Rumpf und Parametern. Dann hält sie vor der Geschäftslogik an.

Im Testmodus gilt konkret:

• Es wird nichts geschrieben und nichts gelöscht.
• Keine E-Mail, kein PDF und kein Aufruf an Tayo wird ausgelöst.
• Die Antwort entspricht dem Antwortschema der Produktion.
• IDs sind zwischen Aufrufen stabil — prj_test_1 bleibt prj_test_1 — damit Ihre Tests sich darauf stützen können.

Das macht den Produktivstart unspektakulär: Sie haben die genaue Form jeder Antwort bereits gesehen.

Einen Fehlerfall mit Tay-Test-Scenario erzwingen

Wer ernsthaft integriert, muss seine Fehlerzweige durchspielen können. Der Header Tay-Test-Scenario wählt die Antwort, die der Testmodus liefern soll:

Szenario	Was Sie erhalten
success	Der Normalfall. Das ist die Vorgabe.
not_found	Die angeforderte Ressource existiert nicht.
validation_error	Der Rumpf wird abgewiesen, mit Detail pro Feld.
send_failed	Der Versand an die Kundin oder den Kunden ist fehlgeschlagen.
quota_exceeded	Ihr Monatskontingent ist aufgebraucht.

Jeder Endpunkt akzeptiert eine Teilmenge davon — send_failed ergibt bei einem Lesezugriff keinen Sinn. Ein Wert ausserhalb dieser Teilmenge antwortet 400.

Im Live-Modus wird dieser Header abgewiesen

Mit einem tay_live_…-Schlüssel tut Tay-Test-Scenario nicht einfach nichts: Er antwortet 400 test_header_in_live_mode.

Das ist Absicht. Ein im Produktivcode vergessener Test-Header ist ein Fehler, und er soll sich beim ersten Aufruf zeigen, statt monatelang unbemerkt zu bleiben.

In den Produktivbetrieb wechseln

Tauschen Sie den Schlüssel. Mehr nicht.

URLs, Anfragerümpfe, Antwortschemata und Fehlercodes sind in beiden Modi identisch — genau dafür gibt es den Testmodus.

Wie Fehler aussehen

Jede fehlschlagende Anfrage liefert dieselbe Hülle:

{
  "error": {
    "code": "invalid_argument",
    "message": "The request failed validation.",
    "details": [
      { "field": "amount", "code": "invalid_type", "message": "Expected number" }
    ]
  }
}

details erscheint nur bei einem Validierungsfehler.

Status	code	Wann
400	invalid_argument	Die Anfrage hat die Validierung nicht bestanden.
400	failed_precondition	Im aktuellen Zustand nicht möglich.
401	unauthenticated	Schlüssel fehlt, ist widerrufen oder falsch übergeben.
403	permission_denied	Dieser Schlüssel darf das nicht.
403	addon_required	Das API-Modul ist für das Unternehmen nicht aktiv.
404	not_found	Die Ressource existiert nicht.
409	already_exists	Die Ressource existiert bereits.
409	delivery_in_flight	Die Zustellung wartet bereits auf einen weiteren Versuch.
409	endpoint_deleted	Der Endpunkt dieser Zustellung existiert nicht mehr.
409	endpoint_disabled	Der Endpunkt dieser Zustellung ist deaktiviert.
409	retry_limit_reached	Die Zustellung hat ihr Limit für manuelle Wiederholungen erreicht.
429	rate_limited	Zu viele Anfragen pro Minute — langsamer machen und erneut versuchen. Siehe Nutzungsgrenzen.
429	quota_exceeded	Das Monatskontingent und seine Überschreitungstoleranz sind aufgebraucht. Siehe Nutzungsgrenzen.
500	internal	Ein Fehler auf unserer Seite.
503	unavailable	Vorübergehend nicht verfügbar.

Die Meldungen sind ausschliesslich auf Englisch und bleiben es: Ein Programm liest den code, und eine Übersetzung der Prosa würde nur erschweren, wonach es tatsächlich sucht.

Weicht eine Antwort von dem ab, was die Referenz beschreibt, ist das ein Fehler und seine Behebung ist im Modul enthalten: siehe Support.