Codes / Code erstellen

Code erstellen

POST/v1/codes

Erstellt einen Code und gibt ihn mit seinem Kurzlink zurück. Das Ziel eines dynamischen Codes lässt sich später per PATCH ändern, ohne den gedruckten Code anzufassen.

Body-Parameter

namestringerforderlichInterne Bezeichnung des Codes – wird einem Scanner nie angezeigt.

content.typestringerforderlichEiner der unterstützten Code-Typen, z. B. url, vcard, wifi.

content.urlstringerforderlichZiel eines url-Codes. Die Pflichtfelder hängen vom Typ ab.

dynamicbooleanoptionalStandard true: ein Kurzlink, den Sie umstellen können. false kodiert den Inhalt direkt.

designobjectoptionalMuster, Augenform und Farben. Standard ist das Dotwick-Standarddesign.

folderIdstringoptionalOrdner, in den der Code einsortiert wird. Pflicht für auf Ordner beschränkte Schlüssel.

templateIdstringoptionalEine gespeicherte Design-Vorlage, die statt design angewendet wird.

domainIdstring | nulloptionalEigene Kurzlink-Domain (bald verfügbar: eigene Domains sind noch nicht freigeschaltet). Weggelassen = Standard des Arbeitsbereichs; null = die gemeinsame Domain.

slugstringoptionalEin eigener Kurzlink-Slug statt eines erzeugten. Muss auf der Domain eindeutig sein.

Beispielanfrage

AnfragePOST /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"  }'

Antwort201 CreatedAuszug – das vollständige Objekt enthält außerdem Design, Regeln und Zeitstempel

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

Fehler

400validation_failedDer Body hat die Schemaprüfung nicht bestanden – siehe error.details für die Probleme.

401unauthorizedFehlender oder ungültiger Authorization-Header.

403forbiddenDem Schlüssel fehlt codes:write, oder er ist auf andere Ordner beschränkt.

403plan_limit_reachedDas Limit dynamischer Codes des Tarifs ist erreicht.

409conflictDer Slug ist auf dieser Domain bereits vergeben.

422idempotency_conflictDer Idempotency-Key wurde mit einem anderen Body wiederverwendet.

422unsafe_destinationDas Ziel hat die Prüfung gegen Google Web Risk und die Sperrliste nicht bestanden.

429rate_limitedDas Budget pro Minute oder für Spitzen ist überschritten – siehe Retry-After.