API-Referenz

Roestify nutzt eine hybride API-Architektur: tRPC für alle App-Operationen, REST-Endpoints für Webhooks, OAuth und öffentliche APIs.

tRPC (Primäre API)

Endpoint

/api/trpc/{router.procedure}

Setup

• Server: tRPC v11.0.0 mit SuperJSON-Transformer
• Client: @trpc/react-query mit @tanstack/react-query
• Validierung: Zod v4.3.5 via .input()
• Context: Session (Auth.js), DB (Drizzle), userId, tenantId, role

Procedures

Typ	Auth	Beschreibung
publicProcedure	Keine	Health Checks, öffentliche Displays
protectedProcedure	Session	App-Logik, injiziert userId/tenantId/role

Router-Module

Router	Zuständigkeit
production	Lots, Lieferanten, Maschinen, Profile, Tonnen, Röst-Log, Varianten, Abpackung, Wartung
b2b	Kunden, Bestellungen, Rechnungen, Abos, Preise, Forecasts
analytics	Berichte, Metriken
tenant	Einstellungen, Team, Onboarding, Billing
online-store	Shopify-Integration
shipping	DHL-Versand
billing	Stripe, Subscriptions
traceability	Rückverfolgung

Beispiel

// Server (src/server/trpc/routers/production.ts)
export const productionRouter = createTRPCRouter({
  lots: {
    list: protectedProcedure
      .input(z.object({ status: z.enum(['Active', 'Depleted', 'Blocked']).optional() }))
      .query(async ({ ctx, input }) => {
        return ctx.db.select().from(greenCoffeeLots)
          .where(eq(greenCoffeeLots.tenantId, ctx.session.user.tenantId));
      }),
  },
});

// Client (React Component)
const { data } = trpc.production.lots.list.useQuery({ status: 'Active' });

---

REST-Endpoints

REST-Routes unter /api/v1/ für Fälle, die nicht in tRPC passen:

Authentifizierung

REST-Endpoints nutzen verschiedene Auth-Mechanismen:

Mechanismus	Verwendung
Session JWT	Eingeloggte User (Cookies von Auth.js)
Bearer Token	Cron-Jobs (CRON_SECRET), Platform-Admin
HMAC / Signatur	Shopify OAuth, Stripe Webhooks
Token (URL)	Display-API, Einladungen, Bestellformular

Response-Format

// Erfolg
{ "data": { ... } }

// Fehler
{ "error": "Beschreibung des Fehlers" }

HTTP-Status-Codes

Code	Bedeutung
200	Erfolg
201	Erstellt
400	Validierungsfehler
401	Nicht authentifiziert
403	Keine Berechtigung / Usage Limit
404	Nicht gefunden
409	Konflikt (Duplikat, Statusverletzung)
410	Abgelaufen (Token)
429	Rate Limit überschritten
500	Server-Fehler

Rate Limiting

In-Memory Rate Limiter mit Sliding-Window-Ansatz. Bei Überschreitung:

HTTP 429 Too Many Requests

REST-Endpunkte nach Domain

Domain	Basis-Pfad	Beschreibung
Auth	/api/auth/	Auth.js Endpunkte
Admin	/api/v1/admin/	Plattform-Administration
Shopify	/api/v1/shopify/	OAuth + Sync
Reports	/api/v1/reports/	Finanzberichte
Settings	/api/v1/tenant-settings/	Logo, Display
Cron	/api/v1/cron/	Hintergrund-Jobs
Order-Form	/api/v1/order-form/	B2B-Bestellformular (OTP-Auth)
Billing	/api/v1/billing/	Stripe Webhooks
Invitations	/api/v1/invitations/	Einladungs-Annahme