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.

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"
  ]
}
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.

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"
}

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 records (list of parsed data entries).

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"
  ],
  "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.
  • 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.
  • 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.
  • additional_widgets — list of additional widgets.

The JSON object fields maps field names from the CSV file to widget description. 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.

Consider the following example of the fields mapping:

{
  "Name": {
    "title": "Product Name",
    "position": 1
  },
  "Image": {
    "widget": "image",
    "position": 2
  },
  "Cert": {
    "widget": "image",
    "position": 3,
    "action": "copy_to_cdn"
  }
}

In this case field Name from the CSV file will be mapped to a text widget. Widget will have "Product Name" as title and field content from the file as text. Field Image in the CSV file must contain image URL. Image widget will be created, URL from the file field will be used as is. Field Cert will be mapped to an image widget, but the actual image will be copied to Shping CDN first and CDN URL will be used in the created image 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.

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",
  "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"
    ]
  }
}
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"
    }
  ]
}

results matching ""

    No results matching ""