Registrar novos produtos e seus relacionamentos

Este endpoint é utilizado para registrar 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.

Nota: Este mesmo endpoint (POST) também realiza atualização (upsert) de produtos existentes com base no externalReference. Caso o produto já exista, seus dados serão atualizados.

POST /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. Se não for fornecida, será gerada automaticamente.
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
commercialPolicyId	string	Não	-	Id da política comercial registrada no portal de admin no qual o produto existirá
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

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",
    "brandExternalReference": "5",
    "categoryExternalReference": "4",
    "commercialPolicyId": "3FA85F64-5717-4562-B3FC-2C963F66AFA6",
    "displayInSite": false,
    "displayInSoldOut": false,
    "fiscalCode": "1111111",
    "EAN": "7896891504153",
    "Punctuation": 1,
    "Characteristics": "Arroz branco tipo 1, grãos selecionados, pacote de 1kg",
    "Active": false,
    "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" }

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",
      "Produto 1: SKU EAN deve ter no máximo 30 caracteres",
      "Produto 1: SKU Reference deve ter no máximo 30 caracteres"
    ]
  }
}

Validações Implementadas

O sistema implementa validações rigorosas para garantir a integridade dos dados:

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": 26,
  "data": {
    "name": "Granola Tradicional com Castanhas Mãe Terra 800g",
    "similarTerms": "granola,castanhas,mãe terra",
    "slug": "granola-tradicional-castanhas-mae-terra-800g",
    "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",
    "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": 28,
  "data": {
    "name": "",
    "similarTerms": null,
    "slug": "",
    "title": null,
    "externalReference": "103928"
  },
  "contractAccountId": "E9A2FCA6-198F-4B4A-A183-2356EF6562F5",
  "error": {
    "statusCode": 400,
    "message": "Erro de validação",
    "validationErrors": [
      { "id": 1, "validation": "Nome é um campo obrigatório", "key": "Name" },
      { "id": 2, "validation": "Título é um campo obrigatório", "key": "Title" },
      { "id": 3, "validation": "Slug é um campo obrigatório", "key": "Slug" }
    ]
  }
}

Tipos de Eventos

Tipos de eventos para produtos:

• ProductWithSKUs_Created = 26: Produto com SKUs criado com sucesso
• ProductWithSKUs_Updated = 27: Produto com SKUs atualizado com sucesso
• ProductWithSKUs_CreationFailed = 28: Falha na criação do produto com SKUs
• 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_CreationFailed) na configuração do seu webhook. Sem essa configuração, você não receberá webhooks quando ocorrerem falhas nas operações.