Szybki start

Dla: Programista

Przykłady na tej stronie używają adresu . Zmień adres

Po tej stronie będziesz mieć sprawdzony klucz, działające połączenie z API Prynt i wiedzieć, jak wywołać pierwszą operację z referencji.

Zanim zaczniesz

Integracja ma akceptację Prynt, a administrator drukarni przekazał Ci klucz API. Jak to załatwić: Dostęp i akceptacja; instrukcja dla administratora: Integracje API.
Znasz adres drukarni w Prynt: ten sam, pod którym pracownicy logują się do aplikacji.
Masz curl albo jedno ze środowisk: Node.js 18+, Python 3 z biblioteką requests, PHP 8 z rozszerzeniem curl.

Wpisz adres swojej drukarni, a przykłady w całej sekcji dla programistów go użyją:

Twój adres w Prynt

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

1. Zapisz klucz w zmiennej środowiskowej

Nie wklejaj klucza do kodu ani do polecenia, które trafi do historii powłoki. Polecenie poniżej czeka na wklejenie klucza i nie wyświetla go:

read -rs PRYNT_API_KEY && export PRYNT_API_KEY

W aplikacji serwerowej trzymaj klucz w menedżerze sekretów albo w zmiennej środowiskowej ustawianej przy wdrożeniu.

2. Sprawdź klucz

Pierwsze żądanie wywołuje currentApiKey. Ta operacja nie wymaga zakresu, więc odpowie na nią każdy ważny klucz: od razu sprawdzisz adres, format żądania, sam klucz i akceptację integracji.

curl -sS -i https://twoja-drukarnia.prynt.pl/api/v1/graphql \
  -H "Authorization: Bearer $PRYNT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "query": "query CurrentApiKey {\n  currentApiKey {\n    integration {\n      id\n      name\n    }\n    scopes\n    hint\n    expiresAt\n    approvalExpiresAt\n    rateLimitPerMinute\n  }\n}"
}
JSON

// Node.js 18+ (wbudowany fetch), moduł ES
const query = `query CurrentApiKey {
  currentApiKey {
    integration {
      id
      name
    }
    scopes
    hint
    expiresAt
    approvalExpiresAt
    rateLimitPerMinute
  }
}`;

const response = await fetch('https://twoja-drukarnia.prynt.pl/api/v1/graphql', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PRYNT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query }),
});
console.log(response.status, response.headers.get('x-request-id'));
const text = await response.text();
try {
  console.log(JSON.stringify(JSON.parse(text), null, 2));
} catch {
  console.log(text); // nie JSON: sprawdź adres i ścieżkę
}

import os

import requests

QUERY = """
query CurrentApiKey {
  currentApiKey {
    integration {
      id
      name
    }
    scopes
    hint
    expiresAt
    approvalExpiresAt
    rateLimitPerMinute
  }
}
"""

response = requests.post(
    "https://twoja-drukarnia.prynt.pl/api/v1/graphql",
    headers={"Authorization": f"Bearer {os.environ['PRYNT_API_KEY']}"},
    json={"query": QUERY},
    timeout=30,
)
print(response.status_code, response.headers.get("X-Request-ID"))
try:
    print(response.json())
except ValueError:
    print(response.text)  # nie JSON: sprawdź adres i ścieżkę

<?php
$query = <<<'GRAPHQL'
query CurrentApiKey {
  currentApiKey {
    integration {
      id
      name
    }
    scopes
    hint
    expiresAt
    approvalExpiresAt
    rateLimitPerMinute
  }
}
GRAPHQL;

$requestId = null;
$ch = curl_init('https://twoja-drukarnia.prynt.pl/api/v1/graphql');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => function ($curl, $header) use (&$requestId) {
        if (stripos($header, 'x-request-id:') === 0) {
            $requestId = trim(substr($header, 13));
        }
        return strlen($header);
    },
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PRYNT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['query' => $query]),
]);
$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), ' ', $requestId, PHP_EOL;
$json = json_decode($body, true);
// nie JSON: sprawdź adres i ścieżkę
echo $json === null ? $body : json_encode($json, JSON_PRETTY_PRINT), PHP_EOL;

3. Sprawdź odpowiedź

Gdy klucz działa, API odpowiada statusem HTTP 200 i opisem klucza:

{
  "data": {
    "currentApiKey": {
      "integration": {
        "id": "6a1f0c2e-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
        "name": "Sklep internetowy"
      },
      "scopes": [
        "orders:read",
        "orders:write"
      ],
      "hint": "k3Fq",
      "expiresAt": "2027-04-03T00:00:00.000Z",
      "approvalExpiresAt": "2027-10-06T00:00:00.000Z",
      "rateLimitPerMinute": 120
    }
  }
}

integration to integracja, do której należy klucz. Pod tą nazwą Prynt pokazuje autora zmian zapisanych kluczem.
scopes to zakresy, których klucz może teraz używać. Operacje spoza nich odpowiedzą błędem API_SCOPE_MISSING.
expiresAt to koniec ważności klucza, a approvalExpiresAt koniec akceptacji Prynt. Zaplanuj rotację klucza przed pierwszą z tych dat.
rateLimitPerMinute to limit żądań integracji na minutę, wspólny dla wszystkich jej kluczy.

Każda odpowiedź GraphQL ma nagłówek X-Request-ID. Zapisuj go w logach: po nim znajdziemy żądanie, gdy poprosisz nas o pomoc.

Klucz, którego API nie przyjmie, dostanie zamiast tego status HTTP 401, 403 albo 429 i błąd z listy poniżej, bez data. Status 503 z sub-kodem API_KEY_CHECK_UNAVAILABLE oznacza, że Prynt nie mógł chwilowo sprawdzić klucza: ponów żądanie za chwilę i nie wymieniaj klucza.

4. Wywołaj operację z referencji

Wybierz w referencji API operację z zakresu Twojej integracji i wyślij ją tak samo: zmienia się tylko pole query (i opcjonalnie variables). Strona operacji podaje wymagany zakres, argumenty i przykład wywołania. Operacja spoza zakresów integracji dostanie błąd API_SCOPE_MISSING ze statusem HTTP 403.

Gdy coś nie działa

404 albo strona HTML zamiast odpowiedzi GraphQL. Zły adres lub ścieżka. Sprawdź adres drukarni, https:// i ścieżkę /api/v1/graphql.
401, API_TOKEN_INVALID. Klucz jest niepełny, z literówką albo unieważniony. Wklej klucz jeszcze raz. Jeśli nie pomoże, poproś administratora drukarni o nowy.
401, API_TOKEN_EXPIRED. Klucz minął datę ważności. Poproś administratora drukarni o nowy klucz.
429, RATE_LIMITED. Integracja przekroczyła limit żądań na minutę. Odczekaj tyle sekund, ile podaje nagłówek Retry-After, zobacz Limity.
403, API_TOKEN_INSECURE_TRANSPORT. Adres API zaczyna się od http://. Zmień go na https://, a klucz wymień: przeszedł przez sieć jawnym tekstem, zobacz Uwierzytelnianie.
403, API_TOKEN_BROWSER_USE. Żądanie wysłała przeglądarka. Wywołuj API z serwera.
403, ORIGIN_NOT_ALLOWED. Żądanie ma nagłówek Origin strony spoza Prynt, np. wysłała je przeglądarka albo dopisał go Twój program. Wywołuj API z serwera, bez nagłówka Origin. Przeglądarka pokaże w konsoli błąd CORS: przyczyna jest ta sama.
403, API_INTEGRATION_NOT_APPROVED. Akceptacja Prynt wygasła albo została cofnięta. Skontaktuj się z administratorem drukarni.
403, API_INTEGRATION_SUSPENDED. Drukarnia wstrzymała integrację albo Prynt ją zawiesił. Skontaktuj się z administratorem drukarni.
403, API_SCOPE_MISSING. Integracja nie ma zakresu z params.scope. Usuń element z zapytania albo poproś administratora o rozszerzenie zakresów.
403, API_OPERATION_NOT_AVAILABLE. Operacja nie należy do publicznego API. Wybierz operację z referencji.
400, API_QUERY_INVALID. Literówka w nazwie pola albo pole spoza publicznego schematu. Sprawdź zapytanie z pobranym schematem.
503, API_KEY_CHECK_UNAVAILABLE. Prynt chwilowo nie może sprawdzić klucza. Ponów za chwilę.

Wszystkie kody opisuje strona Błędy API.