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ą.
Masowe tworzenie zamienia listę nazw i adresów URL w kody QR typu Website ze wspólnym projektem. Działa w tle: uruchom je, odpytuj o postęp, a potem pobierz archiwum ZIP.

Jak to działa

1

Uruchom masowe tworzenie

Wyślij wiersze przez tworzenie z JSON lub tworzenie z pliku CSV. API odpowiada 202 i zwraca masowe tworzenie z jego id.
2

Odpytuj o postęp

Co kilka sekund wywołuj odczyt masowego tworzenia, aż status będzie miał wartość completed lub failed.
3

Pobierz archiwum

Gdy status ma wartość completed, wywołaj pobieranie archiwum, aby otrzymać plik ZIP z obrazami kodów QR.
  • Limit. Do 100 wierszy na jedno masowe tworzenie.
  • Jedno naraz. W obszarze roboczym działa naraz tylko jedno masowe tworzenie. Próba uruchomienia kolejnego, gdy jedno trwa, zwraca to, które trwa.
  • Idempotentność. Każde żądanie wymaga idempotencyKey. Powtórzenie żądania z tym samym kluczem i tą samą treścią zwraca już uruchomione masowe tworzenie. Ten sam klucz z inną treścią zwraca 422.
  • Wiersze. Każdy wiersz wymaga name i url. Zobacz Wiersze.
  • Plan. Masowe tworzenie nie jest dostępne w planie Single QR: żądanie zwraca 403 exceeded_limit.

Wiersze

  • Nazwa. Staje się tytułem kodu QR. Spacje na początku i końcu są usuwane, a nazwa jest obcinana do 40 znaków. Powtarzające się nazwy (bez względu na wielkość liter) dostają numer: Menu, Menu 2, Menu 3.
  • URL. Staje się celem. Musi to być adres http lub https z prawdziwą domeną, np. example.com/menu, bez spacji. Adres URL bez schematu dostaje https://.
  • Puste wiersze. Wiersze bez nazwy i bez adresu URL są pomijane. Wiersz z tylko jedną z tych wartości jest odrzucany.
Każdy kod QR jest kodem QR typu website z krótkim linkiem. Zobacz Typy kodów QR.

Nagłówki

string
wymagane
Bearer, a po nim Twój klucz API. Zobacz Uwierzytelnianie.
string
application/json dla tworzenia z JSON, multipart/form-data dla tworzenia z pliku CSV.

Obiekt masowego tworzenia

string
ID masowego tworzenia, np. cm2k7x9qb0003ax8eb4f6gh2t.
string
queued, processing, packaging lub completed. Nieudane lub przerwane masowe tworzenie przechodzi przez rollingBack do failed.
string
Nazwa pliku źródłowego.
integer
Liczba wierszy.
integer
Liczba kodów QR utworzonych do tej pory.
integer
Liczba obrazów kodów QR wyrenderowanych do tej pory.
integer
Ogólny postęp, od 0 do 100. Tworzenie zajmuje do 40, renderowanie do 90, pakowanie to 95, a completed to 100.
boolean
true, gdy trwające masowe tworzenie nie zrobiło postępu przez 2 minuty. Odpytuj dalej: odczyt masowego tworzenia wznawia zablokowane masowe tworzenie.
object | null
Gdy status ma wartość failed: code i message. Przerwane masowe tworzenie ma kod cancelled_by_user. Nieudane masowe tworzenie jest wycofywane, więc żaden z jego kodów QR nie zostaje zachowany.
string | null
Ścieżka do pobierania archiwum, gdy status ma wartość completed.
string
Data rozpoczęcia, ISO 8601.
string
Data ostatniej aktualizacji, ISO 8601.
string | null
Data zakończenia, ISO 8601.
string | null
Data niepowodzenia, ISO 8601.

Bieżące masowe tworzenie

GET /api/v1/bulk-qr-creations Zwraca masowe tworzenie, które wciąż trwa w Twoim obszarze roboczym. Gdy żadne nie trwa, zwraca ostatnie zakończone (completed lub failed), dopóki nie zostanie zamknięte: robi to pobranie jego archiwum lub zamknięcie go w panelu. W przeciwnym razie zwraca null. Użyj go, aby wznowić śledzenie po ponownym uruchomieniu.

Tworzenie z JSON

POST /api/v1/bulk-qr-creations Uruchamia masowe tworzenie z listy wierszy. Odpowiada 202 Accepted. Masowe tworzenie działa w tle.
object[]
wymagane
Kody QR do utworzenia, do 100. Każdy wiersz to { "name": "...", "url": "..." } i nie przyjmuje innych pól. Zobacz Wiersze.
object
wymagane
Projekt stosowany do każdego kodu QR: styles, frameOptions i logoOptions, wszystkie opcjonalne. Wyślij {} dla projektu domyślnego. Inne pola są odrzucane. Zobacz Personalizacja.
string
wymagane
Nazwa wyświetlana w panelu i używana dla archiwum, od 1 do 255 znaków.
string
wymagane
Twój własny klucz dla tego masowego tworzenia, od 8 do 100 znaków.

Tworzenie z pliku CSV

POST /api/v1/bulk-qr-creations/csv Działa tak samo jak tworzenie z JSON, ale przyjmuje wiersze jako plik CSV wysłany jako multipart/form-data. Odpowiada 202 Accepted. Plik musi mieć format .csv i rozmiar najwyżej 1 000 000 bajtów. Jego wiersz nagłówka musi mieć dokładnie postać name,url, a po nim może być do 100 wierszy danych. Zobacz Format CSV.
file
wymagane
Plik CSV.
string
wymagane
Obiekt projektu zserializowany do JSON, np. {"styles":{"dotsOptions":{"type":"rounded"}}}. Wyślij {} dla projektu domyślnego.
string
wymagane
Twój własny klucz dla tego masowego tworzenia, od 8 do 100 znaków.
string
Nazwa wyświetlana w panelu i używana dla archiwum, do 255 znaków. Domyślnie nazwa przesłanego pliku.

Odczyt masowego tworzenia

GET /api/v1/bulk-qr-creations/{id} Zwraca status i postęp masowego tworzenia. Odpytuj ten endpoint, dopóki status ma wartość queued, processing lub packaging. downloadUrl pojawia się, gdy archiwum jest gotowe.
string
wymagane
ID masowego tworzenia. Weź je z odpowiedzi tworzenia lub odczytu bieżącego masowego tworzenia.

Przerywanie masowego tworzenia

DELETE /api/v1/bulk-qr-creations/{id} Zatrzymuje trwające masowe tworzenie i usuwa kody QR, które już utworzyło. Wycofanie odbywa się w trakcie żądania, więc odpowiedź zwykle ma status równy failed i error.code równy cancelled_by_user. Przerwanie masowego tworzenia, które już się nie powiodło, zwraca je bez zmian.
Zakończonego masowego tworzenia nie można przerwać: żądanie zwraca 400. Zamiast tego usuń jego kody QR pojedynczo przez Kody QR.
string
wymagane
ID masowego tworzenia.

Pobieranie archiwum

GET /api/v1/bulk-qr-creations/{id}/download Zwraca archiwum ZIP z jednym plikiem JPEG 1024 px na każdy kod QR, nazwanym według wiersza: 001-Menu.jpg, 002-Wine list.jpg i tak dalej. Nazwa archiwum pochodzi od sourceFilename. Dostępne, gdy status ma wartość completed. Pobranie zamyka masowe tworzenie, więc bieżące masowe tworzenie przestaje je zwracać.
string
wymagane
ID masowego tworzenia.

Typowe problemy

Komunikat wskazuje wiersz. Każdy adres URL musi być adresem http lub https z prawdziwą domeną, np. example.com/menu. Popraw wiersz i wyślij żądanie ponownie.
Pierwszy wiersz pliku CSV musi mieć postać name,url, w tej kolejności i małymi literami, bez innych kolumn.
Kluczy nie można ponownie używać dla innej partii. Wyślij nowy idempotencyKey.
Masowe tworzenie jeszcze się nie zakończyło. Odpytuj dalej, aż status będzie miał wartość completed.
Masowe tworzenie już się zakończyło, więc nie można go wycofać.
Twój obszar roboczy jest w planie Single QR, który nie obejmuje masowego tworzenia. Zmień plan na wyższy.
W Twoim obszarze roboczym wciąż trwa inne masowe tworzenie albo ponownie użyłeś idempotencyKey. Poczekaj, aż się zakończy, lub użyj nowego klucza.

Co dalej

Personalizacja

Kody QR

Masowe tworzenie w aplikacji

Format CSV