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
with_receipt boolean Select only documents with receipts
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")

with_receipt filter allows filtering documents that are linked to receipts:

  • true - Only linked documents
  • false - Only unlinked documents
  • no_filter - Ignore filter
Example Response
{
    "count": 2,
    "documents": [
        {
            "country": "643",
            "id": "urn:authenticateit:contributor_doc:675263878887127",
            "img": null,
            "language": "ru",
            "level": 0,
            "with_receipt": false,
            "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"
        },
        {
            "country": "036",
            "id": "urn:authenticateit:contributor_doc:067927640337671",
            "img": "https://dev-cdn.shping.com/2023/3/7/011508f8-9b03-4509-9c25-a6aca9a7e30c",
            "item_id": "feb54636-71dc-4036-bf51-4b8251dee73f",
            "language": "en",
            "level": 0,
            "lock": 0,
            "locked_by": "urn:authenticateit:user:email:system@authenticateit.com",
            "moderator_email": null,
            "moderator_first_name": null,
            "moderator_last_name": null,
            "owner": "urn:authenticateit:user:email:shping:9cf92a52-e708-4d45-a7f5-53ed475c1c3c",
            "product_id": "00111900001193",
            "reason": null,
            "receipt_id": "50502cb9-8163-4fdf-a59c-2154bf1b1425",
            "reviewer": null,
            "status": "closed",
            "ts": "2023-03-07T00:18:13Z"
        }
    ]
}
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"
}

results matching ""

    No results matching ""