How to validate SSCC codes, check digit algorithm, EDIFACT extraction and free API

export interface SsccValidationResult {
  isValid: boolean;
  normalizedSscc: string;
  providedCheckDigit: number;
  expectedCheckDigit: number;
  error?: string;
}

/**
 * Normalizes raw SSCC input by removing non-digit characters
 * and handling Application Identifier prefixes.
 */
export function normalizeSsccInput(rawInput: string): string {
  const digitsOnly = rawInput.replace(/\D/g, '');
  
  // Handle 20-digit format with AI (00)
  if (digitsOnly.length === 20 && digitsOnly.startsWith('00')) {
    return digitsOnly.substring(2);
  }
  
  // Handle 17-digit body (missing check digit)
  if (digitsOnly.length === 17) {
    const checkDigit = computeGs1CheckDigit(digitsOnly);
    return digitsOnly + checkDigit.toString();
  }
  
  if (digitsOnly.length !== 18) {
    throw new Error(`Invalid SSCC length: ${digitsOnly.length}. Expected 17 or 18 digits.`);
  }
  
  return digitsOnly;
}

/**
 * Computes the GS1 Modulo-10 check digit for a 17-digit payload.
 */
export function computeGs1CheckDigit(payload: string): number {
  if (payload.length !== 17) {
    throw new Error('Payload must be exactly 17 digits');
  }

  let sum = 0;
  
  // Iterate from right to left
  for (let i = payload.length - 1; i >= 0; i--) {
    const digit = parseInt(payload[i], 10);
    const positionFromRight = payload.length - i;
    const multiplier = (positionFromRight % 2 === 1) ? 3 : 1;
    sum += digit * multiplier;
  }
  
  return (10 - (sum % 10)) % 10;
}

/**
 * Validates an 18-digit SSCC by verifying the check digit.
 */
export function validateSsccIntegrity(sscc: string): SsccValidationResult {
  const normalized = normalizeSsccInput(sscc);
  const body = normalized.substring(0, 17);
  const providedCheckDigit = parseInt(normalized[17], 10);
  const expectedCheckDigit = computeGs1CheckDigit(body);
  
  return {
    isValid: providedCheckDigit === expectedCheckDigit,
    normalizedSscc: normalized,
    providedCheckDigit,
    expectedCheckDigit,
    error: providedCheckDigit !== expectedCheckDigit 
      ? 

Check digit mismatch: expected ${expectedCheckDigit}, got ${providedCheckDigit} : undefined }; }

#### 3. EDIFACT Extraction with Custom Delimiters

EDIFACT messages use the UNA segment to define custom delimiters. Hardcoding separators like `+` and `'` will fail on non-standard files. A robust parser must read the UNA header first.

```typescript
export interface EdifactSsccResult {
  sscc: string;
  segmentId: string;
  qualifier: string;
  validation: SsccValidationResult;
}

/**
 * Extracts SSCCs from EDIFACT messages, handling custom UNA delimiters.
 */
export function extractSsccsFromEdifact(rawMessage: string): EdifactSsccResult[] {
  const results: EdifactSsccResult[] = [];
  
  // Parse UNA delimiters
  const unaMatch = rawMessage.match(/^UNA(.{6})/);
  const delimiters = unaMatch ? {
    compSep: unaMatch[1][0],
    elemSep: unaMatch[1][1],
    segTerm: unaMatch[1][5]
  } : { compSep: ':', elemSep: '+', segTerm: "'" };

  // Split into segments
  const segments = rawMessage
    .replace(/\r?\n/g, '')
    .split(delimiters.segTerm)
    .map(s => s.trim())
    .filter(Boolean);

  for (const segment of segments) {
    const elements = segment.split(delimiters.elemSep);
    const segmentId = elements[0];
    
    // Check relevant segments: GIN (with BJ qualifier), RFF (SI, AAK)
    if (segmentId === 'GIN' || segmentId === 'RFF') {
      for (let i = 1; i < elements.length; i++) {
        const parts = elements[i].split(delimiters.compSep);
        const qualifier = parts[0];
        const value = parts[1];
        
        if (value && (segmentId === 'GIN' && qualifier === 'BJ' || 
                      segmentId === 'RFF' && (qualifier === 'SI' || qualifier === 'AAK'))) {
          try {
            const validation = validateSsccIntegrity(value);
            results.push({
              sscc: validation.normalizedSscc,
              segmentId,
              qualifier,
              validation
            });
          } catch (err) {
            // Log parsing error but continue processing
            console.warn(`Failed to parse SSCC in segment ${segmentId}: ${err}`);
          }
        }
      }
    }
  }
  
  return results;
}

Architecture Decisions

• Pure Functions: All validation and extraction functions are pure, ensuring testability and idempotency.
• Type Safety: TypeScript interfaces enforce contract compliance and reduce runtime errors.
• Error Boundaries: Extraction functions catch and log errors without halting the entire pipeline, ensuring partial data availability.
• Delimiter Agnostic: The EDIFACT parser reads UNA headers dynamically, supporting custom separators used by various trading partners.

Pitfall Guide

1. Application Identifier Contamination

Explanation: Scanners often output the AI (00) followed by the 18-digit SSCC, resulting in a 20-character string. Treating this as the SSCC payload causes validation failure. Fix: Always strip the leading 00 before validation. Use normalizeSsccInput to handle this automatically.

2. Fixed-Width ERP Blindness

Explanation: ERP exports may store SSCCs in fixed-width fields without delimiters. Regex patterns using word boundaries (\b) will fail to match SSCCs followed immediately by other data. Fix: Use lookbehind assertions or fixed-length extraction. Example: /(?<!\d)(00\d{18})/g captures the AI-prefixed SSCC regardless of trailing content.

3. EDIFACT Delimiter Assumption

Explanation: Hardcoding + and ' as separators will break on files with custom UNA delimiters, leading to missed SSCCs or parsing errors. Fix: Always parse the UNA segment first. If UNA is absent, fall back to defaults but log a warning for non-standard files.

4. Check Digit Math Errors

Explanation: Incorrect multiplier application (e.g., starting with 1 instead of 3, or left-to-right iteration) produces wrong check digits. Fix: Implement the algorithm strictly from right to left, with the rightmost digit multiplied by 3. Use the provided computeGs1CheckDigit function.

5. Leading Zero Loss

Explanation: Parsing SSCCs as numbers strips leading zeros, corrupting the payload. Fix: Always treat SSCCs as strings. Avoid parseInt or Number conversions unless extracting individual digits for checksum calculation.

6. Segment Qualifier Variance

Explanation: Only checking GIN+BJ misses SSCCs in RFF+SI or RFF+AAK segments, which are common in DESADV messages. Fix: Extend extraction logic to check multiple segments and qualifiers. Use a whitelist of valid qualifiers per segment type.

7. Performance in Batch Processing

Explanation: Inefficient string operations or regex compilation in loops can degrade performance when processing large EDIFACT files. Fix: Pre-compile regex patterns, use array methods like map and filter for batch processing, and avoid unnecessary string concatenations.

Production Bundle

Action Checklist

• Normalize Inputs: Ensure all SSCC inputs pass through normalizeSsccInput to handle AI prefixes and missing check digits.
• Verify Check Digits: Implement Modulo-10 validation for all SSCCs before storing or processing.
• Parse UNA Headers: Always read EDIFACT UNA segments to handle custom delimiters dynamically.
• Handle Fixed-Width Fields: Use lookbehind regex or fixed-length extraction for ERP exports.
• Test Edge Cases: Validate against known edge cases: 17-digit bodies, 20-digit AI-prefixed codes, and custom EDIFACT delimiters.
• Log Errors: Implement error logging for failed validations to identify data quality issues early.
• Use TypeScript: Enforce type safety with interfaces to prevent runtime errors and improve code maintainability.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Real-time UI Validation	Client-side Modulo-10 Check	Immediate feedback, reduces server load	Low
Batch EDIFACT Processing	Server-side Structured Parser	Handles large files, custom delimiters, and multiple segments	Medium
ERP Fixed-Width Exports	Lookbehind Regex + Normalization	Captures SSCCs without delimiters	Low
High-Volume API Integration	Optimized Pure Functions	Ensures performance and idempotency	Medium

Configuration Template

// sscc.config.ts
export interface SsccConfig {
  enableLogging: boolean;
  logLevel: 'debug' | 'info' | 'warn' | 'error';
  edifactDefaults: {
    compSep: string;
    elemSep: string;
    segTerm: string;
  };
  validationRules: {
    rejectInvalidCheckDigit: boolean;
    autoGenerateCheckDigit: boolean;
  };
}

export const defaultConfig: SsccConfig = {
  enableLogging: true,
  logLevel: 'info',
  edifactDefaults: {
    compSep: ':',
    elemSep: '+',
    segTerm: "'"
  },
  validationRules: {
    rejectInvalidCheckDigit: true,
    autoGenerateCheckDigit: true
  }
};

Quick Start Guide

1. Install Dependencies: Ensure TypeScript is configured in your project.

   npm install typescript --save-dev
   npx tsc --init
   

2. Copy Implementation: Add the normalizeSsccInput, computeGs1CheckDigit, validateSsccIntegrity, and extractSsccsFromEdifact functions to your codebase.
3. Run Validation Tests: Test with sample SSCCs and EDIFACT messages.

   const result = validateSsccIntegrity('356012345600000016');
   console.log(result.isValid); // true
   

4. Integrate with Pipeline: Use extractSsccsFromEdifact in your EDI processing workflow to validate and extract SSCCs automatically.
5. Monitor Logs: Enable logging to track validation errors and data quality issues in production.