Documentation Home

API Import

The API import is the same format as the CSV/XLSX file import through the admin with the CSV or excel portion of the request sent in the
body. The import endpoint is available at /api/importer if you have the admin application running. The full url is /admin/api/importer.

Requests

/api/importer/{importType}, POST

URI Parameters

  • importType - (required) The type of import to run, should map directly to a ImportType enumeration. Examples:
    • Product import - PRODUCT
    • Category import - CATEGORY
    • Customer import - CUSTOMER
    • Customer Address import - ADDRESS
    • Order import - ORDER
    • Bulk asset upload - ASSET

Request Parameters

  • importSpecification - (required) Specification of import type. Available default specifications are here. Provide any valid specification for Assets.
  • catalogId - (optional) The ID of the catalog that the items should be imported into
  • siteId - (optional) The ID of the site that the items should be imported into
  • userId - (optional) The ID of the user who is importing
  • importToSandbox - (optional) Can be True/False to indicate whether to import into a particular sandbox. If not specified the import goes straight to production.
  • sandboxId - (optional) The ID of the sandbox if importing into a particular sandbox. Above param importToSandbox needs to be true.
  • fileType - (optional) Defaults to CSV. Currently supports CSV or XLSX

Request Body

If executing a CSV based import, the request body should be the CSV data to be imported. Similarly, body can be an excel file if the fileType param is XLSX.
If executing a bulk asset upload, then the request body should be a .zip file containing the assets.

Response

The response is a JSON object representing the scheduled ImportStatus that also includes the status URL representing where
you should poll to determine the status of the import. Example:

{
  "status": "START_REQUESTED",
  "lastUpdateDate": "2020.11.09 21:13:11",
  "totalRecords": 5,
  "percentComplete": 0.0,
  "statusId": 1,
  "statusUrl": "/admin/api/importer/status/1",
  "details": []
}

/api/importer/{statusId}, GET

URI Parameters

  • statusId - the primary key of the import status you are trying to retrieve

Response

The response is a JSON object representing the scheduled ImportStatus. Example:

{
    "status": "IN_PROCESS",
    "createdDate": "2020.11.09 21:13:12",
    "lastUpdateDate": "2020.11.09 21:13:12",
    "totalRecords": 3,
    "percentComplete": 50.0,
    "statusId": 1,
    "statusUrl": "/admin/api/importer/status/1",
    "details": []
}

If the import has completed, you would see something like this:

{
    "status": "COMPLETED",
    "createdDate": "2020.11.09 21:33:27",
    "lastUpdateDate": "2020.11.09 21:33:28",
    "totalRecords": 3,
    "percentComplete": 100.0,
    "statusId": 2,
    "statusUrl": "/admin/api/importer/status/2",
    "details": []
}

If there were errors, those come as apart of the details array inside the returned JSON:

{
    "totalRecords": 0,
    "details": [
        {
            "type": "status",
            "description": "error"
        },
        {
            "type": "message",
            "description": "Error in the uploaded file"
        },
        {
            "type": "headerValidation",
            "description": "[]"
        },
        {
            "type": "recordValidation",
            "description": "[{\"fieldName\":\"Product Title\",\"fieldValue\":\"\",\"rowNumber\":1,\"message\":\"Missing Required Data\"}]"
        }
    ]
}

Example Request

  • Import 3 products into the -2 catalog and the -3 site as the user -2:

    curl -k -X POST --user testadmin:admin -H "Accept: application/json" -H "Content-Type: text/csv" -d \
'SKU Number,SKU Indicator,Product Title,Product Description,Product Description(SPANISH),Default Category Id,Product URL,Retail Price,UPC,Available Quantity,ProductAttribute[Color]\
2011,,ProductB2011,ProductB2011 is awesome!!!,¡ ProductB2011 es increíble!,2007,/mens/ProductB2011,3.99,2822011,300,Red\
2012,,ProductB2012,ProductB2012 is awesome!!!,¡ ProductB2012 es increíble!,2007,/mens/ProductB2012,3.99,2822012,300,Blue\
2013,,ProductB2013,ProductB2013 is awesome!!!,¡ ProductB2013 es increíble!,2007,/mens/ProductB2013,3.99,2822013,300,Black' \
"https://test.localhost:8444/admin/api/importer/PRODUCT?importSpecification=DefaultProductImportSpecification&catalogId=-2&siteId=-3&userId=-2&fileType=CSV"

API Security

Security in the admin can be done a number of ways with Spring Security. The easiest implementation of this is to use HTTP Basic security
and the existing blAdminAuthenticationProvider. In order to enable this, we recommend creating a new API Admin User that
has all the same roles and permissions as the global super user. This serves 2 purposes:

  1. Ensures that your API user can performa all operations and will not be blocked by the admin security services
  2. Allows you to track changes that were performed by this separate admin user, for instance if you are importing into a sandbox

To ensure the /api/** paths use a different security mechanism, add an additional WebSecurityConfigurerAdapter:

// Explicit order to appear before any unordered security configs
@Order(1)
@Configuration
public class AdminApiSecurityConfiguration extends WebSecurityConfigurerAdapter {

    @Resource(name = "blAdminUserDetailsService")
    protected UserDetailsService adminUserDetailsService;

    @Resource(name = "blAdminPasswordEncoder")
    protected PasswordEncoder passwordEncoder;

    @Resource(name = "blAdminAuthenticationProvider")
    protected AuthenticationProvider authenticationProvider;

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(adminUserDetailsService).passwordEncoder(passwordEncoder);
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // @formatter:off
        http
            .authenticationProvider(authenticationProvider)
            .antMatcher("/api/**")
            .authorizeRequests()
                .antMatchers("/**")
                .access("isAuthenticated()")
                .and()
            // HTTP Basic credentials
            .httpBasic()
                .and()
            .csrf().disable()
            .sessionManagement()
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .sessionFixation()
                .none()
                .enableSessionUrlRewriting(false);
        // @formatter:on
    }

}

Since this uses the same AuthenticationProvider as the regular AdminSecurityConfig for the rest of the application, you can use credentials of any admin user (like the special API admin user you created earlier). Alternatively, you can use a completely separate UserDetailsService and underlying AuthenticationProvider to separate these users.