Przejdź do głównej treści
API GetQR jest w wersji beta i jest dostępne dla wybranych obszarów roboczych. Szczegóły mogą się zmienić przed ogólną premierą.
Kod QR w GetQR to obraz plus krótki link, przez który kod prowadzi do celu. Utworzenie kodu QR tworzy też jego krótki link, więc możesz później zmienić cel bez ponownego drukowania kodu.

Dane kodu QR według typu

Format data dla każdego z 16 typów.

Personalizacja

Style kropek, kolory, ramki i logo.

Reguły dostępu

Harmonogram, limit skanowań i hasło.
Statystyki skanowań kodu QR znajdziesz w sekcji Analityka.

Obiekt kodu QR

Każdy endpoint kodów QR odpowiada tym obiektem, z wyjątkiem usuwania i pobierania obrazu. Lista zwraca tablicę takich obiektów.
string
Unikalne ID kodu QR, np. qr_1EPcVfeHZAY2iNoVLsgW2Aqf.
string
Typ kodu QR, np. website. Wszystkie 16 wartości opisuje strona Dane kodu QR według typu.
string | null
Nazwa kodu QR wyświetlana w panelu.
string | null
Dowolna notatka o kodzie QR.
string
Zapisane dane. Dla wifi, vcard, social, multilink, event i sms są to dane, które wysłałeś. Dla każdego innego typu jest to krótki link, więc cel odczytuj z url.
boolean
true, gdy kod QR jest wstrzymany.
boolean
true dla statycznego kodu QR utworzonego w panelu, który nie ma krótkiego linku. API zawsze tworzy dynamiczne kody QR.
Pełny krótki link, np. https://getqr.sh/x7Kd2p1.
string | null
Domena krótkiego linku.
string | null
Slug krótkiego linku.
boolean
true, gdy slug został wybrany, a nie wygenerowany.
string | null
Cel, do którego przekierowuje krótki link.
string | null
Cel dla odwiedzających z iOS, w kodach QR typu app.
string | null
Cel dla odwiedzających z Androidem, w kodach QR typu app.
integer
Łączna liczba skanowań.
object
Reguły dostępu. Samo hasło nigdy nie jest zwracane. Zobacz Reguły dostępu.
string
Tylko do odczytu. custom to projekt, który API może w pełni edytować. branded i ai to projekt Branded lub AI utworzony w panelu. API nie może edytować jego grafiki, ale zachowuje ją, gdy zmieniasz inne pola.
object
Zapisany projekt: styles, frameOptions i logoOptions, każdy jako obiekt lub null. Mają ten sam kształt co pola żądania, więc możesz je odesłać. Zobacz Personalizacja.
object | null
Plik kodu QR typu pdf, image lub video: id, name i size w bajtach.
string | null
Tylko do odczytu. Wyświetlana nazwa kodu QR typu app utworzonego w panelu.
object | null
Tylko do odczytu. Kod QR typu pdf z kilkoma plikami, utworzony w panelu: title, layout i files.
Tylko do odczytu. Kod QR typu image z kilkoma obrazami, utworzony w panelu: title, layout i files.
string
Data utworzenia, ISO 8601.
string
Data ostatniej aktualizacji, ISO 8601.
Dane poufne i wewnętrzne ID (password, userId, workspaceId, projectId) nigdy nie są zwracane.

Lista kodów QR

GET /api/v1/qrs Zwraca kody QR z Twojego obszaru roboczego, po jednej stronie naraz.
integer
domyślnie:"1"
Strona do zwrócenia, 1 lub więcej.
integer
domyślnie:"100"
Liczba kodów QR na stronę, od 1 do 100. Większa wartość jest odrzucana.
Dopasowuje tytuł kodu QR. Zapytania dłuższe niż 2 znaki dopasowują też zapisane data. W typach z linkiem zapisane data to krótki link, więc adresów docelowych nie da się wyszukać.
string
domyślnie:"createdAt"
Pole sortowania: createdAt, updatedAt, clicks (łączna liczba skanowań), lastClicked (ostatnie skanowanie) lub type. type zawsze sortuje malejąco i ignoruje sortOrder.
string
domyślnie:"desc"
Kierunek sortowania: asc lub desc.
boolean
domyślnie:"false"
Uwzględnia wstrzymane kody QR.
boolean
domyślnie:"false"
Zwraca tylko wstrzymane kody QR. Ma pierwszeństwo przed showArchived.
Parametry logiczne przyjmują ciągi true lub false. Pobieraj kolejną stronę, dopóki pagination.hasMore ma wartość true. Zobacz Paginacja.

Tworzenie kodu QR

POST /api/v1/qrs Tworzy kod QR razem z jego krótkim linkiem. Odpowiada 201 Created z nowym kodem QR.
string
Twój własny token ponowień. Powtórzenie żądania z tym samym kluczem w ciągu 24 godzin zwraca pierwotną odpowiedź zamiast tworzyć drugi kod QR. Zobacz Ponowienia i duplikaty.
string
wymagane
Co koduje kod QR. Określa też format, w jakim musi być data. Jedna z wartości: website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event.
string
wymagane
Dane danego typu, sprawdzane względem qrType. Pusty ciąg pomija sprawdzenie. Format każdego typu opisuje strona Dane kodu QR według typu.
Krótki link, przez który kod QR prowadzi do celu. Opcjonalny: gdy go pominiesz, link.url przyjmuje wartość data.
string
Nazwa kodu QR wyświetlana w panelu. Po przycięciu spacji od 1 do 40 znaków. Gdy ją pominiesz, kod QR nie ma tytułu.
string
Dowolna notatka o kodzie QR. Do 280 znaków.
string
Plik kodu QR typu pdf, image lub video, przesłany z odpowiadającym mu celem (target). Dla vcard, social i multilink opcjonalne zdjęcie profilowe przesłane z celem logo. event też go przyjmuje, ale jego strona odczytuje okładkę z data.fileId. Inne typy dostają 422. Najpierw prześlij plik przez Pliki. Zobacz Pliki w kodach QR.
string
Szablon, którego projekt zostanie zastosowany do nowego kodu QR. Wysłane pola projektu są z nim scalane i mają przed nim pierwszeństwo. Szablon z projektem Branded lub AI dostaje 422 (art_template_unsupported). Nieznany szablon lub szablon z innego obszaru roboczego dostaje 404.
object
Kształty i kolory kropek oraz narożników. Zobacz Personalizacja.
object
Ramka wokół kodu QR i jej tekst wezwania do działania. Zobacz Personalizacja.
object
Logo na środku: sugerowane logo albo własny plik przesłany z celem logo. Nieznany plik, niedokończone przesyłanie lub plik z innym celem są odrzucane. Zobacz Personalizacja.
object
Harmonogram, limit skanowań i ochrona hasłem. Zobacz Reguły dostępu.
boolean
Czy kod QR jest wstrzymany. true tworzy go jako wstrzymany: skanowania pokazują stronę wstrzymania zamiast celu.
Nieznane pola są pomijane bez błędu. Zobacz Nieobsługiwane przez API.

Ponowienia i duplikaty

  • Z kluczem. Z nagłówkiem Idempotency-Key odpowiedź jest odtwarzana przez 24 godziny.
  • Bez klucza. Identyczna treść wysłana w ciągu 30 sekund jest traktowana jako duplikat.
  • Odtworzenia. Odtworzenie zwraca zapisaną odpowiedź z x-idempotent-replay: true. Nowy kod QR zwraca false.
  • W toku. Drugie żądanie wysłane, gdy pierwsze wciąż trwa, dostaje 409 conflict.
  • Niepowodzenia. Nieudane utworzenie od razu zwalnia klucz, więc możesz ponowić żądanie z tym samym kluczem.
  • Bez gwarancji. Jeśli zabezpieczenie jest niedostępne, utworzenia przechodzą bez ochrony.
Zobacz też Idempotentność.

Odczyt kodu QR

GET /api/v1/qrs/{qrId} Zwraca kod QR z jego krótkim linkiem, regułami dostępu, projektem oraz, w typach opartych na plikach, plikiem.
string
wymagane
ID kodu QR z odpowiedzi listy lub tworzenia.
Odpowiedzią jest pełny obiekt kodu QR.

Aktualizacja kodu QR

PATCH /api/v1/qrs/{qrId} Zmienia treść, cel, projekt lub reguły dostępu kodu QR. Wysyłaj tylko pola, które chcesz zmienić. Odpowiada zaktualizowanym kodem QR.
string
wymagane
ID kodu QR.
Treść żądania przyjmuje te same pola co tworzenie kodu QR, wszystkie opcjonalne, z tymi różnicami:
  • templateId. Nieakceptowane.
  • link. Częściowe. Gdy pominiesz link.url, obecny cel zostaje zachowany. link.domain i link.key dostają 422: krótki link jest tym, co koduje wydrukowany kod, więc aby użyć innego, utwórz nowy kod QR.
  • data. Sprawdzane względem wynikowego typu tylko wtedy, gdy zmienia się data lub qrType. Zmiana qrType bez pasującego data jest odrzucana. Zobacz Zmiana typu.
  • Projekt. styles, frameOptions i logoOptions są scalane z zapisanym projektem, więc częściowy obiekt zmienia tylko to, co zawiera. Wybranie innego logo zastępuje je, ale zachowuje jego rozmiar.
  • access. Każdy klucz jest stosowany, gdy jest obecny. null usuwa regułę. Reguły dostępu należą do access: wysłanie ich w link zwraca 422.
  • archived. Wstrzymuje lub ponownie aktywuje kod QR razem z jego krótkim linkiem, tak jak wstrzymanie i ponowna aktywacja.
Co można zmienić po wydruku w każdym typie, opisuje strona Dane kodu QR według typu.

Ustawianie stanu wstrzymania

PUT /api/v1/qrs/{qrId} Bezpośrednio ustawia stan wstrzymania. Wstrzymanie i ponowna aktywacja robią to samo i są czytelniejsze.
string
wymagane
ID kodu QR.
boolean
wymagane
true, aby wstrzymać kod QR, false, aby go ponownie aktywować.

Wstrzymanie kodu QR

POST /api/v1/qrs/{qrId}/pause Sprawia, że kod QR przestaje prowadzić do celu: skanowania pokazują zamiast tego stronę wstrzymania. Wydrukowany kod i jego krótki link pozostają ważne. Bez treści żądania.
string
wymagane
ID kodu QR.

Ponowna aktywacja kodu QR

POST /api/v1/qrs/{qrId}/activate Sprawia, że wstrzymany kod QR znowu prowadzi do celu. Harmonogram i limit skanowań nadal obowiązują. Bez treści żądania.
string
wymagane
ID kodu QR.

Duplikowanie kodu QR

POST /api/v1/qrs/{qrId}/duplicate Tworzy kopię z tą samą treścią i projektem. Bez treści żądania. Odpowiada 201 Created z nowym kodem QR.
string
wymagane
ID kodu QR do skopiowania.
  • Krótki link. Kopia dostaje własny krótki link z losowym slugiem w domenie domyślnej obszaru roboczego, a nie w domenie oryginału. Jej skanowania są liczone osobno.
  • Tytuł. Tytuł dostaje przyrostek (Copy). Wynik mieści się w 40 znakach: długi tytuł jest najpierw skracany. Kod QR bez tytułu pozostaje bez tytułu.
  • Niekopiowane. Reguły dostępu (hasło, harmonogram, limit skanowań) i stan wstrzymania. Kopia jest zawsze aktywna.
  • Pliki. Pliki PDF i obrazy, w tym pliki pakietów i galerii, są kopiowane, więc kopia jest ich właścicielem. Pliki wideo i pliki projektu, takie jak logo, są współdzielone z oryginałem.

Usuwanie kodu QR

DELETE /api/v1/qrs/{qrId} Usuwa kod QR i jego krótki link. Odpowiada ID usuniętego kodu.
Usunięcie jest trwałe. Wydrukowany kod i jego krótki link przestają działać, a historia skanowań staje się niedostępna. Jeśli kod może się jeszcze przydać, lepiej go wstrzymaj.
string
wymagane
ID kodu QR.
string
ID usuniętego kodu QR.
boolean
Zawsze true.

Pobieranie obrazu kodu QR

GET /api/v1/qrs/{qrId}/download Renderuje kod QR z jego projektem i zwraca plik.
string
wymagane
ID kodu QR do wyrenderowania, z odpowiedzi listy lub tworzenia.
string
domyślnie:"jpg"
Format wyjściowy: jpg, png, svg, pdf (strona A4) lub eps. Projekt Branded lub AI można pobrać tylko jako jpg, png lub pdf.
integer
domyślnie:"1024"
Rozmiar obrazu w pikselach: 1024, 2048 lub 4096. svg i pdf go ignorują. Projekt Branded lub AI można pobrać tylko w rozdzielczości 1024.
  • Treść. Treścią odpowiedzi jest plik. Sugerowana nazwa pliku znajduje się w nagłówku Content-Disposition i jest tworzona z tytułu albo jako qr-code dla kodu QR bez tytułu.
  • Buforowanie. Odpowiedzi zawierają ETag i Cache-Control: private, max-age=3600, must-revalidate. Odeślij ETag w If-None-Match, aby otrzymać 304 Not Modified, gdy kod QR się nie zmienił.
  • Błędy. Nieobsługiwany format lub rozdzielczość dostaje 400 bad_request. Komunikat błędu podaje przyczynę: qr_download_invalid_format, qr_download_invalid_resolution, qr_download_art_format_unsupported lub qr_download_art_resolution_unsupported.

Reguły dostępu

Wyślij obiekt access przy tworzeniu lub aktualizacji, aby zaplanować początek i koniec, ograniczyć liczbę skanowań lub wymagać hasła. Pominięte reguły pozostają bez zmian, a null usuwa regułę. Pełny opis działania z przykładami znajdziesz w przewodniku Reguły dostępu.

Obiekty projektu

styles, frameOptions i logoOptions ustawiają kształty kropek i narożników, kolory, ramkę i logo. Działają tak samo w kodach QR, szablonach i masowym tworzeniu. Nieznane kształty, ramki lub logo są odrzucane. Wszystkie akceptowane wartości i pełny przykład znajdziesz w przewodniku Personalizacja.

Typowe problemy

Wyślij regułę w access, a nie w link.
data nie pasuje do formatu qrType. Sprawdź typ na stronie Dane kodu QR według typu.
Identyczne tworzenie wciąż trwa albo link.key jest zajęty. Ponów żądanie, gdy pierwsze się zakończy. Z Idempotency-Key ponowienie zwraca pierwotny kod QR.
Parametry to format i resolution, a format ma domyślnie wartość jpg. Wyślij format=png.
Każde żądanie jest wykonywane w obszarze roboczym Twojego klucza API. Sprawdź, czy kod QR do niego należy. Zobacz Uwierzytelnianie.

Co dalej

Dane kodu QR według typu

Personalizacja

Reguły dostępu

Analityka