QR Endpoints

Complete reference for QR code management endpoints.

Base URL

https://api.govalid.org/api/v1/qr/

List QR Codes

GET /api/v1/qr/

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
page_size	integer	Results per page (default: 20, max: 100)
qr_type	string	Filter by type (url, document, certificate, etc.)
security_level	string	Filter by level (smart, verified, secure, enterprise)
status	string	Filter by status (active, expired, removed)

Response

{
  "count": 150,
  "next": "https://api.govalid.org/api/v1/qr/?page=2",
  "previous": null,
  "results": [
    {
      "id": "abc123",
      "title": "Product Certificate",
      "qr_type": "certificate",
      "security_level": "verified",
      "status": "active",
      "scan_count": 45,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:22:00Z"
    }
  ]
}

Create QR Code

POST /api/v1/qr/

Request Body

Field	Type	Required	Description
title	string	Yes	QR code title
qr_type	string	Yes	Type: url, text, email, phone, vcard, document, certificate, goods
content	string	Conditional	Content (required for url, text, email, phone types)
security_level	string	No	smart, verified, secure, enterprise (default: smart)
metadata	object	No	Custom metadata fields
password	string	No	Password protection
expires_at	datetime	No	Expiration date (ISO 8601)

Example Request

{
  "title": "Product Certificate #001",
  "qr_type": "certificate",
  "security_level": "verified",
  "metadata": {
    "product_name": "Organic Coffee",
    "batch": "BATCH-2025-001",
    "origin": "Aceh, Indonesia"
  }
}

Response

{
  "id": "abc123",
  "title": "Product Certificate #001",
  "qr_type": "certificate",
  "security_level": "verified",
  "qr_image": "https://api.govalid.org/media/qr/abc123.png",
  "short_url": "https://govalid.org/q/abc123",
  "verification_url": "https://govalid.org/v/abc123",
  "metadata": {
    "product_name": "Organic Coffee",
    "batch": "BATCH-2025-001",
    "origin": "Aceh, Indonesia"
  },
  "created_at": "2025-01-29T12:00:00Z"
}

Get QR Code Details

GET /api/v1/qr/{id}/

Response

{
  "id": "abc123",
  "title": "Product Certificate #001",
  "qr_type": "certificate",
  "security_level": "verified",
  "status": "active",
  "scan_count": 45,
  "unique_scans": 30,
  "qr_image": "https://api.govalid.org/media/qr/abc123.png",
  "short_url": "https://govalid.org/q/abc123",
  "metadata": { ... },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:22:00Z"
}

Update QR Code

PATCH /api/v1/qr/{id}/

Request Body

Any field from the create request can be updated.

Delete QR Code

DELETE /api/v1/qr/{id}/

Get Scan History

GET /api/v1/qr/{id}/scans/

Response

{
  "count": 45,
  "results": [
    {
      "scanned_at": "2025-01-29T15:30:00Z",
      "location": {
        "country": "ID",
        "city": "Jakarta"
      },
      "device": "mobile",
      "platform": "iOS",
      "is_first_scan": false
    }
  ]
}

Get Analytics

GET /api/v1/qr/{id}/analytics/

Response

{
  "total_scans": 150,
  "unique_scans": 89,
  "scans_today": 12,
  "scans_this_week": 45,
  "top_locations": [
    {"country": "US", "count": 50},
    {"country": "ID", "count": 35}
  ],
  "scan_timeline": [
    {"date": "2025-01-28", "count": 15},
    {"date": "2025-01-29", "count": 12}
  ],
  "device_breakdown": {
    "mobile": 120,
    "desktop": 30
  }
}

Bulk Create QR Codes

POST /api/v1/qr/bulk/

Request Body

{
  "qr_codes": [
    {"title": "Product 1", "qr_type": "product", "sku": "SKU001"},
    {"title": "Product 2", "qr_type": "product", "sku": "SKU002"},
    {"title": "Product 3", "qr_type": "product", "sku": "SKU003"}
  ]
}

QR Transfers

Initiate Transfer

POST /api/v1/qr/{id}/transfer/

Approve Transfer

POST /api/v1/qr/{id}/transfer/approve/

Reject Transfer

POST /api/v1/qr/{id}/transfer/reject/

Cancel Transfer

POST /api/v1/qr/{id}/transfer/cancel/

Related

• QR Codes Guide - User guide for QR features
• Security Levels - Understanding security tiers
• Code Examples - Common use cases