Aperçu de l'API

Aperçu de l’API

L’API REST de qr3.app est accessible à l’adresse https://qr3.app/v1/.

Versionnement

L’API est versionnée via le chemin d’URL (/v1/). Les changements majeurs (breaking changes) entraînent toujours une nouvelle version majeure.

Format des requêtes

• Content-Type : application/json
• Authentification : Authorization: Bearer qr3_sk_xxx
• Idempotence : Les requêtes POST peuvent être rendues idempotentes avec Idempotency-Key: <uuid>

Format des réponses

Toutes les réponses réussies renvoient du JSON :

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

Les réponses sous forme de liste ont toujours une structure meta.pagination :

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

Format d’erreur (RFC 7807)

Toutes les erreurs suivent la norme 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"
}

Statut	Type d’erreur	Description
400	bad-request	JSON invalide ou champs obligatoires manquants
401	authentication	API-Key manquant ou invalide
403	forbidden	Autorisation insuffisante pour cette ressource
404	not-found	Ressource non trouvée
409	conflict	Conflit d’Idempotency-Key
422	validation-error	Données d’entrée incorrectes (avec tableau errors)
429	rate-limited	Limite de taux dépassée
500	internal	Erreur interne du serveur

Pagination

L’API utilise une pagination basée sur un curseur :

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

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

Note

Le curseur est l’ID du dernier objet de la page actuelle.

Limites de taux

Chaque réponse contient :

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

Référence API interactive

Testez tous les points de terminaison directement dans le navigateur :

→ Ouvrir la référence API (Scalar, interactif, avec Try-it-out)

DPP-Contract (Phase 4a)

Pour le flux de travail de la batterie, qr3.app documente également ces routes :

• 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=...

Les pages du tableau de bord, les SDKs et cette documentation utilisent le même contrat de données.