Barcode API Documentation

01Overview

Ratifye.ai provides APIs for generating signed barcode URLs and authenticating scanned barcode URLs. The APIs are intended for server-to-server integration and should be called from a trusted backend where the API key can be kept private.

The Generate API creates a serial pool and the corresponding barcode URLs. The Scan Authentication API accepts a scanned Ratifye URL and returns the decoded GS1 data together with authentication information and barcode quality.

Base URL

https://api.ratifye.ai

02Authentication

Every API request requires an API key in the x-api-key header. Production keys must remain private; they appear as YOUR_API_KEY throughout this document.

03Barcode Generate API

When serialEnabled=true, Ratifye.ai generates unique serial values and returns a signed URL for each serial. The example below requests 1,000 serials, and the response reports urlsCount: 1000.

Request

curl --location 'https://api.ratifye.ai/barcode/generate?serialEnabled=true' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "gtin": "18909192000128",
  "batch": "SNFDP2131",
  "expiry": "290202",
  "mrp": 199.99,
  "marketCode": "IN",
  "poolSize": 1000,
  "digits": 10,
  "prefix": "SNF",
  "notes": "April batch",
  "domain": "https://dl.ratifye.ai"
}'

Request parameters

Response

{
  "success": true,
  "data": {
    "companyId": 98,
    "serialEnabled": true,
    "poolId": "6b94d5d8-fd42-46cb-b76d-f8b8d3e87c11",
    "serials": [
      "SNF3WNL1VJ5V6",
      "SNFBNHBI2ELIQ",
      "SNF8N3ZMF4TSO",
      "...",
      "SNF576Z0OL40B"
    ],
    "urls": [
      "https://dl.ratifye.ai/01/18909192000128/10/SNFDP2131/21/SNF3WNL1VJ5V6?17=290202",
      "https://dl.ratifye.ai/01/18909192000128/10/SNFDP2131/21/SNF8N3ZMF4TSO?17=290202",
      "..."
    ],
    "urlsCount": 1000,
    "timings": {
      "serialPoolMs": 303,
      "serialMembersMs": 0,
      "urlBuildMs": 1,
      "signatureMs": 429,
      "auditMs": 399,
      "serialUpdateMs": 29,
      "totalMs": 864
    }
  }
}

Response fields

04Barcode URL structure

Each generated URL follows the GS1 Digital Link format. Every value is preceded by its GS1 Application Identifier (AI).

05Barcode Scan Authentication API

Authenticates a scanned Ratifye barcode URL and returns the barcode payload, parsed GS1 data, encrypted text and a quality result.

Request

curl --location 'https://api.ratifye.ai/barcode/scan/authenticate' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
  "url": "https://dl.ratifye.ai/01/18901234567897/10/AMI432/21/GKBM4O3OI0SB?17=270606&98=W7PA====/97=48"
}'

Response

{
  "success": true,
  "data": [
    {
      "barcode_data": "https://dl.ratifye.ai/01/18901234567897/10/AMI432/21/GKBM4O3OI0SB?17=270606",
      "gs1_data": {
        "10": { "name": "Batch/Lot", "value": "AMI432" },
        "17": { "name": "Expiry", "value": "270606" },
        "21": { "name": "Serial", "value": "GKBM4O3OI0SB" },
        "01": { "name": "GTIN", "value": "18901234567897" }
      },
      "encrypted_text": "W7PA====",
      "quality": "Real"
    }
  ]
}

Response fields

06GS1 Application Identifiers

07Recommended integration flow

1. Store the API key securely on your backend.
2. Call the Generate API with product, batch, expiry and serial-pool parameters.
3. Store poolId, serials and urls as required by your business workflow.
4. Print or distribute the generated barcode payloads on your packaging.
5. Send each scanned Ratifye URL to the Scan Authentication API.
6. Read gs1_data and quality from the response.
7. Use the authentication response as the trusted scan result.

08Security guidelines

• Keep API keys confidential and server-side.
• Use HTTPS for all API calls.
• Do not expose production API keys in mobile apps or browser bundles.
• Do not log complete API keys.
• Validate both the HTTP status and the success field.
• Handle authentication failures, malformed URLs, network failures and empty data arrays.
• Use the returned quality field in the scan decision flow.

09Example client-side processing

const response = await authenticateBarcode(scannedUrl);

if (response.success && response.data?.length) {
  const result = response.data[0];
  console.log(result.gs1_data["01"].value); // GTIN
  console.log(result.gs1_data["10"].value); // Batch/Lot
  console.log(result.gs1_data["17"].value); // Expiry
  console.log(result.gs1_data["21"].value); // Serial
  console.log(result.quality);              // Real
}

10Quick reference