Skip to content

Product

A product is the central object when we talk about the portfolio, this object contains descriptive information about the SKU (Stock Keeping Unit) that will be made available.

SKU (Stock Keeping Unit)

When we talk about product, we are talking about a term that can be easily confused, since its use is very wide in the market, being able to deal with a single product, a product with several variations, advertisements, offers, etc. When we are talking about the product in the Portfolio solution, we will be dealing more with the SKU itself, but what is the SKU?

The SKU, acronym for Stock Keeping Unit, is a unique identifier of a product and can also be used to identify the product unit in stocks. An example of a SKU would be a t-shirt, we can identify this product unit by its color and size, generating a SKU such as: T_SHIRT_WHITE_P.

Product variation

In the real world we know that we can have a product with different variations, that is, taking any t-shirt as an example we will be able to have its variations in sizes S, M or L. With that in mind, we provide in our solution a field called variation_key that serves to tie products with their variations.

The variation key can be any one that is unique to that variation. Returning to the T-shirts example, we could use a variation_key such as SHIRT_PMG and all SKUs that belong to the variation should reference that same variation_key, so it is recommended to enjoy a good experience of the entire solution.

Create a product position

Describe a product that will be made available in the portfolio.

Warning

When creating a product, you will receive the code 201 - Created. If the same UUID is sent as a parameter in the URL, the return code must be 303 - See Other. If you are receiving the code 200 - OK it is because the redirect is being performed automatically, but the product has not been updated. For more information, see Return Codes.

Required scope

Value Description
open:portfolio:write Allows manage SKUs

URL parameters

Field Type Description Required
id uuid4 Product identification Yes

Query parameters

Property Type Description Required Size
code string Product SKU code. Yes Min 1 character. Max 50 characters.
title object Object containing the title in different languages. Yes -
title.{language} string SKU title, language needs to follow the ISO 639-1/2 standard (e.g., en_US). Yes Min 1 character. Max 150 characters.
variation_key string Parent SKU code. When there is no value, you can send ''. Yes Max 50 characters.
condition enum SKU condition. Only the following values are accepted:
  • new
  • used
  • remanufactured
 Yes -
brand string Product brand. Yes Min 1 character. Max 70 characters.
tags array SKU keywords. When there is no value, you can send []. Yes Min 1 character. Max 100 characters per tag.
available boolean Availability of the publication. Yes -
origin enum Product origin. Accepted values are:
  • national
  • imported
 Yes -
datasheet object Product technical data sheets. When there is no value, you can send {}. Yes -
datasheet.reference URL Reference URL for the datasheet No -
dimensions array Product dimensions, more information Yes -
dimensions[].name enum Dimension name. The following values are accepted:
  • product
  • package
 Yes -
dimensions[].height object Height Yes -
dimensions[].height.value float Height value Yes Min 1 character. Max 10 characters.
dimensions[].height.unit enum Height unit. The following values are accepted:
  • cm - centimeters
  • m - meters
 Yes -
dimensions[].width object Width Yes -
dimensions[].width.value float Width value Yes Min 1 character. Max 10 characters.
dimensions[].width.unit enum Width unit. The following values are accepted:
  • cm - centimeters
  • m - meters
 Yes -
dimensions[].length object Length Yes -
dimensions[].length.value float Length value Yes Min 1 character. Max 10 characters.
dimensions[].length.unit enum Length unit. The following values are accepted:
  • cm - centimeters
  • m - meters
 Yes -
dimensions[].weight object Weight Yes -
dimensions[].weight.value float Weight value Yes Min 1 character. Max 10 characters.
dimensions[].weight.unit enum Weight unit. The following values are accepted:
  • g - grams
  • kg - kilograms
 Yes -
description object Object containing the product description in different languages. When there is no value, you can send {}. Yes -
description.{language} string Product description, language needs to follow the ISO 639-1/2 standard (e.g., en_US). No -
description.{language}.verbose_value string Verbose product description. Yes Min 1 character.
description.{language}.simplified_value string Simplified product description. When there is no value, you can send ''. No Max 1000 characters.
identifiers array Product identifiers. When there is no value, you can send []. Yes -
identifiers[].type enum Identifier type. The number of digits will be validated for the following types:
  • EAN
  • ISBN
  • UPC
  • NCM

You can send a value not on this list, but the numbering will not be validated.		 No Min 1 character.
identifiers[].value string Identifier value. The number of digits will be validated for identifier types. No EAN - 8, 12, 13 or 14 digits
ISBN - 13 digits
UPC - 8 or 12 digits
NCM - 8 or 10 digits
attributes object Product attributes. When there is no value, you can send {}. Yes -
attributes.variant array Product variant attributes. When there is no value, you can send []. No -
attributes.variant[].name string Variant attribute name No Min 1 character.
attributes.variant[].value string Variant attribute value No Min 1 character.
attributes.variant[].display object Object containing the display value for the attribute in different languages. When there is no value, you can send {}. No -
attributes.variant[].display.{language} string Value to display for the attribute, language needs to follow the ISO 639-1/2 standard (e.g., en_US). No -
attributes.variant[].display.{language}.name string Attribute variant name to be displayed No Min 1 character.
attributes.variant[].display.{language}.value string Attribute variant value to be displayed No Min 1 character.
attributes.variant[].display.{language}.simplified_value string Simplified attribute variant value to be displayed. When there is no value, you can send ''. No -
attributes.optional array Optional product attributes. When there is no value, you can send []. No -
attributes.optional[].name string Optional attribute name No Min 1 character.
attributes.optional[].value string Optional attribute value No Min 1 character.
attributes.optional[].display object Object containing the display value for the optional attribute in different languages. When there is no value, you can send {}. No -
attributes.optional[].display.{language} string Value to display for the attribute, language needs to follow the ISO 639-1/2 standard (e.g., en_US). No -
attributes.optional[].display.{language}.name string Optional attribute name to be displayed No Min 1 character.
attributes.optional[].display.{language}.value string Optional attribute value to be displayed No Min 1 character.
attributes.optional[].display.{language}.simplified_value string Simplified optional attribute value to be displayed. When there is no value, you can send ''. No -
medias array Product media. When there is no value, you can send []. Yes -
medias[].name string Media name No Min 1 character. Max 50 characters.
medias[].type string Media type No Min 1 character.
medias[].reference URL Media reference URL No -
extras object Additional information about the SKU. When there is no value, you can send {}. Yes -

Informative

The dimensions field is a list of items with their respective dimensions. And it is necessary that one of these items is the package. To do this enter package in the name key and specify the values for height, width, length and weight. 

{
  "dimensions": [
    {
      "name": "package",
      "height": {
        "value": 120,
        "unit": "cm"
      },
      "width": {
        "value": 100,
        "unit": "cm"
      },
      "length": {
        "value": 110,
        "unit": "cm"
      },
      "weight": {
        "value": 170,
        "unit": "g"
      }
    }
  ]
}

Request:

curl -X 'PUT' \
  'https://api.magalu.com/v0/portfolios/skus/{id}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "123-abc-4",
  "title": {
    "pt_BR": "O que a vida me ensinou"
  },
  "variation_key": "123-abc-4",
  "condition": "new",
  "brand": "apple",
  "datasheet": {
    "reference": "https://api.magalu.com/datasheets/97885021802085cb3e35b-a497-3d6e-a8a7-4fa34b024c45"
  },
  "description": {
    "pt_BR": {
      "verbose_value": "No sexto livro da Coleção O que a vida me ensinou",
      "simplified_value": "No sexto livro da Coleção O que a vida me ensinou..."
    }
  },
  "tags": [
    "auto-ajuda",
    "negocios"
  ],
  "dimensions": [
    {
      "name": "package",
      "height": {
        "value": 120,
        "unit": "cm"
      },
      "width": {
        "value": 100,
        "unit": "cm"
      },
      "length": {
        "value": 110,
        "unit": "cm"
      },
      "weight": {
        "value": 170,
        "unit": "g"
      }
    },
    {
      "name": "product",
      "height": {
        "value": 120,
        "unit": "cm"
      },
      "width": {
        "value": 100,
        "unit": "cm"
      },
      "length": {
        "value": 110,
        "unit": "cm"
      },
      "weight": {
        "value": 170,
        "unit": "g"
      }
    }
  ],
  "identifiers": [
    {
      "type": "ean",
      "value": "7891118012282"
    }
  ],
  "attributes": {
    "variant": [
      {
        "name": "color",
        "value": "white",
        "display": {
          "pt_BR": {
            "name": "Cor",
            "value": "Branco",
            "simplified_value": "Branco"
          }
        }
      },
      {
        "name": "internal_memory",
        "value": "256gb",
        "display": {
          "pt_BR": {
            "name": "Memória interna",
            "value": "256GB",
            "simplified_value": "Memória interna"
          }
        }
      }
    ],
    "optional": [
      {
        "name": "processor",
        "value": "a14",
        "display": {
          "pt_BR": {
            "name": "Processador",
            "value": "A14",
            "simplified_value": "Processador"
          }
        }
      },
      {
        "name": "operational_system",
        "value": "ios",
        "display": {
          "pt_BR": {
            "name": "Sistema operacional",
            "value": "iOS",
            "simplified_value": "Sistema operacional"
          }
        }
      }
    ]
  },
  "medias": [
    {
      "name": "book_cover_1",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "book_cover_2",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "book_cover_3",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "author_interview",
      "type": "embedded",
      "reference": "https://youtube.com/watch?v=deadbeef"
    }
  ],
  "available": true,
  "origin": "national",
  "extras": {}
}'

Response:

{
  "id": "a11d50a5-31c1-4e9d-bbe3-27a59f944508",
  "created_at": "2022-06-15T14:25:37Z",
  "code": "123-abc-4",
  "title": {
    "pt_BR": "O que a vida me ensinou"
  },
  "variation_key": "123-abc-4",
  "condition": "new",
  "brand": "apple",
  "datasheet": {
    "reference": "https://api.magalu.com/datasheets/97885021802085cb3e35b-a497-3d6e-a8a7-4fa34b024c45"
  },
  "description": {
    "pt_BR": {
      "verbose_value": "No sexto livro da Coleção O que a vida me ensinou",
      "simplified_value": "No sexto livro da Coleção O que a vida me ensinou..."
    }
  },
  "tags": [
    "auto-ajuda",
    "negocios"
  ],
  "dimensions": [
    {
      "name": "package",
      "height": {
        "value": 120,
        "unit": "cm"
      },
      "width": {
        "value": 100,
        "unit": "cm"
      },
      "length": {
        "value": 110,
        "unit": "cm"
      },
      "weight": {
        "value": 170,
        "unit": "g"
      }
    },
    {
      "name": "product",
      "height": {
        "value": 120,
        "unit": "cm"
      },
      "width": {
        "value": 100,
        "unit": "cm"
      },
      "length": {
        "value": 110,
        "unit": "cm"
      },
      "weight": {
        "value": 170,
        "unit": "g"
      }
    }
  ],
  "identifiers": [
    {
      "type": "ean",
      "value": "7891118012282"
    }
  ],
  "attributes": {
    "variant": [
      {
        "name": "color",
        "value": "white",
        "display": {
          "pt_BR": {
            "name": "Cor",
            "value": "Branco",
            "simplified_value": "Branco"
          }
        }
      },
      {
        "name": "internal_memory",
        "value": "256gb",
        "display": {
          "pt_BR": {
            "name": "Memória interna",
            "value": "256GB",
            "simplified_value": "Memória interna"
          }
        }
      }
    ],
    "optional": [
      {
        "name": "processor",
        "value": "a14",
        "display": {
          "pt_BR": {
            "name": "Processador",
            "value": "A14",
            "simplified_value": "Processador"
          }
        }
      },
      {
        "name": "operational_system",
        "value": "ios",
        "display": {
          "pt_BR": {
            "name": "Sistema operacional",
            "value": "iOS",
            "simplified_value": "Sistema operacional"
          }
        }
      }
    ]
  },
  "medias": [
    {
      "name": "book_cover_1",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "book_cover_2",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "book_cover_3",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "author_interview",
      "type": "embedded",
      "reference": "https://youtube.com/watch?v=deadbeef"
    }
  ],
  "available": true,
  "origin": "national",
  "extras": {}
}

Return code

Note

For more information about status code see Return code

Code Description
201 Created
303 See Other
401 Unauthorized
403 Forbidden
422 Unprocessable Entity
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Update a product position

In the portfolio we use two fields that deserve attention when updating a product position, the code and the id. The code represents the SKU code, it is permanent. The id is the SKU identifier and can be changed. It is important not to confuse them in the process of updating an SKU position. To guarantee the traceability of all changes in the information of a SKU, the system does not allow the data of a record to be altered, that is, whenever you need to make any changes to a SKU, you need to create a new SKU record. We can then have multiple records under a single SKU. These records have different id but the same code. The current registration will be the most recent one.

Retrieve a product

Return a specific product.

Required scope

Value Description
open:portfolio:read Allows access to a SKU

URL parameters

Field Type Description Required
id uuid4 Product identification Yes

Request:

curl -X 'GET' \
  'https://api.magalu.com/v0/portfolios/skus/{id}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \

Response:

{
  "id": "a11d50a5-31c1-4e9d-bbe3-27a59f944508",
  "created_at": "2022-06-15T14:25:37Z",
  "code": "123-abc-4",
  "title": {
    "pt_BR": "O que a vida me ensinou"
  },
  "variation_key": "123-abc-4",
  "condition": "new",
  "brand": "apple",
  "datasheet": {
    "reference": "https://api.magalu.com/datasheets/97885021802085cb3e35b-a497-3d6e-a8a7-4fa34b024c45"
  },
  "description": {
    "pt_BR": {
      "verbose_value": "No sexto livro da Coleção O que a vida me ensinou",
      "simplified_value": "No sexto livro da Coleção O que a vida me ensinou..."
    }
  },
  "tags": [
    "auto-ajuda",
    "negocios"
  ],
  "dimensions": [
    {
      "name": "package",
      "height": {
        "value": 120,
        "unit": "cm"
      },
      "width": {
        "value": 100,
        "unit": "cm"
      },
      "length": {
        "value": 110,
        "unit": "cm"
      },
      "weight": {
        "value": 170,
        "unit": "g"
      }
    },
    {
      "name": "item",
      "height": {
        "value": 120,
        "unit": "cm"
      },
      "width": {
        "value": 100,
        "unit": "cm"
      },
      "length": {
        "value": 110,
        "unit": "cm"
      },
      "weight": {
        "value": 170,
        "unit": "g"
      }
    }
  ],
  "identifiers": [
    {
      "type": "isbn",
      "value": "9788502180208"
    },
    {
      "type": "isbn_10",
      "value": "8502180207"
    },
    {
      "type": "isbn_13",
      "value": "9788502180208"
    },
    {
      "type": "gtin_13",
      "value": "9788502180208"
    },
    {
      "type": "moid",
      "value": "089099300"
    }
  ],
  "attributes": {
    "variant": [
      {
        "name": "color",
        "value": "white",
        "display": {
          "pt_BR": {
            "name": "Cor",
            "value": "Branco",
            "simplified_value": "Branco"
          }
        }
      },
      {
        "name": "internal_memory",
        "value": "256gb",
        "display": {
          "pt_BR": {
            "name": "Memória interna",
            "value": "256GB",
            "simplified_value": "Memória interna"
          }
        }
      }
    ],
    "optional": [
      {
        "name": "brand",
        "value": "apple",
        "display": {
          "pt_BR": {
            "name": "Marca",
            "value": "Apple",
            "simplified_value": "Marca"
          }
        }
      },
      {
        "name": "processor",
        "value": "a14",
        "display": {
          "pt_BR": {
            "name": "Processador",
            "value": "A14",
            "simplified_value": "Processador"
          }
        }
      },
      {
        "name": "operational_system",
        "value": "ios",
        "display": {
          "pt_BR": {
            "name": "Sistema operacional",
            "value": "iOS",
            "simplified_value": "Sistema operacional"
          }
        }
      }
    ]
  },
  "medias": [
    {
      "name": "book_cover_1",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "book_cover_2",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "book_cover_3",
      "type": "image/jpeg",
      "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
    },
    {
      "name": "author_interview",
      "type": "embedded",
      "reference": "https://youtube.com/watch?v=deadbeef"
    }
  ],
  "available": true,
  "origin": "national",
  "extras": {}
}

Return code

Note

For more information about status code see Return code

Code Description
200 Ok
401 Unauthorized
403 Forbidden
404 Not Found
422 Unprocessable Entity
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Retrieve a product list

Returns all available products.

Note

This endpoint implements pagination, sorting and filters. To learn more, refer to Make paginated requests and query parameters.

Required scope

Value Description
open:portfolio:read Allows list to SKUs

Query parameters

Field Type Description Required
code__in string Returns the products with the listed codes No
variation_key string Returns the product variations of a binding No
variation_key__in string Returns the product variations of multiple bindings No

Sort parameters

Field Description Required
created_at Sort skus by creation date. No

Request:

curl -X 'GET' \
  'https://api.magalu.com/v0/portfolios/skus' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \

Response:

{
  "meta": {
    ...
  },
  "results": [
    {
      "id": "a11d50a5-31c1-4e9d-bbe3-27a59f944508",
      "created_at": "2022-06-15T14:25:37Z",
      "code": "123-abc-4",
      "title": {
        "pt_BR": "O que a vida me ensinou"
      },
      "variation_key": "123-abc-4",
      "condition": "new",
      "medias": [
        {
          "name": "book_cover_1",
          "type": "image/jpeg",
          "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
        },
        {
          "name": "book_cover_2",
          "type": "image/jpeg",
          "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
        },
        {
          "name": "book_cover_3",
          "type": "image/jpeg",
          "reference": "https://api.magalu.com/livro-o-que-a-vida/8cb51075ef9143001982f2914180fc0b.jpg"
        },
        {
          "name": "author_interview",
          "type": "embedded",
          "reference": "https://youtube.com/watch?v=deadbeef"
        }
      ]
    }
  ]
}

Return code

Note

For more information about status code see Return code

Code Description
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
422 Unprocessable Entity
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout