Description

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

Requirements

User's session must contain field “current_participant”.

{
  "id": "urn:authenticateit:user:email:my@gmail.com",
  "name": "usr",
  "roles": [
    "user",
    "product_line"
  ],
  "ticket": "7b758d11-a597-44ae-8ab4-dd3cf864e20f",
  "current_participant": "urn:epc:sgln:0614141.12345.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

Bulk GTINs update

Create bulk GTINs update task

POST /description-service/bulk/task

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
gtins	list	Required: Gtins (max 500 items)
actions	list	Required: Task actions

Example of actions item. Set GPC

{
    "action_key": "gpc",
    "action_value": "set",
    "action_data": {
        "gpc_brick": "10006373",
        "gpc_brick_attributes": {
            "20002876": "30008323",
            "20002877": "30010065"
        },
        "gpc_class": "77030200",
        "gpc_family": "77030000",
        "gpc_segment": "77000000"
    }
}

Example of actions item. Unset GPC

{
    "action_key": "gpc",
    "action_value": "unset"
}

Example of actions item. Set Brand

{
    "action_key": "brand",
    "action_value": "set",
    "action_data": "urn:authenticateit:brand:255d4b06-ce67-479a-bf57-5776fc1d3cce"
}

Example of actions item. Unset Brand

{
    "action_key": "brand",
    "action_value": "unset"
}

Example Request

{
    "gtins": [
        "04499988844441"
    ],
    "actions": [
        {
            "action_key": "gpc",
            "action_value": "set",
            "action_data": {
                "gpc_brick": "10006373",
                "gpc_brick_attributes": {
                    "20002876": "30008323",
                    "20002877": "30010065"
                },
                "gpc_class": "77030200",
                "gpc_family": "77030000",
                "gpc_segment": "77000000"
            }
        },
        {
            "action_key": "brand",
            "action_value": "unset"
        }
    ]
}

Example Response

{
    "id": "urn:authenticateit:bulk_update_task:228f7aef-d769-4a9a-91ff-1d79451ea637",
    "status": "pending"
}

Read bulk GTINs update task

GET /description-service/bulk/task

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
id	string	Required: Task id

Example Response

{
    "actions": [
        {
            "action_key": "brand",
            "action_value": "unset",
            "id": "8d68f041-0d4e-4a40-adc9-dd1e2dd696a7"
        },
        {
            "action_data": {
                "gpc_brick": "10006373",
                "gpc_brick_attributes": {
                    "20002877": "30010065"
                },
                "gpc_class": "77030200",
                "gpc_family": "77030000",
                "gpc_segment": "77000000"
            },
            "action_key": "gpc",
            "action_value": "set",
            "id": "32fc89a7-9db4-4a36-8bda-1902ba4f3944"
        }
    ],
    "created_ts": "2022-11-17T04:43:21Z",
    "end_ts": "2022-11-17T04:43:25Z",
    "gtins": [
        "04499988844441"
    ],
    "id": "urn:authenticateit:bulk_update_task:228f7aef-d769-4a9a-91ff-1d79451ea637",
    "participant_id": "urn:authenticateit:participant:708023102856412",
    "result": [
        {
            "errors": [
                {
                    "error": "not_owner",
                    "error_text": "Participant must be system or GTIN owner.",
                    "type": "global"
                }
            ],
            "gtin": "04499988844441",
            "status": "failure"
        }
    ],
    "start_ts": "2022-11-17T04:43:25Z",
    "status": "failure",
    "user_id": "urn:authenticateit:user:email:system@authenticateit.com"
}

Read bulk GTINs update list of tasks

GET /description-service/bulk/tasks

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
status	string	Status filter
action	string	Action filter
offset	string	Offset
limit	string	Limit

status can be a value from list pending,success,failure,part_success
action can be a value from list gpc,brand

Example Response

{
    "count": 3,
    "data": [
        {
            "actions": "gpc,brand",
            "created_ts": "2022-11-17T01:28:54Z",
            "id": "urn:authenticateit:bulk_update_task:1efe6669-2731-42cf-bd4c-2af4df46f361",
            "participant_id": "urn:authenticateit:participant:708023102856412",
            "status": "part_success",
            "user_id": "urn:authenticateit:user:email:system@authenticateit.com"
        },
        {
            "actions": "gpc,brand",
            "created_ts": "2022-11-17T01:29:07Z",
            "id": "urn:authenticateit:bulk_update_task:b70c2a4c-e60e-4b3e-8d21-d6db607085ae",
            "participant_id": "urn:authenticateit:participant:708023102856412",
            "status": "success",
            "user_id": "urn:authenticateit:user:email:system@authenticateit.com"
        },
        {
            "actions": "brand,gpc",
            "created_ts": "2022-11-17T03:24:06Z",
            "id": "urn:authenticateit:bulk_update_task:68372f41-ccfa-4e1b-bcb6-fe7b29aefdb6",
            "participant_id": "urn:authenticateit:participant:708023102856412",
            "status": "failure",
            "user_id": "urn:authenticateit:user:email:system@authenticateit.com"
        }
    ]
}

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": []
}

SETs composition add/update/remove

POST /description-service/sets/composition/add

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
list	string	Required: List of set descriptions

Example Request

{
  "list": [
    {
      "id": "0000000001021",
      "composition": [
        {
          "id": "09330000000931",
          "quantity": 2
        },
        {
          "id": "00000000000260",
          "sku":"OptionalSku",
          "quantity": 1
        }
      ]
    },
    {
      "id": "00000000000932",
      "composition": []
    }
  ]
}

Example Response

[
    {
        "composition": [
            {
                "id": "09330000000931",
                "quantity": 2
            },
            {
                "id": "00000000000260",
                "quantity": 1,
                "sku": "OptionalSku"
            }
        ],
        "id": "00000000001021"
    },
    {
        "composition": [],
        "id": "00000000000932"
    }
]

SETs composition read

POST /description-service/sets/composition/get

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
list	string	Required: List of set descriptions

Example Request

{
  "list": ["0000000001021", "00000000000932"]
}

Example Response

[
    {
        "composition": [
            {
                "id": "09330000000931",
                "quantity": 2
            },
            {
                "id": "00000000000260",
                "quantity": 1,
                "sku": "OptionalSku"
            }
        ],
        "id": "00000000001021"
    },
    {
        "composition": [],
        "id": "00000000000932"
    }
]

Update SKU value

PUT /description-service/description/sku

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
gtin	string	Required: GTIN
sku		Required: SKU value
issuer	string	Required: Source issuer

sku should be presented as null - remove item or should be in string or list of string

Example Request

{
  "gtin": "03616301290599",
  "sku": "99350055769",
  "issuer": "urn:authenticateit:participant:399530525345285"
}

Example Request

{
  "gtin": "03616301290599",
  "sku": null,
  "issuer": "urn:authenticateit:participant:399530525345285"
}

Example Request

{
  "gtin": "03616301290599",
  "sku": ["test1", "test2"],
  "issuer": "urn:authenticateit:participant:399530525345285"
}

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
          },
          "no_rewards": true
        }
      ]
    },
    {
      "conditions": {
        "language": "ru",
        "country": [
          "046",
          "054"
        ]
      },
      "data": [
        {
          "text": {
            "title": "Second title",
            "text": "Bla-bla-bla."
          },
          "no_rewards": false
        },
        {
          "link": {
            "text": "Brand web site",
            "url": "http://www.koalabi.com.au"
          },
          "no_rewards": true
        }
      ]
    }
  ]
}

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": [
    {
      "conditions": {
        "language": [
          "en"
        ],
        "country": [
          "036"
        ]
      },
      "data": [
        {
          "image": [
            {
              "url": "https://dev-cdn.shping.com/2019/7/25/0ef00b6f-6a78-4d0b-af9a-728efe5203c3",
              "private": true,
              "origin": null
            }
          ],
          "private": false
        },
        {
          "text": {
            "title": "Brand",
            "text": "irvine",
            "markdown": false
          },
          "private": false,
          "no_rewards": true
        }
      ],
      "id": "urn:authenticateit:participant:111111111111111",
      "type": "imported_retailer"
    },
    {
      "conditions": {},
      "data": [
        {
          "image": [
            {
              "url": "https://dev-cdn.shping.com/2019/7/25/0ef00b6f-6a78-4d0b-af9a-728efe5203c3",
              "private": false
            }
          ],
          "private": false,
          "no_rewards": false
        }
      ],
      "id": "urn:authenticateit:participant:111111111111111",
      "type": "imported_retailer"
    },
    {
      "conditions": {
        "language": [
          "en"
        ],
        "country": [
          "036"
        ]
      },
      "data": [
        {
          "image": [
            {
              "url": "https://dev-cdn.shping.com/2022/8/9/1d502afa-4053-43a9-8be2-bf1313fb1e23.JPG",
              "private": false,
              "origin": "self_uploaded"
            },
            {
              "url": "https://dev-cdn.shping.com/2022/8/9/9e3cbc9e-0f0c-49f1-9c37-7c90b3c1292a.jpeg",
              "private": true,
              "origin": "gs1"
            }
          ],
          "private": false
        },
        {
          "text": {
            "title": "Text widget title",
            "text": "Text widget body",
            "markdown": false,
            "sub_type": "instruction"
          },
          "private": false
        }
      ],
      "id": "urn:authenticateit:participant:708023102856412",
      "type": "brand"
    }
  ],
  "id": "00000021765926"
}

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,
          "no_rewards": true
        },
        {
          "text": {
            "title": "Title without type 1",
            "text": "Text without type 1",
            "markdown": false
          },
          "private": false,
          "no_rewards": true
        },
        {
          "text": {
            "title": "Title with type 1",
            "text": "Text wit type 1",
            "sub_type": "instruction",
            "markdown": false
          },
          "private": false,
          "no_rewards": true
        },
        {
          "text": {
            "title": "Title with type 2",
            "text": "Text wit type 2",
            "sub_type": "warning",
            "markdown": false
          },
          "private": false,
          "no_rewards": true
        },
        {
          "text": {
            "title": "Title with type 3",
            "text": "Text wit type 3",
            "sub_type": "company_name",
            "markdown": false
          },
          "private": false,
          "no_rewards": true
        },
        {
          "made_in": {
            "country": "036"
          },
          "private": false,
          "no_rewards": true
        }
      ],
      "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
gs1_import	boolean	GS1 file flag
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_header — true 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_header — true 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:

Text widget with title "Product Identifier" and text taken from the gtin_col column of the CSV file.
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.
Header widget with text "Additional Header". No CSV columns are used for this widget.
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.
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"
]

Apply `change_retailer` action by moderator

PUT /description-service/receipts/status

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_id	string	Required: Receipt id
user_id	string	Required: User Id
retailer_id	string	Required: Retailer Id

Method can be applied only for receipts with status COMPLETED/UNRECOGNIZED/INIT (if country excluded from OCR)

Example Request

{
    "receipt_id": "ccd9b055-30b4-4a28-b154-a1b662561346",
    "retailer_id": "costco",
    "user_id": "urn:authenticateit:user:email:shping:9cf92a52-e708-4d45-a7f5-53ed475c1c3c"
}

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
pending_gtin	string	Pending gtin filter value (up to 14 symbols)
receipt_uploaded_ts_from	string	Uploaded timestamp filter value from
receipt_uploaded_ts_to	string	Uploaded timestamp filter value to
moderated_at_from	string	Moderated at filter value from
moderated_at_to	string	Moderated at filter value to
receipt_code	string	Receipt code filter value
receipt_id	string	Receipt id filter value
moderator_id	string	Moderator id filter value
user_id	string	User id filter value
user_first_name	string	User first_name filter value
user_last_name	string	User last_name filter value
moderator_first_name	string	Moderator first_name filter value
moderator_last_name	string	Moderator last_name filter value
moderator_last_name	string	Moderator last_name filter value
limit	pos_integer	Limit
offset	non_neg_integer	Offset
receipt_ts_from	datetime	Receipt Ts filter value
receipt_ts_to	datetime	Receipt Ts filter value
status	string or null	Status filter `MONITOR`/`NEW`/`PENDING`/`REMOVED`/`SUCCESS`/`REJECTED`/`APPROVED`/null
contributor_doc	string	Contribution id filter value
contributor_doc_exist	string	Contribution has been attached (`true`/`false`/`null`)
contributor_doc_locked_by	string	Contribution Moderator id filter value
contributor_moderator_first_name	string	Contribution Moderator first name filter value
contributor_moderator_last_name	string	ContributionModerator last name filter value
contributor_doc_status	string	Status filter `approved`/`closed`/`deleted`/`unreviewed`
order_by	string	One of table field
order_type	string	`asc` or `desc`

Order fields: receipt_uploaded_ts, receipt_id, receipt_ts, status, analyzed_receipt_id, hash, id, name, receipt_store, ts, auto_matched, user_id, user_first_name, user_last_name, moderated_at, moderator_id, moderator_first_name, moderator_last_name, receipt_uploaded_ts, receipt_code contributor_doc_locked_by, contributor_doc, contributor_doc_status, pending_gtin

Example Request

{
    "limit": 30,
    "offset": 0,
    "order_by": "receipt_uploaded_ts",
    "status": "SUCCESS",
    "name": "test",
    "moderated_at_from": "2022-08-21T01:34:51.873105170Z",
    "moderated_at_to": "2022-08-24T01:34:51.873105170Z",
    "receipt_id": "2b2b6e46-9bb2-4c3c-b77a-610d6f24a7ab",
    "user_first_name": "usr",
    "user_last_name": "surname",
    "moderator_first_name": "system",
    "moderator_last_name": "admin",
    "receipt_ts_from": "2022-08-10T00:00:00Z",
    "receipt_ts_to": "2022-08-12T00:00:00Z",
    "user_id": "urn:authenticateit:user:email:mail@gmail.com",
    "moderator_id": "urn:authenticateit:user:email:system@authenticateit.com",
    "receipt_code": "111-111",
    "receipt_store": "Coles",
    "receipt_uploaded_ts_from": "2022-08-22T01:27:00.725Z",
    "receipt_uploaded_ts_to": "2022-08-24T01:27:00.725Z",
    "pending_gtin": "00028400099868"
}

Example Response

{
    "count": 3,
    "data": [
        {
          "analyzed_receipt_id": "urn:authenticateit:user:email:shping:ad8a25fb-f695-49dc-82fa-f80c5f33c2d9@analyzed_receipts@def193b8-cb0b-4c80-9353-822ba7de4815",
          "auto_matched": 0,
          "contributor_doc": null,
          "contributor_moderator_first_name": null,
          "contributor_moderator_id": null,
          "contributor_moderator_last_name": null,
          "contributor_status": null,
          "hash": "d323d048524d6cf683ba8262c79bcf4d9b403d67",
          "id": "urn:authenticateit:receipt_product_gtin_mapping:01fc9310-65f1-4b4d-b5f2-174b811a5f10",
          "moderated_at": null,
          "moderator_first_name": null,
          "moderator_id": null,
          "moderator_last_name": null,
          "monitor_ts": "2022-11-25T06:20:48.386576949Z",
          "monitored_first_name": "System1",
          "monitored_last_name": "Administrator1",
          "monitored_user_id": "urn:authenticateit:user:email:system@authenticateit.com",
          "name": "S / REPUBLIC B / PURIFY CHARC MASK '",
          "pending_gtin": null,
          "receipt_code": "26052945CW0682312169814432610081362021",
          "receipt_id": "def193b8-cb0b-4c80-9353-822ba7de4815",
          "receipt_store": "chemistwarehouse",
          "receipt_ts": "2021-06-13T14:14:00Z",
          "receipt_uploaded_ts": "2022-11-24T05:44:35.658Z",
          "status": "monitor",
          "ts": "2022-11-25T05:00:00Z",
          "user_first_name": "TestForWeb",
          "user_id": "urn:authenticateit:user:email:shping:ad8a25fb-f695-49dc-82fa-f80c5f33c2d9",
          "user_last_name": ""
        },
        {
            "analyzed_receipt_id": "urn:authenticateit:user:email:shping:9cf92a52-e708-4d45-a7f5-53ed475c1c3c@analyzed_receipts@354838af-f785-47f4-bfe6-036f1c1e7127",
            "auto_matched": 0,
            "contributor_doc": "urn:authenticateit:contributor_doc:668505757085139",
            "contributor_moderator_first_name": "System1",
            "contributor_moderator_id":  "urn:authenticateit:user:email:system@authenticateit.com",
            "contributor_moderator_last_name": "Administrator1",
            "contributor_status": "closed",
            "hash": "737e6211f7c1885731daabed5a2128120e7b572b",
            "id": "urn:authenticateit:receipt_product_gtin_mapping:a019957e-5b04-4bb8-acc0-aa8ba911abe8",
            "moderated_at": "2022-10-19T07:12:53.353368991Z",
            "moderator_first_name": "System1",
            "moderator_id": "urn:authenticateit:user:email:system@authenticateit.com",
            "moderator_last_name": "Administrator1",
            "monitor_ts": null,
            "monitored_first_name": null,
            "monitored_last_name": null,
            "name": "BASIN ROUND 10LITRE",
            "pending_gtin": "08889888898891",
            "receipt_code": "11210227774122950900",
            "receipt_id": "354838af-f785-47f4-bfe6-036f1c1e7127",
            "receipt_store": "coles",
            "receipt_ts": "2022-10-12T20:49:00Z",
            "receipt_uploaded_ts": "2022-10-17T22:20:40.123Z",
            "status": "SUCCESS",
            "ts": "2022-10-19T07:15:00Z",
            "user_first_name": "First 5",
            "user_id": "urn:authenticateit:user:email:shping:9cf92a52-e708-4d45-a7f5-53ed475c1c3c",
            "user_last_name": "Last 5"
        },
        {
            "analyzed_receipt_id": "urn:authenticateit:user:email:shping:9cf92a52-e708-4d45-a7f5-53ed475c1c3c@analyzed_receipts@354838af-f785-47f4-bfe6-036f1c1e7127",
            "auto_matched": 0,
            "contributor_doc": "urn:authenticateit:contributor_doc:668505757085139",
            "contributor_moderator_first_name": "System1",
            "contributor_moderator_id":  "urn:authenticateit:user:email:system@authenticateit.com",
            "contributor_moderator_last_name": "Administrator1",
            "contributor_status": "closed",
            "hash": "80c1f53899a23304f2508fc196fe66235a18d06b",
            "id": "urn:authenticateit:receipt_product_gtin_mapping:a1871c8a-cb43-4111-b5da-60ac15976d9d",
            "moderated_at": "2022-10-19T07:12:47.060829151Z",
            "moderator_first_name": "System1",
            "moderator_id": "urn:authenticateit:user:email:system@authenticateit.com",
            "moderator_last_name": "Administrator1",
            "monitor_ts": null,
            "monitored_first_name": null,
            "monitored_last_name": null,
            "name": "VIVA PAPR TOWL SELEC 3PACK",
            "pending_gtin": "08889888898891",
            "receipt_code": "11210227774122950900",
            "receipt_id": "354838af-f785-47f4-bfe6-036f1c1e7127",
            "receipt_store": "coles",
            "receipt_ts": "2022-10-12T20:49:00Z",
            "receipt_uploaded_ts": "2022-10-17T22:20:40.123Z",
            "status": "SUCCESS",
            "ts": "2022-10-19T07:15:00Z",
            "user_first_name": "First 5",
            "user_id": "urn:authenticateit:user:email:shping:9cf92a52-e708-4d45-a7f5-53ed475c1c3c",
            "user_last_name": "Last 5"
        }
    ]
}

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/:status

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
id	string	Required: Name identifier
gtin	string	Required: Valid gtin
status	string	Required: `confirm`/`reject` /`monitor`
store_id	string	Optional store_id value (applicable for `confirm`)

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

Receipt mapping management

Methods allowed only for system nominated users

Get current mapping product name to gtin

POST /description-service/receipts/mapping/get

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_store	string	Required: Receipt store
name	string	Product name
hash	string	Product name hash

name or hash value is Required

Example Request

{
  "receipt_store":"COLES",
  "hash":"ea7939ba8267c85c02b40974aed9ecc265229af9"
}

Example Request

{
  "receipt_store":"COLES",
  "name": "TOSTITOS 175G ANY 2 FOR $ 6",
}

Example Response

{
  "gtin": "00000000070980",
  "hash": "ea7939ba8267c85c02b40974aed9ecc265229af9",
  "id": "urn:authenticateit:receipt_product_gtin_mapping:rt:coles@ea7939ba8267c85c02b40974aed9ecc265229af9",
  "name": "TOSTITOS 175G ANY 2 FOR $ 6",
  "receipt_store": "coles",
  "receipt_store_alias": "coles",
  "ts": "2022-08-11T04:17:49Z"
}

Set new/update mapping product name to gtin

POST /description-service/receipts/mapping/set

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_store	string	Required: Receipt store
name	string	Required: Product name
hash	string	Product name hash
gtin	string	Required: Valid GTIN
store_id	string	Optional store_id value

Example Request

{
  "receipt_store": "coles",
  "name": "TOSTITOS",
  "gtin": "00000000070980"
}

Example Response

{
  "gtin": "00000000070980",
  "hash": "59835b48ba73ee330613dac20c164db979bac07a",
  "id": "urn:authenticateit:receipt_product_gtin_mapping:rt:coles@59835b48ba73ee330613dac20c164db979bac07a",
  "name": "TOSTITOS",
  "receipt_store": "coles",
  "receipt_store_alias": "coles",
  "ts": "2022-08-11T05:54:17Z"
}

Delete mapping product name to gtin

POST /description-service/receipts/mapping/delete

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_store	string	Required: Receipt store
name	string	Product name
hash	string	Product name hash

name or hash value is Required

Example Request

{
  "receipt_store": "coles",
  "name": "TOSTITOS"
}

Receipt rewards processing

Get receipt data by receipt_id

GET /description-service/receipts

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_id	string	Required: Receipt Id

Example Response

{
    "chunk_id": "urn:authenticateit:user:email:mail@gmail.com@receipts",
    "receipt": {
        "accuracy": "37,35312928972",
        "client_ip": "10.0.0.5",
        "country": "036",
        "gross_total_amount": 2.22,
        "hash": "e9d26bc648e9ab39fdc75836afbf43bfe79dd944",
        "issued_at": "2019-10-25T00:00:00Z",
        "latitude": "-37837790",
        "location_name": "aldi store",
        "longitude": "144975284",
        "notes": "My receipt",
        "ocr_done": true,
        "ocr_status": "success",
        "postcode": null,
        "receipt": [
            "https://dev-cdn.shping.com/2022/1/28/7dede4f1-5e5d-45eb-b676-ec9714b329b5"
        ],
        "receipt_code": "n1",
        "receipt_id": "0221971a-5535-4cad-b301-85198f466894",
        "retailer": "aldi",
        "retailer_id": "coles",
        "status": 4,
        "store_id": "697",
        "tax": 1.11,
        "total": 999909,
        "ts": "2022-01-28T01:13:01.378Z",
        "updated_at": "2022-01-28T02:29:40Z"
    }
}

Edit unrecognized receipt by receipt_id

Should be usable only for receipts with action=SET_RETAILERS

POST /description-service/receipts/retailer

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_id	string	Required: Receipt Id
location_name	string	Required: Location name
issued_at	string	Datetime
store_id	string	Store Id
tax	pos_number	Tax value
gross_total_amount	pos_number	Gross total amount value
notes	string	Some noted

Example Request

{
  "receipt_id": "0221971a-5535-4cad-b301-85198f466894",
  "location_name": "aldi store",
  "store_id": "123123",
  "tax": 1.11,
  "gross_total_amount": 2.22,
  "notes": "My receipt",
  "issued_at": "2021-12-12T01:01:01Z"
}

Apply action to the receipt

PUT /description-service/receipts

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_id	string	Required: Receipt id
action	string	`hide` / `change_retailer`
retailer_id	string	Retailer Id

If action=change_retailer then retailer_id value is required
action=change_retailer could be applied only for receipts with status COMPLETED/UNRECOGNIZED/INIT (if country excluded from OCR)
action=hide could be applied only for receipts with status COMPLETED/UNRECOGNIZED/INIT (if country excluded from OCR)

Example Request

{
    "receipt_id": "ccd9b055-30b4-4a28-b154-a1b662561346",
    "retailer_id": "costco",
    "action": "change_retailer"
}

Get analyzed receipt data by receipt_id

GET /description-service/receipts/analyzed

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_id	string	Required: Receipt id

Example Response

{
    "analyzed_receipt": {
        "accuracy_rate": 0.7300000190734863,
        "data": {
            "expanded_prices": [
                {
                    "coins": "420000000000000000",
                    "coins_earned": true,
                    "coins_earned_ts": "2022-02-24T03:11:20Z",
                    "gtin": "00000090693564",
                    "hash": "f3444c5b185759fb036522a2b810d7e599bd463d",
                    "id": "66728820-e781-4a81-a7d0-1ad0082c0d0c",
                    "image": "https://dev-cdn.shping.com/2021/12/6/4dbcd657-0be8-4f23-81e7-b07efdbbe2d5",
                    "name": "COLES LITE MILK 2LITRE",
                    "owner": "urn:authenticateit:participant:111111111111115",
                    "partner_brand": false,
                    "product_id": "00000090693564",
                    "product_name": "Lemon Juice",
                    "status": "success",
                    "value": "2.39"
                },
                {
                    "gtin": null,
                    "hash": "d2d5393bb71106522ccac194e7e78704aa6b39bc",
                    "id": "c522d951-0e8b-42c4-b289-a882d40bdb25",
                    "name": "* FREEDOM MUESLI 500 G 900GRAM vf1f1tv820 @ $3.10 EACH1331",
                    "owner": null,
                    "partner_brand": null,
                    "value": "6.20"
                },
                {
                    "gtin": null,
                    "hash": "4005e88cf73754decec472b4de7abd0403dff558",
                    "id": "99d87e84-b538-4583-a070-906fb644dd3c",
                    "name": "* VEGEMITÉ CHEESYBITE11 270GRAM 17",
                    "owner": null,
                    "partner_brand": null,
                    "value": "3.50"
                },
                {
                    "coins": "420000000000000000",
                    "coins_earned": true,
                    "coins_earned_ts": "2022-02-24T03:11:20Z",
                    "gtin": "00000000000352",
                    "hash": "8d9d763128e8d3296d9b590d99db1563221c8794",
                    "id": "c7a12781-7bee-4d50-aaf9-62eab2ed7f9d",
                    "image": "https://dev-cdn.shping.com/2021/10/28/6d87997b-52ec-4ff4-9f0d-9aeeea920c70",
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 77 @ $3.10 EACH 16",
                    "owner": "urn:authenticateit:participant:657635220994783",
                    "partner_brand": false,
                    "product_id": "00000000000352",
                    "product_name": "Heilige Feuer",
                    "status": "success",
                    "value": "1.00"
                },
                {
                    "coins": "420000000000000000",
                    "coins_earned": true,
                    "coins_earned_ts": "2022-02-24T03:11:20Z",
                    "gtin": "00000000000000",
                    "hash": "1c6791425bab8f4f5349dbce644d920073822c3a",
                    "id": "dc353bcc-82fb-45f8-b5b3-3659c7731b08",
                    "image": "https://cdn.shping.com/2018/1/28/a759926f-0826-4d90-9d62-61aa4d202d56.png",
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 88 @ $3.10 EACH 16",
                    "owner": "urn:authenticateit:participant:399530525345285",
                    "partner_brand": false,
                    "product_id": "00000000000000",
                    "product_name": "Champion Fresh Seal Smooth Blue Duo Pouch 40g X 5 X 30",
                    "status": "success",
                    "value": "12.00"
                }
            ],
            "links": [
                "https://cdn.shping.com/2019/10/25/0770b942-9c81-45ed-8909-6ebb52ca935e"
            ],
            "prices": [
                {
                    "name": "COLES LITE MILK 2LITRE",
                    "value": "2.39"
                },
                {
                    "name": "* FREEDOM MUESLI 500 G 900GRAM vf1f1tv820 @ $3.10 EACH1331",
                    "value": "6.20"
                },
                {
                    "name": "* VEGEMITÉ CHEESYBITE11 270GRAM 17",
                    "value": "3.50"
                },
                {
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 77 @ $3.10 EACH 16",
                    "value": "1.00"
                },
                {
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 88 @ $3.10 EACH 16",
                    "value": "12.00"
                }
            ],
            "store": "coles",
            "total": "9999.09",
            "ts": "2021-07-13T05:45:23.266Z"
        },
        "id": "urn:authenticateit:user:email:mail@gmail.com@analyzed_receipts@207e73f5-177d-4e15-a716-65c92c9f8208",
        "ocr_hash": "e3e2581e80566b3cd7052c56f900f6de97c40570",
        "receipt_date": "25/10/2019",
        "receipt_id": "207e73f5-177d-4e15-a716-65c92c9f8208",
        "receipt_number": "n1",
        "receipt_time": "Date:",
        "retailer": "coles",
        "retailer_store_id": "697",
        "status": "completed",
        "tax": 11.22,
        "ts": "2022-02-24T03:10:40Z",
        "user_id": "urn:authenticateit:user:email:mail@gmail.com",
        "words_count": 146
    },
    "chunk_id": "urn:authenticateit:user:email:mail@gmail.com@receipts",
    "non_partner_brand_product_coins": "420000000000000000",
    "non_partner_brand_product_coins_earned": "126480000000000000000",
    "partner_brand_product_coins": "42160000000000000000",
    "partner_brand_product_coins_earned": 0,
    "pending_coins": "420000000000000000",
    "receipt": {
        "accuracy": "35",
        "client_ip": "165.228.214.94",
        "country": "036",
        "hash": "e3e2581e80566b3cd7052c56f900f6de97c40570",
        "issued_at": "2019-10-25T00:00:00Z",
        "latitude": "-37837681",
        "location_name": "B&V Café",
        "longitude": "144975408",
        "ocr_done": true,
        "ocr_status": "success",
        "postcode": null,
        "receipt": [
            "https://dev-cdn.shping.com/2022/2/24/53ac2ae3-9d5d-4d01-9e4a-2ad802a7b66d"
        ],
        "receipt_code": "n1",
        "receipt_id": "207e73f5-177d-4e15-a716-65c92c9f8208",
        "retailer_id": "coles",
        "status": 4,
        "store_id": "697",
        "tax": 11.22,
        "total": 999909,
        "ts": "2022-02-24T03:08:32.492Z",
        "updated_at": "2022-02-24T03:10:40Z"
    },
    "limits": {
        "has_limit_coins": true,
        "from_ts": "2022-04-25T14:00:00Z",
        "limit_coins": "1000000000000000000",
        "sum_coins": 0,
        "to_ts": "2022-04-26T13:59:59Z"
    },
    "write_off_coins": "1000000000000000000"
}

Coupling gtins to unmatched items by receipt_id

PUT /description-service/receipts/analyzed

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
receipt_id	string	Required: Receipt id
list	list	Required: Data list

list.id - id of elemet with the name
list.scan_id - preview scan_id
list.contributor_doc - contributor doc
list.remove - remove flag (true)

Example Request

{
  "receipt_id": "ef3cb92b-1692-4fa8-878d-6dcd97d57d00",
  "list": [
    {
      "scan_id": "3c4b5cd1-db98-426c-bd19-2b31148140db",
      "contributor_doc": "urn:authenticateit:contributor_doc:624265320442018",
      "id": "d2095809-0591-4d80-b750-eef998913e8d"
    },
    {
      "remove": true,
      "id": "be5b8ee0-d706-4637-bec4-7c6077be4e77"
    }
  ]
}

Example Response

{
    "analyzed_receipt": {
        "accuracy_rate": 0.7300000190734863,
        "data": {
            "expanded_prices": [
                {
                    "coins": "440000000000000000",
                    "coins_earned": true,
                    "coins_earned_ts": "2022-01-18T12:05:00Z",
                    "gtin": "00000090693564",
                    "hash": "f3444c5b185759fb036522a2b810d7e599bd463d",
                    "id": "1c0a25e9-38de-4023-b8bb-3364d130a75f",
                    "image": "https://dev-cdn.shping.com/2021/12/6/4dbcd657-0be8-4f23-81e7-b07efdbbe2d5",
                    "name": "COLES LITE MILK 2LITRE",
                    "owner": "urn:authenticateit:participant:111111111111115",
                    "partner_brand": false,
                    "product_id": "00000090693564",
                    "product_name": "Lemon Juice",
                    "status": "success",
                    "value": "2.39"
                },
                {
                    "gtin": null,
                    "hash": "d2d5393bb71106522ccac194e7e78704aa6b39bc",
                    "id": "be5b8ee0-d706-4637-bec4-7c6077be4e77",
                    "name": "* FREEDOM MUESLI 500 G 900GRAM vf1f1tv820 @ $3.10 EACH1331",
                    "owner": null,
                    "partner_brand": null,
                    "status": "removed",
                    "value": "6.20"
                },
                {
                    "coins": "440000000000000000",
                    "coins_earned": true,
                    "coins_earned_ts": "2022-01-18T12:05:00Z",
                    "gtin": "09351568000034",
                    "hash": "a5e9b587cf8efbd9fc15ecc3a088b3043f90f80c",
                    "id": "abfab52d-2b1c-4d5b-9f26-cad73f00867a",
                    "image": "https://cdn.shping.com/2019/2/22/72a68208-c71a-45a3-a2ba-e670a2cf031c.jpg",
                    "name": "* VEGEMITÉ CHEESYBITE 270GRAM 17",
                    "owner": "urn:authenticateit:participant:1",
                    "partner_brand": false,
                    "product_id": "09351568000034",
                    "product_name": "SkinB5 Acne Control Moisturiser 50ml",
                    "status": "success",
                    "value": "3.50"
                },
                {
                    "gtin": null,
                    "hash": "8d9d763128e8d3296d9b590d99db1563221c8794",
                    "id": "1030bb52-9458-486c-ac93-88962dd16d42",
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 77 @ $3.10 EACH 16",
                    "owner": null,
                    "partner_brand": null,
                    "value": "1.00"
                },
                {
                    "gtin": "09352417000427",
                    "hash": "1c6791425bab8f4f5349dbce644d920073822c3a",
                    "id": "d2095809-0591-4d80-b750-eef998913e8d",
                    "image": "https://dev-cdn.shping.com/2019/5/25/eed94de9-d019-4396-9c51-3d5af298180e",
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 88 @ $3.10 EACH 16",
                    "owner": "urn:authenticateit:participant:1",
                    "partner_brand": false,
                    "product_name": "Lifestyles Condoms Ultra Thin",
                    "status": "pending",
                    "value": "12.00"
                }
            ],
            "links": [
                "https://cdn.shping.com/2019/10/25/0770b942-9c81-45ed-8909-6ebb52ca935e"
            ],
            "prices": [
                {
                    "name": "COLES LITE MILK 2LITRE",
                    "value": "2.39"
                },
                {
                    "name": "* FREEDOM MUESLI 500 G 900GRAM f110120 @ $3.10 EACH1331",
                    "value": "6.20"
                },
                {
                    "name": "* VEGEMITÉ CHEESYBITE 270GRAM 17",
                    "value": "3.50"
                },
                {
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 77 @ $3.10 EACH 16",
                    "value": "1.00"
                },
                {
                    "name": "* FREEDOM MUESLI 500 G 500GRAM 88 @ $3.10 EACH 16",
                    "value": "12.00"
                }
            ],
            "store": "coles",
            "total": "9999.09",
            "ts": "2021-07-13T05:45:23.266Z"
        },
        "id": "urn:authenticateit:user:email:mail@gmail.com@analyzed_receipts@ef3cb92b-1692-4fa8-878d-6dcd97d57d00",
        "ocr_hash": "b0e21ec105ad48183e72231e81ec9314c0a0e946",
        "receipt_date": "25/10/2019",
        "receipt_id": "ef3cb92b-1692-4fa8-878d-6dcd97d57d00",
        "receipt_number": "n1",
        "receipt_time": "Date:",
        "retailer": "coles",
        "retailer_store_id": "697",
        "status": "completed",
        "ts": "2022-01-18T12:03:40Z",
        "user_id": "urn:authenticateit:user:email:mail@gmail.com",
        "words_count": 146
    },
    "chunk_id": "urn:authenticateit:user:email:mail@gmail.com@receipts",
    "non_partner_brand_product_coins": "440000000000000000",
    "non_partner_brand_product_coins_earned": "88260000000000000000",
    "partner_brand_product_coins": "44130000000000000000",
    "partner_brand_product_coins_earned": 0,
    "pending_coins": "1000000000000000000",
    "receipt": {
        "accuracy": "21,5763965700274",
        "client_ip": "10.0.0.5",
        "country": "036",
        "hash": "b0e21ec105ad48183e72231e81ec9314c0a0e946",
        "issued_at": "2019-10-25T00:00:00Z",
        "latitude": "56853798",
        "location_name": "Обувь",
        "longitude": "53298409",
        "ocr_done": true,
        "ocr_status": "success",
        "postcode": null,
        "receipt": [
            "https://dev-cdn.shping.com/2022/1/18/9597a69a-3a41-4f70-aaf4-25e5c25374d3"
        ],
        "receipt_code": "n1",
        "receipt_id": "ef3cb92b-1692-4fa8-878d-6dcd97d57d00",
        "retailer_id": "coles",
        "status": 5,
        "store_id": "697",
        "total": 999909,
        "ts": "2022-01-18T12:01:47.804Z",
        "updated_at": "2022-01-18T12:03:40Z"
    },
    "limits": {
        "from_ts": "2022-04-25T14:00:00Z",
        "limit_coins": "1000000000000000000",
        "sum_coins": 0,
        "to_ts": "2022-04-26T13:59:59Z"
    }
}

Description

Requirements

GTIN

Bulk GTINs update

Create bulk GTINs update task

Parameters

Example of actions item. Set GPC

Example of actions item. Unset GPC

Example of actions item. Set Brand

Example of actions item. Unset Brand

Example Request

Example Response

Read bulk GTINs update task

Parameters

Example Response

Read bulk GTINs update list of tasks

Parameters

Example Response

Create New Trade Item

Parameters

Example Request

Example Response

Delete Trade Item

Parameters

Update Trade Item

Parameters

Example Request

Example Response

SETs composition add/update/remove

Parameters

Example Request

Example Response

SETs composition read

Parameters

Example Request

Example Response

Update SKU value

Parameters

Example Request

Example Request

Example Request

Attach GDTIs

Parameters

Example Request

Example Response

Detach GDTIs

Parameters

Example Request

Example Response

Sources

Create new or update existing source in document

Parameters

Example Request - add new source

Example Request - remove self sources

Example Request. For system participant only. Set sources with id and type.

Set made_in widget and text widgets with sub_type option

Outdated. Removes source

Parameters

Read gtin document

Parameters

Example Response

GS1 File parser

Parsing csv file

Parameters

Example Request - Parse GS1 file

Example Request - Parse file from expert

Example Response

Read current parsing status

Parameters

Example Response

Import GTINs

Preview Import

Parameters

Example Request

Example Response

Start Import Task

Parameters

Example Request

Example Response

Read Import Task Status

Apply `change_retailer` action by moderator