API de códigos QR

Descripción general

La API de códigos es el núcleo de qr3.app. Con ella puedes crear, actualizar y eliminar códigos QR dinámicos y estáticos.

URL base: https://qr3.app/v1/codes

Crear código QR

`POST /v1/codes`

curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "Mein erster QR-Code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'Mein erster QR-Code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "Mein QR-Code" --tags marketing,q1

Respuesta (HTTP 201):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "target_url": "https://example.com",
    "is_dynamic": true,
    "status": "live",
    "tags": ["marketing", "q1"],
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz123" }
}

Tipos de códigos QR

Tipo	Descripción	Campos obligatorios
`url`	URL del sitio web (dinámica o estática)	`url`
`vcard`	Tarjeta de visita (vCard 3.0)	`vcard_first_name` o `vcard_last_name`
`wifi`	Configuración Wi-Fi	`wifi_ssid`
`email`	Correo electrónico (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Ubicación (geo:)	`location_lat`, `location_lng`

Pruebas A/B

Prueba dos URLs de destino diferentes con redirección ponderada:

{
  "type": "url",
  "url": "https://version-a.example.com",
  "ab_enabled": true,
  "ab_target_url_b": "https://version-b.example.com",
  "ab_weight_a": 50
}

Expiración (Expiry)

Los códigos QR pueden expirar automáticamente:

{
  "type": "url",
  "url": "https://aktionsseite.example.com",
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_after_expiry": "https://archiv.example.com"
}

Después de la expiración, se redirigirá a redirect_after_expiry o se mostrará una página 410.

Creación por lotes

`POST /v1/codes/batch`

Crea hasta 1.000 códigos QR en una sola solicitud. Ideal para aplicaciones masivas.

curl -X POST https://qr3.app/v1/codes/batch \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "url", "url": "https://produkt-1.example.com", "tags": ["batch"] },
      { "type": "url", "url": "https://produkt-2.example.com", "tags": ["batch"] },
      { "type": "wifi", "wifi_ssid": "GastWLAN", "wifi_password": "geheim123" }
    ],
    "skip_url_scan": false
  }'

Respuesta (HTTP 201):

{
  "data": {
    "created": [
      { "id": "qr_...", "short_code": "abc123", "redirect_url": "https://qr3.app/abc123" },
      { "id": "qr_...", "short_code": "def456", "redirect_url": "https://qr3.app/def456" },
      { "id": "qr_...", "short_code": "ghi789", "status": "live" }
    ],
    "total": 3,
    "failed": 0
  }
}

Lista de códigos QR

`GET /v1/codes`

curl https://qr3.app/v1/codes?status=live&limit=20 \
  -H "Authorization: Bearer qr3_sk_..."

Parámetros de consulta:

Parámetro	Tipo	Por defecto	Descripción
`cursor`	string	—	Cursor para paginación
`limit`	integer	20	Resultados por página (máx. 100)
`status`	string	—	Filtro: `live`, `paused`, `flagged`, `draft`

Obtener código QR

`GET /v1/codes/:id`

curl https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Actualizar código QR

`PATCH /v1/codes/:id`

Los códigos QR dinámicos permiten cambiar la URL de destino en cualquier momento, sin tener que volver a imprimir el código QR.

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://neue-zielseite.example.com", "status": "live" }'

Landing page y enlaces externos

Para códigos url dinámicos, puedes establecer is_landing_page: true (al crearlos o mediante PATCH). Al escanearlos, se mostrará una página alojada por qr3 con los archivos públicos y enlaces externos del código, en lugar de redirigir. Los enlaces externos se envían como un array links:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

Entre 0 y 20 enlaces por código; label debe tener de 1 a 100 caracteres; url debe ser http(s) (≤ 2048 caracteres).
Cada URL se comprueba con Google Web Risk; una URL no segura devuelve un error 422.
Si Web Risk no está disponible al guardar, el enlace se aceptará de todos modos, pero se marcará para una nueva comprobación. Una tarea diaria vuelve a comprobar los enlaces guardados (y reevalúa periódicamente los clasificados como seguros) y pausa el código automáticamente si un enlace se detecta más tarde como no seguro.
"links": [] elimina todos los enlaces. Consulta la guía de landing pages.

Eliminar código QR

`DELETE /v1/codes/:id`

Eliminación suave (Soft-Delete): el código QR se archiva y los datos de escaneo se conservan.

curl -X DELETE https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Descargar imágenes de QR

Todos los formatos de imagen son de acceso público; no se requiere autenticación.

Formato	URL	Uso
SVG (vectorial)	`/v1/codes/:code/qr.svg`	Web, escalado, digital
PNG (rasterizado)	`/v1/codes/:code/qr.png`	Correo electrónico, presentaciones
PDF (vectorial)	`/v1/codes/:code/qr.pdf`	Por defecto: cuadrado (solo el código); `?format=a4` para una hoja de impresión
EPS (vectorial)	`/v1/codes/:code/qr.eps`	Flujos de trabajo de impresión profesional (Adobe, imprentas)

Opcional: ?size=N — Tamaño del módulo en píxeles (2–20, por defecto: 4) para SVG, PNG y EPS. El PDF utiliza un tamaño de módulo fijo.

Solo PDF: ?format=a4|square — Formato de página (por defecto: square — solo código + zona de silencio, sin espacio en blanco A4; a4 para una hoja A4 lista para imprimir)

# SVG für Web
curl https://qr3.app/v1/codes/r7f3Kx/qr.svg

# PNG in hoher Auflösung
curl https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10 -o qr-hires.png

# Kompaktes PDF (nur der Code, Standard)
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr.pdf

# Druckfertiges A4-Blatt
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?format=a4" -o qr-a4.pdf

Comentarios

Los comentarios permiten ciclos de retroalimentación entre agencias y clientes.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

`PATCH /v1/codes/:id/comments/:commentId`

`DELETE /v1/codes/:id/comments/:commentId`

# Kommentar hinzufügen
curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/comments \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "QR-Code bitte auf grünen Hintergrund abstimmen.", "author_name": "Max Müller" }'

# Offene Kommentare auflisten
curl "https://qr3.app/v1/codes/qr_a1b2c3d4/comments?resolved=false" \
  -H "Authorization: Bearer qr3_sk_..."

# Kommentar als erledigt markieren
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4/comments/cmt_xyz \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'