API v1

Un’API per codici che restano stampati.

{  "id": "qr_8841ce2mxk",  "type": "url",  "dynamic": true,  "status": "active",  "shortUrl": "https://dotwick.co/Xq7mK2p",  "createdAt": "2026-09-10T09:41:08.000Z"}

Leggi la documentazione

Un’API REST sugli stessi oggetti usati dall’app. Crea codici, cambia le destinazioni, leggi le scansioni ed esporta file pronti per la stampa. Nessun SDK necessario: bastano curl, fetch o requests.

Inizia gratis Leggi la documentazione

inclusa da Pro in su · 60 richieste/min su Pro, 600 su Business

Crea le chiavi nell’app in Impostazioni → API, con solo gli scope che servono.

POST /v1/codes

richiestaPOST /v1/codes

curl -X POST https://api.dotwick.com/v1/codes \  -H "Authorization: Bearer sk_live_…" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: van-014-2026-09-10" \  -d '{    "name": "Van fleet – unit 14",    "content": {      "type": "url",      "url": "https://example.com/fleet/van-014"    },    "design": {      "pattern": "rounded",      "eyes": {        "frame": "circle",        "ball": "circle"      },      "colors": {        "fg": "#18181B",        "bg": "#FFFFFF"      }    },    "folderId": "fld_8k2m4q7x"  }'

risposta201 Createdestratto: l’oggetto completo contiene anche design, regole e timestamp

{  "id": "qr_8841ce2mxk",  "name": "Van fleet – unit 14",  "type": "url",  "dynamic": true,  "status": "active",  "slug": "Xq7mK2p",  "shortUrl": "https://dotwick.co/Xq7mK2p",  "content": {    "type": "url",    "url": "https://example.com/fleet/van-014"  },  "folderId": "fld_8k2m4q7x",  "createdAt": "2026-09-10T09:41:08.000Z"}

api.dotwick.com/v1
REST su JSON
Risorse prevedibili, paginazione a cursore, chiavi di idempotenza su ogni POST. Gli errori arrivano come { error: { code, message, requestId } }.
11 tipi di evento
Webhook
Scansioni, modifiche ai codici, esecuzioni in blocco ed esportazioni completate, stato dei domini e risposte dei moduli. Firmati secondo Standard Webhooks e ritentati per 24 ore.
POST /v1/codes/bulk
In blocco ed esportazioni
Crea fino a 500 codici in una richiesta, poi scaricali in SVG, PNG, PDF o EPS in un unico ZIP generato in background.
api.dotwick.com/openapi.json
OpenAPI
Ogni rotta pubblica è descritta in OpenAPI 3.1, generata dagli stessi contratti con cui l’API valida, e ogni operazione riporta lo scope richiesto.

POST/v1/codes
GET/v1/codes
GET/v1/codes/{id}
PATCH/v1/codes/{id}
DELETE/v1/codes/{id}
POST/v1/codes/bulk
GET/v1/codes/{id}/scans
POST/v1/webhooks

Endpoint

Tutte le rotte che una chiave API può chiamare. Tutto il resto, come fatturazione, membri e gestione delle chiavi, resta nell’app.

Metodo	Percorso	Scope	Scopo
Codici
GET	/v1/codes	codes:read	Elenca i codici, con filtro per cartella, tipo o stato
POST	/v1/codes	codes:write	Crea un codice
GET	/v1/codes/{id}	codes:read	Leggi un codice con il suo design e le sue regole
PATCH	/v1/codes/{id}	codes:write	Cambia destinazione, nome, design e regole
DELETE	/v1/codes/{id}	codes:write	Elimina un codice (il suo link breve risponde 410)
POST	/v1/codes/move	codes:write	Sposta i codici in una cartella
POST	/v1/codes/move-domain	codes:write	Sposta i codici su un altro dominio
POST	/v1/codes/tags	codes:write	Aggiungi o rimuovi tag su molti codici
POST	/v1/codes/{id}/duplicate	codes:write	Duplica un codice
PATCH	/v1/codes/bulk	codes:write	Metti in pausa, riattiva, archivia, assegna tag, sposta o elimina più codici
GET	/v1/utm-presets	codes:read	Elenca i preset UTM salvati
GET	/v1/codes/{id}/versions	codes:read	Cronologia delle destinazioni di un codice
GET	/v1/codes/{id}/activity	codes:read	Feed delle attività di un codice
GET	/v1/codes/{id}/export	codes:read	Scarica in SVG, PNG, JPG, PDF o EPS
GET	/v1/codes/{id}/hosted-stats	codes:read	Contatori di un codice ospitato
GET	/v1/codes/{id}/submissions	submissions:read	Risposte a un codice modulo
GET	/v1/codes/{id}/submissions/export	submissions:read	Risposte del modulo in CSV
GET	/v1/gs1/products	codes:read	Elenca i prodotti GS1 (i codici gs1)
GET	/v1/codes/{id}/gs1/qualifiers	codes:read	Livelli di lotto, CPV e seriale di un codice GS1
GET	/v1/codes/{id}/gs1/print-runs	codes:read	Tirature di un codice GS1
GET	/v1/codes/{id}/gs1/print-runs/{runId}	codes:read	Controlla una tiratura e ottieni i link ai file
Esecuzioni in blocco
POST	/v1/codes/bulk	codes:write	Crea fino a 500 codici in un’unica esecuzione
GET	/v1/bulk-imports	codes:read	Elenca le esecuzioni in blocco
GET	/v1/bulk-imports/{id}	codes:read	Controlla un’esecuzione in blocco
GET	/v1/bulk-imports/{id}/rows	codes:read	Righe di un’esecuzione in blocco
GET	/v1/bulk-imports/{id}/results.csv	codes:read	Risultati di un’esecuzione in CSV
POST	/v1/bulk-imports/{id}/cancel	codes:write	Annulla un’esecuzione in coda o in corso
POST	/v1/bulk-imports/{id}/retry	codes:write	Riprova le righe non riuscite di un’esecuzione
Statistiche
GET	/v1/analytics/summary	analytics:read	Totali delle scansioni per un intervallo
GET	/v1/analytics/timeseries	analytics:read	Scansioni nel tempo
GET	/v1/analytics/breakdown	analytics:read	Paesi, dispositivi e altro più frequenti
GET	/v1/analytics/scans	analytics:read	Record di ogni scansione
GET	/v1/analytics/sparklines	analytics:read	Conteggi giornalieri per i codici
GET	/v1/analytics/compare	analytics:read	Confronta fino a 4 codici
GET	/v1/analytics/export	analytics:read	Scansioni in CSV (intervalli brevi)
POST	/v1/analytics/exports	analytics:read	Scansioni in CSV, preparate in background
GET	/v1/codes/{id}/analytics/summary	analytics:read	Totali di un codice
GET	/v1/codes/{id}/analytics/timeseries	analytics:read	Un codice nel tempo
GET	/v1/codes/{id}/analytics/breakdown	analytics:read	Le classifiche di un codice
GET	/v1/codes/{id}/scans	analytics:read	Record di ogni scansione di un codice
GET	/v1/codes/{id}/gs1/batches	analytics:read	Scansioni per lotto di un codice GS1
GET	/v1/codes/{id}/downloads	analytics:read	Download per file di un codice Documenti
GET	/v1/analytics/locations	analytics:read	Mappa GPS delle scansioni con consenso
GET	/v1/codes/{id}/analytics/locations	analytics:read	Mappa GPS di un codice
GET	/v1/alerts	analytics:read	Elenca le regole di avviso sulle scansioni
Esportazioni
POST	/v1/exports	codes:read	Esporta molti codici in un unico ZIP
GET	/v1/exports	codes:read	Elenca le esportazioni
GET	/v1/exports/{id}	codes:read	Controlla un’esportazione e ottieni il link allo ZIP
Cartelle
GET	/v1/folders	folders:read	Elenca le cartelle
POST	/v1/folders	folders:write	Crea una cartella
GET	/v1/folders/{id}	folders:read	Leggi una cartella
PATCH	/v1/folders/{id}	folders:write	Rinomina o sposta una cartella
DELETE	/v1/folders/{id}	folders:write	Elimina una cartella (i codici salgono di livello)
Modelli
GET	/v1/templates	templates:read	Elenca i modelli di design
POST	/v1/templates	templates:write	Crea un modello
GET	/v1/templates/{id}	templates:read	Leggi un modello
PATCH	/v1/templates/{id}	templates:write	Modifica un modello
DELETE	/v1/templates/{id}	templates:write	Elimina un modello
Caricamenti
POST	/v1/assets	codes:write	Carica un logo o un file
GET	/v1/assets/{id}	codes:read	Leggi un caricamento con un URL firmato
Domini
GET	/v1/domains	domains:read	Elenca i domini personalizzati
GET	/v1/domains/{id}	domains:read	Leggi un dominio e il suo stato
GET	/v1/subdomain	domains:read	Il sottodominio dello spazio di lavoro e i suoi link
GET	/v1/subdomain/availability	domains:read	Verifica se un nome di sottodominio è libero
Spazio di lavoro
GET	/v1/workspaces/current	qualsiasi chiave	Lo spazio di lavoro della chiave e il suo piano
GET	/v1/usage	qualsiasi chiave	Limiti del piano e utilizzo del mese
Webhook
GET	/v1/webhooks	webhooks:read	Elenca gli endpoint webhook
POST	/v1/webhooks	webhooks:write	Registra un endpoint e i tipi di evento
GET	/v1/webhooks/{id}	webhooks:read	Leggi un endpoint
PATCH	/v1/webhooks/{id}	webhooks:write	Modifica o riattiva un endpoint
DELETE	/v1/webhooks/{id}	webhooks:write	Elimina un endpoint
POST	/v1/webhooks/{id}/test	webhooks:write	Invia un evento webhook.test
GET	/v1/webhooks/{id}/deliveries	webhooks:read	Consegne di un endpoint
GET	/v1/webhooks/{id}/deliveries/{deliveryId}	webhooks:read	Una consegna con i suoi tentativi
POST	/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver	webhooks:write	Invia di nuovo una consegna
POST	/v1/webhooks/{id}/recover	webhooks:write	Reinvia le consegne non riuscite
Tag
GET	/v1/tags	tags:read	Elenca i tag
POST	/v1/tags	tags:write	Crea un tag
GET	/v1/tags/{id}	tags:read	Leggi un tag
PATCH	/v1/tags/{id}	tags:write	Rinomina un tag o cambia colore
DELETE	/v1/tags/{id}	tags:write	Elimina un tag (viene rimosso dai suoi codici)
Report
POST	/v1/reports	analytics:read	Genera un report di statistiche in PDF o CSV
GET	/v1/reports	analytics:read	Elenca i report generati
GET	/v1/reports/{id}	analytics:read	Controlla un report e ottieni il link
Hook Zapier e Make
GET	/v1/hooks	webhooks:read	Elenca gli hook di integrazione
POST	/v1/hooks	webhooks:write	Iscrivi un hook a un evento
DELETE	/v1/hooks/{id}	webhooks:write	Annulla l’iscrizione di un hook
GET	/v1/hooks/samples/{event}	webhooks:read	Eventi recenti di un tipo, come esempio per un trigger
Biglietti da visita
GET	/v1/cards	cards:read	Elenca i biglietti da visita del team
POST	/v1/cards	cards:write	Crea un biglietto da visita
GET	/v1/cards/{id}	cards:read	Leggi un biglietto da visita
PATCH	/v1/cards/{id}	cards:write	Modifica un biglietto da visita
POST	/v1/cards/{id}/deactivate	cards:write	Disattiva un biglietto da visita
GET	/v1/cards/{id}/analytics	cards:read	Visualizzazioni, salvataggi e tocchi di un biglietto
Conversioni
POST	/v1/conversions	conversions:write	Registra una conversione
GET	/v1/analytics/funnel	analytics:read	Funnel dalla scansione al ricavo
Tag NFC
GET	/v1/nfc/tags	codes:read	Elenca i tag NFC
POST	/v1/nfc/tags	codes:write	Registra un tag NFC su un codice

Gli schemi di richiesta e risposta di ogni rotta sono nel riferimento API e nel documento OpenAPI. Riferimento API →

Limiti di richieste

Pro: 60 richieste/min · burst 20 / 10 s
Business: 600 richieste/min · burst 200 / 10 s
Enterprise: su misura
Job di esportazione e in blocco · Pro / Business: 2 simultanee / 5 simultanee

I limiti valgono per spazio di lavoro e sono condivisi da tutte le sue chiavi API
Burst: al massimo 2× il ritmo al minuto in 10 secondi
Le risposte 429 includono Retry-After in secondi
Ogni risposta include X-RateLimit-Limit, -Remaining e -Reset (secondi alla fine della finestra)
Ogni POST accetta un header Idempotency-Key, rispettato per 24 ore

Limiti di richieste nel dettaglio →

Autenticazione

Invia la tua chiave segreta come bearer token. Le chiavi iniziano con sk_live_, si mostrano una sola volta alla creazione, hanno degli scope e agiscono nel loro spazio di lavoro con il ruolo di chi le ha create, al massimo Editor.

Autenticazione e scope →

Un’API per codici che restano stampati.

REST su JSON

Webhook

In blocco ed esportazioni

OpenAPI

Endpoint