Batch QR Generation

API reference for generating multiple QR codes in a single request.

Generate multiple QR codes in a single API call. Each item in the batch follows the same schema as a single QR generation request.

Endpoint

POST /api/v1/qr/batch

Scope: storage:upload

Request body

Field	Type	Required	Description
items	array	Yes	Array of QR generation inputs (same schema as single generation)

Each item in the array has:

Field	Type	Required	Description
entityType	string	Yes	Entity type for the QR target
entityId	string	Yes	ID of the entity
options	object	No	QR generation options (size, error correction, colors, UTM)

The maximum number of items per batch is controlled by the QR processor's maxBatchSize setting (default: 100).

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "qrDataUrl": "data:image/png;base64,iVBORw0KGgo...",
        "targetUrl": "https://app.example.com/properties/prop_001",
        "entityType": "PROPERTY",
        "entityId": "prop_001"
      },
      {
        "qrDataUrl": "data:image/png;base64,iVBORw0KGgo...",
        "targetUrl": "https://app.example.com/properties/prop_002",
        "entityType": "PROPERTY",
        "entityId": "prop_002"
      }
    ],
    "totalGenerated": 2,
    "errors": []
  }
}

Field	Type	Description
results	array	Successfully generated QR codes
totalGenerated	number	Count of successfully generated codes
errors	string[]	Error messages for any failed items

Batch generation is partially tolerant -- individual items can fail without failing the entire batch. Check errors for any items that could not be generated.

Examples

Generate QR codes for multiple properties

curl

curl -X POST https://api.platformxe.com/api/v1/qr/batch \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "items": [
      { "entityType": "PROPERTY", "entityId": "prop_001" },
      { "entityType": "PROPERTY", "entityId": "prop_002" },
      { "entityType": "PROPERTY", "entityId": "prop_003" },
      {
        "entityType": "PROPERTY",
        "entityId": "prop_004",
        "options": { "size": "large", "includeUtm": true, "utmCampaign": "flyer-batch" }
      }
    ]
  }'

TypeScript SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const batch = await px.qr.generateBatch({
  items: [
    { entityType: 'PROPERTY', entityId: 'prop_001' },
    { entityType: 'PROPERTY', entityId: 'prop_002' },
    { entityType: 'PROPERTY', entityId: 'prop_003' },
    {
      entityType: 'PROPERTY',
      entityId: 'prop_004',
      options: { size: 'large', includeUtm: true, utmCampaign: 'flyer-batch' },
    },
  ],
});

console.log(batch.totalGenerated);
// 4

console.log(batch.errors.length);
// 0

Python SDK

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

batch = px.qr.generate_batch({
    "items": [
        {"entityType": "PROPERTY", "entityId": "prop_001"},
        {"entityType": "PROPERTY", "entityId": "prop_002"},
        {"entityType": "PROPERTY", "entityId": "prop_003"}
    ]
})

print(f"Generated {batch['totalGenerated']} QR codes")

Mixed entity types

const batch = await px.qr.generateBatch({
  items: [
    { entityType: 'PROPERTY', entityId: 'prop_001' },
    { entityType: 'AGENT', entityId: 'agt_001' },
    { entityType: 'BOOKING', entityId: 'bk_001' },
  ],
});

Error responses

Code	Description
BAD_REQUEST	Empty items array or exceeds maxBatchSize
FORBIDDEN	API key does not have the storage:upload scope
SERVICE_DISABLED	QR processor is disabled for this organization
RATE_LIMITED	Rate limit exceeded