API GetQR jest w wersji beta i jest dostępne dla wybranych obszarów roboczych. Szczegóły mogą się zmienić przed ogólną premierą.
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ą zwraca422. - Wiersze. Każdy wiersz wymaga
nameiurl. 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
httplubhttpsz prawdziwą domeną, np.example.com/menu, bez spacji. Adres URL bez schematu dostajehttps://. - Puste wiersze. Wiersze bez nazwy i bez adresu URL są pomijane. Wiersz z tylko jedną z tych wartości jest odrzucany.
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.
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
422 z komunikatem "contains an invalid HTTP(S) URL"
422 z komunikatem "contains an invalid HTTP(S) URL"
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.422 "CSV headers must be exactly: name,url."
422 "CSV headers must be exactly: name,url."
Pierwszy wiersz pliku CSV musi mieć postać
name,url, w tej kolejności i małymi literami, bez innych kolumn.422 "This idempotencyKey was already used with a different request body."
422 "This idempotencyKey was already used with a different request body."
Kluczy nie można ponownie używać dla innej partii. Wyślij nowy
idempotencyKey.409 "The bulk QR archive is not ready for download."
409 "The bulk QR archive is not ready for download."
Masowe tworzenie jeszcze się nie zakończyło. Odpytuj dalej, aż
status będzie miał wartość completed.400 "Cannot cancel a finished bulk QR creation."
400 "Cannot cancel a finished bulk QR creation."
Masowe tworzenie już się zakończyło, więc nie można go wycofać.
403 exceeded_limit
403 exceeded_limit
Twój obszar roboczy jest w planie Single QR, który nie obejmuje masowego tworzenia. Zmień plan na wyższy.
Otrzymałem starsze masowe tworzenie zamiast nowego
Otrzymałem starsze masowe tworzenie zamiast nowego
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.