QR Code API and Webhooks
The API lets your own software create, update, read and delete QR codes, and read their scan summaries. Webhooks send a signed notice to your server when a code changes, a human scan arrives or a landing page form is answered.
What the API and webhooks do
The REST API lives under the /api/v1 path and answers in JSON. It can list codes with a search, a tag filter and pages of up to one hundred, read one code, create, update and delete codes, return a plain SVG of a code, and summarise the last thirty days of scans. A key is a bearer token that starts with qrk_ and belongs to one workspace, so a request can only touch that workspace's codes.
A webhook is an HTTPS address that you register with the events you want to hear about. The app posts a JSON message for each event: a code is created, updated or deleted, a human scan is recorded, or a landing page form is answered. A test action sends a ping event, so you can check your receiver before real traffic arrives. Each delivery is signed with HMAC-SHA256 using the webhook secret, over the timestamp and the body.
The API is for people who build integrations, and it does not change how codes look. The SVG is plain black and white with no logo, shape or color, because styled images come from the editor. The API needs the Team plan. Keys survive a downgrade, but they stop working until the workspace is back on a plan that includes the API.
How to start using the API
-
01
Create a key as an owner
Open the API page as an owner, give the key a name such as the server that will use it, and create it. The full token appears once, so copy it into your secret store straight away. Afterwards the page shows only the name, the prefix, the creation date and the last use.
-
02
Send the key with each request
Send the token in an Authorization header, with the word Bearer, a space and the token. Call the account check first: the answer names the workspace, the key and the credits left, which confirms that the setup works. A missing or wrong key receives an unauthorized answer.
-
03
Create, update and read codes
Send the name, the kind (the default is a web link), the content and the optional fields: dynamic, slug, expiry, password, a verified domain, tags and style. Creating a code costs one credit, while reading and updating are free. A request that fails validation returns the reasons and gives the credit back.
Where the API fits
-
Ticketing and bookings
When a booking system confirms a seat, it creates a dynamic code for that ticket and sends the short link and the SVG to the buyer. The email or the wallet pass carries the same code, and no one copies it by hand.
-
Stock and asset tags
A warehouse system can create one code per item, with the item number as a tag. Each scan is recorded, and the system can read the thirty-day summary of any item to see which tags were checked recently.
-
Restaurant menus from a spreadsheet
A script can read a spreadsheet of menu links and update the content of each dynamic code through the API. The printed codes stay the same, and the update applies from the next scan.
-
Event check-in and feedback forms
An events team can publish a landing page with a form and receive a webhook for each answer. A separate system reacts to the event, so nobody has to poll the responses.
-
Monitoring and alerts
A webhook receiver can store scan events by country and device and raise a message when a code stops being scanned. Your system decides what counts as a problem, because the app delivers the events and does not judge them.
Tips for a reliable integration
- Store the key like a password
- Keys are shown once and kept only as a digest, so the app cannot show them again. If a key leaks, revoke it from the API page and create a new one. Revoking stops every request that uses the old token at once.
- Respect the rate limit and the credits
- Each key may send 120 requests a minute. A request above that rate receives a too-many-requests answer. When credits run out, creating a code returns a payment-required answer whose error code says that no credits are left. The app has no way to buy more credits yet, so plan batch jobs around the balance.
- Verify signatures and timestamps
- Compute the HMAC-SHA256 of the timestamp, a dot and the raw body with your secret, and compare it with the signature header. Reject timestamps that are too old, so a captured request cannot be replayed, and use the delivery identifier to ignore a repeat.
- Use an endpoint you control
- Webhook addresses must be HTTPS, must not carry credentials and must resolve to public addresses. Local hosts and private network ranges are refused, and redirects are not followed. A failed delivery is retried up to five times with growing waits.
Questions about the API and webhooks
Which plan includes the API?
The Team plan. Creating keys and webhooks requires it, and the API answers with a payment-required status when the workspace is on a plan without it. Existing keys are kept through a downgrade, so they start working again when the plan returns.
What does a credit pay for?
One credit is spent for each code created through the API. Reading, updating, deleting codes and reading the scan summary cost nothing. If a creation fails validation, the credit goes back.
How many credits does a workspace start with?
Forty, which is the default value in the database for each workspace. The app has no page to buy more yet, so check the balance on the API page or with the account request before a large import.
Can I get the code as an image from the API?
Yes, as a plain SVG. You choose the module size from one to twenty and the margin from zero to ten. The image is black and white without a logo, and if the content is too long for a QR code the API says so. For shapes, colors or a logo, use the editor.
Which events can I subscribe to?
Creation, update and deletion of a code, a human scan and a landing page form answer. Bot requests and link previews do not trigger scan events, and a test event can be sent to any webhook.
What happens when my endpoint is down?
The delivery is retried up to five times with growing waits, and each attempt has a connect timeout of five seconds and a read timeout of ten. After the last failure the delivery is marked as failed, and the webhooks page shows the response code and the last error.
Направете първия си код за минута
Редакторът е безплатен. Добавете профил, когато поискате да запазвате кодове, да следите сканиранията или да смените целевия адрес по-късно.