Embalagem

Integração Básica do RUB — entidade obrigatória, de contexto Empresa. Na API pública é representada pelo objeto packaging[] do schema ProductFull (JSON 1:1) e pelo schema ProductPackaging na importação massiva (CSV).

O que é uma Embalagem

A Embalagem descreve as formas em que um produto existe fisicamente: unidade, caixa com 9, fardo com 6, pack com 12, display com 24. Cada Embalagem é definida por sua quantidade em relação à menor unidade comercializada do produto — a lata, no caso de um refrigerante; a grama, no caso de um item de peso variável.

Para o RUB, a Embalagem é o que permite converter tudo o que é lido ou contado na loja para uma única unidade de medida:

• No recebimento, o conferente lê o DUN-14 da caixa e o RUB registra a entrada de 12 unidades, não de 1 caixa.
• No inventário, o colaborador conta 3 fardos e 4 unidades avulsas; o RUB calcula 3 × 6 + 4 = 22 unidades.
• Na reposição, o RUB sabe que a gôndola pede 30 unidades e que o depósito tem caixas de 12, logo sugere trazer 3 caixas.
• Na etiqueta de preço, cada Embalagem pode ter um preço próprio (unidade a R$ 4,99, pack com 6 a R$ 27,90), definido na Embalagem Loja.

Cada Código de Produto (código de barras) aponta para uma Embalagem — é assim que o RUB descobre, ao ler um código, quantas unidades ele representa.

graph LR
    PE["Produto Empresa<br/>4482 ARROZ 5KG"]
    PE --> E1["Embalagem QTD = 1<br/>UNIDADE"]
    PE --> E6["Embalagem QTD = 6<br/>FARDO C/ 6"]
    E1 --> B1["EAN 7896006700016"]
    E6 --> B6["DUN-14 17896006700013"]
    E1 --> P1["Embalagem Loja<br/>R$ 24,99"]
    E6 --> P6["Embalagem Loja<br/>R$ 143,94"]

Todo produto precisa da Embalagem unitária (QTD = 1). Ela é a referência da menor unidade comercializada e é sobre ela que estoque e movimentos são expressos. As demais Embalagens são múltiplos dela.

Modelo de dados

Chave e identidade

A chave é composta: PRODUTO + QTD. Um produto não pode ter duas Embalagens com a mesma quantidade — "caixa com 12" e "display com 12" são, para o RUB, a mesma Embalagem (12 unidades). Reenviar o par atualiza a DESCRICAO.

Relacionamentos

• Uma Embalagem pertence a um Produto Empresa.
• Uma Embalagem possui zero ou mais Códigos de Produto.
• Uma Embalagem possui zero ou uma Embalagem Loja (preço) em cada loja.
• Depende do Produto Empresa já existir.

Equivalência na API

Exemplos de uso

Cenário 1 — Produto com três Embalagens (JSON 1:1)

Cerveja em lata: unidade, pack com 12 e caixa com 24. Em JSON as Embalagens viajam dentro do produto:

POST /empresa/api/rest/product/v2
{
  "code": "8801",
  "name": "CERVEJA PILSEN LATA 350ML",
  "category": "100202",
  "supplier": "5010",
  "packaging": [
    { "description": "LATA",       "quantity": 1,  "barcodes": [ { "code": "7891149010011" } ] },
    { "description": "PACK C/ 12", "quantity": 12, "barcodes": [ { "code": "17891149010018" } ] },
    { "description": "CAIXA C/ 24","quantity": 24, "barcodes": [ { "code": "27891149010015" } ] }
  ]
}

Cenário 2 — Carga massiva de Embalagens (CSV)

Na carga inicial, as Embalagens de todos os produtos são enviadas em um arquivo plano, uma linha por produto × quantidade, após o arquivo de produtos:

POST /empresa/api/rest/product/v1/packaging
Content-Type: text/csv

"product";"quantity";"description"
"8801";"1";"LATA"
"8801";"12";"PACK C/ 12"
"8801";"24";"CAIXA C/ 24"
"4482";"1";"UNIDADE"
"4482";"6";"FARDO C/ 6"
"7301";"1";"GRAMA"

Cenário 3 — Nova Embalagem em regime

O fornecedor passou a entregar o arroz também em caixa com 10. Basta reenviar o produto com a Embalagem adicional (o POST é incremental e preserva as existentes):

POST /empresa/api/rest/product/v2
{
  "code": "4482",
  "name": "ARROZ TIPO 1 5KG",
  "packaging": [ { "description": "CAIXA C/ 10", "quantity": 10, "barcodes": [ { "code": "17896006700105" } ] } ]
}

Cenário 4 — Uso operacional: recebimento e contagem

Com as Embalagens cadastradas:

• No recebimento, o conferente lê 27891149010015 → o RUB registra 24 latas do produto 8801.
• Numa contagem de depósito, o colaborador informa "3 caixas + 2 packs + 5 latas" → o RUB consolida 3 × 24 + 2 × 12 + 5 = 101 latas.
• Na sugestão de reposição, sabendo que a gôndola precisa de 40 latas e que o depósito tem packs de 12, o RUB sugere levar 4 packs.

Boas práticas

• Envie sempre a Embalagem quantity: 1; sem ela, o RUB não tem a unidade de referência.
• Para peso variável, a Embalagem unitária é 1 grama; preços por quilo são expressos na Embalagem Loja com quantity: 1000.
• Use descrições curtas e padronizadas (UNIDADE, CAIXA C/ 12, FARDO C/ 6) — elas aparecem na tela do dispositivo móvel.
• Não crie Embalagens que a loja não manuseia (ex.: palete com 1.200) a menos que exista um código de barras lido na operação para ela.

Referência na API

O contrato técnico completo dos endpoints e schemas de Embalagens (propriedades aninhadas em ProductFull no modo JSON 1:1, formatos de importação massiva CSV e exemplos de requisição/resposta) encontra-se documentado no Swagger oficial:

• Swagger da API: https://api.docs.rub.gicbrasil.com (tag Produtos ( Empresa))
• Diretrizes da API REST: consulte a Referência da API REST para regras de tenancy, autenticação e fluxo de processamento de lotes.