Home

📦 SSCC API — Wiki

Free REST API for SSCC validation, check digit generation, range expansion and file extraction. Built on Cloudflare Workers — no auth, no setup, no cost.

🔗 Base URL: https://sscc.birth1mark.workers.dev

🔗 Live app: birth1mark.github.io/sscc-check

🔗 API docs page: https://birth1mark.github.io/sscc-check/sscc-api-guide.html

🔗 SSCC guide: birth1mark.github.io/sscc-check/guide.html

🌐 Overview

The SSCC API exposes the same validation logic as the SSCC Pro Vision web app as a REST API — allowing any system to validate, generate or extract SSCCs programmatically.

Key properties:

No authentication required
CORS open (*) — safe to call from any browser or server
100,000 requests/day free (Cloudflare Workers free tier)
Edge network — low latency globally
Stateless — no data is stored or logged
All responses are JSON

📡 Endpoints

Method	Path	Description
`GET`	`/validate`	Validate an 18-digit SSCC
`GET`	`/generate`	Generate check digit for a 17-digit body
`GET`	`/range`	Generate all SSCCs between two codes
`GET`	`/prefix`	Look up GS1 country from SSCC prefix
`POST`	`/extract`	Extract SSCCs from EDIFACT, XML, CSV or TXT
`GET`	`/health`	API status and endpoint list

✅ GET /validate

Validates an 18-digit SSCC and returns check digit info and GS1 country data.

Parameters:

Parameter	Type	Required	Description
`sscc`	string	✅	18-digit SSCC, or 20-digit with AI `00` prefix

Example:

GET /validate?sscc=356012345600000016

Response:

{
  "input":     "356012345600000016",
  "sscc":      "356012345600000016",
  "formatted": "(00)356012345600000016",
  "valid":     true,
  "checkDigit": { "provided": 6, "expected": 6 },
  "gs1": {
    "extensionDigit": 3,
    "prefix":         560,
    "country":        "Portugal",
    "countryCode":    "PT",
    "flag":           "🇵🇹"
  }
}

When valid is false, checkDigit.provided and checkDigit.expected will differ — useful for pinpointing transcription errors.

🔢 GET /generate

Calculates the GS1 check digit for a 17-digit SSCC body.

Parameters:

Parameter	Type	Required	Description
`body`	string	✅	17-digit SSCC body (no check digit)

Example:

GET /generate?body=35601234560000001

Response:

{
  "input":      "35601234560000001",
  "body":       "35601234560000001",
  "checkDigit": 6,
  "sscc":       "356012345600000016",
  "formatted":  "(00)356012345600000016",
  "gs1": {
    "extensionDigit": 3,
    "prefix":         560,
    "country":        "Portugal",
    "countryCode":    "PT",
    "flag":           "🇵🇹"
  }
}

🔁 GET /range

Generates every SSCC between two codes, each with its check digit. Maximum 500 codes per request.

Parameters:

Parameter	Type	Required	Description
`from`	string	✅	Start SSCC (17, 18 or 20 digits)
`to`	string	✅	End SSCC (17, 18 or 20 digits)

Both parameters accept 17-digit bodies, 18-digit SSCCs (check digit is stripped and recalculated) or 20-digit strings with the AI 00 prefix.

Example:

GET /range?from=35601234560000001&to=35601234560000005

Response:

{
  "from":  "35601234560000001",
  "to":    "35601234560000005",
  "count": 5,
  "items": [
    { "sscc": "356012345600000016", "formatted": "(00)356012345600000016", "checkDigit": 6 },
    { "sscc": "356012345600000023", "formatted": "(00)356012345600000023", "checkDigit": 3 },
    { "sscc": "356012345600000030", "formatted": "(00)356012345600000030", "checkDigit": 0 },
    { "sscc": "356012345600000047", "formatted": "(00)356012345600000047", "checkDigit": 7 },
    { "sscc": "356012345600000054", "formatted": "(00)356012345600000054", "checkDigit": 4 }
  ]
}

🌍 GET /prefix

Returns the GS1 member country for an SSCC based on its company prefix (digits 1–3 after the extension digit).

Parameters:

Parameter	Type	Required	Description
`sscc`	string	✅	18-digit SSCC or 20-digit with AI prefix

Example:

GET /prefix?sscc=356012345600000016

Response:

{
  "sscc":        "356012345600000016",
  "prefix":      560,
  "country":     "Portugal",
  "countryCode": "PT",
  "flag":        "🇵🇹"
}

ℹ️ The GS1 prefix identifies the organisation that issued the company prefix — not the country of manufacture or shipment origin.

📂 POST /extract

Extracts and validates all SSCCs from the raw text content of any file. Send the file content as a plain text request body.

Supported formats:

Format	Detection	Key segments / fields
EDIFACT	`UNA` / `UNB+` header	`GIN+BJ`, `RFF+SI`, `RFF+AAK`, `PAC`
IDoc SAP	`<IDOC>`, `<EDI_DC>` tags	`EXIDV`, `EXIDV2`, `VHILM_KU`
XML	`<?xml` header	Known logistics tags + regex fallback
CSV / TXT	Generic fallback	Regex scan for 17/18/20-digit patterns

Request:

POST /extract
Content-Type: text/plain

UNB+UNOA:1+...
GIN+BJ:356012345600000016'
GIN+BJ:356012345600000023'

Response:

{
  "format":  "edifact",
  "count":   2,
  "summary": { "valid": 2, "invalid": 0, "generated": 0 },
  "items": [
    {
      "sscc":       "356012345600000016",
      "formatted":  "(00)356012345600000016",
      "valid":      true,
      "generated":  false,
      "checkDigit": { "provided": 6, "expected": 6 },
      "gs1": { "prefix": 560, "country": "Portugal", "countryCode": "PT", "flag": "🇵🇹" }
    },
    ...
  ]
}

curl example:

curl -X POST "https://sscc.birth1mark.workers.dev/extract" \
  -H "Content-Type: text/plain" \
  --data-binary @desadv.edi

JavaScript example:

const file    = document.querySelector('#file-input').files[0];
const content = await file.text();
const res     = await fetch('https://sscc.birth1mark.workers.dev/extract', {
    method: 'POST',
    body:   content,
});
const data = await res.json();
console.log(`Found ${data.count} SSCCs in ${data.format} file`);

Python example:

import requests

with open('desadv.edi', 'r') as f:
    content = f.read()

r = requests.post('https://sscc.birth1mark.workers.dev/extract', data=content)
data = r.json()
for item in data['items']:
    print(item['sscc'], '✓' if item['valid'] else '✗')

❤️ GET /health

Returns API status and a list of available endpoints.

GET /health

{
  "status":  "ok",
  "version": "1.0.0",
  "endpoints": [
    "GET /validate?sscc=<18-digit SSCC>",
    "GET /generate?body=<17-digit body>",
    "GET /range?from=<SSCC>&to=<SSCC>",
    "GET /prefix?sscc=<18-digit SSCC>",
    "POST /extract  (body: EDIFACT, XML, CSV or TXT content)",
    "GET /health"
  ]
}

⚠️ Error Handling

All errors return a JSON object with an error field and the appropriate HTTP status code.

Status	Meaning
`400`	Bad request — missing or invalid parameter
`405`	Method not allowed
`500`	Internal server error

Example error:

{ "error": "Invalid length: expected 18 digits, got 15" }

📐 Input Formats

All numeric parameters accept several formats — the API normalises them automatically:

Input	Length	Treated as
`35601234560000001`	17 digits	Body — check digit generated
`356012345600000016`	18 digits	Full SSCC — check digit validated
`00356012345600000016`	20 digits	AI `00` + 18-digit SSCC
`(00)356012345600000016`	18 + AI	Parentheses stripped, 18-digit SSCC

🔍 SSCC Detection Filters

When extracting SSCCs from files (POST /extract), two quality filters are applied before accepting a candidate:

1. GS1 prefix validation The digits 1–3 of the SSCC (after the extension digit) must match a known GS1 member prefix from the GS1 General Specifications 2025. Sequences like 00000000000000228820 (prefix 000) are rejected.

2. Trivial sequence rejection Strings with more than 10 identical consecutive digits are discarded — these are clearly padding or system IDs, not real SSCCs.

Both filters run before the check digit is validated.

📱 Related — SSCC Pro Vision App

The API powers the same logic as SSCC Pro Vision — a free browser-based tool that provides a visual interface for the same operations:

Feature	App	API
Validate SSCCs	✅	✅ `/validate`
Generate check digits	✅	✅ `/generate`
Expand ranges	✅	✅ `/range`
Extract from files	✅ (drag & drop)	✅ `POST /extract`
Camera barcode scan	✅	❌
Copy / CSV export	✅	❌
Country flag	✅	✅ `/prefix`
Offline (PWA)	✅	❌

Use the app for manual, one-off validation. Use the API for automated pipelines, system integrations, or batch processing.

📝 Changelog

v1.0.0

🚀 Initial release
✅ GET /validate — SSCC validation with GS1 country lookup
🔢 GET /generate — check digit generation
🔁 GET /range — range expansion (max 500 codes)
🌍 GET /prefix — GS1 prefix to country lookup
📂 POST /extract — EDIFACT, IDoc SAP, XML, CSV and TXT extraction
🔒 CORS open, no auth, no data stored
⚡ Cloudflare Workers edge deployment

Part of the SSCC Pro Vision project.

📦 SSCC API — Wiki

Free REST API for SSCC validation, check digit generation, range expansion and file extraction. Built on Cloudflare Workers — no auth, no setup, no cost.

🔗 Base URL: https://sscc.birth1mark.workers.dev

🔗 Live app: birth1mark.github.io/sscc-check

🔗 API docs page: birth1mark.github.io/sscc-check/api.html

🔗 SSCC guide: birth1mark.github.io/sscc-check/guide.html

📋 Table of Contents

🌐 Overview

The SSCC API exposes the same validation logic as the SSCC Pro Vision web app as a REST API — allowing any system to validate, generate or extract SSCCs programmatically.

Key properties:

No authentication required
CORS open (*) — safe to call from any browser or server
100,000 requests/day free (Cloudflare Workers free tier)
Edge network — low latency globally
Stateless — no data is stored or logged
All responses are JSON

📡 Endpoints

Method	Path	Description
GET	/validate	Validate an 18-digit SSCC
GET	/generate	Generate check digit for a 17-digit body
GET	/range	Generate all SSCCs between two codes
GET	/prefix	Look up GS1 country from SSCC prefix
POST	/extract	Extract SSCCs from EDIFACT, XML, CSV or TXT
GET	/health	API status and endpoint list

Use the app for manual, one-off validation. Use the API for automated pipelines, system integrations, or batch processing.

📝 Changelog

v1.0.0

🚀 Initial release
✅ GET /validate — SSCC validation with GS1 country lookup
🔢 GET /generate — check digit generation
🔁 GET /range — range expansion (max 500 codes)
🌍 GET /prefix — GS1 prefix to country lookup
📂 POST /extract — EDIFACT, IDoc SAP, XML, CSV and TXT extraction
🔒 CORS open, no auth, no data stored
⚡ Cloudflare Workers edge deployment

Part of the SSCC Pro Vision project.

# 📦 SSCC API — Wiki

Free REST API for SSCC validation, check digit generation, range expansion and file extraction. Built on Cloudflare Workers — no auth, no setup, no cost.

🔗 Base URL: https://sscc.birth1mark.workers.dev

🔗 Live app: [birth1mark.github.io/sscc-check](https://birth1mark.github.io/sscc-check/)

🔗 API docs page: [birth1mark.github.io/sscc-check/api.html](https://birth1mark.github.io/sscc-check/api.html)

🔗 SSCC guide: [birth1mark.github.io/sscc-check/guide.html](https://birth1mark.github.io/sscc-check/guide.html)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Home

📦 SSCC API — Wiki

📋 Table of Contents

🌐 Overview

📡 Endpoints

✅ GET /validate

🔢 GET /generate

🔁 GET /range

🌍 GET /prefix

📂 POST /extract

❤️ GET /health

⚠️ Error Handling

📐 Input Formats

🔍 SSCC Detection Filters

📱 Related — SSCC Pro Vision App

📝 Changelog

v1.0.0

📦 SSCC API — Wiki

📋 Table of Contents

🌐 Overview

📡 Endpoints

📝 Changelog

v1.0.0

Clone this wiki locally