Productfeed mapping (ALPHA) - Heyloyalty/api GitHub Wiki

Productfeed mapping

All endpoints can receive the unauthorized response:

Status: 401 Unauthorized

{
  "message": "Unauthorized",
  "code": 401
}

Get productfeed mapping

Lists productfeed mapping from a productfeed id.

GET /integrations/productfeed-mapping/{id}

Response

No mapping

status: 200 OK

{
  "customFields": []
}

Status: 200 OK

{
  "id": 6,
  "product_feed_id": 8,
  "feed_type": "xml",
  "search_field": "item",
  "strip_tags": 1,
  "encode_url_fields": 0,
  "productId": "id",
  "name": "title",
  "url": "link",
  "originalPrice": "price",
  "salePrice": "",
  "discount": "",
  "description": "",
  "imageUrl": "",
  "currency": "",
  "categoryName": "",
  "categoryId": "",
  "brandName": "shipping/price",
  "brandId": "",
  "inStock": "availability",
  "filename": "",
  "password": "",
  "username": "",
  "mappingTypes": {
    "id": 6,
    "product_feed_id": 8,
    "productId": "string",
    "name": "string",
    "url": "string",
    "originalPrice": "string",
    "salePrice": "string",
    "discount": "string",
    "description": "string",
    "imageUrl": "string",
    "currency": "string",
    "categoryName": "string",
    "categoryId": "string",
    "brandName": "string",
    "brandId": "string",
    "inStock": "string"
  },
  "customFields": [
    {
      "id": 70,
      "name": "shippingPrice",
      "mapping": "shipping/price",
      "type": "string",
    }
  ]
}

OBS: The id (NOT mappingTypes.id) is the id to be used as the path parameter mappingId in the Update a productfeed mapping section

Create/upsert a productfeed mapping

Can be used to create/overwrite or update productfeed mappings. We recommend using the update endpoint for updating or overwriting the mapping after creation as the update functionality might be removed in the future. Edit a productfeed

POST /integrations/productfeed-mapping

Parameters

Name Description Type Required Default Allowed values Remarks
product_feed_id ID of the productfeed string x NA
feed_type Productfeed type string x NA xml, json, csv, ftp, zip
search_field Productfeed field name string x (*) NA * This field is not required if the feed_type is json
productId mapping path string x NA
name mapping path string x NA
url mapping path string ""
originalPrice mapping path string ""
salePrice mapping path string ""
discount mapping path string ""
description mapping path string ""
imageUrl mapping path string ""
currency mapping path string ""
categoryName mapping path string ""
categoryId mapping path string ""
brandName mapping path string ""
inStock mapping path string ""
filename filename for ftp/sftp or zip string ""
password password for ftp/sftp string ""
username username for ftp/sftp string ""
strip_tags Strip HTML tags boolean true "true",true,"false",false,1,"1",0,"0"
encode_url_fields URL encode IDN and URL fields boolean false "true",true,"false",false,1,"1",0,"0"
mappingTypes[{fieldName}][{type}] field type for all standard mapping fields object { "productId": "string", "name": "string", "url": "string", "originalPrice": "string", "salePrice": "string", "discount": "string", "description": "string", "imageUrl": "string", "currency": "string", "categoryName": "string", "categoryId": "string", "brandName": "string", "brandId": "string", "inStock": "string" } type = string,number,date,url

OBS: The following fields, which is returned by the Get productfeed mapping request, can be parsed along safely but will ALWAYS be ignored.

fieldName
id
mappingTypes['id']
mappingTypes['product_feed_id']

CUSTOM FIELDS:

Expect Custom field ID's to change on every update or overwrite The customFields field is not required to make a productfeed so when a field is set as required below it means it is required specifically when wanting to create custom mapping fields.

OBS: If two custom fields with the same name without an id is parsed, it will at random take one of the parsed fields and either create a new field or update an existing field with that name in the productfeed mapping. If a name is updated by an id, and the name already exists on the productfeed, only one of them will be kept, chosen at random.

Name uniqueness will always overrule id. A unique of two identical named fields will always be chosen at random.

Create new custom field:

Name Description Type Required Allowed values
customFields array x
customFields.* object x
customFields.*.name Custom field name string x
customFields.*.mapping Custom field mapping string x
customFields.*.type Custom field type string x string, number, date, url

Update existing field: Note custom fields change id after every create/update

Name Description Type Required Allowed values
customFields array x
customFields.* object x
customFields.*.id Id of existing custom field integer x
customFields.*.name Custom field name string x
customFields.*.mapping Custom field mapping string x
customFields.*.type Custom field type string x string, number, date, url

Delete existing field:

Name Description Type Required Allowed values Note
customFields array x
customFields.* object x
customFields.*.id Id of existing custom field integer x
customFields.*.deleteCustomField Delete the chosen custom field boolean x "true",true,"false",false,1,"1",0,"0" If this field is a falsy value the call becomes an update instead and will be validated as such

Partial example only showing the customFields part of the call where a create, update and delete is handled in the same call. This is valid to do:

{
"product_feed_id": 16,
.....,
"customFields": [
  {
    "name": "fieldName",
    "mapping": "fieldMapping",
    "type": "string"
  },
  {
    "id": 108,
    "name": "newFieldName",
    "mapping": "newFieldMapping",
    "type": "number" 
  },
  {
    "id": 110,
    "deleteCustomField"
  }
]
}

FTP/SFTP: If ftp is selected as feed_type it is required to send the following fields:

Name Description Type Required
username ftp/sftp username string x
password ftp/sftp password string x
filename Name of the file to get data from string x

ZIP: If zip is selected as feed_type it makes sense to send the following fields: We currently only support csv files when fetching via zip files. When using zip files the productfeed url has to end with .zip AND the csv contained inside the zip file has to be named the same as zip file.

Name Description Type Required
filename Name of the file to get data from string x

Response

Returns the id of the newly created productfeed mapping.

Status: 201 Created

{
    "id": "5"
}

Errors

Validation error

Is returned one error at a time

Status: 400 Bad Request

{
  "error": "{validation error message}"
}

Productfeed not found

Status: 404 Not Found

{
  "message": "Not Found",
  "code": 404
}

Update a productfeed mapping

Updates a productfeed mapping by providing a productfeed mapping id

PUT /integrations/productfeed-mapping/{mappingId}

Expect Custom field ID's to change on every update or overwrite

URL Parameters

Field Description
mappingId productfeed mapping id

OBS: Find the mappingId by getting the productfeed mapping via a productfeed id and using the id (NOT mappingTypes.id) value.

Parameters

The same parameters as Create productfeed applies.

Response

Status: 204 No content

The method does not return anything on success.

Errors

The same Errors as create/upsert endpoint

Delete a productfeed mapping

The mapping can only be deleted by deleting a producfeed

Update product feed data

Update products with the current mapping.

PUT /integrations/productfeed/refresh

Parameters

Name Description Required
id productfeed id x

Response

Status: 200 OK

{
  "message": "feed set to update"
}

Errors

Productfeed not found

Status: 400 Not Found

{
  "message": "unable to find the specified feed"
}