GetQR API je v beta verzi a je dostupné pro vybrané pracovní prostory. Do obecného vydání se podrobnosti mohou změnit.
Jak to funguje
1
Spusťte hromadné vytváření
Pošlete své řádky pomocí vytvoření z JSON nebo vytvoření ze souboru CSV. API odpoví
202 s hromadným vytvářením a jeho id.2
Sledujte průběh
Každých pár sekund volejte získání hromadného vytváření, dokud
status nebude completed nebo failed.3
Stáhněte archiv
Když je
status rovno completed, zavolejte stažení archivu a získáte ZIP s obrázky QR kódů.- Limit. Nejvýše 100 řádků na jedno hromadné vytváření.
- Jedno po druhém. V pracovním prostoru běží vždy jen jedno hromadné vytváření. Pokus o spuštění dalšího, zatímco jedno běží, vrátí to běžící.
- Idempotence. Každý požadavek potřebuje
idempotencyKey. Zopakování požadavku se stejným klíčem a stejným tělem vrátí už spuštěné hromadné vytváření. Stejný klíč s jiným tělem vrátí422. - Řádky. Každý řádek potřebuje
nameaurl. Viz Řádky. - Tarif. Hromadné vytváření není v tarifu Single QR k dispozici: požadavek vrátí
403 exceeded_limit.
Řádky
- Název. Stane se názvem QR kódu. Ořízne se a zkrátí na 40 znaků. Opakované názvy (bez ohledu na velikost písmen) dostanou číslo:
Menu,Menu 2,Menu 3. - URL. Stane se cílem. Musí to být adresa
httpnebohttpsse skutečnou doménou, napříkladexample.com/menu, a nesmí obsahovat mezery. URL bez schématu dostanehttps://. - Prázdné řádky. Řádky bez názvu i bez URL se přeskočí. Řádek, který má jen jedno z nich, se odmítne.
website s krátkým odkazem. Viz Typy QR kódů.
Hlavičky
string
application/json pro vytvoření z JSON, multipart/form-data pro vytvoření ze souboru CSV.Objekt hromadného vytváření
string
ID hromadného vytváření, například
cm2k7x9qb0003ax8eb4f6gh2t.string
queued, processing, packaging nebo completed. Neúspěšné nebo přerušené hromadné vytváření přejde přes rollingBack do stavu failed.string
Název zdrojového souboru.
integer
Počet řádků.
integer
Dosud vytvořené QR kódy.
integer
Dosud vykreslené obrázky QR kódů.
integer
Celkový průběh, 0 až 100. Vytváření zabere až 40, vykreslování až 90, balení je 95 a
completed je 100.boolean
true, když běžící hromadné vytváření 2 minuty nepokročilo. Pokračujte v dotazování: získání hromadného vytváření zaseknuté hromadné vytváření znovu spustí.object | null
Když je
status rovno failed: code a message. Přerušené hromadné vytváření má kód cancelled_by_user. Neúspěšné hromadné vytváření se vrátí zpět, takže se žádný z jeho QR kódů nezachová.string | null
Cesta ke stažení archivu, jakmile je
status rovno completed.string
Datum spuštění, ISO 8601.
string
Datum poslední změny, ISO 8601.
string | null
Datum dokončení, ISO 8601.
string | null
Datum selhání, ISO 8601.
Získání aktuálního hromadného vytváření
GET /api/v1/bulk-qr-creations
Vrátí hromadné vytváření, které ve vašem pracovním prostoru ještě běží. Pokud žádné neběží, vrací poslední dokončené (completed nebo failed), dokud ho nezavřete: zavře ho stažení archivu nebo jeho zavření v dashboardu. Jinak vrátí null. Použijte ho k obnovení sledování po restartu.
Vytvoření z JSON
POST /api/v1/bulk-qr-creations
Spustí hromadné vytváření ze seznamu řádků. Odpoví 202 Accepted. Hromadné vytváření běží na pozadí.
object[]
povinné
QR kódy k vytvoření, nejvýše 100. Každý řádek má tvar
{ "name": "...", "url": "..." } a nepřijímá žádná další pole. Viz Řádky.object
povinné
Design použitý pro všechny QR kódy:
styles, frameOptions a logoOptions, všechny nepovinné. Pro výchozí design pošlete {}. Jiná pole se odmítnou. Viz Přizpůsobení.string
povinné
Název zobrazený v dashboardu a použitý pro archiv, 1 až 255 znaků.
string
povinné
Váš vlastní klíč pro toto hromadné vytváření, 8 až 100 znaků.
Vytvoření ze souboru CSV
POST /api/v1/bulk-qr-creations/csv
Totéž jako vytvoření z JSON, ale řádky přijímá jako soubor CSV odeslaný jako multipart/form-data. Odpoví 202 Accepted.
Soubor musí být .csv o velikosti nejvýše 1 000 000 bajtů. Jeho záhlaví musí být přesně name,url a po něm může následovat nejvýše 100 datových řádků. Viz Formát CSV.
file
povinné
Soubor CSV.
string
povinné
Objekt designu serializovaný jako JSON, například
{"styles":{"dotsOptions":{"type":"rounded"}}}. Pro výchozí design pošlete {}.string
povinné
Váš vlastní klíč pro toto hromadné vytváření, 8 až 100 znaků.
string
Název zobrazený v dashboardu a použitý pro archiv, nejvýše 255 znaků. Výchozí hodnota je název nahraného souboru.
Získání hromadného vytváření
GET /api/v1/bulk-qr-creations/{id}
Vrátí stav a průběh hromadného vytváření. Dotazujte se, dokud je status rovno queued, processing nebo packaging. Jakmile je archiv připravený, objeví se downloadUrl.
string
povinné
ID hromadného vytváření. Najdete ho v odpovědi na vytvoření nebo na získání aktuálního hromadného vytváření.
Přerušení hromadného vytváření
DELETE /api/v1/bulk-qr-creations/{id}
Zastaví běžící hromadné vytváření a smaže QR kódy, které už vytvořilo. Vrácení zpět proběhne během požadavku, takže odpověď má obvykle status failed a error.code cancelled_by_user. Přerušení hromadného vytváření, které už selhalo, ho vrátí beze změny.
string
povinné
ID hromadného vytváření.
Stažení archivu
GET /api/v1/bulk-qr-creations/{id}/download
Vrátí archiv ZIP s jedním obrázkem JPEG o velikosti 1024 px na každý QR kód, pojmenovaným podle jeho řádku: 001-Menu.jpg, 002-Wine list.jpg a tak dále. Archiv je pojmenovaný podle sourceFilename. K dispozici, jakmile je status rovno completed. Stažení hromadné vytváření zavře, takže ho získání aktuálního hromadného vytváření přestane vracet.
string
povinné
ID hromadného vytváření.
Časté problémy
422 s "contains an invalid HTTP(S) URL"
422 s "contains an invalid HTTP(S) URL"
Zpráva uvádí řádek. Každá URL musí být adresa
http nebo https se skutečnou doménou, například example.com/menu. Opravte řádek a pošlete požadavek znovu.422 "CSV headers must be exactly: name,url."
422 "CSV headers must be exactly: name,url."
První řádek CSV musí být
name,url, v tomto pořadí, malými písmeny a bez dalších sloupců.422 "This idempotencyKey was already used with a different request body."
422 "This idempotencyKey was already used with a different request body."
Klíče nelze znovu použít pro jinou dávku. Pošlete nový
idempotencyKey.409 "The bulk QR archive is not ready for download."
409 "The bulk QR archive is not ready for download."
Hromadné vytváření ještě není dokončené. Pokračujte v dotazování, dokud
status nebude completed.400 "Cannot cancel a finished bulk QR creation."
400 "Cannot cancel a finished bulk QR creation."
Hromadné vytváření už je dokončené, takže ho nelze vrátit zpět.
403 exceeded_limit
403 exceeded_limit
Váš pracovní prostor má tarif Single QR, který hromadné vytváření nezahrnuje. Přejděte na vyšší tarif.
Místo nového hromadného vytváření se vrátilo starší
Místo nového hromadného vytváření se vrátilo starší
Ve vašem pracovním prostoru ještě běží jiné hromadné vytváření, nebo jste znovu použili
idempotencyKey. Počkejte, až doběhne, nebo použijte nový klíč.