> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Qr

## Worked QR samples

The endpoint list below documents every operation's parameters; this
overlay walks a QR render the way a checkout or loyalty integration
actually uses it: **generate an arbitrary QR → render an SMS deep link →
branch on the script-scheme rejection**. Success envelopes are `{ data,
meta }` when you ask for JSON (`format=json`), and raw binary when you
let the default `image/png` content-type carry the pixels — see [How to
read a worked sample](/guides/using-orbit-samples). Script-execution URL
schemes (`javascript:`, `data:`, `vbscript:`, …) are rejected with 422
even inside a `{ data, meta }` JSON response, so a misrouted user gesture
never becomes a stored XSS.

Every response carries `meta.request_id`. Quote it when you report a
render the SDK will not link to, or a phone number that failed the
normalization the SMS route applies.

### 1. Generate a QR code for arbitrary data

`GET /api/v1/qr/generate` renders a QR for any text or URL payload. It
streams `image/png` bytes by default, or a base64 data URL inside the
standard `{ data, meta }` envelope when you pass `format=json`.
Script-execution URL schemes are rejected with 422.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/qr/generate?data=https%3A%2F%2Fbrand.example%2Fcheckin%2Ftoken&format=json" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/qr/generate?data=https%3A%2F%2Fbrand.example%2Fcheckin%2Ftoken&format=json",
    {
      headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
    },
  );
  console.log(await res.json());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "data": {
    "format": "base64",
    "data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
  },
  "meta": {
    "request_id": "req_qr_generate",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}
```

* `data_url` is a complete `data:image/png;base64,…` — assign it to an
  `<img src>` directly inside the browser, or paste it into a card body
  for an email client that honors inline images.
* A 200 with JSON only asks for the envelope; the bytes are still
  attached per scan, not per poll — recompute is not needed on the
  second party's page view.

### 2. Render an SMS deep-link QR code

`GET /api/v1/qr/sms` renders a QR that encodes an
`sms:<phone>?body=…` deep link — scanning it opens the device's native
SMS composer addressed to the given number with an optional pre-filled
body. The phone number is validated and normalised to E.164 before
rendering.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/qr/sms?phone=%2B14155552671&body=I%20want%20to%20rebook&format=json" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/qr/sms?phone=%2B14155552671&body=I%20want%20to%20rebook&format=json",
    {
      headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
    },
  );
  console.log(await res.json());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "data": {
    "format": "base64",
    "data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
  },
  "meta": {
    "request_id": "req_qr_sms",
    "timestamp": "2026-08-26T12:01:00.000Z"
  }
}
```

* The number is normalised before render — pass a national-format number
  and the route returns the same envelope with E.164 applied.
* A 422 fires when the phone is unrouteable under the numbering plan;
  the rejected input is echoed back, not stored.

### 3. Render a WhatsApp click-to-chat QR code

`GET /api/v1/qr/whatsapp` renders a QR that encodes a
`https://wa.me/<phone>?text=…` click-to-chat deep link — scanning it
opens a WhatsApp chat with the given number and an optional pre-filled
message. The number is validated for a dialable international format.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/qr/whatsapp?phone=%2B14155552671&text=Hi%20I%20want%20a%20demo&format=json" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/qr/whatsapp?phone=%2B14155552671&text=Hi%20I%20want%20a%20demo&format=json",
    {
      headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
    },
  );
  console.log(await res.json());
  ```
</CodeGroup>

### 4. Errors

Errors follow the `{ error, meta }` envelope. The failure every integrator
hits:

**422 — script-scheme rejection.** A payload starting with
`javascript:`, `data:`, `vbscript:` or any non-whitelisted scheme never
reaches the renderer:

```json 422 theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unsupported URL scheme for QR generation.",
    "status": 422
  },
  "meta": {
    "request_id": "req_qr_err",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}
```