{"openapi":"3.1.0","info":{"title":"IMBRIQ public packaging dimension comparison API","version":"0.2.0","description":"Stateless nominal-dimension screening for manufacturer case references or caller-supplied cartons. One occupied envelope is compared with internal dimensions; this is not multi-item packing, shipping-cost optimization, strength validation or engineering approval. No live supplier feed or customer CAD processing. The precomputed generic CAD reference is served separately."},"servers":[{"url":"/"}],"security":[],"paths":{"/api/packaging/catalog":{"get":{"operationId":"getPackagingCatalog","summary":"Read the selected manufacturer case references","responses":{"200":{"description":"Reference case catalog, nominal dimensions and provenance. Carton options are supplied in the evaluation request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}}}}},"/api/packaging/evaluate":{"post":{"operationId":"evaluatePackagingEnvelope","summary":"Compare an explicit envelope with reference cases or caller-supplied cartons","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationRequest"},"examples":{"referenceCases":{"summary":"Existing case-catalog request; family defaults to case","value":{"units":"mm","envelope":{"length":214,"width":110,"height":65},"paddingPerSideMm":10,"orientation":"upright"}},"callerCartons":{"summary":"Caller-supplied carton sizes; no manufacturer or stock claim","value":{"units":"mm","packagingFamily":"carton","envelope":{"length":214,"width":110,"height":65},"paddingPerSideMm":10,"orientation":"upright","cartonOptions":[{"id":"box-240","label":"Warehouse box 240","internalDimensionsMm":{"length":240,"width":140,"height":90}},{"id":"box-300","label":"Warehouse box 300","internalDimensionsMm":{"length":300,"width":200,"height":150}}]}}}}}},"responses":{"200":{"description":"Candidates or an explicit no-match / no-catalog result. No engineering approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationResponse"}}}},"400":{"description":"Invalid JSON, units, fields, dimensions, catalog identifiers or carton options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Cross-origin browser request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Comparison unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"DimensionsMm":{"type":"object","additionalProperties":false,"required":["length","width","height"],"properties":{"length":{"type":"number","exclusiveMinimum":0,"maximum":3000,"multipleOf":0.001,"description":"length in millimetres; not a measurement-accuracy claim."},"width":{"type":"number","exclusiveMinimum":0,"maximum":3000,"multipleOf":0.001,"description":"width in millimetres; not a measurement-accuracy claim."},"height":{"type":"number","exclusiveMinimum":0,"maximum":3000,"multipleOf":0.001,"description":"height in millimetres; not a measurement-accuracy claim."}}},"EvaluationRequest":{"type":"object","additionalProperties":false,"required":["units","envelope","paddingPerSideMm"],"properties":{"units":{"type":"string","const":"mm"},"envelope":{"$ref":"#/components/schemas/DimensionsMm"},"packagingFamily":{"type":"string","enum":["case","carton"],"default":"case","description":"Omit for the existing case catalogs. Carton requests require explicit cartonOptions and reject allowedCatalogs."},"cartonOptions":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CartonOption"},"description":"Caller-supplied carton sizes. IDs must be unique within the request. Required for carton; not allowed for case. The total request remains limited to 8 KiB."},"paddingPerSideMm":{"type":"number","minimum":0,"maximum":250,"multipleOf":0.001,"description":"Added on both sides of all three envelope axes."},"allowedCatalogs":{"type":"array","maxItems":6,"items":{"type":"string","enum":["peli","nanuk","skb","hprc","explorer","zarges"]},"description":"Case requests only. Omit to consider all case catalogs; [] explicitly considers none. Duplicates are deduplicated."},"orientation":{"type":"string","enum":["upright","fixed"],"default":"upright","description":"upright allows 0° or 90° footprint rotation without tipping the height; fixed only checks the supplied orientation."}},"oneOf":[{"properties":{"packagingFamily":{"const":"case"}},"not":{"required":["cartonOptions"]}},{"required":["packagingFamily","cartonOptions"],"properties":{"packagingFamily":{"const":"carton"}},"not":{"required":["allowedCatalogs"]}}]},"CartonOption":{"type":"object","additionalProperties":false,"required":["id","label","internalDimensionsMm"],"properties":{"id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$","description":"Unique caller identifier. Returned unchanged as referenceId."},"label":{"type":"string","minLength":1,"maxLength":80,"pattern":"\\S","description":"Nonblank caller label; surrounding whitespace is trimmed."},"internalDimensionsMm":{"$ref":"#/components/schemas/DimensionsMm"}}},"Catalog":{"type":"object","additionalProperties":false,"required":["id","label","logo","sourceUrl","referenceCount"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"logo":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"referenceCount":{"type":"integer","minimum":0}}},"CatalogReference":{"type":"object","additionalProperties":false,"required":["id","catalogId","model","label","internalDimensionsMm","manufacturerUrl","logo","thumbnail"],"properties":{"id":{"type":"string"},"catalogId":{"type":"string"},"model":{"type":"string"},"label":{"type":"string"},"internalDimensionsMm":{"$ref":"#/components/schemas/DimensionsMm"},"manufacturerUrl":{"type":"string","format":"uri"},"geometryNote":{"type":"string","description":"Manufacturer geometry caveat, when available. Screening does not resolve this caveat."},"logo":{"type":"string"},"thumbnail":{"type":"string"}}},"CatalogResponse":{"type":"object","additionalProperties":false,"required":["ok","apiVersion","units","referenceCatalog","liveSupplierFeed","catalogs","references","geometryBasis","pricesIncluded","availabilityIncluded","engineeringApproved"],"properties":{"ok":{"const":true},"apiVersion":{"const":"0.2.0"},"units":{"const":"mm"},"referenceCatalog":{"const":true},"liveSupplierFeed":{"const":false},"catalogs":{"type":"array","items":{"$ref":"#/components/schemas/Catalog"}},"references":{"type":"array","items":{"$ref":"#/components/schemas/CatalogReference"}},"geometryBasis":{"const":"manufacturer_nominal_internal_dimensions"},"pricesIncluded":{"const":false},"availabilityIncluded":{"const":false},"engineeringApproved":{"const":false}}},"EvaluatedInput":{"type":"object","additionalProperties":false,"required":["units","envelope","paddingPerSideMm","orientation","packagingFamily"],"properties":{"units":{"const":"mm"},"envelope":{"$ref":"#/components/schemas/DimensionsMm"},"packagingFamily":{"enum":["case","carton"]},"cartonOptions":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CartonOption"}},"paddingPerSideMm":{"type":"number","minimum":0,"maximum":250,"multipleOf":0.001},"orientation":{"enum":["upright","fixed"]},"allowedCatalogs":{"type":"array","items":{"type":"string"},"uniqueItems":true}},"oneOf":[{"properties":{"packagingFamily":{"const":"case"}},"not":{"required":["cartonOptions"]}},{"required":["packagingFamily","cartonOptions"],"properties":{"packagingFamily":{"const":"carton"}},"not":{"required":["allowedCatalogs"]}}]},"OrientationCheck":{"type":"object","additionalProperties":false,"required":["rotationZDegrees","marginMm","failedAxes","qualifies"],"properties":{"rotationZDegrees":{"type":"integer","enum":[0,90]},"marginMm":{"type":"object","additionalProperties":false,"required":["length","width","height"],"properties":{"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}},"description":"Internal nominal dimension minus the protected envelope; negative means a shortfall. This is total axis margin, not margin per side."},"failedAxes":{"type":"array","uniqueItems":true,"items":{"enum":["length","width","height"]}},"qualifies":{"type":"boolean"}}},"ReferenceEvaluation":{"type":"object","additionalProperties":false,"required":["referenceId","catalogId","label","model","manufacturerUrl","internalDimensionsMm","nominalVolumeLitres","qualifies","selectedRotationZDegrees","reasonCodes","orientationChecks"],"properties":{"referenceId":{"type":"string"},"catalogId":{"type":"string"},"label":{"type":"string"},"model":{"type":"string"},"manufacturerUrl":{"type":"string","format":"uri"},"geometryNote":{"type":"string"},"internalDimensionsMm":{"$ref":"#/components/schemas/DimensionsMm"},"nominalVolumeLitres":{"type":"number","minimum":0},"qualifies":{"type":"boolean"},"selectedRotationZDegrees":{"type":["integer","null"],"enum":[0,90,null]},"reasonCodes":{"type":"array","uniqueItems":true,"items":{"enum":["footprint_too_small","height_too_small"]}},"orientationChecks":{"type":"array","minItems":1,"maxItems":2,"items":{"$ref":"#/components/schemas/OrientationCheck"}}}},"CartonEvaluation":{"type":"object","additionalProperties":false,"required":["referenceId","label","internalDimensionsMm","nominalVolumeLitres","qualifies","selectedRotationZDegrees","reasonCodes","orientationChecks"],"properties":{"referenceId":{"type":"string"},"label":{"type":"string"},"internalDimensionsMm":{"$ref":"#/components/schemas/DimensionsMm"},"nominalVolumeLitres":{"type":"number","minimum":0},"qualifies":{"type":"boolean"},"selectedRotationZDegrees":{"type":["integer","null"],"enum":[0,90,null]},"reasonCodes":{"type":"array","uniqueItems":true,"items":{"enum":["footprint_too_small","height_too_small"]}},"orientationChecks":{"type":"array","minItems":1,"maxItems":2,"items":{"$ref":"#/components/schemas/OrientationCheck"}}}},"EvaluationResponse":{"type":"object","additionalProperties":false,"required":["ok","apiVersion","engine","units","packagingFamily","catalogSource","status","input","requiredEnvelopeMm","catalogIds","checkedReferenceCount","matchingReferenceCount","recommendedReferenceId","rankedReferenceIds","results","ranking","engineeringApproved","checksPerformed","notValidated","dataStored"],"properties":{"ok":{"const":true},"apiVersion":{"const":"0.2.0"},"engine":{"const":"nominal-dimensions-v1"},"units":{"const":"mm"},"packagingFamily":{"enum":["case","carton"]},"catalogSource":{"enum":["manufacturer_reference_catalog","caller_supplied_cartons"]},"status":{"type":"string","enum":["no_catalogs","no_match","candidates_found"]},"input":{"$ref":"#/components/schemas/EvaluatedInput"},"requiredEnvelopeMm":{"type":"object","additionalProperties":false,"required":["length","width","height"],"properties":{"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}}},"catalogIds":{"type":"array","items":{"type":"string"},"description":"Selected manufacturer catalog IDs for cases; empty for caller-supplied cartons."},"checkedReferenceCount":{"type":"integer","minimum":0},"matchingReferenceCount":{"type":"integer","minimum":0},"recommendedReferenceId":{"type":["string","null"]},"rankedReferenceIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ReferenceEvaluation"},{"$ref":"#/components/schemas/CartonEvaluation"}]}},"ranking":{"const":"smallest_nominal_internal_volume"},"engineeringApproved":{"const":false},"checksPerformed":{"type":"array","items":{"type":"string"}},"notValidated":{"type":"array","items":{"type":"string"}},"dataStored":{"const":false}},"oneOf":[{"properties":{"packagingFamily":{"const":"case"},"catalogSource":{"const":"manufacturer_reference_catalog"},"results":{"items":{"$ref":"#/components/schemas/ReferenceEvaluation"}}}},{"properties":{"packagingFamily":{"const":"carton"},"catalogSource":{"const":"caller_supplied_cartons"},"catalogIds":{"maxItems":0},"results":{"items":{"$ref":"#/components/schemas/CartonEvaluation"}}}}]},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["ok","error"],"properties":{"ok":{"const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"enum":["invalid_request","invalid_content_length","empty_request","invalid_json","cross_origin_request","request_too_large","unsupported_media_type","evaluation_unavailable"]},"message":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}}}}}}}}}