Atualizar produtos e seus relacionamentos

Este endpoint é utilizado para atualizar um lote de produtos de uma vez. É ideal para sistemas que precisam sincronizar uma grande quantidade de dados de produtos em uma única requisição.

PUT /v1/batch/products

Header

• 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 fora dos sistemas Grocers. Obrigatório para identificar o produto
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
ProductExternalReference	string	Não	-	Referência externa do produto pai
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
UnitOfMeasurement	int	Não	-	Unidade de medida (ver tabela abaixo)
UnitMultiplier	decimal	Sim	-	Multiplicador da unidade (deve ser > 0 se fornecido)
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

Possiveis valores para UnitOfMeasure

O campo UnitOfMeasure dentro de SKUs aceita os seguintes valores:

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, fácil preparo, ideal para acompanhamentos e pratos do dia a dia",
    "Active": false,
    "brandExternalReference": null,
    "categoryExternalReference": "4",
    "SKUs": [
      {
        "externalReference": "10",
        "Name": "Sample Product",
        "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.
• 404: Produto não encontrado pela referência externa fornecida.
• 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" }

Exemplo de Resposta para Erro (400) - Validação

{
  "title": "Erro de validação",
  "detail": "Um ou mais produtos contêm dados inválidos",
  "status": 400,
  "errors": {
    "ValidationErrors": [
      "Produto 1: Nome deve ter no máximo 120 caracteres",
      "Produto 1: Título deve ter no máximo 60 caracteres",
      "Produto 1: SKU 'Nome do SKU' deve ter no máximo 120 caracteres"
    ]
  }
}

Validações Implementadas

O sistema implementa as mesmas validações rigorosas da criação de produtos:

Validações de Produto:

• Nome: Obrigatório, mínimo 5 caracteres, máximo 120 caracteres
• Slug: Obrigatório, máximo 120 caracteres
• Título: Obrigatório, mínimo 3 caracteres, máximo 60 caracteres
• Descrição Curta: Obrigatório, mínimo 3 caracteres, máximo 160 caracteres
• Descrição Longa: Obrigatório, mínimo 3 caracteres
• Código Fiscal: Obrigatório, mínimo 3 caracteres, máximo 30 caracteres
• EAN: Máximo 48 caracteres
• Pontuação: Obrigatório, deve ser ≥ 0
• Referência Externa da Marca: Máximo 30 caracteres
• Referência Externa da Categoria: Máximo 30 caracteres

Validações de SKU:

• Nome: Obrigatório, máximo 120 caracteres
• EAN: Obrigatório, máximo 30 caracteres
• Reference: Obrigatório, máximo 30 caracteres
• Dimensões e Pesos: Todos devem ser > 0
• Data de Chegada: Obrigatório
• Código do Fabricante: Obrigatório
• Unidade de Medida: Deve ser um valor válido do enum
• Badges de Exibição: Máximo 15 caracteres cada

Mensagem de notificação webhook

Quando a operação é processada, uma mensagem é enviada para os endpoints de notificação registrados pelo webhook. A mensagem contém o ID, o status da operação e detalhes do retorno.

Webhook de Sucesso

{
  "operationId": "54d6a979-5f62-4e17-9d4c-dbd9f5ede403",
  "relatedEntity": "Product",
  "eventType": 2,
  "data": {
    "name": "Granola Tradicional com Castanhas Mãe Terra 800g - Atualizada",
    "similarTerms": "granola,castanhas,mãe terra,atualizada",
    "slug": "granola-tradicional-castanhas-mae-terra-800g-v2",
    "title": "Granola Tradicional com Castanhas Mãe Terra 800g",
    "shortDescription": "Granola Tradicional com Castanhas Mãe Terra 800g",
    "longDescription": "Granola Tradicional com Castanhas Mãe Terra 800g - Versão atualizada",
    "brandId": "e7b8a9d4-3f4b-4c8e-9d2e-1f5a6b7c8d9e",
    "categoryId": "c9b1d5e4-2f3a-4b8e-9d1e-7f6a8b9c0d1f",
    "commercialPoliticId": "b6a2f813-9952-4f35-fbc5-08dcf2bc3756",
    "displayInSite": true,
    "displayInSoldOut": false,
    "fiscalCode": "11111",
    "EAN": "7891150075443",
    "punctuation": 1,
    "externalReference": "103928"
  },
  "contractAccountId": "E9A2FCA6-198F-4B4A-A183-2356EF6562F5"
}

Webhook de Erro

{
  "operationId": "bb067d1e-5388-4794-95cb-188b417dc280",
  "relatedEntity": "Product",
  "eventType": 110,
  "data": {
    "externalReference": "103928",
    "name": "Nome muito longo que excede o limite de 120 caracteres permitidos pelo sistema de validação implementado",
    "title": "Título muito longo que excede o limite de 60 caracteres"
  },
  "contractAccountId": "E9A2FCA6-198F-4B4A-A183-2356EF6562F5",
  "error": {
    "statusCode": 400,
    "message": "Erro de validação",
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Erro de validação",
    "detail": "Um ou mais produtos contêm dados inválidos",
    "instance": "/v1/batch/products",
    "traceId": "00-42bf4652eeb9c657161c4d7e92ec7cd7-27a5fd389fba4dbf-00",
    "validationErrors": [
      { "id": 1, "validation": "Nome deve ter no máximo 120 caracteres", "key": "Name" },
      { "id": 2, "validation": "Título deve ter no máximo 60 caracteres", "key": "Title" }
    ]
  }
}

Tipos de Eventos

Tipos de eventos para atualização de produtos:

• Product_Updated = 2: Produto atualizado com sucesso
• Product_UpdateFailed = 110: Falha na atualização do produto
• SKU_Updated = 5: SKU atualizado com sucesso
• SKU_UpdateFailed = 111: Falha na atualização do SKU

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

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 (SKU_UpdateFailed = 111)

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