Podstawy GraphQL w Prynt

API Prynt to jeden punkt końcowy GraphQL na drukarnię. Ta strona opisuje, jak wysyłać do niego żądania i skąd wziąć schemat, z którego zbudujesz zapytania i typy w swoim kodzie.

Twój adres w Prynt

Wyczyść

Przykłady pokazują adres zastępczy. Wpisz adres swojej drukarni, żeby go podmienić.

Punkt końcowy

POST https://twoja-drukarnia.prynt.pl/api/v1/graphql
Authorization: Bearer prynt_…
Content-Type: application/json

Treść żądania to obiekt JSON:

{
  "query": "query Example($id: ID!) { … }",
  "variables": { "id": "…" },
  "operationName": "Example"
}

• query jest wymagane, variables i operationName opcjonalne.
• Wysyłaj żądania metodą POST. Zapytania przez GET i wiele operacji w jednej tablicy JSON (batching) nie należą do publicznego API.
• Jedno żądanie to jedna operacja: zapytanie (query) albo mutacja (mutation). Operacja może wybrać kilka pól głównych naraz.
• Subskrypcje (subscription) nie są dostępne dla kluczy API. Zmiany na żywo pobieraj sondą zmian w backendzie integracji, zobacz przepis Zmiany na żywo w ekranach integracji.

Odpowiedź

Odpowiedź ma kształt standardowy dla GraphQL:

{
  "data": { "…": "…" },
  "errors": [{ "message": "…", "path": ["…"], "extensions": { "code": "…", "requestId": "…" } }]
}

• data zawiera wyniki pól, które się udały. Gdy część pól zawiedzie, dostaniesz jednocześnie data i errors, a path błędu wskaże pole.
• Sprawdzaj errors w każdej odpowiedzi, także ze statusem HTTP 200. Kody błędów i zalecane reakcje opisuje strona Błędy API.
• Żądanie odrzucone, zanim operacja się wykona, ma własny status HTTP 4xx albo 5xx (400, 401, 403, 409, 429, 500 albo 503) i same errors, bez data. Status 200 oznacza, że API zaczęło wykonywać operację: sprawdź errors, bo mogło się nie udać część pól albo każde z nich.
• Odpowiedź ze statusem HTTP 5xx może nie mieć kształtu GraphQL, np. gdy Prynt jest chwilowo niedostępny. Traktuj każdą taką odpowiedź jak błąd przejściowy i ponów żądanie później.
• Nagłówek X-Request-ID i pole extensions.requestId w błędach identyfikują żądanie. Zapisuj je w logach.
• Treść żądania, która nie jest poprawnym JSON-em, dostaje status HTTP 400 z krótkim komunikatem spoza formatu GraphQL (bez errors). Sprawdź, jak Twój kod serializuje treść.

Schemat do pobrania

Introspekcja (__schema, __type) jest wyłączona dla kluczy API: takie zapytanie kończy się błędem API_QUERY_INVALID. Pełny publiczny schemat w formacie SDL publikujemy razem z dokumentacją, przy każdym wydaniu Prynt:

Pobierz schemat (SDL)

Schemat zawiera wszystkie publiczne operacje i pola. Twój klucz może z niego wybrać tylko część objętą zakresami integracji: na przykład bez prices:read zapytanie o pola cen i kosztów API odrzuci błędem API_SCOPE_MISSING, z brakującym zakresem w params.scope i polem, argumentem albo filtrem, który go wymaga, w params.coordinate. Zmiany schematu opisuje historia zmian API.

Trzymaj schemat w repozytorium

Zapisz pobrany plik w repozytorium integracji, np. jako schema/prynt.graphql, i aktualizuj go świadomie. Twój build nie zależy wtedy od dostępności dokumentacji, a różnica w pliku pokaże, co zmieniło się w API.

Narzędzia

Generator typów sprawdzi Twoje zapytania ze schematem jeszcze przed uruchomieniem integracji.

JavaScript

GraphQL Code Generator z pluginem typed-document-node generuje typy zapytań i wyników:

codegen.ts

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'schema/prynt.graphql',
  documents: ['src/**/*.graphql'],
  generates: {
    'src/generated/prynt.ts': {
      plugins: ['typescript', 'typescript-operations', 'typed-document-node'],
    },
  },
};

export default config;

Python

ariadne-codegen generuje klienta z typowanymi modelami na podstawie pliku SDL i Twoich zapytań:

pyproject.toml

[tool.ariadne-codegen]
schema_path = "schema/prynt.graphql"
queries_path = "queries/"
target_package_name = "prynt_client"

• Edytor. Rozszerzenie GraphQL do VS Code i edytory JetBrains podpowiadają pola i sprawdzają zapytania na podstawie pliku graphql.config.yml:

  schema: schema/prynt.graphql
  documents: src/**/*.graphql

• Ręczne testy. Do wysyłania pojedynczych żądań użyj curl albo aplikacji desktopowej (Insomnia, Postman) z zaimportowanym plikiem SDL. Narzędzia działające w przeglądarce, np. GraphiQL czy Apollo Sandbox, wysyłają nagłówek Origin, więc API odrzuci ich żądania z kluczem (ORIGIN_NOT_ALLOWED, a na stronie Prynt API_TOKEN_BROWSER_USE).

Dobre praktyki

• Nazywaj operacje, np. query OrdersForSync. Łatwiej je potem znaleźć w logach.
• Przekazuj wartości przez variables, nie wklejaj ich do tekstu zapytania. Unikniesz błędów cytowania i wstrzyknięcia.
• Wybieraj tylko potrzebne pola. Mniejsze zapytanie jest szybsze i mieści się w limicie złożoności.
• Obsłuż nieznane wartości enumów. Nowa wartość może dojść w kolejnym wydaniu; zobacz Wersjonowanie.