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": "usr",
  "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

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"
}
Set made_in widget and text widgets with sub_type option

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

{
  "sources": [
    {
      "conditions": {},
      "data": [
        {
          "text": {
            "title": "Title without type",
            "text": "Text without type",
            "markdown": false
          },
          "private": false,
          "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_headertrue if first line of the file is a header with field names. The parameter is optional, true by default.
  • num_lines — limit number of data lines to include in the preview. The parameter is optional, 10 by default.

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

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

Start Import Task

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

Import task is described by the following parameters:

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

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

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

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

The possible actions for the action field are the following:

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

Consider the following example of the widgets templates:

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

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

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

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

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

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

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

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

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

Read Import Task Status

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

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

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

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

Read Status of All Import Tasks

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

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

Export GTINs

Start Export Task

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

Export task is described by the following parameters:

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

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

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

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

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

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

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

Read Export Task Status

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

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

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

Read Status of All Export Tasks

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

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

Mapping receipts product names to GTINs

All methods are available only for system.

Get receipt_store filter values

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

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

results matching ""

    No results matching ""