API kodów kreskowych i QR

Dla kogo

API jest w planach Biznes (10 000 wywołań miesięcznie) i Pro (100 000 wywołań miesięcznie). Klucz tworzysz w panelu, na stronie API.

Adres i klucz

Wszystkie trasy są pod adresem https://app.qreska.com/api/v1. Każde wywołanie niesie klucz w nagłówku, nigdy w adresie, bo adresy trafiają do logów i historii przeglądarki. Klucza nie umieszczaj w kodzie strony, który trafia do przeglądarki: API jest dla Twojego serwera.

Klucz API z panelu, w nagłówku Authorization: Bearer qrk_…

Opis wszystkich tras w formacie OpenAPI 3.1, do wczytania w Postmanie, Insomnii albo generatorze klienta: https://app.qreska.com/api/v1/openapi.json?lang=pl

Limity

• Miesięczny limit wywołań z planu liczy się w miesiącu kalendarzowym (UTC). Liczy się każde wywołanie z poprawnym kluczem, także zakończone błędem walidacji; nie liczą się odrzucone przez brak klucza i przez limit.
• Do 20 wywołań na sekundę na zespół. Ponad to odpowiedź 429 z nagłówkiem Retry-After.
• Każda odpowiedź ma nagłówki RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset (sekundy do początku następnego miesiąca).

Co zapisujemy

Treść kodów statycznych rysujemy w pamięci i zapominamy po wysłaniu odpowiedzi. W dzienniku wywołań, który widzisz w panelu, jest czas, klucz, metoda, trasa bez danych, wynik i czas odpowiedzi — bez treści i bez adresu IP. Szczegóły w polityce prywatności.

Przykłady

Kod EAN-13 jako PNG w 600 dpi:

curl -X POST https://app.qreska.com/api/v1/barcodes \
  -H "Authorization: Bearer $QRESKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbology":"ean-13","data":"590123412345","format":"png","dpi":600}' \
  -o ean-13.png

Kod dynamiczny, a potem zmiana jego celu:

curl -X POST https://app.qreska.com/api/v1/codes \
  -H "Authorization: Bearer $QRESKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Flyer","target":{"type":"url","url":"https://example.com/offer"}}'

curl -X PATCH https://app.qreska.com/api/v1/codes/$CODE_ID \
  -H "Authorization: Bearer $QRESKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":{"type":"url","url":"https://example.com/winter"}}'

SDK dla JavaScriptu i PHP

Dwie małe biblioteki bez zależności: dla Node.js 18+ (TypeScript, fetch) i dla PHP 8.1+ (curl). Obsługują klucz, błędy jako wyjątki z kodem z tabeli wyżej, ponowienie po 429 rate_limited i stronicowanie listy kodów. Do czasu publikacji w npm i Packagist instalujesz je z katalogów sdk/js i sdk/php w repozytorium.

JavaScript i TypeScript:

import { Qreska } from "@qreska/sdk";

const qreska = new Qreska({ apiKey: process.env.QRESKA_KEY });
const file = await qreska.barcode({ symbology: "ean-13", data: "590123412345", format: "png" });
const code = await qreska.codes.create({
  name: "Flyer",
  target: { type: "url", url: "https://example.com/offer" },
});

PHP:

$qreska = new \Qreska\Client(getenv('QRESKA_KEY'));
$file = $qreska->barcode(['symbology' => 'ean-13', 'data' => '590123412345', 'format' => 'png']);
file_put_contents('ean-13.png', $file->data);
$code = $qreska->createCode([
    'name' => 'Flyer',
    'target' => ['type' => 'url', 'url' => 'https://example.com/offer'],
]);

Numery GTIN, ISBN i ISSN

Numery GTIN/EAN nadaje organizacja GS1, w Polsce GS1 Polska. Qreska tylko rysuje kod z numeru, który już masz.

W Polsce numery ISBN nadaje Krajowe Biuro ISBN w Bibliotece Narodowej. Qreska tylko rysuje kod z numeru, który już masz.

W Polsce numery ISSN nadaje Krajowy Ośrodek ISSN w Bibliotece Narodowej. Qreska tylko rysuje kod z numeru, który już masz.

Błędy

Błędy mają format application/problem+json (RFC 9457). Pole code jest stałe i do porównań w programie; title jest dla człowieka, po polsku albo po angielsku według nagłówka Accept-Language. Przy błędach walidacji errors wskazuje pola: path to miejsce w ciele żądania, code to powód.