Generate Code

POST /api/v1/code/generate

Generate a cryptographically signed GS1 Digital Link URL for a product.

Request

Headers

Header	Required	Description
x-api-key	Yes	Your Optropic API key
Content-Type	Yes	Must be application/json

Body Parameters

Parameter	Type	Required	Description
gtin	string	Yes	14-digit GTIN (Global Trade Item Number)
serialNumber	string	Yes	Unique serial number for this item
batchNumber	string	No	Batch/lot number
expiryDate	string	No	Expiry date in ISO 8601 format
metadata	object	No	Additional key-value data

Example Request

curl -X POST https://api.optropic.com/api/v1/code/generate \
  -H "x-api-key: optr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gtin": "04260799580008",
    "serialNumber": "SN-2026-001",
    "batchNumber": "BATCH-A",
    "metadata": {
      "product": "Premium Widget",
      "color": "Blue"
    }
  }'

Response

Success (201 Created)

{
  "url": "https://id.optropic.com/01/04260799580008/21/SN-2026-001/10/BATCH-A?sig=Kx7mN2...",
  "gtin": "04260799580008",
  "serial": "SN-2026-001",
  "batch": "BATCH-A",
  "signature": "Kx7mN2vL9pQr5tYw8zAb...",
  "keyId": "key_abc123",
  "createdAt": "2026-02-18T10:30:00Z"
}

Response Fields

Field	Type	Description
url	string	The complete GS1 Digital Link URL with signature
gtin	string	The GTIN used
serial	string	The serial number
batch	string	The batch number (if provided)
signature	string	Base64url-encoded Ed25519 signature
keyId	string	ID of the signing key used
createdAt	string	ISO 8601 timestamp

URL Structure

The generated URL follows GS1 Digital Link syntax:

https://id.optropic.com/01/{GTIN}/21/{SERIAL}/10/{BATCH}?sig={SIGNATURE}

Component	AI (Application Identifier)	Description
01	GTIN	Global Trade Item Number
21	Serial	Serial number
10	Batch/Lot	Batch number
sig	—	Ed25519 signature (query param)

Errors

Code	HTTP Status	Description
INVALID_GTIN	400	GTIN is not a valid 14-digit number
DUPLICATE_SERIAL	409	This GTIN+Serial combination already exists
MISSING_REQUIRED_FIELD	400	Required field is missing
RATE_LIMITED	429	Generate rate limit exceeded

Example Error

{
  "error": {
    "code": "INVALID_GTIN",
    "message": "GTIN must be exactly 14 digits",
    "details": {
      "provided": "1234567890",
      "expected": "14 digits"
    }
  }
}

Code Examples

JavaScript

async function generateCode(gtin, serialNumber, batchNumber) {
  const response = await fetch('https://api.optropic.com/api/v1/code/generate', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.OPTROPIC_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      gtin,
      serialNumber,
      batchNumber,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return response.json();
}

// Usage
const code = await generateCode('04260799580008', 'SN-001', 'BATCH-A');
console.log(code.url);

Python

import requests
import os

def generate_code(gtin: str, serial: str, batch: str = None) -> dict:
    response = requests.post(
        'https://api.optropic.com/api/v1/code/generate',
        headers={
            'x-api-key': os.environ['OPTROPIC_API_KEY'],
            'Content-Type': 'application/json',
        },
        json={
            'gtin': gtin,
            'serialNumber': serial,
            'batchNumber': batch,
        }
    )
    response.raise_for_status()
    return response.json()

# Usage
code = generate_code('04260799580008', 'SN-001', 'BATCH-A')
print(code['url'])

QR Code Generation

The URL returned can be encoded into a QR code using any standard library:

import QRCode from 'qrcode';

const code = await generateCode('04260799580008', 'SN-001', 'BATCH-A');
const qrDataUrl = await QRCode.toDataURL(code.url);
// Use qrDataUrl in an <img> tag

Print-Ready QR Codes

For print production, generate QR codes at minimum 300 DPI with adequate quiet zones. We recommend SVG format for scalability.