Contributors

All contributors endpoints have path prefix /contributors-service.

Contributors settings

Example of settings document

{
  "id": "urn:authenticateit:contributor_settings",
  "contributor_levels": [
    {
      "type": "newbie",
      "name": "Newbie",
      "coin_rate": 1
    },
    {
      "type": "expert",
      "contributions": 10,
      "accuracy_rating": 90,
      "interval": "month",
      "name": "Expert",
      "coin_rate": 2
    },
    {
      "type": "Guru",
      "name": "guru",
      "contributions": 30,
      "accuracy_rating": 97,
      "interval": "month",
      "coin_rate": 3
    }
  ],
  "moderator": [
    {
      "random_document_reviewing": 0,
      "level": 1,
      "downgrade_rating": 0.01,
      "upgrade_rating": 0.05
    },
    {
      "random_document_reviewing": 10,
      "level": 2,
      "downgrade_rating": 0.1,
      "upgrade_rating": 0.1
    },
    {
      "random_document_reviewing": 0,
      "level": 3
    }
  ],
  "type": "system_doc"
}

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

Contributor Schema

Example of schema:

{
  "user": [
    {
      "item": "company",
      "name": "Company name",
      "field": "required",
      "type": "text",
      "help": "Enter the company name (usually directed on the package)",
      "conditions": {
        "language": "en"
      }
    },
    {
      "item": "brand",
      "name": "Brand name",
      "field": "required",
      "type": "text",
      "help": "Enter the brand name (usually directed on the package)",
      "conditions": {
        "language": "en"
      }
    },
    {
      "item": "product_name",
      "name": "Product name",
      "field": "required",
      "type": "text",
      "help": "Enter the product name (usually directed on the package)",
      "conditions": {
        "language": "en"
      }
    },
    {
      "item": "description",
      "name": "Description",
      "field": "required",
      "type": "text",
      "help": "Enter description the product",
      "conditions": {
        "language": "en"
      }
    },
    {
      "item": "image",
      "name": "Image",
      "field": "required",
      "type": "image",
      "help": "You can make a photo",
      "conditions": {
        "language": "en"
      }
    },
    {
      "item": "nutrition_info",
      "name": "Nutrition information",
      "field": "optional",
      "type": "image",
      "help": "You can make a photo or provide information from package",
      "conditions": {
        "language": "en"
      }
    }
  ],
  "contributor": {
    "text_widget": {
      "title": [
        "brand",
        "-",
        "product_name"
      ],
      "text": "description"
    }
  }
}
Schema description
user field includes a list of user widgets
contributor map between user widgets and gtin widgets
User widgets description
item widget's system name Example: “company”
name name of widget (It will be shown to the user) Example: “Company Name”
field required or optional Example: “required”
type type of widget - “text” and “image” Example: “text”
help widget help text (It will be shown to the user) Example: “You can make a photo or provide information from package”
conditions widget conditions - supports only language Example: {“language”: “en”} or {“language”: [“en”, “ru”]}

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 Scan id
Example Request
{
  "scan_id": "112694b3-1425-48eb-9d48-9e5d55642b02",
  "data": {
    "company": "Some Company Name",
    "brand": "Some Brand Name",
    "product_name": "Perfect Product",
    "description": "Perfect Product Description",
    "image": "http://localhost/image.png",
    "nutrition_info": "http://localhost/some_image.png"
  }
}
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
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
Example Response
{
  "documents": [
    {
      "id": "urn:authenticateit:contributor_doc:860882970513377",
      "level": 2,
      "owner": "urn:authenticateit:user:email:test1@gmail.com",
      "product_id": "0123456789",
      "reviewer": "urn:authenticateit:user:email:my@gmail.com",
      "status": "approved",
      "ts": "2016-12-27T12:40:57Z"
    }
  ]
}
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”

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
{
  "conditions": {
    "country": "643",
    "language": "ru"
  },
  "created": "2017-08-24T11:05:15Z",
  "data": {
    "brand": "Some Brand Name",
    "company": "Some Company Name",
    "description": "Perfect Product Description",
    "image": "http://localhost/image.png",
    "nutrition_info": "http://localhost/image.png",
    "product_name": "Perfect Product",
    "widgets": {
      "text": {
        "text": "Perfect Product Description",
        "title": "Some Brand Name-Perfect Product"
      }
    }
  },
  "id": "urn:authenticateit:contributor_doc:514973036878252",
  "owner": {
    "id": "urn:authenticateit:user:email:zippityelf@mailinator.com",
    "ts": "2017-08-24T11:05:15Z"
  },
  "product_id": "04324654768588",
  "reviewing_history": [],
  "reviewing_status": {
    "status": "unreviewed"
  },
  "type": "contributor_doc",
  "user_id": "urn:authenticateit:user:email:zippityelf@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”

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
document new document body
Example Request
{
  "status": "approved",
  "document": {
    "data": {
      "description": "Perfect Product Description",
      "product_name": "Perfect Product",
      "owner": {
        "id": "urn:authenticateit:user:email:my@gmail.com",
        "ts": "2017-01-15T12:12:11Z"
      },
      "widgets": [
        {
          "text": {
            "text": "Perfect Product Description",
            "title": "Some Brand Name-Perfect Product"
          }
        }
      ]
    },
    "product_id": "0123456789"
  }
}
Example Response

It depends on the level of moderator

trusted_level=1, moderator updates the unreviewed document with id=urn:authenticateit:contributor_doc:144872424060662

{
  "document_id": "urn:authenticateit:contributor_doc:144872424060662",
  "reviewing_status": {
    "id": "urn:authenticateit:user:email:my@gmail.com",
    "next_doc": "urn:authenticateit:contributor_doc:657780238761081",
    "status": "approved",
    "ts": "2017-01-15T14:08:55Z"
  }
}

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=3, moderator approves the document with id=urn:authenticateit:contributor_doc:617171882335734

{
  "closed_documents": [
    "urn:authenticateit:contributor_doc:144872424060662",
    "urn:authenticateit:contributor_doc:657780238761081",
    "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": [
    "urn:authenticateit:contributor_doc:291039659648371",
    "urn:authenticateit:contributor_doc:333080554492567",
    "urn:authenticateit:contributor_doc:888393519857163"
  ],
  "final_status": "deleted"
}

results matching ""

    No results matching ""