ToDo Cards

All ToDo cards endpoints have path prefix /todocards-service.

To access ToDo cards APIs user must have todo_cards_supervisor role from product360, manufacturer, retailer, system or partner participant. Current participant must have todo_cards module active.

Cards

Create Card

Create ToDo card. Takes JSON object containing card name, icon (predefined icon identifier or URL), description, result (reward for ToDo card completion), auto_approve (if false or missing, review by the supervisor will be required on completion), non-empty list of steps. Responds with created card representation.

Predefined icon identifiers are action, brand, contact, fb, support, verify and warning.

The result field must contain coins field (reward in Shping Coins for the user for card completion).

Each step is a JSON object containing step type, title (optional step title) and bunch of other fields depending on the type.

Step type may be text. In that case step must also include text field (textual description of the step).

Step type may be textbox. No other fields are defined for such step. User will be asked to provide some text to complete the step.

Step type may be rating. No other fields are defined for such step. User will be asked to provide a rating (integer number from 1 to 5) to complete the step.

Step type may be question. Fields question (question textual description) and answers (non-empty list of possible answers) must be present for such step. Each answer is a JSON object with fields answer (answer textual description) and optional correct (true if the answer must be accepted as correct).

Step type may be image. No other fields are defined for such step. User will be asked to upload an image to complete the step.

ToDo card also may have an action. The action will be performed on ToDo card completion. Completed ToDo card step values will be mapped to the action fields according to the fields mapping in the action. Action type is determined from it's id field. The only defined action type for now is review.

Action review must contain fields property to describe mapping of values from ToDo card steps to review document title, description and photo properties (see example below). Steps in the mapping are referenced by their index in the steps list.

POST /todocards-service/cards
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "name": "Sample ToDo card",
  "icon": "warning",
  "description": "Complete this survey to earn some coins.",
  "result": {
    "coins": "120000000000000"
  },
  "auto_approve": false,
  "steps": [
    {
      "type": "text",
      "title": "Step 1 title",
      "text": "Review our Product"
    },
    {
      "type": "rating",
      "title": "Please rate this"
    },
    {
      "type": "question",
      "question": "A or B?",
      "answers": [
        {
          "answer": "Definitely A!"
        },
        {
          "answer": "B for sure!",
          "correct": true
        }
      ]
    },
    {
      "type": "image",
      "title": "Upload a photo, please"
    },
    {
      "type": "textbox",
      "title": "What's on your mind?"
    }
  ],
  "action": {
    "id": "review",
    "fields": {
      "title": 0,
      "description": 4,
      "photo": 3
    }
  }
}
Example Response
{
  "name": "Sample ToDo card",
  "icon": "warning",
  "description": "Complete this survey to earn some coins.",
  "result": {
    "coins": "120000000000000"
  },
  "auto_approve": false,
  "steps": [
    {
      "type": "text",
      "title": "Step 1 title",
      "text": "Review our Product"
    },
    {
      "type": "rating",
      "title": "Please rate this"
    },
    {
      "type": "question",
      "question": "A or B?",
      "answers": [
        {
          "answer": "Definitely A!"
        },
        {
          "answer": "B for sure!",
          "correct": true
        }
      ]
    },
    {
      "type": "image",
      "title": "Upload a photo, please"
    },
    {
      "type": "textbox",
      "title": "What's on your mind?"
    }
  ],
  "action": {
    "id": "review",
    "fields": {
      "title": 0,
      "description": 4,
      "photo": 3
    }
  },
  "id": "todo-card-id-1231241231",
  "owner": "participant-id-1231298967123"
}

Update Card

Endpoint for owner participant to update a ToDo card. Takes JSON object containing card (see endpoint for card creation). Responds with updated card representation.

Current participant must be card's owner.

PUT /todocards-service/cards/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Card id
Example Request
{
  "name": "Changed sample ToDo card name",
  "icon": "action",
  "result": {
    "coins": "150000000000000"
  }
}
Example Response
{
  "name": "Changed sample ToDo card name",
  "icon": "action",
  "description": "Complete this survey to earn some coins.",
  "result": {
    "coins": "150000000000000"
  },
  "auto_approve": false,
  "steps": [
    {
      "type": "text",
      "title": "Step 1 title",
      "text": "Review our Product"
    },
    {
      "type": "rating",
      "title": "Please rate this"
    },
    {
      "type": "question",
      "question": "A or B?",
      "answers": [
        {
          "answer": "Definitely A!"
        },
        {
          "answer": "B for sure!",
          "correct": true
        }
      ]
    },
    {
      "type": "image",
      "title": "Upload a photo, please"
    },
    {
      "type": "textbox",
      "title": "What's on your mind?"
    }
  ],
  "action": {
    "id": "review",
    "fields": {
      "title": 0,
      "description": 4,
      "photo": 3
    }
  },
  "id": "todo-card-id-1231241231",
  "owner": "participant-id-1231298967123"
}

Delete Card

Endpoint to delete existing ToDo card by id. Current participant must be card's owner.

DELETE /todocards-service/cards/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Card id

List Cards

List participant's ToDo cards. Accepts offset (skip specified number of cards; 0 by default) and limit (limit the number of returned cards; 100 by default) query parameters. Responds with a list of card representations.

GET /todocards-service/cards
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
offset number Skip specified number of cards
limit number Limit the number of returned cards
Example Response
[
  {
    "name": "Card 1",
    "icon": "action",
    "description": "Descr 1",
    "result": {
      "coins": "10000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "todo-card-id-1",
    "owner": "participant-id-1"
  },
  {
    "name": "Card 2",
    "icon": "action",
    "description": "Descr 2",
    "result": {
      "coins": "20000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "todo-card-id-2",
    "owner": "participant-id-1"
  }
]

Deliveries

Adjustment of budgets and result coins

adjustment.budget and adjustment.result field is required.

POST /todocards-service/adjustment/get
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
adjustment body Required: Adjustment object
Example Request
{
  "adjustment":
  {
      "result": 0.5,
    "coins_step" : "10000000000000000000"
  }
}

Example Response

{
    "coins_step": "10000000000000000000",
    "currency": "usd",
    "result": "1700000000000000000000"
}
Example Request
{
  "adjustment":
  {
      "result": 0.5,
      "country":"036",
    "coins_step" : "10000000000000000000"
  }
}

Example Response

{
    "coins_step": "10000000000000000000",
    "currency": "aud",
    "result": "770000000000000000000"
}
Example Request
{
  "adjustment":
  {
      "result": 0.5,
      "currency":"aud",
    "coins_step" : "10000000000000000000"
  }
}

Example Response

{
    "coins_step": "10000000000000000000",
    "currency": "aud",
    "result": "770000000000000000000"
}

Create Delivery

Create ToDo card delivery. Takes JSON object containing delivery name, card_id (identifier of the card to be used as a template for the delivery; all the card data will be copied and stored inside the delivery), start_date (card will be suggested to the users since this time), end_date (optional; card will not be suggested to the users after this time), budget (limit the amount of coins to be spent on ToDo card completion rewards), audience (target audience, the same as Bot audience), products (ToDo card will be delivered only to the users who scan one of these products; if this field is missing or null, users who scan any participant's product will be considered). Responds with created card delivery representation.

Delivery may also have delay (card wouldn't be delivered to a user for at least delay minutes since user's scan) and count (card wouldn't be delivered to a user until user makes at least count scans).

Current participant must be card's owner.

POST /todocards-service/deliveries
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
Example Request
{
  "adjustment":
  {
      "result": 0.5,
    "coins_step" : "10000000000000000000"
  },
  "name": "End of year delivery",
  "start_date": "2017-12-24T00:00:00Z",
  "end_date": "2017-12-31T23:59:00Z",
  "card_id": "urn:authenticateit:participant:576318441844504:todo_cards:335340395780923",
  "budget": "123000000000000",
  "products": [
    "09212345000152" 
  ],
  "audience": {
    "countries": [
      "036",
      "643"
    ],
    "languages": [
      "en",
      "ru"
    ],
    "min_age": 25,
    "max_age": 30,
    "gender": "male",
    "registration_methods": [
      "email",
      "facebook"
    ],
    "weekly_scans": {
      "from": 15,
      "to": 30
    },
    "scan_countries": [
      "036",
      "643"
    ]
  }
}
Example Response
{
    "adjustment": {
        "coins_step": "10000000000000000000",
        "currency": "usd",
        "result": 0.5
    },
    "audience": {
        "countries": [
            "036",
            "643"
        ],
        "gender": "male",
        "languages": [
            "en",
            "ru"
        ],
        "max_age": 30,
        "min_age": 25,
        "registration_methods": [
            "email",
            "facebook"
        ],
        "scan_countries": [
            "036",
            "643"
        ],
        "weekly_scans": {
            "from": 15,
            "to": 30
        }
    },
    "budget": "2380000000000000000000",
    "card": {
        "auto_approve": true,
        "description": "Test Action",
        "icon": "action",
        "id": "urn:authenticateit:participant:576318441844504:todo_cards:335340395780923",
        "name": "Test4",
        "owner": "urn:authenticateit:participant:576318441844504",
        "result": {
            "coins": "1700000000000000000000"
        },
        "steps": [
            {
                "title": "Set ratio",
                "type": "rating"
            }
        ]
    },
    "end_date": "2017-12-31T23:59:00Z",
    "id": "urn:authenticateit:participant:576318441844504:todo_cards:deliveries:868309185919644",
    "name": "End of year delivery",
    "owner": "urn:authenticateit:participant:576318441844504",
    "products": [
        "09212345000152"
    ],
    "start_date": "2017-12-24T00:00:00Z",
    "status": "inactive"
}

Update Delivery

Endpoint for owner participant to update a ToDo card delivery. Takes JSON object containing delivery parameters (see endpoint for delivery creation). Responds with updated delivery representation.

To update ToDo card data (such as steps, result, etc.) either use parameter card or card_id. Parameter card must be a JSON object containing ToDo card data (see endpoint for ToDo card creation). If card_id is used instead, card data will be copied from the specified card.

Current participant must be delivery owner.

PUT /todocards-service/deliveries/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Card delivery id
Example Request
{
  "name": "Prolonged end of year delivery",
  "end_date": "2018-01-15T23:59:59Z",
  "card": {
    "name": "Card 1 New Name",
  }
}
Example Response
{
  "name": "Prolonged end of year delivery",
  "start_date": "2017-12-24T00:00:00Z",
  "end_date": "2018-01-15T23:59:59Z",
  "budget": "123000000000000",
  "card": {
    "name": "Card 1 New Name",
    "icon": "action",
    "description": "Descr 1",
    "result": {
      "coins": "10000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ]
  },
  "products": [
    "99336097001625",
    "99336097000833"
  ],
  "audience": {
    "countries": [
      "036",
      "643"
    ],
    "languages": [
      "en",
      "ru"
    ],
    "min_age": 25,
    "max_age": 30,
    "gender": "male",
    "registration_methods": [
      "email",
      "facebook"
    ],
    "weekly_scans": {
      "from": 15,
      "to": 30
    },
    "scan_countries": [
      "036",
      "643"
    ]
  },
  "id": "todo-card-delivery-id-1231241231",
  "owner": "participant-id-1231298967123"
}

Delete Delivery

Endpoint to delete existing ToDo card delivery by id. Current participant must be delivery and card owner.

DELETE /todocards-service/deliveries/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Card delivery id

List Deliveries

List participant's ToDo card deliveries. Accepts offset (skip specified number of deliveries; 0 by default) and limit (limit the number of returned deliveries; 100 by default) query parameters. Responds with a list of card delivery representations.

GET /todocards-service/deliveries
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
offset number Skip specified number of deliveries
limit number Limit the number of returned deliveries
Example Response
[
  {
    "name": "Delivery 1",
    "start_date": "2017-12-24T00:00:00Z",
    "budget": "123000000000000",
    "card": {
      "name": "Card 1 New Name",
      "icon": "action",
      "description": "Descr 1",
      "result": {
        "coins": "10000000000000"
      },
      "steps": [
        {
          "type": "text",
          "text": "Step 1 text."
        }
      ]
    },
    "audience": {
      "countries": [
        "036",
        "643"
      ],
      "min_age": 18
    },
    "id": "todo-card-delivery-id-1231241231",
    "owner": "participant-id-1231298967123"
  },
  {
    "name": "Delivery 2",
    "start_date": "2018-02-01T00:00:00Z",
    "budget": "55000000000000",
    "card": {
      "name": "Card 123",
      "icon": "action",
      "description": "Some Descr",
      "result": {
        "coins": "50000000000000"
      },
      "steps": [
        {
          "type": "text",
          "text": "Step 1 text."
        }
      ]
    },
    "audience": {
      "countries": [
        "036"
      ],
      "min_age": 25
    },
    "id": "todo-card-delivery-id-1299999999",
    "owner": "participant-id-1231298967123"
  }
]

Update delivery status

Endpoint to update status of existing ToDo card delivery (with status "inactive") by id to "pending-active". Current participant must be delivery and card owner.

PUT /todocards-service/deliveries/status/:id
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string Required: Card delivery id
status string "active" or "inactive"
Example Response
{
  "name": "Prolonged end of year delivery",
  "start_date": "2017-12-24T00:00:00Z",
  "end_date": "2018-01-15T23:59:59Z",
  "budget": "123000000000000",
  "card": {
    "name": "Card 1 New Name",
    "icon": "action",
    "description": "Descr 1",
    "result": {
      "coins": "10000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ]
  },
  "products": [
    "99336097001625",
    "99336097000833"
  ],
  "audience": {
    "countries": [
      "036",
      "643"
    ],
    "languages": [
      "en",
      "ru"
    ],
    "min_age": 25,
    "max_age": 30,
    "gender": "male",
    "registration_methods": [
      "email",
      "facebook"
    ],
    "weekly_scans": {
      "from": 15,
      "to": 30
    },
    "scan_countries": [
      "036",
      "643"
    ]
  },
  "id": "todo-card-delivery-id-1231241231",
  "status" : "active",
  "owner": "participant-id-1231298967123"
}

User Cards

These endpoints do not require todo_cards_supervisor role and are accessible by ordinary users.

Dismiss Delivered Card

Endpoint for user to dismiss suggested ToDo card. Card status will be changed to dismissed, response will be empty.

PUT /todocards-service/cards/considered/:id/dismiss
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string User card identifier

Complete Delivered Card

Endpoint for user to complete suggested ToDo card. Takes JSON object containing steps field (non-empty list of completed ToDo card steps). The response will be empty.

If card has auto_approve feature, user card status will be changed to completed and user will be rewarded according to the card result. Otherwise user card status will be changed to under_review and completed card will require a review from participant's ToDo cards supervisor.

The list of completed steps must align with the steps in the original card. Both lists must have the same length, corresponding list elements must have the same step type.

Step of type text doesn't require any actions to be completed. It must be at the same position in the completed steps list and must have the same step type text.

Step of type textbox must have text field (textbox contents).

Step of type rating must have rating field (rating by user, integer number from 1 to 5).

Step of type question must have answer_index field (index of the answer choosen by user, starting from 0).

Step of type image must have url field (URL of the uploaded image).

PUT /todocards-service/cards/considered/:id/complete
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string User card identifier
Example Request
{
  "steps": [
    {
      "type": "text"
    },
    {
      "type": "rating",
      "rating": 4
    },
    {
      "type": "question",
      "answer_index": 1
    },
    {
      "type": "image",
      "url": "https://cdn.shping.com/2018/01/22/xyz.jpg"
    },
    {
      "type": "textbox",
      "text": "None of your business."
    }
  ]
}

List Delivered Cards

List ToDo cards suggested to the user. Accepts status parameter to filter returned cards by their status (dismissed, under_review, completed or rejected).

GET /todocards-service/cards/considered
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
status string Filter returned cards by status
Example Response
[
  {
    "name": "Card 1",
    "icon": "action",
    "description": "Descr 1",
    "result": {
      "coins": "10000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "user-id-1~todo-card-id-1",
    "owner": "participant-id-1",
    "status": null
  },
  {
    "name": "Card 2",
    "icon": "action",
    "description": "Descr 2",
    "result": {
      "coins": "20000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "user-id-1~todo-card-id-2",
    "owner": "participant-id-1",
    "status": "dismissed"
  }
]

User Card Reviews

These endpoints require todo_cards_supervisor role from participant.

List Unreviewed User Completed Cards

List ToDo cards completed by the users and requiring a review. Accepts offset (skip specified number of cards; 0 by default) and limit (limit the number of returned cards; 100 by default) query parameters.

GET /todocards-service/cards/unreviewed
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
offset number Skip specified number of cards
limit number Limit the number of returned cards
Example Response
[
  {
    "name": "Card 1",
    "icon": "action",
    "description": "Descr 1",
    "result": {
      "coins": "10000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "user-id-1~todo-card-id-1",
    "owner": "participant-id-1",
    "status": "under_review"
  },
  {
    "name": "Card 2",
    "icon": "action",
    "description": "Descr 2",
    "result": {
      "coins": "20000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "user-id-1~todo-card-id-2",
    "owner": "participant-id-1",
    "status": "under_review"
  }
]

Reject User Completed Card

Endpoint for ToDo card supervisor to reject completed ToDo card. Card status will be changed to rejected, response will be empty.

PUT /todocards-service/cards/unreviewed/:id/reject
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string User card identifier

Approve User Completed Card

Endpoint for ToDo card supervisor to approve completed ToDo card. User card status will be changed to completed and user will be rewarded according to the card result. The response will be empty.

PUT /todocards-service/cards/unreviewed/:id/approve
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
id string User card identifier

List Approved User Completed Cards

List ToDo cards completed by the users and approved by participant. Accepts offset (skip specified number of cards; 0 by default) and limit (limit the number of returned cards; 100 by default) query parameters.

GET /todocards-service/cards/approved
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
offset number Skip specified number of cards
limit number Limit the number of returned cards
Example Response
[
  {
    "name": "Card 11",
    "icon": "action",
    "description": "Descr 11",
    "result": {
      "coins": "11000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "user-id-1~todo-card-id-11",
    "owner": "participant-id-1",
    "status": "completed"
  }
]

List Rejected User Completed Cards

List ToDo cards completed by the users and rejected by participant. Accepts offset (skip specified number of cards; 0 by default) and limit (limit the number of returned cards; 100 by default) query parameters.

GET /todocards-service/cards/rejected
Parameters
Name Type Description
authenticateit_identity_ticket header Required: Session's ticket
offset number Skip specified number of cards
limit number Limit the number of returned cards
Example Response
[
  {
    "name": "Card 21",
    "icon": "action",
    "description": "Descr 21",
    "result": {
      "coins": "21000000000000"
    },
    "steps": [
      {
        "type": "text",
        "text": "Step 1 text."
      }
    ],
    "id": "user-id-1~todo-card-id-21",
    "owner": "participant-id-1",
    "status": "rejected"
  }
]

results matching ""

    No results matching ""