Erste Schritte · DOC-3000-001

Übersicht

Die apps3k-API ist eine REST- und GraphQL-Schnittstelle zu Master Suite und Shopify Apps. Sie ist versioniert, idempotent und vollständig dokumentiert.

Installation

Installiere das offizielle SDK über npm:

# npm
npm install @apps3k/sdk

# pnpm
pnpm add @apps3k/sdk

# bun
bun add @apps3k/sdk

Authentifizierung

Alle API-Calls werden mit einem API-Token authentifiziert. Tokens werden im SaaS-Login unter Settings → API Tokens erstellt und sind je Workspace gültig. Verwende immer Server-Token, niemals Client-Token im Browser.

import { Apps3k } from "@apps3k/sdk";

const client = new Apps3k({
  token: process.env.APPS3K_TOKEN,
  workspace: "studio-zuerich",
  region: "eu-ch-1",
});

Sicherheit

Lege Tokens nie in den Source Code. Nutze Environment-Variablen und rotiere Tokens regelmäßig (Empfehlung: alle 90 Tage).

Erster API-Call

Lese die Liste der Veranstaltungen aus Venuemaster3000:

const events = await client.venuemaster.events.list({
  from: "2026-05-01",
  to:   "2026-12-31",
  status: ["confirmed", "tentative"],
});

console.log(events.data.length, "Veranstaltungen geladen");

REST API

Die REST-API folgt klassischen Konventionen: GET, POST, PATCH, DELETE. Antworten sind JSON, Fehler folgen RFC 7807 (Problem Details).

GET /v4/venuemaster/events?from=2026-05-01&to=2026-12-31
Authorization: Bearer apps3k_pat_***
Accept: application/json

200 OK
Content-Type: application/json
{
  "data": [
    { "id": "evt_01HX...", "title": "Konzert · Quartett", "starts_at": "2026-05-12T19:30:00Z" }
  ],
  "meta": { "total": 134, "page": 1, "per_page": 50 }
}

GraphQL

Der GraphQL-Endpunkt liegt unter /v4/graphql und unterstützt Queries, Mutations und Subscriptions (über WebSocket).

query EventsThisWeek {
  events(from: "2026-05-04", to: "2026-05-10") {
    id
    title
    startsAt
    venue { id, name, capacity }
    bookings { id, customer { name, email } }
  }
}

Webhooks

Webhooks werden in Settings → Webhooks konfiguriert. Jeder Webhook ist signiert (HMAC-SHA256) und enthält eine eindeutige X-Apps3k-Event-Id.

POST https://your-app.example.com/hooks/apps3k
X-Apps3k-Event-Id:   evt_webhook_01HX...
X-Apps3k-Signature:  sha256=4f2a...
Content-Type:        application/json

{
  "type": "event.confirmed",
  "data": { "id": "evt_01HX...", "title": "..." }
}