How to submit an Item

Note

To make your first API request, complete the initial setup by following the Get Started guide.

Summary

To submit an item, you'll need to:

Select a product by navigating through categories and brands
Select the desired option values for the product
Create a draft item with your selected product and option values
Submit protocol answers for the item's technical assessment
Submit user protocol answers with seller information
Mark the item as submitted to complete the process

1. Select the desired product

To find the available products, you will need to navigate through the categories and brands.

To know which categories are available, make a request to Core/categories.

This will return a response with the following information

{
  "label": "Category",
  "type": "category",
  "options": [
    {
      "id": 225,
      "value": "Smartphone",
      "references": [],
      "next_url": {
        "method": "GET",
        "url": "/api/v1/brands?category_id=225"
      },
      "image_url": null,
      "acceptance_settings": {
        "acceptable": true,
        "acceptable_online": true,
        "saleable_new": true,
        "can_trade_in": true
      }
    },
    {
      "id": 126,
      "value": "Smartwatch",
      "references": [
        "mobile",
        "wrist",
      ],
      "next_url": {
        "method": "GET",
        "url": "/api/v1/brands?category_id=126"
      },
      "image_url": "https://picsum.photos/200/300",
      "acceptance_settings": {
        "acceptable": true,
        "acceptable_online": true,
        "saleable_new": true,
        "can_trade_in": true,
        "allow_open_product": true,
        "allow_open_brand": true
      }
    },
  ],
  "pagy": {
    "count": 2,
    "page": 1,
    "pages": 1,
    "last": 1,
    "prev": null,
    "next": null,
    "items": 15
  }
}

After choosing a category, make a request to the corresponding next_url property.
If the base path is /api/v1/brands, then you will need to choose a brand, by making a request to Core/brands, using the id of the category as a filter.

This will return a response with the following information

{
  "label": "Brand",
  "type": "brand",
  "allow_creation": false,
  "category_id": "225",
  "options": [
    {
      "id": 9,
      "draft": false,
      "active": true,
      "value": "Phone Brand 1",
      "next_url": {
        "method": "GET",
        "url": "/api/v1/products?brand_id=9&category_id=225"
      },
      "image_url": null
    },
    {
      "id": 152,
      "draft": false,
      "active": true,
      "value": "Phone Brand 2",
      "next_url": {
        "method": "GET",
        "url": "/api/v1/products?brand_id=152&category_id=225"
      },
      "image_url": null
    }
  ]
}

The last step should be picking the product, by making a request to Core/products, using the brand and category ids as filters.

This will return a response with the following information

  {
    "label": "Product",
    "type": "product",
    "category_id": "225",
    "brand_id": "152",
    "allow_creation": false,
    "options": [
      {
        "id": 1072,
        "value": "Smartphone 1",
        "draft": false,
        "active": true,
        "references": [],
        "image_url": null,
        "acceptance_settings": {
          "acceptable": true,
          "acceptable_online": true,
          "saleable_new": false,
          "can_trade_in": true
        }
      },
      {
        "id": 1073,
        "value": "Smartphone 2",
        "draft": false,
        "active": true,
        "references": [],
        "acceptance_settings": {
          "acceptable": true,
          "acceptable_online": true,
          "saleable_new": false,
          "can_trade_in": false
        }
      }
    ]
  }

2. Select the desired option values

Now that you have chosen the product, you will need to choose the option values for each option type associated to that product.

Make a request to Core/optiontypes - make sure to set with_values as true to get the option values in a single request.

This will return a response with the following information

{
"label": "Option Type",
"type": "option_type",
"product_id": "1072",
"options": [
  {
    "id": 8,
    "slug": "option_type_8",
    "value": "Grade",
    "options": [
      {
        "id": 35,
        "name": "A"
      },
      {
        "id": 36,
        "name": "B"
      }
    ]
  },
  {
    "id": 10,
    "slug": "option_type_10",
    "value": "Color",
    "options": [
      {
        "id": 54,
        "name": "Green"
      },
      {
        "id": 55,
        "name": "Red"
      }
    ]
  }
]
}

Take note of the ids of each option value selected for each option type, (i.e. option value 54 for option type 10).

3. Create a draft item

Now that you have chosen your product, it is time to create the Draft item

To create the item, make a request to Core/item, with the product and option values selected.

This will return a response with an important field token, which will now become the identifier of the item for all next endpoints.

4. Submit the needed protocol answers

Request the protocol for the item

To get the protocol questions for your item, make a request to Core/items#protocol.

This will return a response with protocol elements that need to be answered.

 {
   "submit_url": "https://<core-base-url>/api/v1/items/<token>/protocol_answers",
   "items": [
     {
       "id": 208,
       "position": 1,
       "slug": "protocol_element_input_select_208",
       "required": false,
       "hint": null,
       "hint_icon": null,
       "hint_url": null,
       "hint_url_text": null,
       "label": "What is the grade of the item?",
       "label_html": "<p class=\"loopos-editor-paragraph loopos-ltr\" dir=\"ltr\"><span data-lexical-text=\"true\">Extra</span></p>",
       "autocomplete_type": "no-autocomplete",
       "placeholder": "Question",
       "type": "input:select",
       "default": null,
       "dropdown": null,
       "options": [
         {
           "id": 101,
           "label": "Very Good",
           "deal_breaker": false,
           "value": "101"
         },
         {
           "id": 102,
           "label": "Reasonable",
           "deal_breaker": false,
           "value": "102"
         }
       ]
     },
     {
       "id": 32,
       "position": 2,
       "slug": null,
       "required": false,
       "hint": null,
       "hint_icon": null,
       "hint_url": null,
       "hint_url_text": null,
       "label": "Any comments about the item?",
       "label_html": null,
       "autocomplete_type": "no-autocomplete",
       "placeholder": null,
       "type": "input:text",
       "default": null,
       "text_area": null
     },
   ]
 }

Submit answers to the protocol by making a POST request to Core/items#protocol_answers.

Example request body

{
  "protocol_answers_attributes": [
    {
      "protocol_element_id": 208,
      "value": "101"
    },
    {
      "protocol_element_id": 32,
      "value": "No."
    }
  ]
}

5. Submit the user protocol answers

Request the user protocol for the item by making a GET request to Core/items#user_protocol.

This will return a response with user information fields that need to be completed.

An example of response body is:

 {
   "submit_url": "https://<core-base-url>/api/v1/items/<token>/user_protocol_answers",
   "items": [
     {
       "id": 16,
       "position": 1,
       "slug": "full_name",
       "required": true,
       "hint": null,
       "hint_icon": null,
       "hint_url": null,
       "hint_url_text": null,
       "label": "Full name",
       "label_html": "<p class=\"loopos-editor-paragraph loopos-ltr\" dir=\"ltr\"><span data-lexical-text=\"true\">Full name</span></p>",
       "autocomplete_type": "name",
       "placeholder": null,
       "type": "input:text",
       "default": null,
       "text_area": null
     },
     {
       "id": 17,
       "position": 2,
       "slug": "email",
       "required": true,
       "hint": null,
       "hint_icon": null,
       "hint_url": null,
       "hint_url_text": null,
       "label": "Email",
       "label_html": "<p class=\"loopos-editor-paragraph loopos-ltr\" dir=\"ltr\"><span data-lexical-text=\"true\">Email</span></p>",
       "autocomplete_type": "email",
       "placeholder": null,
       "type": "input:text",
       "default": null,
       "text_area": null
     },
     {
       "id": 26,
       "position": 12,
       "slug": "terms_and_conditions",
       "required": true,
       "hint": null,
       "hint_icon": null,
       "hint_url": null,
       "hint_url_text": null,
       "label": "Terms and conditions",
       "label_html": "<p class=\"loopos-editor-paragraph loopos-ltr\" dir=\"ltr\"><span data-lexical-text=\"true\">Terms and conditions</span></p>",
       "autocomplete_type": "no-autocomplete",
       "placeholder": null,
       "type": "input:bool",
       "default": null,
       "label_url": null
     }
   ]
 }

Submit answers to the user protocol by making a POST request to Core/items#user_protocol_answers.

Example request body

{
  "protocol_answers_attributes": [
    {
      "protocol_element_id": 16,
      "value": "John Doe"
    },
    {
      "protocol_element_id": 17,
      "value": "john.doe@example.com"
    },
    {
      "protocol_element_id": 26,
      "value": true
    }
  ]
}

6. Mark the item as submitted

Once you have completed all the required steps (selecting a product, answering the protocol questions, and providing user information), you need to mark the item as submitted.

Make a POST request to Core/items#update.

;TODO: this will be changed to a better structure in the future.

This will return a response confirming the submission

{
  "extra_data": {
    "submission": {
      "state": "submitted"
    }
  }
}

After successful submission, the item will be processed according to your system's workflow. You can check the status of your item at any time by making a GET request to Core/item.

Summary​

1. Select the desired product​

2. Select the desired option values​

3. Create a draft item​

4. Submit the needed protocol answers​

5. Submit the user protocol answers​

6. Mark the item as submitted​

Summary

1. Select the desired product

2. Select the desired option values

3. Create a draft item

4. Submit the needed protocol answers

5. Submit the user protocol answers

6. Mark the item as submitted