Data Import API — cURL Commands for Postman

These cURLs target the Data Import module at {{BASE_URL}}. Replace {{BASE_URL}} and {{ID_TOKEN}} with your values.

Authentication: All endpoints (except preview and template download) require a valid Firebase ID token via Authorization: Bearer <token> or flowpos-id-token cookie. Endpoints that take businessId (upload, list jobs, get job, get job errors) also enforce business access: the user must be root, have a role for that business in the token, or be linked to the business in the DB — otherwise the API returns 403 Access denied to the requested business.

1. Upload file and create import job

POST /data-import/upload

Content-Type: multipart/form-data

Field	Type	Required	Description
file	file	✓	Excel (.xlsx, .xls) or CSV file (max 10MB)
importType	string	✓	One of: attribute, brand, category, color, customer, employee, location, size, style, model, product, product_with_variants, opening_inventory, price_list, price_list_scope, price_list_item, supplier
mapping	string	✓	JSON: `{ "Source Column": "targetField" }` e.g. `{"Brand Name": "name"}`
businessId	string	✓	UUID of the business

curl -X POST '{{BASE_URL}}/data-import/upload' \
  -H 'Authorization: Bearer {{ID_TOKEN}}' \
  -F 'file=@/path/to/your-import-file.xlsx' \
  -F 'importType=brand' \
  -F 'mapping={"Brand Name":"name","Code":"code"}' \
  -F 'businessId={{businessId}}'

Example with brand import:

curl -X POST '{{BASE_URL}}/data-import/upload' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN' \
  -F 'file=@./brands.xlsx' \
  -F 'importType=brand' \
  -F 'mapping={"name":"name","code":"code"}' \
  -F 'businessId={{businessId}}'

2. List import jobs

GET /data-import/jobs

Query param	Type	Required	Description
businessId	string	✓	UUID of the business
importType	string	no	brand, category, color, etc.
status	string	no	pending, processing, completed, failed
page	number	no	Page number for pagination
size	number	no	Page size

curl -X GET '{{BASE_URL}}/data-import/jobs?businessId={{businessId}}&importType=brand&status=completed&page=1&size=20' \
  -H 'Authorization: Bearer {{ID_TOKEN}}'

Minimal example:

curl -X GET '{{BASE_URL}}/data-import/jobs?businessId={{businessId}}' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN'

3. Get import job by ID

GET /data-import/jobs/:id

Path param	Description
id	Import job UUID

Query param	Required	Description
businessId	✓	Business UUID

curl -X GET '{{BASE_URL}}/data-import/jobs/{{dataImportJobId}}?businessId={{businessId}}' \
  -H 'Authorization: Bearer {{ID_TOKEN}}'

Example:

curl -X GET '{{BASE_URL}}/data-import/jobs/{{dataImportJobId}}?businessId={{businessId}}' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN'

4. Get job error rows

GET /data-import/jobs/:id/errors

Returns error rows as JSON (default) or CSV.

Path param	Description
id	Import job UUID

Query param	Required	Description
businessId	✓	Business UUID
format	no	`csv` for CSV with content and filename

JSON (default):

curl -X GET '{{BASE_URL}}/data-import/jobs/{{dataImportJobId}}/errors?businessId={{businessId}}' \
  -H 'Authorization: Bearer {{ID_TOKEN}}'

CSV format:

curl -X GET '{{BASE_URL}}/data-import/jobs/{{dataImportJobId}}/errors?businessId={{businessId}}&format=csv' \
  -H 'Authorization: Bearer {{ID_TOKEN}}'

5. Preview mapped rows (first 20)

POST /data-import/preview

Parses the file and returns a preview of the first 20 rows using the provided mapping. Does not persist data.

Content-Type: multipart/form-data

Field	Type	Required	Description
file	file	✓	Excel (.xlsx, .xls) or CSV file (max 10MB)
mapping	string	✓	JSON: `{ "Source Column": "targetField" }`
businessId	string	no	Business UUID (optional)

curl -X POST '{{BASE_URL}}/data-import/preview' \
  -H 'Authorization: Bearer {{ID_TOKEN}}' \
  -F 'file=@/path/to/your-import-file.xlsx' \
  -F 'mapping={"Brand Name":"name","Code":"code"}'

6. Download Excel template

GET /data-import/templates/:importType

Returns an Excel template for the given import type.

Import types: attribute, brand, category, color, customer, employee, location, size, style, model, product, product_with_variants, opening_inventory, price_list, price_list_scope, price_list_item, supplier

curl -X GET '{{BASE_URL}}/data-import/templates/{{importType}}' \
  -H 'Authorization: Bearer {{ID_TOKEN}}' \
  -o ./{{importType}}-import-template.xlsx

Examples:

# Brand template
curl -X GET '{{BASE_URL}}/data-import/templates/brand' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN' \
  -o ./brand-import-template.xlsx

# Product template
curl -X GET '{{BASE_URL}}/data-import/templates/product' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN' \
  -o ./product-import-template.xlsx

# Customer template
curl -X GET '{{BASE_URL}}/data-import/templates/customer' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN' \
  -o ./customer-import-template.xlsx

Import type schemas (column headers)

importType	Headers
attribute	name, description, isActive
brand	name, code
category	name, parentName, code
color	name, code, hex
size	name, code, sortOrder
style	name, code, brandName
model	name, code, brandName
product	name, sku, barcode, category, brand, color, size, style, model, unitOfMeasure, price, cost, currency, description, taxes, isActive
product_with_variants	name, category, unitOfMeasure, cost, variantSku, variantPrice, variantBarcode, optionType1, optionValue1, optionType2, optionValue2, optionType3, optionValue3, currency, brand, description, taxes, isActive, generateBarcode
opening_inventory	sku, location, quantity, cost
customer	name, firstName, lastName, email, phone, taxId, taxName, taxAddress, customerCode, address, city, country, creditLimit
employee	fullName, employeeNumber, email, phone, locationName, userEmail, position, department, employmentType, hireDate, terminationDate, commissionRate, hourlyRate, salaryAmount, tipPoolShare, serverNumber, canTakeOrders, canCloseTables, maxTableCapacity, salesTargetMonthly, canProcessReturns, defaultShift, worksWeekends, isActive, isManager, canApproveReturns, canApproveDiscounts, canApproveVoids, canOverridePrices, notes
location	name, timezone, taxNumber, availableToSell, availableToBuy, isActive, lineOne, lineTwo, postalCode, municipality, department, countryId
price_list	name, kind, channel, currency, priority, validFrom, validTo, isActive, notes
price_list_scope	priceListName, locationName, channel, isDefault, isActive
price_list_item	priceListName, itemType, itemIdentifier, unitPrice, minQty, priority, validFrom, validTo, isActive
supplier	name, supplierCode, email, phone, taxId, taxName, taxAddress, address, city, postalCode, country, stateName, departmentName, municipalityName, taxpayerType, isActive

Product taxes column: Optional. Empty = default product taxes for new rows; none = no taxes; IVA or IVA\|ISR or IVA:12 = tax codes (and optional rate). See user guide.

Postman variables

Suggested Postman environment variables:

Variable	Example value
API_URL	<{{BASE_URL}}>
ID_TOKEN	eyJhbGciOiJSUzI1NiIs...
BUSINESS_ID	{{businessId}}
JOB_ID	{{dataImportJobId}}
IMPORT_TYPE	brand

Notes

Max file size: 10MB
Allowed file types: .xlsx, .xls, .csv
mapping: In form-data, mapping must be a JSON string (Postman handles this when using JSON in the value)
Auth: Obtain the Firebase ID token from your frontend or Firebase Auth client and pass it in the Authorization: Bearer <token> header

1. Upload file and create import job​

2. List import jobs​

3. Get import job by ID​

4. Get job error rows​

5. Preview mapped rows (first 20)​

6. Download Excel template​

Import type schemas (column headers)​

Postman variables​

Notes​