Información general de la API

La API REST de qr3.app está disponible en https://qr3.app/v1/.

Versionado

La API está versionada a través de la ruta URL (/v1/). Los cambios importantes (breaking changes) siempre dan lugar a una nueva versión principal.

Formato de solicitud

Content-Type: application/json
Autenticación: Authorization: Bearer qr3_sk_xxx
Idempotencia: Las solicitudes POST se pueden hacer idempotentes con Idempotency-Key: <uuid>

Formato de respuesta

Todas las respuestas exitosas devuelven JSON:

{
  "id": "qr_abc123",
  "type": "url",
  "url": "https://example.com",
  "short_url": "https://qr3.app/r7f3Kx",
  "created_at": "2026-03-15T10:00:00.000Z"
}

Las respuestas de lista siempre tienen una estructura meta.pagination:

{
  "data": [...],
  "meta": {
    "request_id": "req_xxx",
    "pagination": {
      "has_more": true,
      "next_cursor": "qr_abc",
      "total_count": 142
    }
  }
}

Formato de errores (RFC 7807)

Todos los errores siguen el estándar RFC 7807 Problem Details:

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found",
  "instance": "/v1/codes/qr_xxx"
}

Status	Tipo de error	Descripción
400	`bad-request`	JSON no válido o campos obligatorios faltantes
401	`authentication`	API-Key faltante o no válido
403	`forbidden`	Sin permisos para este recurso
404	`not-found`	Recurso no encontrado
409	`conflict`	Conflicto de Idempotency-Key
422	`validation-error`	Datos de entrada incorrectos (con array `errors`)
429	`rate-limited`	Límite de solicitudes (rate limit) superado
500	`internal`	Error interno del servidor

Paginación

La API utiliza paginación basada en cursor:

# Erste Seite
GET /v1/codes?limit=20

# Nächste Seite
GET /v1/codes?limit=20&cursor=qr_lastid

Límites de solicitudes (Rate Limits)

Cada respuesta contiene:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1742040120

Referencia interactiva de la API

Prueba todos los endpoints directamente en el navegador:

→ Abrir referencia de la API (Scalar, interactiva, con Try-it-out)

DPP-Contract (Fase 4a)

Para el flujo de trabajo de baterías, qr3.app documenta adicionalmente estas rutas:

POST /v1/dpp
GET /v1/dpp
GET /v1/dpp/:id
POST /v1/dpp/validate
GET /v1/dpp/:id/qr.svg
GET /v1/dpp/:id/qr.png
GET /v1/dpp/:id/qr.pdf
GET /v1/dpp/:id/qr.eps
GET /01/...
GET /dpp/:gtin/:serial?lot=...

Las páginas del panel de control (dashboard), los SDK y esta documentación utilizan el mismo contrato de datos.