{"openapi":"3.1.0","info":{"title":"Barcode, GS1 & ZPL API","version":"1","description":"Free plan: 1000 requests per day (UTC) and 60 per minute per key. Request contents are not stored or logged. Validation is not a formal barcode verification or certification."},"servers":[{"url":"/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key (bpk_…) from the account page"}},"responses":{"BadRequest":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"e.g. invalid_data"}},"required":[]}}}},"Unauthorized":{"description":"Missing, unknown or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["api_key_required","invalid_api_key"]}},"required":[]}}}},"RateLimited":{"description":"Limit reached; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited","daily_quota_exceeded"]}},"required":[]}}}}}},"paths":{"/gtin/validate":{"post":{"summary":"Validate a GTIN-8/12/13/14","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gtin":{"type":"string"}},"required":["gtin"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"type":{"type":"string"},"error":{"type":"string"},"expectedCheckDigit":{"type":"integer"},"gtin14":{"type":"string"}},"required":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/gs1/parse":{"post":{"summary":"Parse GS1 element strings, raw scanner data or GS1 Digital Link URIs","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","description":"e.g. (01)09521234543213(10)ABC123"}},"required":["data"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"elements":{"type":"array","items":{"type":"object","properties":{"ai":{"type":"string"},"title":{"type":"string"},"value":{"type":"string"}},"required":[]}},"dataStr":{"type":"string"},"digitalLink":{"type":"string"},"error":{"type":"string"},"errorMarkup":{"type":"string"}},"required":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/barcode/generate":{"post":{"summary":"Generate a barcode as SVG","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"symbology":{"type":"string","enum":["EAN-13","EAN-8","UPC-A","UPC-E","Code 128","GS1-128","Code 39","Code 93","ITF-14","ITF","DataMatrix","GS1 DataMatrix","QR Code","Micro QR","PDF417","Aztec"]},"data":{"type":"string"},"scale":{"type":"number","description":"Points per module","default":2,"minimum":1,"maximum":10},"includeText":{"type":"boolean","default":true},"rotate":{"type":"string","enum":["N","R","I","L"],"default":"N"}},"required":["symbology","data"]}}}},"responses":{"200":{"description":"SVG","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"The symbology cannot encode the data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"cannot_encode"},"detail":{"type":"string"}},"required":[]}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/barcode/decode":{"post":{"summary":"Decode all barcodes in a PNG or JPEG image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"Base64 PNG or JPEG, max 5 MB"}},"required":["image"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"barcodes":{"type":"array","items":{"type":"object","properties":{"format":{"type":"string"},"text":{"type":"string"},"symbologyIdentifier":{"type":"string"},"ecLevel":{"type":"string"},"position":{"type":"object"},"gs1":{"type":"object"}},"required":[]}}},"required":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"description":"Image too large"},"415":{"description":"Not a PNG or JPEG"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/zpl/render":{"post":{"summary":"Render ZPL to SVG (printer dots)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zpl":{"type":"string"},"dpmm":{"type":"integer","enum":[6,8,12,24],"default":8,"description":"Printer resolution in dots per mm (6, 8, 12, 24 = 152, 203, 300, 600 dpi)"},"widthMm":{"type":"number","description":"Label width in mm if the ZPL has no ^PW","default":101.6},"heightMm":{"type":"number","description":"Label height in mm if the ZPL has no ^LL","default":152.4}},"required":["zpl"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","properties":{"svg":{"type":"string"},"widthDots":{"type":"integer"},"heightDots":{"type":"integer"}},"required":[]}},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"code":{"type":"string"},"command":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"detail":{"type":"string"}},"required":[]}}},"required":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/zpl/validate":{"post":{"summary":"Check ZPL and list issues and commands","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zpl":{"type":"string"},"dpmm":{"type":"integer","enum":[6,8,12,24],"default":8,"description":"Printer resolution in dots per mm (6, 8, 12, 24 = 152, 203, 300, 600 dpi)"},"widthMm":{"type":"number","description":"Label width in mm if the ZPL has no ^PW","default":101.6},"heightMm":{"type":"number","description":"Label height in mm if the ZPL has no ^LL","default":152.4}},"required":["zpl"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"labels":{"type":"integer"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"code":{"type":"string"},"command":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"detail":{"type":"string"}},"required":[]}},"commands":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"}},"required":[]}}},"required":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/barcode-to-zpl":{"post":{"summary":"Generate ZPL for a barcode","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"symbology":{"type":"string","enum":["EAN-13","EAN-8","UPC-A","Code 128","GS1-128","Code 39","Code 93","ITF","DataMatrix","GS1 DataMatrix","QR Code","PDF417","Aztec"]},"data":{"type":"string"},"dpmm":{"type":"integer","enum":[6,8,12,24],"default":8,"description":"Printer resolution in dots per mm (6, 8, 12, 24 = 152, 203, 300, 600 dpi)"},"widthMm":{"type":"number","description":"Label width in mm if the ZPL has no ^PW","default":101.6},"heightMm":{"type":"number","description":"Label height in mm if the ZPL has no ^LL","default":152.4},"x":{"type":"number","description":"Field origin x in dots","default":40},"y":{"type":"number","description":"Field origin y in dots","default":40},"module":{"type":"number","description":"Module width in dots","default":3},"height":{"type":"number","description":"1D bar height in dots","default":120},"hri":{"type":"boolean","default":true},"orientation":{"type":"string","enum":["N","R","I","B"],"default":"N"}},"required":["symbology","data"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"zpl":{"type":"string"}},"required":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"The symbology cannot encode the data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"cannot_encode"},"detail":{"type":"string"}},"required":[]}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/batch/validate":{"post":{"summary":"Validate up to 10,000 GTINs or GS1 element strings","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"array","items":{"type":"string"},"maxItems":10000}},"required":["values"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object"}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"valid":{"type":"integer"},"invalid":{"type":"integer"},"duplicates":{"type":"integer"},"errors":{"type":"object"}},"required":[]}},"required":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}