JavaScript- und TypeScript-SDK

Das offizielle SDK installieren und einen Checkout mit typisierten Public-API-v1-Methoden ausführen

Das offizielle Paket @cowtic/sdk deckt alle Endpunkte der öffentlichen API v1 ab und benötigt Node.js 20 oder neuer.

Installation

npm install @cowtic/sdk

Bestellung erstellen und Ticket erhalten

Erstellen Sie einen API-Schlüssel mit orders:write und tickets:read. Verwenden Sie für diesen Schnellstart einen kostenlosen Tickettyp, damit die Bestellung sofort abgeschlossen wird.

import { Cowtic } from "@cowtic/sdk";

const cowtic = new Cowtic({
	apiKey: process.env.COWTIC_API_KEY!,
});

const response = await cowtic.orders.create({
	eventId: process.env.COWTIC_EVENT_ID!,
	customer: {
		email: `sdk-${Date.now()}@example.com`,
		name: "SDK verification",
	},
	items: [{
		ticketId: process.env.COWTIC_TICKET_TYPE_ID!,
		quantity: 1,
	}],
});

const ticket = response.data.issuedTickets[0];

if (response.data.order.status !== "COMPLETED" || !ticket) {
	throw new Error("The order did not issue a ticket.");
}

const issuedTicket = await cowtic.tickets.get(ticket.id);
console.log(issuedTicket.data.code);

Beim Abschluss einer Bestellung werden deren Tickets automatisch ausgegeben. cowtic.tickets.issue ist ein separater Vorgang für kostenlose oder manuell ausgegebene Tickets, die zu keiner Bestellung gehören.

Konfiguration

Legen Sie für Staging oder die lokale Entwicklung die vollständige Basis-URL der API v1 fest:

const cowtic = new Cowtic({
	apiKey: process.env.COWTIC_API_KEY!,
	baseUrl: "http://localhost:8080/api/v1",
});

Das SDK setzt X-Api-Key automatisch und erzeugt Idempotenzschlüssel für die Bestellungserstellung und manuelle Ticketausgabe. Jede Antwort enthält zudem HTTP-Status, Header, Anfrage-ID und ausgewertete Rate-Limit-Werte.

Bezahlter Checkout mit eigenen Return-URLs

Für einen eigenen Shop übergeben Sie checkoutRedirectUrls, damit Zahls Käuferinnen und Käufer auf Ihre Domain zurückführt. Halten Sie den API-Key auf Ihrem Server — siehe Headless-Checkout und das ausführbare Beispiel unter examples/headless-checkout.

const response = await cowtic.orders.create({
	eventId: process.env.COWTIC_EVENT_ID!,
	customer: { email: "buyer@example.com", name: "Buyer" },
	items: [{ ticketId: process.env.COWTIC_TICKET_TYPE_ID!, quantity: 1 }],
	checkoutRedirectUrls: {
		success: "https://shop.example.com/success",
		failure: "https://shop.example.com/failure",
		cancel: "https://shop.example.com/cancel",
	},
});

if (response.data.checkoutUrl) {
	// Kundin oder Kunde zu Zahls weiterleiten
}

Versionskompatibilität

@cowtic/sdk 1.x ist für /api/v1 vorgesehen. Additive v1-Unterstützung erscheint als Minor-Version, Korrekturen als Patch-Version und eine zukünftige /api/v2 erfordert SDK 2.x.