Dynamic QR Code API Tutorial

A dynamic QR code API is useful when an application must create many trackable codes without asking someone to use a dashboard for every item. The difficult part is not drawing the square. It is managing destinations, credentials, retries, webhooks, and records so a printed code still works months later. This tutorial uses the current CraftMyQR API documentation and turns it into a production workflow you can reproduce.

You will create one managed code, store the identifiers returned by the API, verify its webhook, and decide which failures deserve a retry. The examples match CraftMyQR’s documented request fields as of October 19, 2026. Check the live documentation before deploying because an API contract can change.

What a Dynamic QR Code API Actually Creates

A static QR generator places the final content directly inside the symbol. A managed workflow instead encodes a short redirect controlled by the service. That separation lets an authorized user change the destination without replacing the printed symbol. It also gives the application a stable record with an ID, slug, state, and scan data.

CraftMyQR’s endpoint is POST https://craftmyqr.com/api/v1/qr-codes. It accepts a destination and management fields, then returns a managed short URL. Use the dynamic QR code page if you want to understand the user-facing workflow before automating it.

This architecture has an operational consequence: your database should treat the returned short URL as the printable asset and the target URL as editable campaign data. Never regenerate a new symbol merely because the destination changed.

Before You Send the First Dynamic QR Code API Request

The current API is available to eligible Business workspaces. Create an API key in the account area, keep it on the server, and send it as a Bearer token. Do not embed the key in browser JavaScript, a mobile application bundle, a public repository, or an automation screenshot.

Prepare these values:

Keep an internal idempotency key even though it is not a documented request field. If your connection drops after CraftMyQR accepted the request, blindly repeating it can create a second managed record. Your own job table can record a request fingerprint, its state, and the returned CraftMyQR ID.

• title: a human-readable name, limited to 80 characters.
• targetUrl: a required HTTP or HTTPS destination.
• folder: an optional grouping label, limited to 40 characters.
• tags: an optional array with no more than eight entries.
• expiresAt: an optional ISO 8601 timestamp or null.
• scanLimit: an optional positive integer or null.

Make a Minimal Request

Start with the smallest valid payload. That makes authentication and validation problems easier to isolate.

Run this server-side cURL command after replacing the environment variable with your secret:

curl -X POST "https://craftmyqr.com/api/v1/qr-codes" -H "Authorization: Bearer $CRAFTMYQR_API_KEY" -H "Content-Type: application/json" -d '{"title":"Autumn menu","targetUrl":"https://example.com/menu"}'

The response includes the managed QR record, including its id, slug, shortUrl, lifecycle state, and scan information. Save the ID and short URL immediately. Your renderer should encode shortUrl, not targetUrl, because the managed redirect is what keeps the printed QR editable.

For Node.js, call fetch from a server route or worker. Set method to POST, add the same two headers, and pass JSON.stringify(payload) as the body. Reject the operation when response.ok is false; do not assume every response body has the success schema.

Validate Before the Network Call

Client-side validation improves the form, but server-side validation protects the queue and your API allowance. Check the URL protocol, character limits, tag count, timestamp format, and positive-integer rule before sending anything.

A practical application also normalizes values. Trim surrounding spaces, remove empty tags, convert an empty expiration field to null, and reject credentials accidentally pasted into a destination. Preserve the original user input separately if audit history matters.

Do not “repair” a malformed URL by silently adding a guessed domain or protocol. Return a clear error that points to the field. Quiet correction can create a perfectly scannable code that directs customers to the wrong place.

Store a Durable Mapping

Many tutorials stop after printing the response. A dependable QR code API integration needs a local mapping table. At minimum, store:

Save the raw success response as structured JSON if your data policy permits it. Avoid logging the Bearer token or full authorization header. The OWASP secrets management guidance explains why secrets need controlled storage, rotation, and auditability.

Handle Errors Without Creating Duplicates

CraftMyQR documents 400, 401, 403, and 429 responses. Treat them differently:

The documented limit is 120 requests per minute by API key and client IP. That is a ceiling, not a target throughput. A queue should smooth bursts, limit concurrency, and surface persistent throttling. Retry only transient failures, and cap attempts so one bad job does not block the queue.

Network timeouts are ambiguous. The server may have created the code even though your application never received the response. Mark the job “unknown,” investigate through your saved identifiers or event stream, and require an operator decision if no deterministic lookup is available. Automatically posting again is convenient but can create duplicate assets.

• 400 Bad Request: fix the payload; an automatic retry with identical data will fail again.
• 401 Unauthorized: stop and check whether the key is missing, malformed, or revoked.
• 403 Forbidden: confirm the workspace and plan have API access.
• 429 Too Many Requests: wait, apply exponential backoff with jitter, and retry within a capped policy.

Verify the Dynamic QR Webhook

CraftMyQR can send a dynamic_qr.created event. The request includes an X-CraftMyQR-Signature header containing a lowercase hexadecimal HMAC-SHA256 digest of the raw request body, calculated with your webhook secret.

Verification must use the raw bytes. If a framework parses JSON and then serializes it again, differences in whitespace or property order can change the digest. Read the body once as bytes, calculate the HMAC, and compare the expected and received values with a timing-safe function. The underlying HMAC construction is standardized in RFC 2104.

A safe receiver follows this order:

Assume delivery can repeat. Make the handler idempotent by storing a unique event key or a hash of stable event fields. A second delivery should update nothing harmful and still receive a successful acknowledgement.

1. Read and retain the raw request body.
2. Read the signature header without transforming it.
3. Compute HMAC-SHA256 with the stored webhook secret.
4. Compare lowercase hexadecimal values in constant time.
5. Reject invalid requests before parsing or writing data.
6. Parse the verified event and record its event identity.
7. Return a success response quickly, then process asynchronously.

Separate Creation, Rendering, and Release

A production pipeline has three different approvals. Creation confirms that the managed record exists. Rendering confirms that the returned short URL has been encoded into an image with an intact quiet zone. Release confirms that the final printed or displayed asset passes representative scans.

That separation prevents an API success from being mistaken for a usable campaign. The ISO/IEC 18004 standard defines the QR symbol, while real delivery adds resizing, compression, screens, printers, and lighting. You can review the standard’s current listing through ISO.

For batch work, write a manifest containing the local item ID, returned short URL, image filename, checksum, and approval state. The bulk QR code generator is useful for manual batches, while the API is better when QR creation belongs inside an application or repeatable job.

Production Checklist

Before releasing your dynamic QR code API integration, verify the following:

Run a small canary batch before opening the queue. Inspect the first records, scan the generated assets, change one destination through the approved management workflow, and confirm that the original printed URL still redirects correctly.

• The API key exists only in server-side secret storage.
• Validation mirrors the documented title, folder, tag, date, and limit rules.
• The database stores both provider ID and printable short URL.
• Timeout handling cannot silently create unlimited duplicates.
• 429 responses use bounded backoff with jitter.
• Webhook verification uses raw bytes and a timing-safe comparison.
• Webhook processing is idempotent.
• Logs redact authorization headers and sensitive destinations.
• The exported symbol encodes the returned shortUrl exactly.
• A human or automated release gate tests the final asset, not only the API response.

What This Tutorial Adds Beyond a Basic API Example

The request itself takes only a few lines. The useful difference is the surrounding control system: an idempotency ledger for ambiguous timeouts, a durable mapping between local work and provider records, raw-body webhook verification, failure-specific retry rules, and separate creation/render/release gates.

Those additions are not performance claims. They are a reproducible implementation pattern derived from the documented CraftMyQR contract and common failure modes in networked jobs. Your monitoring, workload, compliance requirements, and framework will still determine the final design.

Conclusion: Build the Dynamic QR Code API as a Workflow

A dynamic QR code API should produce more than an image. It should create a traceable managed record, preserve the returned short URL, survive retries without uncontrolled duplication, and verify every webhook before processing it. Start with the CraftMyQR API docs, create a canary code, and add the operational controls before increasing volume.

CraftMyQR fits teams that need editable destinations and managed QR records inside an existing application. Use the plans page to confirm current API eligibility, then keep the first integration deliberately small enough to audit end to end.