Contributors
All contributors endpoints have path prefix /contributors-service.
Read user contributor's rating
Endpoint for contributors to read his rating
GET /contributors-service/user/rating
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
{
"contributor_levels": [
{
"accuracy": 90,
"current": true,
"current_percentages": 20,
"days_left": 31,
"descriptions": "Some text for newbie",
"full_description": "Another text for newbie",
"max_percentages": 100,
"name": "Newbie",
"coin_rate": 1,
"products": 2,
"todo_description": "todo_description for newbie",
"type": "newbie"
}
]
}
Write/Update Schema
Endpoint for supervisor of contributors to create or update “product_info_schema”. Roles required: “contributors_supervisor”
PUT /contributors-service/schema
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| schema | string | new product_info_schema |
Example Response
{
"ts": "2016-12-26T15:34:09Z",
"updated_by": "urn:authenticateit:user:email:my@gmail.com"
}
Read Schema
Endpoint for supervisor of contributors to read “product_info_schema”. Roles required: “contributors_supervisor”
GET /contributors-service/schema
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
{
"contributor": {
"text_widget": {
"text": "description",
"title": [
"brand",
"-",
"product_name"
]
}
},
"updated": {
"id": "urn:authenticateit:user:email:my@gmail.com",
"ts": "2016-12-28T14:53:21Z"
},
"user": [
{
"field": "required",
"help": "Enter the company name (usually directed on the package)",
"item": "company",
"name": "Company name",
"type": "text",
"conditions": {
"language": "en"
}
},
{
"field": "required",
"help": "Enter the brand name (usually directed on the package)",
"item": "brand",
"name": "Brand name",
"type": "text",
"conditions": {
"language": "en"
}
},
{
"field": "required",
"help": "Enter the product name (usually directed on the package)",
"item": "product_name",
"name": "Product name",
"type": "text",
"conditions": {
"language": "en"
}
},
{
"field": "required",
"help": "Enter description the product",
"item": "description",
"name": "Description",
"type": "text",
"conditions": {
"language": "en"
}
},
{
"field": "required",
"help": "You can make a photo",
"item": "image",
"name": "Image",
"type": "image",
"conditions": {
"language": "en"
}
},
{
"field": "optional",
"help": "You can make a photo or provide information from package",
"item": "nutrition_info",
"name": "Nutrition information",
"type": "image",
"conditions": {
"language": "en"
}
}
]
}
Read Widgets Fields
Endpoint for users to read “product_info_schema” widgets. Roles required: “user”
GET /contributors-service/user/schema
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
{
"data": [
{
"field": "required",
"help": "Enter the company name (usually directed on the package)",
"item": "company",
"name": "Company name",
"type": "text"
},
{
"field": "required",
"help": "Enter the brand name (usually directed on the package)",
"item": "brand",
"name": "Brand name",
"type": "text"
},
{
"field": "required",
"help": "Enter the product name (usually directed on the package)",
"item": "product_name",
"name": "Product name",
"type": "text"
},
{
"field": "required",
"help": "Enter description the product",
"item": "description",
"name": "Description",
"type": "text"
},
{
"field": "required",
"help": "You can make a photo",
"item": "image",
"name": "Image",
"type": "image"
},
{
"field": "optional",
"help": "You can make a photo or provide information from package",
"item": "nutrition_info",
"name": "Nutrition information",
"type": "image"
}
]
}
Contributed Documents
Create Document
Endpoint for create new document. Initially we have to read the widgets (GET /contributor_docs/user/schema) and create the document in accordance with the scheme
POST /contributors-service/contributor_docs
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| scan_id | string | Required: Scan id |
| item_id | string | Item id |
| receipt_id | string | Receipt id |
Example Request
{
"scan_id": "112694b3-1425-48eb-9d48-9e5d55642b02",
"item_id": "6f778a93-277b-43a6-9664-c57e0f620403",
"receipt_id": "1856f9c1-18fb-46fb-88fd-35505a0afb37",
"data": {
"front_view": "https://dev-cdn.shping.com/2022/10/19/d1b14cc6-63ea-4a04-af7b-e0511e2f63f1.jpeg",
"back_view": "https://dev-cdn.shping.com/2022/10/19/d1b14cc6-63ea-4a04-af7b-e0511e2f63f1.jpeg"
}
}
Example Response
{
"id": "urn:authenticateit:contributor_doc:624265320442018"
}
Delete Document
Endpoint for contributors moderator to delete contributed document.
DELETE /contributors-service/contributor_docs/:id
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | string | Contributed document identifier |
Read contributor_doc list
Endpoint for moderators to read list of “contributor_doc”. Roles required: “contributors_moderator”
POST /contributors-service/get_docs
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| page | Page of docs - non_neg_integer | |
| limit | the number of elements on the page | |
| level | select docs with that level (0, 1, 2) | |
| lock | select only unlocked documents or documents locked by current moderator | |
| reviewer | reviewer id | |
| status | document status (unreviewed, deleted, approved, closed) | |
gtin |
string | Select only documents related to the specified GTIN (or part of GTIN) |
user_name |
string | Select only documents related to the specified user |
user_email |
string | Select only documents related to the user with the specified email |
from |
string | Datetime format. Select from date |
to |
string | Datetime format. Select to date |
country |
string | Country filter. Country code or null |
language |
string | Language filter. Language code or null |
moderator_name |
string | Moderator name filter. |
moderator_email |
string | Moderator email filter. |
order |
string | Order by ts type ("asc", "desc") |
Example Response
{
"count": 1,
"documents": [
{
"country": "643",
"id": "urn:authenticateit:contributor_doc:675263878887127",
"img": null,
"language": "ru",
"level": 0,
"lock": 0,
"locked_by": null,
"moderator_email": null,
"moderator_first_name": null,
"moderator_last_name": null,
"owner": "urn:authenticateit:user:email:email@mailinator.com",
"product_id": "06432100009210",
"reviewer": null,
"status": "unreviewed",
"ts": "2017-09-20T11:32:27Z"
}
]
}
| Fields description | ||
|---|---|---|
| id | Dociment id | urn:authenticateit:contributor_doc:860882970513377 |
| lock | Lock status | 0/null or 1 |
| locked_by | Moderator who locked the doc | null/urn:authenticateit:user:email:my@gmail.com |
| level | Reviewing level | 2 |
| product_id | Base product_id | 0123456789 |
| owner | Base document owner | urn:authenticateit:user:email:test1@gmail.com |
| reviewer | reviewer id | urn:authenticateit:user:email:my@gmail.com |
| status | document status | approved |
| ts | if document was reviewed - timestamp when document was reviewed, if document was not reviewed - timestamp when document was created | 2016-12-27T12:40:57Z |
| img | link to image |
Reviewing process
The general review process: user creates a document → moderator with level 1 read document and may locked it → after locking moderator with level 1 creates a document with status «“deleted”» or «“approved”» → moderator with level 2 read document and may locked it → after locking moderator creates a document with status «“deleted”» or «“approved”» → moderator with level 3 read document and may locked it → after locking moderator creates a document with status «“deleted”» or «“approved”» → all contributor's documents will be removed and final document converted to gtin if final status is «“approved”» or not converted if final status is «“deleted”»
Upgrade the level of сontributor's moderator
Endpoint for contributors supervisors to change trusted level of сontributor's moderator. Roles required: “contributors_supervisor”
PUT /contributors-service/trusted_level
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | string | сontributor's moderator id |
| level | number | trusted level |
Example Response
{
"trusted_level": 2,
"ts": "2017-01-15T13:22:57Z"
}
Read the level of сontributor's moderator
Endpoint for contributors supervisors to read current trusted level of сontributor's moderator. Roles required: “contributors_supervisor”
POST /contributors-service/trusted_level
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | string | сontributor's moderator id |
Example Response
{
"id": "urn:authenticateit:user:email:test1@gmail.com",
"supervisor_id": "urn:authenticateit:user:email:my@gmail.com",
"trusted_level": 2,
"trusted_rating": 0,
"ts": "2017-01-15T13:26:50Z"
}
Read and locking document
Endpoint for moderators for read document and locking it. Roles required: “contributors_moderator”
product_data section returns current brand_id, name, owner of the stored product
POST /contributors-service/contributor_docs/:id
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | document id | |
| lock | lock flag |
Example Response. Level=1. New document
{
"conditions": {
"country": "643",
"language": "ru"
},
"created": "2018-06-04T10:25:31Z",
"data": {
"back_view": "https://dev-cdn.shping.com/2018/6/4/89526dbd-3099-47aa-a4fb-35fe2297b09b",
"bottom_view": "https://dev-cdn.shping.com/2018/6/4/b8219ef4-5b5f-4671-a40a-59a9336ce2d6",
"widgets": [
{
"image": [
{
"url": "https://dev-cdn.shping.com/2018/6/4/5eaca8e9-2ec2-42e9-af9f-44d9dafebbad"
},
{
"url": "https://dev-cdn.shping.com/2018/6/4/f696dbbf-00b8-421a-a968-5d636ae43086"
}
]
}
]
},
"product_data": {
"brand_id": "Jumbo Ugg",
"name": "BUTTON TALL GRAPE 5",
"owner": "urn:authenticateit:participant:576318441844504"
},
"id": "urn:authenticateit:contributor_doc:562740939083956",
"lock": true,
"locked_by": "urn:authenticateit:user:email:level1@mailinator.com",
"owner": {
"id": "urn:authenticateit:user:email:email@mailinator.com",
"ts": "2018-06-04T10:25:31Z"
},
"product_id": "04665270951320",
"reviewing_history": [],
"reviewing_status": {
"status": "unreviewed"
},
"rewards": {
"coins": 2000000000000000000,
"doc_id": "urn:authenticateit:contributor_doc:562740939083956",
"user_id": "urn:authenticateit:user:email:email@mailinator.com"
},
"type": "contributor_doc",
"user_id": "urn:authenticateit:user:email:email@mailinator.com"
}
Example Response. Level=1. Rejected document
{
"conditions": {
"country": "643",
"language": "ru"
},
"created": "2018-04-09T18:43:14Z",
"data": {
"image": "https://dev-cdn.shping.com/2018/4/9/5389cb24-dacf-436d-929c-048ae5b2076d",
"widgets": [
{
"image": [
{
"url": "https://dev-cdn.shping.com/2018/4/9/5389cb24-dacf-436d-929c-048ae5b2076d"
}
]
}
]
},
"id": "urn:authenticateit:contributor_doc:804234598237641",
"lock": true,
"locked_by": "urn:authenticateit:user:email:level1@mailinator.com",
"owner": {
"id": "urn:authenticateit:user:email:email@mailinator.com",
"ts": "2018-04-09T18:43:14Z"
},
"product_data": {
"brand_id": "Jumbo Ugg",
"name": "BUTTON TALL GRAPE 5",
"owner": "urn:authenticateit:participant:576318441844504"
},
"product_id": "00000007929878",
"reviewing_history": [],
"reviewing_status": {
"reason": "Bad description",
"status": "unreviewed"
},
"rewards": {
"coins": 2000000000000000000,
"doc_id": "urn:authenticateit:contributor_doc:804234598237641",
"user_id": "urn:authenticateit:user:email:email@mailinator.com"
},
"type": "contributor_doc",
"user_id": "urn:authenticateit:user:email:email@mailinator.com"
}
Example Response. Level=2
{
"conditions": {
"country": "036",
"language": "en"
},
"created": "2018-06-05T12:10:43Z",
"data": {
"image": "https://dev-cdn.shping.com/2018/4/9/5389cb24-dacf-436d-929c-048ae5b2076d",
"owner": {
"id": "urn:authenticateit:user:email:email@mailinator.com",
"ts": "2018-06-05T11:36:38.989Z"
},
"widgets": [
{
"text": {
"markdown": false,
"text": "Name",
"title": "Product Name"
}
},
{
"image": [
{
"url": "https://dev-cdn.shping.com/2018/6/4/5eaca8e9-2ec2-42e9-af9f-44d9dafebbad"
},
{
"url": "https://dev-cdn.shping.com/2018/6/4/f696dbbf-00b8-421a-a968-5d636ae43086"
}
]
}
]
},
"id": "urn:authenticateit:contributor_doc:286769007190535",
"lock": true,
"locked_by": "urn:authenticateit:user:email:level1@mailinator.com",
"product_id": "00000007929878",
"reviewing_history": [
{
"data": {
"image": "https://dev-cdn.shping.com/2018/4/9/5389cb24-dacf-436d-929c-048ae5b2076d",
"widgets": [
{
"image": [
{
"url": "https://dev-cdn.shping.com/2018/4/9/5389cb24-dacf-436d-929c-048ae5b2076d"
}
]
}
]
},
"reviewing_status": {
"accuracy": 80,
"id": "urn:authenticateit:user:email:level1@mailinator.com",
"next_doc": "urn:authenticateit:contributor_doc:286769007190535",
"status": "approved",
"ts": "2018-06-05T12:10:43Z"
}
}
],
"product_data": {
"brand_id": "Jumbo Ugg",
"name": "BUTTON TALL GRAPE 5",
"owner": "urn:authenticateit:participant:576318441844504"
},
"reviewing_status": {
"history": [
"approved"
],
"level": 1,
"moderator_email": "level1@mailinator.com",
"moderator_first_name": "level1",
"moderator_last_name": "Level",
"prev_accuracy": 80,
"prev_doc": "urn:authenticateit:contributor_doc:804234598237641",
"status": "unreviewed"
},
"rewards": {
"coins": 2000000000000000000,
"doc_id": "urn:authenticateit:contributor_doc:804234598237641",
"user_id": "urn:authenticateit:user:email:email@mailinator.com"
},
"scan_id": null,
"type": "contributor_doc",
"user_id": "urn:authenticateit:user:email:email@mailinator.com"
}
Field “reviewing_history” contained older versions of data and it review status.
Unlocking document
Endpoint for moderators for unlocking previously locking doc. Roles required: “contributors_moderator”
PUT /contributors-service/contributor_docs/unlock/:id
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | string | document id |
Reviewing document
Endpoint for contributors moderators to reviewing the document. Roles required: “contributors_moderator”
Moderator is able to set up a brand in document.data.brand_id section.
The brand must be valid. If gtin has already present then distribution must be set up between brand and product_owner (if the owner is not a system participant)
If the key document.data.brand_id does not exist - there will not make any effect to the gtin
If key document.data.brand_id=null - the brand will be removed from the product
If key document.data.brand_id=...valid brand... - the brand will be replaced
PUT /contributors-service/contributor_docs/:id
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | reviewing document id | |
| status | reviewing status | |
| conditions | New conditions | |
| document | new document body | |
| reason | Text for moderator |
Example Request (approved)
{
"accuracy": 80,
"status": "approved",
"conditions":{"language":"en", "country":"036"},
"document": {
"data": {
"brand_id": "urn:authenticateit:brand:f0c7bd79-5ec3-4bfe-b548-4c6465ac820b",
"widgets": [
{
"text": {
"markdown": false,
"text": "Name",
"title": "Product Name"
}
},
{
"image": [
{
"url": "https://dev-cdn.shping.com/2018/6/4/5eaca8e9-2ec2-42e9-af9f-44d9dafebbad"
},
{
"url": "https://dev-cdn.shping.com/2018/6/4/f696dbbf-00b8-421a-a968-5d636ae43086"
}
]
}
],
"owner": {
"id": "urn:authenticateit:user:email:email@mailinator.com",
"ts": "2018-06-05T11:36:38.989Z"
}
}
}
}
Example Request (deleted)
{
"status": "deleted",
"reason":"Bad description",
"document": {
"data": {
"widgets": [
{
"text": {
"markdown": false,
"text": "Name",
"title": "Product Name"
}
},
{
"image": [
{
"url": "https://dev-cdn.shping.com/2018/6/4/5eaca8e9-2ec2-42e9-af9f-44d9dafebbad"
},
{
"url": "https://dev-cdn.shping.com/2018/6/4/f696dbbf-00b8-421a-a968-5d636ae43086"
}
]
}
]
}
}
}
Example Response
It depends on the level of moderator
trusted_level=1, moderator updates the unreviewed document with id=urn:authenticateit:contributor_doc:804234598237641
{
"document_id": "urn:authenticateit:contributor_doc:804234598237641",
"reviewing_status": {
"accuracy": 80,
"id": "urn:authenticateit:user:email:level1@mailinator.com",
"next_doc": "urn:authenticateit:contributor_doc:286769007190535",
"status": "approved",
"ts": "2018-06-05T12:10:43Z"
}
}
trusted_level=2, moderator updates the reviewed document with id=urn:authenticateit:contributor_doc:657780238761081
{
"document_id": "urn:authenticateit:contributor_doc:657780238761081",
"reviewing_status": {
"history": [
"approved"
],
"id": "urn:authenticateit:user:email:test1@gmail.com",
"level": 1,
"next_doc": "urn:authenticateit:contributor_doc:617171882335734",
"prev_doc": "urn:authenticateit:contributor_doc:144872424060662",
"status": "approved",
"ts": "2017-01-15T14:12:46Z"
}
}
trusted_level=2, moderator delete the document with id=urn:authenticateit:contributor_doc:286769007190535
{
"closed_documents": [
{
"document_id": "urn:authenticateit:contributor_doc:286769007190535"
}
],
"final_status": "unreviewed"
}
trusted_level=3, moderator approves the document with id=urn:authenticateit:contributor_doc:617171882335734
{
"closed_documents": [
{"document_id":"urn:authenticateit:contributor_doc:144872424060662"},
{"document_id":"urn:authenticateit:contributor_doc:657780238761081"},
{"document_id":"urn:authenticateit:contributor_doc:617171882335734"}
],
"final_document": {
"id": "0123456789",
"name": "Perfect Product",
"owner": "urn:authenticateit:user:email:my@gmail.com",
"sources": [
{
"conditions": {
"country": "044",
"language": "ru"
},
"data": [
{
"text": {
"text": "Perfect Product Description",
"title": "Some Brand Name-Perfect Product"
}
}
],
"id": "urn:authenticateit:user:email:my@gmail.com",
"type": "contributor"
}
],
"type": "gtin"
},
"final_status": "approved"
}
trusted_level=3, moderator deletes the document with id=urn:authenticateit:contributor_doc:888393519857163
{
"closed_documents": [
{"document_id":"urn:authenticateit:contributor_doc:291039659648371"},
{"document_id":"urn:authenticateit:contributor_doc:333080554492567"},
{"document_id":"urn:authenticateit:contributor_doc:888393519857163"}
],
"final_status": "deleted"
}