Description

The “description-service” provides methods for creation, update and delete sources in GTIN document.

Requirements

  1. User's session must contain field “current_participant”.
{
  "id": "urn:authenticateit:user:email:my@gmail.com",
  "name": "ivan",
  "roles": [
    "user",
    "product_line"
  ],
  "ticket": "7b758d11-a597-44ae-8ab4-dd3cf864e20f",
  "current_participant": "urn:epc:sgln:0614141.12345.1"
}
  1. This participant must be presented in doc_storage with list of company prefixes
{
  "_id": "urn:epc:sgln:0614141.12345.1",
  "type": "participant",
  "company_prefix": [
    "0614141"
  ]
}

GTIN

Create New Trade Item

Takes JSON object containing GTIN and name of the trade item. Company prefix in GTIN must agree with company prefixes of participant. Newly created GTIN initially do not have any information sources.

POST /description-service/gtins
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Trade item identifier, GTIN
name string Trade item name
gpc_brick string Trade item attribute
gpc_class string Trade item attribute
gpc_family string Trade item attribute
gpc_segment string Trade item attribute
gpc_brick_attributes object Object with brick attributes and values
Example Request
{
  "id": "00000026013992",
  "name": "ZippityElfBrand T",
  "brand_id": "ZippityElfBrand",
  "gpc_brick":"10000188",
  "gpc_brick_attributes": {"20000239": "30002960"}
}
Example Response
{
    "brand_id": "ZippityElfBrand",
    "gpc_brick": "10000188",
    "gpc_brick_attributes": {
        "20000239": "30002960"
    },
    "gpc_class": "50132000",
    "gpc_family": "50130000",
    "gpc_segment": "50000000",
    "id": "00000026013992",
    "name": "ZippityElfBrand T",
    "owner": "urn:authenticateit:participant:841535075581481",
    "sources": []
}

Delete Trade Item

Delete trade item and all it's information sources. Current participant must be GTIN owner.

DELETE /description-service/gtins/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Trade item identifier, GTIN

Update Trade Item

Only name of the trade item could be changed. There is separate API endpoint to change trade item's information sources.

PUT /gtins/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Trade item identifier, GTIN
name string New trade item name
gpc_brick string Trade item attribute
gpc_class string Trade item attribute
gpc_family string Trade item attribute
gpc_segment string Trade item attribute
gpc_brick_attributes list List with brick attributes
Example Request
{
  "name": "ZippityElfBrand E",
  "brand_id": "ZippityElfBrand",
  "gpc_segment":"50000000",
  "gpc_brick_attributes": {"20000239": "30002960"}
}
Example Response
{
  "brand_id": "ZippityElfBrand",
  "gpc_brick":null,
  "gpc_brick_attributes":null,
  "gpc_class":null,
  "gpc_family":null,
  "gpc_segment":"50000000"
  "id": "00000026013992",
  "name": "ZippityElfBrand E",
  "owner": "urn:authenticateit:participant:841535075581481",
  "sources": []
}

Attach GDTIs

Link trade idem to existing GDTI documents. Request body must have attachments list of document identifiers. Responds with updated attachments list of the trade item.

Sources from attached documents are expanded after all product sources, in the same order as in the attachments list. Positions to expand the attachments may be overriden with attachment_positions in the request body. The positions is a JSON object mapping attachment GDTIs to positive integer positions (or to null for positions to be removed) in the scan widgets list (see example request below).

Besides GDTIs attached to the product itself, there may be brand attachments, product owner global attachments and system global attachments. They are expanded in this order (product attachments, brand attachments, product owner global attachments, system global attachments), unless explicit positions are defined.

POST /description-service/gtins/:id/attachments/add
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Trade item identifier, GTIN
Example Request
{
  "attachments": [
    "urn:epc:id:gdti:9212345.00001.008113943527211"
  ],
  "attachment_positions": {
    "urn:epc:id:gdti:9212345.00001.008113943527211": 1
  }
}
Example Response
[
  "urn:epc:id:gdti:9212345.00001.008113943527211"
]

Detach GDTIs

Unlink trade idem from GDTI documents. Request body must have attachments list of document identifiers to be detached. Responds with updated attachments list of the trade item. Positions for detached GDTIs will also be removed.

Attachment positions may be removed with this API, by providing attachment_positions. The actual positions provided in the mapping are ignored, all positions for GDTIs from the attachment_positions will be removed.

POST /description-service/gtins/:id/attachments/remove
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Trade item identifier, GTIN
Example Request
{
  "attachments": [
    "urn:epc:id:gdti:9212345.00001.008113943527211"
  ]
}
Example Response
[]

Sources

Create new or update existing source in document

That request create new or update existing source in document Participant must has actived product360. If module product360 isn't active - participant can create only text, image and nutrition_info widgets.

POST /description-service/description
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string base gtin
sources array::object list of sources - MUST contain objects with two tags “conditions” and “data”
conditions object::object MAY contain objects with two tags “language” and “country”
language array::string/string list of elements or one element
country array::string/string list of elements or one element
data array:object object with widgets
Example Request - add new source
{
  "id": "0978099679130451",
  "sources": [
    {
      "conditions": {
        "language": [
          "fr",
          "ru"
        ]
      },
      "data": [
        {
          "text": {
            "title": "Main prod",
            "text": "Some textww",
            "lines": 10
          }
        }
      ]
    },
    {
      "conditions": {
        "language": "ru",
        "country": [
          "046",
          "054"
        ]
      },
      "data": [
        {
          "text": {
            "title": "Second title",
            "text": "Bla-bla-bla."
          }
        },
        {
          "link": {
            "text": "Brand web site",
            "url": "http://www.koalabi.com.au"
          }
        }
      ]
    }
  ]
}
Example Request - remove self sources
{
  "id": "0978099679130451",
  "sources": []
}
Example Request. For system participant only. Set sources with id and type.

If system participant will update the sources of gtin, all of the sources from doc will be deleted and new sources with set id and type will be set. If source will not have id and type fields, then type="gs1" and id=ParticipantId will be set as default

{
  "sources": [
    {
      "type": "brand",
      "id": "urn:authenticateit:participant:1",
      "conditions": {},
      "data": [
        {
          "text": {
            "title": "Company name",
            "text": "contributor Doal,solventes",
            "markdown": false
          }
        },
        {
          "image": [
            {
              "url": "https://cdn.shping.com/2018/2/17/bfd87b20-cdd4-4bad-829b-135d9ea44bbd"
            }
          ]
        }
      ]
    }
  ],
  "id": "00000000000000"
}
Set made_in widget and text widgets with sub_type option

Country parameter in made_in widget should be contain a country code. sub_type option into text is optional and should contain one of possible values from text_widget_types dictionary (settings-service)

{
  "sources": [
    {
      "conditions": {},
      "data": [
        {
          "text": {
            "title": "Title without type",
            "text": "Text without type",
            "markdown": false
          },
          "private": false
        },
        {
          "text": {
            "title": "Title without type 1",
            "text": "Text without type 1",
            "markdown": false
          },
          "private": false
        },
        {
          "text": {
            "title": "Title with type 1",
            "text": "Text wit type 1",
            "sub_type": "instruction",
            "markdown": false
          },
          "private": false
        },
        {
          "text": {
            "title": "Title with type 2",
            "text": "Text wit type 2",
            "sub_type": "warning",
            "markdown": false
          },
          "private": false
        },
        {
          "text": {
            "title": "Title with type 3",
            "text": "Text wit type 3",
            "sub_type": "company_name",
            "markdown": false
          },
          "private": false
        },
        {
          "made_in": {
            "country": "036"
          },
          "private": false
        }
      ],
      "id": "urn:authenticateit:participant:735879621218609",
      "type": "brand"
    }
  ],
  "id": "00498765432233"
}

Outdated. Removes source

That request removes source with requested “conditions”

POST /description-service/description/delete
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string base gtin
conditions object::object MUST contain objects with two tags “language” and “country”
language array::string/string list of elements or one element
country array:string/string list of elements or one element

Read gtin document

That request return the GTIN document by ID

GET /description-service/description
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string base gtin
Example Response
{
  "id": "19780996791304",
  "name": "Test product",
  "owner": "urn:epc:sgln:0614141.12345.1",
  "sources": [
    {
      "conditions": {
        "language": "ru"
      },
      "data": [
        {
          "text": {
            "text": "Bla-bla-bla.",
            "title": "Second title"
          }
        },
        {
          "link": {
            "text": "Brand website",
            "url": "http://www.koalabi.com.au"
          }
        }
      ],
      "id": "urn:authenticateit:user:email:my@gmail.com",
      "type": "contrubutor"
    },
    {
      "conditions": {
        "country": "036"
      },
      "data": [
        {
          "text": {
            "lines": 10,
            "text": "Some text",
            "title": "Main prod"
          }
        }
      ],
      "id": "urn:authenticateit:user:email:my@gmail.com",
      "type": "contrubutor"
    }
  ],
  "type": "gtin"
}

GS1 File parser

Parsing csv file

Convert CSV file to GTIN document with sources and other attributes

POST /description-service/parse/file
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
link aws link “dev-test-cdn.shping.com.s3-ap-southeast-2.amazonaws.com/2017/2/20/test1.csv”
delimiter delimiter “\t”
fields map of fields which are converted to text widgets {“Brand”:{“title”:“Will be converted to title of text widget”, “position”:1},GST_Reported_Date”:“Дата”}
name fields which are converted to gtin name [“Brand”]
gtin_field GTIN field in file “GTIN”
brand Optional brand field which are converted to brand document “Brand”
conditions widget conditions {“language”:“en”, “country”:[“036”, “044”]}
additional_widgets list of additional widgets
gpc_segment_field gpc_segment field in file “GPC_Segment”
gpc_family_field gpc_family field in file “GPC_Family”
gpc_class_field gpc_class field in file “GPC_Class”
gpc_brick_field gpc_brick field in file “GPC_Brick”
Example Request - Parse GS1 file
{
  "link": "https://dev-cdn.shping.com/2018/6/28/de044f80-6ad6-41d3-84a7-d23f88fa6d98.txt",
  "gpc_brick_field":"GPC_Brick",
  "replace_included_conditions": true,
  "delimiter": "\t",
  "gtin_field": "GTIN",
  "fields": {
    "Brand": {
      "title": "Brand",
      "position": 1
    },
    "Functional_Name": {
      "title": "Product Type",
      "position": 2
    },
    "Company_Name": {
      "title": "Company Name",
      "position": 3
    },
    "GTIN": {
      "action": "to_country",
      "title": "Country of Barcode Registration",
      "position": 4
    }
  },
  "name": [
    "Trade_Item_Description"
  ],
  "conditions": {
    "language": "en",
    "country": [
      "036",
      "554"
    ]
  }
}
{
  "link": "https://dev-cdn.shping.com/2018/6/26/edfd3aa4-ed7a-4b45-bbd0-395317c60fff.txt",
  "gpc_segment_field":"GTIN_gpc_segment_field",
  "gpc_family_field":"GTIN_gpc_family_field",
  "gpc_class_field":"GTIN_gpc_class_field",
  "gpc_brick_field":"GTIN_gpc_brick_field",
  "replace_included_conditions": true,
  "delimiter": "\t",
  "gtin_field": "GTIN",
  "fields": {
    "Brand": {
      "title": "Brand",
      "position": 1
    },
    "Functional_Name": {
      "title": "Product Type",
      "position": 2
    },
    "Company_Name": {
      "title": "Company Name",
      "position": 3
    },
    "GTIN": {
      "action": "to_country",
      "title": "Country of Barcode Registration",
      "position": 4
    }
  },
  "name": [
    "Trade_Item_Description"
  ],
  "conditions": {
    "language": "en",
    "country": [
      "036",
      "554"
    ]
  }
}
Example Request - Parse file from expert
{
  "link": "dev-cdn.shping.com.s3.amazonaws.com/2017/6/19/e47a98c0-bf8f-40e1-a5bb-a387e08d747e-Updated_ACO GTIN List 23_03_17 (1) (4).txt",
  "delimiter": "\t",
  "gtin_field": "gtin",
  "fields": {
    "title": {
      "title": "Title",
      "position": 2
    },
    "DESCRIPTION": {
      "title": "Description",
      "position": 3
    },
    "Size": {
      "title": "Size",
      "position": 6
    },
    "Source": {
      "title": "Source",
      "position": 7
    },
    "Certificate": {
      "title": "Certificate",
      "position": 8
    }
  },
  "name": [
    "title"
  ],
  "conditions": {
    "language": "en",
    "country": "036"
  },
  "additional_widgets": [
    {
      "position": 4,
      "widgets": [
        {
          "certificates": {
            "title": "Certificates",
            "list": [
              {
                "img_url": "http://dev-cdn.shping.com.s3.amazonaws.com/2017/6/20/95e287e3-490d-4c4b-bc2e-15295c2b64bd-Australian-Certified-Organic.png",
                "gdti": "urn:epc:id:gdti:9212345.00002.009114953628221",
                "expired": false
              }
            ]
          }
        }
      ]
    },
    {
      "position": 5,
      "widgets": [
        {
          "video": {
            "title": "Video",
            "url": "http://dev-cdn.shping.com.s3.amazonaws.com/2017/6/19/bad421e2-64bb-4565-a0a4-a1c7e64caecb-aco.mp4",
            "preview": "http://dev-cdn.shping.com.s3.amazonaws.com/2017/6/19/ffb555c2-56fb-4283-90d5-dba970c2e0e7-img.png"
          }
        }
      ]
    }
  ]
}
Example Response
"Task in progress"

Read current parsing status

GET /description-service/parse/status
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
  "message": "success",
  "status": "done",
  "ts": "2017-02-20T21:02:49Z"
}

Import GTINs

Preview Import

Parses CSV file with GTIN description and provides a preview of the initial entries in the file. Accepts JSON object with preview description, which consists of the following parameters:

  • link — URL of uploaded CSV file.
  • delimiter — character used in the CSV file to separate line fields (,, \t, ; or |).
  • has_headertrue if first line of the file is a header with field names. The parameter is optional, true by default.
  • num_lines — limit number of data lines to include in the preview. The parameter is optional, 10 by default.

Responds with JSON object containing header (field names from the file header, or generated field names ("1", "2", "3", …) if file has no header) and rows (list of parsed data rows).

POST /description-service/import/preview
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "link": "https://dev-cdn.shping.com/2017/11/22/f6ba5d7f-5be2-4a7a-94e6-194cbeefdc26.csv",
  "delimiter": ",",
  "num_lines": 3,
  "has_header": true
}
Example Response
{
  "header": [
    "Company Name",
    "Company Prefix",
    "GTIN Number",
    "Brand Name",
    "Product Name",
    "Target Market Country",
    "Classification Category Code (GPC Code)",
    "Image URL"
  ],
  "rows": [
    [
      "VANCE CHEMICALS PTE LTD",
      "888500035",
      "8885000350025",
      "MR MCKENIC",
      "9-IN-1 TECHNOLOGY OIL",
      "Singapore",
      "10005267",
      "#N/A"
    ],
    [
      "VANCE CHEMICALS PTE LTD",
      "888500035",
      "8885000350049",
      "MR MCKENIC",
      "CONTACT CLEANER AND LUBRICANT",
      "Singapore",
      "10005356",
      "#N/A"
    ],
    [
      "VANCE CHEMICALS PTE LTD",
      "888500035",
      "8885000350100",
      "MR MCKENIC",
      "LITHIUM GREASE",
      "Singapore",
      "10000405",
      "#N/A"
    ]
  ],
  "records": [
    {
      "Brand Name": "MR MCKENIC",
      "Classification Category Code (GPC Code)": "10005267",
      "Company Name": "VANCE CHEMICALS PTE LTD",
      "Company Prefix": "888500035",
      "GTIN Number": "8885000350025",
      "Image URL": "#N/A",
      "Product Name": "9-IN-1 TECHNOLOGY OIL",
      "Target Market Country": "Singapore"
    },
    {
      "Brand Name": "MR MCKENIC",
      "Classification Category Code (GPC Code)": "10005356",
      "Company Name": "VANCE CHEMICALS PTE LTD",
      "Company Prefix": "888500035",
      "GTIN Number": "8885000350049",
      "Image URL": "#N/A",
      "Product Name": "CONTACT CLEANER AND LUBRICANT",
      "Target Market Country": "Singapore"
    },
    {
      "Brand Name": "MR MCKENIC",
      "Classification Category Code (GPC Code)": "10000405",
      "Company Name": "VANCE CHEMICALS PTE LTD",
      "Company Prefix": "888500035",
      "GTIN Number": "8885000350100",
      "Image URL": "#N/A",
      "Product Name": "LITHIUM GREASE",
      "Target Market Country": "Singapore"
    }
  ]
}

Start Import Task

Import GTIN description with sources and other attributes from a CSV file. Accepts JSON object with import task description and starts a background import task.

Import task is described by the following parameters:

  • link — URL of uploaded CSV file.
  • delimiter — character used in the CSV file to separate line fields (,, \t, ; or |).
  • has_headertrue if first line of the file is a header with field names. The parameter is optional, true by default.
  • widgets — list of widget templates for the imported products. See description below.
  • name — list of field names which will be converted to GTIN name.
  • brand — field name of the brand name in the file. Brand documents will be created for these brand names. The parameter is optional.
  • conditions — widget conditions for sources in GTINs.
  • gtin_field — field name in the file containing the actual GTIN number.
  • gpc_segment_field, gpc_family_field, gpc_class_field, gpc_brick_field — fields names of the GPC fields in the file. These parameters are optional.
  • fields — maps field names of the file to text widgets in the GTIN. E.g., {"Brand":{"title":"Will be converted to title of text widget","position":1},"GST_Reported_Date":"Date"}. See additional description below. The parameter is superseded by widgets.
  • additional_widgets — list of additional widgets. The parameter is superseded by widgets.

Parameter widgets is a list of widget templates for the resulting products. It allows to specify mapping of CSV columns to widget attributes, and to specify additional widgets in the required order. The widgets parameter should be used instead of fields and additional_widgets parameters.

Each entry in the widgets list is a widget description with some attributes replaced with CSV mapping specification (see Widgets and Sections for details on widget description). Mapping specification is a JSON object with column (name of a CSV column to get value from) and optional action fields. If a widget couldn't be created with the values from the CSV record, it will be missing from the resulting list of product widgets. The following subset of all widgets may be used in widgets templates:

  • certificates — attributes title, img_url and gdti may be filled from CSV columns.
  • components — no CSV mapping.
  • email — no CSV mapping.
  • follow_fb — no CSV mapping.
  • gdti — attribute gdti may be filled from CSV column.
  • header — no CSV mapping.
  • health_star — no CSV mapping.
  • image — attribute url may be filled from CSV column.
  • link — attributes text, image and url may be filled from CSV columns.
  • nutrition_info — no CSV mapping.
  • phone — no CSV mapping.
  • popup — no CSV mapping.
  • social_networks — attributes icon and url may be filled from CSV columns.
  • text — attributes title and text may be filled from CSV columns.
  • title — no CSV mapping.
  • video — attributes title, url and preview may be filled from CSV columns.

The possible actions for the action field are the following:

  • to_country — convert GTIN code to name of a country, which corresponds to the GS1 prefix of the GTIN.
  • copy_to_cdn — copy file from the specified URL, and replace the URL with a new CDN URL. Should be used for image and video files only.

Consider the following example of the widgets templates:

[
  {
    "text": {
      "title": "Product Identifier",
      "text": {
        "column": "gtin_col"
      }
    }
  },
  {
    "text": {
      "title": "Product Country",
      "text": {
        "column": "gtin_col",
        "action": "to_country"
      }
    }
  },
  {
    "header": {
      "text": "Additional Header"
    }
  },
  {
    "social_networks": [
      {
        "icon": {
          "column": "sn_icon"
        },
        "url": {
          "column": "sn_url"
        }
      }
    ]
  },
  {
    "image": [
      {
        "url": {
          "column": "img1_col"
        }
      },
      {
        "url": {
          "column": "img2_col",
          "action": "copy_to_cdn"
        }
      }
    ]
  }
]

The imported product will have the following list of widgets in it's source, in that order:

  1. Text widget with title "Product Identifier" and text taken from the gtin_col column of the CSV file.
  2. Text widget with title "Product Country". The text will be country name for the GTIN code from the gtin_col column of the CSV file.
  3. Header widget with text "Additional Header". No CSV columns are used for this widget.
  4. Social networks widget with a single link. Value of the sn_icon CSV column will be used for the social network icon. Column sn_url will be used for the URL.
  5. Image widget with two image URLs. Value of the img1_col CSV column will be used as the URL of the first image. File from the URL in img2_col CSV column will be copied to CDN, and the CDN URL will be used for the second image in the widget.

Sources in the GTINs will have source type determined from participant type. Current participant will be source owner in the GTINs.

Responds with JSON representation of initial task status. The response also contains id of the import task.

The JSON object fields maps field names from the CSV file to widget description (this parameter is deprecated, widgets should be used instead). Widget description may contain position field. Created widgets will be sorted in GTIN source by their specified position. Widget description may contain an action to be performed on the widget.

A field from the file may be mapped to a text widget. For this title must be specified in widget description. Field content will be used as text in the created widget.

A field from the file may be mapped to an image widget. For this to happen there must be entry widget with value image in the widget description. Field value will be used as image URL. There may be copy_to_cdn action in image widget description. In this case image will be copied from the URL to Shping CDN and URL will be replaced with the actual URL in the CDN. Otherwise the original URL will be used in the image widget.

POST /description-service/import/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "link": "https://dev-cdn.shping.com/2018/6/28/de044f80-6ad6-41d3-84a7-d23f88fa6d98.txt",
  "gpc_brick_field": "GPC_Brick",
  "replace_included_conditions": true,
  "delimiter": "\t",
  "gtin_field": "GTIN",
  "widgets": [
    {
      "title": "Brand",
      "text": {
        "column": "Brand"
      }
    },
    {
      "title": "Product Type",
      "text": {
        "column": "Functional_Name"
      }
    },
    {
      "title": "Company Name",
      "text": {
        "column": "Company_Name"
      }
    },
    {
      "title": "Country of Barcode Registration",
      "text": {
        "column": "GTIN",
        "action": "to_country"
      }
    }
  ],
  "name": [
    "Trade_Item_Description"
  ],
  "conditions": {
    "language": "en",
    "country": [
      "036"
    ]
  }
}
Example Response
{
  "id": "087d6a14-e393-4d39-a6fe-050bfbb56a07",
  "status": "started",
  "ts": "2018-10-01T14:37:56Z"
}

Read Import Task Status

API to read status of import task. Status for finished tasks will be kept for at least 12 hours after the completion. Responds with JSON representation of import task status.

Status contains total number of lines in the file in total_lines field and number of already processed lines in processed_lines field. Status also contains has_header value (true if there was a header row in the CSV file for the import).

Status may contain bad_lines (line numbers of syntactically incorrect lines), bad_gtins (GTIN errors for invalid GTINs (invalid check digit, line with null GTIN, etc.)) and bad_prefixes (GTIN errors for GTINs with incompatible company prefixes) lists. GTIN error is a JSON object containing line (line number in the CSV file) and gtin (GTIN code extracted from the CSV line).

GET /description-service/import/tasks/{id}
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Task identifier.
Example Response
{
  "limits": {
    "current": "undefined",
    "max": "undefined"
  },
  "bad_lines": [
    197,
    82
  ],
  "bad_gtins": [
    {
      "gtin": "09342336037849",
      "line": 196
    },
    {
      "gtin": null,
      "line": 115
    }
  ],
  "message": "success",
  "id": "087d6a14-e393-4d39-a6fe-050bfbb56a07",
  "status": "done",
  "processed_lines": 5982,
  "total_lines": 12690,
  "has_header": true,
  "ts": "2018-10-01T18:21:48Z"
}

Read Status of All Import Tasks

API to read status of all current participant's import tasks. Responds with JSON object containing tasks list. Each list entry is status of a single task (see API to read single task status for description).

GET /description-service/import/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
  "tasks": [
    {
      "limits": {
        "current": "undefined",
        "max": "undefined"
      },
      "bad_lines": [
        197,
        82
      ],
      "bad_gtins": [
        {
          "gtin": "09342336037849",
          "line": 196
        },
        {
          "gtin": null,
          "line": 115
        }
      ],
      "message": "success",
      "id": "087d6a14-e393-4d39-a6fe-050bfbb56a07",
      "status": "done",
      "processed_lines": 5982,
      "total_lines": 12690,
      "has_header": true,
      "ts": "2018-10-01T18:21:48Z"
    }
  ]
}

Export GTINs

Start Export Task

Export information for participant's products to a a CSV file. Accepts JSON object with export task description and starts a background export task.

Export task is described by the following parameters:

  • delimiter — character used in the CSV file to separate line fields (,, \t, ; or |). The parameter is optional, , by default.
  • has_header — if true first line of the CSV file will be a header line with field names. The parameter is optional, true by default.
  • widgets — list of widgets to fields mapping specification for the exported products. See description on widgets in Start Import Task for details. The parameter is optional, it's empty list of widgets by default.
  • conditions — only sources matching these conditions will be considered for export. The parameter is optional, widgets from all sources are exported by default.
  • gtin_field — field name in the file CSV to contain the actual GTIN number.
  • brand_field — field name to contain product's brand name. The parameter is optional.
  • name_field — field name to contain product name. The parameter is optional.
  • gpc_segment_field, gpc_family_field, gpc_class_field, gpc_brick_field — fields names of the GPC fields in the file. These parameters are optional.
  • query, op — RSQL query to select exported products from participant's GTIN table. These parameters are optional, all participant GTINs are exported by default.

Product's GTIN number, brand, name and GPC fields are exported to the fields specified in the export task description (gtin_field, brand_field, etc.).

Information from the product widgets is exported in accordance to the specification in widgets as follows.

Product widgets list is prepared by contatenating widgets from product sources matching specified conditions. For each widget specification from the widgets list, product widgets list is scanned. The first product widget matching the widget specfication is selected for properties extraction. The process repeats for the next specification from the widgets.

For details on widget fields to CSV columns mapping see description on widgets in Start Import Task.

Responds with JSON representation of initial task status. The response also contains id of the export task.

POST /description-service/export/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "gtin_field": "GTIN",
  "brand_field": "BrandId",
  "name_field": "Name",
  "conditions": {
    "language": "en",
    "country": [
      "036"
    ]
  },
  "widgets": [
    {
      "social_networks": [
        {
          "icon": {
            "column": "SocialNetwork1Icon"
          },
          "url": {
            "column": "SocialNetwork1URL"
          }
        }
      ]
    },
    {
      "gdti": {
        "gdti": {
          "column": "FirstGDTI"
        }
      }
    }
  ],
  "query": "id==08383451029304"
}
Example Response
{
  "brand_field": "BrandId",
  "columns": [
    "GTIN",
    "BrandId",
    "Name",
    "SocialNetwork1Icon",
    "SocialNetwork1URL",
    "FirstGDTI"
  ],
  "conditions": {
    "language": "en",
    "country": [
      "036"
    ]
  },
  "count": 1,
  "created": "2020-02-09T21:20:14Z",
  "delimiter": ",",
  "end_time": null,
  "gtin_field": "GTIN",
  "has_header": true,
  "id": "b034ee8b-a146-4935-a744-b718fdf5b4d8",
  "name_field": "Name",
  "op": "AND",
  "owner": "urn:authenticateit:participant:708023102856412",
  "progress": 0,
  "query": "id==08383451029304",
  "start_time": null,
  "status": null,
  "table": "index_schema_table_gtin_fb21b728-7881-4182-acd3-81ca7542bea4"
}

Read Export Task Status

API to read status of an export task. Status for finished tasks will be kept for at least 12 hours after the completion. Responds with JSON representation of export task status.

Status contains total number of products selected for the export in the count field and number of already exported products in progress field.

GET /description-service/export/tasks/{id}
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Task identifier.
Example Response
{
  "brand_field": "BrandId",
  "columns": [
    "GTIN",
    "BrandId",
    "Name",
    "SocialNetwork1Icon",
    "SocialNetwork1URL",
    "FirstGDTI"
  ],
  "conditions": {
    "language": "en",
    "country": [
      "036"
    ]
  },
  "count": 1,
  "created": "2020-02-09T21:20:14Z",
  "delimiter": ",",
  "end_time": "2020-02-09T21:20:14Z",
  "gtin_field": "GTIN",
  "has_header": true,
  "id": "b034ee8b-a146-4935-a744-b718fdf5b4d8",
  "link": "https://dev-cdn.shping.com/2020/2/9/f4e25c65f51e3fb0bae306665223dc136c513713100888427bd746db7f045b96.csv",
  "name_field": "Name",
  "op": "AND",
  "owner": "urn:authenticateit:participant:708023102856412",
  "progress": 1,
  "query": "id==08383451029304",
  "start_time": "2020-02-09T21:20:14Z",
  "status": "done",
  "table": "index_schema_table_gtin_fb21b728-7881-4182-acd3-81ca7542bea4"
}

Read Status of All Export Tasks

API to read status of all current participant's export tasks. Responds with JSON object containing tasks list. Each list entry is status of a single task (see API to read single task status for description).

GET /description-service/export/tasks
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
{
  "tasks": [
    {
      "brand_field": "BrandId",
      "columns": [
        "GTIN",
        "BrandId",
        "Name",
        "SocialNetwork1Icon",
        "SocialNetwork1URL",
        "FirstGDTI"
      ],
      "conditions": {
        "language": "en",
        "country": [
          "036"
        ]
      },
      "count": 1,
      "created": "2020-02-09T21:20:14Z",
      "delimiter": ",",
      "end_time": "2020-02-09T21:20:14Z",
      "gtin_field": "GTIN",
      "has_header": true,
      "id": "b034ee8b-a146-4935-a744-b718fdf5b4d8",
      "link": "https://dev-cdn.shping.com/2020/2/9/f4e25c65f51e3fb0bae306665223dc136c513713100888427bd746db7f045b96.csv",
      "name_field": "Name",
      "op": "AND",
      "owner": "urn:authenticateit:participant:708023102856412",
      "progress": 1,
      "query": "id==08383451029304",
      "start_time": "2020-02-09T21:20:14Z",
      "status": "done",
      "table": "index_schema_table_gtin_fb21b728-7881-4182-acd3-81ca7542bea4"
    }
  ]
}

Mapping receipts product names to GTINs

All methods are available only for system.

Get receipt_store filter values

GET /description-service/receipts/stores
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Response
[
    "Coles",
    "IGA",
    "Woolworths",
    "ALDI"
]

Get receipts names

POST /description-service/receipts/names
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
receipt_store list receipt_store filter values
name string Name filter value
limit pos_integer Limit
offset non_neg_integer Offset
order_by string One of table field
order_type string asc or desc

Order table fields:
analyzed_receipt_id,hash,id,name,receipt_store,ts

Example Request
{
  "limit": 3,
  "offset": 0,
  "receipt_store": ["Coles", "Woolworths"],
  "name": "at"
}
Example Response
{
    "count": 3,
    "data": [
        {
            "analyzed_receipt_id": "urn:authenticateit:user:email:ikleeen@gmail.com@analyzed_receipts@f1c3cb3f-7d5b-4df9-87a7-9f637200fb92",
            "hash": "bf1623ddffd0753f29784afe641dda2f467df86a",
            "id": "urn:authenticateit:receipt_product_gtin_mapping:bf1623ddffd0753f29784afe641dda2f467df86a",
            "name": "RED WASHED POTATOES 2KG",
            "receipt_store": "Coles",
            "ts": "2019-06-11T12:40:00Z"
        },
        {
            "analyzed_receipt_id": "urn:authenticateit:user:email:ikleeen@gmail.com@analyzed_receipts@a13f27a8-30ca-423d-8a39-34a0d809cdb8",
            "hash": "6911c6c5eec9e4ba5098ae5bfca98a6ce25661d3",
            "id": "urn:authenticateit:receipt_product_gtin_mapping:6911c6c5eec9e4ba5098ae5bfca98a6ce25661d3",
            "name": "SAN REMO PASTA:RIGAT 500GRAM",
            "receipt_store": "Coles",
            "ts": "2019-06-11T12:40:00Z"
        },
        {
            "analyzed_receipt_id": "urn:authenticateit:user:email:ikleeen@gmail.com@analyzed_receipts@9834a803-fd25-412e-b140-b1aa70ce0e90",
            "hash": "5c7333359f70c800c5204a26ee04020f90b9825f",
            "id": "urn:authenticateit:receipt_product_gtin_mapping:5c7333359f70c800c5204a26ee04020f90b9825f",
            "name": "% LOACKER GRAN PATICCE 100GRAM",
            "receipt_store": "Coles",
            "ts": "2019-06-11T12:40:00Z"
        }
    ]
}

Get receipt images

GET /description-service/receipts/images/:analyzed_receipt_id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
analyzed_receipt_id string analyzed_receipt_id identifier
Example Response
[
    "https://dev-cdn.shping.com/2019/6/11/9834a803-fd25-412e-b140-b1aa70ce0e90.jpg"
]

Map GTIN to receipt name

PUT /description-service/receipts/names/:id/:gtin
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Required: Name identifier
gtin string Required: Valid gtin

Delete receipt name identifier

DELETE /description-service/receipts/names/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Required: Name identifier

Get user's scans by receipt_id

GET /description-service/receipts/scans/:analyzed_receipt_id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
analyzed_receipt_id string analyzed_receipt_id identifier
Example Response
{
    "from": "2019-10-24T13:00:00Z",
    "images": [
        "https://cdn.shping.com/2019/10/25/0770b942-9c81-45ed-8909-6ebb52ca935e"
    ],
    "scans": [
        {
            "product_id": "00000000000123",
            "product_name": "Davis Icing Sugar 12.5  Kilogram"
        }
    ],
    "to": "2019-10-25T12:59:59Z"
}

results matching ""

    No results matching ""