API GetQR jest w wersji beta i jest dostępne dla wybranych obszarów roboczych. Szczegóły mogą się zmienić przed ogólną premierą.
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.
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.string | null
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.object | null
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.
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.
string
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.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.object
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.Ponowienia i duplikaty
- Z kluczem. Z nagłówkiem
Idempotency-Keyodpowiedź 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 zwracafalse. - 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.
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.
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.
templateId. Nieakceptowane.link. Częściowe. Gdy pominieszlink.url, obecny cel zostaje zachowany.link.domainilink.keydostają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ędatalubqrType. ZmianaqrTypebez pasującegodatajest odrzucana. Zobacz Zmiana typu.- Projekt.
styles,frameOptionsilogoOptionssą 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.nullusuwa regułę. Reguły dostępu należą doaccess: wysłanie ich wlinkzwraca422.archived. Wstrzymuje lub ponownie aktywuje kod QR razem z jego krótkim linkiem, tak jak wstrzymanie i ponowna aktywacja.
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.
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-Dispositioni jest tworzona z tytułu albo jakoqr-codedla kodu QR bez tytułu. - Buforowanie. Odpowiedzi zawierają
ETagiCache-Control: private, max-age=3600, must-revalidate. OdeślijETagwIf-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_unsupportedlubqr_download_art_resolution_unsupported.
Reguły dostępu
Wyślij obiektaccess 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
422 przy ustawianiu hasła, harmonogramu lub limitu skanowań
422 przy ustawianiu hasła, harmonogramu lub limitu skanowań
Wyślij regułę w
access, a nie w link.422 przy zmianie link.domain lub link.key
422 przy zmianie link.domain lub link.key
Krótkiego linku nie można zmienić po utworzeniu, ponieważ koduje go wydrukowany kod. Zamiast tego utwórz nowy kod QR.
422 "Expected … for qrType"
422 "Expected … for qrType"
data nie pasuje do formatu qrType. Sprawdź typ na stronie Dane kodu QR według typu.409 conflict przy tworzeniu kodu QR
409 conflict przy tworzeniu kodu QR
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.Pobrany plik to JPEG, a nie PNG
Pobrany plik to JPEG, a nie PNG
Parametry to
format i resolution, a format ma domyślnie wartość jpg. Wyślij format=png.404 dla kodu QR, który widzę w panelu
404 dla kodu QR, który widzę w panelu
Każde żądanie jest wykonywane w obszarze roboczym Twojego klucza API. Sprawdź, czy kod QR do niego należy. Zobacz Uwierzytelnianie.