Catalogue
Upload a shop or marketplace catalogue (CSV, XLSX, JSON, a PDF of up to 20 pages, or a photo) and get its columns mapped to product fields and its rows back as product records. Nothing is classified and nothing is stored.
Parse a catalogue file without classification or storage
Required scope: ai-engine:easydogana:catalogue:parse
Parameters
- Name
x-request-id- Type
- string · nullable
- Description
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Allowed values:
2026-10-23. Default:2026-10-23.
Request body Body_parseCatalogue
- Name
allow_llm- Type
- boolean
- Description
Default:
true.
- Name
column_map- Type
- string · nullable
- Description
JSON object mapping exact headers to catalogue fields
- Name
currency_hint- Type
- string · nullable
- Description
- Name
file- Type
- string
- required
- Description
Catalogue file: CSV, XLSX, JSON, PDF or photos (PNG, JPG, JPEG)
- Name
locale- Type
- string · nullable
- Description
Responses
200Successful ResponseCatalogueParseResponse401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail403The token is valid but carries none of the required scopes.ErrorDetail413Request Entity Too LargeCatalogueErrorResponse415Unsupported Media TypeCatalogueErrorResponse422Unprocessable EntityCatalogueErrorResponse500Internal Server ErrorCatalogueErrorResponse502Bad GatewayCatalogueErrorResponse503Service UnavailableCatalogueErrorResponse504Gateway TimeoutCatalogueErrorResponse
Request
curl -X POST "https://ai-engine.parcelabs.com/easydogana/catalogue/parse" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@/path/to/file" \
-F 'allow_llm=true' \
-F 'currency_hint=EUR'Response 200
{
"capabilities": {
"classification": false
},
"columns": [
{
"confidence": 1,
"field": "group_key",
"method": "synonym",
"source_header": "Handle"
},
{
"confidence": 1,
"field": "description",
"method": "synonym",
"source_header": "Title"
},
{
"confidence": 1,
"field": "sku",
"method": "synonym",
"source_header": "Variant SKU"
},
{
"confidence": 1,
"field": "weight",
"method": "synonym",
"source_header": "Variant Grams",
"unit": "g"
},
{
"confidence": 1,
"field": "quantity",
"method": "synonym",
"source_header": "Variant Inventory Qty"
},
{
"confidence": 1,
"field": "price",
"method": "synonym",
"source_header": "Variant Price"
},
{
"confidence": 1,
"field": "gtin",
"method": "synonym",
"source_header": "Variant Barcode"
},
{
"confidence": 1,
"field": "weight_unit",
"method": "synonym",
"source_header": "Variant Weight Unit"
},
{
"confidence": 1,
"field": "cost",
"method": "synonym",
"source_header": "Cost per item"
},
{
"confidence": 1,
"field": "details",
"method": "synonym",
"source_header": "Body (HTML)"
}
],
"cost_usd": 0.0012,
"engine_version": "catalogue-parse-v1",
"input": {
"filename_ext": "csv",
"kind": "tabular",
"sheets_ignored": 0
},
"llm_calls": 1,
"llm_used": true,
"request_id": "d2dc15bd-006d-4db5-b555-cfa1c7f67b79",
"rows": [
{
"cost": 4,
"currency": "EUR",
"currency_source": "hint",
"description": "Wool socks for men with reinforced heel",
"description_en": "Wool socks for men with reinforced heel",
"details": "Warm & soft",
"group_key": "wool-socks",
"gtin": "8001234567897",
"input_hash": "1260e9f59ed3c03782aed44128fe2cb75809436df18f6c3c8a1084950f592e0f",
"sku": "SOCK-BL-42",
"source_language": "en",
"source_row": 1,
"value": 12.5,
"warnings": [],
"weight_kg": 0.085
},
{
"cost": 4,
"currency": "EUR",
"currency_source": "hint",
"description": "Wool socks for men with reinforced heel",
"description_en": "Wool socks for men with reinforced heel",
"group_key": "wool-socks",
"input_hash": "15d0dbfc71257862f620359c54059364472000f9b14f4bdd0454eb83c056916d",
"sku": "SOCK-RD-42",
"source_language": "en",
"source_row": 2,
"value": 12.5,
"warnings": [
{
"code": "DESCRIPTION_INHERITED"
}
],
"weight_kg": 0.09
},
{
"cost": 6,
"currency": "EUR",
"currency_source": "hint",
"description": "Maglietta di cotone con il logo",
"description_en": "Cotton t-shirt with the logo",
"details": "100% cotton",
"group_key": "cotton-tee",
"input_hash": "289d4ef4acaebce4a733c0fd8423c84cc203ce0fb307d73a5ed7a9be62161311",
"sku": "TEE-1",
"source_language": "it",
"source_row": 3,
"value": 19.9,
"warnings": [],
"weight_kg": 0.2
}
],
"summary": {
"fields_filled": {
"dimensions_cm": 0,
"gtin": 1,
"hs_code_in_file": 0,
"origin": 0,
"sku": 3,
"value": 3,
"weight_kg": 3
},
"rows_read": 3,
"rows_skipped": 0,
"rows_with_warnings": 1,
"source_languages": {
"en": 2,
"it": 1
}
},
"took_ms": 430,
"unmapped_headers": [],
"warnings": []
}Models
Objects used by the requests and responses on this page.
Body_parseCatalogue
- Name
allow_llm- Type
- boolean
- Description
Default:
true.
- Name
column_map- Type
- string · nullable
- Description
JSON object mapping exact headers to catalogue fields
- Name
currency_hint- Type
- string · nullable
- Description
- Name
file- Type
- string
- required
- Description
Catalogue file: CSV, XLSX, JSON, PDF or photos (PNG, JPG, JPEG)
- Name
locale- Type
- string · nullable
- Description
CatalogueParseResponse
- Name
capabilities- Type
- CatalogueCapabilities
- required
- Description
- Name
columns- Type
- array of CatalogueColumn
- required
- Description
- Name
cost_usd- Type
- number
- required
- Description
- Name
engine_version- Type
- string
- required
- Description
- Name
input- Type
- CatalogueInput
- required
- Description
- Name
llm_calls- Type
- integer
- required
- Description
- Name
llm_used- Type
- boolean
- required
- Description
- Name
request_id- Type
- string
- required
- Description
- Name
rows- Type
- array of CatalogueRow
- required
- Description
- Name
summary- Type
- CatalogueSummary
- required
- Description
- Name
took_ms- Type
- integer
- required
- Description
- Name
unmapped_headers- Type
- array of string
- required
- Description
- Name
warnings- Type
- array of CatalogueWarning
- required
- Description
CatalogueCapabilities
- Name
classification- Type
- boolean
- Description
Default:
false.
CatalogueColumn
- Name
confidence- Type
- number
- required
- Description
- Name
currency- Type
- string · nullable
- Description
- Name
field- Type
- string
- required
- Description
- Name
method- Type
- string
- required
- Description
- Name
source_header- Type
- string
- required
- Description
- Name
unit- Type
- string · nullable
- Description
CatalogueInput
- Name
filename_ext- Type
- string
- required
- Description
- Name
kind- Type
- string
- required
- Description
- Name
pages_in_file- Type
- integer · nullable
- Description
- Name
pages_read- Type
- integer · nullable
- Description
- Name
sheet- Type
- string · nullable
- Description
- Name
sheets_ignored- Type
- integer
- Description
Default:
0.
CatalogueRow
- Name
classification- Type
- null
- Description
- Name
cost- Type
- number · nullable
- required
- Description
- Name
currency- Type
- string · nullable
- required
- Description
- Name
currency_source- Type
- string · nullable
- required
- Description
- Name
description- Type
- string
- required
- Description
- Name
description_en- Type
- string · nullable
- required
- Description
- Name
details- Type
- string · nullable
- required
- Description
- Name
dimensions_cm- Type
- DimensionsCM · nullable
- required
- Description
- Name
extraction_confidence- Type
- string · nullable
- Description
- Name
group_key- Type
- string · nullable
- required
- Description
- Name
gtin- Type
- string · nullable
- required
- Description
- Name
hs_code_in_file- Type
- string · nullable
- required
- Description
- Name
input_hash- Type
- string
- required
- Description
- Name
origin- Type
- string · nullable
- required
- Description
- Name
sku- Type
- string · nullable
- required
- Description
- Name
source_language- Type
- string · nullable
- required
- Description
- Name
source_row- Type
- integer
- required
- Description
1-based index of the data row after the header row, blank rows included; not the file line number.
- Name
value- Type
- number · nullable
- required
- Description
- Name
warnings- Type
- array of RowWarning
- required
- Description
- Name
weight_kg- Type
- number · nullable
- required
- Description
DimensionsCM
- Name
h- Type
- number · nullable
- required
- Description
- Name
l- Type
- number · nullable
- required
- Description
- Name
w- Type
- number · nullable
- required
- Description
RowWarning
- Name
code- Type
- string
- required
- Description
- Name
field- Type
- string · nullable
- Description
CatalogueSummary
- Name
fields_filled- Type
- map of integer
- required
- Description
- Name
rows_read- Type
- integer
- required
- Description
- Name
rows_skipped- Type
- integer
- required
- Description
- Name
rows_with_warnings- Type
- integer
- required
- Description
- Name
source_languages- Type
- map of integer
- required
- Description
CatalogueWarning
- Name
code- Type
- string
- required
- Description
- Name
details- Type
- object · nullable
- Description
- Name
message- Type
- string
- required
- Description
ErrorDetail
Body of every error returned through FastAPI's `HTTPException`.
- Name
detail- Type
- string
- required
- Description
Human-readable reason. Not a stable machine code.
CatalogueErrorResponse
- Name
error- Type
- CatalogueErrorDetail
- required
- Description
CatalogueErrorDetail
- Name
code- Type
- string
- required
- Description
- Name
details- Type
- object · nullable
- Description
- Name
message- Type
- string
- required
- Description