Participants

Read participant profile

Read current participant profile

GET /participant-service/users/participant

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket

Example Response

{
  "address": "Some Str.",
  "city": "Some City",
  "company_prefix": [
    "00000935254"
  ],
  "contact": "ContactName",
  "country": "036",
  "email": "foo@bar.ru",
  "external_id": "321",
  "facebook_url": "facebook.com/12345",
  "gln": "123",
  "name": "Name",
  "parent": "urn:authenticateit:participant:1486463259613",
  "participant_type": [
    "manufacturer",
    "system"
  ],
  "logo": "http://dev-cdn.shping.com.s3.amazonaws.com/file2.png",
  "phone": "+7919186733",
  "post_code": "1234",
  "state": "Some State",
  "utc_time_zone": 12
}

Edit participant profile

Current participant may edit the profile

PUT /participant-service/users/participant

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket

Example Request

{
  "name": "Name",
  "address": "Some Str.",
  "city": "Some City",
  "country": "036",
  "contact": "ContactName",
  "phone": "+7919186733",
  "email": "foo@bar.ru",
  "gln": "123",
  "external_id": "321",
  "state": "Some State",
  "post_code": "1234",
  "utc_time_zone": 12,
  "logo":"http://dev-cdn.shping.com.s3.amazonaws.com/file2.png",
  "facebook_url": "facebook.com/12345"
}

Example Response

{
  "address": "Some Str.",
  "city": "Some City",
  "company_prefix": [
    "00000935254"
  ],
  "contact": "ContactName",
  "country": "036",
  "email": "foo@bar.ru",
  "external_id": "321",
  "facebook_url": "facebook.com/12345",
  "gln": "123",
  "name": "Name",
  "parent": "urn:authenticateit:participant:1486463259613",
  "participant_type": [
    "manufacturer"
  ],
  "phone": "+7919186733",
  "post_code": "1234",
  "state": "Some State",
  "utc_time_zone": 12
}

Add participant

Participant types: product360, manufacturer, expert, partner

POST /participant-service/participants

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket

Example Request

{
  "company_prefix": "“999949384",
  "id": "urn:epc:sgln:0614141.12345.1",
  "participant_type": "manufacturer",
  "name": "Ugg",
  "country": "Australia"
}

Get participants

GET /participant-service/users/participants

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket

Delete participant

DELETE /participant-service/participant/:participant_id

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket

Update? participant

POST /participant-service/users/participant

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket

Example Request

{
    "id": "urn:epc:sgln:0614141.12345.1",
    "name": "Ugg",
    "country" : "Australia"
}

Participant's team

The section describes methods for working with a participant's team. Already nominated user with role “security_admin” can add other user to registered participant.

Add/update user

Current user can add other registered users to team. Method must be used for invite user to participant's team or update user in team

POST /participant-service/team

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
id	string	email, facebook id, system id
access_type	string	Possible values: “Admin”, “Content Writer”, “Moderator” (for system participant only)

Example Response

[
  {
    "access_type": "Content Writer",
    "first_name": "Sveta",
    "id": "urn:authenticateit:user:email:my2@gmail.com",
    "last_access": null,
    "last_name": "LastName",
    "ts": "2017-03-24T09:21:50Z"
  },
  {
    "access_type": "Admin",
    "id": "urn:authenticateit:user:email:foo@bar.com",
    "last_access": "2017-03-24T09:12:41Z",
    "ts": "2017-03-24T09:11:47Z"
  }
]

Add/update user with specified roles

Current user can add other registered users to team with specified roles.

POST /participant-service/team

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
id	string	email, facebook id, system id
access_type	string	Possible values: “Admin”, “Content Writer”, “Moderator” (for system participant only)
user_roles	array::string	User's roles

Example Response

[
  {
    "access_type": "Content Writer",
    "first_name": "n",
    "id": "urn:authenticateit:user:email:2qw@mailinator.com",
    "last_access": null,
    "last_name": "n",
    "roles": [
      "contributors_moderator"
    ],
    "trusted_level": 1,
    "trusted_rating": 0,
    "ts": "2017-06-22T09:12:47Z"
  },
  {
    "access_type": "Admin",
    "id": "urn:authenticateit:user:email:foo@bar.com",
    "last_access": "2017-03-24T09:12:41Z",
    "ts": "2017-03-24T09:11:47Z"
  }
]

Get participant's team

Get currents participant's team list

GET /participant-service/team

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket

Example Response

[
  {
    "access_type": "Content Writer",
    "first_name": "Sveta",
    "id": "urn:authenticateit:user:email:my2@gmail.com",
    "last_access": null,
    "last_name": "LastName",
    "ts": "2017-03-24T09:21:50Z"
  },
  {
    "access_type": "Admin",
    "id": "urn:authenticateit:user:email:foo@bar.com",
    "last_access": "2017-03-24T09:12:41Z",
    "ts": "2017-03-24T09:11:47Z"
  }
]

Remove user from team

POST /participant-service/team/delete

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
id	string	email, facebook id, system id

Example Response

[
  {
    "access_type": "Admin",
    "id": "urn:authenticateit:user:email:foo@bar.com",
    "last_access": "2017-03-24T09:12:41Z",
    "ts": "2017-03-24T09:11:47Z"
  }
]

Brands

Create New Brand

Takes JSON object containing unique brand name and URL of brand logo image.

POST  /participant-service/brands

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
name	string	Brand name
logo	string	Img url on our S3 bucket

Example Response

{
  "id": "Koalabi Australia",
  "logo": "http://dev-cdn.shping.com.s3.amazonaws.com/koalabi.png",
  "owner": "urn:epc:sgln:0614141.12345.1",
  "approved": false
}

Update Brand

Currently, only brand logo URL can be changed. Takes JSON object containing URL of brand logo image. Brand that was already approved by parent participant couldn't be changed.

PUT /participant-service/brands/:id

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
id	string	Brand identifier, unique brand name
logo	string	Img url on our S3 bucket

Example Response

{
  "id": "Koalabi Australia",
  "logo": "http://dev-cdn.shping.com.s3.amazonaws.com/koalabi.png",
  "owner": "urn:epc:sgln:0614141.12345.1",
  "approved": false
}

Approve Brand

Approve brand created by a child participant. No body required in the request.

PUT /participant-service/brands/:id/approved

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
id	string	Brand identifier, unique brand name

Example Response

{
  "id": "Koalabi Australia",
  "logo": "http://dev-cdn.shping.com.s3.amazonaws.com/koalabi-large.png",
  "owner": "urn:epc:sgln:0614141.12345.1",
  "approved": true
}

Marketing Profiles

Create New Marketing Profile

Takes JSON object containing marketing profile name, a set of conditions and a list of widgets.

POST /participant-service/marketing_profiles

Parameters

Name	Type	Description
authenticateit_identity_ticket	header	Required: Session's ticket
name	string	Marketing profile name
language	string	Language code in ISO format
countries	array::string	Countries codes
genders	array::string	e.g. ["male", "unknown"]
min_age	number	Min age
max_age	number	Max age
min_date	string	e.g. "2016-12-19"
max_date	string	e.g. "2016-12-29"
min_scans	number	Min scans
max_scans	number	Max scans
register_methods	array::string	e.g. ["email", "facebook"]
widgets	array:object	Array of widgets

Example Response

{
  "countries": [
    "036",
    "643"
  ],
  "genders": [
    "male",
    "unknown"
  ],
  "id": "urn:epc:id:gdti:123.3.842393846914558",
  "language": "en",
  "max_age": 30,
  "max_date": "2016-12-25",
  "max_scans": 15,
  "min_age": 14,
  "min_date": "2016-12-19",
  "min_scans": 0,
  "name": "Xyz",
  "owner": "urn:epc:sgln:0614141.12345.1",
  "register_methods": [
    "email",
    "facebook"
  ],
  "widgets": [
    {
      "header": {
        "text": "Xyz!"
      }
    },
    {
      "text": {
        "lines": 2,
        "text": "B",
        "title": "A"
      }
    }
  ]
}

Attach Marketing Profile to a Trade Item

Attaches requested marketing profile to the trade item. Takes JSON object containing marketing profile identifier.

POST /participant-service/gtins/:id/marketing_profiles

Parameters

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

Supply Chain

Create Participant

Create child distributor or retailer for current participant. Takes JSON object containing participant fields.

There are fields for child participant's address (all required):

country (country code)
post_code
state
city
address
time_zone (UTC offset in minutes; e.g., +03:00 is 180)

Supply chain related fields (all required):

type (distributor or retailer)
company_prefix (list of company prefixes for the participant)
gln
products (non-empty list of associated GTINs)
name

Fields for participant contact information:

phone
email
contact (name of a person to contact)

Also there may be external_id (arbitrary identifier) field for external references.

To create child distributor or retailer current participant must have active supply_chain module and must have distributor type. Also participants with module serialization can create child distributor participants.

Current user is nominated with supply_chain_admin role by newly created participant.

POST /participant-service/supply_chain/participants

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket

Example Request

{
  "type": "distributor",
  "external_id": "289",
  "company_prefix": ["4603721"],
  "name": "Two Toy",
  "gln": "4603721111111",
  "country": "643",
  "city": "Novorossiysk",
  "address": "Portovaya, 14",
  "products": [
    "46037211111111"
  ]
}

Example Response

{
  "id": "urn:authenticateit:participant:655831267204784",
  "parent": "urn:authenticateit:participant:827735452030300",
  "participant_type": ["distributor"],
  "external_id": "289",
  "company_prefix": ["4603721"],
  "name": "Two Toy",
  "gln": "4603721111111",
  "country": "643",
  "city": "Novorossiysk",
  "address": "Portovaya, 14",
  "products": [
    "46037211111111"
  ]
}

Update Participant

Update child distributor or retailer participant. Takes JSON object containing fields to update (see description for Create Participant endpoint above for the list of fields).

PUT /participant-service/supply_chain/participants/:id

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`id`	string	distributor/retailer id

Example Request

{
  "external_id": "288",
  "name": "Two Toyz"
}

Example Response

{
  "id": "urn:authenticateit:participant:655831267204784",
  "parent": "urn:authenticateit:participant:827735452030300",
  "participant_type": ["distributor"],
  "external_id": "288",
  "company_prefix": ["4603721"],
  "name": "Two Toyz",
  "gln": "4603721111111",
  "country": "643",
  "city": "Novorossiysk",
  "address": "Portovaya, 14",
  "products": [
    "46037211111111"
  ]
}

Read Participants

Read list of children distributors or retailers for current participant. Parameter type may be used to return only participants of the specified type (distributor or retailer).

Number of returned participants may be limited with the limit parameter (default valus is 100). Number of participants may be skipped from the list with the offset parameter (0 by default).

Returned participants may be filtered by type (distributor or retailer), external_id, company_prefix (supply chain participant must have all of the specified prefixes to be included in the response), name, gln, country, post_code, state, city, address, contact, phone, email, products (supply chain participant must have all of the specified GTINs associated to be included in the response).

The resulting list may be sorted. Parameter sort_by should be used to specify sorting field (external_id, name, gln, country, post_code, state, city, address, contact, time_zone, phone and email). Sorting order may be specified with sort_order parameter (asc for ascending order and desc for descending order).

GET /participant-service/supply_chain/participants

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`type`	string	`distributor` or `retailer`
`offset`		Skip number of participants from the resulting list.
`limit`		Limit the number of participants in the resulting list.
`external_id`		Only participants with this external identifier.
`company_prefix`		Only participants with all of these prefixes.
`name`		Only participants with name matching this string.
`gln`		Only participants with this GLN.
`country`		Only participants with this country code.
`post_code`		Only participants with this post code.
`state`		Only participants with state mathching this string.
`city`		Only participants with city matching this string.
`address`		Only participants with address matching this string.
`contact`		Only participants with contact name matching this string.
`phone`		Only participants with this phone number.
`email`		Only participants with email address matching this string.
`products`		Only participants with all of these products associated.
`sort_by`		Sort participants by field.
`sort_order`		Ascending or descending sort order.

Example Response

{
  "participants": [
    {
      "id": "urn:authenticateit:participant:655831267204784",
      "parent": "urn:authenticateit:participant:827735452030300",
      "participant_type": [
        "distributor"
      ],
      "external_id": "288",
      "company_prefix": ["4603721"],
      "name": "Two Toyz",
      "gln": "4603721111111",
      "country": "643",
      "city": "Novorossiysk",
      "address": "Portovaya, 14",
      "products": [
        "46037211111111"
      ]
    },
    {
      "id": "urn:authenticateit:participant:954339092655685",
      "parent": "urn:authenticateit:participant:827735452030300",
      "participant_type": [
        "retailer"
      ],
      "external_id": "354",
      "company_prefix": ["4603721"],
      "name": "Two Toyz Store",
      "gln": "4603721111111",
      "country": "643",
      "city": "Novorossiysk",
      "address": "Serebryakova, 2",
      "products": [
        "46037211111111"
      ]
    }
  ],
  "sort_by": "id",
  "sort_order": "asc",
  "offset": 0,
  "limit": 100
}

Read Participant Business Locations

Read list of children distributors or retailers, but instead of participant details include business_locations list for each child participant. See business locations API for description of location JSON representation. Parameter type may be used to return only business locations for participants of the specified type (distributor or retailer).

GET /participant-service/supply_chain/business_locations

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`type`	string	`distributor` or `retailer`

Example Response

{
  "participants": [
    {
      "id": "urn:authenticateit:participant:655831267204784",
      "business_locations": [
        {
          "id": "2c2a486e-8b3f-4a61-a9ac-8400ffa4df73",
          "sub_site_type": "207",
          "name": "Storage Area",
          "address": "Portovaya, 14",
          "city": "Novorossiysk",
          "state": "Krasnodar krai",
          "post_code": "353909",
          "country": "643",
          "latitude": 44.7368214,
          "longitude": 37.7784576,
          "accuracy": 756
        },
        {
          "id": "8a62195e-964d-46d5-a6bd-76fcdf330def",
          "sub_site_type": "206",
          "name": "Xyz",
          "address": "Portovaya, 14",
          "city": "Novorossiysk",
          "state": "Krasnodar krai",
          "post_code": "353909",
          "country": "643",
          "latitude": 44.7368214,
          "longitude": 37.7784576,
          "accuracy": 827
        }
      ]
    },
    {
      "id": "urn:authenticateit:participant:954339092655685",
      "business_locations": []
    }
  ]
}

Delete Participant

Delete child distributor or retailer for current participant.

DELETE /participant-service/supply_chain/participants/:id

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`id`	string	distributor/retailer id

Business Locations

Participant must have supply_chain module active to work with business locations.

Create Location

Create a business location for supply chain participant. Takes JSON object containing fields for business location address: country (country code), post_code, state, city, address. Location coordinates latitude, longitude, and coordinates accuracy in metres. Other fields are sub_site_type (EPCglobal sub-site type code), name (location name). All fields are required.

Participant can create business locations for it's immediate child supply chain participants. Identifier of child participant should be provided in owner parameter in this case.

POST /participant-service/business_locations

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket

Example Request

{
  "sub_site_type": "207",
  "name": "Storage Area",
  "address": "Elevatornaya, 22",
  "city": "Novorossiysk",
  "state": "Krasnodar krai",
  "post_code": "353909",
  "country": "643",
  "latitude": 44736821,
  "longitude": 37778457,
  "accuracy": 378
}

Example Response

{
  "id": "9b3102d2-715a-4e1f-92a2-1ccfec7b9bd5",
  "sub_site_type": "207",
  "name": "Storage Area",
  "address": "Elevatornaya, 22",
  "city": "Novorossiysk",
  "state": "Krasnodar krai",
  "post_code": "353909",
  "country": "643",
  "latitude": 44736821,
  "longitude": 37778457,
  "accuracy": 378
}

Update Location

Update business location data. Takes JSON object containing fields to change (see Create Location endpoint for the list of fields).

PUT /participant-service/business_locations/:id

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`id`	string	Business location id

Example Request

{
  "sub_site_type": "202"
}

Example Response

{
  "id": "9b3102d2-715a-4e1f-92a2-1ccfec7b9bd5",
  "sub_site_type": "202",
  "name": "Storage Area",
  "address": "Elevatornaya, 22",
  "city": "Novorossiysk",
  "state": "Krasnodar krai",
  "post_code": "353909",
  "country": "643",
  "latitude": 44.7368214,
  "longitude": 37.7784576,
  "accuracy": 378
}

Read Locations

Read list of participant's business locations.

Number of returned locations may be limited with the limit parameter (default valus is 100). Number of locations may be skipped from the list with the offset parameter (0 by default).

Returned locations may be filtered by sub_site_type, name, address, city, state, post_code and country.

The resulting list may be sorted. Parameter sort_by should be used to specify sorting field (sub_site_type, name, address, city, state, post_code or country). Sorting order may be specified with sort_order parameter (asc for ascending order and desc for descending order).

There is a parameter retrieve to control which locations to return. If it's value is own (the default value), participant's own business locations will be retrieved. If it's value is child, business locations of immediate child supply chain participant will be retrieved. If it's all both own and child locations will be present in the response.

GET /participant-service/business_locations

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`offset`		Skip number of locations from the resulting list.
`limit`		Limit the number of locations in the resulting list.
`sub_site_type`		Only locations with this sub-site type.
`name`		Only locations with name matching this string.
`address`		Only locations with address mathching this string.
`city`		Only with city matching this string.
`state`		Only with state mathching this string.
`post_code`		Only locations with this post code.
`country`		Only locations with this country code.
`sort_by`		Sort locations by field.
`sort_order`		Ascending or descending sort order.
`retrieve`		Retrieve `own`, `child` or `all` locations.

Example Response

{
  "business_locations": [
    {
      "id": "9b3102d2-715a-4e1f-92a2-1ccfec7b9bd5",
      "sub_site_type": "202",
      "name": "Storage Area",
      "address": "Elevatornaya, 22",
      "city": "Novorossiysk",
      "state": "Krasnodar krai",
      "post_code": "353909",
      "country": "643",
      "latitude": 44.7368214,
      "longitude": 37.7784576,
      "accuracy": 378
    }
  ],
  "sort_by": "id",
  "sort_order": "asc",
  "offset": 0,
  "limit": 100
}

Delete Location

Delete participant's business location.

DELETE /participant-service/business_locations/:id

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`id`	string	Business location id

Serialized Products Reassignment

Create Reassignment Task

Reassign set of serialized products to a new supply chain participant. Takes JSON object containing reassignment description.

Products are selected from current participant's serialized products indexing table with a query. See RSQL API from Index service for description of table, query and op parameters. Indexing table must be of sgtin, lgtin or slgtin type.

To specify new owner of serialized products, use location or participant parameters. If participant provided, it must be identifier of a child supply chain participant. If location is specified, it must be business location identifier and location's owner will be used as participant.

Responds with JSON representation of newly created reassignment task. Task has id which should be used to query task status and progress. Field count in task representation will contain total number of products selected for reassignment.

POST /participant-service/supply_chain/reassignments

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket

Example Request

{
    "table": "index_schema_table_slgtin_aeb5afdf-aa5c-439c-b20d-9504bebf7ecf",
    "query": "id==urn:epc:id:sgtin:084556643.0001.000000000000044;id==urn:epc:id:sgtin:084556643.0001.000000000000043;id==urn:epc:id:sgtin:084556643.0001.000000000000042",
    "op": "OR",
    "participant": "urn:authenticateit:participant:868695661420695"
}

Example Response

{
  "id": "44ff192c-a88d-4089-a534-5f66beafcc78",
  "created": "2018-05-14T21:33:51Z",
  "count": 3,
  "progress": 0
}

Read Reassignment Task

Query reassignment task status and progress.

GET /participant-service/supply_chain/reassignments/:id

Parameters

Name	Type	Description
`authenticateit_identity_ticket`	header	Required: Session's ticket
`id`		Reassignment task identifier.

Example Response

{
  "count": 3,
  "created": "2018-05-14T21:33:51Z",
  "end_time": "2018-05-14T21:33:53Z",
  "id": "44ff192c-a88d-4089-a534-5f66beafcc78",
  "op": "OR",
  "owner": "urn:authenticateit:participant:266730991497899",
  "participant": "urn:authenticateit:participant:868695661420695",
  "progress": 3,
  "query": "id==urn:epc:id:sgtin:084556643.0001.000000000000044;id==urn:epc:id:sgtin:084556643.0001.000000000000043;id==urn:epc:id:sgtin:084556643.0001.000000000000042",
  "real_ip": "95.211.138.15",
  "start_time": "2018-05-14T21:33:51Z",
  "status": "done",
  "table": "index_schema_table_slgtin_aeb5afdf-aa5c-439c-b20d-9504bebf7ecf",
  "user_agent": "curl/7.52.1"
}