ForSURE.orders_data.fulfilment.__api__

Base URL for all requests

Retrieve fulfilment/packaging data with filtering, pagination, and search capabilities.

This endpoint returns a paginated list of fulfilment records grouped by order ID. Fulfilment data includes packaging dimensions, weights, box IDs, and other packaging information for orders.

Parameters

limit int, default 50 - Maximum number of fulfilment groups to return (1-200).

offset int, default 0 - Number of fulfilment groups to skip for pagination.

start_date date, optional - Filter fulfilment from this date (inclusive). Format: YYYY-MM-DD.

end_date date, optional - Filter fulfilment until this date (inclusive). Format: YYYY-MM-DD.

search str, optional - Free text search across all string columns (case-insensitive partial match).

source str, optional - Filter by specific source/file name.

Returns

FulfilmentPage

Paginated response containing:

items list - List of fulfilment records grouped by order ID

source_names list - List of unique source names in the result set

total int - Total number of fulfilment groups matching the filters

limit int - Current page size

offset int - Current offset

next_offset int - Offset for next page (None if no next page)

prev_offset int - Offset for previous page (None if no previous page)

Example

curl -X GET "https://api.example.com/saas/fulfilment?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31&search=FS1234" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
  "items": [
    {
      "orderid": "FS1234",
      "dimension": "10x20x15",
      "fulfilmentday": "2024-01-15T10:30:00Z",
      "total_weight": 2.5,
      "main_type": "Box",
      "main_type_weight": 0.3,
      "box_id": "BOX001",
      "source": "fulfilment_upload_2024_01",
      "profile": 1
    }
  ],
  "source_names": ["fulfilment_upload_2024_01"],
  "total": 150,
  "limit": 50,
  "offset": 0,
  "next_offset": 50,
  "prev_offset": null
}

{
  "detail": "Failed to get fulfilment"
}

Note

Requires ORDERS_VIEW permission. Results are grouped by order ID.

Add fulfilment/packaging data to the system via API using profile-based column mapping.

This endpoint allows you to add fulfilment data using a flexible dictionary format where column names can be any keys. The profile defines the mapping between your external column names and the internal system field names. This is useful when integrating with external systems that use different column naming conventions.

Parameters

fulfilment FulfilmentWithProfileAPI - FulfilmentWithProfileAPI object containing:

• fulfilment: List of dictionaries with any keys. The keys should match the column names defined in your profile mapping. Example:

[
  {
    "Order ID": "FS1234",
    "Dimension": "10x20x15",
    "Fulfilment Day": "2024-01-15T10:30:00Z",
    "Total Weight": 2.5,
    "Main Type": "Box",
    "Box SKU": "BOX001"
  }
]

• profile: Profile ID (int) that defines the column mapping. The profile must be configured with mappings for required fields: orderid and total_weight.

Returns

dict

Response containing:

status str - "success" if operation completed

failed list, optional - List of failed fulfilment records if any

Raises

HTTPException If profile is not found or required mappings are missing

Example

curl -X POST "https://api.example.com/saas/fulfilment/add-with-profile" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "fulfilment": [
    {
      "Order ID": "FS1234",
      "Dimension": "10x20x15",
      "Fulfilment Day": "2024-01-15T10:30:00Z",
      "Total Weight": 2.5,
      "Main Type": "Box",
      "Box SKU": "BOX001"
    }
  ],
  "profile": 1
}'

Response Example

{
  "status": "success",
  "failed": []
}

{
  "detail": "Failed to add fulfilment with profile mapping: Profile 1 not found or not configured for this organization"
}

Note

Requires ORDERS_ADD permission. The profile must be configured with proper column mappings before using this endpoint. Any columns in your fulfilment dictionaries that are not mapped in the profile will be stored in the 'unmapped' field as JSON. Duplicate detection is based on orderid.

Upload fulfilment/packaging data from CSV or Excel files.

This endpoint allows bulk upload of fulfilment data from CSV or Excel files. Fulfilment data includes packaging dimensions, weights, box IDs, and other packaging information. Files are processed in the background to handle large uploads efficiently.

Parameters

file_lists list[UploadFile] - List of uploaded files (CSV or Excel format).

profiles list[str] - List of profile IDs, one per file. Profiles define column mappings.

fileId list[str] - List of file identifiers to track the source of each fulfilment record.

resolutions list[str] - List of JSON strings containing column name mappings (external -> internal).

Returns

dict

Response containing:

status_code int - HTTP status code: 200: Success (files are being processed in background), 400: Error (contains list of file errors with file IDs)

Raises

HTTPException If file validation fails or processing errors occur.

Example

curl -X POST "https://api.example.com/saas/fulfilment/upload" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file_lists=@fulfilment1.csv" \
-F "file_lists=@fulfilment2.xlsx" \
-F "profiles=1" \
-F "profiles=2" \
-F "fileId=source1" \
-F "fileId=source2" \
-F 'resolutions={"Order ID": "orderid", "Dimensions": "dimension"}' \
-F 'resolutions={}'

Response Example

{
  "status_code": 200
}

{
  "status_code": 400,
  "data": [
    {
      "id": "source1",
      "error": "File validation failed: missing required column 'orderid'"
    }
  ]
}

Note

• Requires ORDERS_ADD permission
• Files are validated synchronously, then processed asynchronously
• Fulfilment algorithm can be applied if user has 'access-fulfilment-algorithm' attribute
• Each file must have a corresponding profile and fileId
• Column mappings must be defined correctly in the profile before upload

Validate a fulfilment file before upload.

This endpoint performs validation on a fulfilment file without actually uploading the data. It checks for required columns, data format, and provides feedback on any issues found. Use this endpoint before uploading to ensure your file is correctly formatted.

Parameters

file_list UploadFile - The fulfilment file to validate (CSV or Excel format).

profile int - Profile ID that defines the expected column mapping.

Returns

dict

Validation result containing:

success bool - True if file is valid, False otherwise

total_fulfilment int - Total number of fulfilment records found in the file

missing_fulfilment int - Number of records with missing required fields

details dict - Detailed information about validation issues

description str - Human-readable description of validation results

Example

curl -X POST "https://api.example.com/saas/fulfilment/check" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file_list=@fulfilment.csv" \
-F "profile=1"

Response Example

{
  "success": true,
  "total_fulfilment": 150,
  "missing_fulfilment": 0,
  "details": {},
  "description": "File validation successful"
}

{
  "success": false,
  "total_fulfilment": 150,
  "missing_fulfilment": 5,
  "details": {
    "missing_orderid": 3,
    "missing_dimension": 2
  },
  "description": "File validation failed: 5 records have missing required fields"
}

Note

• Requires ORDERS_ADD permission
• This endpoint does not save any data - it only validates
• Use this before /upload to catch errors early
• Profile must be configured with correct column mappings