What the data for this category looks like
Duty-free marketing content data is mainly sourced from the commodity management systems of duty-free business entities, off-island duty-free policy announcement platforms, and member marketing backends. The data update rhythm is adjusted according to business nodes. Regular commodity information is synchronized weekly, while limited-time promotional activities are updated in real time or daily. Most data documents are in structured JSON or CSV formats. Core fields include commodity code, commodity name, dutiable price, duty-free discount rate, off-island eligible user groups, activity effective time, and activity expiration time. Price-related fields use RMB yuan as the unit, time fields adopt the ISO 8601 standard format, and some associated fields need to be bound with off-island port verification identifiers.
Constraints Imposed on HTTP Interfaces and External Systems by These Data Characteristics
The data characteristics of duty-free marketing content impose multiple constraints on interfaces and external systems. Multi-source data requirements mean interfaces must support access requests in different formats, and provide field mapping configurations to unify data structures. Real-time updated promotional activities require interfaces to support webhook callback modes, while weekly updated regular commodity data can be synchronized via scheduled pull interfaces. Exclusive fields such as off-island ports and applicable user groups require interface parameters to include corresponding verification items to prevent invalid data from entering the system. Price-related fields use RMB yuan as the fixed unit; interfaces must not arbitrarily convert units, and must clearly mark the field unit in responses. Temporary changes to policy-related fields require interfaces to support timestamp verification to ensure that the latest compliant content is obtained.
How to Set the Configurations
| Configuration Item | Recommended Value | Rationale |
|---|---|---|
external_sync_interval | 604800 seconds | Matches the weekly update rhythm of regular duty-free commodities, balancing data timeliness and system resource usage |
webhook_trigger_event | promotion_update | Triggers callbacks only when duty-free limited-time promotional activities change, avoiding invalid requests |
response_field_filter | ["sku_id","tax_free_price","valid_period","is_compliant"] | Returns only the required fields for marketing content, reducing data transmission redundancy |
unit_validation_enabled | Enabled | Duty-free price fields use RMB yuan as the fixed unit; enabling verification prevents unit conversion errors |
policy_version_check | Enabled | Off-island policies change frequently; verifying version numbers ensures access to the latest compliant data |
max_batch_request_count | 100 items | Adapts to the typical scale of duty-free commodity SKUs; pulling 100 items per request balances transmission efficiency and interface load |
The parameter values provided on this page are common recommended starting points for configuration. Actual values are affected by material formats, data volume, and business rules. Specific issues require individual analysis, and it is recommended to test on your own samples before finalizing settings.
Three Common Misconfigurations
- Symptom: In instances deployed via docker compose, the configuration interface has no input field for
oneapi_base_url, and calling external systems prompts "Third-party service address not configured". Cause: This parameter is not added to the environment variable list in docker-compose.yml by default; theONEAPI_BASE_URLenvironment configuration item must be added manually. - Symptom: When pushing duty-free marketing data in multiple table formats, the interface only accepts single pieces of data and returns an error "Field format is invalid". Cause: The
webhook_data_formatconfiguration is not set to support multi-table parsing; the default mode only adapts to single pieces of structured data. - Symptom: Pulled off-island duty-free policy content does not match the latest announced content, and the returned activity validity period is incorrect. Cause: The
policy_version_checkconfiguration is not enabled, and the interface does not verify the data version timestamp, resulting in access to old version policy data.
How to Confirm Configurations Are Properly Set
- Call the test interface, check if the returned fields match those configured in
response_field_filter, and confirm that only the required marketing content fields are included. - Trigger a promotional update webhook, check if the external system receives the corresponding data, and confirm that the callback trigger logic works normally.
- Check the unit of the price field returned by the interface, confirm that it is RMB yuan, and verify that the
unit_validation_enabledconfiguration is active. - Check the logs of the scheduled synchronization task, confirm that the synchronization interval matches the
external_sync_intervalsetting, and there are no abnormal timeout errors.
Question material comes from public community discussions. Configuration values are common starting points and should be measured against your own samples. Verified on 2026-09-14.