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. The following parameters may be specified in request body:

  • name — participant's name.
  • country, post_code, state, city, address — participant's address.
  • email — contact email address.
  • phone — contact phone number.
  • contact — contact person's name.
  • facebook_url — link to participant's Facebook profile.
  • utc_time_zone — UTC offset in hours.
  • gln — GLN.
  • external_id — arbitrary external identifier.
  • logo — link to participant's logo.
  • authentic_barcodes — serialized GTINs of participant will have "Authentic Barcode" status when scanned.
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

Create participant. Only system participant is allowed to create new participants directly. Accepts JSON object with fields company_prefix (list of company prefixes for participant (prefix may be "*")), participant_type (expert, manufacturer, partner, product360), name (participant name) and country (participant country code). Responds with JSON representation of newly created participant.

POST /participant-service/participants
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "name": "ACO Expert",
  "company_prefix": [
    "999949384",
    "999949529"
  ],
  "participant_type": "expert",
  "country": "036"
}
Example Request
{
  "company_prefix": [
    "999949384",
    "999949529"
  ],
  "country": "036",
  "id": "urn:authenticateit:participant:73082866710077",
  "name": "ACO Expert",
  "parent": "urn:authenticateit:participant:1",
  "participant_type": [
    "expert"
  ]
}

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

results matching ""

    No results matching ""