Erste Schritte mit der API

Die TAYO.pro-API erlaubt Ihrer eigenen Software, Ihre Projekte, Einsätze, Offerten, Rechnungen und Zahlungserinnerungen zu lesen. In ihrer aktuellen Version liest sie nur: Kein Endpunkt erstellt oder sendet ein Dokument. Die genaue Liste steht in der Referenz.

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 eine kostenpflichtige Option zusätzlich zu einem Abonnement des PLUS-Plans. Ohne sie antworten alle authentifizierten Aufrufe mit 403 addon_required.

Die Schlüssel werden unter Einstellungen → API erstellt, nur in der Web-App, nachdem Sie die Nutzungsbedingungen der API akzeptiert haben.

Ihre zwei Schlüssel

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

Schlüssel	Was er tut
`tay_live_…`	Der Produktionsschlüssel: greift auf Ihre echten Daten zu.
`tay_test_…`	Der Testschlüssel: durchläuft den gesamten Weg einer Anfrage 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 — ausschließlich im Schlüssel, den Sie vorlegen.

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://app.tayo.pro/api/v1/me \
  -H "Authorization: Bearer tay_test_ihr_schluessel"

{ "companyId": "…", "mode": "test" }

GET /me sagt Ihnen, zu welchem Unternehmen und welchem Modus der Schlüssel gehört: Das ist der erste Aufruf, um einen Schlüssel zu prüfen. GET /ping dagegen verlangt keinen Schlüssel: Er sagt nur, ob die API antwortet.

Die Basis-URL lautet https://app.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;
die IDs sind von Aufruf zu Aufruf stabil — prj_test_1 bleibt prj_test_1 —, damit sich Ihre Tests darauf stützen können.

Das macht den Produktivstart ohne Überraschungen: Sie haben die genaue Form jeder Antwort bereits gesehen.

Einen Fehlerfall mit `Tay-Test-Scenario` erzwingen

Wer ernsthaft integriert, muss seine Fehlerzweige testen 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 den Kunden ist fehlgeschlagen.
`quota_exceeded`	Ihr Monatskontingent ist aufgebraucht.

Jeder Endpunkt akzeptiert eine Teilmenge dieser Werte — send_failed ergibt bei einem Lesezugriff keinen Sinn. Heute akzeptiert eine Liste success und quota_exceeded, das Lesen einer Ressource fügt not_found hinzu. Ein Wert außerhalb dieser Menge antwortet mit 400.

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`	Der Vorgang ist 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`	Die API-Option 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`	Dienst vorübergehend nicht verfügbar.

Die Meldungen sind ausschließlich 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 in der Option inbegriffen: siehe API-Support.