Codici / Creazione in blocco

Creazione in blocco

POST/v1/codes/bulk

Crea fino a 500 codici di un tipo in una sola richiesta, come esecuzione in background che puoi seguire: le stesse esecuzioni di un caricamento CSV nell’app.

Parametri del corpo

itemsarrayobbligatorioDa 1 a 500 codici. Ognuno è { content, name?, slug?, folder?, fileName?, ref? }.

items[].contentobjectobbligatorioIl contenuto del codice; il suo tipo deve essere uguale a codeType.

items[].refstringfacoltativoIl tuo riferimento (SKU, ID CRM), riportato nelle righe e nel file dei risultati.

items[].folderstringfacoltativoIl nome di una sottocartella sotto folderId, creata se manca.

codeTypestringfacoltativoUn tipo per richiesta. Predefinito url.

dynamicbooleanfacoltativoPredefinito true.

folderIdstring | nullfacoltativoDove vanno i codici. Predefinita la radice dello spazio di lavoro.

templateIdstring | nullfacoltativoIl design di ogni codice. Predefinito il design standard di Dotwick.

exportobject | nullfacoltativoGenera anche uno ZIP al termine dell’esecuzione, per esempio { formats: ["svg", "pdf"] }.

Richiesta di esempio

richiestaPOST /v1/codes/bulk

curl -X POST https://api.dotwick.com/v1/codes/bulk \  -H "Authorization: Bearer sk_live_…" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: fleet-2026-09-batch-3" \  -d '{    "codeType": "url",    "folderId": "fld_8k2m4q7x",    "items": [      {        "name": "Van 15",        "content": {          "type": "url",          "url": "https://example.com/fleet/van-015"        },        "ref": "VAN-015"      },      {        "name": "Van 16",        "content": {          "type": "url",          "url": "https://example.com/fleet/van-016"        },        "ref": "VAN-016"      }    ],    "export": {      "formats": [        "svg",        "pdf"      ]    }  }'

risposta202 Acceptedestratto: l’esecuzione contiene anche opzioni, riepilogo e righe di anteprima

{  "id": "blk_9f24ab7c3e1d5f80",  "status": "queued",  "source": "api",  "codeType": "url",  "dynamic": true,  "counts": {    "total": 2,    "valid": 2,    "invalid": 0,    "created": 0,    "failed": 0,    "canceled": 0  },  "progress": 0,  "folderId": "fld_8k2m4q7x",  "exportId": null,  "createdAt": "2026-09-12T14:03:51.000Z"}

Seguire l’esecuzione

La risposta è 202 Accepted con l’esecuzione. Interroga GET /v1/bulk-imports/{id} finché lo stato non è succeeded, partially_succeeded o failed, poi leggi i codici con GET /v1/bulk-imports/{id}/rows o scarica GET /v1/bulk-imports/{id}/results.csv. Oppure iscriviti a bulk.completed e salta il polling.

Un elemento malformato fa fallire l’intera richiesta con validation_failed a items.N. Gli elementi che falliscono i controlli del database (uno slug già preso) vengono saltati e contati come non validi; gli altri vengono creati. Riprova quelli falliti con POST /v1/bulk-imports/{id}/retry.

Limiti

Un tipo di codice per richiesta: invia una richiesta per tipo. Si applicano il limite di righe in blocco del piano e il suo limite di codici dinamici, e le esecuzioni oltre i lavori simultanei del piano attendono in coda.