> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deal-pipe.de/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL und TypeScript

> Typisierte Dokumente, Authentifizierung und Cursor-Seiten.

## API-Adresse und Verfügbarkeit

Senden Sie GraphQL-Anfragen an `POST /graphql` auf Ihrem konfigurierten API-Host. Adresse und Verfügbarkeit erhalten Sie von Ihrem Arbeitsbereichsadministrator. API und Anwendungsmigration sind noch im Gange; dieser Leitfaden kündigt weder einen gehosteten Release noch eine vollständige Dashboard-/Admin-Abdeckung an. Die [generierte Referenz](/de/developers/graphql-reference) zeigt die Operationen dieses Builds.

Der GraphQL-Leitfaden und die generierte Referenz stehen unten. Apollo Sandbox ist unter `/playground` auf dem konfigurierten API-Host verfügbar.

Die API verwendet Apollo Server 5 auf Vercel. Unter `/playground` steht Apollo Sandbox mit authentifiziertem Schema und benannten Abfragen und Mutationen bereit. Metriken und Schema-Prüfungen in Apollo Studio erfordern einen separat konfigurierten GraphOS-Graphen.

## Authentifizierung

Senden Sie `Authorization: Bearer <token>`. Server-Integrationen verwenden API-Tokens des Arbeitsbereichs. Jede Anfrage schneidet die Token-Scopes mit den aktuellen Berechtigungen und Objektzuweisungen des Erstellers. Eine übergebene ID wechselt keinen Arbeitsbereich.

Dashboard und mobile Clients verwenden ein Supabase-Benutzer-Access-Token. Die API prüft Identität und Sitzung und lädt danach aktuelle Mitgliedschaft, Arbeitsbereich, Berechtigungen und Zuweisungen. Erforderliche Zwei-Faktor-Authentifizierung muss erfüllt sein. Tokens werden über Supabase Auth erneuert; Refresh-Tokens sind keine GraphQL-Zugangsdaten. Persönliche Einstellungen erfordern eine Benutzersitzung und sind mit API-Tokens nicht zugänglich.

## Abfrage

Ersetzen Sie Host und Token durch Ihre konfigurierten Werte. Prüfen Sie lesende Abfragen zuerst in einem Testarbeitsbereich.

```bash theme={null}
curl 'https://api.example.com/graphql' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  --data '{"query":"query Projects($first: Int!) { projects(first: $first) { nodes { id name } pageInfo { hasNextPage endCursor } } }","variables":{"first":50}}'
```

Übergeben Sie Eingaben als Variablen und wählen Sie nur benötigte Felder. IDs sind UUIDs, `DateTime` verwendet ISO 8601 mit Zeitzone und `Decimal` Zeichenfolgen für genaue Dezimalwerte. Enum-Werte wie `frei` bleiben in allen Oberflächensprachen gleich.

## Seiten und verschachtelte Abfragen

Connections liefern `nodes` und `pageInfo`. Übergeben Sie den letzten `endCursor` als `after`, solange `hasNextPage` wahr ist. Standard sind 50 Datensätze, maximal sind 200 möglich. Behandeln Sie Cursor als undurchsichtige Werte und behalten Sie die Filter beim Blättern bei. Sichtbarkeit und Kundenzuweisungen werden vor der Seitenauswahl geprüft.

Verschachtelte Projekteinheiten bündeln ihre Datenbankabfragen. Die Abfrageprüfung berechnet den verschachtelten Umfang; 200 Projekte mit jeweils 200 Einheiten können das Budget überschreiten. Wählen Sie kleinere Seiten, statt abgelehnte Abfragen wiederholt zu senden.

## TypeScript mit typisierten Dokumenten

Externe Clients verwenden standardmäßige GraphQL-Werkzeuge; es gibt kein DealPipe-SDK
und keinen Import generierter Clients aus dem Repository. Installieren Sie
`graphql-request`, `graphql`, `@graphql-codegen/cli` und
`@graphql-codegen/client-preset`. Speichern Sie eigene `.graphql`-Operationen und
generieren Sie Dokumente und Typen aus dem exportierten
[Schema](/assets/graphql/schema.graphql). Eine Codegen-Konfiguration kann zum Beispiel
so aussehen:

```ts theme={null}
import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  schema: "./schema.graphql",
  documents: ["src/**/*.graphql"],
  generates: {
    "src/gql/": {
      preset: "client",
      presetConfig: { fragmentMasking: false },
    },
  },
};
export default config;
```

Verwenden Sie das generierte typisierte Dokument mit `graphql-request`. Lösen Sie
für jede Anfrage das aktuelle Token auf und übergeben Sie die Abbruchsteuerung in
den Anfrageoptionen:

```ts theme={null}
import { GraphQLClient } from "graphql-request";
import { ListProjectsDocument } from "./gql/graphql";

const client = new GraphQLClient("https://api.example.com/graphql");

const result = await client.request({
  document: ListProjectsDocument,
  variables: { first: 50, after: null },
  requestHeaders: {
    Authorization: `Bearer ${await getCurrentAccessToken()}`,
  },
  signal: abortController.signal,
});
```

Mutationen werden nicht automatisch wiederholt. Nach einem Verbindungsfehler kann
der Server die Änderung bereits ausgeführt haben. Wiederholen Sie sie nur mit einem
ausdrücklichen, serverseitig erzwungenen Idempotenzvertrag.

## Fehler und Anfragebudgets

GraphQL-Antworten können auch bei HTTP-Status 200 ein `errors`-Array enthalten. Prüfen Sie die Meldung und `extensions` jedes Fehlers und notieren Sie den Antwort-Header `x-request-id` für Supportanfragen. `graphql-request` lehnt fehlerhafte GraphQL-Antworten mit seinem eigenen Fehlertyp ab; es garantiert keine Maskierung von Variablen oder anderen Anfragedetails. Protokollieren Sie rohe Clientfehler oder Anfrageinhalte nur nach eigener Redaktion. Der Anwendungstransport von DealPipe maskiert Fehler separat.

Die API begrenzt die tatsächlichen Body-Bytes, Parser-Tokens, Abfragetiefe, Abfragekosten und Anfrageraten. Budgetfehler nennen Budget, Grenze und den versuchten Wert, wenn bekannt. Reduzieren Sie Felder, verschachtelte Seiten oder Importgrößen und teilen Sie die Arbeit auf. Beachten Sie bei Ratenlimits `Retry-After`. Private Speicher-URLs werden erst nach der Sichtbarkeitsprüfung signiert.

## Weitere Protokolle

Supabase Auth, direkte Uploads über freigegebene signierte URLs und Realtime-Kanäle behalten ihre Protokolle. Provider-Webhooks behalten HTTP-Methoden und Signaturprüfungen. Sie sind keine allgemeinen Alternativen zur GraphQL-API für Anwendungsdaten.

## Apollo Sandbox

Öffnen Sie `/playground?lang=de` auf Ihrem konfigurierten API-Host. Geben Sie ein Test-Token ein und wählen Sie eine Query oder Mutation. Der Operationskatalog verwendet kanonische Beispieldokumente aus `packages/graphql/operations`; jeder Build prüft die Operationswurzeln gegen das ausführbare Schema. Ersetzen Sie notwendige Eingabevariablen vor dem Ausführen. Die Seite speichert Tokens nicht und verwendet keine Auth-Cookies. Das Schema wird mit Ihren Berechtigungen über dieselbe GraphQL-API geladen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.