Ir para o conteúdo

Produtos

Um produto é o objeto central quando falamos do portfólio, esse objeto contém informações descritivas a respeito do SKU (Stock Keeping Unit) que será disponibilizado.

SKU (Stock Keeping Unit)

Quando falamos de produto estamos falando de um termo que pode ser facilmente confundido, já que sua utilização é bem ampla no mercado, podendo tratar de um único produto, um produto com várias variações, anúncios, ofertas, etc. Quando estivermos falando de produto na solução Portfólio, estaremos tratando mais do SKU em sí, mas o que é o SKU?

O SKU, sigla para Stock Keeping Unit, se trata de um identificador único de um produto e também pode ser utilizado para identificação da unidade de produto nos estoques. Um exemplo de SKU seria de uma camiseta, podemos identificar essa unidade de produto pela sua cor e seu tamanho gerando um SKU como por exemplo: CAMISETA_BRANCA_P.

Variação de produtos

No mundo real sabemos que podemos ter um produto com diferentes variações, ou seja, pegando como exemplo uma camiseta qualquer vamos poder ter as variações dela em tamanhos P, M ou G. Pensando nisso disponibilizamos na nossa solução um campo chamado de variation_key que serve para amarrar produtos com suas variações.

A chave de variação pode ser qualquer uma desde que seja única para aquela variação. Retornando ao exemplo das camisetas, poderiamos utilizar um variation_key como por exemplo CAMISETAS_PMG e todos os SKUs que pertencerem à variação deveriam referenciar esse mesmo variation_key, assim é recomendado para que seja possível usufruir de uma boa experiência de toda a solução.

Criar uma posição de produto

Descrever um produto que será disponibilizado no portfólio.

Aviso

Ao criar um produto, você receberá o código 201 - Created. Caso seja enviado o mesmo UUID como parâmetro na URL, o retorno deverá ser o código 303 - See Other. Se você estiver recebendo o código 200 - OK é porque está sendo realizado o redirecionamento automático, mas o produto não foi atualizado. Para mais informações, consulte Códigos de retorno.

Escopo requerido

Valor Descrição
open:portfolio:write Permite gerenciar os SKUs

Parâmetros da URL

Campo Tipo Descrição Obrigatório
id uuid4 Identificação do produto Sim

Parâmetros da chamada

Propriedade Tipo Descrição Obrigatório Tamanho
code string Código SKU do produto. Sim Min 1 carácter.
Max 50 caracteres.
title object Objeto contendo o título em diferentes linguas. Sim -
title.{language} string Título do SKU, language precisa precisa seguir o padrão ISO 639-1/2 (ex. pt_BR) Sim Min 1 carácter.
Max 150 caracteres.
variation_key string Código do SKU pai. Quando não houver um valor você poderá enviar ''. Sim Max 50 caracteres.
condition enum Condição do SKU. Somente são aceitos os valores:
  • new
  • used
  • remanufactured
 Sim -
brand string Marca do produto. Sim Min 1 carácter.
Max 70 caracteres.
tags array Palavras chaves do SKU. Quando não houver um valor você poderá enviar []. Sim Min 1 carácter.
Max 100 caracteres (por tag).
available boolean Disponibilidade da publicação. Sim -
origin enum Origem do produto. Os valores aceitos são:
  • national
  • imported
.		 Sim -
datasheet object Fichas técnicas do produto. Quando não houver um valor você poderá enviar {}. Sim -
datasheet.reference URL URL referente à ficha técnica Não -
dimensions array Dimensões do produto, mais informações Sim -
dimensions[].name enum Nome da dimensão. Serão Aceito os seguintes valores:
  • product
  • package
 Sim -
dimensions[].height object Altura Sim -
dimensions[].height.value float Valor da altura Sim Min 1 carácter.
Max 10 caracteres.
dimensions[].height.unit enum Unidade da altura. Serão Aceito os seguintes valores:
  • cm - centímetros
  • m - metros
 Sim -
dimensions[].width object Largura Sim -
dimensions[].width.value float Valor da largura Sim Min 1 carácter.
Max 10 caracteres.
dimensions[].width.unit enum Unidade da largura. Serão Aceito os seguintes valores:
  • cm - centímetros
  • m - metros
 Sim -
dimensions[].length object Comprimento Sim -
dimensions[].length.value float Valor do comprimento Sim Min 1 carácter.
Max 10 caracteres.
dimensions[].length.unit enum Unidade do comprimento. Serão Aceito os seguintes valores:
  • cm - centímetros
  • m - metros
 Sim -
dimensions[].weight object Peso Sim -
dimensions[].weight.value float Valor do peso Sim Min 1 carácter.
Max 10 caracteres.
dimensions[].weight.unit enum Unidade do peso. Serão Aceito os seguintes valores:
  • g - gramas
  • kg - kilograma
 Sim -
description object Objeto contendo a descrição do produto em diferentes linguas. Quando não houver um valor você poderá enviar {}. Sim -
description.{language} string Descrição do produto, language precisa precisa seguir o padrão ISO 639-1/2 (ex. pt_BR) Não -
description.{language}.verbose_value string Descrição verbosa do produto. Não Min 1 carácter
description.{language}.simplified_value string Descrição simplificada do produto. Quando não houver um valor você poderá enviar '' Não Max 1000 caracteres.
identifiers array Identificadores do produto. Quando não houver um valor você poderá enviar []. Sim -
identifiers[].type enum Tipo do identificador. Será validado a quantidade de números dos seguintes tipos:
  • EAN
  • ISBN
  • UPC
  • NCM

É permitido enviar um valor que não está nesta lista, porém não será validada a numeração.		 Não Min 1 carácter.
identifiers[].value string Valor do identificador. Será validado a quantidade de números dos tipos de identificadores. Não EAN - 8, 12, 13 ou 14 números
ISBN - 13 números
UPC - 8 ou 12 números
NCM - 8 ou 10 números
attributes object Atributos do produto. Quando não houver um valor você poderá enviar {}. Sim -
attributes.variant array Atributos variante do produto. Quando não houver um valor você poderá enviar []. Não -
attributes.variant[].name string Nome variante do atributo Não Min 1 carácter.
attributes.variant[].value string Valor variante do atributo Não Min 1 carácter.
attributes.variant[].display object Objeto contendo o valor para exibir do atributo em diferentes linguas. Quando não houver um valor você poderá enviar {}. Não -
attributes.variant[].display.{language} string Valor para exibir do atributo, language precisa precisa seguir o padrão ISO 639-1/2 (ex. pt_BR) Não -
attributes.variant[].display.{language}.name string Nome variante do atributo a ser exibido Não Min 1 carácter.
attributes.variant[].display.{language}.value string Valor variante do atributo a ser exibido Não Min 1 carácter.
attributes.variant[].display.{language}.simplified_value string Valor variante simplificado do atributo a ser exibido. Quando não houver um valor você poderá enviar ''. Não -
attributes.optional array Atributos opcionais do produto. Quando não houver um valor você poderá enviar []. Não -
attributes.optional[].name string Nome opcional do atributo Não Min 1 carácter.
attributes.optional[].value string Valor opcional do atributo Não Min 1 carácter.
attributes.optional[].display object Objeto contendo o valor para exibir do atributo em diferentes linguas. Quando não houver um valor você poderá enviar {}. Não -
attributes.optional[].display.{language} string Valor para exibir do atributo, language precisa precisa seguir o padrão ISO 639-1/2 (ex. pt_BR) Não -
attributes.optional[].display.{language}.name string Nome opcional do atributo a ser exibido Não Min 1 carácter.
attributes.optional[].display.{language}.value string Valor opcional do atributo a ser exibido Não Min 1 carácter.
attributes.optional[].display.{language}.simplified_value string Valor opcional simplificado do atributo a ser exibido. Quando não houver um valor você poderá enviar '' Não -
medias array Mídias do produto. Quando não houver um valor você poderá enviar []. Sim -
medias[].name string Nome da mídia Não Min 1 carácter.
Max 50 caracteres.
medias[].type string Tipo da mídia Não Min 1 carácter.
medias[].reference URL URL de referência da mídia Não -
extras object Informações adicionais sobre o SKU. Quando não houver um valor você poderá enviar {}. Sim -

Informativo

O campo dimensions é uma lista de itens com as suas respectivas dimensões. E é necessário que um desses itens seja o pacote. Para isso informe package na chave name e especifique os valores para height, width, length e weight. 

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

Chamada:

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": {}
}'

Resposta:

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

Códigos de retorno

Nota

Para maiores informações sobre códigos de retorno, Código de retorno.

Código Descrição
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

Atualizar uma posição de produto

No portfólio usamos dois campos que merecem atenção ao atualizar uma posição de produto, o code e o id. O code representa o código do SKU, ele é permanente. O id é o identificador do SKU e pode ser modificado. É importante não confundi-los no processo de atualização de uma posição de SKU. Para garantir a rastreabilidade de todas as mudanças nas informações de um SKU, o sistema não permite que os dados de um registro sejam alterados, ou seja, sempre que precisar fazer alguma alteração de um SKU é necessário criar um novo registro do mesmo. Podemos ter então múltiplos registros sobre um único SKU. Estes registros tem id diferentes, mas o mesmo code. O registro vigente será o mais recente.

Recuperar um produto

Retornar um produto em específico.

Escopo requerido

Valor Descrição
open:portfolio:read Permite acessar um SKU

Parâmetros da URL

Campo Tipo Descrição Obrigatório
id uuid4 Identificação do produto Sim

Chamada:

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' \

Resposta:

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

Códigos de retorno

Nota

Para maiores informações sobre códigos de retorno, Código de retorno.

Código Descrição
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

Recuperar uma lista de produtos

Retorna todos os produtos disponíveis.

Nota

Este endpoint implementa paginação, ordenação e filtros. Para saber mais, consulte Fazer solicitações paginadas e parâmetros de consulta.

Escopo requerido

Valor Descrição
open:portfolio:read Permite listar os SKUs

Parâmetros de consulta

Campo Tipo Descrição Obrigatório
code__in string Retorna os produtos com os códigos listados Não
variation_key string Retorna as variações de produto de uma amarração Não
variation_key__in string Retorna as variações de produto de várias amarrações Não

Parâmetros de ordenação

Campo Descrição Obrigatório
created_at Ordernar por data de criação dos skus. Não

Chamada:

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

Resposta:

{
  "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",
      "brand": "apple",
      "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"
        }
      ]
    }
  ]
}

Códigos de retorno

Nota

Para maiores informações sobre códigos de retorno, Código de retorno.

Código Descrição
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