Codici / Crea un codice

Crea un codice

POST/v1/codes

Crea un codice e lo restituisce con il suo link breve. La destinazione di un codice dinamico si può cambiare poi con PATCH senza toccare il codice stampato.

Parametri del corpo

namestringobbligatorioEtichetta interna del codice: non viene mai mostrata a chi scansiona.

content.typestringobbligatorioUno dei tipi di codice supportati, per esempio url, vcard, wifi.

content.urlstringobbligatorioDestinazione per un codice url. I campi obbligatori variano per tipo.

dynamicbooleanfacoltativoPredefinito true: un link breve che puoi riassegnare. false codifica direttamente il contenuto.

designobjectfacoltativoMotivo, forma degli occhi e colori. Predefinito il design standard di Dotwick.

folderIdstringfacoltativoCartella in cui archiviare il codice. Obbligatoria per le chiavi limitate a cartelle.

templateIdstringfacoltativoUn modello di design salvato da applicare al posto di design.

domainIdstring | nullfacoltativoDominio breve personalizzato (in arrivo: i domini personalizzati non sono ancora attivi). Omesso = quello predefinito dello spazio di lavoro; null = il dominio condiviso.

slugstringfacoltativoUno slug breve personalizzato al posto di uno generato. Deve essere univoco sul dominio.

Richiesta di esempio

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"}

Errori

400validation_failedIl corpo non ha superato la validazione dello schema: vedi error.details per i problemi.

401unauthorizedHeader Authorization mancante o non valido.

403forbiddenLa chiave non ha codes:write, o è limitata ad altre cartelle.

403plan_limit_reachedIl limite di codici dinamici del piano è stato raggiunto.

409conflictLo slug è già preso su questo dominio.

422idempotency_conflictL’Idempotency-Key è stata riutilizzata con un corpo diverso.

422unsafe_destinationLa destinazione non ha superato il controllo Google Web Risk / lista di blocco.

429rate_limitedSuperato il budget al minuto o di burst: vedi Retry-After.