Atualizar produtos e seus relacionamentos

Este endpoint é utilizado para atualizar um lote de produtos de uma vez. A atualização é realizada via o mesmo endpoint de criação (POST), que funciona como upsert — se o produto com o externalReference informado já existir, seus dados serão atualizados.

POST `/v1/batch/products`

Authorization: Basic Auth contendo a chave pública e secreta disponibilizadas para o cliente.
- Exemplo: Basic <base64-encoded-credentials>
x-contractAccountId: Identificador da conta do contrato do cliente.
- Exemplo: x-contractAccountId: 9f36a666-acd5-4987-a47f-3de247f65d82

Exemplo de Autorização

Para gerar o valor de Authorization, você precisa codificar suas credenciais (public_key:secret_key) em base64. Por exemplo, se sua chave pública for public_key e sua chave secreta for secret_key, você deve codificar public_key:secret_key em base64.

echo -n 'public_key:secret_key' | base64

Corpo da Requisição

O corpo da requisição deve ser uma lista de objetos de produtos, cada um contendo os seguintes campos:

Campo	Tipo	Nullable	Limite	Descrição
`externalReference`	string	Não	-	Referência externa do produto para rastreabilidade. Obrigatório para identificar o produto a ser atualizado
`name`	string	Não	120	Nome do produto. Máximo 120 caracteres
`similarTerms`	string	Sim	-	Termos similares para facilitar a busca separados por vírgula.
`slug`	string	Não	120	Slug único do produto. Máximo 120 caracteres
`title`	string	Não	60	Texto de exibição do produto. Máximo 60 caracteres
`shortDescription`	string	Não	160	Descrição breve do produto. Máximo 160 caracteres
`longDescription`	string	Não	-	Descrição longa do produto
`brandExternalReference`	string	Sim	30	Referência externa da marca já cadastrada. Máximo 30 caracteres
`categoryExternalReference`	string	Sim	30	Referência externa da categoria já cadastrada. Máximo 30 caracteres
`displayInSite`	bool	Não	-	Define se o produto será exibido no site
`displayInSoldOut`	bool	Não	-	Define se o produto será exibido quando esgotado
`fiscalCode`	string	Não	30	Código fiscal do produto. Máximo 30 caracteres
`EAN`	string	Sim	48	Código de barras EAN. Máximo 48 caracteres
`Punctuation`	int	Não	-	Pontuação do produto (deve ser ≥ 0)
`Characteristics`	string	Sim	-	Características descritivas do produto
`Active`	bool	Sim	-	Produto ativo/inativo
`SKUs`	array	Não	-	SKUs do produto a ser cadastrado. Os SKUs não enviados serão removidos

Campos dos SKUs

Campo	Tipo	Nullable	Limite	Descrição
`externalReference`	string	Não	-	Referência externa do SKU
`Name`	string	Não	120	Nome do SKU. Máximo 120 caracteres
`EAN`	string	Não	30	Código de barras EAN do SKU. Máximo 30 caracteres
`Reference`	string	Não	30	Referência interna do SKU. Máximo 30 caracteres
`WeightForFreight`	decimal	Não	-	Peso para cálculo de frete (deve ser > 0)
`HeightForFreight`	decimal	Não	-	Altura para cálculo de frete (deve ser > 0)
`WidthForFreight`	decimal	Não	-	Largura para cálculo de frete (deve ser > 0)
`LengthForFreight`	decimal	Não	-	Comprimento para cálculo de frete (deve ser > 0)
`WeightReal`	decimal	Não	-	Peso real do produto (deve ser > 0)
`HeightReal`	decimal	Não	-	Altura real do produto (deve ser > 0)
`WidthReal`	decimal	Não	-	Largura real do produto (deve ser > 0)
`LengthReal`	decimal	Não	-	Comprimento real do produto (deve ser > 0)
`ArrivalDate`	date	Não	-	Data de chegada do produto
`UnitOfMeasure`	int	Não	-	Unidade de medida (ver tabela abaixo)
`ArithmeticFactor`	decimal	Sim	-	Fator aritmético para cálculo de preço por peso
`ManufacturerCode`	string	Não	-	Código do fabricante
`Weight`	decimal	Sim	-	Peso do produto (deve ser > 0 se fornecido)
`MinimumWeightForSale`	decimal	Sim	-	Peso mínimo para venda (deve ser > 0 se fornecido)
`SkuPackageMinAmount`	int	Sim	-	Quantidade mínima do pacote (deve ser > 0 se fornecido)
`SkuPackageMaxAmount`	int	Sim	-	Quantidade máxima do pacote (deve ser > 0 se fornecido)
`ExhibitionBadge1`	string	Sim	15	Badge de exibição 1. Máximo 15 caracteres
`ExhibitionBadge2`	string	Sim	15	Badge de exibição 2. Máximo 15 caracteres
`ExhibitionBadge3`	string	Sim	15	Badge de exibição 3. Máximo 15 caracteres

Possíveis valores para `UnitOfMeasure`

Valor	Descrição
1	Unidade (Un)
2	Quilograma (Kg)
3	Grama (g)
4	Miligrama (Mg)

Exemplo de Corpo da Requisição

[
  {
    "externalReference": "1",
    "name": "Arroz branco",
    "similarTerms": "arroz, branco",
    "slug": "arroz-branco-prato-fino-1kg-431150",
    "title": "Arroz Branco Prato Fino 1kg",
    "shortDescription": "ARROZ B PRATO FINO 1KG",
    "longDescription": "Arroz Branco Prato Fino 1kg",
    "displayInSite": false,
    "displayInSoldOut": false,
    "fiscalCode": "1111111",
    "EAN": "7896891504153",
    "Punctuation": 1,
    "Characteristics": "Arroz branco tipo 1, grãos selecionados, pacote de 1kg",
    "Active": false,
    "brandExternalReference": null,
    "categoryExternalReference": "4",
    "SKUs": [
      {
        "externalReference": "10",
        "Name": "Arroz Branco Prato Fino 1kg",
        "EAN": "1234567890123",
        "Reference": "REF12345",
        "WeightForFreight": 1.5,
        "HeightForFreight": 10.0,
        "WidthForFreight": 5.0,
        "LengthForFreight": 20.0,
        "WeightReal": 1.4,
        "HeightReal": 9.8,
        "WidthReal": 4.9,
        "LengthReal": 19.8,
        "ArrivalDate": "2023-10-01",
        "ManufacturerCode": "MFG12345",
        "UnitOfMeasure": 2,
        "Weight": 1.5,
        "ArithmeticFactor": 2,
        "MinimumWeightForSale": 1.5,
        "SkuPackageMinAmount": 1,
        "SkuPackageMaxAmount": 3,
        "ExhibitionBadge1": "Promoção",
        "ExhibitionBadge2": "Novidade",
        "ExhibitionBadge3": "Frete Grátis"
      }
    ]
  }
]

Respostas

200: Retorna sucesso da operação. A resposta incluirá detalhes sobre o processamento da lista de produtos.
400: Retorna erro de requisição inválida. Isso geralmente ocorre devido a dados de entrada mal formatados, limites de caracteres excedidos ou campos obrigatórios faltando.
500: Retorna erro interno do servidor. Indica problemas no processamento da requisição no servidor.

Exemplo de Resposta para Sucesso (200)

{ "operationId": "402fe685-2060-432b-ac57-223eb2e680f3" }

Comportamento Especial para SKUs

⚠️ ATENÇÃO: Durante a atualização de produtos, os SKUs são tratados de forma especial:

SKUs enviados: Serão criados ou atualizados conforme necessário
SKUs não enviados: Serão removidos do produto
SKUs com erro: Gerarão webhooks de erro específicos (ProductWithSKUs_PartiallyFailed = 30)

Esta abordagem garante que o estado final dos SKUs no sistema corresponda exatamente ao que foi enviado na requisição de atualização.

Mensagem de notificação webhook

Quando a operação é processada, uma mensagem é enviada para os endpoints de notificação registrados pelo webhook.

Tipos de Eventos

Tipos de eventos para atualização de produtos:

ProductWithSKUs_Updated = 27: Produto com SKUs atualizado com sucesso
ProductWithSKUs_UpdateFailed = 29: Falha na atualização do produto com SKUs
ProductWithSKUs_PartiallyFailed = 30: Falha parcial (alguns SKUs falharam)

IMPORTANTE: Para receber notificações de erro, você deve explicitamente incluir os tipos de eventos de erro (como ProductWithSKUs_UpdateFailed) na configuração do seu webhook.

POST /v1/batch/products​

Header​

Exemplo de Autorização​

Corpo da Requisição​

Campos dos SKUs​

Possíveis valores para UnitOfMeasure​

Exemplo de Corpo da Requisição​

Respostas​

Exemplo de Resposta para Sucesso (200)​

Comportamento Especial para SKUs​

Mensagem de notificação webhook​

Tipos de Eventos​